diff --git a/.changeset/cli-contract-shoulds.md b/.changeset/cli-contract-shoulds.md new file mode 100644 index 0000000..2feafa8 --- /dev/null +++ b/.changeset/cli-contract-shoulds.md @@ -0,0 +1,13 @@ +--- +"@managers/server": minor +--- + +**The CLI contract's remaining `service` and `serve` options (SPEC §1, §3), ported from Paddock ([paddock#996](https://github.com/edspencer/paddock/pull/996)).** What a script can see: + +- **`managers 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. The npx refusal now suggests `npm i -g @edspencer/managers` rather than `npm link`, which this refusal would catch. +- **`service install` refuses a port something else holds**, exit **1**, rather than writing a service that can only crash-loop. A Managers on the port (a reinstall) is fine, and so is the unit's own running service. A Paddock on the port counts as something else. +- **`--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 7234. +- **`managers serve --quiet` (`-q`)** prints only the first line, `Managers : `. +- **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. diff --git a/README.md b/README.md index 5025afb..42a4527 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,10 @@ Each GitHub Release also carries a self-contained tarball. 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 +`status [--json]` and `logs [-f] [-n ]`; `install --dry-run` prints the unit +and writes nothing, a reinstall keeps the unit's port, host and data dir, and +`install` refuses a git checkout (unless `--from-checkout`) and a port something else +holds. `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**. `managers busy` exits **75** while a chat turn or trigger run is in flight (0 when idle, 3 when nothing is running), diff --git a/UPDATING.md b/UPDATING.md index a7939b8..8cf5473 100644 --- a/UPDATING.md +++ b/UPDATING.md @@ -199,4 +199,7 @@ managers service status `service install --refresh` is the one worth remembering: it re-renders the unit from what the **existing** one records, rather than from the flags and environment of the shell you happen to be in. With nothing installed it exits 4 rather than quietly performing a -first install with defaults. +first install with defaults. A plain `managers service install` keeps the installed unit's +port, host and data dir too, unless you give new ones; `--refresh` differs in ignoring +`MANAGERS_DATA_DIR` in your shell, and in refusing to do a first install. +`managers service install --dry-run` prints the unit either would write, and writes nothing. diff --git a/packages/server/NPM-README.md b/packages/server/NPM-README.md index 7753259..c7f6a2e 100644 --- a/packages/server/NPM-README.md +++ b/packages/server/NPM-README.md @@ -59,6 +59,7 @@ the API as you. The UI shows a permanent banner saying so. --host Bind address (default 127.0.0.1) -d, --data-dir Projects + state (default ~/.managers) -o, --open Open the app in your browser once it is listening + -q, --quiet Print only the first line, `Managers : ` --verbose Show the server's own logs (quiet by default) -v, --version Print the version -h, --help Show help @@ -66,7 +67,11 @@ the API as you. The UI shows a permanent banner saying so. `managers service install` keeps it running in the background from login (launchd on macOS, a systemd user unit on Linux; it refuses to install from the -`npx` cache, so `npm i -g` first). `managers config show --resolved` prints every +`npx` cache or a git checkout, so `npm i -g` first, and refuses a port something +else holds). Running it again keeps the port, host and data dir the installed unit +records unless you give new ones; `--dry-run` prints the unit and writes nothing, +and `--json` on `install`, `uninstall`, `start`, `stop` and `restart` prints one +JSON document. `managers config show --resolved` prints every effective setting and where it came from. Your projects, objectives, tasks, memory, chats and settings persist in diff --git a/packages/server/src/cli/args.ts b/packages/server/src/cli/args.ts index 1cc65ce..9db8bd2 100644 --- a/packages/server/src/cli/args.ts +++ b/packages/server/src/cli/args.ts @@ -117,6 +117,20 @@ export interface CliOptions { refresh?: boolean; /** `doctor --offline`: skip the one check that asks the npm registry (SPEC §1). */ 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 `Managers : ` line and nothing else (SPEC §3). */ + quiet?: boolean; } /** @@ -321,6 +335,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 `Managers : ` line.", + }, { flag: "--offline", read: (o) => o.offline === true, @@ -475,6 +524,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; @@ -574,6 +635,7 @@ Usage 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 + (--dry-run prints the unit instead) managers service uninstall stop it and remove the unit managers service status [--json] installed? running? which version? managers service start start an installed service @@ -600,6 +662,7 @@ Options --host Bind address (default 127.0.0.1) -d, --data-dir Projects + state (default ~/.managers, or $MANAGERS_DATA_DIR) -o, --open Open the app in your browser once it is listening + -q, --quiet Print only the first line, \`Managers : \` --verbose Show the server's own logs (quiet by default) -v, --version Print the Managers version and exit -h, --help Show this help @@ -723,6 +786,7 @@ export const SERVICE_USAGE = `managers service — keep Managers running in the Usage managers service install [options] register it and start it now managers service install --refresh re-write the unit, keeping its settings + managers service install --dry-run print the unit it would write; write nothing managers service uninstall stop it and deregister it managers 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 MANAGERS_DATA_DIR in this shell. This is what \`managers 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 7234. + 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,19 +878,25 @@ 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/managers && managers service install + + (--from-checkout installs from the checkout anyway, for working on Managers.) - npm link -w packages/server && managers service install (from a built checkout) + It also refuses when something that isn't Managers holds the port: pick + another with --port. A note on access Managers binds loopback, and the managers command runs it with authentication diff --git a/packages/server/src/cli/managers.ts b/packages/server/src/cli/managers.ts index 2cb876a..b2acd93 100644 --- a/packages/server/src/cli/managers.ts +++ b/packages/server/src/cli/managers.ts @@ -400,7 +400,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.MANAGERS_DATA_DIR = dataDir; @@ -463,6 +465,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(`${MANAGERS_NAME} ${MANAGERS_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 3293022..db13806 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, + identifyManagers, + 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 Managers, 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" | "managers" | "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 identifyManagers(`http://${probe.includes(":") ? `[${probe}]` : probe}:${port}`); + return who?.managers === true ? "managers" : "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 Managers itself, where that is the point. + */ +export function checkoutRefusal(packageRoot: string): string { + return ( + `this copy of Managers 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/managers && managers service install\n\n" + + " Or run this checkout as the service anyway (when working on Managers):\n" + + " managers service install --from-checkout\n" + ); } /** @@ -279,6 +317,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/managers/ + // 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 @@ -288,11 +332,28 @@ async function install( // CLI, and a silent fallback would move a `--port 9000` service to 7234 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 7234. `--refresh` still differs in two ways: + // it ignores `MANAGERS_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; } } @@ -304,7 +365,43 @@ 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 `> managers.service` captures the + // unit alone. + if (opts.dryRun === true) { + const contents = + backend.platform === "darwin" ? renderPlist(MANAGERS_SERVICE, spec) : renderUnit(MANAGERS_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( + `managers: 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 Managers 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 Managers (before 0.4). + 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 Managers, so the service could not start.\n` + + ` Stop it, or pick another port: managers service install --port ${port + 1}`, + ); + } + } + + if (existing !== undefined) { console.log( `\n Re-writing ${backend.unitPath}\n Keeping: managers ${spec.args.join(" ")}`, ); @@ -910,6 +1007,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 `managers: ` 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/ready.ts b/packages/server/src/cli/service/ready.ts index d065aa2..5d31bf1 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,53 @@ 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 Managers, 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, which Managers forked from; `counts.run` + * (the trigger runs in flight) is Managers' own, so a Paddock on the port reads + * as not-Managers. A Managers older than 0.4 has no `/api/busy`, and reads as + * not-Managers here: callers that can tell it apart some other way (an + * installed unit on that port) should. + */ +export async function identifyManagers( + url: string, + fetchImpl: typeof fetch = fetch, +): Promise<{ managers: 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 { + managers: + health.ok && typeof counts.chat === "number" && "background" in counts && typeof counts.run === "number", + ...version, + }; + } catch { + return { managers: false, ...version }; + } +} diff --git a/packages/server/src/cli/service/spec.ts b/packages/server/src/cli/service/spec.ts index b623110..450c20a 100644 --- a/packages/server/src/cli/service/spec.ts +++ b/packages/server/src/cli/service/spec.ts @@ -172,7 +172,7 @@ export const NPX_REFUSAL = "`service install` needs an install path that will still be there at your\n" + " next login, and this copy is running from npx's cache — a hash-keyed\n" + " directory that `npm cache clean` removes.\n\n" + - " npm link -w packages/server && managers service install (from a built checkout)\n"; + " npm i -g @edspencer/managers && managers service install\n"; /** * The port a generated unit will actually serve on, read back out of its own 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 0000000..8bb6824 --- /dev/null +++ b/packages/server/test/unit/cli-service-shoulds.test.ts @@ -0,0 +1,380 @@ +/** + * 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, MANAGERS_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/managers/packages/server"; +const CLI = `${GLOBAL}/dist/cli/managers.js`; + +let home: string; +beforeEach(() => { + home = fs.mkdtempSync(path.join(os.tmpdir(), "managers-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 = "7234") => + createSystemd(MANAGERS_SERVICE, { run: recorder().run, homeDir: home }).install( + buildSpec({ nodePath: "/opt/node/bin/node", scriptPath: CLI, dataDir: path.join(home, ".managers"), 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(MANAGERS_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.managers"); + expect(fs.existsSync(plistPath(MANAGERS_SERVICE, home))).toBe(false); + }); + + it("with --refresh, prints the unit re-rendered from the installed one's settings", async () => { + installed("9123"); + const unit = unitPath(MANAGERS_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(MANAGERS_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/managers/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/managers"); + expect(calls).toEqual([]); + expect(fs.existsSync(unitPath(MANAGERS_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(MANAGERS_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 Managers", 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 Managers"); + expect(calls.filter((c) => c.includes("enable"))).toEqual([]); + expect(fs.existsSync(unitPath(MANAGERS_SERVICE, home))).toBe(false); + }); + + it("goes ahead over a Managers (a reinstall), and over its own running service even when that can't say it's Managers", async () => { + expect( + (await streams(() => runService("install", OPTS, ctxFor("linux", recorder().run, { portOwner: async () => "managers" })))).value, + ).toBe(EXIT.OK); + installed("7234"); + 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(MANAGERS_SERVICE, home); + const r = await streams(() => runService("install", OPTS, ctxFor("linux", recorder().run))); + expect(r.value).toBe(EXIT.OK); + expect(r.out).toContain("Keeping: managers 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(MANAGERS_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("Managers 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 managers: 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 managers.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/managers/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(MANAGERS_SERVICE, { run, homeDir: home }); + expect(() => backend.install(buildSpec({ nodePath: "/n", scriptPath: CLI, dataDir: path.join(home, ".managers") }))).toThrow(); + expect(fs.existsSync(unitPath(MANAGERS_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(MANAGERS_SERVICE, { run, homeDir: home }); + expect(() => backend.install(buildSpec({ nodePath: "/n", scriptPath: CLI, dataDir: path.join(home, ".managers") }))).toThrow(); + expect(fs.existsSync(unitPath(MANAGERS_SERVICE, home))).toBe(true); + }); + + it("launchd", () => { + const { run } = recorder({ fail: (c, a) => c === "launchctl" && a[0] === "bootstrap" }); + const backend = createLaunchd(MANAGERS_SERVICE, { run, homeDir: home, sleep: () => undefined }); + expect(() => backend.install(buildSpec({ nodePath: "/n", scriptPath: CLI, dataDir: path.join(home, ".managers") }))).toThrow(); + expect(fs.existsSync(plistPath(MANAGERS_SERVICE, home))).toBe(false); + }); +}); + +describe("identifyManagers: a Paddock on the port is not a Managers", () => { + const answer = (busy: unknown) => + (async (url: string | URL | Request) => + String(url).endsWith("/api/health") + ? new Response(JSON.stringify({ ok: true, version: "0.4.0" })) + : new Response(JSON.stringify(busy))) as typeof fetch; + + it("Managers' /api/busy has counts.run", async () => { + const { identifyManagers } = await import("../../src/cli/service/ready.js"); + expect(await identifyManagers("http://x", answer({ counts: { chat: 0, background: 0, job: 0, run: 0 } }))).toEqual({ + managers: true, + version: "0.4.0", + }); + }); + + it("Paddock's has no counts.run, and something with no /api/busy is not Managers either", async () => { + const { identifyManagers } = await import("../../src/cli/service/ready.js"); + expect((await identifyManagers("http://x", answer({ counts: { chat: 0, background: 0, job: 0 } })))?.managers).toBe(false); + expect((await identifyManagers("http://x", answer("not json")))?.managers).toBe(false); + }); +}); diff --git a/packages/server/test/unit/cli-service.test.ts b/packages/server/test/unit/cli-service.test.ts index da4dcb2..8530654 100644 --- a/packages/server/test/unit/cli-service.test.ts +++ b/packages/server/test/unit/cli-service.test.ts @@ -166,7 +166,7 @@ describe("managers CLI: verb dispatch (#796)", () => { it("SERVICE_USAGE says at login, not at boot, and names enable-linger", () => { expect(SERVICE_USAGE).toMatch(/LOG IN, not when the machine boots/); expect(SERVICE_USAGE).toContain("loginctl enable-linger"); - expect(SERVICE_USAGE).toContain("managers service install (from a built checkout)"); + expect(SERVICE_USAGE).toContain("npm i -g @edspencer/managers"); }); }); @@ -1318,7 +1318,7 @@ describe("managers service: refusals", () => { const npx = { ...ctx, packageRoot: "/Users/ed/.npm/_npx/399ccf38/node_modules" }; await expect(runService("install", opts, npx)).rejects.toThrow(CliError); await expect(runService("install", opts, npx)).rejects.toThrow( - /npm link -w packages\/server && managers service install/, + /npm i -g @edspencer\/managers && managers service install/, ); }); diff --git a/scripts/service-real.mjs b/scripts/service-real.mjs index c9e70d6..e1825d8 100644 --- a/scripts/service-real.mjs +++ b/scripts/service-real.mjs @@ -15,8 +15,12 @@ // What it checks, in order: // status with nothing installed exit 4, --json says installed:false // install from an npx cache refused, exit 1, nothing written -// install --port it answers; the unit names the installed CLI, `serve`, and the log file +// install --dry-run --port the unit on stdout, "Nothing was written" on stderr, no unit file +// install --port --json it answers; one JSON document; the unit names the installed CLI, `serve`, +// and the log file // the log file carries the server's own banner line, which proves stdout reaches it +// doctor --offline --json the unit, running-version, port, data-home and node-engines checks pass +// install again, no flags keeps the port, replaces the running process (SPEC §1) // status / status --json exit 0, running + answering, installed version == running version // logs, logs -n exit 0, reads that same file // an unknown flag exit 2 @@ -276,10 +280,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 +321,26 @@ try { fs.readFileSync(logFile, "utf8").includes(`Managers ${version}: http://127.0.0.1:${port}`), ); + step("doctor --offline --json against the real service: the service checks pass"); + { + const r = managers("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);