@edspencer/paddock 0.81.0 → 0.82.0

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

@@ -0,0 +1,221 @@
+/**
+ * Running the package manager (CLI contract SPEC §5 steps 8 and 10, §6, §7).
+ *
+ * Three jobs, all of them small and all of them easy to get subtly wrong:
+ *
+ * - **Find npm.** SPEC §6 and §10 both say the `npm` next to
+ *   `process.execPath`, not whatever is on PATH. Under nvm, fnm or volta those
+ *   are routinely different npms belonging to different Nodes, and asking the
+ *   wrong one `npm root -g` gets a global folder this install is not in — which
+ *   would report a perfectly ordinary global install as a `dependency` and
+ *   refuse to update it.
+ * - **No shell.** `spawnSync(npm, args)` with the default `shell: false`, so a
+ *   package name or a path with a space in it cannot become two arguments.
+ *   Windows is the exception and has to be: `npm` there is `npm.cmd`, which
+ *   Node refuses to spawn without a shell since its fix for CVE-2024-27980
+ *   (SPEC §7). That path quotes its arguments itself.
+ * - **Can we write there?** SPEC §5 step 5. Asked before anything is stopped,
+ *   and answered by actually creating a file rather than by `access()` alone —
+ *   see {@link isWritable}.
+ *
+ * Generic: wave C4 lifts this into `reference/`. Node built-ins only.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+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,
+    });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+};
+/**
+ * The npm that belongs to the Node running us.
+ *
+ * `<dirname(execPath)>/npm` on POSIX; on Windows the sibling is `npm.cmd`.
+ * Falls back to the bare name — if the sibling is not there (a distro that
+ * splits node and npm into separate packages), PATH is the only answer left and
+ * is better than failing.
+ */
+export function npmBeside(execPath = process.execPath, platform = process.platform) {
+    const dir = path.dirname(execPath);
+    const candidate = path.join(dir, platform === "win32" ? "npm.cmd" : "npm");
+    try {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    catch {
+        /* fall through */
+    }
+    return platform === "win32" ? "npm.cmd" : "npm";
+}
+/** Run npm with no shell (except on Windows, where `npm.cmd` needs one). */
+export function runNpm(args, ctx = {}) {
+    const platform = ctx.platform ?? process.platform;
+    const cmd = npmBeside(ctx.execPath ?? process.execPath, platform);
+    const run = ctx.spawn ?? spawnSyncRunner;
+    return run(cmd, args, {
+        ...(ctx.env !== undefined ? { env: ctx.env } : {}),
+        // The ONE place a shell is used, and only where Node leaves no choice. The
+        // arguments passed through here are package specs and npm flags we build
+        // ourselves, never user text.
+        ...(platform === "win32" ? { shell: true } : {}),
+        timeoutMs: 15 * 60 * 1000,
+    });
+}
+/** `npm root -g`, or undefined when npm could not answer. */
+export function npmGlobalRoot(ctx = {}) {
+    const r = runNpm(["root", "-g"], ctx);
+    if (r.status !== 0)
+        return undefined;
+    const out = r.stdout.trim().split("\n").at(-1)?.trim();
+    return out !== undefined && out !== "" ? out : undefined;
+}
+/** `npm config get <key>`, or undefined. Used to resolve the registry (SPEC §5 step 3). */
+export function npmConfigGet(key, ctx = {}) {
+    const r = runNpm(["config", "get", key], ctx);
+    if (r.status !== 0)
+        return undefined;
+    const out = r.stdout.trim().split("\n").at(-1)?.trim();
+    return out !== undefined && out !== "" && out !== "undefined" && out !== "null" ? out : undefined;
+}
+/**
+ * Really writable? (SPEC §5 step 5.)
+ *
+ * `access(W_OK)` alone is not enough and the difference is the whole point of
+ * this check. It consults the mode bits, which say yes for root and say
+ * nothing about a read-only mount, an immutable flag, or an ACL — the usual
+ * shapes of "npm install -g needs sudo". So the directory is probed by
+ * CREATING something in it and removing it again, which is the same syscall
+ * npm is about to make.
+ *
+ * A missing directory walks up to its nearest existing parent: npm would create
+ * it, and whether it can is the parent's question.
+ */
+export function isWritable(dir) {
+    let probe = dir;
+    for (;;) {
+        if (fs.existsSync(probe))
+            break;
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            return false;
+        probe = parent;
+    }
+    try {
+        fs.accessSync(probe, fs.constants.W_OK);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const tmp = fs.mkdtempSync(path.join(probe, ".update-probe-"));
+        fs.rmSync(tmp, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where a package manager would put the package, so {@link isWritable} has a
+ * directory to ask about.
+ *
+ * Only npm can be asked properly (`npm root -g`). For the others the install
+ * command's own target is a good enough proxy — and if it is wrong, the install
+ * fails with that manager's own message and the rollback runs, which is a worse
+ * experience than the sudo hint but not a worse outcome.
+ */
+export function globalRootFor(manager, ctx = {}) {
+    if (manager === "npm")
+        return npmGlobalRoot(ctx);
+    return undefined;
+}
+/** The argv for a global install, per SPEC §6's last column. */
+export function installArgs(manager, spec) {
+    switch (manager) {
+        case "npm":
+            // `--no-audit --no-fund` keeps the output to the point; `--global` is
+            // spelled out rather than `-g` so a log of what ran reads plainly.
+            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] };
+    }
+}
+/**
+ * Install `<name>@<version>` with the manager this install came from.
+ *
+ * npm goes through {@link runNpm}, so it is the npm beside this Node. The other
+ * three are looked up on PATH, which is the only place they are: pnpm, bun and
+ * volta are not installed beside node.
+ */
+export function installPackage(o) {
+    const spec = `${o.packageName}@${o.version}`;
+    const { cmd, args } = installArgs(o.manager, spec);
+    if (o.manager === "npm") {
+        return runNpm(args, {
+            ...(o.spawn !== undefined ? { spawn: o.spawn } : {}),
+            ...(o.env !== undefined ? { env: o.env } : {}),
+            ...(o.execPath !== undefined ? { execPath: o.execPath } : {}),
+            ...(o.platform !== undefined ? { platform: o.platform } : {}),
+        });
+    }
+    const run = o.spawn ?? spawnSyncRunner;
+    return run(cmd, args, {
+        ...(o.env !== undefined ? { env: o.env } : {}),
+        ...((o.platform ?? process.platform) === "win32" ? { shell: true } : {}),
+        timeoutMs: 15 * 60 * 1000,
+    });
+}
+/**
+ * `npm cache add <name>@<version>` — fetch before stopping anything
+ * (SPEC §5 step 8).
+ *
+ * Both the target and the CURRENT version are cached, and caching the current
+ * one is the half that is easy to leave out and expensive to miss: it is what
+ * gives the rollback a package to reinstall when the reason the update failed
+ * was the network. Done while the old version is still serving, so a failure
+ * here costs nothing but a message.
+ *
+ * `npm cache add` is used whatever the manager is, because every one of these
+ * layouts has an npm available (it ships with Node) and the point is only to
+ * have the tarball on the machine. A failure is reported and not fatal — the
+ * install below may still succeed from the network.
+ */
+export function cacheAdd(packageName, version, ctx = {}) {
+    return runNpm(["cache", "add", `${packageName}@${version}`], ctx);
+}
+/**
+ * Ask a CLI what version it is, by running it (`node <cli> --version`).
+ *
+ * This is how `update` proves that the install actually replaced the files
+ * before it hands over to the new CLI. The alternative — reading the
+ * `package.json` next to it — answers a different question: npm writes the
+ * manifest and the files in one operation, but a partially-updated global
+ * folder, a stale symlink, or a pnpm layout whose versioned realpath moved all
+ * show up here and not there.
+ */
+export function cliVersion(cliPath, ctx = {}) {
+    const run = ctx.spawn ?? spawnSyncRunner;
+    const r = run(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("\n")[0]?.trim();
+    return line !== undefined && /^\d+\.\d+\.\d+/.test(line) ? line : undefined;
+}
+/** A throwaway directory, for callers that need one (the writability probe's sibling). */
+export function tmpDir(prefix) {
+    return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}

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

@@ -0,0 +1,89 @@
+/**
+ * The npm registry, as `update` asks it (CLI contract SPEC §5 step 3).
+ *
+ * Two requests, both with `fetch` and a 10-second abort, and nothing else:
+ *
+ *   GET <registry>/-/package/<name>/dist-tags   which version is `latest`
+ *   GET <registry>/<name>/<version>             that version's `engines`
+ *
+ * Deliberately NOT `npm view`: spawning npm to read two small JSON documents
+ * costs a second of process start-up, needs npm to be on PATH at all, and puts
+ * the registry's answer through a program whose output format is not a
+ * contract. `fetch` is in Node 22 and the registry's REST surface has been
+ * stable for a decade.
+ *
+ * **Nothing here is called except by a person.** SPEC §3: only `update`,
+ * `update --check` and `doctor` contact the registry, and only when someone
+ * runs them. There is no background check and no check at startup, which is why
+ * this module is reachable from the CLI and from nowhere in the server.
+ *
+ * Generic: wave C4 lifts it into `reference/registry.ts`.
+ */
+/** SPEC §5: 10 seconds, and it is the budget for each request rather than the pair. */
+export declare const REGISTRY_TIMEOUT_MS = 10000;
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export interface RegistryOptions {
+    packageName: string;
+    /** Base URL, no trailing slash required — {@link registryUrl} normalises it. */
+    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 first is what makes the fake-registry tests possible without touching a
+ * global npm config — an `npm_config_registry` in the environment is how npm
+ * itself takes the same setting, so a test and a real `.npmrc` arrive by the
+ * same door.
+ */
+export declare function resolveRegistry(env: NodeJS.ProcessEnv, npmConfigGet?: (key: string) => string | undefined): string;
+/**
+ * Join a path onto the registry base.
+ *
+ * A scoped name's `/` is written `%2f` (SPEC §5 step 3). That is required by
+ * the dist-tags route and accepted by the manifest route, so both are built the
+ * same way — one rule instead of two, and no chance of only one of them being
+ * right for `@scope/name`.
+ */
+export declare function registryUrl(registry: string, ...parts: string[]): string;
+/** Everything that went wrong talking to the registry, as one reportable error. */
+export declare class RegistryError extends Error {
+    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` (SPEC §5 step 3). */
+export declare function fetchManifest(o: RegistryOptions & {
+    version: string;
+}): Promise<PackageManifest>;
+export interface ResolveTargetInput extends RegistryOptions {
+    /** `--to <version|tag>`, or undefined for `latest`. */
+    to?: string;
+}
+export interface ResolvedTarget {
+    version: string;
+    /** The dist-tag asked for, or null when `--to` named a version (schema field). */
+    tag: string | null;
+    engines: string | null;
+}
+/**
+ * Turn `--to` (or its absence) into one concrete version, plus its `engines`.
+ *
+ * `--to` is a version or a dist-tag and the two are told apart by shape, not by
+ * asking: anything that parses as a version is a version, everything else is a
+ * tag. That ordering matters because a registry will happily serve a manifest
+ * for a tag name as well, and resolving `--to next` as a literal version would
+ * silently install whatever `next` pointed at while REPORTING the target as
+ * "next".
+ */
+export declare function resolveTarget(o: ResolveTargetInput): Promise<ResolvedTarget>;

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

@@ -0,0 +1,145 @@
+/**
+ * The npm registry, as `update` asks it (CLI contract SPEC §5 step 3).
+ *
+ * Two requests, both with `fetch` and a 10-second abort, and nothing else:
+ *
+ *   GET <registry>/-/package/<name>/dist-tags   which version is `latest`
+ *   GET <registry>/<name>/<version>             that version's `engines`
+ *
+ * Deliberately NOT `npm view`: spawning npm to read two small JSON documents
+ * costs a second of process start-up, needs npm to be on PATH at all, and puts
+ * the registry's answer through a program whose output format is not a
+ * contract. `fetch` is in Node 22 and the registry's REST surface has been
+ * stable for a decade.
+ *
+ * **Nothing here is called except by a person.** SPEC §3: only `update`,
+ * `update --check` and `doctor` contact the registry, and only when someone
+ * runs them. There is no background check and no check at startup, which is why
+ * this module is reachable from the CLI and from nowhere in the server.
+ *
+ * Generic: wave C4 lifts it into `reference/registry.ts`.
+ */
+/** SPEC §5: 10 seconds, and it is the budget for each request rather than the pair. */
+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 first is what makes the fake-registry tests possible without touching a
+ * global npm config — an `npm_config_registry` in the environment is how npm
+ * itself takes the same setting, so a test and a real `.npmrc` arrive by the
+ * same door.
+ */
+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");
+    if (fromNpm !== undefined && fromNpm.trim() !== "" && fromNpm.trim() !== "undefined") {
+        return fromNpm.trim();
+    }
+    return DEFAULT_REGISTRY;
+}
+/**
+ * Join a path onto the registry base.
+ *
+ * A scoped name's `/` is written `%2f` (SPEC §5 step 3). That is required by
+ * the dist-tags route and accepted by the manifest route, so both are built the
+ * same way — one rule instead of two, and no chance of only one of them being
+ * right for `@scope/name`.
+ */
+export function registryUrl(registry, ...parts) {
+    const base = registry.replace(/\/+$/, "");
+    return `${base}/${parts.map((p) => p.replace(/\//g, "%2f")).join("/")}`;
+}
+/** Everything that went wrong talking to the registry, as one reportable error. */
+export class RegistryError extends Error {
+    url;
+    constructor(url, message) {
+        super(message);
+        this.url = url;
+    }
+}
+async function getJson(url, o) {
+    const doFetch = o.fetch ?? globalThis.fetch;
+    let res;
+    try {
+        res = await doFetch(url, {
+            signal: AbortSignal.timeout(o.timeoutMs ?? REGISTRY_TIMEOUT_MS),
+            headers: { accept: "application/json" },
+        });
+    }
+    catch (err) {
+        const why = err.name === "TimeoutError" || err.name === "AbortError"
+            ? `no answer within ${(o.timeoutMs ?? REGISTRY_TIMEOUT_MS) / 1000} seconds`
+            : (err.message ?? String(err));
+        throw new RegistryError(url, `could not 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 was not 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 body = await getJson(url, o);
+    const tags = {};
+    for (const [k, v] of Object.entries(body))
+        if (typeof v === "string")
+            tags[k] = v;
+    if (Object.keys(tags).length === 0)
+        throw new RegistryError(url, "the registry listed no dist-tags");
+    return tags;
+}
+/** One version's manifest — read for `engines` (SPEC §5 step 3). */
+export async function fetchManifest(o) {
+    const url = registryUrl(o.registry, o.packageName, o.version);
+    return getJson(url, o);
+}
+/**
+ * Turn `--to` (or its absence) into one concrete version, plus its `engines`.
+ *
+ * `--to` is a version or a dist-tag and the two are told apart by shape, not by
+ * asking: anything that parses as a version is a version, everything else is a
+ * tag. That ordering matters because a registry will happily serve a manifest
+ * for a tag name as well, and resolving `--to next` as a literal version would
+ * silently install whatever `next` pointed at while REPORTING the target as
+ * "next".
+ */
+export async function resolveTarget(o) {
+    const { to } = o;
+    let version;
+    let tag;
+    if (to === undefined) {
+        const tags = await fetchDistTags(o);
+        const latest = tags.latest;
+        if (latest === undefined) {
+            throw new RegistryError(registryUrl(o.registry, "-", "package", o.packageName, "dist-tags"), "the registry has no `latest` dist-tag for this package");
+        }
+        version = latest;
+        tag = "latest";
+    }
+    else if (/^v?\d+\.\d+\.\d+/.test(to.trim())) {
+        version = to.trim().replace(/^v/, "");
+        tag = null;
+    }
+    else {
+        const tags = await fetchDistTags(o);
+        const resolved = tags[to];
+        if (resolved === undefined) {
+            throw new RegistryError(registryUrl(o.registry, "-", "package", o.packageName, "dist-tags"), `no dist-tag \`${to}\` (the registry has: ${Object.keys(tags).sort().join(", ")})`);
+        }
+        version = resolved;
+        tag = to;
+    }
+    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,68 @@
+/**
+ * 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`.
+ */
+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` → a {@link Version}, or undefined if it is not a version. */
+export declare function parseVersion(raw: string): Version | undefined;
+/** Is this a prerelease? SPEC §5: prereleases count only when `--to` names them. */
+export declare function isPrerelease(raw: string): boolean;
+/**
+ * -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 declare function compareVersions(a: string, b: string): number;
+/** Is `a` strictly newer than `b`? */
+export declare const isNewer: (a: string, b: string) => boolean;
+/** The highest of a list, ignoring anything unparseable. Undefined if none parse. */
+export declare function maxVersion(versions: readonly string[]): string | undefined;
+/**
+ * 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 declare function satisfies(version: string, range: string): boolean | undefined;
+export interface EnginesVerdict {
+    /** True pass, false genuine fail, undefined when the range could not be read. */
+    ok: boolean | undefined;
+    /** The range as published, for the message. */
+    range: string | 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 declare function satisfiesEngines(nodeVersion: string, engines: {
+    node?: string;
+} | undefined): EnginesVerdict;