From c685d4839d4265e6f3d7f57496a1b4f0ba80768d Mon Sep 17 00:00:00 2001 From: HomeLab Agent Date: Thu, 5 Nov 2026 03:12:17 -0500 Subject: [PATCH 1/3] feat(cli): align the CLI with the cli-contract spec (F1) Ported from Paddock, whose CLI this is, by three-way merging Paddock's own changes onto Managers: B1 (paddock#981, #983), the launchd bootout/bootstrap race fix (paddock#984) and the systemd restart-an-active-unit fix (paddock#986). - /api/health answers { ok, version } (version.ts, shared with the OpenAPI document and the management MCP handshake). - `serve`, with `start` a permanent alias; the server logs to stderr so the first stdout line is `Managers : `. - Exit codes: usage errors 2 with the usage after; `service status` 0/3/4; logs/start/stop/restart 4 with no unit; an install that never answers 1. - `service status --json`, `service logs [-f] [-n]`; Linux logs go to /logs/service.log, rotated by copy-and-truncate. - Units: realpath'd Node, a rebuilt PATH, quoted ExecStart, a linger check. - launchd: poll until a bootout has finished, retry bootstrap on 5/37. - systemd: install restarts a unit that was already active. - Real-service CI (scripts/service-real.mjs) and the conformance runner (@edspencer/cli-conformance ^0.2.0): 7 passed, 2 skipped (busy, F2). Co-Authored-By: Claude Opus 5.5 --- .changeset/cli-contract-align.md | 49 ++ .github/workflows/ci.yml | 72 ++ CONTRIBUTING.md | 19 + README.md | 10 + cli-contract.json | 50 ++ package-lock.json | 14 + package.json | 1 + packages/server/src/app.ts | 31 +- packages/server/src/cli/args.ts | 140 +++- packages/server/src/cli/exit-codes.ts | 50 ++ packages/server/src/cli/managers.ts | 129 ++- packages/server/src/cli/service/backend.ts | 53 +- packages/server/src/cli/service/index.ts | 423 ++++++++-- packages/server/src/cli/service/launchd.ts | 177 +++- packages/server/src/cli/service/logs.ts | 125 +++ packages/server/src/cli/service/path-env.ts | 136 +++ packages/server/src/cli/service/ready.ts | 39 + packages/server/src/cli/service/spec.ts | 75 +- packages/server/src/cli/service/systemd.ts | 196 ++++- packages/server/src/management-mcp-server.ts | 18 +- packages/server/src/routes/meta.ts | 15 +- packages/server/src/service-log.ts | 118 +++ packages/server/src/start.ts | 12 + packages/server/src/version.ts | 33 + .../integration/cli-bin-invocation.test.ts | 70 +- .../server/test/integration/routes.test.ts | 26 +- packages/server/test/unit/cli-config.test.ts | 2 +- .../server/test/unit/cli-contract.test.ts | 783 ++++++++++++++++++ .../server/test/unit/cli-managers.test.ts | 5 +- packages/server/test/unit/cli-service.test.ts | 271 +++++- scripts/service-real.mjs | 279 +++++++ 31 files changed, 3159 insertions(+), 262 deletions(-) create mode 100644 .changeset/cli-contract-align.md create mode 100644 cli-contract.json create mode 100644 packages/server/src/cli/exit-codes.ts create mode 100644 packages/server/src/cli/service/logs.ts create mode 100644 packages/server/src/cli/service/path-env.ts create mode 100644 packages/server/src/service-log.ts create mode 100644 packages/server/src/version.ts create mode 100644 packages/server/test/unit/cli-contract.test.ts create mode 100644 scripts/service-real.mjs diff --git a/.changeset/cli-contract-align.md b/.changeset/cli-contract-align.md new file mode 100644 index 00000000..c608eff3 --- /dev/null +++ b/.changeset/cli-contract-align.md @@ -0,0 +1,49 @@ +--- +"@managers/server": minor +--- + +Align the `managers` CLI with the CLI contract (SPEC 0.2) + +`serve` is now the name for running in the foreground, `/api/health` reports the +version it is running, `service status` answers in scriptable exit codes and +`--json`, there is a `service logs`, and the generated units are hardened. Ported +from Paddock 0.80–0.82, whose CLI this is. + +**Behaviour changes a script can see.** These are why this is a minor: + +- **Usage errors now exit `2`, not `1`.** An unknown command, flag or bad value + exits 2 and prints a short usage synopsis after the message. `1` now means only + that something genuinely failed. +- **`service status` now exits `3` or `4`.** `0` when installed, running and + answering; `3` when installed but not running, or running and not answering; + `4` when there is no unit. `service logs`, `start`, `stop` and `restart` exit + `4` with no unit too. +- **An `install`, `start` or `restart` that never answers now exits `1`**, not 0. +- **Linux service logs go to a file, not the journal.** Both streams append to + `/logs/service.log` (the path macOS already used, now one file rather + than two), which Managers rotates itself at 8 MB, keeping three generations. + An existing unit keeps the path it names until `managers service install` is + re-run. +- **The server's logs now go to stderr, not stdout**, so `serve`'s first stdout + line is `Managers : `. Docker, Kubernetes and the service units + collect both streams; a log shipper reading stdout ALONE is the one thing that + changes. + +Everything else is additive: + +- `managers serve` runs the server; **`managers start` stays an alias, for good.** +- `GET /api/health` answers `{ ok, version }`, with no auth. +- `managers service status --json`: installed / running / answering, the + installed and running versions, port, URL, pid, unit, log file and warnings. +- `managers service logs [-f] [-n ]`, the last 50 lines by default. +- The main `--help` lists all seven `service` actions. +- Generated units: Node resolved through symlinks, a `PATH` without per-session + entries or missing directories, every systemd `ExecStart` word quoted, and + warnings for a vanished Node, a running-vs-installed version gap and (Linux) + lingering being off, which is now checked rather than printed at everyone. +- **macOS:** `install`, `start` and `restart` no longer lose a race with launchd + (`Bootstrap failed: 5: Input/output error`): they wait for a bootout to finish, + and retry a bootstrap that returns launchd's race codes 5 or 37. +- **Linux:** a reinstall over a RUNNING service now restarts it. + `systemctl --user enable --now` does nothing to an active unit, so the old + process went on serving the old code. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 09505b87..0235498d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,6 +37,78 @@ jobs: - name: Unit + integration tests run: npm test + # The CLI contract, checked from the outside by @edspencer/cli-conformance: `--version` is + # bare, `--help` exits 0, an unknown flag exits 2 with the usage after the message, + # `service status` exits 4 with nothing installed and its --json matches the shared schema, + # `serve`'s first stdout line is `Managers : `, and /api/health answers with + # that same version. `cli-contract.json` at the root says which checks apply and why the + # two that don't (`busy`, wave C1) don't — a NEWER runner's new check fails until this repo + # says whether it applies, which is the point. + # + # `--dir dist-npm`, not the repo root: Managers' publishable package is SYNTHESIZED from two + # private workspaces by scripts/make-npm-package.mjs (see RELEASING.md), so `npm pack` at the + # root would pack the private root manifest, which has no `bin` at all. `npm run pack:npm` + # stages the real thing and the runner packs that — the same tarball a user installs. + # + # This is the check that found the banner bug: with pino on stdout, a machine with no Claude + # login printed a JSON log line as `serve`'s first line. Nothing else in CI could see it. + conformance: + name: CLI conformance + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 22 + cache: npm + - run: npm ci + - name: Stage the npm package + run: npm run pack:npm + - name: Conformance + run: npx cli-conformance --dir dist-npm --config cli-contract.json + + # `managers service …` against the REAL service manager: launchd's gui/ domain on the + # macOS runner, systemd's user instance on the Ubuntu runner (with lingering on, so there + # is one). scripts/service-real.mjs stages and packs the npm package, installs it into a + # temporary prefix, then installs, kills, stops, starts, restarts and uninstalls the + # service, checking the exit codes and that the log file really receives the server's + # stdout. It writes the runner's real LaunchAgents / systemd user directory under the real + # label, which is why it runs only here and refuses without MANAGERS_REAL_SERVICE=1. + # + # This is the only place the service CAN be proven: the dev box is a container with tini + # as PID 1 — no systemd, not a Mac — so everything else about these units is covered by + # unit tests of the rendered file, which cannot catch a key launchd rejects or a + # `systemctl --user` that will not load what we wrote. + service: + name: Service (real ${{ matrix.os == 'macos-latest' && 'launchd' || 'systemd' }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 22 + cache: npm + - run: npm ci + # A `systemctl --user` needs a user manager, and a GitHub runner has none until + # lingering starts one. Without this every systemctl call fails on the bus address. + - name: Start a systemd user instance (Linux) + if: runner.os == 'Linux' + run: | + sudo loginctl enable-linger "$USER" + for i in $(seq 1 20); do [ -S "/run/user/$(id -u)/bus" ] && break; sleep 0.5; done + echo "XDG_RUNTIME_DIR=/run/user/$(id -u)" >> "$GITHUB_ENV" + echo "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus" >> "$GITHUB_ENV" + - name: The service lifecycle, for real + env: + MANAGERS_REAL_SERVICE: "1" + run: node scripts/service-real.mjs + # Fails on a high/critical npm advisory that is not a documented exception # (docs/security/npm-audit.md). Reads only the lockfile, so no `npm ci`. audit: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 02965327..2cca8521 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,25 @@ npm run test:e2e # Playwright journeys against the real server + a fa The tell that you are looking at contention rather than a regression: the failures pass when re-run in isolation. +- **The CLI contract** is checked from the outside by + [`@edspencer/cli-conformance`](https://github.com/edspencer/cli-contract), which packs the + package, installs it into a temporary prefix and runs the installed `managers` with a + throwaway home: + + ```bash + npm run pack:npm # stage dist-npm first + npx cli-conformance --dir dist-npm --config cli-contract.json + ``` + + **`--dir dist-npm` is not optional.** The publishable `@edspencer/managers` is synthesized + from the two private workspaces (see [RELEASING.md](RELEASING.md)), so `npm pack` at the + repo root packs the private root manifest, which has no `bin`. `cli-contract.json` lists + every check the runner has and why the ones that do not apply yet do not — a new check in + a newer runner fails until this repo says which it is. + + It is worth running by hand when you touch the CLI, because it checks things no unit test + can see: that `serve`'s FIRST stdout line is `Managers : ` (it found a JSON + log record there), and that `service status --json` matches the contract's shared schema. - More on the test layers: [docs/TESTING.md](docs/TESTING.md). ## The demo reel diff --git a/README.md b/README.md index 3639cc30..37a9d462 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,16 @@ docker run -d --name managers -p 127.0.0.1:7234:7234 -v /srv/managers-data:/data Each GitHub Release also carries a self-contained tarball. +**Commands.** Bare `managers` runs the server; `managers serve` is the same thing +said out loud (`managers start` is a permanent alias). `managers service install` +runs it in the background from login (a launchd LaunchAgent on macOS, a +`systemd --user` unit on Linux), with `uninstall`, `start`, `stop`, `restart`, +`status [--json]` and `logs [-f] [-n ]`. `service status` exits **0** when +it is up and answering, **3** when installed but not, and **4** when there is no +unit; a bad command, flag or value exits **2**. The CLI follows the shared +[CLI contract](https://github.com/edspencer/cli-contract) (`cli-contract.json` +says which of its checks apply). + ## Quick start from a checkout You need **Node 22+**. Build once: diff --git a/cli-contract.json b/cli-contract.json new file mode 100644 index 00000000..c30a49fb --- /dev/null +++ b/cli-contract.json @@ -0,0 +1,50 @@ +{ + "$schema": "./node_modules/@edspencer/cli-conformance/schemas/cli-contract.schema.json", + "name": "Managers", + "serve": { + "args": [ + "serve", + "--port", + "{port}", + "--host", + "127.0.0.1", + "--data-dir", + "{home}/managers" + ], + "timeoutMs": 60000 + }, + "env": { + "MANAGERS_DATA_DIR": "{home}/managers", + "MANAGERS_DRIVE_MODE": "batch", + "MANAGERS_ALLOW_BATCH_DRIVE": "1", + "MANAGERS_AUTH_MODE": "none", + "MANAGERS_DANGEROUSLY_ALLOW_NO_AUTH": null, + "MANAGERS_PROJECTS_DIR": null, + "MANAGERS_AUTH_JWKS_URL": null, + "MANAGERS_AUTH_JWT_HEADER": null, + "MANAGERS_SELF_MCP": null, + "MANAGERS_SELF_MCP_WRITE": null, + "MANAGERS_SELF_MCP_PROJECTS": null, + "CLAUDE_CODE_OAUTH_TOKEN": null, + "ANTHROPIC_API_KEY": null, + "CLAUDE_CONFIG_DIR": null, + "HOST": null, + "PORT": null, + "NODE_ENV": null + }, + "checks": { + "version": true, + "help": true, + "unknown-flag": true, + "service-status": true, + "service-status-json": true, + "busy": { + "skip": "no `managers busy` until wave F2 of the CLI-contract rollout" + }, + "busy-json": { + "skip": "no `managers busy` until wave F2 of the CLI-contract rollout" + }, + "serve-banner": true, + "serve-health": true + } +} diff --git a/package-lock.json b/package-lock.json index ad752fe8..bb36ad5f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,6 +14,7 @@ "devDependencies": { "@changesets/changelog-github": "^0.5.2", "@changesets/cli": "^2.31.0", + "@edspencer/cli-conformance": "^0.2.0", "@playwright/test": "^1.61.0", "playwright": "^1.61.0" }, @@ -994,6 +995,19 @@ "node": ">=18" } }, + "node_modules/@edspencer/cli-conformance": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@edspencer/cli-conformance/-/cli-conformance-0.2.0.tgz", + "integrity": "sha512-NdMOpEc9le30qv+Jj0US7e/ciCUiLQwEqV39HLuLjOFuRuPdqcjsLsXHR9V5QHjNveu/hFJvMUvDhoJEmk8q+A==", + "dev": true, + "license": "MIT", + "bin": { + "cli-conformance": "dist/src/cli.js" + }, + "engines": { + "node": ">=22" + } + }, "node_modules/@esbuild/aix-ppc64": { "version": "0.21.5", "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz", diff --git a/package.json b/package.json index 6e2e8de7..b47131be 100644 --- a/package.json +++ b/package.json @@ -43,6 +43,7 @@ "devDependencies": { "@changesets/changelog-github": "^0.5.2", "@changesets/cli": "^2.31.0", + "@edspencer/cli-conformance": "^0.2.0", "@playwright/test": "^1.61.0", "playwright": "^1.61.0" }, diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts index 80806199..7ff503e4 100644 --- a/packages/server/src/app.ts +++ b/packages/server/src/app.ts @@ -16,7 +16,6 @@ import fastifyStatic from "@fastify/static"; import fastifyMultipart from "@fastify/multipart"; import fastifySwagger from "@fastify/swagger"; import fastifySwaggerUi from "@fastify/swagger-ui"; -import { createRequire } from "node:module"; import { promises as fs } from "node:fs"; import path from "node:path"; import { loadPaddockConfig, type PaddockConfig } from "./config.js"; @@ -67,17 +66,10 @@ import { ensureDataRepo, dataGitInitEnabled } from "./managers/data-repo.js"; import { ManagersState } from "./managers/state.js"; import { Autocommitter } from "./managers/autocommit.js"; import { DataSync } from "./managers/data-sync.js"; +// One source of truth for "which Managers is this?" — the OpenAPI document, +// /api/health and the management MCP handshake all read it (version.ts). +import { MANAGERS_VERSION } from "./version.js"; -// Resolve the package version at runtime (dist/app.js → ../package.json) so the -// generated OpenAPI document's info.version tracks the release without a build step. -const pkgVersion: string = (() => { - try { - const require = createRequire(import.meta.url); - return (require("../package.json") as { version?: string }).version ?? "0.0.0"; - } catch { - return "0.0.0"; - } -})(); export interface BuiltApp { app: FastifyInstance; @@ -160,7 +152,20 @@ export async function buildApp(opts: BuildAppOptions = {}): Promise { installHerdctlBridgeLoopbackBind(); const app = Fastify({ - logger: { level: cfg.logLevel }, + // **Logs go to stderr, not stdout**, and that is load-bearing rather than + // tidy. SPEC §3 of the CLI contract requires `serve`'s FIRST stdout line to + // be `Managers : ` — the line a script reads to find the URL — + // and boot logging is emitted before the server can know it has bound. With + // pino on stdout, a machine with no Claude login (every CI runner, every + // fresh install) put `{"level":40,…,"msg":"no Claude credentials found…"}` + // there first, so the first line was a JSON log record. The conformance + // runner caught it; nothing else would have. + // + // Nothing loses the logs: Docker and Kubernetes collect both streams, and + // the service units send stdout and stderr to the same file (SPEC §7). A log + // shipper configured for stdout ALONE is the one thing that changes, which + // is why the changeset says so. + logger: { level: cfg.logLevel, stream: process.stderr }, }); // --- safe-by-default bind guard (#435) -------------------------------- @@ -497,7 +502,7 @@ export async function buildApp(opts: BuildAppOptions = {}): Promise { readImage(path.join("icons", "icon-192.png"), "image/png"), readImage(path.join("icons", "favicon-32.png"), "image/png"), ]); - await app.register(fastifySwagger, buildSwaggerOptions(pkgVersion, cfg.auth)); + await app.register(fastifySwagger, buildSwaggerOptions(MANAGERS_VERSION, cfg.auth)); await app.register( fastifySwaggerUi, buildSwaggerUiOptions({ diff --git a/packages/server/src/cli/args.ts b/packages/server/src/cli/args.ts index 6ab2deb3..f4c4df0b 100644 --- a/packages/server/src/cli/args.ts +++ b/packages/server/src/cli/args.ts @@ -24,6 +24,8 @@ * the next shim, platform or package manager. `managers.ts` now always runs. */ +import { EXIT } from "./exit-codes.js"; + export interface CliOptions { port?: string; host?: string; @@ -68,10 +70,41 @@ export interface CliOptions { * supplies. Off by default — see the argument in config.ts. */ includeEnv?: boolean; + /** `service logs`: keep printing what gets appended (`-f`). */ + follow?: boolean; + /** `service logs`: how many lines to print first (`-n`, default 50). */ + lines?: number; +} + +/** + * A failure with an exit code attached (SPEC §2). + * + * Thrown rather than exiting, so parsing stays testable. The code travels with + * the error because the thing that KNOWS which code applies is whatever threw — + * `main` cannot tell an unsupported platform (a failure, 1) from a misspelled + * flag (usage, 2) by looking at a string. + */ +export class CliError extends Error { + readonly exitCode: number; + constructor(message: string, exitCode: number = EXIT.failure) { + super(message); + this.exitCode = exitCode; + } } -/** A usage error. Thrown rather than exiting, so parsing stays testable. */ -export class CliError extends Error {} +/** + * An unknown command, an unknown flag, or a bad value: exit 2 (SPEC §2). + * + * **This is a behaviour change, and a deliberate one.** Every one of these used + * to exit 1, which is also what a genuine failure exits — so a script could not + * tell "you typed it wrong" from "it tried and could not". The contract splits + * them, and a script that tested `$? -eq 1` for a typo now needs `-eq 2`. + */ +export class UsageError extends CliError { + constructor(message: string) { + super(message, EXIT.usage); + } +} export const MIN_NODE_MAJOR = 22; @@ -91,6 +124,7 @@ export const SERVICE_ACTIONS = [ "start", "stop", "restart", + "logs", ] as const; export type ServiceAction = (typeof SERVICE_ACTIONS)[number]; @@ -105,8 +139,15 @@ export type ServiceAction = (typeof SERVICE_ACTIONS)[number]; export const CONFIG_ACTIONS = ["show", "eject"] as const; export type ConfigAction = (typeof CONFIG_ACTIONS)[number]; -/** The leading words {@link parseCommand} recognises. Anything else is a flag. */ -export const VERBS = ["start", "service", "config"] as const; +/** + * The leading words {@link parseCommand} recognises. Anything else is a flag. + * + * `serve` is the contract's name for running in the foreground (SPEC §1), and + * `start` is kept as an alias **for good** — the spec says so explicitly for + * Managers and Managers, every existing service unit's `ExecStart` names it, and + * it is in two years of other people's scripts. They parse to the same command. + */ +export const VERBS = ["serve", "start", "service", "config"] as const; /** * A parsed invocation: which verb, plus the flags that followed it. @@ -116,7 +157,7 @@ export const VERBS = ["start", "service", "config"] as const; * is the whole request. It is `undefined` only when `opts.help` is true. */ export type Command = - | { verb: "start"; opts: CliOptions } + | { verb: "serve"; opts: CliOptions } | { verb: "service"; action: ServiceAction | undefined; opts: CliOptions } | { verb: "config"; action: ConfigAction | undefined; opts: CliOptions }; @@ -136,7 +177,7 @@ function parseAction( let action: T | undefined; if (head !== undefined && !head.startsWith("-")) { if (!(actions as readonly string[]).includes(head)) { - throw new CliError( + throw new UsageError( `unknown ${verb} action: ${head}\n` + `Expected one of: ${actions.join(", ")}.\n` + `Run \`managers ${verb} --help\` for usage.`, @@ -147,7 +188,7 @@ function parseAction( const opts = parseArgs(action === undefined ? rest : rest.slice(1)); // `--help` wins over a missing action: asking for usage is not a usage error. if (action === undefined && !opts.help) { - throw new CliError( + throw new UsageError( `\`managers ${verb}\` needs an action: ${actions.join(", ")}.\n` + `Run \`managers ${verb} --help\` for usage.`, ); @@ -192,9 +233,10 @@ export function parseCommand(argv: string[]): Command { return { verb: "config", ...parseAction("config", CONFIG_ACTIONS, rest) }; } - if (first === "start") return { verb: "start", opts: parseArgs(rest) }; + // `serve` and `start` are one command: see VERBS. + if (first === "serve" || first === "start") return { verb: "serve", opts: parseArgs(rest) }; - return { verb: "start", opts: parseArgs(argv) }; + return { verb: "serve", opts: parseArgs(argv) }; } export function parseArgs(argv: string[]): CliOptions { @@ -208,7 +250,7 @@ export function parseArgs(argv: string[]): CliOptions { const arg = argv[i]; const next = (): string => { const v = argv[++i]; - if (v === undefined) throw new CliError(`${arg} needs a value`); + if (v === undefined) throw new UsageError(`${arg} needs a value`); return v; }; switch (arg) { @@ -225,7 +267,7 @@ export function parseArgs(argv: string[]): CliOptions { // into a hard error. const v = next(); if (v !== "" && (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 65535)) { - throw new CliError(`${arg} needs a number between 1 and 65535, got: ${v}`); + throw new UsageError(`${arg} needs a number between 1 and 65535, got: ${v}`); } opts.port = v; break; @@ -262,6 +304,21 @@ export function parseArgs(argv: string[]): CliOptions { case "--include-env": opts.includeEnv = true; break; + // `service logs` flags, the names `tail`, `journalctl` and every other + // log reader uses — this is not the place to be original. + case "-f": + case "--follow": + opts.follow = true; + break; + case "-n": + case "--lines": { + const v = next(); + if (!/^\d+$/.test(v) || Number(v) < 1) { + throw new UsageError(`${arg} needs a positive number of lines, got: ${v}`); + } + opts.lines = Number(v); + break; + } case "-h": case "--help": opts.help = true; @@ -271,7 +328,7 @@ export function parseArgs(argv: string[]): CliOptions { opts.version = true; break; default: - throw new CliError(`unknown option: ${arg}\nRun \`managers --help\` for usage.`); + throw new UsageError(`unknown option: ${arg}`); } } return opts; @@ -317,13 +374,34 @@ export function explainListenError(err: unknown, host: string, port: string): st return String((err as { message?: string } | undefined)?.message ?? err); } +/** + * The command list, on its own. + * + * Printed after a usage error, because SPEC §2 says the usage follows the + * message — and because {@link USAGE} is a thousand words of guide that would + * bury the one line explaining what went wrong. The full text is one + * `--help` away, and the last line here says so. + */ +export const USAGE_SYNOPSIS = `Usage + managers [serve] [options] run the server in this terminal + managers service [options] install|uninstall|status|start|stop|restart|logs + managers config [options] what this instance's config resolved to + managers -v | --version print the version and exit + managers -h | --help the full help`; + export const USAGE = `managers — run a Managers instance locally Usage - managers [options] start the server (the default) - managers start [options] the same thing, said out loud - managers service - run it in the background from login + npx @edspencer/managers [options] run the server (the default) + managers serve [options] the same thing, said out loud + (\`managers start\` is a permanent alias) + managers service install [options] run it in the background from login + managers service uninstall stop it and remove the unit + managers service status [--json] installed? running? which version? + managers service start start an installed service + managers service stop stop it, leave it installed + managers service restart stop it and start it again + managers service logs [-f] [-n ] the service's log (\`managers service --help\`) managers config show [--resolved] what this instance's config resolved to, and where each value came from @@ -340,6 +418,13 @@ Options -v, --version Print the Managers version and exit -h, --help Show this help +Exit codes + 0 done; running and answering + 1 failed + 2 usage: an unknown command or flag, or a bad value + 3 not running: installed, but not running or not answering + 4 not installed: there is no service unit + Opening your own directories Where you run this from does not matter — the instance is decided by its data dir alone. Directories are added inside the app, on the Discover screen: it @@ -448,10 +533,16 @@ export const SERVICE_USAGE = `managers service — keep Managers running in the Usage managers service install [options] register it and start it now managers service uninstall stop it and deregister it - managers service status is it registered, is it running, where are the logs + managers service status [--json] is it registered, is it running, which + version, where are the logs managers service start start an installed service that is stopped managers service stop stop it, and leave it installed managers service restart stop it and start it again, re-reading config + managers service logs [-f] [-n ] the service's log (the last 50 lines) + +Options (logs) + -f, --follow keep printing what gets appended, until Ctrl-C + -n, --lines how many lines to print first (default 50) Options (install only — recorded in the generated unit) -p, --port HTTP/WS port (default 7234) @@ -483,9 +574,20 @@ At login, not at boot Where it lives macOS ~/Library/LaunchAgents/net.edspencer.managers.plist - logs in /service/ Linux ~/.config/systemd/user/managers.service - logs via journalctl --user -u managers.service -f + + Both write stdout and stderr to ONE file, /logs/service.log, which + is what \`managers service logs\` reads. Not the journal on Linux: a volatile + journal has nothing in it after the reboot you are asking about, and one file + means one answer to "where are the logs" on every OS. Managers rotates it + itself at 8 MB, keeping three older generations beside it. + +Exit codes + 0 it is installed, running and answering + 3 installed, but not running or not answering + 4 not installed: there is no unit (status, logs, start, stop, restart) + 1 something failed + 2 usage: an unknown action or flag, or a bad value Installed from npx? \`service install\` refuses. An npx cache path is hash-keyed and npm may prune diff --git a/packages/server/src/cli/exit-codes.ts b/packages/server/src/cli/exit-codes.ts new file mode 100644 index 00000000..5ee04e1b --- /dev/null +++ b/packages/server/src/cli/exit-codes.ts @@ -0,0 +1,50 @@ +/** + * The CLI contract's exit codes (SPEC §2), as constants. + * + * From edspencer/cli-contract SPEC.md §2 @ 0.1. Written here rather than copied + * from `reference/exit-codes.ts` because the reference module did not exist yet + * when Managers aligned; wave C4 re-syncs this file to it and adds the usual + * provenance header. The numbers, and what each means, are the contract. + * + * | 0 | done; running and answering; up to date; not busy + * | 1 | failed + * | 2 | usage: an unknown command or flag, a bad value + * | 3 | not running: installed but not running or not answering + * | 4 | not installed: there is no service unit + * | 5 | this install cannot update itself (`update`, not yet built) + * | 6 | the update failed and was rolled back (`update`, not yet built) + * | 7 | the update failed and could not be rolled back + * | 75 | busy: refused, and why was printed (`busy`, not yet built) + * + * Codes 3 and 4 are what `systemctl status` and LSB init scripts use for "not + * running" and "no such service", so a script that already branches on them + * keeps working. 75 is `EX_TEMPFAIL` from `sysexits.h`, which is also the code + * that makes Watchtower's pre-update hook skip an update. + * + * The three `update` codes are declared now and unused until wave C2. They are + * here because the contract's whole point is that the numbers mean the same + * thing in every tool: adding them later, from a different file, is how two + * tools end up disagreeing about what 5 means. + */ +export const EXIT = { + /** Done. Running and answering. Up to date. Not busy. */ + ok: 0, + /** Failed — the catch-all. */ + failure: 1, + /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */ + usage: 2, + /** Not running: installed, but not running or not answering. */ + notRunning: 3, + /** Not installed: there is no service unit. */ + notInstalled: 4, + /** This install cannot update itself; the right command was printed. */ + cannotSelfUpdate: 5, + /** The update failed and was rolled back; the old version is running again. */ + rolledBack: 6, + /** The update failed and could not be rolled back; a person is needed. */ + needsHuman: 7, + /** Busy: refused, and why was printed. Try later, or use `--force`. */ + busy: 75, +} as const; + +export type ExitCode = (typeof EXIT)[keyof typeof EXIT]; diff --git a/packages/server/src/cli/managers.ts b/packages/server/src/cli/managers.ts index f8b27367..403ac949 100644 --- a/packages/server/src/cli/managers.ts +++ b/packages/server/src/cli/managers.ts @@ -27,14 +27,18 @@ import { type CliOptions, type Command, CliError, + UsageError, USAGE, + USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js"; -import { runService, safeHomeDir } from "./service/index.js"; +import { EXIT } from "./exit-codes.js"; +import { runService, safeHomeDir, realpathOr } from "./service/index.js"; +import { MANAGERS_NAME, MANAGERS_VERSION } from "../version.js"; /** * This module's own file and directory: `<…>/packages/server/dist/cli/`. @@ -74,18 +78,27 @@ function findUp(rel: string): string | undefined { /** Nearest ancestor holding a `package.json` — `packages/server` in both layouts. */ const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../.."); -function fail(message: string): never { +/** + * Report a failure, and hand back the code to exit with (SPEC §2, §3). + * + * Two things here are the contract rather than style. Errors go to **stderr** + * as `managers: `, so a `--json` document on stdout stays the only + * thing on stdout. And the code is RETURNED rather than passed to + * `process.exit()`: exiting mid-write truncates piped output, which is how a + * `managers service status | jq` loses the end of its document. `main` assigns + * `process.exitCode` and lets the process end on its own. + * + * A usage error also prints the synopsis after the message, because the spec + * says the usage follows the message — the short one, not {@link USAGE}'s + * thousand words, which would bury the line that says what was wrong. + */ +function fail(message: string, code: number = EXIT.failure): number { console.error(`managers: ${message}`); - process.exit(1); -} - -function readVersion(): string { - try { - const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"); - return (JSON.parse(raw) as { version?: string }).version ?? "unknown"; - } catch { - return "unknown"; + if (code === EXIT.usage) { + console.error(""); + console.error(USAGE_SYNOPSIS); } + return code; } /** @@ -132,7 +145,10 @@ function addBundledBinsToPath(): void { */ function noteFirstRun(dataDir: string): void { if (fs.existsSync(dataDir)) return; - console.log( + // stderr, because stdout's first line belongs to the banner (SPEC §3). This + // block is prose for a person and it only appears on a first run — which is + // exactly the run a conformance check or a script reading the URL performs. + console.error( [ "", ` Welcome to Managers. Creating a new instance in ${dataDir}`, @@ -170,18 +186,23 @@ function openBrowser(url: string): void { * for npx's cache, because a unit file pointing into a prunable hash-keyed * directory rots at some future login with nobody watching. */ -async function service(command: Extract): Promise { +async function service(command: Extract): Promise { const { action, opts } = command; // Unreachable: `parseCommand` only omits the action when `--help` was given, // which `main` has already handled. Typed rather than asserted. if (action === undefined) { console.log(SERVICE_USAGE); - return; + return EXIT.ok; } try { - await runService(action, opts, { + return await runService(action, opts, { platform: process.platform, - nodePath: process.execPath, + // Realpath'd (SPEC §7). `process.execPath` under a version manager is + // routinely a symlink into a per-shell directory — fnm's + // `fnm_multishells/_/bin/node` is deleted when that terminal + // exits — so a unit naming the symlink stops working when the tab closes, + // at some later login, with nothing in the logs because it never ran. + nodePath: realpathOr(process.execPath), scriptPath: entryScript, packageRoot, homeDir: safeHomeDir(), @@ -194,8 +215,10 @@ async function service(command: Extract): Promise< ...(process.env.PATH !== undefined ? { pathEnv: process.env.PATH } : {}), }); } catch (err) { - if (err instanceof CliError) fail(err.message); - if (err instanceof Error) fail(err.message); + // A CliError carries its own code: an unsupported platform or an npx + // refusal is a failure (1), a misspelled flag is usage (2). + if (err instanceof CliError) return fail(err.message, err.exitCode); + if (err instanceof Error) return fail(err.message); throw err; } } @@ -224,35 +247,38 @@ function resolveDataDir(opts: CliOptions): string { * the PATH edit, the first-run notice, the log-level defaults — applies to a * command that only reads. */ -async function config(command: Extract): Promise { +async function config(command: Extract): Promise { const { action, opts } = command; // Unreachable: `parseCommand` only omits the action when `--help` was given, // which `main` has already handled. Typed rather than asserted. if (action === undefined) { console.log(CONFIG_USAGE); - return; + return EXIT.ok; } process.env.MANAGERS_DATA_DIR = resolveDataDir(opts); const { runConfig } = await import("./config.js"); try { await runConfig(action, opts); + return EXIT.ok; } catch (err) { // A config that will not load reaches here as a CliError already carrying // the "start would fail too" note; anything else is reported as itself, // because it is a bug in this command rather than in the configuration. // Same shape as `service` above. - if (err instanceof CliError) fail(err.message); - if (err instanceof Error) fail(err.message); + if (err instanceof CliError) return fail(err.message, err.exitCode); + if (err instanceof Error) return fail(err.message); throw err; } } -async function main(): Promise { +async function main(): Promise { let command: Command; try { command = parseCommand(process.argv.slice(2)); } catch (err) { - if (err instanceof CliError) fail(err.message); + // Parse failures are usage failures: exit 2, not 1 (SPEC §2). + if (err instanceof UsageError) return fail(err.message, err.exitCode); + if (err instanceof CliError) return fail(err.message, err.exitCode); throw err; } const opts = command.opts; @@ -261,25 +287,20 @@ async function main(): Promise { console.log( command.verb === "service" ? SERVICE_USAGE : command.verb === "config" ? CONFIG_USAGE : USAGE, ); - return; + return EXIT.ok; } if (opts.version) { - console.log(readVersion()); - return; + // Bare: the version and a newline, nothing else (SPEC §1). Scripts parse this. + console.log(MANAGERS_VERSION); + return EXIT.ok; } const problem = nodeVersionProblem(process.versions.node); - if (problem !== undefined) fail(problem); + if (problem !== undefined) return fail(problem); - if (command.verb === "service") { - await service(command); - return; - } + if (command.verb === "service") return service(command); - if (command.verb === "config") { - await config(command); - return; - } + if (command.verb === "config") return config(command); addBundledBinsToPath(); @@ -362,10 +383,15 @@ async function main(): Promise { try { await start({ loopbackNoAuth }); } catch (err) { - fail(explainListenError(err, host, port)); + return fail(explainListenError(err, host, port)); } const url = `http://${host}:${port}`; + // The contract's banner line, FIRST on stdout and in exactly this shape: + // ` : ` (SPEC §3). It is parsed — by the conformance + // runner, and by anything that wants the URL without guessing the port — so + // the friendly block below it stays, but below it. + console.log(`${MANAGERS_NAME} ${MANAGERS_VERSION}: ${url}`); // Still name the data dir, even though it no longer varies with cwd: "which // instance am I looking at" is a real question the moment anyone passes // `--data-dir`, and the answer should be readable off the two lines the tool @@ -380,9 +406,32 @@ async function main(): Promise { ].join("\n"), ); if (opts.open) openBrowser(url); + // 0, but NOT yet: a foreground serve keeps running because the server holds + // the event loop open. `process.exitCode` is set and never acted on until the + // listener closes, which is what SIGTERM does (start.ts). + return EXIT.ok; } -main().catch((err: unknown) => { - console.error("fatal:", err); - process.exit(1); +/** + * A closed pipe exits quietly (SPEC §2). + * + * `managers service logs | head -5` closes the pipe under us, and Node's default + * is an unhandled EPIPE with a stack trace — printed to the terminal, after the + * output the user asked for, about a thing that is not a problem. + */ +process.stdout.on("error", (err: NodeJS.ErrnoException) => { + if (err.code === "EPIPE") process.exit(0); }); + +main().then( + (code) => { + // `process.exitCode`, never `process.exit()` (SPEC §2): exiting mid-write + // truncates piped output, which is how `managers config show --json | jq` + // loses the end of a large document. + process.exitCode = code; + }, + (err: unknown) => { + console.error("fatal:", err); + process.exitCode = EXIT.failure; + }, +); diff --git a/packages/server/src/cli/service/backend.ts b/packages/server/src/cli/service/backend.ts index 83174324..8ebc16e3 100644 --- a/packages/server/src/cli/service/backend.ts +++ b/packages/server/src/cli/service/backend.ts @@ -34,6 +34,24 @@ export const spawnRunner: Runner = (cmd, args) => { }; }; +/** + * Whether the user lingers — Linux only (SPEC §7). + * + * `loginctl show-user -p Linger` is the question, and all three answers + * are distinct and useful: on (nothing to say), off (the service dies at + * logout, and the fix needs `sudo`), and *unknown* — no `loginctl`, no logind, + * a container. Collapsing unknown into "off" would print a `sudo` instruction + * to someone whose machine has no `loginctl` to run it with. + */ +export interface LingerState { + /** False where the platform has no such concept (darwin). */ + applies: boolean; + /** On, off, or undefined when the check could not answer. */ + enabled?: boolean; + /** The user the check asked about, for the printed command. */ + user?: string; +} + export interface ServiceState { /** Is a unit file installed for us? */ registered: boolean; @@ -42,6 +60,28 @@ export interface ServiceState { pid?: string; /** The Managers arguments recorded in the installed unit, interpreter stripped. */ argv: string[]; + /** + * The interpreter and script the installed unit actually names. + * + * Reported separately from {@link argv} because `status` has to be able to + * say "the Node it runs is not there any more" (SPEC §7), which is only + * answerable from the paths in the FILE. Under nvm, fnm or volta, removing a + * Node version leaves a unit naming an interpreter that no longer exists — + * and the symptom is Managers being absent with an empty log, because it never + * got as far as running. Undefined for a unit we could not parse. + */ + nodePath?: string; + cliPath?: string; + /** + * The log file the installed unit names, if it names one. + * + * Read back rather than recomputed so `status` and `logs` report the file the + * service is really appending to. A unit written before the logs moved to + * `/logs/service.log` names the old pair under `/service/`, + * and telling its owner to read a file nothing writes to is worse than + * telling them nothing. + */ + logPath?: string; /** * Does the unit ON DISK come back after a graceful stop (#872)? * @@ -87,8 +127,13 @@ export interface ServiceBackend { start(): void; stop(): void; restart(): void; - /** How to read the logs, as printed lines. */ - logsHint(spec: ServiceSpec): string; - /** The `enable-linger` warning, or undefined where it does not apply. */ - lingerNote(): string | undefined; + /** + * Does this user linger? (SPEC §7.) Asked of the OS, not assumed. + * + * The note used to be printed unconditionally on Linux, which meant the + * people who had already run `enable-linger` were told to run it at every + * install and every status — so the one line that mattered to the people who + * had NOT was indistinguishable from boilerplate. + */ + linger(): LingerState; } diff --git a/packages/server/src/cli/service/index.ts b/packages/server/src/cli/service/index.ts index 78871199..bbe15c34 100644 --- a/packages/server/src/cli/service/index.ts +++ b/packages/server/src/cli/service/index.ts @@ -26,6 +26,7 @@ import fs from "node:fs"; import os from "node:os"; import path from "node:path"; import { CliError, type CliOptions, type ServiceAction } from "../args.js"; +import { EXIT } from "../exit-codes.js"; import { buildSpec, defaultDataDir, @@ -34,17 +35,27 @@ import { NPX_REFUSAL, portFromArgv, serviceDir, + serviceLogPath, type ServiceSpec, } from "./spec.js"; import { spawnRunner, + type LingerState, type Runner, type ServiceBackend, type ServiceState, } from "./backend.js"; import { createLaunchdBackend } from "./launchd.js"; import { createSystemdBackend } from "./systemd.js"; -import { waitForReady, READY_TIMEOUT_LABEL, type Readiness } from "./ready.js"; +import { missingPaths } from "./path-env.js"; +import { DEFAULT_LOG_LINES, followFile, sizeOf, tailFile } from "./logs.js"; +import { + waitForReady, + fetchHealth, + READY_TIMEOUT_LABEL, + type HealthAnswer, + type Readiness, +} from "./ready.js"; export interface ServiceContext { /** `process.platform`. */ @@ -70,6 +81,11 @@ export interface ServiceContext { * message — twenty seconds per case, and green for the wrong reason. */ checkReady?: (url: string) => Promise; + /** + * "What does `/api/health` say?", injected for the same reason `checkReady` + * is — `status` has to be assertable without a server to ask. + */ + probeHealth?: (url: string) => Promise; } /** @@ -136,17 +152,15 @@ const AT_LOGIN = * signalled rather than crashed. Naming the fix here is the only path from that * symptom back to a working service. */ -function staleUnitNote(backend: ServiceBackend): string { +function staleUnitWarning(backend: ServiceBackend): string { const key = backend.platform === "darwin" ? "KeepAlive is conditional on a non-zero exit" : "Restart=on-failure"; return ( - ` ⚠ This unit predates a fix (#872): ${key}, so a graceful stop —\n` + - " the kind sleep, logout or a stray `kill` sends — puts Managers down\n" + - " until you start it again by hand. Re-run to update the unit:\n" + - "\n" + - " managers service install" + `This unit predates a fix (#872): ${key}, so a graceful stop — the kind ` + + "sleep, logout or a stray `kill` sends — puts Managers down until you start " + + "it again by hand. Re-run `managers service install` to update the unit." ); } @@ -175,11 +189,25 @@ 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"; + return ( + `${head}\n` + + " out of an SSH session. To keep Managers up, once:\n" + + ` sudo loginctl enable-linger ${linger.user ?? "$USER"}` + ); +} + async function install( opts: CliOptions, ctx: ServiceContext, backend: ServiceBackend, -): Promise { +): Promise { if (isNpxPath(ctx.packageRoot)) throw new CliError(NPX_REFUSAL); const { spec, dataDir } = specFor(opts, ctx); @@ -199,7 +227,10 @@ async function install( const kind = backend.platform === "darwin" ? "a launchd LaunchAgent" : "a systemd --user service"; - const linger = backend.lingerNote(); + // Asked of the OS now, rather than printed at everyone (SPEC §7): the people + // who have already enabled lingering were being told to enable it at every + // install, which is how the line stopped being read by the people it is for. + const linger = lingerNote(backend.linger()); console.log( [ @@ -213,7 +244,7 @@ async function install( ...(readiness === "ready" ? [] : [` URL: ${url}`]), ` Data: ${dataDir}`, ` Unit: ${backend.unitPath}`, - backend.logsHint(spec), + ` Logs: ${spec.logPath} (managers service logs -f)`, "", AT_LOGIN, ...(linger !== undefined ? ["", linger] : []), @@ -224,77 +255,291 @@ async function install( "", ].join("\n"), ); + // "It is installed but did not answer" is a failure, and used to exit 0 — so + // an Ansible task or a CI step could not tell it from a working install. + return readiness === "ready" ? EXIT.ok : EXIT.failure; } -function uninstall(ctx: ServiceContext, backend: ServiceBackend): void { +function uninstall(ctx: ServiceContext, backend: ServiceBackend): number { const existed = backend.uninstall(); console.log( existed ? `\n Managers' ${backend.platform === "darwin" ? "LaunchAgent" : "user service"} is stopped and removed.\n ${backend.unitPath}\n\n Your data is untouched — it was never in there.\n` : `\n No Managers service was installed (${backend.unitPath}).\n Nothing to do.\n`, ); - // Leave the service directory: it holds logs, and the last thing anyone wants - // from `uninstall` is for the record of why they are uninstalling to vanish. + // Leave the service directory and the logs: the last thing anyone wants from + // `uninstall` is for the record of why they are uninstalling to vanish (and + // SPEC §1 requires it — `uninstall` keeps the data home and the logs). void ctx; + // 0 either way: "there was nothing to remove" is the state the caller asked + // for. `uninstall` is idempotent on purpose, so a teardown script can run it + // without first asking whether it has anything to do. + return EXIT.ok; +} + +/** + * The data dir the INSTALLED unit uses, read out of its own argument vector. + * + * Today's `--data-dir` flag is deliberately ignored (#824): every reporting + * surface here describes the unit on disk, and letting a flag through printed + * the unit's data dir beside a log path under a directory the service never + * writes to. `--data-dir` is documented as install-only (SERVICE_USAGE). + */ +function dataDirOf(state: ServiceState, ctx: ServiceContext): string { + const i = state.argv.indexOf("--data-dir"); + return i >= 0 && state.argv[i + 1] !== undefined + ? state.argv[i + 1] + : defaultDataDir(ctx.homeDir); +} + +/** The URL the installed unit serves, read back out of the unit. */ +function urlOf(state: ServiceState): string { + return `http://${hostFromArgv(state.argv)}:${portFromArgv(state.argv)}`; +} + +/** + * The log file to read: the one the unit names, else where we would write it. + * + * A unit written before the logs moved to `/logs/service.log` names + * the old `/service/managers.log`, and that is the file its service is + * still appending to — so that is the file `logs` has to read. The fallback + * covers a unit we could not parse. + */ +function logPathOf(state: ServiceState, dataDir: string): string { + return state.logPath ?? serviceLogPath(dataDir); } -function status(opts: CliOptions, ctx: ServiceContext, backend: ServiceBackend): void { +/** + * The version of the Managers the unit points at. + * + * Found by walking up from the `cli.js` in the unit to the nearest + * `package.json`, which is `packages/server/package.json` in both the repo and + * the published tarball — the same hop the CLI itself makes to answer + * `--version`. Undefined when the unit names a path that is no longer there, + * which is a state `status` reports rather than guesses around. + */ +export function installedVersionOf(cliPath: string | undefined): string | undefined { + if (cliPath === undefined) return undefined; + let dir = path.dirname(cliPath); + for (;;) { + const manifest = path.join(dir, "package.json"); + if (fs.existsSync(manifest)) { + try { + const raw = JSON.parse(fs.readFileSync(manifest, "utf8")) as { version?: string }; + return raw.version; + } catch { + return undefined; + } + } + const parent = path.dirname(dir); + if (parent === dir) return undefined; + dir = parent; + } +} + +/** + * What `service status` knows, before it is either printed or serialised. + * + * One shape for both renderings, so `--json` cannot quietly disagree with the + * prose above it — which is the usual way a `--json` flag rots. + */ +export interface StatusReport { + installed: boolean; + running: boolean; + /** Did `/api/health` answer? Only then is the service actually usable. */ + answering: boolean; + /** The version the unit points at, and the version that answered. */ + installedVersion: string | null; + runningVersion: string | null; + port: number | null; + host: string | null; + url: string | null; + pid: number | null; + /** The Managers arguments the unit records, interpreter and script stripped. */ + args: string[]; + /** The plist / unit file — present whether or not it exists. */ + unit: string; + manager: "launchd" | "systemd"; + /** The one file both streams append to. */ + log: string | null; + dataDir: string | null; + node: string | null; + cli: string | null; + /** Linux only: null where the platform has no such concept. */ + linger: boolean | null; + /** A stale unit, a missing Node — things that are wrong but not fatal. */ + warnings: string[]; +} + +async function buildStatus(ctx: ServiceContext, backend: ServiceBackend): Promise { const state = backend.status(); + const base = { + installed: state.registered, + args: state.argv, + manager: backend.platform === "darwin" ? ("launchd" as const) : ("systemd" as const), + unit: backend.unitPath, + }; + const linger = backend.linger(); + const lingerValue = linger.applies ? (linger.enabled ?? null) : null; + if (!state.registered) { + return { + ...base, + running: false, + answering: false, + installedVersion: null, + runningVersion: null, + port: null, + host: null, + url: null, + pid: null, + log: null, + dataDir: null, + node: null, + cli: null, + linger: lingerValue, + warnings: [], + }; + } + + const dataDir = dataDirOf(state, ctx); + const url = urlOf(state); + const health = await (ctx.probeHealth ?? ((u: string) => fetchHealth(u)))(url); + const installedVersion = installedVersionOf(state.cliPath); + + const warnings: string[] = []; + if (!state.keepsAlive) warnings.push(staleUnitWarning(backend)); + for (const gone of missingPaths([state.nodePath, state.cliPath])) { + warnings.push( + `The unit runs ${gone}, which is not there any more. ` + + "That happens when a Node version is removed (nvm, fnm, volta) or the " + + "package is reinstalled elsewhere. Re-run `managers service install`.", + ); + } + if ( + installedVersion !== undefined && + health?.version !== undefined && + installedVersion !== health.version + ) { + warnings.push( + `It is running ${health.version}, but ${installedVersion} is installed. ` + + "The package was upgraded under a service that has not restarted: " + + "`managers service restart`.", + ); + } + if (linger.applies && linger.enabled === false) { + warnings.push( + "Lingering is off, so this service stops when you log out — including out " + + `of an SSH session. To keep it up: sudo loginctl enable-linger ${linger.user ?? "$USER"}`, + ); + } + + return { + ...base, + running: state.running, + answering: health?.ok === true, + installedVersion: installedVersion ?? null, + runningVersion: health?.version ?? null, + port: Number(portFromArgv(state.argv)), + host: hostFromArgv(state.argv), + url, + pid: state.pid !== undefined ? Number(state.pid) : null, + log: logPathOf(state, dataDir), + dataDir, + node: state.nodePath ?? null, + cli: state.cliPath ?? null, + linger: lingerValue, + warnings, + }; +} + +/** + * `status` (SPEC §1, §2). + * + * The exit code is the headline and the reason this command is worth scripting: + * + * - **4** — no unit. Nothing to start, nothing to ask. + * - **3** — installed, but not running or not answering. "Not answering" + * counts, because a supervisor reports a crash-looping job as `running` for + * most of the window between restarts, and a service nothing can reach is not + * up whatever the supervisor thinks. + * - **0** — installed, running and answering. + * + * Those are the numbers `systemctl status` and LSB init scripts already use, so + * an Ansible task or a shell `if` written against either keeps working. + */ +async function status( + opts: CliOptions, + ctx: ServiceContext, + backend: ServiceBackend, +): Promise { + const report = await buildStatus(ctx, backend); + + if (opts.json === true) { + // Exactly one JSON document on stdout, and nothing else (SPEC §1). Every + // other line this command can print goes to stderr under --json or is not + // printed at all. + console.log(JSON.stringify(report, null, 2)); + return statusExit(report); + } + + if (!report.installed) { console.log( [ "", " Managers is not installed as a service.", - ` Looked for: ${backend.unitPath}`, + ` Looked for: ${report.unit}`, "", " managers service install register it and start it now", "", ].join("\n"), ); - return; + return EXIT.notInstalled; } - // Everything below is read back out of the INSTALLED unit, not recomputed - // from today's flags — the installed port is the one the URL has to name. - const url = `http://${hostFromArgv(state.argv)}:${portFromArgv(state.argv)}`; - const dataFromUnit = state.argv.indexOf("--data-dir"); - const dataDir = - dataFromUnit >= 0 && state.argv[dataFromUnit + 1] !== undefined - ? state.argv[dataFromUnit + 1] - : defaultDataDir(ctx.homeDir); - // Drop `--data-dir` before building the log-path spec (#824). `resolveDataDir` - // gives `opts.dataDir` precedence over `ctx.envDataDir`, which is right for - // `install` (see the comment there) and wrong here: this whole block reports - // the INSTALLED unit, so letting today's flag through printed the unit's data - // dir beside a `Logs:` path under a directory the service never writes to. On - // macOS that log path is real and load-bearing, not just cosmetic. - // - // `--data-dir` is documented as install-only (SERVICE_USAGE), so ignoring it - // here matches both the help text and the stated intent of this block. - const statusOpts: CliOptions = { ...opts }; - delete statusOpts.dataDir; - const { spec } = specFor(statusOpts, { ...ctx, envDataDir: dataDir }); - const linger = backend.lingerNote(); + const versions = + report.runningVersion !== null && report.runningVersion !== report.installedVersion + ? ` Version: ${report.runningVersion} running, ${report.installedVersion ?? "unknown"} installed` + : ` Version: ${report.runningVersion ?? report.installedVersion ?? "unknown"}`; console.log( [ "", - state.running - ? ` Managers is running${state.pid !== undefined ? ` (pid ${state.pid})` : ""}.` - : " Managers is registered as a service, but not running right now.", + report.running + ? report.answering + ? ` Managers is running${report.pid !== null ? ` (pid ${String(report.pid)})` : ""} and answering.` + : ` Managers is running${report.pid !== null ? ` (pid ${String(report.pid)})` : ""}, but ${report.url ?? "its URL"} is not answering.` + : report.answering + ? // Found in QA, and worth its own line: the supervisor does not have + // the job, yet something IS serving that URL — usually a `managers + // serve` in a terminal on the same port. "Not running" on its own + // reads as "nothing there", and then `service start` fails on a + // port clash for reasons the status screen had the answer to. + ` The service is not running, but something IS answering at ${report.url ?? "its URL"}\n` + + " — most likely a `managers serve` in a terminal. The service cannot take\n" + + " that port while it is held." + : " Managers is registered as a service, but not running right now.", "", - ` URL: ${url}`, - ` Data: ${dataDir}`, - ` Unit: ${backend.unitPath}`, - ` Args: managers ${state.argv.join(" ")}`, - backend.logsHint(spec), + ` URL: ${report.url ?? "unknown"}`, + versions, + ` Data: ${report.dataDir ?? "unknown"}`, + ` Unit: ${report.unit}`, + ` Args: managers ${report.args.join(" ")}`, + ` Logs: ${report.log ?? "unknown"} (managers service logs -f)`, "", AT_LOGIN, - ...(state.keepsAlive ? [] : ["", staleUnitNote(backend)]), - ...(linger !== undefined && !state.running ? ["", linger] : []), + ...report.warnings.flatMap((w) => ["", ` ⚠ ${w}`]), "", ].join("\n"), ); + return statusExit(report); +} + +/** The exit code a report means (SPEC §2). */ +function statusExit(report: StatusReport): number { + if (!report.installed) return EXIT.notInstalled; + if (!report.running || !report.answering) return EXIT.notRunning; + return EXIT.ok; } /** @@ -338,17 +583,17 @@ async function startOrRestart( action: "start" | "restart", ctx: ServiceContext, backend: ServiceBackend, -): Promise { +): Promise { const before = backend.status(); if (!before.registered) { console.log(notInstalled(backend)); - return; + return EXIT.notInstalled; } const url = installedUrl(before); if (action === "start" && before.running) { console.log(`\n Managers is already running${pid(before)}.\n\n URL: ${url}\n`); - return; + return EXIT.ok; } console.log(`\n ${action === "start" ? "Starting" : "Restarting"} Managers…`); @@ -364,22 +609,31 @@ async function startOrRestart( ? ` ✓ Managers is running${pid(after)} at ${url}` : ` Managers was ${action === "start" ? "started" : "restarted"}, but ${url} did not\n` + ` answer within ${READY_TIMEOUT_LABEL}. It may still be coming up — check:`, - ...(readiness === "ready" ? [] : ["", " managers service status", backend.logsHint(specForLogs(ctx, after))]), + ...(readiness === "ready" + ? [] + : [ + "", + " managers service status", + ` managers service logs (${logPathOf(after, dataDirOf(after, ctx))})`, + ]), "", ].join("\n"), ); + // A start that never answered is a failure, not a success with a caveat: the + // caller — often an Ansible task — has no other way to find out. + return readiness === "ready" ? EXIT.ok : EXIT.failure; } /** `stop` (#873): put it down, leave it installed. */ -function stop(backend: ServiceBackend): void { +function stop(backend: ServiceBackend): number { const state = backend.status(); if (!state.registered) { console.log(notInstalled(backend)); - return; + return EXIT.notInstalled; } if (!state.running) { console.log(`\n Managers is already stopped.\n Unit: ${backend.unitPath}\n`); - return; + return EXIT.ok; } backend.stop(); @@ -395,33 +649,74 @@ function stop(backend: ServiceBackend): void { "", ].join("\n"), ); + return EXIT.ok; } function pid(state: ServiceState): string { return state.pid !== undefined ? ` (pid ${state.pid})` : ""; } -/** The spec `logsHint` needs, built from the INSTALLED unit's data dir. */ -function specForLogs(ctx: ServiceContext, state: ServiceState): ServiceSpec { - const i = state.argv.indexOf("--data-dir"); - const dataDir = i >= 0 && state.argv[i + 1] !== undefined ? state.argv[i + 1] : undefined; - const { spec } = specFor( - { open: false, verbose: false, help: false, version: false }, - { ...ctx, ...(dataDir !== undefined ? { envDataDir: dataDir } : {}) }, - ); - return spec; +/** + * `logs [-f] [-n ]` (SPEC §1, §7). + * + * Reads the file the INSTALLED unit names, which is the only file its service + * is actually appending to — a unit written before the logs moved still names + * the old path, and sending its owner to a file nothing writes to would be + * worse than sending them nowhere. + * + * Exit 4 with no unit, like every other command that needs one. A unit whose + * log file does not exist yet is NOT an error: a service installed thirty + * seconds ago and still booting has nothing to show, and that is worth saying + * rather than failing over. + */ +async function logs( + opts: CliOptions, + ctx: ServiceContext, + backend: ServiceBackend, +): Promise { + const state = backend.status(); + if (!state.registered) { + console.log(notInstalled(backend)); + return EXIT.notInstalled; + } + + const file = logPathOf(state, dataDirOf(state, ctx)); + const lines = opts.lines ?? DEFAULT_LOG_LINES; + + if (!fs.existsSync(file)) { + // stderr: with `-f` this is a caveat ahead of a stream, and prose on stdout + // would be mixed into the log output itself. + console.error(`managers: nothing has been written to ${file} yet.`); + if (opts.follow !== true) return EXIT.ok; + } else { + const tail = tailFile(file, lines); + if (tail !== "") console.log(tail); + } + + if (opts.follow === true) { + console.error(`managers: following ${file} — Ctrl-C to stop.`); + await followFile(file, { from: sizeOf(file) }); + } + return EXIT.ok; } +/** + * Dispatch, returning the exit code rather than setting one (SPEC §2). + * + * The code is returned up to `managers.ts`, which assigns `process.exitCode` — + * never `process.exit()`, which truncates piped output mid-write. + */ export async function runService( action: ServiceAction, opts: CliOptions, ctx: ServiceContext, -): Promise { +): Promise { const backend = backendFor(ctx); if (action === "install") return install(opts, ctx, backend); if (action === "uninstall") return uninstall(ctx, backend); if (action === "start" || action === "restart") return startOrRestart(action, ctx, backend); if (action === "stop") return stop(backend); + if (action === "logs") return logs(opts, ctx, backend); return status(opts, ctx, backend); } diff --git a/packages/server/src/cli/service/launchd.ts b/packages/server/src/cli/service/launchd.ts index 3c910134..bb7859ad 100644 --- a/packages/server/src/cli/service/launchd.ts +++ b/packages/server/src/cli/service/launchd.ts @@ -37,7 +37,7 @@ import fs from "node:fs"; import os from "node:os"; import path from "node:path"; import { LAUNCHD_LABEL, type ServiceSpec } from "./spec.js"; -import type { Runner, ServiceBackend, ServiceState } from "./backend.js"; +import type { LingerState, Runner, ServiceBackend, ServiceState } from "./backend.js"; /** `~/Library/LaunchAgents/net.edspencer.managers.plist`. */ export function plistPath(homeDir: string = os.homedir()): string { @@ -81,6 +81,12 @@ function xmlEscape(s: string): string { * * No `MANAGERS_DATA_DIR`: see `buildSpec`. One `~/.managers` instance, reachable * from the service and from a terminal. + * + * `StandardOutPath` and `StandardErrorPath` name the SAME file (SPEC §7). + * launchd opens both in append mode, so interleaving is what a reader wants + * anyway — a warning and the stack trace that followed it used to land in two + * separate files, in an order nothing recorded. One file is also what makes + * `managers service logs` one implementation across platforms. */ export function renderPlist(spec: ServiceSpec): string { const argv = [spec.nodePath, spec.scriptPath, ...spec.args]; @@ -104,9 +110,9 @@ ${strings} WorkingDirectory ${xmlEscape(spec.workingDirectory)} StandardOutPath - ${xmlEscape(spec.stdoutPath)} + ${xmlEscape(spec.logPath)} StandardErrorPath - ${xmlEscape(spec.stderrPath)} + ${xmlEscape(spec.logPath)} EnvironmentVariables PATH @@ -153,6 +159,17 @@ export function plistKeepsAlive(xml: string): boolean { return /KeepAlive<\/key>\s*/.test(xml); } +/** The log file an installed plist appends to, read back from `StandardOutPath`. */ +export function parsePlistLogPath(xml: string): string | undefined { + const m = /StandardOutPath<\/key>\s*([\s\S]*?)<\/string>/.exec(xml); + if (m === null) return undefined; + return m[1] + .replace(/"/g, '"') + .replace(/>/g, ">") + .replace(/</g, "<") + .replace(/&/g, "&"); +} + /** * Read liveness out of `launchctl print gui//