vouchington-tooling 0.0.4 → 0.0.6

package/dist/pnpm-install/pnpm-install-fixture.test-helpers.mjs

@@ -0,0 +1,174 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { runPnpmInstallCli } from '../cli/commands/pnpm-install.mjs';
+const execFileAsync = promisify(execFile);
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value)}\n`);
+}
+export async function makeFixture() {
+    const root = await mkdtemp(join(tmpdir(), 'pnpm-install-'));
+    const consumer = join(root, 'packages', 'consumer');
+    const dependency = join(root, 'packages', 'dependency');
+    const dependencyLink = join(consumer, 'node_modules', '@fixture', 'dependency');
+    const pnpmBin = join(root, 'bin');
+    const pnpmLog = join(root, 'pnpm.log');
+    const summary = join(root, 'summary.md');
+    await Promise.all([
+        writeJson(join(root, 'package.json'), { name: 'fixture-root', private: true }),
+        writeFile(join(root, 'pnpm-workspace.yaml'), 'packages:\n  - packages/*\nminimumReleaseAge: 2880\n'),
+        writeJson(join(consumer, 'package.json'), {
+            name: '@fixture/consumer',
+            dependencies: { '@fixture/dependency': 'workspace:^' },
+        }),
+        writeJson(join(dependency, 'package.json'), { name: '@fixture/dependency', version: '1.0.0' }),
+        mkdir(dirname(dependencyLink), { recursive: true }),
+        mkdir(pnpmBin),
+    ]);
+    await symlink(dependency, dependencyLink, 'dir');
+    await writeFile(join(pnpmBin, 'pnpm'), `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = m ]; then
+  if [ -n "\${PNPM_LIST_WARNING:-}" ]; then printf '%s\\n' "$PNPM_LIST_WARNING" >&2; fi
+  printf '%s\\n' "$PNPM_WORKSPACES_JSON"
+  exit 0
+fi
+if [ "\${1:-}" = --version ]; then
+  printf '%s\\n' "\${PNPM_VERSION:-11.0.0}"
+  exit 0
+fi
+printf '%s\\n' "$*" >> "$PNPM_LOG"
+calls=0
+if [ -f "$PNPM_CALLS" ]; then calls="$(cat "$PNPM_CALLS")"; fi
+calls=$((calls + 1))
+printf '%s' "$calls" > "$PNPM_CALLS"
+print_release_age_violation() {
+  printf '%s\\n' '✗ Lockfile failed supply-chain policy check (1 entries in 0.1s)'
+  printf '%s\\n' '[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] 1 lockfile entries failed verification:'
+  printf '%s\\n' '  undici@8.10.0 was published at 2026-08-03T15:06:33.000Z, within the minimumReleaseAge cutoff (2026-08-02T04:48:10.357Z)'
+}
+if [ "\${PNPM_FAIL_CALL:-0}" = "$calls" ]; then
+  if [ -n "\${PNPM_FAIL_RELEASE_AGE:-}" ]; then print_release_age_violation; fi
+  exit "\${PNPM_FAIL_CODE:-1}"
+fi
+if [ "\${PNPM_FAIL_RELEASE_AGE_CALL:-0}" = "$calls" ]; then
+  print_release_age_violation
+  exit 1
+fi
+if [ -n "\${PNPM_SLEEP_SECONDS:-}" ]; then sleep "$PNPM_SLEEP_SECONDS"; fi
+case " $* " in
+  *' --force '*)
+    if [ "\${PNPM_REPAIR_LINK:-0}" = 1 ]; then
+      mkdir -p "$(dirname "$PNPM_DEPENDENCY_LINK")"
+      rm -f "$PNPM_DEPENDENCY_LINK"
+      ln -s "$PNPM_DEPENDENCY" "$PNPM_DEPENDENCY_LINK"
+    fi
+    ;;
+esac
+`);
+    await execFileAsync('chmod', ['+x', join(pnpmBin, 'pnpm')]);
+    const workspaces = [
+        { name: 'fixture-root', path: root },
+        { name: '@fixture/consumer', path: consumer },
+        { name: '@fixture/dependency', path: dependency },
+    ];
+    const env = {
+        ...process.env,
+        GITHUB_STEP_SUMMARY: summary,
+        PATH: `${pnpmBin}:${process.env.PATH ?? ''}`,
+        PNPM_CALLS: join(root, 'pnpm.calls'),
+        PNPM_DEPENDENCY: dependency,
+        PNPM_DEPENDENCY_LINK: dependencyLink,
+        PNPM_LOG: pnpmLog,
+        PNPM_REPAIR_LINK: '0',
+        PNPM_WORKSPACES_JSON: JSON.stringify(workspaces),
+    };
+    return {
+        consumer,
+        dependency,
+        dependencyLink,
+        env,
+        pnpmLog,
+        root,
+        summary,
+    };
+}
+export async function runInstaller(fixture, options = {}) {
+    const lifecycle = options.lifecycle ?? 'persistent';
+    const installScripts = options.installScripts ?? true;
+    const args = [
+        '--runner-lifecycle',
+        lifecycle,
+        '--install-scripts',
+        String(installScripts),
+        '--command-timeout-seconds',
+        String(options.commandTimeoutSeconds ?? 0),
+        '--max-attempts',
+        String(options.maxAttempts ?? 1),
+    ];
+    if (options.selectors !== undefined)
+        args.push('--ephemeral-workspaces', options.selectors);
+    const previousCwd = process.cwd();
+    const previousEnv = { ...process.env };
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const write = (chunk, sink) => {
+        sink.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString());
+        return true;
+    };
+    const stdout = process.stdout.write.bind(process.stdout);
+    const stderr = process.stderr.write.bind(process.stderr);
+    const warn = console.warn;
+    const error = console.error;
+    process.stdout.write = ((chunk) => write(chunk, stdoutChunks));
+    process.stderr.write = ((chunk) => write(chunk, stderrChunks));
+    console.warn = (...values) => {
+        stderrChunks.push(values.map(String).join(' '));
+    };
+    console.error = (...values) => {
+        stderrChunks.push(values.map(String).join(' '));
+    };
+    process.chdir(fixture.root);
+    Object.assign(process.env, fixture.env);
+    try {
+        const code = await runPnpmInstallCli(args);
+        const result = { stdout: stdoutChunks.join(''), stderr: stderrChunks.join('') };
+        if (code !== 0) {
+            throw Object.assign(new Error(result.stderr || 'pnpm-install failed'), {
+                code,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            });
+        }
+        return result;
+    }
+    finally {
+        process.stdout.write = stdout;
+        process.stderr.write = stderr;
+        console.warn = warn;
+        console.error = error;
+        process.chdir(previousCwd);
+        for (const key of Object.keys(process.env)) {
+            if (!(key in previousEnv))
+                delete process.env[key];
+        }
+        Object.assign(process.env, previousEnv);
+    }
+}
+export async function installCalls(fixture) {
+    try {
+        return (await readFile(fixture.pnpmLog, 'utf8')).trim().split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export async function resetInstallCalls(fixture) {
+    await Promise.all([
+        rm(fixture.pnpmLog, { force: true }),
+        rm(fixture.env.PNPM_CALLS, { force: true }),
+    ]);
+}

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

@@ -0,0 +1,11 @@
+export declare const INSTALL_TERMINATION_FAILED = -1;
+export declare function safeProcessGroup(pid: number | undefined): number | undefined;
+export declare function installExitCode(code: number | null, timedOut: boolean): number;
+export declare function startInstallHeartbeat(): NodeJS.Timeout;
+export type ProcessGroupSupervisor = {
+    isAlive: (processGroup: number) => boolean;
+    signal: (processGroup: number, signal: NodeJS.Signals) => void;
+    waitForExit: (processGroup: number, timeoutMs: number) => Promise<boolean>;
+};
+export declare function terminateProcessGroup(processGroup: number, supervisor?: ProcessGroupSupervisor): Promise<boolean>;
+export declare function terminateSafeProcessGroup(pid: number | undefined): Promise<boolean>;

package/dist/pnpm-install/process.mjs

@@ -0,0 +1,81 @@
+import { scheduler } from 'node:timers/promises';
+const TERM_GRACE_SECONDS = 10;
+const KILL_GRACE_SECONDS = 10;
+const HEARTBEAT_SECONDS = 30;
+export const INSTALL_TERMINATION_FAILED = -1;
+export function safeProcessGroup(pid) {
+    return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+}
+export function installExitCode(code, timedOut) {
+    return timedOut ? 1 : (code ?? 1);
+}
+export function startInstallHeartbeat() {
+    const started = performance.now();
+    const heartbeat = setInterval(() => {
+        console.warn(`pnpm install still running after ${Math.floor((performance.now() - started) / 1000)}s`);
+    }, HEARTBEAT_SECONDS * 1000);
+    heartbeat.unref();
+    return heartbeat;
+}
+function processGroupExists(processGroup) {
+    try {
+        // oxlint-disable-next-line no-restricted-properties -- the installer must verify its detached process group has stopped
+        process.kill(-processGroup, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function waitForProcessGroupExit(processGroup, timeoutMs) {
+    const deadline = performance.now() + timeoutMs;
+    while (processGroupExists(processGroup)) {
+        /* v8 ignore next -- a live group that outlasts both grace windows is host-specific */
+        if (performance.now() >= deadline)
+            return false;
+        await scheduler.wait(100);
+    }
+    return true;
+}
+const processGroupSupervisor = {
+    isAlive: processGroupExists,
+    signal(processGroup, signal) {
+        // oxlint-disable-next-line no-restricted-properties -- the installer must terminate the detached process group before retrying
+        process.kill(-processGroup, signal);
+    },
+    waitForExit: waitForProcessGroupExit,
+};
+export async function terminateProcessGroup(processGroup, supervisor = processGroupSupervisor) {
+    const signal = (value) => {
+        try {
+            supervisor.signal(processGroup, value);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                return false;
+            throw error;
+        }
+    };
+    if (!supervisor.isAlive(processGroup))
+        return true;
+    console.warn(`pnpm install process group ${processGroup} exceeded its deadline; sending TERM`);
+    if (!signal('SIGTERM'))
+        return true;
+    if (await supervisor.waitForExit(processGroup, TERM_GRACE_SECONDS * 1000))
+        return true;
+    console.warn(`pnpm install process group ${processGroup} ignored TERM; sending KILL`);
+    if (!signal('SIGKILL'))
+        return true;
+    if (await supervisor.waitForExit(processGroup, KILL_GRACE_SECONDS * 1000))
+        return true;
+    console.error(`pnpm install process group ${processGroup} survived SIGKILL for ${KILL_GRACE_SECONDS}s; refusing to overlap another attempt`);
+    return false;
+}
+export function terminateSafeProcessGroup(pid) {
+    const processGroup = safeProcessGroup(pid);
+    if (processGroup !== undefined)
+        return terminateProcessGroup(processGroup);
+    console.error('pnpm install timed out before a safe child process group was available');
+    return Promise.resolve(false);
+}

package/dist/pnpm-install/release-age.d.mts

@@ -0,0 +1,9 @@
+export interface ReleaseAgeViolation {
+    cutoff: string;
+    packageSpec: string;
+    publishedAt: string;
+}
+/** Gate on the stable pnpm error code; detail-line shape is parsed best-effort separately. */
+export declare function isReleaseAgeViolation(log: string): boolean;
+export declare function parseReleaseAgeViolations(log: string): ReleaseAgeViolation[];
+export declare function formatReleaseAgeFailure(label: string, log: string, docsLink?: string): string;

package/dist/pnpm-install/release-age.mjs

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+// pnpm's supply-chain policy check is permanent-until-timestamp, not transient: retrying an
+// ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION cannot succeed before the flagged release ages past
+// pnpm-workspace.yaml's minimumReleaseAge. Fail those attempts immediately instead of burning
+// retries against a deterministic wall-clock gate.
+const TOKEN = 'ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION';
+// Targets pnpm's stable detail-line wording; if pnpm rephrases it, parseReleaseAgeViolations()
+// falls back to an empty list and formatReleaseAgeFailure() still reports terminal (see below).
+const DETAIL_LINE = /^\s*(?<packageSpec>\S+) was published at (?<publishedAt>\S+), within the minimumReleaseAge cutoff \((?<cutoff>\S+)\)\s*$/gm;
+const defaultDocsLink = process.env['PNPM_INSTALL_DOCS_URL'] ?? 'pnpm minimumReleaseAge';
+// This module loads before `pnpm install` has ever run, so it cannot depend on a package pnpm
+// would install — including yaml. minimumReleaseAge is a single top-level scalar, so a targeted
+// line match avoids needing a YAML parser at all.
+const MINIMUM_RELEASE_AGE_LINE = /^minimumReleaseAge:\s*(?<minutes>\d+)\s*(?:#.*)?$/m;
+/** Gate on the stable pnpm error code; detail-line shape is parsed best-effort separately. */
+export function isReleaseAgeViolation(log) {
+    return log.includes(TOKEN);
+}
+export function parseReleaseAgeViolations(log) {
+    const violations = [];
+    for (const match of log.matchAll(DETAIL_LINE)) {
+        const { cutoff, packageSpec, publishedAt } = match.groups ?? {};
+        if (cutoff && packageSpec && publishedAt)
+            violations.push({ cutoff, packageSpec, publishedAt });
+    }
+    return violations;
+}
+function workspaceMinimumReleaseAgeMinutes() {
+    try {
+        const workspace = readFileSync(`${process.cwd()}/pnpm-workspace.yaml`, 'utf8');
+        const minutes = MINIMUM_RELEASE_AGE_LINE.exec(workspace)?.groups?.minutes;
+        return minutes === undefined ? undefined : Number(minutes);
+    }
+    catch (error) {
+        console.warn(`unable to read minimumReleaseAge from pnpm-workspace.yaml: ${String(error)}`);
+        return undefined;
+    }
+}
+function eligibleAt(publishedAt, minutes) {
+    const published = new Date(publishedAt);
+    if (minutes === undefined || Number.isNaN(published.getTime()))
+        return undefined;
+    return new Date(published.getTime() + minutes * 60_000).toISOString();
+}
+export function formatReleaseAgeFailure(label, log, docsLink = defaultDocsLink) {
+    const violations = parseReleaseAgeViolations(log);
+    const minutes = workspaceMinimumReleaseAgeMinutes();
+    const lines = violations.length > 0
+        ? violations.map((violation) => {
+            const eligible = eligibleAt(violation.publishedAt, minutes);
+            return `  ${violation.packageSpec} published ${violation.publishedAt}${eligible ? `, eligible at ${eligible}` : ''}`;
+        })
+        : ['  (violation details were not present in the captured log)'];
+    return [
+        `${label} failed: the lockfile has entries that violate pnpm's minimumReleaseAge supply-chain policy. This is not transient and will not pass until the flagged release ages past the cutoff:`,
+        ...lines,
+        `See ${docsLink}.`,
+    ].join('\n');
+}

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

@@ -0,0 +1,2 @@
+import { type InstallOptions } from './support.mts';
+export declare function runInstallLifecycle(options: InstallOptions): Promise<string>;

package/dist/pnpm-install/runner.mjs

@@ -0,0 +1,106 @@
+import { scheduler } from 'node:timers/promises';
+import { persistentDependencyTreeIsCold, persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata.mjs';
+import { runPnpm } from './exec.mjs';
+import { INSTALL_TERMINATION_FAILED } from './process.mjs';
+import { formatReleaseAgeFailure, isReleaseAgeViolation } from './release-age.mjs';
+import { baseInstallArgs, findWorkspaceLinkMismatches, logWorkspaceLinkMismatches, } from './support.mjs';
+// oxfmt-ignore
+const fail = (message) => { throw new Error(message); };
+async function install(args, options, label) {
+    for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
+        const attemptResult = await runPnpm(args, options);
+        if (attemptResult.code === 0)
+            return;
+        if (attemptResult.code === INSTALL_TERMINATION_FAILED)
+            fail(`${label} could not terminate safely`);
+        const combinedOutput = `${attemptResult.output}\n${attemptResult.errorOutput ?? ''}`;
+        if (isReleaseAgeViolation(combinedOutput))
+            fail(formatReleaseAgeFailure(label, combinedOutput));
+        if (attempt < options.maxAttempts) {
+            console.warn(`${label} failed (attempt ${attempt}/${options.maxAttempts}); retrying`);
+            await scheduler.wait(5000);
+        }
+    }
+    fail(`${label} failed after ${options.maxAttempts} attempt${options.maxAttempts === 1 ? '' : 's'}`);
+}
+function withScriptPolicy(args, installScripts) {
+    return installScripts ? args : [...args, '--ignore-scripts'];
+}
+async function reconcileAndFindMismatches(options, runCapture) {
+    const forced = ['install', '--frozen-lockfile', '--force', ...baseInstallArgs.slice(2)];
+    // oxfmt-ignore
+    await install([...forced, '--ignore-scripts', '--ignore-pnpmfile'], options, 'script-free reconciliation');
+    // oxfmt-ignore
+    await install(withScriptPolicy(forced, options.installScripts), options, 'strict persistent reconciliation');
+    return findWorkspaceLinkMismatches(runCapture);
+}
+async function reconcileOrFail(options, runCapture) {
+    const remaining = await reconcileAndFindMismatches(options, runCapture);
+    if (remaining.length > 0) {
+        logWorkspaceLinkMismatches(remaining);
+        fail('persistent reconciliation completed with invalid workspace links');
+    }
+}
+async function persistent(options) {
+    if (options.ephemeralWorkspaces.trim())
+        fail('ephemeral-workspaces is only valid for ephemeral runners');
+    const runCapture = (args) => runPnpm(args, options, true);
+    const fingerprint = await persistentMetadataFingerprint(runCapture, options.installScripts);
+    const stamped = await persistentMetadataMatches(fingerprint);
+    // An absent tree has nothing to repair, so one ordinary install below matches the
+    // reconciled end state. Check first: an install would otherwise make the tree non-cold.
+    const cold = !stamped && (await persistentDependencyTreeIsCold());
+    if (!stamped && !cold) {
+        console.warn('persistent dependency metadata provenance is missing or changed; reconciling');
+        await reconcileOrFail(options, runCapture);
+        await writePersistentMetadataStamp(fingerprint);
+        return 'persistent metadata reconciled';
+    }
+    if (!stamped)
+        console.warn('persistent dependency tree is absent; installing cold');
+    await install(withScriptPolicy([...baseInstallArgs], options.installScripts), options, 'ordinary persistent install');
+    const stale = await findWorkspaceLinkMismatches(runCapture);
+    if (stale.length === 0) {
+        if (!stamped)
+            await writePersistentMetadataStamp(fingerprint);
+        return stamped ? 'persistent ordinary' : 'persistent cold';
+    }
+    logWorkspaceLinkMismatches(stale);
+    await reconcileOrFail(options, runCapture);
+    await writePersistentMetadataStamp(fingerprint);
+    return 'persistent reconciled';
+}
+// A path selector's `...` (dependency closure) suffix is silently ignored by pnpm unless the
+// path is brace-wrapped, e.g. `{./web}...` — `./web...` installs only `web` itself. Reject the
+// unbraced form outright rather than let it resolve to a smaller-than-intended scope.
+function isUnbracedPathClosureSelector(selector) {
+    return /^\.{0,2}\//.test(selector) && selector.endsWith('...') && !selector.startsWith('{');
+}
+async function ephemeral(options) {
+    const selectors = options.ephemeralWorkspaces
+        .split('\n')
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (selectors.length === 0)
+        fail('ephemeral-workspaces must contain at least one selector');
+    if (selectors.some((selector) => selector.startsWith('!') || selector.startsWith('-') || /\s/.test(selector)))
+        fail('ephemeral-workspaces selectors must be positive and not flags');
+    if (selectors.some(isUnbracedPathClosureSelector))
+        fail('ephemeral-workspaces path selectors must be brace-wrapped, e.g. {./web}... — bare ./web... silently drops its workspace dependencies');
+    const args = withScriptPolicy([...baseInstallArgs], options.installScripts);
+    for (const selector of selectors)
+        args.push('--filter', selector);
+    await install([...args, '--fail-if-no-match'], options, 'ephemeral filtered install');
+    return 'ephemeral filtered';
+}
+async function ephemeralFull(options) {
+    if (options.ephemeralWorkspaces.trim())
+        fail('ephemeral-workspaces is only valid for filtered ephemeral runners');
+    await install(withScriptPolicy([...baseInstallArgs], options.installScripts), options, 'ephemeral full install');
+    return 'ephemeral full';
+}
+export function runInstallLifecycle(options) {
+    if (options.runnerLifecycle === 'persistent')
+        return persistent(options);
+    return options.runnerLifecycle === 'ephemeral-full' ? ephemeralFull(options) : ephemeral(options);
+}

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

@@ -0,0 +1,30 @@
+export type Lifecycle = 'ephemeral' | 'ephemeral-full' | 'persistent';
+export type InstallOptions = {
+    commandTimeoutSeconds: number;
+    ephemeralWorkspaces: string;
+    installScripts: boolean;
+    maxAttempts: number;
+    runnerLifecycle: Lifecycle;
+};
+export type CommandResult = {
+    code: number;
+    errorOutput?: string;
+    output: string;
+};
+export type CaptureCommand = (args: string[]) => Promise<CommandResult>;
+export type WorkspaceLinkMismatch = {
+    actual: string;
+    dependency: string;
+    expected: string;
+    workspace: string;
+};
+export type Workspace = {
+    name: string;
+    path: string;
+};
+export declare const baseInstallArgs: string[];
+export declare function parseInstallOptions(argv: string[]): InstallOptions;
+export declare function listWorkspaces(runCapture: CaptureCommand): Promise<Workspace[]>;
+export declare function findWorkspaceLinkMismatches(runCapture: CaptureCommand): Promise<WorkspaceLinkMismatch[]>;
+export declare function logWorkspaceLinkMismatches(mismatches: WorkspaceLinkMismatch[]): void;
+export declare function reportGlibcVersionRuntime(report: object | undefined): string;

package/dist/pnpm-install/support.mjs

@@ -0,0 +1,143 @@
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+export const baseInstallArgs = [
+    'install',
+    '--frozen-lockfile',
+    '--prefer-offline',
+    '--prod=false',
+    '--config.disallow-workspace-cycles=false',
+];
+const usage = 'usage: vouchington pnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false [--ephemeral-workspaces <newline-separated selectors>] [--command-timeout-seconds <nonnegative integer>] [--max-attempts <positive integer>]';
+const MAX_COMMAND_TIMEOUT_SECONDS = 3600;
+const MAX_ATTEMPTS = 10;
+function fail(message) {
+    throw new Error(message);
+}
+function integer(value, name, allowZero, maximum) {
+    if (!/^\d+$/.test(value) || (!allowZero && value === '0'))
+        fail(`${name} must be ${allowZero ? 'a nonnegative' : 'a positive'} integer`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed > maximum)
+        fail(`${name} must not exceed ${maximum}`);
+    return parsed;
+}
+export function parseInstallOptions(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 2) {
+        const key = argv[index];
+        const value = argv[index + 1];
+        if (!key?.startsWith('--') || value === undefined || values.has(key))
+            fail(usage);
+        values.set(key, value);
+    }
+    const supported = new Set([
+        '--command-timeout-seconds',
+        '--ephemeral-workspaces',
+        '--install-scripts',
+        '--max-attempts',
+        '--runner-lifecycle',
+    ]);
+    if ([...values.keys()].some((key) => !supported.has(key)))
+        fail(usage);
+    const runnerLifecycle = values.get('--runner-lifecycle');
+    const installScripts = values.get('--install-scripts');
+    if ((runnerLifecycle !== 'ephemeral' &&
+        runnerLifecycle !== 'ephemeral-full' &&
+        runnerLifecycle !== 'persistent') ||
+        (installScripts !== 'true' && installScripts !== 'false'))
+        fail(usage);
+    return {
+        commandTimeoutSeconds: integer(values.get('--command-timeout-seconds') ?? '120', '--command-timeout-seconds', true, MAX_COMMAND_TIMEOUT_SECONDS),
+        ephemeralWorkspaces: values.get('--ephemeral-workspaces') ?? '',
+        installScripts: installScripts === 'true',
+        maxAttempts: integer(values.get('--max-attempts') ?? '3', '--max-attempts', false, MAX_ATTEMPTS),
+        runnerLifecycle,
+    };
+}
+export async function listWorkspaces(runCapture) {
+    const result = await runCapture(['m', 'ls', '--depth=-1', '--json']);
+    if (result.code !== 0)
+        fail(`pnpm m ls failed: ${result.errorOutput?.trim() || result.output.trim() || 'unknown error'}`);
+    let entries;
+    try {
+        entries = JSON.parse(result.output);
+    }
+    catch {
+        fail('pnpm m ls returned invalid workspace JSON');
+    }
+    if (!Array.isArray(entries) || entries.length === 0)
+        fail('pnpm m ls returned an invalid or empty workspace list');
+    const listed = entries.flatMap((entry) => typeof entry === 'object' &&
+        entry !== null &&
+        typeof entry.name === 'string' &&
+        typeof entry.path === 'string'
+        ? [entry]
+        : []);
+    if (listed.length !== entries.length)
+        fail('pnpm m ls returned an invalid workspace list');
+    return listed;
+}
+async function workspaceDependencies(workspace) {
+    const pkg = JSON.parse(await readFile(path.join(workspace.path, 'package.json'), 'utf8'));
+    return Object.entries({
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+        ...pkg.optionalDependencies,
+    })
+        .flatMap(([name, spec]) => (typeof spec === 'string' ? [{ name, spec }] : []))
+        .toSorted((left, right) => left.name.localeCompare(right.name));
+}
+export async function findWorkspaceLinkMismatches(runCapture) {
+    const workspaces = await listWorkspaces(runCapture);
+    const targets = new Map(await Promise.all(workspaces.map(async (workspace) => [workspace.name, await realpath(workspace.path)])));
+    const mismatches = [];
+    for (const workspace of workspaces) {
+        for (const dependency of await workspaceDependencies(workspace)) {
+            if (!dependency.spec.startsWith('workspace:'))
+                continue;
+            const expected = targets.get(dependency.name);
+            const link = path.join(workspace.path, 'node_modules', dependency.name);
+            if (!expected) {
+                mismatches.push({
+                    actual: 'unknown workspace',
+                    dependency: dependency.name,
+                    expected: dependency.name,
+                    workspace: workspace.name,
+                });
+                continue;
+            }
+            try {
+                const actual = await realpath(link);
+                if (actual !== expected)
+                    mismatches.push({
+                        actual,
+                        dependency: dependency.name,
+                        expected,
+                        workspace: workspace.name,
+                    });
+            }
+            catch {
+                mismatches.push({
+                    actual: 'missing or broken link',
+                    dependency: dependency.name,
+                    expected,
+                    workspace: workspace.name,
+                });
+            }
+        }
+    }
+    return mismatches;
+}
+export function logWorkspaceLinkMismatches(mismatches) {
+    for (const mismatch of mismatches)
+        console.warn(`workspace link mismatch: ${mismatch.workspace} -> ${mismatch.dependency}; expected ${mismatch.expected}, got ${mismatch.actual}`);
+}
+export function reportGlibcVersionRuntime(report) {
+    if (!report || !('header' in report))
+        return '';
+    const { header } = report;
+    if (typeof header !== 'object' || header === null || !('glibcVersionRuntime' in header))
+        return '';
+    const { glibcVersionRuntime } = header;
+    return typeof glibcVersionRuntime === 'string' ? glibcVersionRuntime : '';
+}

package/dist/shared-context/fake-git.test-helpers.d.mts

@@ -0,0 +1,11 @@
+export type FakeGitOptions = {
+    binDir: string;
+    isInsideWorkTree?: boolean;
+    lsFilesExitCode?: number;
+    lsFilesStderr?: string;
+    pathPrefix?: string;
+    repoRoot?: string;
+    trackedFiles?: readonly string[];
+};
+export declare function installFakeGit({ binDir, isInsideWorkTree, lsFilesExitCode, lsFilesStderr, pathPrefix, repoRoot, trackedFiles, }: FakeGitOptions): void;
+export declare function clearFakeGitEnv(): void;