From ad76674e4347708c145a36f4c5165285bc426556 Mon Sep 17 00:00:00 2001 From: HomeLab Agent Date: Thu, 5 Nov 2026 04:48:25 -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 | 27 ++++++--------- packages/server/test/unit/cli-service.test.ts | 33 +++++++++++++++++-- 20 files changed, 69 insertions(+), 43 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 0000000..79a8cb7 --- /dev/null +++ b/.changeset/g3-linger-unknown-quiet.md @@ -0,0 +1,5 @@ +--- +"@managers/server": patch +--- + +`managers 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 255a850..2bc6a89 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 Managers' 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 938ee13..c5f8cd5 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 69fd600..5be7ee2 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` // (Managers 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 d1ab3ac..3293022 100644 --- a/packages/server/src/cli/service/index.ts +++ b/packages/server/src/cli/service/index.ts @@ -260,15 +260,14 @@ function installProgress(backend: ServiceBackend): string { : `\n Installing ${kind} and starting Managers…`; } -/** 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 Managers 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 4d9b1fd..29d4854 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 (with #7, d5ddc0e); 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 859270b..2c0de3e 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 a1d7909..e076e51 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`; and the examples in comments name Managers, not Paddock. // 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 3ed46cf..bfdd59f 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 2ce277d..090041f 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 (with #7, d5ddc0e); 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 dc3c48d..b2a67a0 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`; and the examples in comments name Managers, not Paddock. // 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 5e22ee3..1436774 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`; and the examples in comments name Managers, not Paddock. // 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 4d904ab..df8ffd0 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 Managers 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 Managers keeps them (`../`, `../../`); and the examples in comments name Managers, not Paddock. // `/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 6754eea..e519918 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 Managers 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 Managers 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 594d3b3..6b3fb1e 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 1f2c684..68a584e 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 ec6b2ad..b3fa2db 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 Managers 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 Managers keeps them (`../`, `../../`); and the examples in comments name Managers, not Paddock. // `/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 006fcf6..e9fb435 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 Managers 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 Managers keeps them (`../`, `../../`); and the examples in comments name Managers, not Paddock. // ` 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 1166d0e..11445e9 100644 --- a/packages/server/src/runtime-file.ts +++ b/packages/server/src/runtime-file.ts @@ -1,8 +1,4 @@ -// From edspencer/cli-contract reference/runtime-file.ts @ SPEC 0.1; local changes: `node:fs` / `node:path` imports -// unchanged, nothing else — the module is Node built-ins only and Managers' `` is its data dir, so it needed -// no adaptation. Kept verbatim on purpose: wave C4 re-syncs it, and a divergence here would be a divergence in the -// one file every tool's `busy`, `service status` and `update` agree on. -// +// 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. // @@ -10,8 +6,8 @@ // is settled; the file is written 0600 already, so adding one later changes nothing about who can read it. // Node built-ins only. -import fs from "node:fs"; -import path from "node:path"; +import fs from 'node:fs'; +import path from 'node:path'; export interface RuntimeInfo { pid: number; @@ -23,17 +19,14 @@ export interface RuntimeInfo { startedAt: string; } -export const RUNTIME_FILE = "runtime.json"; +export const RUNTIME_FILE = 'runtime.json'; export function runtimeFilePath(home: string): string { return path.join(home, RUNTIME_FILE); } /** Writes the file atomically (a temporary file, then a rename), readable only by this user. */ -export function writeRuntimeFile( - home: string, - info: Omit & { startedAt?: string }, -): RuntimeInfo { +export function writeRuntimeFile(home: string, info: Omit & { startedAt?: string }): RuntimeInfo { const full: RuntimeInfo = { pid: info.pid, port: info.port, @@ -58,7 +51,7 @@ export function writeRuntimeFile( export function readRuntimeFile(home: string): RuntimeInfo | null { let raw: string; try { - raw = fs.readFileSync(runtimeFilePath(home), "utf8"); + raw = fs.readFileSync(runtimeFilePath(home), 'utf8'); } catch { return null; } @@ -67,9 +60,9 @@ export function readRuntimeFile(home: string): RuntimeInfo | null { if ( Number.isInteger(v.pid) && Number.isInteger(v.port) && - typeof v.url === "string" && - typeof v.version === "string" && - typeof v.startedAt === "string" + typeof v.url === 'string' && + typeof v.version === 'string' && + typeof v.startedAt === 'string' ) { return v as RuntimeInfo; } @@ -97,7 +90,7 @@ export function isPidAlive(pid: number): boolean { process.kill(pid, 0); return true; } catch (err) { - return (err as NodeJS.ErrnoException).code === "EPERM"; + return (err as NodeJS.ErrnoException).code === 'EPERM'; } } diff --git a/packages/server/test/unit/cli-service.test.ts b/packages/server/test/unit/cli-service.test.ts index 4bc64f2..da4dcb2 100644 --- a/packages/server/test/unit/cli-service.test.ts +++ b/packages/server/test/unit/cli-service.test.ts @@ -1226,10 +1226,14 @@ describe("managers 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("managers 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("managers 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 Managers 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(); + }); +});