vouchington-tooling 0.0.4 → 0.0.6

package/README.md

@@ -17,6 +17,13 @@ vouchington runner-port-policy --file ./policy.json
 vouchington runner-port-policy --reserved 2200
 vouchington with-host-lock --name expensive-build --timeout-seconds 60 -- make build
 vouchington gha-runtime-audit --pr-workflow CI --push-workflow '/^Main CI \\(.+\\)$/'
+vouchington gha-output name
+vouchington gha-needs-results
+vouchington download-with-diagnostics <url> <destination>
+vouchington host-pressure-diagnostics
+vouchington allocate-browser-safe-ports 2 --policy ./policy.json --forbidden-ports ./ports.json
+vouchington vitest-blob-manifest <suite> [reports-directory]
+vouchington pnpm-install --runner-lifecycle persistent --install-scripts true
 ```
 
 Host-lock environment:
@@ -39,4 +46,7 @@ import {
 import { initSqlAst, extractCreateTableMetadata } from 'vouchington-tooling/sql-ast'
 import { splitSqlStatements, stripSqlComments } from 'vouchington-tooling/sql-scanner'
 import { auditCiJobRuntime } from 'vouchington-tooling/gha-runtime-audit'
+import { writeVitestBlobManifest } from 'vouchington-tooling/vitest-blob-manifest'
+import { runInstallLifecycle } from 'vouchington-tooling/pnpm-install'
+import { buildSharedContext, runNamedChecks } from 'vouchington-tooling/shared-context'
 ```

package/dist/cli/commands/allocate-browser-safe-ports.slot-fixtures.test-helpers.d.mts

@@ -0,0 +1,6 @@
+export declare const synthesizedRunnerSlot: number;
+export declare const synthesizedPortRangeStart: number;
+export declare const synthesizedPortRangeEnd: number;
+export declare function requiredPort(port: number | undefined): number;
+export declare const synthesizedSlotHostLockTestTimeoutMs: number;
+export declare function withSynthesizedSlotHostLock<T>(body: () => Promise<T>): Promise<T>;

package/dist/cli/commands/allocate-browser-safe-ports.slot-fixtures.test-helpers.mjs

@@ -0,0 +1,103 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { runnerPortPolicy } from '../../runner-port-policy/index.mjs';
+const hostLockScriptPath = resolve('packages/vouchington-tooling/scripts/host-lock/with-host-lock.sh');
+// Slot `maximumRunnerSlot` is the fleet's established synthetic ceiling for boundary tests (see
+// allocate-browser-safe-ports.test.mts's "uses the slot-50 boundary" case) — no host runs that
+// many runner slots, so this range never collides with a real runner's live port allocation.
+export const synthesizedRunnerSlot = runnerPortPolicy.maximumRunnerSlot;
+export const synthesizedPortRangeStart = runnerPortPolicy.reservedPortStart +
+    (synthesizedRunnerSlot - runnerPortPolicy.minimumRunnerSlot) * runnerPortPolicy.portsPerRunner;
+export const synthesizedPortRangeEnd = synthesizedPortRangeStart + runnerPortPolicy.portsPerRunner - 1;
+export function requiredPort(port) {
+    if (port === undefined)
+        throw new Error('expected an allocated port');
+    return port;
+}
+const hostLockName = 'allocate-browser-safe-ports-synthesized-slot';
+const hostLockTimeoutSeconds = 60;
+const hostLockCommandTimeoutSeconds = 60;
+// Grace this wrapper waits past with-host-lock.sh's own --timeout-seconds before giving up on the
+// acquired marker (mirrors the script's internal polling/teardown overhead around acquisition).
+const hostLockAcquireGraceSeconds = 15;
+// Fixed overhead for this wrapper's own teardown once body() returns: writing the release marker,
+// waiting for the placeholder to exit, and removing the marker dir.
+const hostLockWrapperTeardownMarginSeconds = 15;
+// Single source of truth for how long a vitest `it()` calling withSynthesizedSlotHostLock must be
+// allowed to run: the full lock-acquisition window, then a critical section that may legitimately
+// run right up to with-host-lock's own --command-timeout-seconds watchdog, plus fixed wrapper
+// teardown. Deriving this -- instead of a second, independent literal on the `it()` call -- is what
+// guarantees with-host-lock's watchdog can never force-release the lock while the calling test
+// still believes it's within its own timeout budget: with-host-lock.sh's
+// start_command_timeout_watchdog force-kills the placeholder and unconditionally releases the lock
+// once command_timeout_seconds elapses, regardless of whether body() has finished, so the vitest
+// timeout must always exceed that watchdog's own worst case, never fall short of it.
+export const synthesizedSlotHostLockTestTimeoutMs = (hostLockTimeoutSeconds +
+    hostLockAcquireGraceSeconds +
+    hostLockCommandTimeoutSeconds +
+    hostLockWrapperTeardownMarginSeconds) *
+    1000;
+async function waitForMarker(path, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (!existsSync(path)) {
+        if (Date.now() >= deadline)
+            throw new Error(`timed out waiting for marker: ${path}`);
+        await new Promise((resolveWait) => setTimeout(resolveWait, 50));
+    }
+}
+// ci/with-host-lock.sh only wraps a subprocess command, but the racy resource here (binding real
+// host ports) is in-process Node.js code. The wrapped command is therefore a placeholder that
+// writes an "acquired" marker the instant it starts running — which is exactly when the lock is
+// held, per with-host-lock.sh's start-release handshake — and blocks on a "release" marker until
+// told to stop. That gates the Node-side critical section on lock acquisition/release instead of
+// trying to run that section as the locked subprocess itself, so two concurrent copies of a test
+// using the synthesized slot take turns instead of colliding on the same synthetic port range.
+export async function withSynthesizedSlotHostLock(body) {
+    const markerDir = await mkdtemp(join(tmpdir(), 'host-lock-marker-'));
+    const acquiredMarker = join(markerDir, 'acquired');
+    const releaseMarker = join(markerDir, 'release');
+    const stderrChunks = [];
+    const holder = spawn('bash', [
+        hostLockScriptPath,
+        '--name',
+        hostLockName,
+        '--timeout-seconds',
+        String(hostLockTimeoutSeconds),
+        '--command-timeout-seconds',
+        String(hostLockCommandTimeoutSeconds),
+        '--',
+        'bash',
+        '-c',
+        'touch "$1"; while [ ! -e "$2" ]; do sleep 0.05; done',
+        '_',
+        acquiredMarker,
+        releaseMarker,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    holder.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
+    const exited = new Promise((resolveExit) => {
+        holder.once('close', (code) => resolveExit(code));
+    });
+    const acquireTimeoutMs = (hostLockTimeoutSeconds + hostLockAcquireGraceSeconds) * 1000;
+    const acquired = await Promise.race([
+        waitForMarker(acquiredMarker, acquireTimeoutMs).then(() => true),
+        exited.then(() => false),
+    ]);
+    if (!acquired) {
+        const code = await exited;
+        throw new Error(`with-host-lock exited before acquiring "${hostLockName}" (code ${code}): ${Buffer.concat(stderrChunks).toString('utf8')}`);
+    }
+    try {
+        return await body();
+    }
+    finally {
+        await releasePlaceholderAndAwaitExit(releaseMarker, exited);
+        await rm(markerDir, { force: true, recursive: true });
+    }
+}
+async function releasePlaceholderAndAwaitExit(releaseMarker, exited) {
+    await writeFile(releaseMarker, '');
+    await exited;
+}

package/dist/cli/commands/github-output.test-helpers.d.mts

@@ -0,0 +1 @@
+export declare function parseGithubOutput(text: string): Record<string, string>;

package/dist/cli/commands/github-output.test-helpers.mjs

@@ -0,0 +1,32 @@
+export function parseGithubOutput(text) {
+    const outputs = {};
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (!line)
+            continue;
+        const heredocSeparator = line.indexOf('<<');
+        if (heredocSeparator !== -1) {
+            const name = line.slice(0, heredocSeparator);
+            const delimiter = line.slice(heredocSeparator + 2);
+            const valueLines = [];
+            index += 1;
+            while (index < lines.length) {
+                const next = lines[index];
+                if (next === undefined || next === delimiter)
+                    break;
+                valueLines.push(next);
+                index += 1;
+            }
+            if (index === lines.length)
+                throw new Error(`Missing output delimiter: ${delimiter}`);
+            outputs[name] = valueLines.join('\n');
+            continue;
+        }
+        const assignmentSeparator = line.indexOf('=');
+        if (assignmentSeparator === -1)
+            throw new Error(`Invalid output record: ${line}`);
+        outputs[line.slice(0, assignmentSeparator)] = line.slice(assignmentSeparator + 1);
+    }
+    return outputs;
+}

package/dist/cli/commands/pnpm-install.d.mts

@@ -0,0 +1 @@
+export declare function runPnpmInstallCli(args: readonly string[]): Promise<number>;

package/dist/cli/commands/pnpm-install.mjs

@@ -0,0 +1,27 @@
+import { appendFile } from 'node:fs/promises';
+import { parseInstallOptions, runInstallLifecycle } from '../../pnpm-install/index.mjs';
+export async function runPnpmInstallCli(args) {
+    const started = performance.now();
+    let mode = 'unknown';
+    let outcome = 'failed';
+    try {
+        mode = await runInstallLifecycle(parseInstallOptions([...args]));
+        outcome = 'completed';
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        const summary = process.env.GITHUB_STEP_SUMMARY;
+        if (summary) {
+            try {
+                await appendFile(summary, `pnpm install: ${mode} ${outcome} in ${Math.round(performance.now() - started)}ms\n`);
+            }
+            catch (error) {
+                console.warn(`unable to append pnpm install summary: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}

package/dist/cli/commands/spawn-script.d.mts

@@ -0,0 +1,5 @@
+import { type SpawnSyncReturns } from 'node:child_process';
+export type ScriptSpawn = (command: string, args: readonly string[], options: {
+    stdio: 'inherit';
+}) => Pick<SpawnSyncReturns<Buffer>, 'error' | 'status'>;
+export declare function runScript(command: string, scriptPath: string, args: readonly string[], spawn?: ScriptSpawn): number;

package/dist/cli/commands/spawn-script.mjs

@@ -0,0 +1,7 @@
+import { spawnSync } from 'node:child_process';
+export function runScript(command, scriptPath, args, spawn = spawnSync) {
+    const result = spawn(command, [scriptPath, ...args], { stdio: 'inherit' });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}

package/dist/cli/commands/vitest-blob-manifest.d.mts

@@ -0,0 +1 @@
+export declare function runVitestBlobManifestCommand(args: readonly string[]): number;

package/dist/cli/commands/vitest-blob-manifest.mjs

@@ -0,0 +1,11 @@
+import { runVitestBlobManifestCli } from '../../vitest-blob-manifest/cli.mjs';
+export function runVitestBlobManifestCommand(args) {
+    try {
+        runVitestBlobManifestCli(args);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -4,10 +4,30 @@ import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { readPackageVersion } from '../package-version.mjs';
 import { runGhaRuntimeAudit } from './commands/gha-runtime-audit.mjs';
+import { runPnpmInstallCli } from './commands/pnpm-install.mjs';
 import { runRunnerPortPolicy } from './commands/runner-port-policy.mjs';
+import { runScript } from './commands/spawn-script.mjs';
+import { runVitestBlobManifestCommand } from './commands/vitest-blob-manifest.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { parseCli } from './parse.mjs';
+import { packageScriptPath } from './script-path.mjs';
 import { printUsage } from './usage.mjs';
+const SCRIPT_PATHS = {
+    'gha-output': { command: 'bash', path: 'scripts/gha/write-github-multiline-output.sh' },
+    'gha-needs-results': { command: 'bash', path: 'scripts/gha/check-needs-results.sh' },
+    'download-with-diagnostics': {
+        command: 'bash',
+        path: 'scripts/gha/download-with-diagnostics.sh',
+    },
+    'host-pressure-diagnostics': {
+        command: 'bash',
+        path: 'scripts/gha/host-pressure-diagnostics.sh',
+    },
+    'allocate-browser-safe-ports': {
+        command: 'python3',
+        path: 'scripts/allocate-browser-safe-ports.py',
+    },
+};
 export function runCli(argv = process.argv) {
     const parsed = parseCli(argv);
     switch (parsed.kind) {
@@ -27,6 +47,14 @@ export function runCli(argv = process.argv) {
             return runWithHostLock(parsed.args);
         case 'gha-runtime-audit':
             return runGhaRuntimeAudit(parsed);
+        case 'script': {
+            const spec = SCRIPT_PATHS[parsed.command];
+            return runScript(spec.command, packageScriptPath(spec.path), parsed.args);
+        }
+        case 'pnpm-install':
+            return runPnpmInstallCli(parsed.args);
+        case 'vitest-blob-manifest':
+            return runVitestBlobManifestCommand(parsed.args);
     }
 }
 function readInstalledVersion() {

package/dist/cli/parse.d.mts

@@ -13,5 +13,16 @@ export type ParsedCli = {
 } | {
     kind: 'with-host-lock';
     args: string[];
+} | {
+    kind: 'script';
+    command: ScriptCommand;
+    args: string[];
+} | {
+    kind: 'pnpm-install';
+    args: string[];
+} | {
+    kind: 'vitest-blob-manifest';
+    args: string[];
 } | ParsedGhaRuntimeAudit;
+export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -1,4 +1,11 @@
 import { parseGhaRuntimeAudit } from './parse-gha-runtime-audit.mjs';
+const SCRIPT_COMMANDS = new Set([
+    'gha-output',
+    'gha-needs-results',
+    'download-with-diagnostics',
+    'host-pressure-diagnostics',
+    'allocate-browser-safe-ports',
+]);
 export function parseCli(argv) {
     const args = argv.slice(2);
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h')
@@ -12,6 +19,13 @@ export function parseCli(argv) {
         return { kind: 'with-host-lock', args: rest };
     if (command === 'gha-runtime-audit')
         return parseGhaRuntimeAudit(rest);
+    if (command === 'pnpm-install')
+        return { kind: 'pnpm-install', args: rest };
+    if (command === 'vitest-blob-manifest')
+        return { kind: 'vitest-blob-manifest', args: rest };
+    if (command !== undefined && SCRIPT_COMMANDS.has(command)) {
+        return { kind: 'script', command: command, args: rest };
+    }
     return { kind: 'error', message: `unknown command: ${command}` };
 }
 function parseRunnerPortPolicy(args) {

package/dist/cli/script-path.d.mts

@@ -0,0 +1 @@
+export declare function packageScriptPath(relativeFromPackageRoot: string): string;

package/dist/cli/script-path.mjs

@@ -0,0 +1,4 @@
+import { fileURLToPath } from 'node:url';
+export function packageScriptPath(relativeFromPackageRoot) {
+    return fileURLToPath(new URL(`../../${relativeFromPackageRoot}`, import.meta.url));
+}

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit    Audit successful GitHub Actions job runtimes\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -3,7 +3,14 @@ export const USAGE = `Usage: vouchington <command> [options]
 Commands:
   runner-port-policy   Print or validate a runner port policy
   with-host-lock       Run a command under a host-wide lock
-  gha-runtime-audit    Audit successful GitHub Actions job runtimes
+  gha-runtime-audit             Audit successful GitHub Actions job runtimes
+  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record
+  gha-needs-results             Fail if required GitHub Actions job results failed
+  download-with-diagnostics     Download a URL and report HTTP status on failure
+  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot
+  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports
+  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file
+  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast
 
 Options:
   -h, --help       Show this help
@@ -28,6 +35,14 @@ gha-runtime-audit
   [--branch main]
   --pr-workflow <name|/regex/>     Repeatable
   --push-workflow <name|/regex/>   Repeatable
+
+gha-output <name>
+gha-needs-results [label]
+download-with-diagnostics <url> <destination> [-- curl-args...]
+host-pressure-diagnostics
+allocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]
+vitest-blob-manifest <suite> [reports-directory]
+pnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/index.d.mts

@@ -5,3 +5,9 @@ export type { ForeignKey, SqlCreateIndexMetadata, SqlCreateTableColumn, SqlCreat
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mts';
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mts';
 export type { GhApiExecutor, RuntimeAuditOptions, RuntimeAuditResult, RuntimeAuditWorkflowFilter, RuntimeJobResult, RuntimeSample, } from './gha-runtime-audit/index.mts';
+export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManifest, serializeVitestBlobManifest, VITEST_BLOB_MANIFEST_FILENAME, VITEST_BLOB_MANIFEST_VERSION, vitestBlobBundlePaths, writeVitestBlobManifest, } from './vitest-blob-manifest/index.mts';
+export type { InspectedVitestBlobBundle, VitestBlobIdentity, VitestBlobManifest, } from './vitest-blob-manifest/index.mts';
+export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mts';
+export type { InstallOptions, Lifecycle } from './pnpm-install/index.mts';
+export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mts';
+export type { NamedCheck, SharedContext } from './shared-context/index.mts';

package/dist/index.mjs

@@ -2,3 +2,6 @@ export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOn
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mjs';
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mjs';
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mjs';
+export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManifest, serializeVitestBlobManifest, VITEST_BLOB_MANIFEST_FILENAME, VITEST_BLOB_MANIFEST_VERSION, vitestBlobBundlePaths, writeVitestBlobManifest, } from './vitest-blob-manifest/index.mjs';
+export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mjs';
+export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mjs';

package/dist/pnpm-install/exec.d.mts

@@ -0,0 +1,8 @@
+import type { CommandResult, InstallOptions } from './support.mts';
+/**
+ * Spawn one `pnpm` attempt. Both stdout and stderr are always captured (so a terminal failure
+ * like a release-age violation can be classified from `errorOutput`) and, unless `capture` is
+ * set, forwarded live to the parent process's streams — `capture` is for structured calls (e.g.
+ * `pnpm m ls --json`) whose stdout the caller parses rather than displays.
+ */
+export declare function runPnpm(args: string[], options: InstallOptions, capture?: boolean): Promise<CommandResult>;

package/dist/pnpm-install/exec.mjs

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process';
+// oxfmt-ignore
+import { INSTALL_TERMINATION_FAILED, installExitCode, startInstallHeartbeat, terminateSafeProcessGroup } from './process.mjs';
+/**
+ * Spawn one `pnpm` attempt. Both stdout and stderr are always captured (so a terminal failure
+ * like a release-age violation can be classified from `errorOutput`) and, unless `capture` is
+ * set, forwarded live to the parent process's streams — `capture` is for structured calls (e.g.
+ * `pnpm m ls --json`) whose stdout the caller parses rather than displays.
+ */
+export function runPnpm(args, options, capture = false) {
+    return new Promise((resolve) => {
+        const errorOutput = [];
+        const output = [];
+        // oxfmt-ignore
+        const result = (code) => ({ code, errorOutput: Buffer.concat(errorOutput).toString(), output: Buffer.concat(output).toString() });
+        let completed = false;
+        const complete = (result) => {
+            if (completed)
+                return;
+            completed = true;
+            resolve(result);
+        };
+        let child;
+        try {
+            child = spawn('pnpm', args, {
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`pnpm failed to spawn: ${message}`);
+            complete({ code: 1, errorOutput: message, output: '' });
+            return;
+        }
+        child.stdout?.on('data', (data) => {
+            output.push(data);
+            if (!capture)
+                process.stdout.write(data);
+        });
+        child.stderr?.on('data', (data) => {
+            errorOutput.push(data);
+            if (!capture)
+                process.stderr.write(data);
+        });
+        child.once('error', (error) => {
+            console.error(`pnpm failed to start: ${error.message}`);
+            complete({ code: 1, errorOutput: error.message, output: '' });
+        });
+        const heartbeat = startInstallHeartbeat();
+        let termination;
+        // Benign race: if the timeout callback and the 'close' handler both fire, `complete`'s dedup
+        // guard lets only the first resolve. `timedOut` is only read by the winner, so whichever wins
+        // sees the correct value for its own case (true when the timeout won, false when close won).
+        let timedOut = false;
+        const terminate = () => (termination ??= terminateSafeProcessGroup(child.pid));
+        const timeout = options.commandTimeoutSeconds === 0
+            ? undefined
+            : setTimeout(() => {
+                /* v8 ignore next -- close can win the race and already settle */
+                if (completed)
+                    return;
+                timedOut = true;
+                void terminate()
+                    .then((stopped) => complete(result(stopped ? 1 : INSTALL_TERMINATION_FAILED)))
+                    .catch((error) => {
+                    console.error(`pnpm install termination failed: ${String(error)}`);
+                    complete(result(INSTALL_TERMINATION_FAILED));
+                })
+                    .finally(() => {
+                    clearInterval(heartbeat);
+                });
+            }, options.commandTimeoutSeconds * 1000);
+        timeout?.unref();
+        child.once('close', async (code) => {
+            try {
+                await termination;
+                complete(result(installExitCode(code, timedOut)));
+            }
+            finally {
+                clearInterval(heartbeat);
+                // oxlint-disable-next-line promise/no-multiple-resolved -- oxlint reports the multi-path settlement at this finally line; the sole `resolve` call site is first-winner-guarded by `completed` inside `complete`
+                if (timeout)
+                    clearTimeout(timeout);
+            }
+        });
+    });
+}

package/dist/pnpm-install/index.d.mts

@@ -0,0 +1,7 @@
+export { runInstallLifecycle } from './runner.mts';
+export { runPnpm } from './exec.mts';
+export { baseInstallArgs, findWorkspaceLinkMismatches, listWorkspaces, logWorkspaceLinkMismatches, parseInstallOptions, reportGlibcVersionRuntime, } from './support.mts';
+export type { CaptureCommand, CommandResult, InstallOptions, Lifecycle, Workspace, WorkspaceLinkMismatch, } from './support.mts';
+export { formatReleaseAgeFailure, isReleaseAgeViolation, parseReleaseAgeViolations, } from './release-age.mts';
+export { INSTALL_TERMINATION_FAILED, installExitCode, safeProcessGroup, startInstallHeartbeat, terminateProcessGroup, terminateSafeProcessGroup, } from './process.mts';
+export { persistentDependencyTreeIsCold, persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata.mts';

package/dist/pnpm-install/index.mjs

@@ -0,0 +1,6 @@
+export { runInstallLifecycle } from './runner.mjs';
+export { runPnpm } from './exec.mjs';
+export { baseInstallArgs, findWorkspaceLinkMismatches, listWorkspaces, logWorkspaceLinkMismatches, parseInstallOptions, reportGlibcVersionRuntime, } from './support.mjs';
+export { formatReleaseAgeFailure, isReleaseAgeViolation, parseReleaseAgeViolations, } from './release-age.mjs';
+export { INSTALL_TERMINATION_FAILED, installExitCode, safeProcessGroup, startInstallHeartbeat, terminateProcessGroup, terminateSafeProcessGroup, } from './process.mjs';
+export { persistentDependencyTreeIsCold, persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata.mjs';

package/dist/pnpm-install/metadata.d.mts

@@ -0,0 +1,5 @@
+import { type CaptureCommand } from './support.mts';
+export declare function persistentMetadataFingerprint(runCapture: CaptureCommand, installScripts: boolean): Promise<string>;
+export declare function persistentMetadataMatches(fingerprint: string): Promise<boolean>;
+export declare function persistentDependencyTreeIsCold(): Promise<boolean>;
+export declare function writePersistentMetadataStamp(fingerprint: string): Promise<void>;

package/dist/pnpm-install/metadata.mjs

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { listWorkspaces, reportGlibcVersionRuntime } from './support.mjs';
+function persistentMetadataStampPath() {
+    return path.join(process.cwd(), 'node_modules', '.pnpm-install-metadata-health.json');
+}
+function fail(message) {
+    throw new Error(message);
+}
+function addFingerprintInput(hash, label, value) {
+    hash.update(`${label.length}:${label}${value.length}:${value}`);
+}
+async function optionalFile(pathname) {
+    try {
+        return await readFile(pathname, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+function runtimePlatformIdentity() {
+    const report = process.report?.getReport();
+    return JSON.stringify({
+        arch: process.arch,
+        glibc: reportGlibcVersionRuntime(report),
+        modules: process.versions.modules,
+        node: process.version,
+        npmConfigArch: process.env.npm_config_arch ?? '',
+        npmConfigLibc: process.env.npm_config_libc ?? '',
+        npmConfigPlatform: process.env.npm_config_platform ?? '',
+        platform: process.platform,
+    });
+}
+export async function persistentMetadataFingerprint(runCapture, installScripts) {
+    const workspaces = (await listWorkspaces(runCapture)).toSorted((left, right) => left.path.localeCompare(right.path));
+    const pnpmVersion = await runCapture(['--version']);
+    if (pnpmVersion.code !== 0)
+        fail(`pnpm --version failed: ${pnpmVersion.errorOutput?.trim() || pnpmVersion.output.trim() || 'unknown error'}`);
+    const hash = createHash('sha256');
+    addFingerprintInput(hash, 'runtime', runtimePlatformIdentity());
+    addFingerprintInput(hash, 'pnpm', pnpmVersion.output.trim());
+    addFingerprintInput(hash, 'installScripts', String(installScripts));
+    for (const filename of [
+        'pnpm-lock.yaml',
+        'pnpm-workspace.yaml',
+        '.npmrc',
+        '.pnpmfile.cjs',
+        '.pnpmfile.mjs',
+    ])
+        addFingerprintInput(hash, filename, await optionalFile(path.join(process.cwd(), filename)));
+    for (const workspace of workspaces)
+        addFingerprintInput(hash, path.relative(process.cwd(), path.join(workspace.path, 'package.json')), await readFile(path.join(workspace.path, 'package.json'), 'utf8'));
+    return hash.digest('hex');
+}
+export async function persistentMetadataMatches(fingerprint) {
+    try {
+        const stamp = JSON.parse(await readFile(persistentMetadataStampPath(), 'utf8'));
+        return stamp.version === 1 && stamp.fingerprint === fingerprint;
+    }
+    catch {
+        return false;
+    }
+}
+export async function persistentDependencyTreeIsCold() {
+    try {
+        await stat(path.dirname(persistentMetadataStampPath()));
+        return false;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        /* v8 ignore next -- non-ENOENT stat failures are host-specific */
+        throw error;
+    }
+}
+export async function writePersistentMetadataStamp(fingerprint) {
+    const stampPath = persistentMetadataStampPath();
+    const directory = path.dirname(stampPath);
+    const temporary = `${stampPath}.${process.pid}.tmp`;
+    await mkdir(directory, { recursive: true });
+    try {
+        await writeFile(temporary, `${JSON.stringify({ fingerprint, version: 1 })}\n`);
+        await rename(temporary, stampPath);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/pnpm-install/pnpm-install-fixture.test-helpers.d.mts

@@ -0,0 +1,22 @@
+export type FixtureOptions = {
+    commandTimeoutSeconds?: number;
+    installScripts?: boolean;
+    lifecycle?: 'ephemeral' | 'ephemeral-full' | 'persistent';
+    maxAttempts?: number;
+    selectors?: string;
+};
+export declare function makeFixture(): Promise<{
+    consumer: string;
+    dependency: string;
+    dependencyLink: string;
+    env: NodeJS.ProcessEnv;
+    pnpmLog: string;
+    root: string;
+    summary: string;
+}>;
+export declare function runInstaller(fixture: Awaited<ReturnType<typeof makeFixture>>, options?: FixtureOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function installCalls(fixture: Awaited<ReturnType<typeof makeFixture>>): Promise<string[]>;
+export declare function resetInstallCalls(fixture: Awaited<ReturnType<typeof makeFixture>>): Promise<void>;