@edspencer/paddock 0.81.0 → 0.82.1

package/packages/server/dist/cli/service/index.js

@@ -27,12 +27,15 @@ import os from "node:os";
 import path from "node:path";
 import { CliError } from "../args.js";
 import { EXIT } from "../exit-codes.js";
-import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, serviceLogPath, } from "./spec.js";
-import { spawnRunner, } from "./backend.js";
-import { createLaunchdBackend } from "./launchd.js";
-import { createSystemdBackend } from "./systemd.js";
+import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, serviceLogPath, PADDOCK_SERVICE, } from "./spec.js";
+import { spawnRunner, } 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 { PADDOCK_VERSION } from "../../version.js";
+import { updateSummary } from "../update/update-check.js";
 import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
 /**
  * Pick a backend, or explain why there isn't one.
@@ -44,9 +47,14 @@ import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
 function backendFor(ctx) {
     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);
+        return createLaunchd(PADDOCK_SERVICE, { run, homeDir: ctx.homeDir });
+    if (ctx.platform === "linux") {
+        return createSystemd(PADDOCK_SERVICE, {
+            run,
+            homeDir: ctx.homeDir,
+            ...(ctx.xdgConfigHome !== undefined ? { xdgConfigHome: ctx.xdgConfigHome } : {}),
+        });
+    }
     throw new CliError(`\`paddock service\` supports macOS (launchd) and Linux (systemd --user), not ${ctx.platform}.\n` +
         "Run `paddock` in a terminal, or keep it up with whatever your platform uses.");
 }
@@ -63,8 +71,52 @@ function resolveDataDir(opts, ctx) {
     }
     return { dataDir: defaultDataDir(ctx.homeDir), explicit: undefined };
 }
-function specFor(opts, ctx) {
-    const { dataDir, explicit } = resolveDataDir(opts, ctx);
+/** The value of a flag in a recorded argument vector, or undefined. */
+function argValue(argv, names) {
+    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/paddock` must come back on 9000
+ * pointing at /srv/paddock — 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
+ * `PADDOCK_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 `~/.paddock` a bare `paddock` reaches.
+ */
+function inherit(opts, state) {
+    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, ctx, 
+/** Set on a `--refresh`: the data dir comes from the unit, not the environment. */
+fromUnit = false) {
+    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,
@@ -136,8 +188,27 @@ function lingerNote(linger) {
 async function install(opts, ctx, backend) {
     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 7233 on
+    // the one run nobody is watching.
+    const refreshing = opts.refresh === true;
+    let existing;
+    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: paddock ${spec.args.join(" ")}`);
+    }
     console.log(installProgress(backend));
     backend.install(spec);
     // The unit is written and the supervisor has accepted it. That is NOT the
@@ -176,7 +247,7 @@ async function install(opts, ctx, backend) {
     ].join("\n"));
     // "It is installed but did not answer" is a failure, and used to exit 0 — so
     // an Ansible task or a CI step could not tell it from a working install.
-    return readiness === "ready" ? EXIT.ok : EXIT.failure;
+    return readiness === "ready" ? EXIT.OK : EXIT.FAILED;
 }
 function uninstall(ctx, backend) {
     const existed = backend.uninstall();
@@ -190,7 +261,7 @@ function uninstall(ctx, backend) {
     // 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;
 }
 /**
  * The data dir the INSTALLED unit uses, read out of its own argument vector.
@@ -251,6 +322,11 @@ export function installedVersionOf(cliPath) {
         dir = parent;
     }
 }
+/** `{ update }` when there is a recent check to repeat, and `{}` otherwise. */
+function withUpdate(home) {
+    const summary = updateSummary(home, { currentVersion: PADDOCK_VERSION });
+    return summary !== undefined ? { update: summary } : {};
+}
 async function buildStatus(ctx, backend) {
     const state = backend.status();
     const base = {
@@ -277,6 +353,7 @@ async function buildStatus(ctx, backend) {
             node: null,
             cli: null,
             linger: lingerValue,
+            ...withUpdate(path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir))),
             warnings: [],
         };
     }
@@ -318,6 +395,7 @@ async function buildStatus(ctx, backend) {
         node: state.nodePath ?? null,
         cli: state.cliPath ?? null,
         linger: lingerValue,
+        ...withUpdate(dataDir),
         warnings,
     };
 }
@@ -354,7 +432,13 @@ async function status(opts, ctx, backend) {
             "  paddock service install     register it and start it now",
             "",
         ].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 = report.runningVersion !== null && report.runningVersion !== report.installedVersion
         ? `  Version: ${report.runningVersion} running, ${report.installedVersion ?? "unknown"} installed`
@@ -387,15 +471,40 @@ async function status(opts, ctx, backend) {
         ...report.warnings.flatMap((w) => ["", `  ⚠ ${w}`]),
         "",
     ].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 `paddock 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) {
+    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: paddock update");
+    console.error(`    Checked: ${update.checkedAt}`);
+}
 /** The exit code a report means (SPEC §2). */
 function statusExit(report) {
     if (!report.installed)
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     if (!report.running || !report.answering)
-        return EXIT.notRunning;
-    return EXIT.ok;
+        return EXIT.NOT_RUNNING;
+    return EXIT.OK;
 }
 /**
  * The URL an installed unit is actually serving, or undefined if none is.
@@ -436,12 +545,12 @@ async function startOrRestart(action, opts, ctx, backend) {
     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  Paddock 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`
     // asks (SPEC §1): refuse with 75 unless `--force`. `start` does not — there
@@ -475,7 +584,7 @@ async function startOrRestart(action, opts, ctx, backend) {
     ].join("\n"));
     // A start that never answered is a failure, not a success with a caveat: the
     // caller — often an Ansible task — has no other way to find out.
-    return readiness === "ready" ? EXIT.ok : EXIT.failure;
+    return readiness === "ready" ? EXIT.OK : EXIT.FAILED;
 }
 /**
  * The busy check, asked of the instance the UNIT describes (SPEC §1, §4).
@@ -500,11 +609,11 @@ async function stop(opts, ctx, backend) {
     const state = backend.status();
     if (!state.registered) {
         console.log(notInstalled(backend));
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     if (!state.running) {
         console.log(`\n  Paddock 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
     // §4). Deliberately AFTER the two cases above: an unit that is not there, or
@@ -523,7 +632,7 @@ async function stop(opts, ctx, backend) {
         "    paddock service start",
         "",
     ].join("\n"));
-    return EXIT.ok;
+    return EXIT.OK;
 }
 function pid(state) {
     return state.pid !== undefined ? ` (pid ${state.pid})` : "";
@@ -545,7 +654,7 @@ async function logs(opts, ctx, backend) {
     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));
     const lines = opts.lines ?? DEFAULT_LOG_LINES;
@@ -554,7 +663,7 @@ async function logs(opts, ctx, backend) {
         // would be mixed into the log output itself.
         console.error(`paddock: nothing has been written to ${file} yet.`);
         if (opts.follow !== true)
-            return EXIT.ok;
+            return EXIT.OK;
     }
     else {
         const tail = tailFile(file, lines);
@@ -565,7 +674,7 @@ async function logs(opts, ctx, backend) {
         console.error(`paddock: following ${file} — Ctrl-C to stop.`);
         await followFile(file, { from: sizeOf(file) });
     }
-    return EXIT.ok;
+    return EXIT.OK;
 }
 /**
  * Dispatch, returning the exit code rather than setting one (SPEC §2).
@@ -589,6 +698,70 @@ export async function runService(action, opts, ctx) {
         return logs(opts, ctx, backend);
     return status(opts, ctx, backend);
 }
+/**
+ * What `paddock 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) {
+    const backend = backendFor(ctx);
+    const first = backend.status();
+    const home = first.registered
+        ? dataDirOf(first, ctx)
+        : path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir));
+    const inspect = () => {
+        const state = backend.status();
+        if (!state.registered) {
+            // No unit. A foreground `paddock serve` is still worth finding, because
+            // SPEC §5's "without a service" path has to be able to say "restart
+            // Paddock 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) => {
+                const run = ctx.run ?? spawnRunner;
+                return run(process.execPath, [cliPath, "service", "install", "--refresh"]);
+            },
+            tail: (lines) => {
+                const state = backend.status();
+                if (!state.registered)
+                    return "";
+                const file = logPathOf(state, dataDirOf(state, ctx));
+                return fs.existsSync(file) ? tailFile(file, lines) : "";
+            },
+        },
+    };
+}
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 /** Best-effort home dir; `os.homedir()` throws on a machine with no passwd entry. */

package/packages/server/dist/cli/service/launchd.d.ts

@@ -1,92 +1,39 @@
-import { type ServiceSpec } from "./spec.js";
-import type { Runner, ServiceBackend } from "./backend.js";
-/** `~/Library/LaunchAgents/net.edspencer.paddock.plist`. */
-export declare function plistPath(homeDir?: string): string;
+import { type Runner, type ServiceIdentity, type ServiceManager, type ServiceSpec } from './manager.js';
+/** `~/Library/LaunchAgents/<label>.plist`. */
+export declare function plistPath(id: Pick<ServiceIdentity, 'label'>, homeDir?: string): string;
 /**
- * Render the plist.
- *
- * `KeepAlive` is unconditional `<true/>`, and that is a deliberate reversal
- * (#872). It used to be `{ SuccessfulExit: false }` — "restart it if it exits
- * nonzero, leave it alone if it exits cleanly" — which reads like the polite
- * choice and is, for a service, a trap. `start.ts` handles SIGTERM by shutting
- * down cleanly and exiting `0`, so **every** SIGTERM the OS routinely sends a
- * LaunchAgent (sleep, logout, a stray `kill`) looked to launchd like "it meant
- * to stop", and Paddock stayed down until the next login. A hard crash was the
- * survivable case; the graceful stop was the terminal one.
- *
- * The worry that motivated the dict — that `<true/>` fights a deliberate stop —
- * does not hold for the stop this CLI actually performs. `launchctl bootout`
- * unloads the job from the domain, and KeepAlive only applies to a job that is
- * still loaded, so `uninstall` still stops Paddock in one call. What `<true/>`
- * does fight is `launchctl stop`, which is why nothing here uses it.
- *
- * Intent belongs in an explicit command, not in an exit code.
- *
- * `EnvironmentVariables` carries PATH and nothing else. It carries PATH because
- * launchd hands a process a stub PATH that a version manager's `node`, and the
- * `git` an agent will want, are both missing from. It carries nothing else
- * because a plist is a world-readable file in the user's home, and the one
- * category of value that would be tempting to put here — a credential — is
- * precisely what the agent shape exists to avoid needing.
- *
- * No `PADDOCK_DATA_DIR`: see `buildSpec`. One `~/.paddock` instance, reachable
- * from the service and from a terminal.
- *
- * `StandardOutPath` and `StandardErrorPath` name the SAME file (SPEC §7).
- * launchd opens both in append mode, so interleaving is what a reader wants
- * anyway — a warning and the stack trace that followed it used to land in two
- * separate files, in an order nothing recorded. One file is also what makes
- * `paddock service logs` one implementation across platforms.
- */
-export declare function renderPlist(spec: ServiceSpec): string;
-/**
- * Pull `ProgramArguments` back out of a plist we wrote.
- *
- * `status` reports the port the service is ACTUALLY installed with, which is
- * only knowable from the installed unit — recomputing it from today's flags
- * would print a confident URL for a server listening somewhere else. Regex
- * rather than a plist parser because the input is a file this module wrote, in
- * a shape this module controls, and adding an XML dependency to read it back
- * would be the larger risk.
+ * The plist.
+ *
+ * - `KeepAlive` is an unconditional `<true/>`. `{ SuccessfulExit: false }` reads as the polite choice, but a server
+ *   exits 0 on SIGTERM, so every SIGTERM launchd sends an agent (sleep, logout) would leave it down until the next
+ *   login. `bootout` unloads the job, so `KeepAlive` doesn't fight a deliberate stop.
+ * - `StandardOutPath` and `StandardErrorPath` name the same file.
+ * - `EnvironmentVariables` has PATH (launchd's is a stub) and the spec's `env`. Never a credential: a plist is a
+ *   readable file.
  */
+export declare function renderPlist(id: Pick<ServiceIdentity, 'label'>, spec: ServiceSpec): string;
+/** `ProgramArguments`, read back from a plist this wrote. A regex is enough for a file whose shape we control. */
 export declare function parsePlistArgv(xml: string): string[];
-/**
- * Does an installed plist carry the unconditional `KeepAlive` from #872?
- *
- * Deliberately narrow: it matches `<key>KeepAlive</key>` followed by `<true/>`
- * and nothing else. The shape it must NOT accept is the old
- * `<dict><key>SuccessfulExit</key><false/></dict>`, which is the one that
- * leaves a service dead after a graceful stop — so a `false` here is the signal
- * `status` turns into "re-run install", and defaulting to `true` on anything
- * unrecognised would silence exactly the case this exists to catch.
- */
-export declare function plistKeepsAlive(xml: string): boolean;
-/** The log file an installed plist appends to, read back from `StandardOutPath`. */
+/** The log the plist names (`StandardOutPath`). */
 export declare function parsePlistLogPath(xml: string): string | undefined;
-/**
- * Read liveness out of `launchctl print gui/<uid>/<label>`.
- *
- * That command is the honest answer to "is it running": it reports the service
- * as launchd currently understands it, including `state = running` and the pid.
- * The alternative — checking whether the plist file exists — answers "is it
- * registered", which is a different and much weaker question.
- */
+/** Whether the plist has an unconditional `KeepAlive` (the old `SuccessfulExit` dict doesn't count). */
+export declare function plistKeepsAlive(xml: string): boolean;
+/** `state = running` and the pid, from `launchctl print gui/<uid>/<label>`. */
 export declare function parseLaunchctlPrint(out: string): {
     running: boolean;
     pid?: string;
 };
-/**
- * Block this thread for `ms`.
- *
- * The backend's {@link Runner} is synchronous (`execFileSync`) and so is every
- * `ServiceBackend` method, so the wait has to be too — making `install` async
- * would ripple through the whole service CLI for a sleep. `Atomics.wait` on a
- * throwaway buffer is the built-in way to do it; `setTimeout` cannot help here
- * and spinning on `Date.now()` would burn a core.
- *
- * Injectable because the unit tests drive the retry path with a fake runner
- * that fails every attempt: with the real sleep, pinning the retry count would
- * cost three seconds per case.
- */
-export declare function sleepSync(ms: number): void;
-export declare function createLaunchdBackend(run: Runner, homeDir?: string, sleep?: (ms: number) => void): ServiceBackend;
+export declare const BOOTOUT_POLLS = 40;
+export declare const BOOTOUT_POLL_MS = 250;
+export declare const BOOTSTRAP_ATTEMPTS = 6;
+export declare const BOOTSTRAP_BACKOFF_MS = 500;
+/** 5 is `EIO`; 37 is "operation already in progress". Both mean the last bootout hasn't finished. */
+export declare const BOOTSTRAP_RACE_CODES: ReadonlySet<number>;
+export interface LaunchdOptions {
+    run: Runner;
+    homeDir?: string;
+    uid?: number;
+    /** Injected for tests. */
+    sleep?: (ms: number) => void;
+}
+export declare function createLaunchd(id: ServiceIdentity, o: LaunchdOptions): ServiceManager;