@edspencer/paddock 0.82.0 → 0.82.1

package/packages/server/dist/cli/update/update.d.ts

@@ -1,109 +1,88 @@
-import fsDefault from "node:fs";
-import type { Output } from "../output.js";
-import { type InstallInfo } from "./install-method.js";
-import { type RunResult, type Spawn } from "./package-manager.js";
+import fsDefault from 'node:fs';
+import { type HealthVerdict } from './health.js';
+import { type InstallInfo } from './install-method.js';
+import type { Output } from '../output.js';
+import { type NpmContext, type RunResult, type Spawn } from './package-manager.js';
+import { type UpdateCheck } from './update-check.js';
+export type { HealthVerdict } from './health.js';
 /** SPEC §5 step 12: 30 seconds unless the tool sets its own. */
 export declare const HEALTH_TIMEOUT_MS = 30000;
+/** How long to wait for the old version to stop answering after the stop (step 9). */
+export declare const STOP_TIMEOUT_MS = 15000;
 /** How many log lines a failure prints (SPEC §5 step 13). */
 export declare const LOG_LINES_ON_FAILURE = 20;
-/** What `update` was asked to do. */
+/** What `update` was asked (SPEC §1). */
 export interface UpdateOptions {
-    /** Report and change nothing (SPEC §1). */
+    /** Report, and change nothing. */
     check?: boolean;
-    /** A version or a dist-tag. The only way to move to a lower version. */
+    /** A version or a dist-tag: the only way to move to a lower version. */
     to?: string;
-    /** Skip the question. Required without a TTY. */
+    /** Skip the question. Needed without a TTY. */
     yes?: boolean;
     /** Skip the busy check, and nothing else. */
     force?: boolean;
     json?: boolean;
 }
-/** What the service looks like from `update`'s point of view. */
+/** The service, as `update` sees it. */
 export interface ServiceSnapshot {
     installed: boolean;
     running: boolean;
-    /** The URL the installed unit serves, when there is one. */
+    /** The URL the installed unit serves, or a foreground `serve` found through `runtime.json`. */
     url?: string;
-    /** The log file the unit names, for the failure tail. */
+    /** The log the unit names, for the failure's tail. */
     log?: string;
 }
 export interface UpdateServiceHooks {
-    /** Is a unit installed, is it running, and where. */
+    /** Is a unit installed, is it running, and where. With no unit, report a foreground `serve` from `runtime.json`. */
     inspect(): ServiceSnapshot;
-    /** Stop the service. Throws with the supervisor's own words on failure. */
+    /** Stops the service. Throws, with the service manager's own words, if it can't. */
     stop(): void;
-    /**
-     * `<cli> service install --refresh`, run through the NEW CLI (SPEC §5 step
-     * 11). Returns the subprocess result so the caller can show what it said.
-     */
+    /** Runs `<node> <cliPath> service install --refresh`: the new CLI on the way up, the old one on a rollback. */
     refresh(cliPath: string): RunResult;
-    /** The last `lines` lines of the service log, or '' when there is no log. */
+    /** The last `lines` lines of the service's log, or ''. */
     tail(lines: number): string;
 }
-/** "Did the target answer?" — the three outcomes that matter (SPEC §5 step 12). */
-export type HealthVerdict = {
-    state: "ok";
-    version: string;
-}
-/** Something answers, but it is not the version we installed. */
- | {
-    state: "wrong-version";
-    version: string;
-} | {
-    state: "no-answer";
-};
 export interface UpdateProduct {
     /** `Paddock`. */
     name: string;
-    /** `paddock` — the bin, for `<tool>: <message>` and printed commands. */
+    /** `paddock`: the bin, for `<tool>: <message>` and the printed commands. */
     tool: string;
     /** `@edspencer/paddock`. */
     packageName: string;
-    /** `PADDOCK` — gives `PADDOCK_IN_DOCKER` and `PADDOCK_UPDATE_HINT`. */
+    /** `PADDOCK`: gives `PADDOCK_IN_DOCKER` and `PADDOCK_UPDATE_HINT`. */
     envPrefix: string;
-    /** The data home: `<home>/update.lock` and `<home>/update-check.json`. */
+    /** The data home, for `update.lock` and `update-check.json`: the one `service status` reads the cache from. */
     home: string;
-    /** This CLI's own version, from its `package.json`. */
+    /** This CLI's version, from its `package.json`. */
     currentVersion: string;
     /**
-     * `process.argv[1]` — NOT realpath'd.
-     *
-     * Both forms are needed and for different reasons. The unresolved path is a
-     * bin shim, and re-resolving it AFTER the install is what finds the new CLI
-     * under a package manager whose realpath carries the version in it (pnpm).
-     * The realpath is what SPEC §6's table walks up from.
+     * `process.argv[1]`, not realpath'd. Re-resolving the bin's symlink after the install is what finds the new CLI
+     * under a manager that puts the version in the real path (pnpm). §6's walk-up realpaths it itself.
      */
     entry: string;
-    /** Where the CLI sits inside the package: `packages/server/dist/cli/paddock.js`. */
+    /** Where the CLI sits in the package: `dist/server/cli.js`. */
     binSubpath: string;
-    /** The container image, for the Docker notice: `ghcr.io/edspencer/paddock`. */
+    /** The image, for the Docker notice: `ghcr.io/edspencer/paddock`. */
     image?: string;
-    /**
-     * The synopsis printed after `update`'s own usage error (SPEC §2: the usage
-     * follows the message).
-     *
-     * `update` has exactly one — "there is no terminal to ask, so `--yes` is
-     * required" — and it is the command's own usage rather than the tool's,
-     * because the reader's problem is one flag on the command they just typed.
-     */
+    /** `update`'s own usage, printed after the exit-2 refusal (SPEC §2). */
     usage?: string;
-    /** The release notes for a version. */
+    /** The release notes for a version: the notice's `Changes:` line. */
     changelogUrl(version: string): string;
     healthTimeoutMs?: number;
-    /** The busy check (SPEC §5 step 6): null to go ahead, or 75 having printed why. */
+    /** The busy check (SPEC §5 step 6): null to go ahead, or 75 having printed why (`guardBusy` in busy-client.ts). */
     guardBusy(o: {
         force: boolean;
         home: string;
     }): Promise<number | null>;
     service: UpdateServiceHooks;
-    /** Poll `<url>/api/health` until it reports `version`, or the budget runs out. */
-    waitForVersion(o: {
+    /** Defaults to `waitForVersion` in health.ts. */
+    waitForVersion?(o: {
         url: string;
         version: string;
         timeoutMs: number;
     }): Promise<HealthVerdict>;
 }
-/** Everything that touches the world, injected so the sequence is testable. */
+/** Everything that touches the machine. */
 export interface UpdateEnvironment {
     out: Output;
     env?: NodeJS.ProcessEnv;
@@ -111,50 +90,37 @@ export interface UpdateEnvironment {
     execPath?: string;
     platform?: NodeJS.Platform;
     fetch?: typeof globalThis.fetch;
-    fs?: Pick<typeof fsDefault, "existsSync" | "readFileSync" | "realpathSync">;
-    /** Is there a person at a keyboard? (SPEC §3.) */
+    fs?: Pick<typeof fsDefault, 'existsSync' | 'readFileSync' | 'realpathSync'>;
+    /** Is there a person at a keyboard? (SPEC §3.) Defaults to stdin and stderr both being TTYs. */
     isTTY?: boolean;
-    /**
-     * The Node to test the target's `engines.node` against.
-     *
-     * Injected so the "the target needs a newer Node" path can be proven, which
-     * it otherwise cannot be: a test runs on whatever Node CI has, and the only
-     * Nodes that fail a real `engines` range are ones the suite cannot run on.
-     */
+    /** The Node to check the target's `engines.node` against. */
     nodeVersion?: string;
-    /** Ask the question. Only called when {@link isTTY} and `--yes` was not given. */
+    /** Asks the question; only called on a TTY without `--yes`. */
     confirm?: (question: string) => Promise<boolean>;
-    /** Injected for tests: `isWritable`. */
     writable?: (dir: string) => boolean;
+    /** Injected for tests: waits between the stop's health polls. */
+    sleep?: (ms: number) => Promise<void>;
 }
-/**
- * Run `update`, and return the exit code (SPEC §2: the caller assigns
- * `process.exitCode`; nothing here calls `process.exit`).
- */
+export type UpdateOutcome = 'up-to-date' | 'ahead' | 'available' | 'updated' | 'restart-required' | 'cannot-self-update' | 'not-writable' | 'node-too-old' | 'busy' | 'needs-yes' | 'declined' | 'rolled-back' | 'needs-human' | 'failed';
+/** `update --json`'s document: the check, plus what happened. `--check --json` matches the update-check schema. */
+export interface UpdateDoc extends Partial<UpdateCheck> {
+    outcome: UpdateOutcome;
+    message?: string;
+    url?: string;
+}
+/** Runs `update` and returns the exit code; the caller sets `process.exitCode`. */
 export declare function runUpdate(product: UpdateProduct, opts: UpdateOptions, envp: UpdateEnvironment): Promise<number>;
 /**
- * Find the CLI on disk that reports `wanted`, trying the places it can be.
- *
- * Three candidates, in the order that copes with the most layouts:
+ * The CLI on disk that reports `wanted`, tried in this order (keep it):
  *
- * 1. **`realpath(argv[1])`, resolved NOW.** The bin shim is a symlink, and a
- *    package manager that puts the version in the package's real path (pnpm's
- *    store) repoints that symlink on install. Re-resolving it after the install
- *    is the only candidate that follows.
- * 2. `<npm root -g>/<name>/<binSubpath>` — the npm-global layout, asked of npm
- *    rather than assumed.
- * 3. The package root §6 found, plus the same subpath — right for every layout
- *    whose path does not move.
+ * 1. `realpath(argv[1])`, resolved now: a manager whose real path carries the version (pnpm's store) repoints the
+ *    bin's symlink on install, and only this candidate follows it;
+ * 2. `<npm root -g>/<name>/<binSubpath>`;
+ * 3. the package root §6 found, plus the same subpath.
  *
- * Each is run (`node <cli> --version`) and the first that reports `wanted`
- * wins. That is deliberately stricter than "the file exists": the thing this
- * guards against is handing `service install --refresh` to a CLI that is still
- * the old version, which would produce a green update that changed nothing.
+ * Each is run with `--version`, and the first that reports `wanted` wins. "The file exists" isn't enough: handing the
+ * refresh to a CLI that's still the old version would make a green update that changed nothing.
  */
-export declare function findCli(product: UpdateProduct, info: InstallInfo | undefined, wanted: string, ctx: {
-    spawn?: Spawn;
-    execPath?: string;
-    platform?: NodeJS.Platform;
-    env?: NodeJS.ProcessEnv;
-    fs?: Pick<typeof fsDefault, "existsSync" | "readFileSync" | "realpathSync">;
+export declare function findCli(product: Pick<UpdateProduct, 'entry' | 'packageName' | 'binSubpath'>, info: InstallInfo | undefined, wanted: string, ctx: NpmContext & {
+    fs?: Pick<typeof fsDefault, 'existsSync' | 'realpathSync'>;
 }): string | undefined;