@edspencer/paddock 0.82.0 → 0.83.0

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

@@ -3,16 +3,17 @@ 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`. */
+    /** What holds 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. */
+    /** Removes the file if it's 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. */
+/** Another live process holds the lock. */
 export declare class LockHeldError extends Error {
+    name: string;
     readonly holder: LockBody;
     readonly path: string;
     constructor(file: string, holder: LockBody);
@@ -21,20 +22,14 @@ 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.
+ * Takes the lock, or throws `LockHeldError`. After removing a stale lock it tries once more, and only once: a second
+ * `EEXIST` means another process won the same race just now, which is a real holder.
  */
 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. */
+/** Removes the lock only if it names `pid`, or names nothing: never somebody else's. */
 export declare function releaseLock(file: string, pid: number): void;

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

@@ -1,108 +1,74 @@
-/**
- * `<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";
+// From edspencer/cli-contract reference/lock.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// `<home>/update.lock`: one update at a time (SPEC §5 step 1). Two at once is easy to cause (an Ansible run and a
+// person at a terminal) and bad: the second stops the service the first just started, or installs an older target
+// over a newer one, and the loser's rollback "restores" a version nobody asked for.
+//
+// So the lock is an `O_EXCL` create holding the pid. A live holder refuses with exit 1; a dead one (a crashed or
+// killed update) is stale and is removed, or the install could never update itself again. Node built-ins only.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPidAlive } from '../../runtime-file.js';
+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. */
+/** Another live process holds the lock. */
 export class LockHeldError extends Error {
+    name = 'LockHeldError';
     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.`);
+        super(`another update is already running (pid ${holder.pid}, started ${holder.startedAt}). If that's 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.
+ * Takes the lock, or throws `LockHeldError`. After removing a stale lock it tries once more, and only once: a second
+ * `EEXIST` means another process won the same race just now, which is a real holder.
  */
 export function acquireLock(o) {
     const file = lockPath(o.home);
     const pid = o.pid ?? process.pid;
-    const isAlive = o.isAlive ?? defaultIsAlive;
+    const isAlive = o.isAlive ?? isPidAlive;
     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++) {
+    for (let attempt = 0;; 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 });
+            // 'wx' is O_CREAT | O_EXCL: the create is the lock, in one call.
+            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")
+            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" });
+            // A lock with no readable pid counts as stale: nobody can show a process holds it.
+            if ((holder !== null && holder.pid !== pid && isAlive(holder.pid)) || attempt > 0) {
+                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")
+        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 */
+        // missing, half-written, or not a lock
     }
     return null;
 }
-/** Remove the lock only when it still names `pid`: never delete somebody else's. */
+/** Removes the lock only if it names `pid`, or names nothing: never 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

@@ -1,109 +1,74 @@
-import type { PackageManager } from "./install-method.js";
+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. */
+/** Runs a command to completion; 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;
+/** How long an install may take. */
+export declare const INSTALL_TIMEOUT_MS: number;
 export interface NpmContext {
     spawn?: Spawn;
     env?: NodeJS.ProcessEnv;
     execPath?: string;
     platform?: NodeJS.Platform;
+    /** Injected for tests: does this file exist? */
+    exists?: (p: string) => boolean;
+    realpath?: (p: string) => string;
 }
-/** 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. */
+/**
+ * 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 declare function npmCommand(ctx?: NpmContext): {
+    cmd: string;
+    pre: string[];
+    shell: boolean;
+};
+/** Runs this Node's npm. */
+export declare function runNpm(args: string[], ctx?: NpmContext, timeoutMs?: number): RunResult;
+/** `npm root -g`, or undefined when npm can't answer. */
 export declare function npmGlobalRoot(ctx?: NpmContext): string | undefined;
-/** `npm config get <key>`, or undefined. Used to resolve the registry (SPEC §5 step 3). */
+/** `npm config get <key>`, or undefined. */
 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.
+ * 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 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.
+ * 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 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. */
+/** The global install command, per SPEC §6's last column. */
 export declare function installArgs(manager: PackageManager, spec: string): {
     cmd: string;
     args: string[];
 };
+/** Installs `<name>@<version>` with the manager this install came from. pnpm, bun and volta come from the PATH. */
+export declare function installPackage(o: NpmContext & {
+    manager: PackageManager;
+    packageName: string;
+    version: string;
+}): RunResult;
 /**
- * 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.
+ * `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 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.
+ * 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 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;