diff --git a/.changeset/cli-contract-update.md b/.changeset/cli-contract-update.md new file mode 100644 index 0000000..872d5d0 --- /dev/null +++ b/.changeset/cli-contract-update.md @@ -0,0 +1,17 @@ +--- +"@managers/server": minor +--- + +`managers update`, `managers doctor`, and `service install --refresh` + +Wave F3 of the CLI-contract rollout (edspencer/cli-contract SPEC 0.2), ported from Paddock 0.82 and the contract's `reference/`. + +**New: `managers update [--check] [--to ] [--yes] [--force] [--json]`** (`upgrade` is a hidden alias). It asks the registry, checks the running instance is not busy, stops the service, installs with the package manager this copy came from, hands over to the new CLI to rewrite the unit, waits for `/api/health` to report the new version, and **rolls back** if it doesn't. Exit codes a script can see: **5** this install can't update itself (a checkout, npx, a container, or a managed install: the right command is printed), **6** the update failed and the old version is running again, **7** it failed and could not be rolled back, **75** busy, **2** no terminal and no `--yes`. `--check` exits 0 whether or not there is an update; read `updateAvailable` from `--json`. Nothing contacts the registry on its own. + +**New: `managers doctor [--json] [--offline]`.** SPEC §1's eight checks (Node against `engines`, the install method, the unit, the running version, the port, linger, the data dir, a newer version), then Managers' own: the configuration loads, and **the security posture `/api/security` reports** (no authentication, trusted-header, any-audience JWTs, batch drive mode), asked of the running instance or computed from this shell's configuration by the server's own rule. Exits 1 if any check failed. + +**New: `managers service install --refresh`** re-renders an existing unit from the settings it records (port, host, data dir), and exits 4 with nothing installed. `service status` repeats what the last `update --check` or `doctor` found (`update` in `--json`, absent rather than null when there's nothing). `service start` and `restart` run `systemctl --user reset-failed` first. A first `service install` that launchd or systemd refuses no longer leaves a unit behind (so `status` doesn't report it installed); a refused reinstall keeps the unit it had. + +**The image** sets `MANAGERS_IN_DOCKER=1` and puts `managers` on `PATH`, so `docker exec managers busy` works as a pre-update hook and `managers update` inside it prints the image to pull and exits 5. Set `MANAGERS_UPDATE_HINT` to have `update` print your own upgrade command instead (for a container or install managed by Ansible, say). + +`--check`, `--to`, `--yes`, `--refresh` and `--offline` exit 2 on commands that can't act on them. See UPDATING.md. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b463dba..80de094 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -56,7 +56,8 @@ jobs: conformance: name: CLI conformance runs-on: ubuntu-latest - timeout-minutes: 15 + # The update checks install the package several times from the runner's local registry. + timeout-minutes: 30 steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 @@ -84,7 +85,7 @@ jobs: service: name: Service (real ${{ matrix.os == 'macos-latest' && 'launchd' || 'systemd' }}) runs-on: ${{ matrix.os }} - timeout-minutes: 20 + timeout-minutes: 35 strategy: fail-fast: false matrix: @@ -109,6 +110,47 @@ jobs: env: MANAGERS_REAL_SERVICE: "1" run: node scripts/service-real.mjs + # The conformance runner's update checks that need a real service manager: install the + # service at the packed version, update it from the runner's local registry, and update it + # to a build that doesn't start, which must roll back with exit 6. CI_REAL_SERVICE (and CI) + # is what lets the runner install a service under this runner's real home. + - name: Stage the npm package again + run: npm run pack:npm + - name: Conformance, with the real service manager + env: + CI_REAL_SERVICE: "1" + run: npx cli-conformance --dir dist-npm --config cli-contract.json --only update-service,update-rollback + + # `managers update` against a LOCAL registry serving three real packed builds + # (scripts/update-registry.mjs). It runs a real `npm install -g` into a throwaway prefix, with a + # throwaway HOME, XDG_CONFIG_HOME, MANAGERS_DATA_DIR and npm cache, and refuses to start unless + # `npm root -g` really resolves inside its temp directory. + # + # Both OSes run everything except the service-backed scenarios; those need the stand-in + # systemctl (scripts/standin-systemctl.mjs) and so are Linux-only. The real managers' side of + # `update` is in the `service` job above, which since C2 installs at one version and updates to + # the next against the same local registry. + # + # This is also the only job that is NOT root, which matters for one scenario: the non-writable + # global folder (SPEC §5 step 5) cannot be proven as root, because root ignores the mode bits. + # The script skips it with a printed reason on a box where it is root, and runs it here. + update: + name: Update (fake registry, ${{ matrix.os == 'macos-latest' && 'macOS' || 'ubuntu' }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 22 + cache: npm + - run: npm ci + - name: Update, against a local registry + run: node scripts/update-registry.mjs # Fails on a high/critical npm advisory that is not a documented exception # (docs/security/npm-audit.md). Reads only the lockfile, so no `npm ci`. diff --git a/Dockerfile b/Dockerfile index d69bc86..1a4a59d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -82,7 +82,8 @@ ENV NODE_ENV=production \ PORT=7234 \ HOST=0.0.0.0 \ MANAGERS_DATA_DIR=/data \ - HOME=/data + HOME=/data \ + MANAGERS_IN_DOCKER=1 # System deps + GitHub CLI + the Claude CLI (the CLI runtime's PATH binary; the # SDK runtime ships its own — see the header). @@ -117,6 +118,25 @@ COPY LICENSE ./ COPY --from=build /app/packages/server/dist packages/server/dist COPY --from=build /app/packages/web/dist packages/web/dist +# `managers` on PATH, which the CLI contract requires of an image (SPEC §9) and which is what makes +# `docker exec managers busy` and `docker exec managers update --check` work. +# +# A shim rather than a global npm install, because the app in this image is not an npm install: it +# is a copied `dist/` with its dependencies at /app/node_modules. The shim invokes the interpreter +# explicitly, for the same reason the service unit does (spec.ts) — a `#!/usr/bin/env node` has to +# find `node` on PATH, and that is one more thing to be true at a moment nobody is watching. +# +# `MANAGERS_IN_DOCKER=1` above is what makes `managers update` in here print the image-pull command +# and exit 5 rather than trying to npm-install over a read-only app directory (SPEC §6 row 1). It +# is set by this Dockerfile and nothing else: `/.dockerenv` is deliberately NOT the signal, because +# dev containers have it too and a global npm install inside one is a legitimate thing to update. +# +# An operator who manages this container with something that knows how to upgrade it — Ansible, a +# Helm chart, a Watchtower label — sets MANAGERS_UPDATE_HINT at `docker run` time, and `update` +# prints that sentence instead of guessing at a `docker compose` line (see UPDATING.md). +RUN printf '#!/bin/sh\nexec node /app/packages/server/dist/cli/managers.js "$@"\n' > /usr/local/bin/managers \ + && chmod +x /usr/local/bin/managers + # Configure git auth from GITHUB_TOKEN (if provided) then exec the server. RUN printf '#!/bin/sh\nif [ -n "$GITHUB_TOKEN" ]; then\n git config --global url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"\nfi\nmkdir -p "$MANAGERS_DATA_DIR"\nexec "$@"\n' > /usr/local/bin/docker-entrypoint.sh \ && chmod +x /usr/local/bin/docker-entrypoint.sh diff --git a/README.md b/README.md index 69b0799..5025afb 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,10 @@ unit; a bad command, flag or value exits **2**. `managers busy` exits **75** whi a chat turn or trigger run is in flight (0 when idle, 3 when nothing is running), and `service stop`/`restart` refuse with 75 unless given `--force`. A SIGTERM waits briefly for in-flight work, then records what it cut short; under Docker, -give the container a `stop_grace_period` of 20 s or more. The CLI follows the shared +give the container a `stop_grace_period` of 20 s or more. `managers update` installs +a newer release and puts the service back up, rolling back if the new version +doesn't answer ([UPDATING.md](UPDATING.md)); `managers doctor` checks the install, +the service, the configuration and the security posture. The CLI follows the shared [CLI contract](https://github.com/edspencer/cli-contract) (`cli-contract.json` says which of its checks apply). diff --git a/UPDATING.md b/UPDATING.md new file mode 100644 index 0000000..a7939b8 --- /dev/null +++ b/UPDATING.md @@ -0,0 +1,202 @@ +# Updating Managers + +`managers update` installs the new version, refreshes the service unit, waits for it to answer — and puts the old version back if it doesn't. + +```bash +managers update +``` + +That is the whole thing. It asks npm what the latest version is, asks you to confirm, +stops your service, installs, starts it again on the new version, and waits until +`/api/health` reports the version it just installed. If that never happens, it reinstalls +the version you were on and tells you so. + +``` +Managers 0.4.0 is available (you have 0.3.1). + Run: managers update + Changes: https://github.com/edspencer/managers/releases/tag/v0.4.0 +``` + +## Look before you leap + +`managers update --check` asks the registry, prints what it found, and changes nothing. It +exits **0** whether or not there is an update — a script reads `updateAvailable` from the +JSON rather than the exit code: + +```bash +managers update --check --json | jq '.updateAvailable, .target' +``` + +What it found is cached in `/update-check.json`, and `managers service status` +repeats it. **Nothing in Managers contacts the registry on its own** — not the server, not +at startup, not in the background. Only `update`, `update --check` and `doctor` ask, and +only when you run them. + +## Updating while something is running + +`update` asks the running instance whether it is busy before it stops anything, and +refuses if it is: + +``` +managers: Managers is busy: 2 chat turns are running. Run it from a terminal, not from + inside a Managers chat. +``` + +A chat turn is a live `claude` subprocess writing a transcript, and it cannot be resumed +from where it was interrupted — so a restart loses it. A trigger run (a scheduled wake, a +report, a consolidation) counts too, from the moment its run record is written until it is +finished and committed. Wait, or override the check with +`--force`. `--force` skips **only** that check: the health check and the rollback still run. + +> **Run it from a terminal, not from a chat.** Managers' agents can drive Managers. A keeper chat that runs `managers update` is itself one +of the chat turns the busy check counts, so it will always see itself as busy — and +`--force` from there stops the service that is running the chat, which then never gets to +tell you what happened. This is why the refusal says where to run it from. + +## Going somewhere particular + +```bash +managers update --to 0.3.1 # a version — the only way to go BACK +managers update --to next # a dist-tag +``` + +`update` never goes backwards by accident: a registry whose `latest` is *older* than what +you have is reported and ignored, and a `latest` that points at a prerelease is not +installed unless `--to` names it. + +## Without a terminal + +`update` asks a question, and a question needs a terminal. In a script, a cron job or an +Ansible task there is none, so it exits **2** and says `--yes` is required rather than +guessing: + +```bash +managers update --yes +``` + +## When it goes wrong + +The exit code is the whole report, and the two failure codes mean different things: + +| Code | What happened | What you do | +|---|---|---| +| 0 | Updated, or already up to date | nothing | +| 2 | No terminal to ask, so `--yes` is required | add `--yes` | +| 5 | This install can't update itself — the right command was printed | run that command | +| 6 | The new version didn't start. **The old one is running again** | read the log it printed, then report it | +| 7 | The new version didn't start **and the old one could not be restored** | run the commands it printed | +| 75 | Busy | wait, or `--force` | + +On a rollback, `update` prints the last 20 lines of the service log before it puts the old +version back — which is usually enough to see why the new one did not come up. + +## Installs that can't update themselves (exit 5) + +Managers works out where it is running from, and five layouts are not its to replace. Each +prints the command that *would* work: + +| Where it is running from | What it tells you | +|---|---| +| A container image | `docker compose pull && docker compose up -d` | +| A managed install (`MANAGERS_UPDATE_HINT` is set) | whatever that variable says | +| `npx` / `pnpm dlx` | `npx @edspencer/managers@latest` — npx already runs the latest each time | +| A checkout | `git pull && npm install && npm run build` | +| A dependency of another project | update it in that project | + +A global **npm**, **pnpm**, **bun** or **volta** install updates in place. + +If the global folder is not writable, `update` prints the same command with `sudo` and +exits 5. **It never runs `sudo` itself** — that is a decision for the person at the +keyboard, not for a tool that has just decided to replace its own files. + +## In Docker + +Nothing installs anything inside a container. The image sets `MANAGERS_IN_DOCKER=1`, so +`update` there prints the image to pull and exits 5: + +```bash +docker exec managers managers update --check +``` + +``` +Managers 0.4.0 is available (you have 0.3.1). + Run: docker compose pull && docker compose up -d (image ghcr.io/edspencer/managers:0.4.0) +``` + +`managers` is on `PATH` in the image, so `docker exec managers managers busy` works too — +which is what lets an automatic updater wait for a quiet moment — for example Watchtower's +pre-update hook: + +```yaml +labels: + com.centurylinklabs.watchtower.lifecycle.pre-update: managers busy +# and on the Watchtower container: WATCHTOWER_LIFECYCLE_HOOKS=true +``` + +Give the container a `stop_grace_period` of at least 20 seconds. On SIGTERM, Managers waits +up to 8 seconds for in-flight chat turns and trigger runs to finish, then records any it has +to cut short (each run is marked `failed`, `interrupted by shutdown`); Docker's default +10-second stop timeout leaves too little room for that. + +If something else manages the container — Ansible, a Helm chart, a deploy job — set +`MANAGERS_UPDATE_HINT` to the command that actually upgrades it, and `update` prints that +instead of guessing: + +```bash +docker run -e MANAGERS_UPDATE_HINT='ansible-playbook -i prod managers.yml' … +``` + +## What it does, step by step + +Worth knowing if you are automating around it, or if it stops half way: + +1. takes `/update.lock`, so two updates cannot interleave; +2. works out how this copy was installed; +3. asks the registry for the target version and its `engines.node`; +4. compares — and stops here with `--check`; +5. checks the global folder is writable; +6. asks the running instance whether it is **busy**, before anything is stopped; +7. asks you, unless `--yes`; +8. fetches **both** the new and the current version into the npm cache, while the old + version is still serving, so a rollback has its package to hand even if the network + has gone; +9. stops the service; +10. installs with the package manager this copy came from; +11. hands over to the **new** CLI, which re-writes the service unit in its own format + with the port and data dir the old one recorded (`managers service install --refresh`); +12. waits for `/api/health` to report the version it installed — not merely for the URL + to answer, because the old server, a sibling instance and a supervisor that restarted + the old unit all answer too; +13. and if any of 10–12 fails, puts the old version back. + +The registry it asks is `npm_config_registry`, else `npm config get registry`, else +`https://registry.npmjs.org`. + +## Checking it afterwards + +```bash +managers doctor # every check, with a fix for each failure +managers doctor --offline # the same, without asking the registry +``` + +`doctor` checks this Node against the package's `engines`, how Managers was installed, the +service unit, that the running version is the installed one, the port, linger (Linux), the +data dir, whether a newer version exists, that the configuration loads, and the security +posture `/api/security` reports. It exits 1 if anything failed. + +## Updating by hand + +There is nothing magic about `update` — it runs the commands you would: + +```bash +managers busy # 0 not busy, 75 busy, 3 nothing running +managers service stop +npm install -g @edspencer/managers@latest +managers service install --refresh # re-write the unit, keeping its settings +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. diff --git a/cli-contract.json b/cli-contract.json index 32e8861..3e6e0c5 100644 --- a/cli-contract.json +++ b/cli-contract.json @@ -41,6 +41,27 @@ "busy": true, "busy-json": true, "serve-banner": true, - "serve-health": true + "serve-health": true, + "update-up-to-date": true, + "update-check-json": true, + "update-no-tty": true, + "update-busy": true, + "update-npx": true, + "update-checkout": true, + "update-not-writable": true, + "update": true, + "update-to-lower": true, + "update-service": true, + "update-rollback": true + }, + "update": { + "runtimeFile": "{home}/managers/runtime.json", + "serviceInstall": [ + "service", + "install", + "--port", + "{port}" + ], + "timeoutMs": 600000 } } diff --git a/packages/server/src/cli/args.ts b/packages/server/src/cli/args.ts index 233f29e..1cc65ce 100644 --- a/packages/server/src/cli/args.ts +++ b/packages/server/src/cli/args.ts @@ -80,10 +80,43 @@ export interface CliOptions { * * The refusal it skips is the only thing it skips. It does not change what the * busy check printed — a forced stop prints the same sentence, prefixed - * `Overriding:` — and in wave C2 it will not skip `update`'s health check or - * its rollback either. + * `Overriding:` — and on `update` it skips the busy check and nothing else: + * the health check and the rollback still run (SPEC §1). */ force?: boolean; + /** + * `update`: report what a new version would be, and change nothing + * (SPEC §1, §5 step 4). + * + * Named `checkOnly` rather than `check` because `check` reads as a verb in a + * bag of flags that also carries `write` and `follow`; `update-command.ts` + * maps it back to the contract's `--check` at the one seam. + */ + checkOnly?: boolean; + /** `update --to `: the only way to move to a LOWER version. */ + to?: string; + /** + * `update --yes`: do not ask. + * + * Required when there is no TTY, where a command that would have asked exits + * 2 instead of guessing (SPEC §1, §3). That asymmetry is deliberate: a + * scripted update that silently assumed yes would be a restart nobody asked + * for, and one that silently assumed no would be a no-op reported as success. + */ + yes?: boolean; + /** + * `service install --refresh`: re-render the unit, keeping the settings the + * EXISTING one carries (SPEC §1, §5 step 11). + * + * This is the hand-over `update` performs: the NEW version writes the unit, + * in its own format, with the port and data dir the OLD one recorded. It + * needs an installed unit — with nothing to refresh it exits 4 rather than + * quietly performing a first install with defaults, which is how a + * `--port 9000` service comes back on 7234. + */ + refresh?: boolean; + /** `doctor --offline`: skip the one check that asks the npm registry (SPEC §1). */ + offline?: boolean; } /** @@ -96,7 +129,7 @@ export interface CliOptions { */ export class CliError extends Error { readonly exitCode: number; - constructor(message: string, exitCode: number = EXIT.failure) { + constructor(message: string, exitCode: number = EXIT.FAILED) { super(message); this.exitCode = exitCode; } @@ -112,7 +145,7 @@ export class CliError extends Error { */ export class UsageError extends CliError { constructor(message: string) { - super(message, EXIT.usage); + super(message, EXIT.USAGE); } } @@ -157,7 +190,7 @@ export type ConfigAction = (typeof CONFIG_ACTIONS)[number]; * Paddock and Managers, every existing service unit's `ExecStart` names it, and * it is in two years of other people's scripts. They parse to the same command. */ -export const VERBS = ["serve", "start", "service", "config", "busy"] as const; +export const VERBS = ["serve", "start", "service", "config", "busy", "update", "upgrade", "doctor"] as const; /** * A parsed invocation: which verb, plus the flags that followed it. @@ -171,7 +204,16 @@ export type Command = | { verb: "service"; action: ServiceAction | undefined; opts: CliOptions } | { verb: "config"; action: ConfigAction | undefined; opts: CliOptions } /** `busy` takes no action — it is one question with one answer (SPEC §1). */ - | { verb: "busy"; opts: CliOptions }; + | { verb: "busy"; opts: CliOptions } + /** + * `update` (SPEC §1, §5). `upgrade` is a HIDDEN alias: the spec requires it + * be accepted, and deliberately does not list it in the help — one name in + * the documentation, two that work, so nobody has to remember which word this + * tool chose. + */ + | { verb: "update"; opts: CliOptions } + /** `doctor` (SPEC §1): checks, each with a fix. Asks the registry unless `--offline`. */ + | { verb: "doctor"; opts: CliOptions }; /** * Split an action off a verb's argv, then parse what follows as flags. @@ -234,31 +276,82 @@ function parseAction( * for. Corrected rather than deleted because the grammar it documents is real * and load-bearing; it was only the example's error that was misdescribed. */ +/** + * Flags that mean something on SOME commands only, and the commands they mean + * it on. + * + * Rejecting a flag the command cannot act on, rather than parsing and dropping + * it, is the difference between being told and guessing: the two readings of a + * quiet `service uninstall --force` are "it overrode something" and "it did + * nothing", and the exit code is 0 either way. The same trap sits under + * `service status --refresh` and `serve --check`. + * + * One table, checked once in {@link parseCommand}, rather than a rule per + * command — a second copy of this logic is a second chance for the two to + * disagree about where a flag applies. `where` is matched against the + * invocation as the user would write it (`service stop`, `update`). + */ +const SCOPED_FLAGS: readonly { + flag: string; + read: (o: CliOptions) => boolean; + where: readonly string[]; + why: string; +}[] = [ + { + flag: "--force", + read: (o) => o.force === true, + where: ["service stop", "service restart", "update"], + why: "It overrides the busy check, and those are the commands that run one.", + }, + { + flag: "--check", + read: (o) => o.checkOnly === true, + where: ["update"], + why: "It reports what an update would do, and changes nothing.", + }, + { + flag: "--to", + read: (o) => o.to !== undefined, + where: ["update"], + why: "It names the version or dist-tag to move to.", + }, + { + flag: "--yes", + read: (o) => o.yes === true, + where: ["update"], + why: "`update` is the only command that asks a question.", + }, + { + flag: "--offline", + read: (o) => o.offline === true, + where: ["doctor"], + why: "It skips the registry check, and `doctor` is the command that has one.", + }, + { + flag: "--refresh", + read: (o) => o.refresh === true, + where: ["service install"], + why: "It re-renders an existing unit, keeping the settings it carries.", + }, +]; + export function parseCommand(argv: string[]): Command { const command = dispatch(argv); - // `--force` overrides the busy check (SPEC §1, §4) and nothing else, so it - // only means anything on the two commands that run one. Rejecting it - // everywhere else, rather than parsing and dropping it, is the difference - // between being told and guessing: the two readings of a quiet - // `service uninstall --force` are "it overrode something" and "it did - // nothing", and the exit code is 0 either way. - // - // Checked here, once, rather than in each command: a second copy of this rule - // is a second chance for the two to drift apart about what `--force` means. - if ( - command.opts.force === true && - // `--help` wins, the same way it wins over a missing action above: asking - // for the usage is not a usage error. - !command.opts.help && - !(command.verb === "service" && (command.action === "stop" || command.action === "restart")) - ) { - const what = - command.verb === "service" && command.action !== undefined - ? `\`service ${command.action}\`` - : `\`${command.verb}\``; + // `--help` wins over every rule below, the same way it wins over a missing + // action above: asking for the usage is not a usage error. + if (command.opts.help) return command; + const said = + "action" in command && command.action !== undefined + ? `${command.verb} ${command.action}` + : command.verb; + for (const rule of SCOPED_FLAGS) { + if (!rule.read(command.opts)) continue; + if (rule.where.includes(said)) continue; + const quoted = rule.where.map((w) => `\`${w}\``); + const list = + quoted.length === 1 ? quoted[0] : `${quoted.slice(0, -1).join(", ")} and ${quoted.at(-1)}`; throw new UsageError( - `--force applies to \`service stop\` and \`service restart\` only, not ${what}.\n` + - "It overrides the busy check, and those are the two commands that run one.", + `${rule.flag} applies to ${list} only, not \`${said}\`.\n${rule.why}`, ); } return command; @@ -280,6 +373,12 @@ function dispatch(argv: string[]): Command { // a Docker container, a Watchtower pre-update hook, an Ansible task. if (first === "busy") return { verb: "busy", opts: parseArgs(rest) }; + // `update`, with `upgrade` accepted and undocumented (SPEC §1). + if (first === "update" || first === "upgrade") return { verb: "update", opts: parseArgs(rest) }; + + // `doctor` (SPEC §1). + if (first === "doctor") return { verb: "doctor", opts: parseArgs(rest) }; + // `serve` and `start` are one command: see VERBS. if (first === "serve" || first === "start") return { verb: "serve", opts: parseArgs(rest) }; @@ -351,10 +450,35 @@ export function parseArgs(argv: string[]): CliOptions { case "--include-env": opts.includeEnv = true; break; - // `service stop` / `service restart`: override the busy check (SPEC §4). + // `service stop` / `service restart` / `update`: override the busy check + // (SPEC §4). case "--force": opts.force = true; break; + // `update` flags (SPEC §1). + case "--check": + opts.checkOnly = true; + break; + case "--to": { + const v = next(); + if (v === "" || v.startsWith("-")) { + throw new UsageError(`${arg} needs a version or a dist-tag, got: ${JSON.stringify(v)}`); + } + opts.to = v; + break; + } + case "-y": + case "--yes": + opts.yes = true; + break; + // `service install --refresh` (SPEC §5 step 11). + case "--refresh": + opts.refresh = true; + break; + // `doctor --offline` (SPEC §1). + case "--offline": + opts.offline = true; + break; // `service logs` flags, the names `tail`, `journalctl` and every other // log reader uses — this is not the place to be original. case "-f": @@ -437,6 +561,8 @@ export const USAGE_SYNOPSIS = `Usage managers [serve] [options] run the server in this terminal managers service [options] install|uninstall|status|start|stop|restart|logs managers busy [--json] is the running instance busy? + managers update [--check] [--to ] install a newer Managers + managers doctor [--json] [--offline] checks, with a fix for each failure managers config [options] what this instance's config resolved to managers -v | --version print the version and exit managers -h | --help the full help`; @@ -458,6 +584,11 @@ Usage managers busy [--json] is it busy? exit 0 no, 75 yes, 3 nothing answering (\`managers busy --help\`) + managers update [--check] [--to ] install a newer Managers and restart + the service + (\`managers update --help\`) + managers doctor [--json] [--offline] checks, with a fix for each failure + (\`managers doctor --help\`) managers config show [--resolved] what this instance's config resolved to, and where each value came from managers config eject [--write] freeze that resolution into @@ -474,11 +605,14 @@ Options -h, --help Show this help Exit codes - 0 done; running and answering; not busy + 0 done; running and answering; up to date; not busy 1 failed 2 usage: an unknown command or flag, or a bad value 3 not running: installed, but not running or not answering; nothing answers 4 not installed: there is no service unit + 5 this install cannot update itself; the right command was printed (update) + 6 the update failed and was rolled back; the old version is back (update) + 7 the update failed and could not be rolled back; a person is needed 75 busy: refused, and why was printed. Try later, or use --force Opening your own directories @@ -588,6 +722,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 uninstall stop it and deregister it managers service status [--json] is it registered, is it running, which version, where are the logs @@ -603,6 +738,17 @@ Options (logs) Options (stop, restart) --force stop it even though it is busy +Options (install) + --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. + 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: + there is no unit to refresh, and doing a first + install with defaults instead is how a --port 9000 + service comes back on 7234. + 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 @@ -677,6 +823,35 @@ A note on access Docs: https://github.com/edspencer/managers`; +export const DOCTOR_USAGE = `managers doctor — is this install, its service and its configuration healthy? + +Usage + managers doctor the checks, one line each: ✓ ok, ! warning, ✗ failed + managers doctor --json the same checks as one JSON document + managers doctor --offline skip the one check that asks the npm registry + managers doctor -d check a particular instance's data dir + +Checks + node-engines this Node satisfies the package's engines + install-method how Managers was installed, and whether \`managers update\` can update it + unit the service unit: present, its Node and CLI still there + running-version the running version is the installed one + port the port is free, or held by Managers + linger (Linux) the service keeps running when you log out + data-home the data dir is writable + update a newer version exists (skipped with --offline) + config the configuration loads, so \`managers serve\` would start + security the security posture (/api/security): no authentication, + trusted-header, any-audience JWTs, batch drive mode + + Every failure has a \`fix:\` line under it. Asking the registry also refreshes + /update-check.json, which \`managers service status\` repeats. + +Exit codes + 0 nothing failed (warnings don't count) + 1 at least one check failed + 2 usage: an unknown flag`; + export const BUSY_USAGE = `managers busy — is the running instance in the middle of something? Usage @@ -834,3 +1009,106 @@ Reading nothing, writing nothing JWT signing material here to hide or reveal. Docs: https://github.com/edspencer/managers`; + + +/** + * `update`'s own synopsis, printed after a usage error from it (SPEC §2). + * + * `update` has one usage error of its own — "there is no terminal to ask, so + * `--yes` is required" — and the contract says the usage follows the message. + * {@link USAGE_SYNOPSIS} is the wrong text there: it lists every command, and + * the reader's problem is one flag on the command they already typed. + */ +export const UPDATE_SYNOPSIS = `Usage + managers update [--yes] install the latest release + managers update --check [--json] what a new version would be; changes nothing + managers update --to a particular version, or a dist-tag + managers update --force skip the busy check, and nothing else + managers update --help the full help`; + +export const UPDATE_USAGE = `managers update — install a newer Managers, and put the service back up + +Usage + managers update update to the latest release, asking first + managers update --check what a new version would be; changes nothing + managers update --yes do not ask (required when there is no terminal) + managers update --to 0.79.1 a particular version — the only way to go BACK + managers update --to next a dist-tag + managers update --json one JSON document on stdout + +Options + --check Ask the registry, report, and change nothing. Exits 0 + whether or not there is an update — scripts read + \`updateAvailable\` from --json + --to Install this version or dist-tag instead of latest. + Required to move to a LOWER version: an update never + goes backwards by accident + --yes, -y Skip the question. Required when stdin is not a + terminal, where a command that would have asked exits + 2 rather than guessing + --force Skip the busy check, and nothing else — the health + check and the rollback still run + --json One JSON document on stdout; all prose on stderr + -h, --help Show this help + +What it does, in order + 1 takes /update.lock, so two updates cannot interleave + 2 works out how this copy was installed (see "Installs that cannot update + themselves" below) + 3 asks the registry for the target version and its \`engines.node\` + 4 compares, and stops here with --check + 5 checks the global folder is writable, and prints a sudo line if not. + It never runs sudo itself + 6 asks the running instance whether it is BUSY — before anything is stopped + 7 asks you, unless --yes + 8 fetches both the new and the current version into the npm cache, while + the old version is still serving, so a rollback has its package to hand + 9 stops the service + 10 installs with the package manager this copy came from + 11 hands over to the NEW CLI, which re-writes the service unit + (\`service install --refresh\`) and starts it + 12 waits for /api/health to report the version it just installed + 13 and if any of 10–12 fails, puts the old version back + +Exit codes — this command is FOR its exit code + 0 updated, or already up to date, or --check reported + 1 something failed, and nothing had been stopped yet + 2 usage — including "there is no terminal to ask, so --yes is required" + 5 this install cannot update itself. The right command was printed + 6 the new version did not start; the old one is running again + 7 the new version did not start and the old one could not be restored. + The commands to run by hand were printed + 75 busy: a chat turn, a background task or a scheduled job is running. + Wait, or --force + +Installs that cannot update themselves (exit 5) + Managers reads where it is running from, and five layouts are not ours to + replace. Each prints the command that WOULD work: + + a container image docker compose pull && docker compose up -d + a managed install whatever MANAGERS_UPDATE_HINT says + npx / pnpm dlx npx @edspencer/managers@latest already runs the latest + a checkout git pull && npm install && npm run build + a project dependency update it in that project + a yarn classic global yarn global add @edspencer/managers + + A global npm, pnpm, bun or volta install updates in place. + +Where it runs from + From a terminal, never from inside the service. An updater the service + started — a Managers chat, say — is in the service's own process group, so + stopping the service kills the updater half way through step 9. The busy + check refuses first and says so; --force from inside a chat would stop the + service running that chat, which then never gets to report what happened. + +Asking the registry + Only \`update\`, \`update --check\` and \`doctor\` ever contact the npm + registry, and only when you run them. There is no background check and no + check at startup; the server never asks. What the last check found is cached + in /update-check.json, which is what \`managers service status\` + repeats — it never asks itself. + + The registry is \`npm_config_registry\`, else \`npm config get registry\`, + else https://registry.npmjs.org. + +Docs: https://github.com/edspencer/managers`; diff --git a/packages/server/src/cli/busy-command.ts b/packages/server/src/cli/busy-command.ts index c149d57..eccba57 100644 --- a/packages/server/src/cli/busy-command.ts +++ b/packages/server/src/cli/busy-command.ts @@ -125,5 +125,5 @@ export async function guardServiceBusy( if (refusal === null) return null; // Spell out the way past it, after the hint about where to run it from. out.warn(`\n managers service ${action} --force ${action} it anyway\n`); - return EXIT.busy; + return EXIT.BUSY; } diff --git a/packages/server/src/cli/busy.ts b/packages/server/src/cli/busy.ts index 446f3d0..255a850 100644 --- a/packages/server/src/cli/busy.ts +++ b/packages/server/src/cli/busy.ts @@ -1,10 +1,8 @@ -// From edspencer/cli-contract reference/busy-client.ts @ SPEC 0.1; local changes: `.ts` import specifiers → `.js` -// and `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); `EXIT.OK` / -// `EXIT.BUSY` / `EXIT.NOT_RUNNING` / `EXIT.FAILED` → Managers' lowercase `EXIT.ok` / `busy` / `notRunning` / -// `failure` (see `exit-codes.ts`, which wave C4 re-syncs); and `hint` widened from a string to -// `string | ((result) => string | undefined)`, with {@link runBusyCommand} printing it too — that is what carries -// Managers' keeper-chat trap (ROADMAP "Busy, per tool"), where the line to print depends on WHICH counts are -// non-zero, so a fixed string could not say it. +// From edspencer/cli-contract reference/busy-client.ts @ 0.2; local changes: `.ts` import specifiers → `.js` and +// `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); and `hint` widened +// from a string to `string | ((result) => string | undefined)`, with {@link runBusyCommand} printing it too — that is +// what carries Managers' keeper-chat trap (ROADMAP "Busy, per tool"), where the line to print depends on WHICH counts +// are non-zero, so a fixed string could not say it. // // The CLI's side of the busy check (SPEC §4): find the running instance through `/runtime.json`, ask its // `/api/busy`, and map the answer to exit 0 (idle), 75 (busy) or 3 (nothing answers), with §4's messages. @@ -115,13 +113,13 @@ export function busyMessage(name: string, result: BusyResult, nouns: Nouns = {}) export function busyExitCode(result: BusyResult): number { switch (result.state) { case "idle": - return EXIT.ok; + return EXIT.OK; case "busy": - return EXIT.busy; + return EXIT.BUSY; case "not-running": - return EXIT.notRunning; + return EXIT.NOT_RUNNING; case "unknown": - return EXIT.failure; + return EXIT.FAILED; } } @@ -193,5 +191,5 @@ export async function guardBusy(o: GuardOptions): Promise { return null; } const hint = resolveHint(o.hint, result) ?? "Try again once it has finished, or use --force."; - return o.out.error(`${message} ${hint}`, EXIT.busy); + return o.out.error(`${message} ${hint}`, EXIT.BUSY); } diff --git a/packages/server/src/cli/doctor.ts b/packages/server/src/cli/doctor.ts new file mode 100644 index 0000000..0de13d5 --- /dev/null +++ b/packages/server/src/cli/doctor.ts @@ -0,0 +1,550 @@ +/** + * `managers doctor [--json] [--offline]` — CLI contract SPEC §1's checks, one + * `✓` / `!` / `✗` line each, with a `fix:` line under every failure. Exit 1 if + * any check failed; warnings don't change it. + * + * Modelled on Local Review's `server/doctor.ts` (D2b), against Managers' own + * service layer: the unit checks are the warnings `service status` already + * computes (one `StatusReport`, so the two can never disagree). + * + * The spec's eight ids come first, in its order: `node-engines`, + * `install-method`, `unit`, `running-version`, `port`, `linger`, `data-home`, + * `update`. Then Managers' own: + * + * - **`config`** — the configuration this shell resolves loads at all. A + * config `serve` would refuse is the likeliest reason a service that was + * installed fine never comes up. + * - **`security`** — `/api/security`'s checks, folded in (ROADMAP: "doctor, + * with `/api/security`'s checks"). One line per dangerous setting the + * instance runs with — no authentication, `trusted-header`, a JWT with any + * audience, batch drive mode — each a warning, because every one of them is + * an explicit opt-in rather than a mistake. A running instance is asked + * (its answer is the truth about what IT booted with); with none running, + * the posture this shell's configuration would boot with is computed by the + * same `evaluateBootPosture` the server runs, and a configuration the server + * would refuse is a failure. + * + * It only reads, apart from `/update-check.json`: like + * `update --check`, it writes what it found there, so `service status` can + * repeat it (SPEC §3). It asks the npm registry only because a person ran it, + * and `--offline` doesn't. + */ +import { execFile } from "node:child_process"; +import fs from "node:fs"; +import net from "node:net"; +import os from "node:os"; +import path from "node:path"; +import { + describeInstall, + detectInstall, + findPackageRoot, + updateCommand, + type InstallInfo, +} from "./update/install-method.js"; +import { fetchHealth } from "./update/health.js"; +import { npmConfigGet, npmGlobalRoot } from "./update/package-manager.js"; +import { RegistryError, resolveRegistry, resolveTarget } from "./update/registry.js"; +import { readLiveRuntimeFile } from "../runtime-file.js"; +import { compareVersions, isPrerelease, satisfiesEngines } from "./update/semver.js"; +import { updateNotice, writeUpdateCheck } from "./update/update-check.js"; +import { MANAGERS_IMAGE, MANAGERS_PACKAGE, managersChangelogUrl } from "./update-command.js"; +import { DEFAULT_PORT } from "./service/spec.js"; +import { serviceStatusReport, type ServiceContext, type StatusReport } from "./service/index.js"; +import type { PostureWarning } from "../boot-posture.js"; + +export type CheckStatus = "pass" | "warn" | "fail" | "skip"; + +export interface Check { + /** Stable, for scripts: the spec's eight, then `config` and `security`. */ + id: string; + status: CheckStatus; + message: string; + fix?: string; +} + +const MARK: Record = { pass: "✓", warn: "!", fail: "✗", skip: "-" }; + +/** The fallback when the package's own `engines` can't be read (a checkout, a test). */ +const ENGINES_FALLBACK = ">=22"; + +/** What the server's posture says, or why it couldn't be read. */ +export type SecurityReading = + | { kind: "answer"; warnings: PostureWarning[]; authMode?: string } + | { kind: "auth-required" } + | { kind: "refused"; message: string } + | { kind: "unknown"; message: string }; + +export interface DoctorInput { + ctx: ServiceContext; + /** This CLI's version. */ + version: string; + /** This invocation's data dir (`--data-dir`, `MANAGERS_DATA_DIR`, else `~/.managers`). */ + dataDir: string; + /** `process.argv[1]`, for SPEC §6's walk-up. */ + entry: string; + env: NodeJS.ProcessEnv; + offline?: boolean; + // ---- seams, for tests ------------------------------------------------- + nodeVersion?: string; + /** The package's `engines.node`; read from its package.json when omitted. */ + engines?: string; + npmGlobalRoot?: () => string | undefined; + registry?: string; + fetch?: typeof fetch; + isListening?: (port: number) => Promise; + /** Linux's linger for this user: true, false, or null when loginctl can't say. */ + linger?: () => Promise; + /** The service report; `serviceStatusReport(ctx)` when omitted. */ + status?: () => Promise; + /** Whether the configuration this shell resolves loads: undefined, or why not. */ + configProblem?: () => Promise; + /** The posture this shell's configuration would boot with (no instance running). */ + localPosture?: () => Promise; +} + +const tildify = (p: string, home: string): string => + p === home ? "~" : p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p; + +export async function diagnose(i: DoctorInput): Promise<{ checks: Check[]; notice?: string }> { + const checks: Check[] = []; + const add = (c: Check): void => { + checks.push(c); + }; + const t = (p: string): string => tildify(p, i.ctx.homeDir); + const doFetch = i.fetch ?? fetch; + let notice: string | undefined; + + // ---- this Node against the package's engines + const nodeVersion = i.nodeVersion ?? process.versions.node; + const enginesRange = i.engines ?? packageEngines(i.entry) ?? ENGINES_FALLBACK; + const engines = satisfiesEngines(nodeVersion, { node: enginesRange }); + if (engines.ok === false) { + add({ + id: "node-engines", + status: "fail", + message: `Node ${nodeVersion} is too old: Managers ${i.version} needs Node ${enginesRange}`, + fix: `install Node ${enginesRange} (nvm, fnm, Homebrew, …), then run managers with it`, + }); + } else { + add({ id: "node-engines", status: "pass", message: `Node ${nodeVersion} (Managers needs ${enginesRange})` }); + } + + // ---- how it was installed (SPEC §6) + const info: InstallInfo = detectInstall({ + packageName: MANAGERS_PACKAGE, + envPrefix: "MANAGERS", + entry: i.entry, + env: i.env, + npmGlobalRoot: i.npmGlobalRoot ?? (() => npmGlobalRoot({ env: i.env })), + }); + const how = describeInstall(info, MANAGERS_PACKAGE); + if (info.canUpdate) { + add({ + id: "install-method", + status: "pass", + message: `Managers ${i.version}, ${how}: \`managers update\` can update it`, + }); + } else { + const cmd = updateCommand(info, { packageName: MANAGERS_PACKAGE, image: MANAGERS_IMAGE }); + add({ + id: "install-method", + status: "warn", + message: `Managers ${i.version}, ${how}: \`managers update\` can't update it`, + fix: `${cmd.command}${cmd.note ? ` (${cmd.note})` : ""}`, + }); + } + + // ---- the service: what `service status` warns about + let report: StatusReport | null = null; + try { + report = await (i.status ?? (() => serviceStatusReport(i.ctx)))(); + } catch (e) { + add({ id: "unit", status: "skip", message: (e as Error).message.split("\n")[0] ?? String(e) }); + } + if (report && !report.installed) { + add({ + id: "unit", + status: "skip", + message: "it isn't installed as a service (`managers service install` runs it in the background)", + }); + } else if (report) { + // The running-version and linger warnings have checks of their own below. + const warnings = report.warnings.filter((w) => !/^It is running /.test(w) && !/^Lingering is off/.test(w)); + if (warnings.length === 0) { + add({ id: "unit", status: "pass", message: `the service is installed (${report.manager}): ${t(report.unit)}` }); + } + for (const w of warnings) { + add( + /not there any more/.test(w) + ? { id: "unit", status: "fail", message: w, fix: "`managers service install` (it keeps the port and the data dir)" } + : { id: "unit", status: "warn", message: w }, + ); + } + } + + // ---- the running version is the installed one: the service's, or a `serve` in a terminal + const home = report?.installed && report.dataDir ? report.dataDir : i.dataDir; + const live = readLiveRuntimeFile(home); + const running = + report?.answering === true + ? { version: report.runningVersion, where: report.url ?? "the service", installed: report.installedVersion, via: "service" as const } + : live + ? { version: live.version, where: live.url, installed: i.version, via: "serve" as const } + : null; + if (!running) { + add({ id: "running-version", status: "skip", message: "Managers isn't running" }); + } else if (running.version && running.installed && running.version !== running.installed) { + add({ + id: "running-version", + status: "fail", + message: `${running.where} is running ${running.version}, but ${running.installed} is installed: it's still running the code it started with`, + fix: + running.via === "service" + ? "`managers service restart`" + : "stop the `managers serve` in its terminal (Ctrl-C) and start it again", + }); + } else { + add({ + id: "running-version", + status: "pass", + message: `${running.where} is running ${running.version ?? "an unknown version"}${running.via === "serve" ? " (in a terminal)" : ""}`, + }); + } + + // ---- the port: free, or held by Managers + const port = report?.port ?? live?.port ?? Number(DEFAULT_PORT); + const listening = await (i.isListening ?? defaultIsListening)(port); + const health = listening ? await fetchHealth({ url: `http://127.0.0.1:${port}`, fetch: doFetch }) : undefined; + if (!listening) add({ id: "port", status: "pass", message: `port ${port} is free` }); + else if (health) { + add({ id: "port", status: "pass", message: `port ${port} is Managers'${health.version ? ` (${health.version})` : ""}` }); + } else { + add({ + id: "port", + status: "fail", + message: `something that isn't Managers is listening on port ${port}`, + fix: report?.installed + ? "stop it, or move the service: `managers service install --port `" + : "stop it, or run Managers on another port: `managers serve --port `", + }); + } + + // ---- linger, on Linux: without it the service stops when you log out + if (i.ctx.platform !== "linux") add({ id: "linger", status: "skip", message: "linger is a Linux thing" }); + else { + const user = i.env.USER || safeUser(); + const on = await (i.linger ?? (() => lingerOf(user)))(); + if (on === true) { + add({ id: "linger", status: "pass", message: `linger is on for ${user}: the service runs while you're logged out, and starts at boot` }); + } else if (on === false && report?.installed) { + add({ + id: "linger", + status: "warn", + message: `linger is off for ${user}: the service stops when you log out, and starts only when you log in`, + fix: `sudo loginctl enable-linger ${user}`, + }); + } else if (on === false) { + add({ id: "linger", status: "pass", message: `linger is off for ${user}, which only matters once it's a service (then: sudo loginctl enable-linger ${user})` }); + } else add({ id: "linger", status: "skip", message: "couldn't ask loginctl about linger" }); + } + + // ---- the data dir + const writable = writableOrCreatable(home); + if (writable === true) add({ id: "data-home", status: "pass", message: `the data dir ${t(home)} is writable` }); + else if (writable === "creatable") { + add({ id: "data-home", status: "pass", message: `the data dir ${t(home)} doesn't exist yet; it's made the first time Managers starts` }); + } else { + add({ + id: "data-home", + status: "fail", + message: `the data dir ${t(home)} isn't writable: ${writable}`, + fix: "check its permissions, or use another one with --data-dir (or MANAGERS_DATA_DIR)", + }); + } + + // ---- a newer version (SPEC §1): the only check that asks the network, and --offline skips it + if (i.offline) add({ id: "update", status: "skip", message: "not asking the registry for a newer version (--offline)" }); + else { + try { + const target = await resolveTarget({ + packageName: MANAGERS_PACKAGE, + registry: i.registry ?? resolveRegistry(i.env, (k) => npmConfigGet(k, { env: i.env })), + fetch: doFetch, + }); + const cmp = compareVersions(target.version, i.version); + const available = cmp > 0 && !isPrerelease(target.version); + const cmd = info.canUpdate + ? { command: "managers update" } + : updateCommand(info, { packageName: MANAGERS_PACKAGE, target: target.version, image: MANAGERS_IMAGE }); + try { + // The cache `service status` repeats. Never creates the data dir: a + // doctor run on a machine that has never started Managers is a reading, + // not a first start. + if (fs.existsSync(home)) { + writeUpdateCheck(home, { + name: "managers", + current: i.version, + target: target.version, + tag: target.tag, + updateAvailable: available, + installMethod: info.method, + canUpdate: info.canUpdate, + command: available ? cmd.command : null, + engines: target.engines, + nodeOk: satisfiesEngines(nodeVersion, target.engines !== null ? { node: target.engines } : undefined).ok !== false, + changelog: managersChangelogUrl(target.version), + checkedAt: new Date().toISOString(), + }); + } + } catch { + /* a cache that can't be written is not a doctor finding */ + } + if (available) { + notice = updateNotice({ + name: "Managers", + current: i.version, + target: target.version, + command: cmd.command, + ...(cmd.note ? { note: cmd.note } : {}), + changelog: managersChangelogUrl(target.version), + }); + add({ id: "update", status: "warn", message: `Managers ${target.version} is available (you have ${i.version})`, fix: cmd.command }); + } else { + add({ + id: "update", + status: "pass", + message: cmp < 0 ? `${i.version} is newer than the registry's latest (${target.version})` : `${i.version} is the latest`, + }); + } + } catch (e) { + add({ + id: "update", + status: "warn", + message: `couldn't ask the registry for a newer version: ${e instanceof RegistryError ? `${e.message} (${e.url})` : (e as Error).message}`, + fix: "check your network, or skip this check with --offline", + }); + } + } + + // ---- Managers' own: the configuration loads + const configProblem = await (i.configProblem ?? (() => defaultConfigProblem(i.dataDir)))(); + if (configProblem === undefined) { + add({ id: "config", status: "pass", message: "the configuration loads (`managers config show` prints it)" }); + } else { + add({ + id: "config", + status: "fail", + message: `the configuration won't load, so \`managers serve\` would refuse to start: ${configProblem}`, + fix: "`managers config show` names the setting; fix it in managers.config.yaml or the environment", + }); + } + + // ---- Managers' own: /api/security's checks + const security = await readSecurity({ + url: running?.where.startsWith("http") ? running.where : undefined, + fetch: doFetch, + local: i.localPosture ?? (() => defaultLocalPosture(i.dataDir, i.env)), + skipLocal: configProblem !== undefined, + }); + const where = running?.where.startsWith("http") ? `${running.where} runs` : "this configuration would run"; + if (security.kind === "auth-required") { + add({ id: "security", status: "pass", message: `${running?.where ?? "the instance"} requires authentication` }); + } else if (security.kind === "refused") { + add({ + id: "security", + status: "fail", + message: `\`managers serve\` would refuse this configuration: ${security.message}`, + fix: "set MANAGERS_AUTH_MODE=jwt (see AUTH.md); with no auth, `managers serve` runs only on a loopback bind (--host 127.0.0.1, and no HOST=0.0.0.0 in the environment)", + }); + } else if (security.kind === "unknown") { + add({ id: "security", status: "skip", message: `couldn't read the security posture: ${security.message}` }); + } else if (security.warnings.length === 0) { + add({ id: "security", status: "pass", message: `${where} with authentication on, and no dangerous setting opted into` }); + } else { + for (const w of security.warnings) { + add({ id: "security", status: "warn", message: `${where} with ${w.title}: ${w.detail}`, fix: securityFix(w) }); + } + } + + return { checks, ...(notice ? { notice } : {}) }; +} + +function securityFix(w: PostureWarning): string { + switch (w.code) { + case "no-auth": + return "set MANAGERS_AUTH_MODE=jwt (see AUTH.md) to close it; it's the laptop default on a loopback bind"; + case "trusted-header": + return "prefer MANAGERS_AUTH_MODE=jwt, which a process on this host can't forge (see AUTH.md)"; + case "jwt-any-audience": + return "set MANAGERS_AUTH_JWT_AUDIENCE and drop MANAGERS_AUTH_JWT_ALLOW_ANY_AUDIENCE"; + case "batch-drive": + return "drop MANAGERS_DRIVE_MODE=batch and MANAGERS_ALLOW_BATCH_DRIVE, so turns run on the SDK session runtime"; + } +} + +/** Ask the running instance's `/api/security`, else compute the posture this shell would boot with. */ +async function readSecurity(o: { + url: string | undefined; + fetch: typeof fetch; + local: () => Promise; + skipLocal: boolean; +}): Promise { + if (o.url !== undefined) { + try { + const res = await o.fetch(new URL("/api/security", o.url), { signal: AbortSignal.timeout(3_000) }); + if (res.status === 401 || res.status === 403) return { kind: "auth-required" }; + if (res.ok) { + const body = (await res.json()) as { warnings?: PostureWarning[]; authMode?: string }; + return { + kind: "answer", + warnings: Array.isArray(body.warnings) ? body.warnings : [], + ...(body.authMode !== undefined ? { authMode: body.authMode } : {}), + }; + } + // An older Managers (404) falls through to the local reading. + } catch { + /* not answering: fall through */ + } + } + if (o.skipLocal) return { kind: "unknown", message: "the configuration doesn't load (see the config check)" }; + return o.local(); +} + +/** The posture `serve` would boot with from this shell, by the server's own rule (boot-posture.ts). */ +async function defaultLocalPosture(dataDir: string, env: NodeJS.ProcessEnv): Promise { + try { + const cfg = await loadConfigFor(dataDir); + const { bootPostureInput, evaluateBootPosture } = await import("../boot-posture.js"); + // The CLI's laptop default (start.ts `loopbackNoAuth`): allowed when nobody + // set MANAGERS_DANGEROUSLY_ALLOW_NO_AUTH either way. + const d = evaluateBootPosture( + bootPostureInput(cfg, { loopbackNoAuth: env.MANAGERS_DANGEROUSLY_ALLOW_NO_AUTH === undefined }), + ); + if (d.action === "refuse") { + return { kind: "refused", message: `${d.message.split("\n")[0] ?? d.message} (bind address: ${cfg.host})` }; + } + return { kind: "answer", warnings: d.posture.warnings, authMode: d.posture.authMode }; + } catch (e) { + return { kind: "unknown", message: (e as Error).message.split("\n")[0] ?? String(e) }; + } +} + +async function defaultConfigProblem(dataDir: string): Promise { + try { + await loadConfigFor(dataDir); + return undefined; + } catch (e) { + return (e as Error).message.split("\n")[0] ?? String(e); + } +} + +/** + * Resolve the configuration the way `managers config show` does — for THIS + * data dir, creating nothing. The environment variable is set and restored + * around the call because `loadPaddockConfig` reads it. + */ +async function loadConfigFor(dataDir: string) { + const { loadPaddockConfig } = await import("../config.js"); + const before = process.env.MANAGERS_DATA_DIR; + process.env.MANAGERS_DATA_DIR = dataDir; + try { + return loadPaddockConfig({ createDataDir: false }); + } finally { + if (before === undefined) delete process.env.MANAGERS_DATA_DIR; + else process.env.MANAGERS_DATA_DIR = before; + } +} + +/** `engines.node` from the installed package's own package.json, when it can be found. */ +function packageEngines(entry: string): string | undefined { + try { + const { root } = findPackageRoot(entry, MANAGERS_PACKAGE, fs); + if (root === undefined) return undefined; + const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as { + name?: string; + engines?: { node?: string }; + }; + return pkg.name === MANAGERS_PACKAGE ? pkg.engines?.node : undefined; + } catch { + return undefined; + } +} + +/** The checklist, for a person. */ +export function renderChecks(checks: Check[]): string { + return ( + checks + .map( + (c) => + `${MARK[c.status]} ${c.message}${c.fix && c.status !== "pass" && c.status !== "skip" ? `\n fix: ${c.fix}` : ""}`, + ) + .join("\n") + "\n" + ); +} + +export const doctorCode = (checks: Check[]): number => (checks.some((c) => c.status === "fail") ? 1 : 0); + +/** True if `dir` is writable; 'creatable' if it doesn't exist but its nearest existing parent is; else why not. */ +export function writableOrCreatable(dir: string): true | "creatable" | string { + let probe = dir; + while (!fs.existsSync(probe)) { + const parent = path.dirname(probe); + if (parent === probe) return "no part of it exists"; + probe = parent; + } + try { + if (!fs.statSync(probe).isDirectory()) return `${probe} isn't a directory`; + fs.accessSync(probe, fs.constants.W_OK); + return probe === dir ? true : "creatable"; + } catch (e) { + return (e as Error).message; + } +} + +const defaultIsListening = (port: number): Promise => + new Promise((resolve) => { + const s = net.connect({ port, host: "127.0.0.1" }); + s.setTimeout(1000); + s.once("connect", () => { + s.destroy(); + resolve(true); + }); + s.once("timeout", () => { + s.destroy(); + resolve(false); + }); + s.once("error", () => resolve(false)); + }); + +function safeUser(): string { + try { + return os.userInfo().username; + } catch { + return "$USER"; + } +} + +/** `loginctl show-user -p Linger`: true, false, or null when it can't say (no loginctl, no logind). */ +export function lingerOf(user: string): Promise { + return new Promise((resolve) => { + execFile("loginctl", ["show-user", user, "-p", "Linger"], { timeout: 5000 }, (err, stdout) => { + const m = /^Linger=(yes|no)$/m.exec(String(stdout ?? "")); + resolve(err || !m ? null : m[1] === "yes"); + }); + }); +} + +/** `managers doctor` as a command: the checklist, or one JSON document, and the exit code. */ +export async function runDoctor(i: DoctorInput & { json?: boolean }): Promise { + const { checks, notice } = await diagnose(i); + const code = doctorCode(checks); + if (i.json) { + // Exactly one JSON document on stdout (SPEC §3); the notice is prose, so stderr. + process.stdout.write(JSON.stringify({ ok: code === 0, version: i.version, checks }, null, 2) + "\n"); + } else { + process.stdout.write(renderChecks(checks)); + } + if (notice) process.stderr.write(`\n${notice}\n`); + return code; +} + diff --git a/packages/server/src/cli/exit-codes.ts b/packages/server/src/cli/exit-codes.ts index 5ee04e1..938ee13 100644 --- a/packages/server/src/cli/exit-codes.ts +++ b/packages/server/src/cli/exit-codes.ts @@ -1,50 +1,49 @@ -/** - * The CLI contract's exit codes (SPEC §2), as constants. - * - * From edspencer/cli-contract SPEC.md §2 @ 0.1. Written here rather than copied - * from `reference/exit-codes.ts` because the reference module did not exist yet - * when Managers aligned; wave C4 re-syncs this file to it and adds the usual - * provenance header. The numbers, and what each means, are the contract. - * - * | 0 | done; running and answering; up to date; not busy - * | 1 | failed - * | 2 | usage: an unknown command or flag, a bad value - * | 3 | not running: installed but not running or not answering - * | 4 | not installed: there is no service unit - * | 5 | this install cannot update itself (`update`, not yet built) - * | 6 | the update failed and was rolled back (`update`, not yet built) - * | 7 | the update failed and could not be rolled back - * | 75 | busy: refused, and why was printed (`busy`, not yet built) - * - * Codes 3 and 4 are what `systemctl status` and LSB init scripts use for "not - * running" and "no such service", so a script that already branches on them - * keeps working. 75 is `EX_TEMPFAIL` from `sysexits.h`, which is also the code - * that makes Watchtower's pre-update hook skip an update. - * - * The three `update` codes are declared now and unused until wave C2. They are - * here because the contract's whole point is that the numbers mean the same - * thing in every tool: adding them later, from a different file, is how two - * tools end up disagreeing about what 5 means. - */ +// From edspencer/cli-contract reference/exit-codes.ts @ 0.2; local changes: none. +// The exit codes every tool shares (SPEC §2). Copy this file; don't renumber it. +// +// Set `process.exitCode`, never call `process.exit()`, so piped output isn't cut short. + export const EXIT = { - /** Done. Running and answering. Up to date. Not busy. */ - ok: 0, - /** Failed — the catch-all. */ - failure: 1, - /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */ - usage: 2, - /** Not running: installed, but not running or not answering. */ - notRunning: 3, - /** Not installed: there is no service unit. */ - notInstalled: 4, - /** This install cannot update itself; the right command was printed. */ - cannotSelfUpdate: 5, + /** Done; running and answering; up to date; not busy. */ + OK: 0, + /** Failed. */ + FAILED: 1, + /** Usage: an unknown command or flag, a bad value. The usage is printed after the message. */ + USAGE: 2, + /** Not running: installed but not running or not answering, or no instance answers. */ + NOT_RUNNING: 3, + /** Not installed: there's no service unit. */ + NOT_INSTALLED: 4, + /** This install can't update itself; the right command was printed. */ + CANNOT_UPDATE: 5, /** The update failed and was rolled back; the old version is running again. */ - rolledBack: 6, - /** The update failed and could not be rolled back; a person is needed. */ - needsHuman: 7, - /** Busy: refused, and why was printed. Try later, or use `--force`. */ - busy: 75, + ROLLED_BACK: 6, + /** The update failed and couldn't be rolled back; a person is needed. */ + ROLLBACK_FAILED: 7, + /** Busy: refused, and why was printed. Try later, or use `--force`. `EX_TEMPFAIL` from sysexits.h. */ + BUSY: 75, } as const; export type ExitCode = (typeof EXIT)[keyof typeof EXIT]; + +/** A tool may use 8 to 63 for its own commands (SPEC §2). */ +export function isToolOwnCode(code: number): boolean { + return Number.isInteger(code) && code >= 8 && code <= 63; +} + +/** The SPEC's name for a shared code, for messages ("expected 4 (not installed), got 0 (ok)"). */ +export function describeExitCode(code: number | null): string { + if (code === null) return 'no exit code (killed by a signal)'; + const names: Record = { + 0: 'ok', + 1: 'failed', + 2: 'usage', + 3: 'not running', + 4: 'not installed', + 5: "can't update itself", + 6: 'rolled back', + 7: "couldn't roll back", + 75: 'busy', + }; + return names[code] ? `${code} (${names[code]})` : String(code); +} diff --git a/packages/server/src/cli/managers.ts b/packages/server/src/cli/managers.ts index 23b6dc3..2cb876a 100644 --- a/packages/server/src/cli/managers.ts +++ b/packages/server/src/cli/managers.ts @@ -33,12 +33,14 @@ import { SERVICE_USAGE, CONFIG_USAGE, BUSY_USAGE, + UPDATE_USAGE, + DOCTOR_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js"; import { EXIT } from "./exit-codes.js"; -import { runService, safeHomeDir, realpathOr } from "./service/index.js"; +import { runService, safeHomeDir, realpathOr, type ServiceContext } from "./service/index.js"; import { MANAGERS_NAME, MANAGERS_VERSION } from "../version.js"; /** @@ -93,9 +95,9 @@ const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../.."); * says the usage follows the message — the short one, not {@link USAGE}'s * thousand words, which would bury the line that says what was wrong. */ -function fail(message: string, code: number = EXIT.failure): number { +function fail(message: string, code: number = EXIT.FAILED): number { console.error(`managers: ${message}`); - if (code === EXIT.usage) { + if (code === EXIT.USAGE) { console.error(""); console.error(USAGE_SYNOPSIS); } @@ -193,28 +195,10 @@ async function service(command: Extract): Promise< // which `main` has already handled. Typed rather than asserted. if (action === undefined) { console.log(SERVICE_USAGE); - return EXIT.ok; + return EXIT.OK; } try { - return await runService(action, opts, { - platform: process.platform, - // Realpath'd (SPEC §7). `process.execPath` under a version manager is - // routinely a symlink into a per-shell directory — fnm's - // `fnm_multishells/_/bin/node` is deleted when that terminal - // exits — so a unit naming the symlink stops working when the tab closes, - // at some later login, with nothing in the logs because it never ran. - nodePath: realpathOr(process.execPath), - scriptPath: entryScript, - packageRoot, - homeDir: safeHomeDir(), - ...(process.env.MANAGERS_DATA_DIR !== undefined - ? { envDataDir: process.env.MANAGERS_DATA_DIR } - : {}), - ...(process.env.XDG_CONFIG_HOME !== undefined - ? { xdgConfigHome: process.env.XDG_CONFIG_HOME } - : {}), - ...(process.env.PATH !== undefined ? { pathEnv: process.env.PATH } : {}), - }); + return await runService(action, opts, serviceContext()); } catch (err) { // A CliError carries its own code: an unsupported platform or an npx // refusal is a failure (1), a misspelled flag is usage (2). @@ -224,6 +208,36 @@ async function service(command: Extract): Promise< } } +/** + * The facts about THIS install that every unit-reading command needs. + * + * One function, used by `managers service` and by `managers update`, because the + * two have to agree: an `update` that refreshed a unit built from a different + * Node path or a different script than `service status` reports would be the + * worst kind of nearly-working. + */ +function serviceContext(): ServiceContext { + return { + platform: process.platform, + // Realpath'd (SPEC §7). `process.execPath` under a version manager is + // routinely a symlink into a per-shell directory — fnm's + // `fnm_multishells/_/bin/node` is deleted when that terminal + // exits — so a unit naming the symlink stops working when the tab closes, + // at some later login, with nothing in the logs because it never ran. + nodePath: realpathOr(process.execPath), + scriptPath: entryScript, + packageRoot, + homeDir: safeHomeDir(), + ...(process.env.MANAGERS_DATA_DIR !== undefined + ? { envDataDir: process.env.MANAGERS_DATA_DIR } + : {}), + ...(process.env.XDG_CONFIG_HOME !== undefined + ? { xdgConfigHome: process.env.XDG_CONFIG_HOME } + : {}), + ...(process.env.PATH !== undefined ? { pathEnv: process.env.PATH } : {}), + }; +} + /** * Which instance this invocation is about: an explicit flag, else the * environment, else `~/.managers`. @@ -254,13 +268,13 @@ async function config(command: Extract): Promise { ? CONFIG_USAGE : command.verb === "busy" ? BUSY_USAGE - : USAGE, + : command.verb === "update" + ? UPDATE_USAGE + : command.verb === "doctor" + ? DOCTOR_USAGE + : USAGE, ); - return EXIT.ok; + return EXIT.OK; } if (opts.version) { // Bare: the version and a newline, nothing else (SPEC §1). Scripts parse this. console.log(MANAGERS_VERSION); - return EXIT.ok; + return EXIT.OK; } const problem = nodeVersionProblem(process.versions.node); @@ -318,6 +336,43 @@ async function main(): Promise { return runBusy(resolveDataDir(opts), opts.json === true); } + // `update` (SPEC §1, §5). Imported dynamically for the same reason `busy` is: + // nothing in it needs the server, and a command whose whole job is to replace + // the files it would have loaded has particularly good reason not to load + // them. + if (command.verb === "update") { + const { runUpdateCommand } = await import("./update-command.js"); + try { + return await runUpdateCommand(opts, serviceContext()); + } catch (err) { + if (err instanceof CliError) return fail(err.message, err.exitCode); + if (err instanceof Error) return fail(err.message); + throw err; + } + } + + // `doctor` (SPEC §1). Its checks read the service layer and the update + // modules; the configuration and security checks import the config loader + // themselves, lazily. + if (command.verb === "doctor") { + const { runDoctor } = await import("./doctor.js"); + try { + return await runDoctor({ + ctx: serviceContext(), + version: MANAGERS_VERSION, + dataDir: resolveDataDir(opts), + entry: process.argv[1] ?? entryScript, + env: process.env, + ...(opts.offline === true ? { offline: true } : {}), + ...(opts.json === true ? { json: true } : {}), + }); + } catch (err) { + if (err instanceof CliError) return fail(err.message, err.exitCode); + if (err instanceof Error) return fail(err.message); + throw err; + } + } + addBundledBinsToPath(); // NOTHING here reads `process.cwd()`, and that is the point (#798). `--here` @@ -425,7 +480,7 @@ async function main(): Promise { // 0, but NOT yet: a foreground serve keeps running because the server holds // the event loop open. `process.exitCode` is set and never acted on until the // listener closes, which is what SIGTERM does (start.ts). - return EXIT.ok; + return EXIT.OK; } /** @@ -448,6 +503,6 @@ main().then( }, (err: unknown) => { console.error("fatal:", err); - process.exitCode = EXIT.failure; + process.exitCode = EXIT.FAILED; }, ); diff --git a/packages/server/src/cli/output.ts b/packages/server/src/cli/output.ts index 3f714d2..69fd600 100644 --- a/packages/server/src/cli/output.ts +++ b/packages/server/src/cli/output.ts @@ -1,8 +1,7 @@ -// From edspencer/cli-contract reference/output.ts @ SPEC 0.1; local changes: `./exit-codes.ts` → `./exit-codes.js` -// (Managers compiles to ESM-with-extensions, not a TS runtime); `EXIT.FAILED`/`EXIT.USAGE` → Managers' lowercase -// `EXIT.failure`/`EXIT.usage`, because Managers' own `exit-codes.ts` predates the reference module and wave C4 -// re-syncs that file; and the reference's `UsageError` / `reportUsageError` are NOT copied, because `cli/args.ts` -// already has a `UsageError` (a `CliError` subclass carrying its own code) that the entrypoint already reports. +// From edspencer/cli-contract reference/output.ts @ 0.2; local changes: `./exit-codes.ts` → `./exit-codes.js` +// (Managers compiles to ESM-with-extensions, not a TS runtime); and the reference's `UsageError` / `reportUsageError` +// are NOT copied, because `cli/args.ts` already has a `UsageError` (a `CliError` subclass carrying its own code) that +// the entrypoint already reports. // // A CLI's output, the way SPEC §2 and §3 say: errors as `: ` on stderr, colour only on a TTY (honouring // NO_COLOR and FORCE_COLOR), and with `--json`, one JSON document on stdout and every word of prose on stderr. @@ -97,7 +96,7 @@ export function createOutput(o: OutputOptions): Output { warn(s) { stderr.write(line(s)); }, - error(message, code = EXIT.failure) { + error(message, code = EXIT.FAILED) { stderr.write(line(`${o.tool}: ${message}`)); return code; }, diff --git a/packages/server/src/cli/service/backend.ts b/packages/server/src/cli/service/backend.ts deleted file mode 100644 index 8ebc16e..0000000 --- a/packages/server/src/cli/service/backend.ts +++ /dev/null @@ -1,139 +0,0 @@ -/** - * The seam between "what a Managers service is" and "how this init system spells - * it" (#796). - * - * Two backends implement this: `launchd.ts` and `systemd.ts`. They differ in - * more than syntax — launchd wants log file paths and systemd sends everything - * to journald; systemd needs `loginctl enable-linger` and launchd has no - * equivalent — so the interface carries those asymmetries explicitly rather - * than pretending the two are the same shape with different quotes. - */ -import { spawnSync } from "node:child_process"; -import type { ServiceSpec } from "./spec.js"; - -export interface RunResult { - status: number | null; - stdout: string; - stderr: string; -} - -/** - * Run an external command. - * - * Injected rather than imported so the install/uninstall/status flows can be - * driven in tests on a box that has neither `launchctl` nor a user systemd. - */ -export type Runner = (cmd: string, args: string[]) => RunResult; - -export const spawnRunner: Runner = (cmd, args) => { - const r = spawnSync(cmd, args, { encoding: "utf8" }); - return { - status: r.status, - stdout: r.stdout ?? "", - stderr: r.stderr ?? "", - }; -}; - -/** - * Whether the user lingers — Linux only (SPEC §7). - * - * `loginctl show-user -p Linger` is the question, and all three answers - * are distinct and useful: on (nothing to say), off (the service dies at - * logout, and the fix needs `sudo`), and *unknown* — no `loginctl`, no logind, - * a container. Collapsing unknown into "off" would print a `sudo` instruction - * to someone whose machine has no `loginctl` to run it with. - */ -export interface LingerState { - /** False where the platform has no such concept (darwin). */ - applies: boolean; - /** On, off, or undefined when the check could not answer. */ - enabled?: boolean; - /** The user the check asked about, for the printed command. */ - user?: string; -} - -export interface ServiceState { - /** Is a unit file installed for us? */ - registered: boolean; - /** Does the init system say the process is up right now? */ - running: boolean; - pid?: string; - /** The Managers arguments recorded in the installed unit, interpreter stripped. */ - argv: string[]; - /** - * The interpreter and script the installed unit actually names. - * - * Reported separately from {@link argv} because `status` has to be able to - * say "the Node it runs is not there any more" (SPEC §7), which is only - * answerable from the paths in the FILE. Under nvm, fnm or volta, removing a - * Node version leaves a unit naming an interpreter that no longer exists — - * and the symptom is Managers being absent with an empty log, because it never - * got as far as running. Undefined for a unit we could not parse. - */ - nodePath?: string; - cliPath?: string; - /** - * The log file the installed unit names, if it names one. - * - * Read back rather than recomputed so `status` and `logs` report the file the - * service is really appending to. A unit written before the logs moved to - * `/logs/service.log` names the old pair under `/service/`, - * and telling its owner to read a file nothing writes to is worse than - * telling them nothing. - */ - logPath?: string; - /** - * Does the unit ON DISK come back after a graceful stop (#872)? - * - * Read from the installed file rather than from what we would write today, - * because those differ for exactly the people who need to hear about it. - * Upgrading the package does not rewrite a unit, so anyone who installed - * before #872 still has `SuccessfulExit: false` / `Restart=on-failure` — the - * shape where one sleep or logout stops Managers for good. They cannot see - * that from the outside: the service simply is not running one morning. - * `status` is where they look, so `status` is where it has to say so. - * - * Meaningless when `registered` is false, and `true` there — "nothing to warn - * about" — so no caller has to special-case a unit that does not exist. - */ - keepsAlive: boolean; -} - -export interface ServiceBackend { - platform: "darwin" | "linux"; - /** Where the plist / unit file goes. */ - unitPath: string; - /** launchd label or systemd unit name — the string a user would type. */ - label: string; - install(spec: ServiceSpec): void; - /** True if something was actually there to remove. */ - uninstall(): boolean; - status(): ServiceState; - /** - * Start / stop / restart an already-installed unit (#873). - * - * These exist so an intended stop has a channel of its OWN. Before them the - * only stop was `uninstall`, which also deregisters, so "bounce it after - * editing config" meant either losing the unit or dropping to raw - * `launchctl kickstart -k gui/$(id -u)/net.edspencer.managers` — undiscoverable, - * and different on each platform. The exit-code heuristic that #872 removed - * was carrying the same meaning by inference; a command carries it directly. - * - * Each throws with the supervisor's own stderr rather than returning a - * boolean: the interesting failures here (a unit that was booted out, a - * manager that is not running) have text worth showing, and swallowing it - * would leave `start` printing a URL for a server that never came up. - */ - start(): void; - stop(): void; - restart(): void; - /** - * Does this user linger? (SPEC §7.) Asked of the OS, not assumed. - * - * The note used to be printed unconditionally on Linux, which meant the - * people who had already run `enable-linger` were told to run it at every - * install and every status — so the one line that mattered to the people who - * had NOT was indistinguishable from boilerplate. - */ - linger(): LingerState; -} diff --git a/packages/server/src/cli/service/index.ts b/packages/server/src/cli/service/index.ts index f8a817c..d1ab3ac 100644 --- a/packages/server/src/cli/service/index.ts +++ b/packages/server/src/cli/service/index.ts @@ -36,19 +36,23 @@ import { portFromArgv, serviceDir, serviceLogPath, - type ServiceSpec, + MANAGERS_SERVICE, } from "./spec.js"; import { spawnRunner, type LingerState, type Runner, - type ServiceBackend, + type ServiceManager as ServiceBackend, + type ServiceSpec, type ServiceState, -} from "./backend.js"; -import { createLaunchdBackend } from "./launchd.js"; -import { createSystemdBackend } from "./systemd.js"; +} from "./manager.js"; +import { createLaunchd } from "./launchd.js"; +import { createSystemd } from "./systemd.js"; import { missingPaths } from "./path-env.js"; import { DEFAULT_LOG_LINES, followFile, sizeOf, tailFile } from "./logs.js"; +import { readLiveRuntimeFile } from "../../runtime-file.js"; +import { MANAGERS_VERSION } from "../../version.js"; +import { updateSummary, type UpdateSummary } from "../update/update-check.js"; import { waitForReady, fetchHealth, @@ -110,8 +114,14 @@ export interface ServiceContext { */ function backendFor(ctx: ServiceContext): ServiceBackend { const run = ctx.run ?? spawnRunner; - if (ctx.platform === "darwin") return createLaunchdBackend(run, ctx.homeDir); - if (ctx.platform === "linux") return createSystemdBackend(run, ctx.homeDir, ctx.xdgConfigHome); + if (ctx.platform === "darwin") return createLaunchd(MANAGERS_SERVICE, { run, homeDir: ctx.homeDir }); + if (ctx.platform === "linux") { + return createSystemd(MANAGERS_SERVICE, { + run, + homeDir: ctx.homeDir, + ...(ctx.xdgConfigHome !== undefined ? { xdgConfigHome: ctx.xdgConfigHome } : {}), + }); + } throw new CliError( `\`managers service\` supports macOS (launchd) and Linux (systemd --user), not ${ctx.platform}.\n` + "Run `managers` in a terminal, or keep it up with whatever your platform uses.", @@ -135,8 +145,56 @@ function resolveDataDir( return { dataDir: defaultDataDir(ctx.homeDir), explicit: undefined }; } -function specFor(opts: CliOptions, ctx: ServiceContext): { spec: ServiceSpec; dataDir: string } { - const { dataDir, explicit } = resolveDataDir(opts, ctx); +/** The value of a flag in a recorded argument vector, or undefined. */ +function argValue(argv: string[], names: readonly string[]): string | undefined { + for (let i = 0; i < argv.length; i++) { + if (names.includes(argv[i]) && argv[i + 1] !== undefined) return argv[i + 1]; + } + return undefined; +} + +/** + * The settings an EXISTING unit carries, as if they had been typed + * (`service install --refresh`, SPEC §1 and §5 step 11). + * + * This is what makes a reinstall idempotent rather than a reset. A unit + * installed with `--port 9000 --data-dir /srv/managers` must come back on 9000 + * pointing at /srv/managers — and `update` is precisely the caller that has no + * way to know those values, because it runs the NEW version's CLI in a shell + * that never typed them. + * + * Flags still win, so `service install --refresh --port 7300` moves the port. + * The ENVIRONMENT deliberately does not: `resolveDataDir` normally lets + * `MANAGERS_DATA_DIR` stand in for `--data-dir`, which would be wrong here — + * the refresh is a faithful re-render of a unit, and inheriting the updating + * shell's data dir would silently repoint somebody's service at a different + * instance. A unit with no recorded `--data-dir` keeps having none, which is + * how it stays the same `~/.managers` a bare `managers` reaches. + */ +function inherit(opts: CliOptions, state: ServiceState): CliOptions { + const port = argValue(state.argv, ["--port", "-p"]); + const host = argValue(state.argv, ["--host"]); + const dataDir = argValue(state.argv, ["--data-dir", "-d"]); + return { + ...opts, + ...(opts.port === undefined && port !== undefined ? { port } : {}), + ...(opts.host === undefined && host !== undefined ? { host } : {}), + ...(opts.dataDir === undefined && dataDir !== undefined ? { dataDir } : {}), + verbose: opts.verbose || state.argv.includes("--verbose"), + }; +} + +function specFor( + opts: CliOptions, + ctx: ServiceContext, + /** Set on a `--refresh`: the data dir comes from the unit, not the environment. */ + fromUnit = false, +): { spec: ServiceSpec; dataDir: string } { + const { dataDir, explicit } = fromUnit + ? opts.dataDir !== undefined + ? { dataDir: path.resolve(opts.dataDir), explicit: path.resolve(opts.dataDir) } + : { dataDir: defaultDataDir(ctx.homeDir), explicit: undefined } + : resolveDataDir(opts, ctx); const spec = buildSpec({ nodePath: ctx.nodePath, scriptPath: ctx.scriptPath, @@ -223,9 +281,35 @@ async function install( ): Promise { if (isNpxPath(ctx.packageRoot)) throw new CliError(NPX_REFUSAL); - const { spec, dataDir } = specFor(opts, ctx); + // `--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 + // same code every other command that needs a unit returns, rather than + // quietly performing a first install from defaults. That distinction is the + // whole reason the flag exists: `update` runs this through the new version's + // 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; + if (refreshing) { + existing = backend.status(); + if (!existing.registered) { + console.log(notInstalled(backend)); + return EXIT.NOT_INSTALLED; + } + } + + const { spec, dataDir } = specFor( + existing !== undefined ? inherit(opts, existing) : opts, + ctx, + refreshing, + ); const url = `http://${hostFromArgv(spec.args)}:${portFromArgv(spec.args)}`; + if (refreshing) { + console.log( + `\n Re-writing ${backend.unitPath}\n Keeping: managers ${spec.args.join(" ")}`, + ); + } console.log(installProgress(backend)); backend.install(spec); @@ -270,7 +354,7 @@ async function install( ); // "It is installed but did not answer" is a failure, and used to exit 0 — so // an Ansible task or a CI step could not tell it from a working install. - return readiness === "ready" ? EXIT.ok : EXIT.failure; + return readiness === "ready" ? EXIT.OK : EXIT.FAILED; } function uninstall(ctx: ServiceContext, backend: ServiceBackend): number { @@ -287,7 +371,7 @@ function uninstall(ctx: ServiceContext, backend: ServiceBackend): number { // 0 either way: "there was nothing to remove" is the state the caller asked // for. `uninstall` is idempotent on purpose, so a teardown script can run it // without first asking whether it has anything to do. - return EXIT.ok; + return EXIT.OK; } /** @@ -380,10 +464,32 @@ export interface StatusReport { cli: string | null; /** Linux only: null where the platform has no such concept. */ linger: boolean | null; + /** + * What the last `update --check` found, from `/update-check.json` + * (SPEC §3). + * + * `status` never asks the registry itself — the contract is explicit that + * nothing contacts it by itself, and a status command run by a monitoring + * loop would be exactly the background check §3 forbids. So this repeats a + * file somebody's `update --check` or `doctor` wrote. + * + * **Absent, not null, when there is nothing to repeat.** The contract's + * `schemas/service-status.schema.json` types this key as an OBJECT, so a + * `null` fails the schema and the conformance runner says so — which is how + * this was found. The other optional fields here are `| null` because the + * schema types THOSE as nullable; this one it does not. + */ + update?: UpdateSummary; /** A stale unit, a missing Node — things that are wrong but not fatal. */ warnings: string[]; } +/** `{ update }` when there is a recent check to repeat, and `{}` otherwise. */ +function withUpdate(home: string): { update?: UpdateSummary } { + const summary = updateSummary(home, { currentVersion: MANAGERS_VERSION }); + return summary !== undefined ? { update: summary } : {}; +} + async function buildStatus(ctx: ServiceContext, backend: ServiceBackend): Promise { const state = backend.status(); const base = { @@ -411,6 +517,7 @@ async function buildStatus(ctx: ServiceContext, backend: ServiceBackend): Promis node: null, cli: null, linger: lingerValue, + ...withUpdate(path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir))), warnings: [], }; } @@ -462,6 +569,7 @@ async function buildStatus(ctx: ServiceContext, backend: ServiceBackend): Promis node: state.nodePath ?? null, cli: state.cliPath ?? null, linger: lingerValue, + ...withUpdate(dataDir), warnings, }; } @@ -507,7 +615,13 @@ async function status( "", ].join("\n"), ); - return EXIT.notInstalled; + // The notice belongs here too. Found in QA: it was printed only on the + // installed path, so a machine with no service got `update` in `--json` + // and silence in the prose — the exact `--json`-disagrees-with-the-text rot + // that one StatusReport is supposed to prevent. A newer version is worth + // knowing about whether or not a unit exists. + noteUpdate(report); + return EXIT.NOT_INSTALLED; } const versions = @@ -545,14 +659,41 @@ async function status( "", ].join("\n"), ); + // The update notice goes to STDERR, and only ever repeats the cache (SPEC + // §3). stderr because it is prose about something other than what was asked + // for, and because that keeps every byte of stdout under the `--json` + // discipline's one rule rather than two. + noteUpdate(report); return statusExit(report); } +/** + * Repeat the cached update answer on stderr, when there is one worth repeating + * (SPEC §3). + * + * Nothing is fetched here. The `Run:` line is the plain `managers update` + * rather than §6's per-install variant, because working that out needs the + * install method and the target's tag — and `status` has deliberately not + * asked the registry, so it has neither. Anyone whose install cannot update + * itself gets the right command from `update --check`, which has. + */ +function noteUpdate(report: StatusReport): void { + const update = report.update; + if (update === undefined || !update.updateAvailable) return; + console.error(""); + const have = report.runningVersion ?? report.installedVersion; + console.error( + ` ${update.latest} is available${have !== null && have !== undefined ? ` (you have ${have})` : ""}.`, + ); + console.error(" Run: managers update"); + console.error(` Checked: ${update.checkedAt}`); +} + /** The exit code a report means (SPEC §2). */ function statusExit(report: StatusReport): number { - if (!report.installed) return EXIT.notInstalled; - if (!report.running || !report.answering) return EXIT.notRunning; - return EXIT.ok; + if (!report.installed) return EXIT.NOT_INSTALLED; + if (!report.running || !report.answering) return EXIT.NOT_RUNNING; + return EXIT.OK; } /** @@ -601,13 +742,13 @@ async function startOrRestart( const before = backend.status(); if (!before.registered) { console.log(notInstalled(backend)); - return EXIT.notInstalled; + return EXIT.NOT_INSTALLED; } const url = installedUrl(before); if (action === "start" && before.running) { console.log(`\n Managers is already running${pid(before)}.\n\n URL: ${url}\n`); - return EXIT.ok; + return EXIT.OK; } // A restart stops the instance first, so it asks the same question `stop` @@ -643,7 +784,7 @@ async function startOrRestart( ); // A start that never answered is a failure, not a success with a caveat: the // caller — often an Ansible task — has no other way to find out. - return readiness === "ready" ? EXIT.ok : EXIT.failure; + return readiness === "ready" ? EXIT.OK : EXIT.FAILED; } /** @@ -679,11 +820,11 @@ async function stop( const state = backend.status(); if (!state.registered) { console.log(notInstalled(backend)); - return EXIT.notInstalled; + return EXIT.NOT_INSTALLED; } if (!state.running) { console.log(`\n Managers is already stopped.\n Unit: ${backend.unitPath}\n`); - return EXIT.ok; + return EXIT.OK; } // Refuse with 75 if it is in the middle of something, unless --force (SPEC @@ -705,7 +846,7 @@ async function stop( "", ].join("\n"), ); - return EXIT.ok; + return EXIT.OK; } function pid(state: ServiceState): string { @@ -733,7 +874,7 @@ async function logs( const state = backend.status(); if (!state.registered) { console.log(notInstalled(backend)); - return EXIT.notInstalled; + return EXIT.NOT_INSTALLED; } const file = logPathOf(state, dataDirOf(state, ctx)); @@ -743,7 +884,7 @@ async function logs( // stderr: with `-f` this is a caveat ahead of a stream, and prose on stdout // would be mixed into the log output itself. console.error(`managers: nothing has been written to ${file} yet.`); - if (opts.follow !== true) return EXIT.ok; + if (opts.follow !== true) return EXIT.OK; } else { const tail = tailFile(file, lines); if (tail !== "") console.log(tail); @@ -753,7 +894,7 @@ async function logs( console.error(`managers: following ${file} — Ctrl-C to stop.`); await followFile(file, { from: sizeOf(file) }); } - return EXIT.ok; + return EXIT.OK; } /** @@ -778,6 +919,98 @@ export async function runService( return status(opts, ctx, backend); } +/** + * The report `service status` prints, for `managers doctor` — one builder, so + * the doctor's unit checks and `status`'s warnings cannot disagree. Throws on a + * platform with no service manager, as `runService` does. + */ +export async function serviceStatusReport(ctx: ServiceContext): Promise { + return buildStatus(ctx, backendFor(ctx)); +} + +/** + * What `managers update` needs to know and do about the service (SPEC §5). + * + * Built here rather than in the update module so that everything which reads a + * unit file stays in one place: `update` gets the same answer `status` and + * `logs` get, from the same backend, including the #824 rule that the instance + * in question is the one the UNIT describes and not whatever `--data-dir` the + * invocation carries. + * + * Returns `home` too, which is the data dir `update.lock` and + * `update-check.json` go in. It has to be the unit's: the cache's reader is + * `service status`, which looks in the unit's data dir, so writing it anywhere + * else would be writing a file nothing reads. + */ +export function updateServiceHooks(ctx: ServiceContext): { + hooks: ServiceHooksForUpdate; + home: string; + installed: boolean; +} { + const backend = backendFor(ctx); + const first = backend.status(); + const home = first.registered + ? dataDirOf(first, ctx) + : path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir)); + + const inspect = (): { + installed: boolean; + running: boolean; + url?: string; + log?: string; + } => { + const state = backend.status(); + if (!state.registered) { + // No unit. A foreground `managers serve` is still worth finding, because + // SPEC §5's "without a service" path has to be able to say "restart + // Managers to use the new version" — and `runtime.json` is the only honest + // way to find it (no guessing at a default port, the busy client's rule). + const live = readLiveRuntimeFile(home); + return { + installed: false, + running: live !== null, + ...(live !== null ? { url: live.url } : {}), + }; + } + return { + installed: true, + running: state.running, + url: urlOf(state), + log: logPathOf(state, dataDirOf(state, ctx)), + }; + }; + + return { + installed: first.registered, + home, + hooks: { + inspect, + stop: () => backend.stop(), + // The NEW version's CLI writes the unit (SPEC §5 step 11). Run with the + // interpreter we are running, not the bin shim: the shim's shebang has to + // find `node` on PATH, and under a version manager there may not be one. + refresh: (cliPath: string) => { + const run = ctx.run ?? spawnRunner; + return run(process.execPath, [cliPath, "service", "install", "--refresh"]); + }, + tail: (lines: number) => { + const state = backend.status(); + if (!state.registered) return ""; + const file = logPathOf(state, dataDirOf(state, ctx)); + return fs.existsSync(file) ? tailFile(file, lines) : ""; + }, + }, + }; +} + +/** The shape {@link updateServiceHooks} returns — structurally `UpdateServiceHooks`. */ +export interface ServiceHooksForUpdate { + inspect(): { installed: boolean; running: boolean; url?: string; log?: string }; + stop(): void; + refresh(cliPath: string): { status: number | null; stdout: string; stderr: string }; + tail(lines: number): string; +} + /** Exported for the entrypoint's context assembly, and for tests. */ export { serviceDir, isNpxPath }; export type { ServiceSpec }; diff --git a/packages/server/src/cli/service/launchd.ts b/packages/server/src/cli/service/launchd.ts index bb7859a..4d9b1fd 100644 --- a/packages/server/src/cli/service/launchd.ts +++ b/packages/server/src/cli/service/launchd.ts @@ -1,102 +1,57 @@ -/** - * The darwin backend: a launchd **LaunchAgent** (#796). - * - * ## Why an agent and not a daemon - * - * A LaunchAgent is bootstrapped into the `gui/` domain when that user logs - * in, and runs as them. A LaunchDaemon starts at boot, as root, before anyone - * has logged in. The difference is not convenience — it decides whether Managers - * can use your Claude login at all. - * - * On macOS that login is a Keychain item, and the login keychain is unlocked by - * your account password *at login*. A daemon has no such session, so the item - * is locked and unreadable; `UserName` in the plist does not help, because it - * changes the effective uid and not the keychain's unlock state. `claude. - * credentials: host` on darwin therefore structurally requires a logged-in user - * session, and boot-time start and Keychain credentials are mutually exclusive. - * - * The consequence users will meet is that Managers starts **at login, not at - * boot** — after a restart nobody logs into, it is not running. Every surface - * that mentions this service says so, because otherwise it gets filed as a bug. - * - * A boot-time instance is a genuinely different feature: a LaunchDaemon plus - * `claude.credentials: own` and a token sitting in `EnvironmentVariables` — - * which is exactly the long-lived-credential-in-a-plist problem the agent shape - * avoids. Stated in the docs as the trade, not offered as a flag. - * - * ## What has actually been verified - * - * A turn completed under `launchctl kickstart` on a Mac whose Claude login - * existed only as the Keychain item, with `ps eww` confirming no credential in - * the process environment, and with no permission dialog. Start **at login** - * (`RunAtLoad` after a real logout/login) has NOT been tested; if a login-time - * agent can race keychain unlock, the fix belongs in this file's plist rather - * than in the design. Nothing here should be read as covering that case. - */ -import fs from "node:fs"; -import os from "node:os"; -import path from "node:path"; -import { LAUNCHD_LABEL, type ServiceSpec } from "./spec.js"; -import type { LingerState, Runner, ServiceBackend, ServiceState } from "./backend.js"; - -/** `~/Library/LaunchAgents/net.edspencer.managers.plist`. */ -export function plistPath(homeDir: string = os.homedir()): string { - return path.join(homeDir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`); +// From edspencer/cli-contract reference/service/launchd.ts @ 0.2 (with #7, d5ddc0e); local changes: `.ts` import specifiers → `.js`. +// macOS: a launchd LaunchAgent in the `gui/` domain (SPEC §7). It starts at login, not at boot, and runs as the +// user, inside their login session (so the login keychain is unlocked). Node built-ins only. +// +// ## The bootout/bootstrap race +// +// `launchctl bootout` returns once launchd has accepted the request, not once the job has gone. A bootstrap of the +// same label straight after it races launchd's own teardown, and when it loses, fails with exit 5 (`EIO`, +// "Input/output error"). It's timing-dependent: Paddock 0.80.0's release run failed on it after the PR had passed. +// Both halves of the fix are needed: +// +// - **after a bootout we issue, wait for the job to go:** poll `launchctl print` until it fails (the label is +// unknown), up to `BOOTOUT_POLLS` times. Counted, not timed, so an injected no-op sleep can't spin for ten seconds; +// - **retry a bootstrap that fails with 5 or 37** ("operation already in progress"), a few times with a pause. This +// covers a bootout someone else issued: `service start` straight after another process's `service stop`. +// +// Anything else launchctl says is reported at once, in its own words. +// +// A fake `launchctl` in tests must fail `print` when nothing is loaded, or every install sits out the whole poll. + +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { sleepSync, type LingerState, type Runner, type RunResult, type ServiceIdentity, type ServiceManager, type ServiceSpec, type ServiceState } from './manager.js'; + +/** `~/Library/LaunchAgents/