8000 feat(deck): run the deck as a user service so it survives terminal close (#29) by simon-inkie · Pull Request #48 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

feat(deck): run the deck as a user service so it survives terminal close (#29) - #48

Closed
simon-inkie wants to merge 4 commits into
mainfrom
io/deck-29-survive-terminal-close
Closed

simon-inkie wants to merge 4 commits into
mainfrom
io/deck-29-survive-terminal-close

Conversation

@simon-inkie
Copy link
Copy Markdown
Owner

Closes #29.

Reviewed at 719476d, two independent legs (CodeRabbit is off):

  • Sol 6.1: PASS with notes
  • Aggy (Gemini 3.8 Flash): PASS, tests green, public hygiene clean

Both reviews checked that the tests fail without the change.

🤖 Generated with Claude Code

https://claude.ai/code/session_018uNaFhmK6yxSR7XfzJDY3Z

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018uNaFhmK6yxSR7XfzJDY3Z
Signed-off-by: Simon <simon@inkie.ink>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review, Sonnet, 2026-10-02

PR 48 (deck issue 29, systemd user service). SHA reviewed: 719476d

Verdict: NEEDS CHANGES (1 Major, moderate confidence; see below)

Ran npx vitest run test/deck-service.test.ts in packages/deck: 3 passed (systemd-analyze 255 is present, so the verifier test ran, not skipped). The tests need the new template and the INSTALL.md renderer, so they fail without the change. Hygiene: no internal names, /home paths, hostnames or plan mentions; git diff --check clean; ASCII only.

Critical

None.

Major

  1. The renderer applies ExecStart-style C escaping to WorkingDirectory= and EnvironmentFile= values, which systemd does not unescape. INSTALL.md escape() turns whitespace, " and \ into \xNN for all three tokens, and only @NODE_BINARY@ is wrapped in quotes. In systemd 255 the ExecStart= parser splits and C-unescapes words, but WorkingDirectory= and EnvironmentFile= take the rest of the line as a literal path after specifier expansion only (the man page describes no escaping for them; a path with spaces is simply written as is). So a checkout at /home/me/my deck renders WorkingDirectory=/home/me/my\x20deck, which names a directory that does not exist, and the service fails with a 200/CHDIR error. The new test (deck-service.test.ts, the checkout\\x20with... assertions) pins the wrong output, and systemd-analyze verify passes because it does not check that the directory exists. I could not start a real user manager here to confirm empirically, so treat as high but not certain; confirm with systemd-run --user -p WorkingDirectory='/tmp/a b' pwd-style probe or by starting a rendered unit under a path with a space. Fix: escape only % to %% for WorkingDirectory and EnvironmentFile (leave spaces raw), keep quoted C escaping for ExecStart= only, and replace the test assertions with a real start (or a systemd-run --user --wait --pipe -p WorkingDirectory=... -p EnvironmentFile=... /bin/true check) in a path with a space.

Minor

  1. Unicode whitespace: '\\x%02x' % ord(c) on a non-ASCII whitespace character (for example U+2003) emits \x2003, which systemd reads as \x20 followed by 03. Rare, but wrong; iterate over value.encode() bytes instead.

  2. Restart=always with RestartSec=5s and no StartLimit* means a launcher that exits immediately on a bad config (missing .env.production, port in use) restarts every 5 seconds forever, since 5 starts per 10 seconds never trips the default limit. Fix: add StartLimitIntervalSec=60 and StartLimitBurst=5 under [Unit]/[Service] as appropriate, or use Restart=on-failure; the documented "explicit stop does not restart" holds either way.

  3. No hardening in the template. Deck has no authentication and runs as the user, so cheap options are worth adding: NoNewPrivileges=yes, PrivateTmp=yes, ProtectSystem=strict with ReadWritePaths= for the checkout, or at least a comment saying they were considered. Optional, but the .env.production is mode 600 which is good.

  4. EnvironmentFile= uses systemd syntax, not dotenv: export FOO=bar lines, inline comments after a value and quoting differ from the .env the foreground launcher reads. INSTALL.md says "use literal values" but tells people to cp .env .env.production; add one line about export and trailing comments.

  5. The detached tmux instructions use tmux new-session -d -s deck, which fails if a deck session already exists; mention tmux kill-session -t deck first or use new-session -A.

Nit

  1. The test locates the renderer by regexing <<'PY' in INSTALL.md, which is a clever way to test the docs, but the failure message could name the heading it expected.
  2. KillMode=control-group is the default; harmless as documentation.
  3. The INSTALL.md section is long; the renderer might read better as a small script under packages/deck/scripts/, with the docs calling it. Not required.

Not checked

  • Starting the unit on a real Ubuntu 24.04 user manager, with and without lingering, and under WSL.
  • Whether loginctl enable-linger needs polkit on a stock desktop install (documented as possibly needing admin).
  • Node installed through a version manager (the template uses process.execPath, and start-production.mjs spawns children with process.execPath, so PATH should not matter, but I did not run it).

Simon and others added 3 commits October 3, 2026 10:40
…ew fixes)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Simon <simon@inkie.ink>
EnvironmentFile= is glob-matched, so a literal backslash in the checkout
path must be escaped; WorkingDirectory= keeps it as is. The launcher test
now feeds the rendered value to systemd-run and probes with a CommonJS
script, since Node's ES module loader rejects backslashes in filenames.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Simon <simon@inkie.ink>
EnvironmentFile= is glob-matched, so escape \ * ? [ (backslash first)
in the rendered path; WorkingDirectory= stays literal. Fixtures now use
a directory name with those characters plus a decoy sibling env file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Simon <simon@inkie.ink>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Fixes pushed: 980b3b7, bca8940, 9a5d76c (head 9a5d76c). EnvironmentFile now escapes backslash, star, question mark and open bracket; WorkingDirectory stays literal. Review legs: Sonnet on bca8940 (PASS with notes, the glob-set note is fixed in 9a5d76c); Aggy on 9a5d76c (PASS, 9/9 service tests including the live systemd-run transient unit). Sol finished the escaping and ran the leak gate (clean). Reviews follow.

@simon-inkie
Copy link
Copy Markdown
Owner Author

Review: deck EnvironmentFile backslash doubling (bca8940, parent 980b3b7)

Verdict: PASS with notes.

Scope: INSTALL.md renderer (around lines 349-385) and packages/deck/test/deck-service.test.ts. Checked empirically on systemd 255 (Ubuntu 24.04) with systemd-run --user -p EnvironmentFile=... against throwaway directories, and Node 22.

Answers to the four questions

  1. Is doubling correct for EnvironmentFile? Yes. systemd glob-matches the EnvironmentFile path at exec time, so \ is the glob escape. Raw dir\b/.env failed to load (matched as b); dir\\b/.env loaded. Unit-file parsing does not C-unescape this directive (only ExecStart does), so one doubling is the right amount. WorkingDirectory is not globbed; the existing test shows it stays literal.
  2. Are *, ?, [ also a problem? [ pairs are, the other two mostly are not. Results:
    • a[x]b raw: file not found (bracket class matched ax b). Doubling backslashes only: still not found. Escaping [: loads.
    • * and ? raw: loaded, because a glob with a single match resolves to the literal file. They are only wrong when a sibling path also matches, in which case systemd loads every match in sorted order (wrong or extra environment file, silently).
    • A lone [, ], !, {}, ^, - are all fine unescaped.
      So the fix is incomplete for any checkout path containing a [...] pair, and imprecise for */?.
  3. Does the test exercise the rendered value? Partly. The "starts a launcher" test feeds the rendered EnvironmentFile= value (with %% hand-reversed to %) to a real transient unit and asserts the variable loaded. Without the fix, that test fails (verified: raw backslash path does not load). That is a genuine exercise of the glob semantics. Weaker parts: the render assertion at line 70 recomputes the same replace chain as the implementation (mirror assertion); the systemd --test assertion only checks the parser echoes the value, not that it loads; the real unit-file load route and the real start-production.mjs launcher are not run (a probe .cjs replaces it). The test directory contains a backslash but no *, ? or [.
  4. Is the % escaping order right? Yes. Backslash doubling then %->%% are over disjoint characters, so order is irrelevant. A trailing backslash cannot occur (path ends /.env.production), so no line-continuation hazard.

Findings

Major: none.

Minor

  • INSTALL.md renderer (the @ENVIRONMENT_FILE@ branch, about line 382): escape the full glob set, not just backslash. Suggested: re.sub(r'([\\*?\[])', r'\\\1', value) (needs import re). Verified that escaping all four loads correctly for every case I tried, including a\*b.
  • deck-service.test.ts line 36 (test directory name): add *, ? and a [x] pair to the fixture path so the test would catch the gap above, and ideally create a sibling directory that the unescaped glob would also match.
  • The "starts a launcher" test is skipped silently when systemd-run --user is unavailable (CI, containers). A vacuous pass is possible; consider logging the skip or failing in CI.

Nit

  • deck-service.test.ts line 70 and 97 duplicate the implementation's replace chain; compare against a hard-coded expected string for one fixed path as well.
  • The managerAvailable probe runs systemd-run at module load (up to 15 s, adds collection time even when the suite is filtered).
  • Test title "parses literal directive paths" is now stale for EnvironmentFile (it is glob-escaped, not literal).
  • The doc note about Node's ES module loader rejecting backslashes is accurate (reproduced ERR_INVALID_MODULE_SPECIFIER on Node 22).

Not checked

  • Loading the rendered unit through a real user manager via systemctl --user daemon-reload (reasoned from systemd behaviour; the repo test uses the parser and transient units only).
  • Other systemd versions; older releases may differ in glob flags.
  • Whether systemd-analyze verify output differs on other distributions.
  • Did not run the repo's vitest suite.

@simon-inkie
Copy link
Copy Markdown
Owner Author

Deck PR 48 Fix Round C Review (Aggy - Independent Review Leg)

  • Target: inkie-deck-burn-29
  • Commit: 9a5d76c (git show 9a5d76c)
  • Review File: pr-48-fix-c-review-aggy.md
  • Verdict: PASS

1. Scope & Objective

Audit the round C fix for Deck PR 48 (fix(deck): escape glob metacharacters in the EnvironmentFile path):

  1. Verify INSTALL.md Python renderer escapes glob characters (\, *, ?, [) for EnvironmentFile= while preserving literal paths for WorkingDirectory=.
  2. Verify transient-unit capability probe and execution under the host's systemd user bus.
  3. Verify all 9 unit tests in packages/deck/test/deck-service.test.ts pass, including transient service execution and decoy environment file clobbering defense.
  4. Ensure public-repo hygiene: zero internal paths, zero /home references, no secrets or local hostnames.

2. Findings (Ranked)

[Observation / Good Practice] Comprehensive Glob Metacharacter Escaping

  • Location: INSTALL.md:383-386
  • Detail: In the documented Python unit generator:
    # Only ExecStart unescapes C escapes. EnvironmentFile uses glob syntax,
    # so escape its glob characters (backslash first) to match them literally.
    if token == '@ENVIRONMENT_FILE@':
        value = re.sub(r'([\\*?\[])', r'\\\1', value)
    value = ('"' + escape_command(value) + '"' if token == '@NODE_BINARY@'
             else value.replace('%', '%%'))
    EnvironmentFile= interprets *, ?, [ and \ as glob syntax. By applying re.sub(r'([\\*?\[])', r'\\\1', value), backslashes are doubled first (\\), while *, ? and [ are prefixed with a literal backslash.
  • Assessment: Correctly adheres to systemd.exec(5) glob matching semantics without altering WorkingDirectory= (which remains literal, escaping only % specifiers).

[Observation / Good Practice] Decoy Fixture Defends Against Accidental Glob Expansion

  • Location: packages/deck/test/deck-service.test.ts:38-40
  • Detail: The test suite creates a decoy directory alongside the target directory:
    const decoy = path.join(sandbox, 'checkout with spaces % and "quotes" and \\backslash [x] AB');
    mkdirSync(decoy);
    writeFileSync(path.join(decoy, ".env.production"), "DECK_SERVICE_PROBE=decoy\n");
    Because the target directory ends with *?, an unescaped glob would match both directories and sort AB after *?, causing DECK_SERVICE_PROBE=decoy to overwrite loaded.
  • Assessment: Rigorous regression test ensuring that globs are genuinely disabled rather than merely superficially escaped.

3. Test Suite Verification

The full test suite was executed against the active systemd user bus:

pnpm -C packages/deck test test/deck-service.test.ts

Results:

  • supervises the production launcher and its children without enabling reboot startup (passed)
  • renders machine-local paths and escapes systemd specifiers, globs and quoted paths (passed)
  • escapes EnvironmentFile as a glob while WorkingDirectory stays literal (passed)
  • passes systemd's unit verifier after following the documented renderer (passed)
  • parses escaped directive paths and UTF-8 command bytes with systemd (passed)
  • starts a launcher with a literal working directory and a glob-escaped environment file (passed in 96ms via systemd-run)
  • rejects line breaks in rendered paths ("\n") (passed)
  • rejects line breaks in rendered paths ("\r") (passed)
  • documents environment-file conversion and replacing an existing tmux session (passed)

All 9 tests passed.


4. Public Repository Hygiene

Verified:

  • No internal /home filesystem paths appear anywhere in the diff or in this review.
  • No user credentials, local machine identities, or private domains are exposed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Deck dies when you close the terminal it was started in

1 participant

0