@edspencer/paddock 0.81.0 → 0.82.0

package/packages/server/dist/cli/update/install-method.js

@@ -0,0 +1,258 @@
+/**
+ * How was this copy installed? (CLI contract SPEC §6.)
+ *
+ * `update` cannot sensibly run `npm install -g` on a checkout, inside a
+ * container, or out of npx's cache — so before it touches anything it works out
+ * which of the ten layouts it is living in, and either picks the matching
+ * package manager or prints the one command that WOULD work and exits 5.
+ *
+ * ## Generic on purpose
+ *
+ * Nothing in this file knows about Paddock. The product arrives as data — the
+ * package name, the environment prefix, the entry script — and every call that
+ * touches the world (spawning `npm root -g`, reading a manifest, resolving a
+ * symlink) is injected. That is what lets the §6 table be tested against
+ * fabricated directory layouts for all ten rows on one machine, and it is what
+ * wave C4 lifts into `reference/install-method.ts` unchanged.
+ *
+ * Node built-ins only.
+ */
+import fsDefault from "node:fs";
+import path from "node:path";
+/** `PADDOCK` → `PADDOCK_IN_DOCKER`. */
+export const inDockerVar = (prefix) => `${prefix}_IN_DOCKER`;
+/** `PADDOCK` → `PADDOCK_UPDATE_HINT`. */
+export const updateHintVar = (prefix) => `${prefix}_UPDATE_HINT`;
+/**
+ * Walk up from `entry` looking for the package root.
+ *
+ * Returns the first ancestor whose `package.json` has our name, and the nearest
+ * ancestor with any `package.json` as a fallback — see
+ * {@link InstallInfo.packageRoot}.
+ */
+export function findPackageRoot(entry, packageName, fs) {
+    let dir = path.dirname(realpathOr(entry, fs));
+    let nearest;
+    for (;;) {
+        const manifest = path.join(dir, "package.json");
+        if (fs.existsSync(manifest)) {
+            nearest ??= dir;
+            try {
+                const raw = JSON.parse(fs.readFileSync(manifest, "utf8"));
+                if (raw.name === packageName)
+                    return { root: dir, named: true };
+            }
+            catch {
+                // An unreadable or malformed manifest is not our package. Keep walking:
+                // a broken `package.json` in some intermediate directory must not stop
+                // the search before it reaches the real root.
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return { root: nearest, named: false };
+        dir = parent;
+    }
+}
+function realpathOr(p, fs) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Is `p` inside a `node_modules` directory?
+ *
+ * Split on the separator rather than matched as a substring, so a project
+ * genuinely called `my-node_modules` is not mistaken for one (and so Windows
+ * paths work, since `path.sep` is what split them). SPEC §6's "checkout or npm
+ * link" row is exactly the negation of this.
+ */
+export function underNodeModules(p) {
+    return p.split(/[/\\]/).includes("node_modules");
+}
+/**
+ * The npx / pnpm dlx / bunx / yarn dlx caches (SPEC §6).
+ *
+ * `_npx` and `bunx-` are matched between separators for the reason above.
+ * `dlx` has to be looser — pnpm's is `~/.local/share/pnpm/store/.../dlx/<hash>`
+ * and yarn's is `$TMPDIR/xfs-<hash>/dlx-<n>` — so a path SEGMENT that is `dlx`
+ * or starts `dlx-` counts.
+ */
+export function isEphemeralCachePath(p) {
+    const parts = p.split(/[/\\]/);
+    return parts.some((seg) => seg === "_npx" || seg === "dlx" || seg.startsWith("dlx-") || seg.startsWith("bunx-"));
+}
+/** A path segment-aware "does this path contain this run of segments". */
+function hasSegments(p, segments) {
+    const parts = p.split(/[/\\]/);
+    for (let i = 0; i + segments.length <= parts.length; i++) {
+        if (segments.every((s, j) => parts[i + j] === s))
+            return true;
+    }
+    return false;
+}
+/**
+ * Which of SPEC §6's rows this install is, checked in the table's own order.
+ *
+ * The order is the contract, and two pairs of rows genuinely overlap:
+ *
+ * - **Docker beats managed.** A container that an Ansible role also labelled
+ *   has both variables set, and the honest answer is "this is an image" — but
+ *   the hint is still carried on {@link InstallInfo.hint} and
+ *   {@link updateCommand} prefers it, because a hint is a sentence an operator
+ *   deliberately wrote and our guess at a `docker compose` line is not.
+ * - **Checkout beats every global.** They cannot both be true (every global
+ *   layout is under a `node_modules`), so the order between them never decides
+ *   anything; it is kept as the table has it so the two can be read side by
+ *   side.
+ */
+export function detectInstall(input) {
+    const fs = input.fs ?? fsDefault;
+    const env = input.env;
+    const { root, named } = findPackageRoot(input.entry, input.packageName, fs);
+    const hint = env[updateHintVar(input.envPrefix)];
+    const base = {
+        packageRoot: root,
+        named,
+        ...(hint !== undefined && hint !== "" ? { hint } : {}),
+    };
+    // 1. Docker. The tool's own Dockerfile sets this; `/.dockerenv` is NOT used,
+    //    because dev containers have it too and a global npm install inside one
+    //    is a legitimate thing to update (SPEC §6).
+    if (env[inDockerVar(input.envPrefix)] === "1") {
+        return { ...base, method: "docker", canUpdate: false };
+    }
+    // 2. Managed: something outside owns this install and said so.
+    if (base.hint !== undefined)
+        return { ...base, method: "managed", canUpdate: false };
+    // The rows below are all about WHERE the package sits, so with no package
+    // root there is nothing to say. Treat it as a checkout: it is the row whose
+    // advice ("you are running from source") is least wrong when we cannot tell,
+    // and it refuses to install rather than guessing a package manager.
+    if (root === undefined)
+        return { ...base, method: "checkout", canUpdate: false };
+    // 3. npx and friends: a hash-keyed cache that gets pruned.
+    if (isEphemeralCachePath(root))
+        return { ...base, method: "npx", canUpdate: false };
+    // 4. A checkout or an `npm link`: not under a node_modules at all.
+    if (!underNodeModules(root))
+        return { ...base, method: "checkout", canUpdate: false };
+    // 5. Global npm: the package root IS `<npm root -g>/<name>`.
+    const globalRoot = (input.npmGlobalRoot ?? (() => undefined))();
+    if (globalRoot !== undefined && samePath(root, path.join(globalRoot, input.packageName), fs)) {
+        return { ...base, method: "npm-global", canUpdate: true, manager: "npm" };
+    }
+    // 6–9. The other global layouts, each identified by a marker in its path.
+    if (hasSegments(root, ["pnpm", "global"])) {
+        return { ...base, method: "pnpm-global", canUpdate: true, manager: "pnpm" };
+    }
+    if (hasSegments(root, [".bun", "install", "global"])) {
+        return { ...base, method: "bun-global", canUpdate: true, manager: "bun" };
+    }
+    if (hasSegments(root, [".volta", "tools", "image", "packages"])) {
+        return { ...base, method: "volta", canUpdate: true, manager: "volta" };
+    }
+    // Yarn classic's global folder. `canUpdate: false`: `yarn global add` works,
+    // but classic is unmaintained and berry has no equivalent, so SPEC §6 prints
+    // the command rather than running it.
+    if (hasSegments(root, ["yarn", "global", "node_modules"])) {
+        return { ...base, method: "yarn-global", canUpdate: false };
+    }
+    // 10. Under somebody else's node_modules: a dependency of a project.
+    return { ...base, method: "dependency", canUpdate: false };
+}
+function samePath(a, b, fs) {
+    if (path.resolve(a) === path.resolve(b))
+        return true;
+    // A global root is routinely reached through a symlink (`/usr/local/lib` →
+    // `/opt/homebrew/lib`, nvm's per-version dirs), so compare realpaths too.
+    return realpathOr(a, fs) === realpathOr(b, fs);
+}
+/**
+ * The one command to print (SPEC §3, §6): what the reader should run instead.
+ *
+ * Returns the command and, where it helps, the parenthetical the spec's example
+ * carries (`(the global folder isn't writable)`). An install that CAN update
+ * itself gets `<tool> update`, which is the line the update notice prints.
+ */
+export function updateCommand(info, input) {
+    const spec = input.target !== undefined ? `${input.packageName}@${input.target}` : input.packageName;
+    switch (info.method) {
+        case "docker": {
+            // A hint beats our guess: see detectInstall's note.
+            if (info.hint !== undefined)
+                return { command: info.hint };
+            const tag = input.target !== undefined ? `:${input.target}` : "";
+            return {
+                command: "docker compose pull && docker compose up -d",
+                ...(input.image !== undefined ? { note: `image ${input.image}${tag}` } : {}),
+            };
+        }
+        case "managed":
+            return { command: info.hint ?? "ask whoever manages this install" };
+        case "npx":
+            return {
+                command: `npx ${input.packageName}@latest`,
+                note: "npx already runs the latest version each time",
+            };
+        case "checkout":
+            return {
+                command: input.checkoutCommand ?? "git pull && npm install && npm run build",
+                note: "this is a checkout",
+            };
+        case "npm-global":
+            return {
+                command: `${input.sudo === true ? "sudo " : ""}npm install -g ${spec}`,
+                ...(input.sudo === true ? { note: "the global folder isn't writable" } : {}),
+            };
+        case "pnpm-global":
+            return { command: `pnpm add -g ${spec}` };
+        case "bun-global":
+            return { command: `bun add -g ${spec}` };
+        case "volta":
+            return { command: `volta install ${spec}` };
+        case "yarn-global":
+            return { command: `yarn global add ${spec}` };
+        case "dependency":
+            return {
+                command: `npm install ${spec}`,
+                note: `run it in the project that depends on ${input.packageName}${info.packageRoot !== undefined ? ` (${projectOf(info.packageRoot)})` : ""}`,
+            };
+    }
+}
+/** The project a dependency install belongs to: the directory above its `node_modules`. */
+function projectOf(packageRoot) {
+    const parts = packageRoot.split(path.sep);
+    const i = parts.lastIndexOf("node_modules");
+    return i <= 0 ? packageRoot : parts.slice(0, i).join(path.sep);
+}
+/** One line a person can act on, for every row of the table. */
+export function describeInstall(info, packageName) {
+    switch (info.method) {
+        case "docker":
+            return "running from a container image";
+        case "managed":
+            return "managed by something outside this machine's package manager";
+        case "npx":
+            return "running from an npx / dlx cache";
+        case "checkout":
+            return info.packageRoot !== undefined
+                ? `running from a checkout at ${info.packageRoot}`
+                : "running from a checkout";
+        case "npm-global":
+            return "installed globally with npm";
+        case "pnpm-global":
+            return "installed globally with pnpm";
+        case "bun-global":
+            return "installed globally with bun";
+        case "volta":
+            return "installed with volta";
+        case "yarn-global":
+            return "installed globally with yarn (classic)";
+        case "dependency":
+            return `installed as a dependency of another project (${packageName})`;
+    }
+}

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

@@ -0,0 +1,40 @@
+export declare const LOCK_FILE = "update.lock";
+export declare function lockPath(home: string): string;
+export interface LockBody {
+    pid: number;
+    startedAt: string;
+    /** What is holding it, for the message: `paddock update --to 0.81.0`. */
+    command?: string;
+}
+export interface Lock {
+    path: string;
+    /** Remove the file, but only if it is still ours. Safe to call twice. */
+    release(): void;
+}
+/** The lock is held by a live process. Carries its pid so the caller can say so. */
+export declare class LockHeldError extends Error {
+    readonly holder: LockBody;
+    readonly path: string;
+    constructor(file: string, holder: LockBody);
+}
+export interface AcquireOptions {
+    home: string;
+    pid?: number;
+    command?: string;
+    /** Injected so a stale lock can be tested without spawning a process to kill. */
+    isAlive?: (pid: number) => boolean;
+    now?: () => Date;
+}
+/**
+ * Take the lock, or throw {@link LockHeldError}.
+ *
+ * The retry is deliberately ONCE. After removing a stale lock the create is
+ * attempted again, and a second `EEXIST` means another process won the same
+ * race in that microsecond — which is a genuine holder, not a stale file, so it
+ * refuses. Looping instead would be a way to spin forever against a lock being
+ * recreated as fast as it is deleted.
+ */
+export declare function acquireLock(o: AcquireOptions): Lock;
+export declare function readLock(file: string): LockBody | null;
+/** Remove the lock only when it still names `pid`: never delete somebody else's. */
+export declare function releaseLock(file: string, pid: number): void;

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

@@ -0,0 +1,108 @@
+/**
+ * `<home>/update.lock` — one update at a time (CLI contract SPEC §5 step 1).
+ *
+ * Two concurrent updates is not a theoretical race. The second one stops the
+ * service the first just started, or installs an older target over a newer one,
+ * and the loser's rollback then "restores" a version nobody asked for. It is
+ * also easy to cause: an Ansible run and a person at a terminal, or a scheduler
+ * firing twice.
+ *
+ * So: `O_EXCL` create, holding the pid. A lock whose pid is alive refuses with
+ * exit 1. A lock whose pid is gone — a crashed or killed update — is stale and
+ * is removed, because the alternative is an install that can never update
+ * itself again without someone finding out about a file they have never heard
+ * of.
+ *
+ * Generic: wave C4 lifts this into `reference/lock.ts`. Node built-ins only.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const LOCK_FILE = "update.lock";
+export function lockPath(home) {
+    return path.join(home, LOCK_FILE);
+}
+/** The lock is held by a live process. Carries its pid so the caller can say so. */
+export class LockHeldError extends Error {
+    holder;
+    path;
+    constructor(file, holder) {
+        super(`another update is already running (pid ${holder.pid}, started ${holder.startedAt})\n` +
+            `         If that is wrong, remove ${file} and try again.`);
+        this.holder = holder;
+        this.path = file;
+    }
+}
+/**
+ * Take the lock, or throw {@link LockHeldError}.
+ *
+ * The retry is deliberately ONCE. After removing a stale lock the create is
+ * attempted again, and a second `EEXIST` means another process won the same
+ * race in that microsecond — which is a genuine holder, not a stale file, so it
+ * refuses. Looping instead would be a way to spin forever against a lock being
+ * recreated as fast as it is deleted.
+ */
+export function acquireLock(o) {
+    const file = lockPath(o.home);
+    const pid = o.pid ?? process.pid;
+    const isAlive = o.isAlive ?? defaultIsAlive;
+    const body = {
+        pid,
+        startedAt: (o.now ?? (() => new Date()))().toISOString(),
+        ...(o.command !== undefined ? { command: o.command } : {}),
+    };
+    fs.mkdirSync(o.home, { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            // 'wx' is O_CREAT|O_EXCL|O_WRONLY: the create is the lock, in one
+            // syscall, so there is no window between "is it there?" and "make it".
+            fs.writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+            return { path: file, release: () => releaseLock(file, pid) };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const holder = readLock(file);
+            // An unreadable or pid-less lock file counts as stale: it is either
+            // half-written or from a version that wrote something else, and either
+            // way nobody can prove a process is holding it.
+            if (holder !== null && isAlive(holder.pid) && holder.pid !== pid) {
+                throw new LockHeldError(file, holder);
+            }
+            if (attempt === 1) {
+                throw new LockHeldError(file, holder ?? { pid: 0, startedAt: "unknown" });
+            }
+            fs.rmSync(file, { force: true });
+        }
+    }
+    // Unreachable: both branches of the loop above either return or throw.
+    throw new LockHeldError(file, { pid: 0, startedAt: "unknown" });
+}
+export function readLock(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (Number.isInteger(raw.pid) && typeof raw.startedAt === "string")
+            return raw;
+    }
+    catch {
+        /* missing, half-written, or not ours */
+    }
+    return null;
+}
+/** Remove the lock only when it still names `pid`: never delete somebody else's. */
+export function releaseLock(file, pid) {
+    const holder = readLock(file);
+    if (holder === null || holder.pid === pid)
+        fs.rmSync(file, { force: true });
+}
+function defaultIsAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists and is not ours, which still counts.
+        return err.code === "EPERM";
+    }
+}

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

@@ -0,0 +1,109 @@
+import type { PackageManager } from "./install-method.js";
+export interface RunResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Run a command; never throws for a non-zero exit. Injected everywhere, for tests. */
+export type Spawn = (cmd: string, args: string[], opts?: {
+    env?: NodeJS.ProcessEnv;
+    shell?: boolean;
+    timeoutMs?: number;
+}) => RunResult;
+export declare const spawnSyncRunner: Spawn;
+/**
+ * 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 declare function npmBeside(execPath?: string, platform?: NodeJS.Platform): string;
+export interface NpmContext {
+    spawn?: Spawn;
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    platform?: NodeJS.Platform;
+}
+/** Run npm with no shell (except on Windows, where `npm.cmd` needs one). */
+export declare function runNpm(args: string[], ctx?: NpmContext): RunResult;
+/** `npm root -g`, or undefined when npm could not answer. */
+export declare function npmGlobalRoot(ctx?: NpmContext): string | undefined;
+/** `npm config get <key>`, or undefined. Used to resolve the registry (SPEC §5 step 3). */
+export declare function npmConfigGet(key: string, ctx?: NpmContext): string | 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 declare function isWritable(dir: string): boolean;
+/**
+ * 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 declare function globalRootFor(manager: PackageManager, ctx?: NpmContext): string | undefined;
+export interface InstallInput {
+    manager: PackageManager;
+    packageName: string;
+    version: string;
+    spawn?: Spawn;
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    platform?: NodeJS.Platform;
+}
+/** The argv for a global install, per SPEC §6's last column. */
+export declare function installArgs(manager: PackageManager, spec: string): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * 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 declare function installPackage(o: InstallInput): RunResult;
+/**
+ * `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 declare function cacheAdd(packageName: string, version: string, ctx?: NpmContext): RunResult;
+/**
+ * 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 declare function cliVersion(cliPath: string, ctx?: NpmContext): string | undefined;
+/** A throwaway directory, for callers that need one (the writability probe's sibling). */
+export declare function tmpDir(prefix: string): string;