Implement GitHub Assigned PRs screen for TRMNL playlist

[bars0udin]

What

A new TRMNL screen that displays a summary of GitHub pull requests assigned to the user (bars0udin). The screen will show the total count of assigned open PRs and a list containing each PR's title and a "time ago" string (e.g., "3 hours ago").

Implementation details:

• A new Phoenix controller TrmnlWeb.GithubPrsController to handle the view request.
• A new template lib/trmnl_web/templates/github_prs/show.html.heex optimized for the 800x480 monochrome TRMNL display.
• A data fetching mechanism using System.cmd/3 to execute gh pr list --assignee=bars0udin --state=open --json number,title,url,createdAt.
• Integration into the existing playlist via lib/trmnl/playlist.ex.

Why

The user requires a way to monitor their PR review queue on their TRMNL device. Using the gh CLI leverages the existing authentication on the system, significantly simplifying the implementation by avoiding manual token management or complex API client configuration.

Quality Attributes

• Maintainability: Follows existing Phoenix controller/template patterns and uses the gh CLI for simplicity.
• Reliability: The implementation must gracefully handle empty PR lists or failures in the gh command execution.
• Performance: Data fetching via CLI should be efficient enough to ensure the screen regenerates within the expected TRMNL interval.

Verification

Automated Tests

• test "parses JSON output from gh CLI command"
• test "calculates relative time strings accurately (e.g., 'X hours ago')"
• test "handles empty PR list response gracefully"

Manual Verification

1. Access the screen via the /screens/:api_key route.
2. Compare the displayed PR count and list with the output of gh pr list --assignee=bars0udin --state=open.
3. Verify that the "time ago" information is correctly displayed for each item.
4. Confirm the layout is legible and fits the 800x480 monochrome constraints.

[bars0udin]

Plan Ready for Review 📋

@bars0udin - An implementation plan has been generated for this issue and is ready for your review.

Next Steps

• Review the plan above
• Comment @udin_code approved on this issue to approve and start implementation
• Or provide feedback to request changes

---

Automated notification from UdinCode

[bars0udin]

Plan Approved ✅

@bars0udin - The implementation plan for this issue has been approved and work is now in progress.

---

Automated notification from UdinCode

[bars0udin]

Plan Ready for Review 📋

@bars0udin - An implementation plan has been generated for this issue and is ready for your review.

Implementation Plan

Click to expand implementation plan

Plan: Implement GitHub Assigned PRs Screen

Context

Add a new TRMNL screen that displays open GitHub PRs assigned to bars0udin. The screen shows the total count and a list with PR titles and "time ago" strings. Data is fetched via the gh CLI.

Key Design Decision

The ticket suggests creating a new controller (GithubPrsController) and template, but the existing codebase uses a screen module pattern: modules implement the Trmnl.Screen behaviour with a render/1 callback and are registered in Playlist.screens/1. The ScreenController already delegates rendering to the current screen module. We will follow this existing pattern — no new controller or route needed.

Files to Create

1. test/trmnl/screens/github_prs_test.exs — Tests for JSON parsing, time_ago calculation, empty list handling, and CLI error handling
2. lib/trmnl/screens/github_prs.ex — Screen module implementing Trmnl.Screen behaviour

Files to Modify

3. lib/trmnl/playlist.ex — Add Trmnl.Screens.GithubPrs to the playlist

Implementation Details

1. Trmnl.Screens.GithubPrs module

defmodule Trmnl.Screens.GithubPrs do
  @behaviour Trmnl.Screen
  use Phoenix.Component

  # Fetch data via gh CLI, parse JSON, render template
end

Data fetching — fetch_prs/0:

• Run System.cmd("gh", ["pr", "list", "--assignee=bars0udin", "--state=open", "--json", "number,title,url,createdAt"])
• On {json, 0} → parse with Jason.decode!/1
• On error (non-zero exit) → return []

Time ago — time_ago/1:

• Use DateTime.diff(DateTime.utc_now(), created_at, :second)
• Classify into: seconds, minutes, hours, days, weeks, months using a cond block
• Return string like "3 hours ago"

render/1 callback:

• Call fetch_prs/0, compute count and time_ago for each PR
• Render an HEEx template optimized for 800x480 monochrome:
  • Header: "GitHub PRs" with count badge
  • List of PRs: title (truncated if needed) + time ago
  • Handle empty state: "No open PRs assigned"

2. Playlist integration

Add Trmnl.Screens.GithubPrs to the list in Playlist.screens/1.

3. Template design (800x480 monochrome)

• Use Tailwind classes already available via the screen layout
• Black text on white, high contrast for e-ink
• Header row with title + count
• Scrollable list with PR title and time ago on each row
• Font sizes: title ~text-xl, list items ~text-base

Test Plan

Unit tests (test/trmnl/screens/github_prs_test.exs)

1. test "parses JSON output from gh CLI command" — Mock the CLI output with sample JSON, verify the parsed list structure
2. test "calculates relative time strings accurately" — Test time_ago/1 with various DateTime values: seconds ago, minutes, hours, days, weeks, months
3. test "handles empty PR list response gracefully" — Verify [] JSON parses to empty state with "No open PRs" message
4. test "handles CLI failure gracefully" — Verify non-zero ex

(truncated)

User Flow

Click to expand user flow

Before

The TRMNL device playlist only contains the HelloWorld screen. When the device cycles through its playlist, it always displays the same "hello, I was rendered at {time}" message.

sequenceDiagram
    actor Device as TRMNL Device
    participant API as APIController
    participant Screen as Screen.regenerate
    participant Playlist as Playlist
    participant HW as HelloWorld

    Device->>API: GET /api/display
    API->>Screen: regenerate(device)
    Screen->>Playlist: current_screen(device)
    Playlist-->>Screen: HelloWorld
    Screen->>HW: render(assigns)
    HW-->>Screen: "hello, I was rendered at..."
    Screen-->>API: BMP image
    API-->>Device: Display image

Loading

After

The playlist now includes the GithubPrs screen alongside HelloWorld. When the device cycles to the GithubPrs screen, it fetches open PRs assigned to bars0udin via the gh CLI and displays a summary with PR count, titles, and "time ago" strings.

sequenceDiagram
    actor Device as TRMNL Device
    participant API as APIController
    participant Screen as Screen.regenerate
    participant Playlist as Playlist
    participant GPR as GithubPrs
    participant CLI as gh CLI

    Device->>API: GET /api/display
    API->>Screen: regenerate(device)
    Screen->>Playlist: current_screen(device)
    Playlist-->>Screen: GithubPrs
    Screen->>GPR: render(assigns)
    GPR->>CLI: gh pr list --assignee=bars0udin --state=open --json ...
    CLI-->>GPR: JS

_(truncated)_

</details>

### Impact Analysis

<details>
<summary>Click to expand impact analysis</summary>

## Impact Score: Low

**Overall Risk**: Low — Self-contained addition of a new screen module following an established pattern, with no changes to existing APIs, schemas, or shared infrastructure.

### Affected Areas

| Area | Risk Level | Details |
|------|-----------|---------|
| Playlist | 🟢 Low | Adding one entry to the screens list; no logic changes |
| Screen rendering pipeline | ⚪ None | Existing ScreenController/ScreenHTML unchanged; new module plugs in via behaviour |
| External dependency (gh CLI) | 🟡 Medium | Requires `gh` CLI installed and authenticated on host; failure handled gracefully |
| Test suite | 🟢 Low | New test file only; no changes to existing tests |

### Summary

This is a low-risk, additive change. A new screen module is created following the existing `Trmnl.Screen` behaviour pattern, and it is registered in the playlist. No existing code is modified beyond adding one line to `Playlist.screens/1`. The only medium-risk area is the runtime dependency on the `gh` CLI tool, which is mitigated by graceful error handling returning an empty PR list on failure.

### Dependency Graph

```mermaid
graph TD
    classDef high fill:#fee2e2,stroke:#dc2626,color:#991b1b
    classDef medium fill:#fef3c7,stroke:#d97706,color:#92400e
    classDef low fill:#d1fae5,stroke:#059669,color:#065f46

    subgraph Backend
        GithubPrs["GithubPrs (new)"]:::low
        Playlist["Playlist"]:::low
        ScreenBehaviour["Screen behaviour"]:::low
    end

 

_(truncated)_

</details>


### Next Steps
- Review the plan above
- Comment **`@udin_code approved`** on this issue to approve and start implementation
- Or provide feedback to request changes

---
_Automated notification from UdinCode_

Loading

[bars0udin]

Plan Approved ✅

@bars0udin - The implementation plan for this issue has been approved and work is now in progress.

Implementation Plan

Click to expand implementation plan

Plan: Implement GitHub Assigned PRs Screen

Context

Add a new TRMNL screen that displays open GitHub PRs assigned to bars0udin. The screen shows the total count and a list with PR titles and "time ago" strings. Data is fetched via the gh CLI.

Key Design Decision

The ticket suggests creating a new controller (GithubPrsController) and template, but the existing codebase uses a screen module pattern: modules implement the Trmnl.Screen behaviour with a render/1 callback and are registered in Playlist.screens/1. The ScreenController already delegates rendering to the current screen module. We will follow this existing pattern — no new controller or route needed.

Files to Create

1. test/trmnl/screens/github_prs_test.exs — Tests for JSON parsing, time_ago calculation, empty list handling, and CLI error handling
2. lib/trmnl/screens/github_prs.ex — Screen module implementing Trmnl.Screen behaviour

Files to Modify

3. lib/trmnl/playlist.ex — Add Trmnl.Screens.GithubPrs to the playlist

Implementation Details

1. Trmnl.Screens.GithubPrs module

defmodule Trmnl.Screens.GithubPrs do
  @behaviour Trmnl.Screen
  use Phoenix.Component

  # Fetch data via gh CLI, parse JSON, render template
end

Data fetching — fetch_prs/0:

• Run System.cmd("gh", ["pr", "list", "--assignee=bars0udin", "--state=open", "--json", "number,title,url,createdAt"])
• On {json, 0} → parse with Jason.decode!/1
• On error (non-zero exit) → return []

Time ago — time_ago/1:

• Use DateTime.diff(DateTime.utc_now(), created_at, :second)
• Classify into: seconds, minutes, hours, days, weeks, months using a cond block
• Return string like "3 hours ago"

render/1 callback:

• Call fetch_prs/0, compute count and time_ago for each PR
• Render an HEEx template optimized for 800x480 monochrome:
  • Header: "GitHub PRs" with count badge
  • List of PRs: title (truncated if needed) + time ago
  • Handle empty state: "No open PRs assigned"

2. Playlist integration

Add Trmnl.Screens.GithubPrs to the list in Playlist.screens/1.

3. Template design (800x480 monochrome)

• Use Tailwind classes already available via the screen layout
• Black text on white, high contrast for e-ink
• Header row with title + count
• Scrollable list with PR title and time ago on each row
• Font sizes: title ~text-xl, list items ~text-base

Test Plan

Unit tests (test/trmnl/screens/github_prs_test.exs)

1. test "parses JSON output from gh CLI command" — Mock the CLI output with sample JSON, verify the parsed list structure
2. test "calculates relative time strings accurately" — Test time_ago/1 with various DateTime values: seconds ago, minutes, hours, days, weeks, months
3. test "handles empty PR list response gracefully" — Verify [] JSON parses to empty state with "No open PRs" message
4. test "handles CLI failure gracefully" — Verify non-zero ex

(truncated)

User Flow

Click to expand user flow

Before

The TRMNL device playlist only contains the HelloWorld screen. When the device cycles through its playlist, it always displays the same "hello, I was rendered at {time}" message.

sequenceDiagram
    actor Device as TRMNL Device
    participant API as APIController
    participant Screen as Screen.regenerate
    participant Playlist as Playlist
    participant HW as HelloWorld

    Device->>API: GET /api/display
    API->>Screen: regenerate(device)
    Screen->>Playlist: current_screen(device)
    Playlist-->>Screen: HelloWorld
    Screen->>HW: render(assigns)
    HW-->>Screen: "hello, I was rendered at..."
    Screen-->>API: BMP image
    API-->>Device: Display image

Loading

After

The playlist now includes the GithubPrs screen alongside HelloWorld. When the device cycles to the GithubPrs screen, it fetches open PRs assigned to bars0udin via the gh CLI and displays a summary with PR count, titles, and "time ago" strings.

sequenceDiagram
    actor Device as TRMNL Device
    participant API as APIController
    participant Screen as Screen.regenerate
    participant Playlist as Playlist
    participant GPR as GithubPrs
    participant CLI as gh CLI

    Device->>API: GET /api/display
    API->>Screen: regenerate(device)
    Screen->>Playlist: current_screen(device)
    Playlist-->>Screen: GithubPrs
    Screen->>GPR: render(assigns)
    GPR->>CLI: gh pr list --assignee=bars0udin --state=open --json ...
    CLI-->>GPR: JS

_(truncated)_

</details>

### Impact Analysis

<details>
<summary>Click to expand impact analysis</summary>

## Impact Score: Low

**Overall Risk**: Low — Self-contained addition of a new screen module following an established pattern, with no changes to existing APIs, schemas, or shared infrastructure.

### Affected Areas

| Area | Risk Level | Details |
|------|-----------|---------|
| Playlist | 🟢 Low | Adding one entry to the screens list; no logic changes |
| Screen rendering pipeline | ⚪ None | Existing ScreenController/ScreenHTML unchanged; new module plugs in via behaviour |
| External dependency (gh CLI) | 🟡 Medium | Requires `gh` CLI installed and authenticated on host; failure handled gracefully |
| Test suite | 🟢 Low | New test file only; no changes to existing tests |

### Summary

This is a low-risk, additive change. A new screen module is created following the existing `Trmnl.Screen` behaviour pattern, and it is registered in the playlist. No existing code is modified beyond adding one line to `Playlist.screens/1`. The only medium-risk area is the runtime dependency on the `gh` CLI tool, which is mitigated by graceful error handling returning an empty PR list on failure.

### Dependency Graph

```mermaid
graph TD
    classDef high fill:#fee2e2,stroke:#dc2626,color:#991b1b
    classDef medium fill:#fef3c7,stroke:#d97706,color:#92400e
    classDef low fill:#d1fae5,stroke:#059669,color:#065f46

    subgraph Backend
        GithubPrs["GithubPrs (new)"]:::low
        Playlist["Playlist"]:::low
        ScreenBehaviour["Screen behaviour"]:::low
    end

 

_(truncated)_

</details>

---
_Automated notification from UdinCode_

Loading

[bars0udin]

Code Review Complete 🔍

@bars0udin - Code review has been completed for this issue. Please review the findings below.

Review Findings

Click to expand review findings

{"critical_issues":[{"description":"DateTime.from_iso8601/1 error not handled — elem(1) on the result assumes success. If createdAt is missing, malformed, or null, DateTime.from_iso8601/1 returns {:error, reason} and elem(1) extracts the reason atom, causing time_ago/1 to crash with an ArithmeticError in DateTime.diff/3. Use case to handle the error tuple or provide a fallback.","file_path":"lib/trmnl/screens/github_prs.ex","line":15},{"description":"System.cmd without timeout — fetch_prs/0 calls System.cmd(\"gh\", ...) (via the default runner) with no timeout mechanism. If the gh CLI hangs (network issues, auth prompt, DNS resolution), the BEAM process blocks indefinitely. Wrap in Task.async/Task.yield with a timeout, or use System.cmd/3 with a :timeout option via Port.","file_path":"lib/trmnl/screens/github_prs.ex","line":52},{"description":"Code formatting failures — 5 files fail mix format --check-formatted: lib/trmnl/screens/github_prs.ex, lib/trmnl_web/components/core_components.ex, test/trmnl/inventory_test.exs, test/trmnl/screens/github_prs_test.exs, test/trmnl_web/live/device_live_test.exs. Run mix format before committing.","file_path":"lib/trmnl/screens/github_prs.ex","line":14},{"description":"render/1 calls fetch_prs() (no-arg) which always uses System.cmd — the injectable runner parameter is only available via fetch_prs/1. During actual screen rendering, there's no way to use the injectable runner, making the render function untestable in isolation and always hitting the real CLI. Consider making the runner configurable via Application env or passing it through assigns.","file_path":"lib/trmnl/screens/github_prs.ex","line":9}],"minor_issues":[{"description":"Unrelated changes bundled into a single commit — The commit 'feat(screens): add GitHub assigned PRs screen' also includes: error handling refactor in lib/trmnl/screen.ex, nil-safety fix in lib/trmnl/inventory/device.ex, MAC address format fixes in test fixtures, page controller redirect test change, and mix.lock changes. These should be separate commits for reviewability and easier revert/bisect.","file_path":"lib/trmnl/screen.ex"},{"description":"Raw Tailwind color border-black used instead of semantic classes. For a monochrome e-ink display this may be intentional, but it's inconsistent with semantic class conventions.","file_path":"lib/trmnl/screens/github_prs.ex","line":23},{"description":"time_ago/1 does not handle negative diff values (future datetimes). If a PR's createdAt is in the future (clock skew), the function will produce incorrect output like '-5 seconds ago'.","file_path":"lib/trmnl/screens/github_prs.ex","line":72},{"description":"Hardcoded assignee @assignee \"bars0udin\" — should be configurable via Application env or function parameter to support different users or environments.","file_path":"lib/trmnl/screens/github_prs.ex","line":6},{"description":"System.cmd calls in render_current_bmp/1 (puppeteer-img and magick) also lack timeout protection. While this is pre-existing code, the branch modifies this function and the same timeout concern applies.","file_path":"lib/trmnl/screen.ex","line":56},{"description":"The time_ago test for 'singular minute' uses -90 seconds which rounds to 1 minute (90/60 = 1), but this is at a boundary — at exactly 60 seconds, diff < 60 is false so it enters the minutes branch with div(60, 60) = 1, producing '1 minute ago'. The test is correct but tests at 90s rather than testing the boundary at 60s.","file_path":"test/trmnl/screens/github_prs_test.exs","line":44}],"recommendation":"REQUEST_CHANGES","recommended_fixes":["Run mix format to fix all 5 formatting failures","Add error handling for DateTime.from_iso8601/1 in render/1 — use case instead of elem(1), with a fallback like 'unknown' for unparseable dates","Wrap System.cmd in fetch_prs/0 with a timeout using Task.async/Task.yield(task, 10_000) to prevent indefinite hangs","Split the single commit into logical units: (1) test fixture fixes, (2) Screen error handling refactor, (3) GithubPrs screen implementation","Consider making the @assignee configurable via Application.get_env(:trmnl, :github_assignee, \"bars0udin\")"],"summary":"Implements a GitHub Assigned PRs screen (Trmnl.Screens.GithubPrs) for the TRMNL playlist. The module fetches open PRs assigned to bars0udin via the gh CLI, computes "time ago" strings, and renders an HEEx template for the 800x480 monochrome display. Tests cover JSON parsing, time_ago calculation, empty list handling, and CLI error handling via an injectable runner function. The commit also includes several unrelated fixes: error handling refactor in Trmnl.Screen, nil-safety fix in Device.upcase/2, MAC address format fixes in test fixtures, and a page controller redirect test change.","test_suite":"PASS — all 31 tests passing"}

Next Steps

• Review the findings above
• Comment @udin_code approved on this issue to approve and apply recommended fixes
• Or provide feedback to request changes

---

Automated notification from UdinCode