@edspencer/paddock 0.81.0 → 0.82.1

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

@@ -0,0 +1,156 @@
+// From edspencer/cli-contract reference/package-manager.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// Running the package manager (SPEC §5 steps 5, 8 and 10, §6, §7). Node built-ins only.
+//
+// - **npm is the one beside `process.execPath`**, run as `node <npm-cli.js>`, never whichever `npm` is first on PATH.
+//   Under nvm, fnm or volta those are different npms for different Nodes, and the wrong one's `npm root -g` is a
+//   global folder this install isn't in: an ordinary global install would read as a dependency and refuse to update.
+//   Running `npm-cli.js` with this Node also needs no shell on Windows, where `npm.cmd` would (CVE-2024-27980).
+// - **No shell otherwise**, so a path or a name with a space in it can't become two arguments. pnpm, bun and volta on
+//   Windows are `.cmd` files and do need one; their arguments are quoted for `cmd.exe` here.
+// - **Writable means a file can be created**, not just that `access()` says yes (`isWritable`).
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+export const spawnSyncRunner = (cmd, args, opts = {}) => {
+    const r = spawnSync(cmd, args, {
+        encoding: 'utf8',
+        ...(opts.env !== undefined ? { env: opts.env } : {}),
+        ...(opts.shell === true ? { shell: true } : {}),
+        ...(opts.timeoutMs !== undefined ? { timeout: opts.timeoutMs } : {}),
+        maxBuffer: 32 * 1024 * 1024,
+        windowsHide: true,
+    });
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? (r.error ? String(r.error.message) : '') };
+};
+/** How long an install may take. */
+export const INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * How to run the npm that belongs to this Node: `[execPath, npm-cli.js]`, found beside it (`<dir>/npm` is a symlink
+ * to it on POSIX; on Windows it's `<dir>/node_modules/npm/bin/npm-cli.js`). Falls back to `npm` on the PATH, for a
+ * distribution that packages npm separately.
+ */
+export function npmCommand(ctx = {}) {
+    const execPath = ctx.execPath ?? process.execPath;
+    const platform = ctx.platform ?? process.platform;
+    const exists = ctx.exists ?? ((p) => fs.existsSync(p));
+    const realpath = ctx.realpath ?? ((p) => fs.realpathSync(p));
+    const dir = path.dirname(execPath);
+    const candidates = platform === 'win32'
+        ? [path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js')]
+        : [path.join(dir, 'npm'), path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')];
+    for (const c of candidates) {
+        if (!exists(c))
+            continue;
+        let real = c;
+        try {
+            real = realpath(c);
+        }
+        catch {
+            // keep the candidate
+        }
+        if (real.endsWith('.js'))
+            return { cmd: execPath, pre: [real], shell: false };
+    }
+    return platform === 'win32' ? { cmd: 'npm.cmd', pre: [], shell: true } : { cmd: 'npm', pre: [], shell: false };
+}
+/** Quotes each word for `cmd.exe`, for the one case that needs a shell. */
+function cmdLine(cmd, args) {
+    const q = (a) => (/^[\w@./:=+-]+$/.test(a) ? a : `"${a.replace(/"/g, '""')}"`);
+    return { cmd: [cmd, ...args].map(q).join(' '), args: [] };
+}
+function runWith(cmd, args, shell, ctx, timeoutMs) {
+    const run = ctx.spawn ?? spawnSyncRunner;
+    const line = shell ? cmdLine(cmd, args) : { cmd, args };
+    return run(line.cmd, line.args, { ...(ctx.env !== undefined ? { env: ctx.env } : {}), ...(shell ? { shell: true } : {}), timeoutMs });
+}
+/** Runs this Node's npm. */
+export function runNpm(args, ctx = {}, timeoutMs = INSTALL_TIMEOUT_MS) {
+    const { cmd, pre, shell } = npmCommand(ctx);
+    return runWith(cmd, [...pre, ...args], shell, ctx, timeoutMs);
+}
+const lastLine = (r) => {
+    if (r.status !== 0)
+        return undefined;
+    const out = r.stdout.trim().split(/\r?\n/).at(-1)?.trim();
+    return out !== undefined && out !== '' && out !== 'undefined' && out !== 'null' ? out : undefined;
+};
+/** `npm root -g`, or undefined when npm can't answer. */
+export function npmGlobalRoot(ctx = {}) {
+    return lastLine(runNpm(['root', '-g'], ctx, 60_000));
+}
+/** `npm config get <key>`, or undefined. */
+export function npmConfigGet(key, ctx = {}) {
+    return lastLine(runNpm(['config', 'get', key], ctx, 60_000));
+}
+/**
+ * Whether `dir` is really writable (SPEC §5 step 5): a folder is created in it and removed again, the same call npm
+ * is about to make. `access(W_OK)` alone says yes to root on a read-only mount, and nothing about ACLs or immutable
+ * flags. A folder that doesn't exist yet asks its nearest existing parent, since npm would create it.
+ */
+export function isWritable(dir) {
+    let probe = dir;
+    while (!fs.existsSync(probe)) {
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            return false;
+        probe = parent;
+    }
+    try {
+        fs.accessSync(probe, fs.constants.W_OK);
+        fs.rmSync(fs.mkdtempSync(path.join(probe, '.update-probe-')), { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where a manager would install, for `isWritable` to ask about. Only npm can be asked (`npm root -g`). For the others
+ * there's no answer, and an install that can't write fails with that manager's own message, and rolls back.
+ */
+export function globalRootFor(manager, ctx = {}) {
+    return manager === 'npm' ? npmGlobalRoot(ctx) : undefined;
+}
+/** The global install command, per SPEC §6's last column. */
+export function installArgs(manager, spec) {
+    switch (manager) {
+        case 'npm':
+            return { cmd: 'npm', args: ['install', '--global', '--no-audit', '--no-fund', spec] };
+        case 'pnpm':
+            return { cmd: 'pnpm', args: ['add', '-g', spec] };
+        case 'bun':
+            return { cmd: 'bun', args: ['add', '-g', spec] };
+        case 'volta':
+            return { cmd: 'volta', args: ['install', spec] };
+    }
+}
+/** Installs `<name>@<version>` with the manager this install came from. pnpm, bun and volta come from the PATH. */
+export function installPackage(o) {
+    const { cmd, args } = installArgs(o.manager, `${o.packageName}@${o.version}`);
+    if (o.manager === 'npm')
+        return runNpm(args, o);
+    return runWith(cmd, args, (o.platform ?? process.platform) === 'win32', o, INSTALL_TIMEOUT_MS);
+}
+/**
+ * `npm cache add <name>@<version>` (SPEC §5 step 8), for the target and for the current version, while the old one
+ * still serves. Caching the current one is what lets a rollback reinstall it when the network is what failed. npm
+ * is used whatever the manager: it ships with Node, and the point is only to have the tarball on the machine.
+ */
+export function cacheAdd(packageName, version, ctx = {}) {
+    return runNpm(['cache', 'add', `${packageName}@${version}`], ctx);
+}
+/**
+ * A CLI's version, by running it: `node <cli> --version`. This is how `update` shows the install replaced the files
+ * before it hands over. A `package.json` beside it answers a different question: a stale symlink, or a pnpm layout
+ * whose versioned path moved, shows up here and not there.
+ */
+export function cliVersion(cliPath, ctx = {}) {
+    const r = (ctx.spawn ?? spawnSyncRunner)(ctx.execPath ?? process.execPath, [cliPath, '--version'], {
+        ...(ctx.env !== undefined ? { env: ctx.env } : {}),
+        timeoutMs: 60_000,
+    });
+    if (r.status !== 0)
+        return undefined;
+    const line = r.stdout.trim().split(/\r?\n/)[0]?.trim();
+    return line !== undefined && /^\d+\.\d+\.\d+/.test(line) ? line : undefined;
+}

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

@@ -0,0 +1,52 @@
+/** SPEC §5: 10 seconds for each request. */
+export declare const REGISTRY_TIMEOUT_MS = 10000;
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export interface RegistryOptions {
+    packageName: string;
+    /** The base URL; a trailing slash is fine. */
+    registry: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+/**
+ * Which registry to ask: `npm_config_registry`, else `npm config get registry`, else the public one (SPEC §5 step 3).
+ * The variable comes first because it's how npm itself takes the setting, so a test and a real `.npmrc` arrive the
+ * same way.
+ */
+export declare function resolveRegistry(env: NodeJS.ProcessEnv, npmConfigGet?: (key: string) => string | undefined): string;
+/** Joins path parts onto the registry, writing a scoped name's `/` as `%2f` (SPEC §5 step 3). Both routes take it. */
+export declare function registryUrl(registry: string, ...parts: string[]): string;
+/** Anything that went wrong talking to the registry, with the URL, as one reportable error. */
+export declare class RegistryError extends Error {
+    name: string;
+    readonly url: string;
+    constructor(url: string, message: string);
+}
+/** `{ latest: "0.81.0", next: "0.82.0-rc.1" }`. */
+export declare function fetchDistTags(o: RegistryOptions): Promise<Record<string, string>>;
+export interface PackageManifest {
+    name?: string;
+    version?: string;
+    engines?: {
+        node?: string;
+    };
+}
+/** One version's manifest, read for `engines`. */
+export declare function fetchManifest(o: RegistryOptions & {
+    version: string;
+}): Promise<PackageManifest>;
+export interface ResolvedTarget {
+    version: string;
+    /** The dist-tag asked for, or null when `--to` named a version. */
+    tag: string | null;
+    /** The target's `engines.node`. */
+    engines: string | null;
+}
+/**
+ * `--to` (or `latest` without it) as one version, with its `engines`. A version and a tag are told apart by shape:
+ * anything that looks like a version is one. Asking first would be wrong, since a registry may serve a manifest for a
+ * tag's name too, and `--to next` would then install `next` while reporting it as a version called "next".
+ */
+export declare function resolveTarget(o: RegistryOptions & {
+    to?: string;
+}): Promise<ResolvedTarget>;

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

@@ -0,0 +1,102 @@
+// From edspencer/cli-contract reference/registry.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// The npm registry, as `update` asks it (SPEC §5 step 3): two requests with `fetch` and a 10-second abort.
+//
+//   GET <registry>/-/package/<name>/dist-tags   which version `latest` (or `--to <tag>`) is
+//   GET <registry>/<name>/<version>             that version's `engines`
+//
+// Not `npm view`: that's a second of start-up to read two small documents, through a program whose output isn't a
+// contract. Only `update`, `update --check` and `doctor` call this, and only when a person runs them (SPEC §3).
+// Node built-ins only.
+/** SPEC §5: 10 seconds for each request. */
+export const REGISTRY_TIMEOUT_MS = 10_000;
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/**
+ * Which registry to ask: `npm_config_registry`, else `npm config get registry`, else the public one (SPEC §5 step 3).
+ * The variable comes first because it's how npm itself takes the setting, so a test and a real `.npmrc` arrive the
+ * same way.
+ */
+export function resolveRegistry(env, npmConfigGet) {
+    const fromEnv = env.npm_config_registry ?? env.NPM_CONFIG_REGISTRY;
+    if (fromEnv !== undefined && fromEnv.trim() !== '')
+        return fromEnv.trim();
+    const fromNpm = npmConfigGet?.('registry')?.trim();
+    if (fromNpm !== undefined && fromNpm !== '' && fromNpm !== 'undefined')
+        return fromNpm;
+    return DEFAULT_REGISTRY;
+}
+/** Joins path parts onto the registry, writing a scoped name's `/` as `%2f` (SPEC §5 step 3). Both routes take it. */
+export function registryUrl(registry, ...parts) {
+    return `${registry.replace(/\/+$/, '')}/${parts.map((p) => p.replace(/\//g, '%2f')).join('/')}`;
+}
+/** Anything that went wrong talking to the registry, with the URL, as one reportable error. */
+export class RegistryError extends Error {
+    name = 'RegistryError';
+    url;
+    constructor(url, message) {
+        super(message);
+        this.url = url;
+    }
+}
+async function getJson(url, o) {
+    const timeoutMs = o.timeoutMs ?? REGISTRY_TIMEOUT_MS;
+    let res;
+    try {
+        res = await (o.fetch ?? globalThis.fetch)(url, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } });
+    }
+    catch (err) {
+        const name = err.name;
+        const why = name === 'TimeoutError' || name === 'AbortError' ? `no answer within ${timeoutMs / 1000} seconds` : (err.message ?? String(err));
+        throw new RegistryError(url, `couldn't reach the registry: ${why}`);
+    }
+    if (res.status === 404)
+        throw new RegistryError(url, 'the registry has no such package or version');
+    if (!res.ok)
+        throw new RegistryError(url, `the registry answered HTTP ${res.status}`);
+    try {
+        return (await res.json());
+    }
+    catch {
+        throw new RegistryError(url, "the registry's answer isn't JSON");
+    }
+}
+/** `{ latest: "0.81.0", next: "0.82.0-rc.1" }`. */
+export async function fetchDistTags(o) {
+    const url = registryUrl(o.registry, '-', 'package', o.packageName, 'dist-tags');
+    const tags = {};
+    for (const [k, v] of Object.entries(await getJson(url, o)))
+        if (typeof v === 'string')
+            tags[k] = v;
+    if (Object.keys(tags).length === 0)
+        throw new RegistryError(url, 'the registry lists no dist-tags');
+    return tags;
+}
+/** One version's manifest, read for `engines`. */
+export function fetchManifest(o) {
+    return getJson(registryUrl(o.registry, o.packageName, o.version), o);
+}
+/**
+ * `--to` (or `latest` without it) as one version, with its `engines`. A version and a tag are told apart by shape:
+ * anything that looks like a version is one. Asking first would be wrong, since a registry may serve a manifest for a
+ * tag's name too, and `--to next` would then install `next` while reporting it as a version called "next".
+ */
+export async function resolveTarget(o) {
+    const to = o.to?.trim();
+    let version;
+    let tag;
+    if (to !== undefined && /^v?\d+\.\d+\.\d+/.test(to)) {
+        version = to.replace(/^v/, '');
+        tag = null;
+    }
+    else {
+        tag = to ?? 'latest';
+        const tags = await fetchDistTags(o);
+        const resolved = tags[tag];
+        if (resolved === undefined) {
+            const url = registryUrl(o.registry, '-', 'package', o.packageName, 'dist-tags');
+            throw new RegistryError(url, `no dist-tag \`${tag}\` (the registry has: ${Object.keys(tags).sort().join(', ')})`);
+        }
+        version = resolved;
+    }
+    const manifest = await fetchManifest({ ...o, version });
+    return { version, tag, engines: manifest.engines?.node ?? null };
+}

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

@@ -0,0 +1,45 @@
+export interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+    /** The dot-separated identifiers after `-`; empty for a release. */
+    prerelease: (string | number)[];
+}
+/** `1.2.3-rc.1` as a `Version`, or undefined if it isn't one. */
+export declare function parseVersion(raw: string): Version | undefined;
+/** SPEC §5: prereleases count only when `--to` names them. */
+export declare function isPrerelease(raw: string): boolean;
+/**
+ * -1, 0 or 1, by semver's rules: `1.0.0-rc.1` is lower than `1.0.0`, numeric identifiers compare as numbers and sort
+ * below alphanumeric ones, and a longer run of identifiers wins when the shared ones are equal. Build metadata is
+ * ignored. Something that isn't a version compares as equal rather than throwing.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/** Whether `a` is strictly newer than `b`. */
+export declare const isNewer: (a: string, b: string) => boolean;
+/** The highest of a list, ignoring anything that isn't a version. */
+export declare function maxVersion(versions: readonly string[]): string | undefined;
+/** `0.82.0` → `0.83.0` (`minor`), or `0.82.1` (`patch`). A prerelease's suffix is dropped. */
+export declare function bumpVersion(raw: string, part: 'major' | 'minor' | 'patch'): string;
+/**
+ * Whether `version` satisfies `range`; undefined when this file can't tell.
+ *
+ * Reads what `engines.node` uses in practice: `>=22`, `>=22.0.0`, `^22.1.0`, `~22.1`, `22`, `22.x`, `>=20 <23`, and
+ * `||` between them. `*` and an empty range accept everything. Alternatives it can't read are ignored; if it can read
+ * none of them, the answer is undefined.
+ */
+export declare function satisfies(version: string, range: string): boolean | undefined;
+export interface EnginesVerdict {
+    /** true passes, false fails, undefined when the range couldn't be read. */
+    ok: boolean | undefined;
+    /** The range as published, for the message. */
+    range: string | undefined;
+}
+/**
+ * Will the target run on this Node? (SPEC §5 step 4.) No `engines.node`, or one this file can't read, doesn't block
+ * an update: callers treat `ok: undefined` as a pass. A false refusal leaves a tool that can't update itself, saying
+ * something nobody can act on; letting an unsuitable Node through fails the install, and the rollback runs.
+ */
+export declare function satisfiesEngines(nodeVersion: string, engines: {
+    node?: string;
+} | undefined): EnginesVerdict;

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

@@ -0,0 +1,182 @@
+// From edspencer/cli-contract reference/semver.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// The small semver `update` needs (SPEC §5 step 4): is the target newer, is it a prerelease, and does its
+// `engines.node` accept this Node. Node built-ins only.
+//
+// It deliberately leaves out hyphen ranges (`1.2 - 2.3`) and build-metadata ordering. A range it can't read is
+// "can't tell" (undefined), not "fails": refusing an update over a range this file doesn't understand would be the
+// worse mistake of the two (`satisfiesEngines`).
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
+const identifiers = (s) => s.split('.').map((id) => (/^\d+$/.test(id) ? Number(id) : id));
+/** `1.2.3-rc.1` as a `Version`, or undefined if it isn't one. */
+export function parseVersion(raw) {
+    const m = VERSION_RE.exec(raw.trim());
+    if (m === null)
+        return undefined;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), prerelease: m[4] === undefined ? [] : identifiers(m[4]) };
+}
+/** 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 semver's rules: `1.0.0-rc.1` is lower than `1.0.0`, numeric identifiers compare as numbers and sort
+ * below alphanumeric ones, and a longer run of identifiers wins when the shared ones are equal. Build metadata is
+ * ignored. Something that isn't a version compares as equal rather than throwing.
+ */
+export function compareVersions(a, b) {
+    const va = parseVersion(a);
+    const vb = parseVersion(b);
+    if (va === undefined || vb === undefined)
+        return 0;
+    return compare(va, vb);
+}
+function compare(va, vb) {
+    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;
+        if (typeof x === 'number' && typeof y === 'number')
+            return x < y ? -1 : 1;
+        if (typeof x === 'number')
+            return -1;
+        if (typeof y === 'number')
+            return 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/** Whether `a` is strictly newer than `b`. */
+export const isNewer = (a, b) => compareVersions(a, b) > 0;
+/** The highest of a list, ignoring anything that isn't a version. */
+export function maxVersion(versions) {
+    let best;
+    for (const v of versions) {
+        if (parseVersion(v) !== undefined && (best === undefined || isNewer(v, best)))
+            best = v;
+    }
+    return best;
+}
+/** `0.82.0` → `0.83.0` (`minor`), or `0.82.1` (`patch`). A prerelease's suffix is dropped. */
+export function bumpVersion(raw, part) {
+    const v = parseVersion(raw);
+    if (v === undefined)
+        throw new Error(`not a version: ${raw}`);
+    if (part === 'major')
+        return `${v.major + 1}.0.0`;
+    if (part === 'minor')
+        return `${v.major}.${v.minor + 1}.0`;
+    return `${v.major}.${v.minor}.${v.patch + 1}`;
+}
+const COMPARATOR_RE = /^(>=|<=|>|<|=|\^|~)?\s*v?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z.-]+))?$/;
+/**
+ * One range atom as the comparators it means: `^22.1.0` is `>=22.1.0 <23.0.0`, `~22.1.0` is `>=22.1.0 <22.2.0`, and
+ * a bare `22` is `>=22.0.0 <23.0.0` (npm's partial versions). Undefined for anything else.
+ */
+function comparatorsFor(atom) {
+    const m = COMPARATOR_RE.exec(atom);
+    if (m === null)
+        return undefined;
+    const op = m[1] ?? '=';
+    const wild = (s) => s === undefined || s === 'x' || s === 'X' || s === '*';
+    const major = Number(m[2]);
+    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 at = (ma, mi, pa) => ({ major: ma, minor: mi, patch: pa, prerelease: [] });
+    const lower = { major, minor, patch, prerelease: m[5] === undefined ? [] : identifiers(m[5]) };
+    const between = (upper) => [
+        { op: '>=', version: lower },
+        { op: '<', version: upper },
+    ];
+    // `^0.x` tightens: ^0.2.3 is >=0.2.3 <0.3.0, ^0.0.3 is >=0.0.3 <0.0.4, ^0.0 is <0.1.0 and ^0 is <1.0.0.
+    if (op === '^') {
+        if (major > 0 || minorWild)
+            return between(at(major + 1, 0, 0));
+        if (minor > 0 || patchWild)
+            return between(at(0, minor + 1, 0));
+        return between(at(0, 0, patch + 1));
+    }
+    if (op === '~')
+        return between(minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0));
+    // A partial version with no operator is a range: `22` is the whole 22 line, `22.1` the whole 22.1 line.
+    if (op === '=' && (minorWild || patchWild))
+        return between(minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0));
+    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;
+    }
+}
+/**
+ * Whether `version` satisfies `range`; undefined when this file can't tell.
+ *
+ * Reads what `engines.node` uses in practice: `>=22`, `>=22.0.0`, `^22.1.0`, `~22.1`, `22`, `22.x`, `>=20 <23`, and
+ * `||` between them. `*` and an empty range accept everything. Alternatives it can't read are ignored; if it can read
+ * none of them, the answer is undefined.
+ */
+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;
+    let known = false;
+    for (const alt of trimmed.split('||')) {
+        const comparators = [];
+        let parsed = true;
+        for (const atom of alt.trim().split(/\s+/).filter(Boolean)) {
+            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;
+    }
+    return known ? false : undefined;
+}
+/**
+ * Will the target run on this Node? (SPEC §5 step 4.) No `engines.node`, or one this file can't read, doesn't block
+ * an update: callers treat `ok: undefined` as a pass. A false refusal leaves a tool that can't update itself, saying
+ * something nobody can act on; letting an unsuitable Node through fails the install, and the rollback runs.
+ */
+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,69 @@
+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. */
+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; null once there's nothing to do. */
+    command: string | null;
+    engines: string | null;
+    nodeOk: boolean;
+    changelog: string | null;
+    /** ISO 8601. */
+    checkedAt: string;
+}
+/** `service status --json`'s `update` (`schemas/service-status.schema.json`). */
+export interface UpdateSummary {
+    latest: string;
+    updateAvailable: boolean;
+    checkedAt: string;
+}
+/**
+ * Writes the cache atomically, so `status` never reads half a file and says nothing. It never throws: a cache that
+ * couldn't be written isn't a failed update.
+ */
+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: long enough for "I checked on Monday, it's Friday", short enough that
+ * `status` doesn't advertise a version that's since been superseded twice.
+ */
+export declare const UPDATE_CHECK_MAX_AGE_MS: number;
+/**
+ * What `service status` repeats, or undefined when there's nothing worth repeating: no cache, a cache for another
+ * version than this one, or one that's too old. Leave `update` out of `status --json` then: the schema types it as an
+ * object, so it's absent, never null.
+ */
+export declare function updateSummary(home: string, o?: {
+    now?: number;
+    maxAgeMs?: number;
+    currentVersion?: string;
+}): UpdateSummary | undefined;
+export interface NoticeInput {
+    name: string;
+    current: string;
+    target: string;
+    /** `<tool> update`, or the command this install needs instead. */
+    command: string;
+    /** What goes in brackets after it: `the global folder isn't writable`. */
+    note?: string;
+    changelog?: string | null;
+}
+/**
+ * SPEC §3's notice, for the caller to put on stderr:
+ *
+ * ```
+ * 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
+ * ```
+ */
+export declare function updateNotice(o: NoticeInput): string;