diff --git a/.changeset/cli-contract-shoulds.md b/.changeset/cli-contract-shoulds.md new file mode 100644 index 00000000..36f92f61 --- /dev/null +++ b/.changeset/cli-contract-shoulds.md @@ -0,0 +1,14 @@ +--- +"@paddock/server": minor +--- + +**The CLI contract's remaining `service` and `serve` options (SPEC §1, §3).** What a script can see: + +- **`paddock service install --dry-run`** prints the unit it would write (the systemd unit or the launchd plist) on stdout, says where it would go on stderr, and writes nothing — not the unit, not a folder. It works with `--refresh` too, and with `--json` (`{ ok, action, dryRun, unit, contents }`). +- **`service install` refuses to run from a git checkout** (or an `npm link`), exit **1**, unless you add **`--from-checkout`**: a unit that runs a working tree follows every rebuild, branch switch and move of it. A global install is unaffected. +- **`service install` refuses a port something else holds**, exit **1**, rather than writing a service that can only crash-loop. A Paddock on the port (a reinstall) is fine, and so is the unit's own running service. +- **`--json` on `service install`, `uninstall`, `start`, `stop` and `restart`**: one document on stdout, `{ ok, action, error?, …the service's status afterwards }` (the same fields as `service status --json`), with every word of prose on stderr. The exit codes don't change; `error` is `busy` for a 75 and `not installed` for a 4. +- **Running `service install` again keeps the installed unit's settings** — its port, host, data dir and verbosity — unless a flag says otherwise (SPEC §1). It used to do that only with `--refresh`, so a plain reinstall over a `--port 9000` service moved it to 7233. +- **`paddock serve --quiet` (`-q`)** prints only the first line, `Paddock : `. +- **Flags belong to their commands:** `--dry-run` and `--from-checkout` (`service install` only), `--quiet` (`serve` only) and **`--json` on a command that has no JSON document — `serve`, `service logs`, `config eject` — now exit 2**. They used to be accepted and ignored. +- A first `service install` that systemd or launchd refuses no longer leaves its unit behind (re-synced with cli-contract's `reference/service/`); a reinstall that fails keeps the unit that was there. diff --git a/packages/server/src/cli/args.ts b/packages/server/src/cli/args.ts index bf177798..b025c335 100644 --- a/packages/server/src/cli/args.ts +++ b/packages/server/src/cli/args.ts @@ -120,6 +120,20 @@ export interface CliOptions { * (SPEC §1). Every other check is local. */ offline?: boolean; + /** + * `service install --dry-run`: print the unit it would write, and write + * nothing — not the unit, not a folder (SPEC §1). + */ + dryRun?: boolean; + /** + * `service install --from-checkout`: install a unit that runs THIS copy even + * though it is a git checkout (SPEC §1). Without it, `install` refuses: a unit + * pointing into a working tree breaks the next time it is rebuilt, switched + * to another branch or moved. + */ + fromCheckout?: boolean; + /** `serve --quiet` / `-q`: print the `Paddock : ` line and nothing else (SPEC §3). */ + quiet?: boolean; } /** @@ -324,6 +338,41 @@ const SCOPED_FLAGS: readonly { where: ["update"], why: "`update` is the only command that asks a question.", }, + { + flag: "--json", + read: (o) => o.json === true, + where: [ + "service status", + "service install", + "service uninstall", + "service start", + "service stop", + "service restart", + "busy", + "update", + "doctor", + "config show", + ], + why: "It prints one JSON document on stdout, and those are the commands that have one.", + }, + { + flag: "--dry-run", + read: (o) => o.dryRun === true, + where: ["service install"], + why: "It prints the unit `install` would write, and writes nothing.", + }, + { + flag: "--from-checkout", + read: (o) => o.fromCheckout === true, + where: ["service install"], + why: "It lets `install` write a unit that runs a git checkout.", + }, + { + flag: "--quiet", + read: (o) => o.quiet === true, + where: ["serve"], + why: "It keeps `serve` to its one `Paddock : ` line.", + }, { flag: "--offline", read: (o) => o.offline === true, @@ -478,6 +527,18 @@ export function parseArgs(argv: string[]): CliOptions { case "--refresh": opts.refresh = true; break; + // `service install` (SPEC §1). + case "--dry-run": + opts.dryRun = true; + break; + case "--from-checkout": + opts.fromCheckout = true; + break; + // `serve --quiet` (SPEC §3). + case "-q": + case "--quiet": + opts.quiet = true; + break; // `doctor --offline` (SPEC §1). case "--offline": opts.offline = true; @@ -577,6 +638,7 @@ Usage paddock serve [options] the same thing, said out loud (\`paddock start\` is a permanent alias) paddock service install [options] run it in the background from login + (--dry-run prints the unit instead) paddock service uninstall stop it and remove the unit paddock service status [--json] installed? running? which version? paddock service start start an installed service @@ -604,6 +666,7 @@ Options --host Bind address (default 127.0.0.1) -d, --data-dir Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR) -o, --open Open the app in your browser once it is listening + -q, --quiet Print only the first line, \`Paddock : \` --verbose Show the server's own logs (quiet by default) -v, --version Print the Paddock version and exit -h, --help Show this help @@ -723,6 +786,7 @@ export const SERVICE_USAGE = `paddock service — keep Paddock running in the ba Usage paddock service install [options] register it and start it now paddock service install --refresh re-write the unit, keeping its settings + paddock service install --dry-run print the unit it would write; write nothing paddock service uninstall stop it and deregister it paddock service status [--json] is it registered, is it running, which version, where are the logs @@ -738,10 +802,21 @@ Options (logs) Options (stop, restart) --force stop it even though it is busy +Options (install, uninstall, start, stop, restart, status) + --json One JSON document on stdout: ok, action, and the + service's status afterwards (the same fields as + \`status --json\`), plus error on a failure. All + prose goes to stderr. The exit code is unchanged + Options (install) + --dry-run Print the unit (and where it would go) and write + nothing — not the unit, not a folder + --from-checkout Install from a git checkout anyway. Without it, + install refuses: a unit that runs a working tree + breaks when you rebuild, switch branch or move it --refresh Re-render the unit from the settings the EXISTING one carries — its port, host, data dir and verbosity — - rather than from this shell's flags and environment. + and never from PADDOCK_DATA_DIR in this shell. This is what \`paddock update\` runs, through the new version's CLI, so the unit is written in the format that version writes. Exit 4 with nothing installed: @@ -749,6 +824,10 @@ Options (install) install with defaults instead is how a --port 9000 service comes back on 7233. + Running install again is safe: it keeps the port, host, data dir and + verbosity the installed unit records, unless you give new ones, and + restarts the running service onto the new unit. + Busy \`stop\` and \`restart\` ask the running instance whether it is busy first, and refuse with exit 75 if it is — a chat turn in flight, a background task, a @@ -799,20 +878,26 @@ Where it lives itself at 8 MB, keeping three older generations beside it. Exit codes - 0 it is installed, running and answering + 0 it is installed, running and answering (status), or done 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 75 busy, and --force was not given (stop, restart) -Installed from npx? +Installed from npx, or running from a checkout? \`service install\` refuses. An npx cache path is hash-keyed and npm may prune it, so the unit would work until it silently didn't, at some future login. - Install properly first: + A checkout is yours to rebuild, switch and move, and the unit would follow + it. Install properly first: npm i -g @edspencer/paddock && paddock service install + (--from-checkout installs from the checkout anyway, for working on Paddock.) + + It also refuses when something that isn't Paddock holds the port: pick + another with --port. + A note on access Paddock binds loopback with authentication off, which is right for a laptop. A service is up for as long as you are logged in rather than as long as a diff --git a/packages/server/src/cli/doctor.ts b/packages/server/src/cli/doctor.ts index c22a46f6..82732ab2 100644 --- a/packages/server/src/cli/doctor.ts +++ b/packages/server/src/cli/doctor.ts @@ -22,7 +22,6 @@ * two cannot disagree about what is installed and what is running. */ import fs from "node:fs"; -import net from "node:net"; import os from "node:os"; import path from "node:path"; import { MIN_NODE_MAJOR, type CliOptions } from "./args.js"; @@ -36,7 +35,7 @@ import { import { defaultDataDir, DEFAULT_PORT } from "./service/spec.js"; import { missingPaths, which } from "./service/path-env.js"; import type { LingerState, ServiceManager } from "./service/manager.js"; -import { fetchHealth } from "./service/ready.js"; +import { identifyPaddock as identify, isListening } from "./service/ready.js"; import { describeInstall, detectInstall, updateCommand, type InstallInfo } from "./update/install-method.js"; import { npmConfigGet, npmGlobalRoot } from "./update/package-manager.js"; import { RegistryError, resolveRegistry, resolveTarget } from "./update/registry.js"; @@ -659,36 +658,3 @@ function urlHost(host: string): string { function firstLine(s: string): string { return s.split("\n")[0] ?? s; } - -function isListening(host: string, port: number): Promise { - return new Promise((resolve) => { - const s = net.connect({ host, port }); - s.setTimeout(1000); - s.once("connect", () => { - s.destroy(); - resolve(true); - }); - s.once("timeout", () => { - s.destroy(); - resolve(false); - }); - s.once("error", () => resolve(false)); - }); -} - -/** - * Is this a Paddock? `/api/health`'s `{ ok, version }` is the contract's, so - * every tool answers it; `/api/busy`'s `counts.chat` is Paddock's own. - */ -async function identify(url: string): Promise<{ paddock: boolean; version?: string } | undefined> { - const health = await fetchHealth(url); - if (health === undefined) return undefined; - try { - const res = await fetch(`${url}/api/busy`, { signal: AbortSignal.timeout(2_000) }); - const body = (await res.json()) as { counts?: Record }; - const paddock = health.ok && typeof body.counts?.chat === "number" && "background" in (body.counts ?? {}); - return { paddock, ...(health.version !== undefined ? { version: health.version } : {}) }; - } catch { - return { paddock: false, ...(health.version !== undefined ? { version: health.version } : {}) }; - } -} diff --git a/packages/server/src/cli/paddock.ts b/packages/server/src/cli/paddock.ts index ff769d62..7037af6a 100644 --- a/packages/server/src/cli/paddock.ts +++ b/packages/server/src/cli/paddock.ts @@ -391,7 +391,9 @@ async function main(): Promise { // Precedence is explicit flag > existing env > our default. const dataDir = resolveDataDir(opts); - noteFirstRun(dataDir); + // `--quiet` (SPEC §3): the banner line and nothing else, so not the + // first-run note either (it is prose on stderr, but prose all the same). + if (opts.quiet !== true) noteFirstRun(dataDir); process.env.PADDOCK_DATA_DIR = dataDir; @@ -445,6 +447,10 @@ async function main(): Promise { // runner, and by anything that wants the URL without guessing the port — so // the friendly block below it stays, but below it. console.log(`${PADDOCK_NAME} ${PADDOCK_VERSION}: ${url}`); + if (opts.quiet === true) { + if (opts.open) openBrowser(url); + return EXIT.OK; + } // 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 diff --git a/packages/server/src/cli/service/index.ts b/packages/server/src/cli/service/index.ts index 2489878b..7bb71920 100644 --- a/packages/server/src/cli/service/index.ts +++ b/packages/server/src/cli/service/index.ts @@ -46,8 +46,9 @@ import { type ServiceSpec, type ServiceState, } from "./manager.js"; -import { createLaunchd } from "./launchd.js"; -import { createSystemd } from "./systemd.js"; +import { createLaunchd, renderPlist } from "./launchd.js"; +import { createSystemd, renderUnit } from "./systemd.js"; +import { underNodeModules } from "../update/install-method.js"; import { missingPaths } from "./path-env.js"; import { DEFAULT_LOG_LINES, followFile, sizeOf, tailFile } from "./logs.js"; import { readLiveRuntimeFile } from "../../runtime-file.js"; @@ -56,6 +57,8 @@ import { updateSummary, type UpdateSummary } from "../update/update-check.js"; import { waitForReady, fetchHealth, + identifyPaddock, + isListening, READY_TIMEOUT_LABEL, type HealthAnswer, type Readiness, @@ -103,6 +106,41 @@ export interface ServiceContext { home: string, opts: { force?: boolean; json?: boolean }, ) => Promise; + /** + * Who holds `host:port` — nothing, a Paddock, or something else — asked by + * `install` before it writes a unit (SPEC §1). Injected so a test's answer + * does not depend on what happens to be listening on the box running it. + */ + portOwner?: (host: string, port: number) => Promise; +} + +export type PortOwner = "free" | "paddock" | "other"; + +/** The real {@link ServiceContext.portOwner}: a TCP connect, then `/api/health` and `/api/busy`. */ +export async function portOwner(host: string, port: number): Promise { + const probe = host === "0.0.0.0" || host === "" ? "127.0.0.1" : host === "::" ? "::1" : host; + if (!(await isListening(probe, port))) return "free"; + const who = await identifyPaddock(`http://${probe.includes(":") ? `[${probe}]` : probe}:${port}`); + return who?.paddock === true ? "paddock" : "other"; +} + +/** + * Why `install` won't write a unit that runs a checkout (SPEC §1, §6). + * + * A checkout (or an `npm link`) is a working tree: it gets rebuilt, switched to + * another branch, cleaned and moved, and a unit that runs it follows every one + * of those — half-built `dist/` included — at the next login, unattended. The + * flag is there for working on Paddock itself, where that is the point. + */ +export function checkoutRefusal(packageRoot: string): string { + return ( + `this copy of Paddock is a checkout (${packageRoot}), so \`service install\` won't use it.\n` + + " A unit that runs a checkout follows every rebuild, branch switch and move of\n" + + " it, at your next login, unattended. Install it properly first:\n\n" + + " npm i -g @edspencer/paddock && paddock service install\n\n" + + " Or run this checkout as the service anyway (when working on Paddock):\n" + + " paddock service install --from-checkout\n" + ); } /** @@ -284,6 +322,12 @@ async function install( backend: ServiceBackend, ): Promise { if (isNpxPath(ctx.packageRoot)) throw new CliError(NPX_REFUSAL); + // A checkout is a package root that isn't under any `node_modules` (SPEC §6): + // `packages/server` in the repo, `/lib/node_modules/@edspencer/paddock/ + // packages/server` from npm. `npm link` reads the same, on purpose. + if (!underNodeModules(ctx.packageRoot) && opts.fromCheckout !== true) { + throw new CliError(checkoutRefusal(ctx.packageRoot)); + } // `--refresh` (SPEC §5 step 11): re-render an EXISTING unit, keeping what it // records. With nothing installed there is nothing to refresh — exit 4, the @@ -293,11 +337,22 @@ async function install( // CLI, and a silent fallback would move a `--port 9000` service to 7233 on // the one run nobody is watching. const refreshing = opts.refresh === true; - let existing: ServiceState | undefined; + // A reinstall keeps what the installed unit records — its port, host, data + // dir and verbosity — unless a flag says otherwise (SPEC §1). It used to do + // that only with `--refresh`, so `service install` over a `--port 9000` + // service quietly moved it to 7233. `--refresh` still differs in two ways: + // it ignores `PADDOCK_DATA_DIR` in this shell, and with no unit it exits 4. + const current = backend.status(); + const existing: ServiceState | undefined = current.registered ? current : undefined; if (refreshing) { - existing = backend.status(); - if (!existing.registered) { - console.log(notInstalled(backend)); + if (existing === undefined) { + if (opts.dryRun === true && opts.json === true) { + // `--dry-run --json` prints its own document (runService leaves it be). + console.error(notInstalled(backend)); + console.log(JSON.stringify({ ok: false, action: "install", dryRun: true, error: "not installed", unit: backend.unitPath }, null, 2)); + } else { + console.log(notInstalled(backend)); + } return EXIT.NOT_INSTALLED; } } @@ -309,7 +364,41 @@ async function install( ); const url = `http://${hostFromArgv(spec.args)}:${portFromArgv(spec.args)}`; - if (refreshing) { + // `--dry-run` (SPEC §1): the unit, on stdout, and nothing written — not the + // unit, not the service or log folders `backend.install` would make. The + // where-it-would-go line is on stderr, so `> paddock.service` captures the + // unit alone. + if (opts.dryRun === true) { + const contents = + backend.platform === "darwin" ? renderPlist(PADDOCK_SERVICE, spec) : renderUnit(PADDOCK_SERVICE, spec); + if (opts.json === true) { + console.log( + JSON.stringify({ ok: true, action: "install", dryRun: true, unit: backend.unitPath, contents }, null, 2), + ); + } else { + console.error(`paddock: dry run: this is the unit \`service install\` would write to ${backend.unitPath}. Nothing was written.`); + console.log(contents.trimEnd()); + } + return EXIT.OK; + } + + // Refuse a port something else holds (SPEC §1): the service would start, + // fail to bind, and restart every ten seconds, for good. A Paddock holding it + // is fine — that's the reinstall this replaces — and so is the unit's own + // running service when it's too old to say it's Paddock (before 0.81). + const port = Number(portFromArgv(spec.args)); + const owner = await (ctx.portOwner ?? portOwner)(hostFromArgv(spec.args), port); + if (owner === "other") { + const itsOwn = current.registered && current.running && portFromArgv(current.argv) === String(port); + if (!itsOwn) { + throw new CliError( + `port ${port} is held by something that isn't Paddock, so the service could not start.\n` + + ` Stop it, or pick another port: paddock service install --port ${port + 1}`, + ); + } + } + + if (existing !== undefined) { console.log( `\n Re-writing ${backend.unitPath}\n Keeping: paddock ${spec.args.join(" ")}`, ); @@ -916,6 +1005,69 @@ export async function runService( // `--force` is rejected on every action but `stop` and `restart` — in // `parseCommand`, once, for every verb. See the note there. const backend = backendFor(ctx); + // `--json` on the actions that change something (SPEC §1): their prose goes + // to stderr, and stdout gets one document — what was done, and the status + // afterwards. `status` has its own; `--dry-run` prints its own. + if (opts.json === true && action !== "status" && action !== "logs" && opts.dryRun !== true) { + return withJson(action, () => act(action, opts, ctx, backend), ctx, backend); + } + return act(action, opts, ctx, backend); +} + +/** + * Run `act` with its prose on stderr, then print `{ ok, action, error?, + * ...status }` on stdout (SPEC §1, §3) — the shape Hallway's `service … --json` + * prints, and `status --json`'s fields after `ok` and `action`, so a script + * reads one shape whatever it asked. + * + * Every line in this file goes through `console.log`, so the prose is moved by + * pointing that at stderr for the duration, rather than by threading a writer + * through every function. A failure still prints its document, and is then + * re-thrown, so `paddock: ` and the exit code are what they are + * without `--json`. + */ +async function withJson( + action: ServiceAction, + run: () => Promise, + ctx: ServiceContext, + backend: ServiceBackend, +): Promise { + const log = console.log; + console.log = (...a: unknown[]) => console.error(...a); + let code: number; + let failure: unknown; + try { + code = await run(); + } catch (err) { + failure = err; + code = err instanceof CliError ? err.exitCode : EXIT.FAILED; + } finally { + console.log = log; + } + const error = + failure !== undefined + ? (failure instanceof Error ? failure.message : String(failure)).split("\n")[0] + : code === EXIT.BUSY + ? "busy" + : code === EXIT.NOT_INSTALLED + ? "not installed" + : code !== EXIT.OK + ? "failed" + : undefined; + const report = await buildStatus(ctx, backend); + console.log( + JSON.stringify({ ok: code === EXIT.OK, action, ...(error !== undefined ? { error } : {}), ...report }, null, 2), + ); + if (failure !== undefined) throw failure; + return code; +} + +async function act( + action: ServiceAction, + opts: CliOptions, + ctx: ServiceContext, + backend: ServiceBackend, +): Promise { if (action === "install") return install(opts, ctx, backend); if (action === "uninstall") return uninstall(ctx, backend); if (action === "start" || action === "restart") return startOrRestart(action, opts, ctx, backend); diff --git a/packages/server/src/cli/service/launchd.ts b/packages/server/src/cli/service/launchd.ts index 2c41af77..bcbbd3fd 100644 --- a/packages/server/src/cli/service/launchd.ts +++ b/packages/server/src/cli/service/launchd.ts @@ -154,6 +154,7 @@ export function createLaunchd(id: ServiceIdentity, o: LaunchdOptions): ServiceMa kind: 'a launchd LaunchAgent', install(spec) { + const existed = fs.existsSync(file); fs.mkdirSync(path.dirname(file), { recursive: true }); fs.mkdirSync(spec.workingDirectory, { recursive: true }); // launchd doesn't create the log's folder; without it the job fails to spawn, and says nothing. @@ -161,7 +162,14 @@ export function createLaunchd(id: ServiceIdentity, o: LaunchdOptions): ServiceMa fs.writeFileSync(file, renderPlist(id, spec), 'utf8'); // A bootout first, because bootstrap refuses a label that's loaded. It fails on a first install, as expected. bootoutAndWait(); - bootstrap(); + try { + bootstrap(); + } catch (err) { + // A first install launchd refused mustn't leave a plist behind: `status` would then say it's installed, and + // the next login would try it again. A reinstall keeps its plist. + if (!existed) fs.rmSync(file, { force: true }); + throw err; + } run('launchctl', ['kickstart', '-k', target]); }, diff --git a/packages/server/src/cli/service/ready.ts b/packages/server/src/cli/service/ready.ts index 95a67295..3af98353 100644 --- a/packages/server/src/cli/service/ready.ts +++ b/packages/server/src/cli/service/ready.ts @@ -21,6 +21,7 @@ * same claim as "it failed". Callers print it as a caveat, not an error, and * point at the logs. */ +import net from "node:net"; /** Where the poll got to when it stopped. */ export type Readiness = "ready" | "timeout"; @@ -185,3 +186,47 @@ export async function waitForVersion(opts: ReadyOptions & { version: string }): await sleep(intervalMs); } } + +/** Is anything accepting connections at host:port? A second at most. */ +export function isListening(host: string, port: number): Promise { + return new Promise((resolve) => { + const s = net.connect({ host, port }); + s.setTimeout(1000); + s.once("connect", () => { + s.destroy(); + resolve(true); + }); + s.once("timeout", () => { + s.destroy(); + resolve(false); + }); + s.once("error", () => resolve(false)); + }); +} + +/** + * Is what answers at `url` a Paddock, and which version? Undefined when nothing + * answers `/api/health` there. + * + * `/api/health`'s `{ ok, version }` is the CLI contract's, so every one of the + * six tools answers it alike; `/api/busy`'s `counts.chat` and + * `counts.background` are Paddock's own. A Paddock older than 0.81 has no + * `/api/busy`, and reads as not-Paddock here — callers that can tell it apart + * some other way (an installed unit on that port) should. + */ +export async function identifyPaddock( + url: string, + fetchImpl: typeof fetch = fetch, +): Promise<{ paddock: boolean; version?: string } | undefined> { + const health = await fetchHealth(url, { fetchImpl }); + if (health === undefined) return undefined; + const version = health.version !== undefined ? { version: health.version } : {}; + try { + const res = await fetchImpl(`${url}/api/busy`, { signal: AbortSignal.timeout(2_000) }); + const body = (await res.json()) as { counts?: Record }; + const counts = body.counts ?? {}; + return { paddock: health.ok && typeof counts.chat === "number" && "background" in counts, ...version }; + } catch { + return { paddock: false, ...version }; + } +} diff --git a/packages/server/src/cli/service/systemd.ts b/packages/server/src/cli/service/systemd.ts index 52f368a5..fef3e371 100644 --- a/packages/server/src/cli/service/systemd.ts +++ b/packages/server/src/cli/service/systemd.ts @@ -126,14 +126,26 @@ export function createSystemd(id: ServiceIdentity, o: SystemdOptions): ServiceMa install(spec) { // Asked before the unit is overwritten, while it still describes what's running. - const wasActive = fs.existsSync(file) && isActive(); + const existed = fs.existsSync(file); + const wasActive = existed && isActive(); fs.mkdirSync(path.dirname(file), { recursive: true }); fs.mkdirSync(spec.workingDirectory, { recursive: true }); fs.mkdirSync(path.dirname(spec.logPath), { recursive: true }); fs.writeFileSync(file, renderUnit(id, spec), 'utf8'); // Without a reload the manager keeps serving its cached copy of the old unit. run('systemctl', ['--user', 'daemon-reload']); - systemctl('enable', '--now', id.unit); + try { + systemctl('enable', '--now', id.unit); + } catch (err) { + // A first install systemd refused (no systemd here, no user bus) mustn't leave a unit behind: `status` would + // then say it's installed. A reinstall keeps its unit, which is what's installed either way. + if (!existed) { + run('systemctl', ['--user', 'disable', id.unit]); + fs.rmSync(file, { force: true }); + run('systemctl', ['--user', 'daemon-reload']); + } + throw err; + } // `enable --now` doesn't touch a unit that's already active: a reinstall over a running service would leave the // old process serving and report success. That's the state `update`'s rollback refreshes in, while the failed // version is still up. So restart, but only then: on a stopped unit it would be two starts milliseconds apart, diff --git a/packages/server/src/runtime-file.ts b/packages/server/src/runtime-file.ts index a75a1e6d..53211593 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 Paddock's `` 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 @ 0.2; 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-shoulds.test.ts b/packages/server/test/unit/cli-service-shoulds.test.ts new file mode 100644 index 00000000..5fee9de8 --- /dev/null +++ b/packages/server/test/unit/cli-service-shoulds.test.ts @@ -0,0 +1,358 @@ +/** + * The CLI contract's §1/§3 "should"s, and the one "must" that came with them: + * `service install --dry-run`, the checkout refusal and `--from-checkout`, the + * refusal of a port something else holds, `--json` on the service actions that + * change something, `serve --quiet`, and the flags that belong to one command. + * + * Like cli-service.test.ts, every subprocess call goes through an injected + * Runner: what these prove is the flow and the output, not that a real systemd + * or launchd agrees (scripts/service-real.mjs does that on CI). + */ +import { describe, it, expect, beforeEach, afterEach } from "vitest"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { parseCommand, UsageError, type CliOptions } from "../../src/cli/args.js"; +import { CliError } from "../../src/cli/args.js"; +import { EXIT } from "../../src/cli/exit-codes.js"; +import { runService, type ServiceContext } from "../../src/cli/service/index.js"; +import { createLaunchd, plistPath } from "../../src/cli/service/launchd.js"; +import { createSystemd, unitPath } from "../../src/cli/service/systemd.js"; +import { buildSpec, PADDOCK_SERVICE } from "../../src/cli/service/spec.js"; +import type { Runner, RunResult } from "../../src/cli/service/manager.js"; + +const OPTS: CliOptions = { open: false, verbose: false, help: false, version: false }; +const GLOBAL = "/usr/local/lib/node_modules/@edspencer/paddock/packages/server"; +const CLI = `${GLOBAL}/dist/cli/paddock.js`; + +let home: string; +beforeEach(() => { + home = fs.mkdtempSync(path.join(os.tmpdir(), "paddock-shoulds-")); +}); +afterEach(() => { + fs.rmSync(home, { recursive: true, force: true }); +}); + +/** A runner that records, answers "active" to is-active when `active`, and says launchd has nothing loaded. */ +function recorder(o: { active?: boolean; fail?: (cmd: string, args: string[]) => boolean } = {}) { + const calls: string[][] = []; + const run: Runner = (cmd, args): RunResult => { + calls.push([cmd, ...args]); + if (o.fail?.(cmd, args) === true) return { status: 1, stdout: "", stderr: "refused" }; + if (cmd === "systemctl" && args.includes("is-active")) + return { status: o.active ? 0 : 3, stdout: o.active ? "active\n" : "inactive\n", stderr: "" }; + if (cmd === "launchctl" && args[0] === "print") return { status: 113, stdout: "", stderr: "Could not find service" }; + return { status: 0, stdout: "", stderr: "" }; + }; + return { run, calls }; +} + +function ctxFor(platform: "linux" | "darwin", run: Runner, over: Partial = {}): ServiceContext { + return { + platform, + nodePath: "/opt/node/bin/node", + scriptPath: CLI, + packageRoot: GLOBAL, + homeDir: home, + pathEnv: "/usr/bin:/bin", + run, + checkReady: async () => "ready", + probeHealth: async () => ({ ok: true, version: "0.82.1" }), + portOwner: async () => "free", + guardBusy: async () => null, + ...over, + }; +} + +/** Everything written to stdout and to stderr, through console.log and console.error, separately. */ +async function streams(body: () => Promise): Promise<{ out: string; err: string; value: unknown; thrown?: unknown }> { + const out: string[] = []; + const err: string[] = []; + const log = console.log; + const error = console.error; + console.log = (...a: unknown[]) => void out.push(a.map(String).join(" ")); + console.error = (...a: unknown[]) => void err.push(a.map(String).join(" ")); + let value: unknown; + let thrown: unknown; + try { + value = await body(); + } catch (e) { + thrown = e; + } finally { + console.log = log; + console.error = error; + } + return { out: out.join("\n"), err: err.join("\n"), value, ...(thrown !== undefined ? { thrown } : {}) }; +} + +const installed = (port = "7233") => + createSystemd(PADDOCK_SERVICE, { run: recorder().run, homeDir: home }).install( + buildSpec({ nodePath: "/opt/node/bin/node", scriptPath: CLI, dataDir: path.join(home, ".paddock"), port }), + ); + +describe("flags belong to their commands (SPEC §1)", () => { + it.each([ + [["service", "install", "--dry-run"]], + [["service", "install", "--from-checkout"]], + [["service", "install", "--dry-run", "--json"]], + [["serve", "--quiet"]], + [["serve", "-q"]], + [["-q"]], + ...["install", "uninstall", "start", "stop", "restart", "status"].map((a) => [["service", a, "--json"]]), + [["busy", "--json"]], + [["update", "--json"]], + [["doctor", "--json"]], + [["config", "show", "--json"]], + ])("accepted: %j", (argv) => { + expect(() => parseCommand(argv)).not.toThrow(); + }); + + it.each([ + [["service", "start", "--dry-run"], "--dry-run"], + [["update", "--dry-run"], "--dry-run"], + [["service", "status", "--from-checkout"], "--from-checkout"], + [["serve", "--from-checkout"], "--from-checkout"], + [["busy", "--quiet"], "--quiet"], + [["service", "install", "-q"], "--quiet"], + [["service", "logs", "--json"], "--json"], + [["serve", "--json"], "--json"], + [["--json"], "--json"], + [["config", "eject", "--json"], "--json"], + ])("refused with exit 2: %j", (argv, flag) => { + let err: unknown; + try { + parseCommand(argv); + } catch (e) { + err = e; + } + expect(err).toBeInstanceOf(UsageError); + expect((err as UsageError).exitCode).toBe(EXIT.USAGE); + expect((err as Error).message.startsWith(`${flag} applies to`)).toBe(true); + }); + + it("serve -q sets quiet", () => { + expect(parseCommand(["serve", "-q"]).opts.quiet).toBe(true); + }); +}); + +describe("service install --dry-run", () => { + it("prints the systemd unit on stdout, says where on stderr, and writes nothing at all", async () => { + const { run, calls } = recorder(); + const r = await streams(() => runService("install", { ...OPTS, dryRun: true, port: "7300" }, ctxFor("linux", run))); + expect(r.value).toBe(EXIT.OK); + expect(r.out).toMatch(/^\[Unit\]$/m); + expect(r.out).toContain("ExecStart=/opt/node/bin/node"); + expect(r.out).toContain("--port 7300"); + expect(r.err).toContain(unitPath(PADDOCK_SERVICE, home)); + expect(r.err).toContain("Nothing was written"); + // Not the unit, not the data dir, not the logs folder — nothing in the home at all. + expect(fs.readdirSync(home)).toEqual([]); + // And nothing asked of systemd. + expect(calls).toEqual([]); + }); + + it("prints the plist on macOS", async () => { + const r = await streams(() => runService("install", { ...OPTS, dryRun: true }, ctxFor("darwin", recorder().run))); + expect(r.out).toMatch(/^<\?xml/); + expect(r.out).toContain("net.edspencer.paddock"); + expect(fs.existsSync(plistPath(PADDOCK_SERVICE, home))).toBe(false); + }); + + it("with --refresh, prints the unit re-rendered from the installed one's settings", async () => { + installed("9123"); + const unit = unitPath(PADDOCK_SERVICE, home); + const before = fs.readFileSync(unit, "utf8"); + const mtime = fs.statSync(unit).mtimeMs; + const r = await streams(() => + runService("install", { ...OPTS, dryRun: true, refresh: true }, ctxFor("linux", recorder().run)), + ); + expect(r.out).toContain("--port 9123"); + expect(fs.readFileSync(unit, "utf8")).toBe(before); + expect(fs.statSync(unit).mtimeMs).toBe(mtime); + }); + + it("--json prints one document with the unit in it", async () => { + const r = await streams(() => + runService("install", { ...OPTS, dryRun: true, json: true }, ctxFor("linux", recorder().run)), + ); + const doc = JSON.parse(r.out) as Record; + expect(doc).toMatchObject({ ok: true, action: "install", dryRun: true, unit: unitPath(PADDOCK_SERVICE, home) }); + expect(String(doc.contents)).toMatch(/^\[Unit\]$/m); + expect(fs.readdirSync(home)).toEqual([]); + }); + + it("--refresh --json with nothing installed: 4, and still one document", async () => { + const r = await streams(() => + runService("install", { ...OPTS, dryRun: true, refresh: true, json: true }, ctxFor("linux", recorder().run)), + ); + expect(r.value).toBe(EXIT.NOT_INSTALLED); + expect(JSON.parse(r.out)).toMatchObject({ ok: false, error: "not installed" }); + }); +}); + +describe("service install refuses a checkout (SPEC §1, §6)", () => { + const CHECKOUT = "/home/ed/src/paddock/packages/server"; + + it("refuses with exit 1, names the way out, and writes nothing", async () => { + const { run, calls } = recorder(); + const r = await streams(() => runService("install", OPTS, ctxFor("linux", run, { packageRoot: CHECKOUT }))); + expect(r.thrown).toBeInstanceOf(CliError); + expect((r.thrown as CliError).exitCode).toBe(EXIT.FAILED); + expect((r.thrown as Error).message).toContain(CHECKOUT); + expect((r.thrown as Error).message).toContain("--from-checkout"); + expect((r.thrown as Error).message).toContain("npm i -g @edspencer/paddock"); + expect(calls).toEqual([]); + expect(fs.existsSync(unitPath(PADDOCK_SERVICE, home))).toBe(false); + }); + + it("--dry-run is refused the same way: it previews what install would do", async () => { + const r = await streams(() => + runService("install", { ...OPTS, dryRun: true }, ctxFor("linux", recorder().run, { packageRoot: CHECKOUT })), + ); + expect(r.thrown).toBeInstanceOf(CliError); + }); + + it("--from-checkout installs anyway", async () => { + const r = await streams(() => + runService("install", { ...OPTS, fromCheckout: true }, ctxFor("linux", recorder().run, { packageRoot: CHECKOUT })), + ); + expect(r.value).toBe(EXIT.OK); + expect(fs.existsSync(unitPath(PADDOCK_SERVICE, home))).toBe(true); + }); + + it("the control: a global install is not a checkout", async () => { + const r = await streams(() => runService("install", OPTS, ctxFor("linux", recorder().run))); + expect(r.value).toBe(EXIT.OK); + }); +}); + +describe("service install refuses a port something else holds (SPEC §1)", () => { + it("refuses when the port is held by something that isn't Paddock", async () => { + const { run, calls } = recorder(); + const r = await streams(() => + runService("install", { ...OPTS, port: "7300" }, ctxFor("linux", run, { portOwner: async () => "other" })), + ); + expect((r.thrown as CliError).exitCode).toBe(EXIT.FAILED); + expect((r.thrown as Error).message).toContain("port 7300 is held by something that isn't Paddock"); + expect(calls.filter((c) => c.includes("enable"))).toEqual([]); + expect(fs.existsSync(unitPath(PADDOCK_SERVICE, home))).toBe(false); + }); + + it("goes ahead over a Paddock (a reinstall), and over its own running service even when that can't say it's Paddock", async () => { + expect( + (await streams(() => runService("install", OPTS, ctxFor("linux", recorder().run, { portOwner: async () => "paddock" })))).value, + ).toBe(EXIT.OK); + installed("7233"); + const r = await streams(() => + runService("install", OPTS, ctxFor("linux", recorder({ active: true }).run, { portOwner: async () => "other" })), + ); + expect(r.thrown).toBeUndefined(); + expect(r.value).toBe(EXIT.OK); + }); +}); + +describe("a reinstall keeps the unit's settings (SPEC §1)", () => { + it("service install with no flags over a --port 9123 unit keeps 9123; a flag still wins", async () => { + installed("9123"); + const unit = unitPath(PADDOCK_SERVICE, home); + const r = await streams(() => runService("install", OPTS, ctxFor("linux", recorder().run))); + expect(r.value).toBe(EXIT.OK); + expect(r.out).toContain("Keeping: paddock serve --port 9123"); + expect(fs.readFileSync(unit, "utf8")).toContain("--port 9123"); + + await streams(() => runService("install", { ...OPTS, port: "9200" }, ctxFor("linux", recorder().run))); + expect(fs.readFileSync(unit, "utf8")).toContain("--port 9200"); + expect(fs.readFileSync(unit, "utf8")).not.toContain("9123"); + }); + + it("the control: a first install takes the defaults", async () => { + const r = await streams(() => runService("install", OPTS, ctxFor("linux", recorder().run))); + expect(r.out).not.toContain("Keeping:"); + expect(fs.readFileSync(unitPath(PADDOCK_SERVICE, home), "utf8")).not.toContain("--port"); + }); +}); + +describe("--json on the service actions (SPEC §1, §3)", () => { + it("install: one document on stdout — ok, action and the status after — and every word of prose on stderr", async () => { + const r = await streams(() => runService("install", { ...OPTS, json: true }, ctxFor("linux", recorder({ active: true }).run))); + expect(r.value).toBe(EXIT.OK); + const doc = JSON.parse(r.out) as Record; + expect(doc).toMatchObject({ ok: true, action: "install", installed: true, running: true, answering: true, runningVersion: "0.82.1" }); + expect(doc).not.toHaveProperty("error"); + expect(r.err).toContain("Paddock is installed as a systemd --user service"); + }); + + it("uninstall: installed is false afterwards", async () => { + installed(); + const r = await streams(() => runService("uninstall", { ...OPTS, json: true }, ctxFor("linux", recorder().run))); + expect(JSON.parse(r.out)).toMatchObject({ ok: true, action: "uninstall", installed: false }); + expect(r.err).toContain("stopped and removed"); + }); + + it("start with nothing installed: 4, and the document says why", async () => { + const r = await streams(() => runService("start", { ...OPTS, json: true }, ctxFor("linux", recorder().run))); + expect(r.value).toBe(EXIT.NOT_INSTALLED); + expect(JSON.parse(r.out)).toMatchObject({ ok: false, action: "start", error: "not installed", installed: false }); + }); + + it("stop refused as busy: 75, and error is busy", async () => { + installed(); + const r = await streams(() => + runService( + "stop", + { ...OPTS, json: true }, + ctxFor("linux", recorder({ active: true }).run, { guardBusy: async () => EXIT.BUSY }), + ), + ); + expect(r.value).toBe(EXIT.BUSY); + expect(JSON.parse(r.out)).toMatchObject({ ok: false, action: "stop", error: "busy", running: true }); + }); + + it("restart that fails: the document is printed, then the failure is re-thrown for paddock: and its code", async () => { + installed(); + const r = await streams(() => + runService( + "restart", + { ...OPTS, json: true }, + ctxFor("linux", recorder({ active: true, fail: (c, a) => c === "systemctl" && a.includes("restart") }).run), + ), + ); + expect(r.thrown).toBeInstanceOf(Error); + const doc = JSON.parse(r.out) as Record; + expect(doc).toMatchObject({ ok: false, action: "restart" }); + expect(String(doc.error)).toContain("systemctl --user restart paddock.service failed"); + }); + + it("a refused install (the checkout) still prints its document", async () => { + const r = await streams(() => + runService("install", { ...OPTS, json: true }, ctxFor("linux", recorder().run, { packageRoot: "/src/paddock/packages/server" })), + ); + expect((r.thrown as CliError).exitCode).toBe(EXIT.FAILED); + expect(JSON.parse(r.out)).toMatchObject({ ok: false, action: "install", installed: false }); + }); +}); + +describe("a first install the service manager refuses leaves no unit behind (cli-contract d5ddc0e)", () => { + it("systemd", () => { + const { run, calls } = recorder({ fail: (c, a) => c === "systemctl" && a.includes("enable") }); + const backend = createSystemd(PADDOCK_SERVICE, { run, homeDir: home }); + expect(() => backend.install(buildSpec({ nodePath: "/n", scriptPath: CLI, dataDir: path.join(home, ".paddock") }))).toThrow(); + expect(fs.existsSync(unitPath(PADDOCK_SERVICE, home))).toBe(false); + expect(calls.some((c) => c.includes("disable"))).toBe(true); + }); + + it("systemd: a REinstall that fails keeps the unit that's there", () => { + installed(); + const { run } = recorder({ fail: (c, a) => c === "systemctl" && a.includes("enable") }); + const backend = createSystemd(PADDOCK_SERVICE, { run, homeDir: home }); + expect(() => backend.install(buildSpec({ nodePath: "/n", scriptPath: CLI, dataDir: path.join(home, ".paddock") }))).toThrow(); + expect(fs.existsSync(unitPath(PADDOCK_SERVICE, home))).toBe(true); + }); + + it("launchd", () => { + const { run } = recorder({ fail: (c, a) => c === "launchctl" && a[0] === "bootstrap" }); + const backend = createLaunchd(PADDOCK_SERVICE, { run, homeDir: home, sleep: () => undefined }); + expect(() => backend.install(buildSpec({ nodePath: "/n", scriptPath: CLI, dataDir: path.join(home, ".paddock") }))).toThrow(); + expect(fs.existsSync(plistPath(PADDOCK_SERVICE, home))).toBe(false); + }); +}); diff --git a/scripts/service-real.mjs b/scripts/service-real.mjs index 447e5753..bac48815 100644 --- a/scripts/service-real.mjs +++ b/scripts/service-real.mjs @@ -276,10 +276,24 @@ try { assert.ok(!fs.existsSync(unit), "nothing written"); const port = await freePort(); - step(`service install --port ${port}`); + step(`service install --dry-run --port ${port}: the unit on stdout, nothing written`); + const dry = expectExit(0, "service", "install", "--dry-run", "--port", String(port)); + assert.ok(dry.stdout.includes(cli), `the dry run prints the unit, which runs ${cli}:\n${dry.stdout}`); + assert.ok(dry.stdout.includes(String(port)), "with the port"); + assert.match(dry.stderr, /Nothing was written/); + assert.ok(!fs.existsSync(unit), "--dry-run wrote no unit"); + + step(`service install --port ${port} --json: one document on stdout, the prose on stderr`); installed = true; - const out = expectExit(0, "service", "install", "--port", String(port)).stdout; + const inst = expectExit(0, "service", "install", "--port", String(port), "--json"); + const out = inst.stderr; assert.match(out, new RegExp(`running at http://127\\.0\\.0\\.1:${port}`)); + const doc = JSON.parse(inst.stdout); + assert.equal(doc.ok, true); + assert.equal(doc.action, "install"); + assert.equal(doc.installed, true); + assert.equal(doc.answering, true, `answering after install: ${inst.stdout}`); + assert.equal(doc.port, port); const answer = await until("health", () => health(port)); assert.equal(answer.ok, true); assert.equal(answer.version, version, "/api/health reports the version it is running (SPEC §8)"); @@ -303,6 +317,26 @@ try { fs.readFileSync(logFile, "utf8").includes(`Paddock ${version}: http://127.0.0.1:${port}`), ); + step("doctor --offline --json against the real service: the service checks pass"); + { + const r = paddock("doctor", "--offline", "--json"); + const d = JSON.parse(r.stdout); + const by = (id) => d.checks.filter((c) => c.id === id); + for (const id of ["unit", "running-version", "port", "data-home", "node-engines"]) { + assert.deepEqual(by(id).map((c) => c.status), ["pass"], `doctor ${id}: ${JSON.stringify(by(id))}`); + } + assert.equal(by("update")[0].status, "skip", "--offline skips the registry"); + } + + step("service install again, with no flags: keeps the port, and replaces the running process (SPEC §1)"); + { + const pidBefore = statusJson(0).pid; + const again = JSON.parse(expectExit(0, "service", "install", "--json").stdout); + assert.equal(again.port, port, "a reinstall keeps the port the unit records"); + assert.equal(again.answering, true); + assert.notEqual(again.pid, pidBefore, `the old process was replaced (pid ${pidBefore})`); + } + step("status: exit 0, running, answering, versions agree"); console.log(expectExit(0, "service", "status").stdout); let s = statusJson(0);