@edspencer/paddock 0.81.0 → 0.82.0

package/packages/server/dist/cli/update/semver.js

@@ -0,0 +1,232 @@
+/**
+ * The small semver `update` needs, and no more (CLI contract SPEC §5 step 4).
+ *
+ * Three questions are asked of versions in this contract: is the target newer
+ * than what we have, is it a prerelease, and does the target's `engines.node`
+ * accept the Node running the update. That is it — so this is ~120 lines of
+ * Node built-ins rather than a dependency, which is what SPEC §5 asks for and
+ * what keeps `update` runnable from a CLI that must not load the server.
+ *
+ * **What it deliberately does not do.** No `semver` package behaviours beyond
+ * the above: no ranges with hyphens (`1.2 - 2.3`), no `x`-ranges (`1.x`), no
+ * build metadata ordering. An `engines.node` we cannot parse is reported as
+ * "cannot tell" rather than as "fails", because refusing an update on the
+ * strength of a range this file does not understand would be the worse error of
+ * the two — see {@link satisfiesEngines}.
+ *
+ * Generic: wave C4 lifts this into `reference/` with the rest of `update`.
+ */
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
+/** `1.2.3-rc.1` → a {@link Version}, or undefined if it is not a version. */
+export function parseVersion(raw) {
+    const m = VERSION_RE.exec(raw.trim());
+    if (m === null)
+        return undefined;
+    const prerelease = m[4] === undefined
+        ? []
+        : m[4].split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id));
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), prerelease };
+}
+/** Is this a prerelease? SPEC §5: prereleases count only when `--to` names them. */
+export function isPrerelease(raw) {
+    return (parseVersion(raw)?.prerelease.length ?? 0) > 0;
+}
+/**
+ * -1, 0 or 1, by the semver rules — including the prerelease ones, which are
+ * the only interesting part: `1.0.0-rc.1` is LOWER than `1.0.0`, numeric
+ * identifiers compare numerically and sort below alphanumeric ones, and a
+ * longer run of identifiers wins when every shared one is equal.
+ *
+ * Build metadata is ignored, as semver says it must be.
+ */
+export function compareVersions(a, b) {
+    const va = parseVersion(a);
+    const vb = parseVersion(b);
+    // Unparseable compares as equal rather than throwing: the callers all have a
+    // better answer for "I cannot tell" than a crash (`update` says the registry
+    // gave it something it did not understand, and stops).
+    if (va === undefined || vb === undefined)
+        return 0;
+    for (const k of ["major", "minor", "patch"]) {
+        if (va[k] !== vb[k])
+            return va[k] < vb[k] ? -1 : 1;
+    }
+    if (va.prerelease.length === 0 && vb.prerelease.length === 0)
+        return 0;
+    if (va.prerelease.length === 0)
+        return 1;
+    if (vb.prerelease.length === 0)
+        return -1;
+    const n = Math.max(va.prerelease.length, vb.prerelease.length);
+    for (let i = 0; i < n; i++) {
+        const x = va.prerelease[i];
+        const y = vb.prerelease[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        if (x === y)
+            continue;
+        const xNum = typeof x === "number";
+        const yNum = typeof y === "number";
+        if (xNum && yNum)
+            return x < y ? -1 : 1;
+        if (xNum)
+            return -1;
+        if (yNum)
+            return 1;
+        return String(x) < String(y) ? -1 : 1;
+    }
+    return 0;
+}
+/** Is `a` strictly newer than `b`? */
+export const isNewer = (a, b) => compareVersions(a, b) > 0;
+/** The highest of a list, ignoring anything unparseable. Undefined if none parse. */
+export function maxVersion(versions) {
+    let best;
+    for (const v of versions) {
+        if (parseVersion(v) === undefined)
+            continue;
+        if (best === undefined || isNewer(v, best))
+            best = v;
+    }
+    return best;
+}
+const COMPARATOR_RE = /^(>=|<=|>|<|=|\^|~)?\s*v?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z.-]+))?$/;
+/**
+ * Expand one range atom into the comparators it means.
+ *
+ * `^22.1.0` is `>=22.1.0 <23.0.0`; `~22.1.0` is `>=22.1.0 <22.2.0`; a bare
+ * `22` is `>=22.0.0 <23.0.0` (npm's partial-version semantics, which is what
+ * `engines: { node: "22" }` means in the wild). Returns undefined for anything
+ * this file does not understand, which propagates up as "cannot tell".
+ */
+function comparatorsFor(atom) {
+    const m = COMPARATOR_RE.exec(atom);
+    if (m === null)
+        return undefined;
+    const op = m[1] ?? "=";
+    const major = Number(m[2]);
+    const wild = (s) => s === undefined || s === "x" || s === "X" || s === "*";
+    const minorWild = wild(m[3]);
+    const patchWild = wild(m[4]);
+    const minor = minorWild ? 0 : Number(m[3]);
+    const patch = patchWild ? 0 : Number(m[4]);
+    const prerelease = m[5] === undefined ? [] : m[5].split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id));
+    const at = (ma, mi, pa) => ({
+        major: ma,
+        minor: mi,
+        patch: pa,
+        prerelease: [],
+    });
+    const lower = { major, minor, patch, prerelease };
+    if (op === "^") {
+        // `^0.x` tightens: ^0.2.3 is >=0.2.3 <0.3.0, ^0.0.3 is >=0.0.3 <0.0.4.
+        const upper = major > 0
+            ? at(major + 1, 0, 0)
+            : minor > 0 || !minorWild
+                ? at(0, minor + 1, 0)
+                : at(1, 0, 0);
+        return [
+            { op: ">=", version: lower },
+            { op: "<", version: upper },
+        ];
+    }
+    if (op === "~") {
+        const upper = minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0);
+        return [
+            { op: ">=", version: lower },
+            { op: "<", version: upper },
+        ];
+    }
+    if (op === "=" && (minorWild || patchWild)) {
+        // A partial version with no operator is a range, not an equality: `22`
+        // means the whole 22 line, and `22.1` means the whole 22.1 line.
+        const upper = minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0);
+        return [
+            { op: ">=", version: lower },
+            { op: "<", version: upper },
+        ];
+    }
+    if (minorWild || patchWild) {
+        // `>=22` / `<23`: fill the missing parts with zero, which is what the
+        // comparison wants in both directions.
+        return [{ op: op, version: lower }];
+    }
+    return [{ op: op, version: lower }];
+}
+function satisfiesComparator(v, c) {
+    const cmp = compare(v, c.version);
+    switch (c.op) {
+        case ">=":
+            return cmp >= 0;
+        case "<=":
+            return cmp <= 0;
+        case ">":
+            return cmp > 0;
+        case "<":
+            return cmp < 0;
+        case "=":
+            return cmp === 0;
+    }
+}
+function compare(a, b) {
+    return compareVersions(stringify(a), stringify(b));
+}
+function stringify(v) {
+    const base = `${v.major}.${v.minor}.${v.patch}`;
+    return v.prerelease.length === 0 ? base : `${base}-${v.prerelease.join(".")}`;
+}
+/**
+ * Does `version` satisfy `range`? Undefined means "this file cannot tell".
+ *
+ * Supports the forms an `engines.node` actually uses: `>=22`, `>=22.0.0`,
+ * `^22.1.0`, `~22.1`, `22`, `22.x`, `>=20 <23`, and `||` between any of those.
+ * `*` and an empty range accept everything.
+ */
+export function satisfies(version, range) {
+    const v = parseVersion(version);
+    if (v === undefined)
+        return undefined;
+    const trimmed = range.trim();
+    if (trimmed === "" || trimmed === "*" || trimmed === "x")
+        return true;
+    const alternatives = trimmed.split("||");
+    let known = false;
+    for (const alt of alternatives) {
+        const atoms = alt.trim().split(/\s+/).filter(Boolean);
+        const comparators = [];
+        let parsed = true;
+        for (const atom of atoms) {
+            const cs = comparatorsFor(atom);
+            if (cs === undefined) {
+                parsed = false;
+                break;
+            }
+            comparators.push(...cs);
+        }
+        if (!parsed)
+            continue;
+        known = true;
+        if (comparators.every((c) => satisfiesComparator(v, c)))
+            return true;
+    }
+    // Every alternative we could read said no. If we could read none of them, say
+    // so rather than claiming a refusal.
+    return known ? false : undefined;
+}
+/**
+ * Will the target version run on this Node? (SPEC §5 step 4.)
+ *
+ * The three-way answer is the point. A target with no `engines.node` at all, or
+ * one whose range this file cannot parse, must NOT block an update: the cost of
+ * a false refusal is a tool that cannot update itself and says something the
+ * user cannot act on, while the cost of letting an incompatible Node through is
+ * the failure `engines` would have produced anyway, with a rollback behind it.
+ */
+export function satisfiesEngines(nodeVersion, engines) {
+    const range = engines?.node;
+    if (range === undefined || range.trim() === "")
+        return { ok: true, range: undefined };
+    return { ok: satisfies(nodeVersion, range), range };
+}

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

@@ -0,0 +1,80 @@
+import type { InstallMethod } from "./install-method.js";
+export declare const UPDATE_CHECK_FILE = "update-check.json";
+export declare function updateCheckPath(home: string): string;
+/** `update --check --json`, and the cached copy. Matches `schemas/update-check.schema.json`. */
+export interface UpdateCheck {
+    name: string;
+    current: string;
+    target: string;
+    /** The dist-tag asked for, or null when `--to` named a version. */
+    tag: string | null;
+    updateAvailable: boolean;
+    installMethod: InstallMethod;
+    canUpdate: boolean;
+    /** `<tool> update`, or the command this install needs instead. */
+    command: string | null;
+    engines: string | null;
+    nodeOk: boolean;
+    changelog: string | null;
+    /** ISO 8601. */
+    checkedAt: string;
+}
+/** What `service status --json` carries (`schemas/service-status.schema.json`). */
+export interface UpdateSummary {
+    latest: string;
+    updateAvailable: boolean;
+    checkedAt: string;
+}
+/**
+ * Write the cache atomically.
+ *
+ * Atomic because `service status` reads it on a path where a torn read has no
+ * recovery worth having — it would report `updateAvailable` as absent and say
+ * nothing, which is indistinguishable from "never checked". Best-effort:
+ * failing to write a cache must never fail an update, so this throws nothing.
+ */
+export declare function writeUpdateCheck(home: string, check: UpdateCheck): void;
+/** The cache, or null when there isn't one (or it isn't one). */
+export declare function readUpdateCheck(home: string): UpdateCheck | null;
+/**
+ * How long a cached answer is worth repeating.
+ *
+ * `status` says "0.81.0 is available" on the strength of a file, so the file
+ * has to be recent enough that the claim is still likely true. A week is long
+ * enough to cover "I checked on Monday, it is Friday" and short enough that a
+ * months-old file does not have `status` advertising a version that has since
+ * been superseded twice.
+ */
+export declare const UPDATE_CHECK_MAX_AGE_MS: number;
+/**
+ * The summary `service status` shows, or undefined when there is nothing worth
+ * repeating: no cache, a cache from a different install, or one too old.
+ */
+export declare function updateSummary(home: string, o?: {
+    now?: number;
+    maxAgeMs?: number;
+}): UpdateSummary | undefined;
+export interface NoticeInput {
+    name: string;
+    current: string;
+    target: string;
+    /** `paddock update`, or the command this install needs instead (SPEC §3, §6). */
+    command: string;
+    /** The parenthetical after the command: `the global folder isn't writable`. */
+    note?: string;
+    changelog?: string | null;
+}
+/**
+ * SPEC §3's update notice, verbatim in shape:
+ *
+ * ```
+ * Paddock 0.80.0 is available (you have 0.79.1).
+ *   Run: paddock update
+ *   Changes: https://github.com/edspencer/paddock/releases/tag/v0.80.0
+ * ```
+ *
+ * Returned as a string rather than printed, because the caller decides the
+ * stream: §3 puts this on **stderr**, always, so that a `--json` document on
+ * stdout stays the only thing on stdout.
+ */
+export declare function updateNotice(o: NoticeInput): string;

package/packages/server/dist/cli/update/update-check.js

@@ -0,0 +1,116 @@
+/**
+ * `<home>/update-check.json` — what the last registry question found
+ * (CLI contract SPEC §3).
+ *
+ * The contract's rule is that **nothing contacts the registry by itself**: only
+ * `update`, `update --check` and `doctor` ask, and only when a person runs
+ * them. But `service status` should still be able to mention a newer version,
+ * because that is where someone looks. The cache is how both hold: the three
+ * commands that ask write what they found here, and `status` reads the file and
+ * never opens a socket.
+ *
+ * The document is the one `schemas/update-check.schema.json` describes, so
+ * `update --check --json` and this file are the same shape — one less thing to
+ * keep in step, and `status --json`'s `update` object is a projection of it.
+ *
+ * Generic: wave C4 lifts this into `reference/`. Node built-ins only.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const UPDATE_CHECK_FILE = "update-check.json";
+export function updateCheckPath(home) {
+    return path.join(home, UPDATE_CHECK_FILE);
+}
+/**
+ * Write the cache atomically.
+ *
+ * Atomic because `service status` reads it on a path where a torn read has no
+ * recovery worth having — it would report `updateAvailable` as absent and say
+ * nothing, which is indistinguishable from "never checked". Best-effort:
+ * failing to write a cache must never fail an update, so this throws nothing.
+ */
+export function writeUpdateCheck(home, check) {
+    try {
+        fs.mkdirSync(home, { recursive: true });
+        const file = updateCheckPath(home);
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(check, null, 2)}\n`, { mode: 0o600 });
+        try {
+            fs.renameSync(tmp, file);
+        }
+        catch (err) {
+            fs.rmSync(tmp, { force: true });
+            throw err;
+        }
+    }
+    catch {
+        /* a cache that could not be written is not a failed update */
+    }
+}
+/** The cache, or null when there isn't one (or it isn't one). */
+export function readUpdateCheck(home) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(updateCheckPath(home), "utf8"));
+        if (typeof raw.name === "string" &&
+            typeof raw.current === "string" &&
+            typeof raw.target === "string" &&
+            typeof raw.updateAvailable === "boolean" &&
+            typeof raw.checkedAt === "string") {
+            return raw;
+        }
+    }
+    catch {
+        /* missing, half-written, or from something else */
+    }
+    return null;
+}
+/**
+ * How long a cached answer is worth repeating.
+ *
+ * `status` says "0.81.0 is available" on the strength of a file, so the file
+ * has to be recent enough that the claim is still likely true. A week is long
+ * enough to cover "I checked on Monday, it is Friday" and short enough that a
+ * months-old file does not have `status` advertising a version that has since
+ * been superseded twice.
+ */
+export const UPDATE_CHECK_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * The summary `service status` shows, or undefined when there is nothing worth
+ * repeating: no cache, a cache from a different install, or one too old.
+ */
+export function updateSummary(home, o = {}) {
+    const check = readUpdateCheck(home);
+    if (check === null)
+        return undefined;
+    const at = Date.parse(check.checkedAt);
+    if (!Number.isFinite(at))
+        return undefined;
+    const age = (o.now ?? Date.now()) - at;
+    if (age > (o.maxAgeMs ?? UPDATE_CHECK_MAX_AGE_MS))
+        return undefined;
+    return {
+        latest: check.target,
+        updateAvailable: check.updateAvailable,
+        checkedAt: check.checkedAt,
+    };
+}
+/**
+ * SPEC §3's update notice, verbatim in shape:
+ *
+ * ```
+ * Paddock 0.80.0 is available (you have 0.79.1).
+ *   Run: paddock update
+ *   Changes: https://github.com/edspencer/paddock/releases/tag/v0.80.0
+ * ```
+ *
+ * Returned as a string rather than printed, because the caller decides the
+ * stream: §3 puts this on **stderr**, always, so that a `--json` document on
+ * stdout stays the only thing on stdout.
+ */
+export function updateNotice(o) {
+    const lines = [`${o.name} ${o.target} is available (you have ${o.current}).`];
+    lines.push(`  Run: ${o.command}${o.note !== undefined ? `    (${o.note})` : ""}`);
+    if (o.changelog !== undefined && o.changelog !== null)
+        lines.push(`  Changes: ${o.changelog}`);
+    return lines.join("\n");
+}

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

@@ -0,0 +1,160 @@
+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";
+/** SPEC §5 step 12: 30 seconds unless the tool sets its own. */
+export declare const HEALTH_TIMEOUT_MS = 30000;
+/** 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. */
+export interface UpdateOptions {
+    /** Report and change nothing (SPEC §1). */
+    check?: boolean;
+    /** A version or a dist-tag. The only way to move to a lower version. */
+    to?: string;
+    /** Skip the question. Required 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. */
+export interface ServiceSnapshot {
+    installed: boolean;
+    running: boolean;
+    /** The URL the installed unit serves, when there is one. */
+    url?: string;
+    /** The log file the unit names, for the failure tail. */
+    log?: string;
+}
+export interface UpdateServiceHooks {
+    /** Is a unit installed, is it running, and where. */
+    inspect(): ServiceSnapshot;
+    /** Stop the service. Throws with the supervisor's own words on failure. */
+    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.
+     */
+    refresh(cliPath: string): RunResult;
+    /** The last `lines` lines of the service log, or '' when there is no log. */
+    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. */
+    tool: string;
+    /** `@edspencer/paddock`. */
+    packageName: string;
+    /** `PADDOCK` — gives `PADDOCK_IN_DOCKER` and `PADDOCK_UPDATE_HINT`. */
+    envPrefix: string;
+    /** The data home: `<home>/update.lock` and `<home>/update-check.json`. */
+    home: string;
+    /** This CLI's own 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.
+     */
+    entry: string;
+    /** Where the CLI sits inside the package: `packages/server/dist/cli/paddock.js`. */
+    binSubpath: string;
+    /** The container 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.
+     */
+    usage?: string;
+    /** The release notes for a version. */
+    changelogUrl(version: string): string;
+    healthTimeoutMs?: number;
+    /** The busy check (SPEC §5 step 6): null to go ahead, or 75 having printed why. */
+    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: {
+        url: string;
+        version: string;
+        timeoutMs: number;
+    }): Promise<HealthVerdict>;
+}
+/** Everything that touches the world, injected so the sequence is testable. */
+export interface UpdateEnvironment {
+    out: Output;
+    env?: NodeJS.ProcessEnv;
+    spawn?: Spawn;
+    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.) */
+    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.
+     */
+    nodeVersion?: string;
+    /** Ask the question. Only called when {@link isTTY} and `--yes` was not given. */
+    confirm?: (question: string) => Promise<boolean>;
+    /** Injected for tests: `isWritable`. */
+    writable?: (dir: string) => boolean;
+}
+/**
+ * Run `update`, and return the exit code (SPEC §2: the caller assigns
+ * `process.exitCode`; nothing here calls `process.exit`).
+ */
+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:
+ *
+ * 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.
+ *
+ * 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.
+ */
+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">;
+}): string | undefined;