Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/g3-linger-unknown-quiet.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion packages/server/src/cli/busy.ts
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/exit-codes.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/output.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
15 changes: 7 additions & 8 deletions packages/server/src/cli/service/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"}`
);
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/service/launchd.ts
Original file line number Diff line number Diff line change
@@ -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/<uid>` 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.
//
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/service/logs.ts
Original file line number Diff line number Diff line change
@@ -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`.
// `<tool> service logs [-f] [-n <lines>]` (SPEC §1, §7): one Node implementation on every OS, because every unit
// writes to `<home>/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.
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/service/manager.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/service/path-env.ts
Original file line number Diff line number Diff line change
@@ -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.
//
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/service/systemd.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/health.ts
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/install-method.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/lock.ts
Original file line number Diff line number Diff line change
@@ -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 (`../`, `../../`).
// `<home>/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.
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/package-manager.ts
Original file line number Diff line number Diff line change
@@ -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 <npm-cli.js>`, never whichever `npm` is first on PATH.
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/registry.ts
Original file line number Diff line number Diff line change
@@ -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 <registry>/-/package/<name>/dist-tags which version `latest` (or `--to <tag>`) is
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/semver.ts
Original file line number Diff line number Diff line change
@@ -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.
//
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/update-check.ts
Original file line number Diff line number Diff line change
@@ -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 (`../`, `../../`).
// `<home>/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
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/cli/update/update.ts
Original file line number Diff line number Diff line change
@@ -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 (`../`, `../../`).
// `<tool> 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,
Expand Down
2 changes: 1 addition & 1 deletion packages/server/src/runtime-file.ts
Original file line number Diff line number Diff line change
@@ -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.
// `<home>/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.
//
Expand Down
33 changes: 31 additions & 2 deletions packages/server/test/unit/cli-service.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}),
);
Expand All @@ -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 =>
Expand Down Expand Up @@ -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();
});
});
Loading