@gjsify/cli 0.51.1 → 0.53.0

package/lib/utils/process-table.js

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: MIT
+// What the CLI asks the OS about OTHER processes — is this pid alive, who are
+// its descendants — answered in ONE place, for Node and GJS hosts alike.
+//
+// Both questions used to be answered only by reading `/proc`, in two files
+// (`install-lock.ts`, `commands/foreach.ts`). procfs is a LINUX filesystem, and
+// on macOS neither reader failed — each returned a plausible, wrong answer:
+//
+//   - `foreach`'s fail-fast tree kill found NO descendants, so it signalled only
+//     the direct `npm run` child and left its shell → gjs/node build grandchildren
+//     running (the orphaned-bundler-at-100%-CPU shape the tree kill exists for).
+//   - `install-lock`'s liveness probe fell back to `process.kill(pid, 0)`, whose
+//     GJS implementation returned `true` for every pid, so a crashed install's
+//     lock was never stolen as dead-owner — only after the 35-min budget.
+//
+// So every reader here is chosen by what the host HAS (procfs readable?), never
+// by platform name — a Linux container can lack procfs too. Only the no-procfs
+// fallback's COMMAND depends on the platform, because Windows has no `ps`.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+/**
+ * Is `pid` a live process on this machine?
+ *
+ * `/proc/<pid>` where procfs exists (one stat, no subprocess, identical under
+ * Node and GJS); elsewhere Node's signal-0 probe — `ESRCH` dead, `EPERM`
+ * alive-but-foreign. Any OTHER outcome counts as ALIVE: callers use this to
+ * decide whether something may be taken away from its owner, and "cannot tell"
+ * must never read as "gone".
+ */
+export function isPidAlive(pid) {
+    // `existsSync` never throws by contract: Node returns false on any error, and
+    // the GJS shim is a typeof guard + Gio `query_exists`.
+    if (existsSync('/proc/self'))
+        return existsSync(`/proc/${pid}`);
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+/**
+ * Parse `ps -A -o pid=,ppid=` output (two integer columns, blank headers) into
+ * ppid → children. Exported for the unit test; the format is POSIX, so procps
+ * on Linux and the BSD `ps` on macOS print the same shape.
+ */
+export function parsePsPidPpid(output) {
+    const map = new Map();
+    for (const line of output.split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        if (pid <= 0 || ppid <= 0 || pid === ppid)
+            continue;
+        const siblings = map.get(ppid);
+        if (siblings)
+            siblings.push(pid);
+        else
+            map.set(ppid, [pid]);
+    }
+    return map;
+}
+// Direct children of `pid` from /proc/<pid>/task/*/children (Linux,
+// CONFIG_PROC_CHILDREN — standard on every mainstream kernel). `null` when the
+// files are unreadable, which sends the caller to the full-table fallback.
+function readProcChildren(pid) {
+    let taskIds;
+    try {
+        taskIds = readdirSync(`/proc/${pid}/task`);
+    }
+    catch {
+        // Process already gone (common) or no procfs.
+        return null;
+    }
+    const kids = [];
+    let readAny = false;
+    for (const tid of taskIds) {
+        try {
+            const data = readFileSync(`/proc/${pid}/task/${tid}/children`, 'utf-8');
+            readAny = true;
+            for (const tok of data.trim().split(/\s+/)) {
+                const n = Number(tok);
+                if (Number.isInteger(n) && n > 0)
+                    kids.push(n);
+            }
+        }
+        catch {
+            // Thread vanished mid-walk, or kernel lacks CONFIG_PROC_CHILDREN.
+        }
+    }
+    return readAny ? kids : null;
+}
+// ppid → children from one /proc/*/stat scan. Empty when there is no procfs.
+function procPpidMap() {
+    const map = new Map();
+    let entries = [];
+    try {
+        entries = readdirSync('/proc');
+    }
+    catch {
+        return map;
+    }
+    for (const entry of entries) {
+        const pid = Number(entry);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+            // comm (field 2) may contain spaces/parens — parse after last ')'.
+            const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            const ppid = Number(rest[1]);
+            if (!Number.isInteger(ppid) || ppid <= 0)
+                continue;
+            const siblings = map.get(ppid);
+            if (siblings)
+                siblings.push(pid);
+            else
+                map.set(ppid, [pid]);
+        }
+        catch {
+            // Process exited between readdir and read — fine.
+        }
+    }
+    return map;
+}
+// ppid → children from the OS's process list where there is no procfs:
+// `ps(1)` on macOS/BSD, CIM's Win32_Process on Windows (no `ps` there — Git's
+// MSYS `ps` rejects `-o` and sees only MSYS processes). Both print "pid ppid"
+// lines, so one parser serves. Empty when neither can be run, which degrades to
+// "signal the direct child only".
+function osPpidMap() {
+    const [cmd, args] = process.platform === 'win32'
+        ? [
+            'powershell.exe',
+            [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId)" }',
+            ],
+        ]
+        : ['ps', ['-A', '-o', 'pid=,ppid=']];
+    try {
+        const res = spawnSync(cmd, args, { encoding: 'utf-8' });
+        if (res.status !== 0 || typeof res.stdout !== 'string')
+            return new Map();
+        return parsePsPidPpid(res.stdout);
+    }
+    catch {
+        return new Map();
+    }
+}
+/**
+ * Every transitive descendant of `pid`, breadth-first (reverse the list for
+ * deepest-first signalling). A snapshot — processes spawned after it are not in
+ * it, which is why `foreach` re-walks before escalating to SIGKILL.
+ */
+export function collectDescendants(pid) {
+    const result = [];
+    const seen = new Set([pid]);
+    const queue = [pid];
+    let table = null;
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        let kids = table ? null : readProcChildren(cur);
+        if (kids === null) {
+            // Per-task children files unreadable: one full table for this and
+            // every later level. procfs first, the OS process list where there is none.
+            if (!table) {
+                table = procPpidMap();
+                if (table.size === 0)
+                    table = osPpidMap();
+            }
+            kids = table.get(cur) ?? [];
+        }
+        for (const kid of kids) {
+            if (seen.has(kid))
+                continue;
+            seen.add(kid);
+            result.push(kid);
+            queue.push(kid);
+        }
+    }
+    return result;
+}

package/lib/utils/prune-prefix.js

@@ -25,7 +25,7 @@
 // Reachability ("nothing installed points at this any more") would catch that one
 // and more, but it needs a record of what the prefix was ASSEMBLED FROM, which no
 // prefix carries yet. Uncertain means keep — see ADR 0025 and
-// `status/open-todos.md`.
+// `status/open-todos/README.md`.
 import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { checkPlatform, declaresPlatform, describePlatformTarget, readPlatformOverrides, } from './platform-check.js';

package/lib/utils/publish-pins.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The intra-repo pins a publish is about to ship, enumerated from the manifest
+ * PAIR — the workspace's own `package.json` and the rewritten one that comes
+ * back out of the tarball.
+ *
+ * Why the pair and not just the rewritten manifest: after
+ * `rewriteWorkspaceDeps` (see `commands/pack.ts`) a sibling pin is an ordinary
+ * `^0.51.1` and indistinguishable from a third-party dependency. The `workspace:`
+ * prefix survives only in the SOURCE manifest, so which edges are this repo's
+ * own is a fact that exists in one file and the version they will ship at exists
+ * in the other.
+ */
+/** The blocks `rewriteWorkspaceDeps` rewrites and a consumer install resolves. */
+export type DependencyBlock = 'dependencies' | 'optionalDependencies' | 'peerDependencies';
+/**
+ * The one block whose unresolvable edge fails EVERY consumer install.
+ *
+ * Measured, npm 11.17.0, against the live registry, on an edge to a name that
+ * did not exist: `optionalDependencies` installs clean (exit 0, silently),
+ * `dependencies` is `npm error 404`, exit 1. Yarn refuses both (`YN0035`),
+ * which is why an optional edge is still reported — just not fatal.
+ */
+export declare const REQUIRED_BLOCK: DependencyBlock;
+export interface WorkspacePin {
+    name: string;
+    /** The concrete range the tarball will carry, after the rewrite. */
+    spec: string;
+    block: DependencyBlock;
+}
+/**
+ * Every edge that was a `workspace:` spec before the rewrite, with the version
+ * it will ship at.
+ *
+ * A name appearing in two blocks yields two pins: `dependencies` and
+ * `optionalDependencies` do not cost the same at install time, so collapsing
+ * them would throw away the distinction the caller decides on.
+ */
+export declare function collectWorkspacePins(source: Record<string, unknown>, rewritten: Record<string, unknown>): WorkspacePin[];

package/lib/utils/publish-pins.js

@@ -0,0 +1,47 @@
+/**
+ * The intra-repo pins a publish is about to ship, enumerated from the manifest
+ * PAIR — the workspace's own `package.json` and the rewritten one that comes
+ * back out of the tarball.
+ *
+ * Why the pair and not just the rewritten manifest: after
+ * `rewriteWorkspaceDeps` (see `commands/pack.ts`) a sibling pin is an ordinary
+ * `^0.51.1` and indistinguishable from a third-party dependency. The `workspace:`
+ * prefix survives only in the SOURCE manifest, so which edges are this repo's
+ * own is a fact that exists in one file and the version they will ship at exists
+ * in the other.
+ */
+const BLOCKS = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+/**
+ * The one block whose unresolvable edge fails EVERY consumer install.
+ *
+ * Measured, npm 11.17.0, against the live registry, on an edge to a name that
+ * did not exist: `optionalDependencies` installs clean (exit 0, silently),
+ * `dependencies` is `npm error 404`, exit 1. Yarn refuses both (`YN0035`),
+ * which is why an optional edge is still reported — just not fatal.
+ */
+export const REQUIRED_BLOCK = 'dependencies';
+const depsOf = (pkg, block) => {
+    const value = pkg[block];
+    return value && typeof value === 'object' ? value : {};
+};
+/**
+ * Every edge that was a `workspace:` spec before the rewrite, with the version
+ * it will ship at.
+ *
+ * A name appearing in two blocks yields two pins: `dependencies` and
+ * `optionalDependencies` do not cost the same at install time, so collapsing
+ * them would throw away the distinction the caller decides on.
+ */
+export function collectWorkspacePins(source, rewritten) {
+    const pins = [];
+    for (const block of BLOCKS) {
+        const before = depsOf(source, block);
+        const after = depsOf(rewritten, block);
+        for (const [name, spec] of Object.entries(before)) {
+            if (typeof spec !== 'string' || !spec.startsWith('workspace:'))
+                continue;
+            pins.push({ name, spec: after[name] ?? spec, block });
+        }
+    }
+    return pins;
+}

package/lib/utils/publish-readback.d.ts

@@ -19,9 +19,42 @@ export type ReadbackProbe = {
     status?: number;
     detail: string;
 };
+/**
+ * What the read-back CONCLUDED — the three outcomes a caller may act on, plus
+ * the one it may not.
+ *
+ * `absent` on its own is not a conclusion. The install document not carrying a
+ * version has two causes with opposite remedies — the write never landed
+ * (re-publish) and the write landed but that document does not serve it yet
+ * (wait; a re-publish is answered 409) — and until this type existed both left
+ * through one message asserting the first. Observed live on the ts-for-gir
+ * v5.1.0 release: `@ts-for-gir/reporter` was recorded by the registry at
+ * 21:43:00.983Z and a cache-busted abbreviated read ~40 min later still did not
+ * carry 5.1.0, while the full packument's `time` map did; two minutes after
+ * that, both agreed.
+ */
+export type ReadbackVerdict = 
+/** The install document serves `name@version` and advertises a tarball. */
+'confirmed'
+/** The registry has no record of this version at all — the v0.46.0 shape. */
+ | 'not-published'
+/** The registry RECORDS the write; the document npm installs from does not serve it. */
+ | 'recorded-not-served'
+/**
+ * Nothing was established. A 5xx, a timeout, DNS, an auth wall — or an
+ * install document without the version whose registry record could then
+ * not be read, which leaves BOTH other verdicts unearned. NEVER "published".
+ */
+ | 'unknown';
 export interface ReadbackResult {
     /** True iff a probe saw the exact version with a tarball on it. */
     confirmed: boolean;
+    /** What the read-back concluded. `confirmed === (verdict === 'confirmed')`. */
+    verdict: ReadbackVerdict;
+    /** One line naming the evidence the verdict rests on — it goes in the report. */
+    verdictDetail: string;
+    /** `time[version]` from the registry's own record, when the corroboration read one. */
+    recordedAt?: string;
     /** Probes actually sent (≥ 1). */
     attempts: number;
     elapsedMs: number;
@@ -80,29 +113,42 @@ export declare function backoffFor(round: number): number;
  */
 export declare function probeTimeoutFor(configuredMs: number, remainingMs: number): number;
 /**
- * Default polling budget: 300 s.
+ * Default polling budget: 600 s.
  *
- * The measured maximum lag between a 2xx and the registry recording the version
- * was 251.7 s (@gjsify/child_process, v0.46.0), so a budget below ~4.2 minutes
- * turns npm's normal queueing into a false red — and a false red at release time
- * costs a manual re-run of a workflow that did its job. 300 s clears that
- * maximum and is still short enough that a genuinely lost write is reported by
- * the job that lost it rather than by a later sweep.
+ * The lag between a 2xx and the registry recording the version has been measured
+ * on two releases, and the second broke the first's ceiling. v0.46.0 (199
+ * packages): 19 late writes, maximum 251.7 s (@gjsify/child_process). ts-for-gir
+ * v5.1.0 (12 packages, run 34899018849, PUT lines against `time["5.1.0"]`):
+ * four recorded ~0.7 s BEFORE the 2xx, eight after it — +74, +74, +75, +75,
+ * +96, +248, +248 and +368 s (@ts-for-gir/reporter) — the last past the 300 s
+ * this constant used to be, so "above the measured maximum" had quietly
+ * stopped being true of it. A budget below the lag turns npm's normal queueing into a false
+ * red, and a false red at release time costs a manual re-run of a workflow that
+ * did its job. A budget above it costs nothing on the nine in ten that confirm
+ * on the first probe; all it delays is the report of a genuinely LOST write —
+ * one in 199, measured — by the difference. 600 s is ~1.6x the larger maximum.
  *
- * THAT MAXIMUM IS A SAMPLE MAXIMUM, and the sample does not look truncated by
- * nature. The 19 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
+ * BOTH MAXIMA ARE SAMPLE MAXIMA, and neither sample looks truncated by nature.
+ * The v0.46.0 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
  * 127(4), 157(3), 189(1), 251(3) — and the TOP bucket is as populated as the
  * middle ones, which is the shape of a distribution cut off by the observation
- * rather than one decaying to zero. One release is one sample, so a lag past
- * 300 s is not ruled out; what makes 300 s affordable anyway is that the
- * remediation is verified rather than assumed. The re-run this reports lands on
- * the 409 path, and that path READS BACK too (see the conflict branch in
- * `commands/publish.ts`), so a window that turns out to be too short costs one
- * re-run that confirms — it does not hand back an unverified success.
+ * rather than one decaying to zero; the next release then produced a value past
+ * it. So a lag past 600 s is not ruled out either. What makes any finite window
+ * affordable is that the remediation is verified rather than assumed: the
+ * re-run this reports lands on the 409 path, and that path READS BACK too (see
+ * the conflict branch in `commands/publish.ts`), so a window that turns out too
+ * short costs one re-run that confirms — never an unverified success.
+ *
+ * `time[version]` is when the registry RECORDED the write, a lower bound on
+ * when the document npm installs from SERVES it: the reporter above was
+ * recorded at +368 s and a cache-busted read of its install document still
+ * lacked 5.1.0 ~40 min later. No budget waits that out, and none should — that
+ * state is what the `recorded-not-served` verdict names.
  */
-export declare const DEFAULT_VERIFY_BUDGET_MS = 300000;
+export declare const DEFAULT_VERIFY_BUDGET_MS = 600000;
 /**
- * Poll the registry until `name@version` resolves, or the budget runs out.
+ * Poll the registry until `name@version` resolves, or the budget runs out, then
+ * say WHICH of the three states it found (see {@link ReadbackVerdict}).
  *
  * No side effects, no exits, no printing beyond the injected `log` — the caller
  * owns presentation, same contract as {@link import('./publish-diagnose.js')}.
@@ -130,3 +176,43 @@ export declare function formatUnconfirmedPublish(opts: {
      */
     claim?: 'accepted' | 'already-published';
 }): string;
+/** Whether the registry serves a packument for a NAME at all. */
+export type NamePresence = {
+    state: 'present';
+    status: number;
+    versions: number;
+} | {
+    state: 'absent';
+    status: number;
+    detail: string;
+}
+/**
+ * We do not KNOW — a 5xx, a timeout, an auth wall. A caller that blocks a
+ * publish on this must treat it as "not established", never as "absent":
+ * the whole point of the guard is that it cannot manufacture a red.
+ */
+ | {
+    state: 'unknown';
+    status?: number;
+    detail: string;
+};
+export interface ProbePackageNameInput {
+    registry: string;
+    name: string;
+    probeTimeoutMs?: number;
+    authorization?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Ask ONE question: does this NAME exist on the registry at all.
+ *
+ * Deliberately not a version question, and that is what makes it safe to gate a
+ * publish on. A version is eventually consistent — measured on v0.46.0, 19 of
+ * 199 packages were recorded 56-252 s AFTER their own 2xx — so "is name@version
+ * there" answers "not yet" for minutes and a gate built on it would manufacture
+ * a red on a publish that worked. Presence of the NAME does not move once the
+ * first version lands, which is the same reason
+ * `verify-published-closure.mjs --phase pre-release` asks it rather than the
+ * version: an answer that does not move when the train moves.
+ */
+export declare function probePackageName(input: ProbePackageNameInput): Promise<NamePresence>;