From 5572b5ca313517de9bc3560c5da4a6a41c54d2cb Mon Sep 17 00:00:00 2001 From: HomeLab Agent Date: Thu, 5 Nov 2026 04:48:20 -0500 Subject: [PATCH] CLI contract 1.0: no linger line when loginctl can't answer; reference headers name 1.0 Co-Authored-By: Claude Opus 5.5 --- .changeset/g3-linger-unknown-quiet.md | 5 +++ packages/server/src/cli/busy.ts | 2 +- packages/server/src/cli/exit-codes.ts | 2 +- packages/server/src/cli/output.ts | 2 +- packages/server/src/cli/service/index.ts | 15 ++++----- packages/server/src/cli/service/launchd.ts | 2 +- packages/server/src/cli/service/logs.ts | 2 +- packages/server/src/cli/service/manager.ts | 2 +- packages/server/src/cli/service/path-env.ts | 2 +- packages/server/src/cli/service/systemd.ts | 2 +- packages/server/src/cli/update/health.ts | 2 +- .../server/src/cli/update/install-method.ts | 2 +- packages/server/src/cli/update/lock.ts | 2 +- .../server/src/cli/update/package-manager.ts | 2 +- packages/server/src/cli/update/registry.ts | 2 +- packages/server/src/cli/update/semver.ts | 2 +- .../server/src/cli/update/update-check.ts | 2 +- packages/server/src/cli/update/update.ts | 2 +- packages/server/src/runtime-file.ts | 2 +- packages/server/test/unit/cli-service.test.ts | 33 +++++++++++++++++-- 20 files changed, 60 insertions(+), 27 deletions(-) create mode 100644 .changeset/g3-linger-unknown-quiet.md diff --git a/.changeset/g3-linger-unknown-quiet.md b/.changeset/g3-linger-unknown-quiet.md new file mode 100644 index 00000000..38ecde8b --- /dev/null +++ b/.changeset/g3-linger-unknown-quiet.md @@ -0,0 +1,5 @@ +--- +"@paddock/server": patch +--- + +`paddock service install` no longer prints a linger line when `loginctl` can't answer; it prints the `sudo loginctl enable-linger` line only when linger is off, as CLI contract 1.0 (§7) says. `doctor` still reports that case as a skipped check. The copied reference files now name contract 1.0 in their headers. diff --git a/packages/server/src/cli/busy.ts b/packages/server/src/cli/busy.ts index 97ec2c0c..aa1721db 100644 --- a/packages/server/src/cli/busy.ts +++ b/packages/server/src/cli/busy.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/busy-client.ts @ 0.2; local changes: `.ts` import specifiers → `.js` and +// From edspencer/cli-contract reference/busy-client.ts @ 1.0; local changes: `.ts` import specifiers → `.js` and // `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); and `hint` widened // from a string to `string | ((result) => string | undefined)`, with {@link runBusyCommand} printing it too — that is // what carries Paddock's keeper-chat trap (ROADMAP "Busy, per tool"), where the line to print depends on WHICH counts diff --git a/packages/server/src/cli/exit-codes.ts b/packages/server/src/cli/exit-codes.ts index 938ee130..c5f8cd59 100644 --- a/packages/server/src/cli/exit-codes.ts +++ b/packages/server/src/cli/exit-codes.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/exit-codes.ts @ 0.2; local changes: none. +// From edspencer/cli-contract reference/exit-codes.ts @ 1.0; local changes: none. // The exit codes every tool shares (SPEC §2). Copy this file; don't renumber it. // // Set `process.exitCode`, never call `process.exit()`, so piped output isn't cut short. diff --git a/packages/server/src/cli/output.ts b/packages/server/src/cli/output.ts index e7cf862f..6e7ac57e 100644 --- a/packages/server/src/cli/output.ts +++ b/packages/server/src/cli/output.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/output.ts @ 0.2; local changes: `./exit-codes.ts` → `./exit-codes.js` +// From edspencer/cli-contract reference/output.ts @ 1.0; local changes: `./exit-codes.ts` → `./exit-codes.js` // (Paddock compiles to ESM-with-extensions, not a TS runtime); and the reference's `UsageError` / `reportUsageError` // are NOT copied, because `cli/args.ts` already has a `UsageError` (a `CliError` subclass carrying its own code) that // the entrypoint already reports. diff --git a/packages/server/src/cli/service/index.ts b/packages/server/src/cli/service/index.ts index 7bb71920..bb12861b 100644 --- a/packages/server/src/cli/service/index.ts +++ b/packages/server/src/cli/service/index.ts @@ -302,15 +302,14 @@ function installProgress(backend: ServiceBackend): string { : `\n Installing ${kind} and starting Paddock…`; } -/** The `enable-linger` line, printed only to the people it applies to (SPEC §7). */ -function lingerNote(linger: LingerState): string | undefined { - if (!linger.applies || linger.enabled === true) return undefined; - const head = - linger.enabled === false - ? " Lingering is off, so this service stops when you log out — including" - : " If you log out (this check could not reach loginctl), a user service"; +/** + * The `enable-linger` line, printed only to the people it applies to (SPEC §7): when linger is off. Nothing when it's + * on, and nothing when loginctl couldn't answer (`doctor` reports that check as skipped). + */ +export function lingerNote(linger: LingerState): string | undefined { + if (!linger.applies || linger.enabled !== false) return undefined; return ( - `${head}\n` + + " Lingering is off, so this service stops when you log out — including\n" + " out of an SSH session. To keep Paddock up, once:\n" + ` sudo loginctl enable-linger ${linger.user ?? "$USER"}` ); diff --git a/packages/server/src/cli/service/launchd.ts b/packages/server/src/cli/service/launchd.ts index bcbbd3fd..29d48548 100644 --- a/packages/server/src/cli/service/launchd.ts +++ b/packages/server/src/cli/service/launchd.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/service/launchd.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/service/launchd.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // macOS: a launchd LaunchAgent in the `gui/` domain (SPEC §7). It starts at login, not at boot, and runs as the // user, inside their login session (so the login keychain is unlocked). Node built-ins only. // diff --git a/packages/server/src/cli/service/logs.ts b/packages/server/src/cli/service/logs.ts index 859270ba..2c0de3e6 100644 --- a/packages/server/src/cli/service/logs.ts +++ b/packages/server/src/cli/service/logs.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/service/logs.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/service/logs.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // ` service logs [-f] [-n ]` (SPEC §1, §7): one Node implementation on every OS, because every unit // writes to `/logs/service.log`. No `tail`: `tail -f` isn't on Windows, and which `tail` won a PATH lookup would // change the output. Node built-ins only. diff --git a/packages/server/src/cli/service/manager.ts b/packages/server/src/cli/service/manager.ts index 6baf232d..5dc1c0ec 100644 --- a/packages/server/src/cli/service/manager.ts +++ b/packages/server/src/cli/service/manager.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/service/manager.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/service/manager.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // The seam between what a tool's service is and how a service manager spells it (SPEC §7). launchd.ts and // systemd.ts implement `ServiceManager`; Task Scheduler (Windows, P3) is the third, later, behind the same interface. // Every command goes through a `Runner`, so the lifecycle is tested with a fake one, on any OS. Node built-ins only. diff --git a/packages/server/src/cli/service/path-env.ts b/packages/server/src/cli/service/path-env.ts index 3ed46cfa..bfdd59f7 100644 --- a/packages/server/src/cli/service/path-env.ts +++ b/packages/server/src/cli/service/path-env.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/service/path-env.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/service/path-env.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // The PATH a unit gives the service (SPEC §7): Node's own bin folder first, then the installing shell's PATH without // its per-shell entries, then the system folders. Only folders that exist are kept. Node built-ins only. // diff --git a/packages/server/src/cli/service/systemd.ts b/packages/server/src/cli/service/systemd.ts index fef3e371..090041f7 100644 --- a/packages/server/src/cli/service/systemd.ts +++ b/packages/server/src/cli/service/systemd.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/service/systemd.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/service/systemd.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // Linux: a systemd user unit (`systemctl --user`, SPEC §7), running as the user. Without linger the user's manager, // and the service with it, stops at their last logout, SSH sessions included; `linger()` asks, and the tool prints // the `sudo loginctl enable-linger` line rather than running it. Node built-ins only. diff --git a/packages/server/src/cli/update/health.ts b/packages/server/src/cli/update/health.ts index c63547d3..e28591c9 100644 --- a/packages/server/src/cli/update/health.ts +++ b/packages/server/src/cli/update/health.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/health.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/health.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // Asking `/api/health` (SPEC §8): once, until it answers, or until it answers with one version. The service commands // wait on it before they claim success, and `update` waits for the target version (SPEC §5 step 12). It's an HTTP // request to the URL a person would open, not a pid lookup: launchd and systemd both report a crash-looping job as diff --git a/packages/server/src/cli/update/install-method.ts b/packages/server/src/cli/update/install-method.ts index f369a9de..6fe858fa 100644 --- a/packages/server/src/cli/update/install-method.ts +++ b/packages/server/src/cli/update/install-method.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/install-method.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/install-method.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // How was this copy installed? (SPEC §6.) `update` can't run `npm install -g` on a checkout, in a container or out of // npx's cache, so before it touches anything it works out which of the table's ten rows it's in, and either picks the // package manager or prints the command that would work and exits 5. diff --git a/packages/server/src/cli/update/lock.ts b/packages/server/src/cli/update/lock.ts index e82917b9..0e62fd9b 100644 --- a/packages/server/src/cli/update/lock.ts +++ b/packages/server/src/cli/update/lock.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/lock.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). +// From edspencer/cli-contract reference/lock.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). // `/update.lock`: one update at a time (SPEC §5 step 1). Two at once is easy to cause (an Ansible run and a // person at a terminal) and bad: the second stops the service the first just started, or installs an older target // over a newer one, and the loser's rollback "restores" a version nobody asked for. diff --git a/packages/server/src/cli/update/package-manager.ts b/packages/server/src/cli/update/package-manager.ts index 83c31878..0910a2ef 100644 --- a/packages/server/src/cli/update/package-manager.ts +++ b/packages/server/src/cli/update/package-manager.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/package-manager.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). +// From edspencer/cli-contract reference/package-manager.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). // Running the package manager (SPEC §5 steps 5, 8 and 10, §6, §7). Node built-ins only. // // - **npm is the one beside `process.execPath`**, run as `node `, never whichever `npm` is first on PATH. diff --git a/packages/server/src/cli/update/registry.ts b/packages/server/src/cli/update/registry.ts index 594d3b3a..6b3fb1ed 100644 --- a/packages/server/src/cli/update/registry.ts +++ b/packages/server/src/cli/update/registry.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/registry.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/registry.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // The npm registry, as `update` asks it (SPEC §5 step 3): two requests with `fetch` and a 10-second abort. // // GET /-/package//dist-tags which version `latest` (or `--to `) is diff --git a/packages/server/src/cli/update/semver.ts b/packages/server/src/cli/update/semver.ts index 1f2c6843..68a584e4 100644 --- a/packages/server/src/cli/update/semver.ts +++ b/packages/server/src/cli/update/semver.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/semver.ts @ 0.2; local changes: `.ts` import specifiers → `.js`. +// From edspencer/cli-contract reference/semver.ts @ 1.0; local changes: `.ts` import specifiers → `.js`. // The small semver `update` needs (SPEC §5 step 4): is the target newer, is it a prerelease, and does its // `engines.node` accept this Node. Node built-ins only. // diff --git a/packages/server/src/cli/update/update-check.ts b/packages/server/src/cli/update/update-check.ts index 7a8d5ff5..7eea960b 100644 --- a/packages/server/src/cli/update/update-check.ts +++ b/packages/server/src/cli/update/update-check.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/update-check.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). +// From edspencer/cli-contract reference/update-check.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). // `/update-check.json`: what the last registry question found (SPEC §3). Only `update`, `update --check` and // `doctor` ask the registry; they write the answer here, and `service status` repeats it without opening a socket. // It's the document `update --check --json` prints (`schemas/update-check.schema.json`), and `service status --json`'s diff --git a/packages/server/src/cli/update/update.ts b/packages/server/src/cli/update/update.ts index 18be40e8..efb1e681 100644 --- a/packages/server/src/cli/update/update.ts +++ b/packages/server/src/cli/update/update.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/update.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). +// From edspencer/cli-contract reference/update.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`). // ` update`: SPEC §5, step by step, for every tool. Node built-ins only; nothing here imports a server. // // It's a sequence over injected hooks. A tool supplies what's its own (`UpdateProduct`): its names, its busy check, diff --git a/packages/server/src/runtime-file.ts b/packages/server/src/runtime-file.ts index 53211593..11445e9d 100644 --- a/packages/server/src/runtime-file.ts +++ b/packages/server/src/runtime-file.ts @@ -1,4 +1,4 @@ -// From edspencer/cli-contract reference/runtime-file.ts @ 0.2; local changes: none. +// From edspencer/cli-contract reference/runtime-file.ts @ 1.0; local changes: none. // `/runtime.json`: what a running instance tells its own CLI (SPEC §4, ROADMAP). `serve` writes it once it's // listening and removes it on a clean exit; `busy`, `service status` and `update` read it to find the instance. // diff --git a/packages/server/test/unit/cli-service.test.ts b/packages/server/test/unit/cli-service.test.ts index 6211321b..550488c2 100644 --- a/packages/server/test/unit/cli-service.test.ts +++ b/packages/server/test/unit/cli-service.test.ts @@ -1226,10 +1226,14 @@ describe("paddock service: install progress + readiness (#861)", () => { it("still prints everything install always printed", async () => { // The report is what people screenshot into issues; the progress lines are - // additive, not a replacement. + // additive, not a replacement. loginctl says linger is off, so the + // enable-linger line is part of it (SPEC 1.0 §7). + const base = recorder().run; + const lingerOff: Runner = (cmd, args) => + cmd === "loginctl" ? { status: 0, stdout: "Linger=no\n", stderr: "" } : base(cmd, args); const out = await capture(() => runService("install", OPTS, { - ...contextFor("linux", home, recorder().run), + ...contextFor("linux", home, lingerOff), checkReady: ready, }), ); @@ -1246,6 +1250,17 @@ describe("paddock service: install progress + readiness (#861)", () => { } }); + it("says nothing about linger when loginctl can't answer (SPEC 1.0 §7)", async () => { + const out = await capture(() => + runService("install", OPTS, { + ...contextFor("linux", home, recorder().run), + checkReady: ready, + }), + ); + expect(out).not.toContain("enable-linger"); + expect(out).not.toContain("could not reach loginctl"); + }); + it("probes /api/health, which is auth-exempt, and gives up on the clock", async () => { const seen: string[] = []; const okAfter = (n: number): typeof fetch => @@ -1312,3 +1327,17 @@ describe("paddock service: refusals", () => { await expect(runService("status", opts, win)).rejects.toThrow(/not win32/); }); }); + +describe("lingerNote (SPEC 1.0 §7)", () => { + it("prints the enable-linger line only when linger is off", async () => { + const { lingerNote } = await import("../../src/cli/service/index.js"); + const off = lingerNote({ applies: true, user: "ed", enabled: false }); + expect(off).toContain("Lingering is off"); + expect(off).toContain("To keep Paddock up, once:"); + expect(off).toContain("sudo loginctl enable-linger ed"); + // loginctl couldn't answer (a container, no loginctl): say nothing, as doctor reports it skipped. + expect(lingerNote({ applies: true, user: "ed" })).toBeUndefined(); + expect(lingerNote({ applies: true, user: "ed", enabled: true })).toBeUndefined(); + expect(lingerNote({ applies: false })).toBeUndefined(); + }); +});