vouchington-tooling 0.0.3 → 0.0.5

package/dist/gha-runtime-audit/index.test-helpers.mjs

@@ -0,0 +1,63 @@
+export const exampleAuditOptions = {
+    workflows: [
+        { name: 'CI', event: 'pull_request' },
+        { name: /^Main CI \(.+\)$/, event: 'push' },
+    ],
+};
+export function makeJob(runId, name, seconds, queueMinutes = 0, conclusion = 'success') {
+    const started = new Date(Date.UTC(2026, 0, runId, 0, queueMinutes));
+    return {
+        id: runId * 10,
+        name,
+        started_at: started.toISOString(),
+        completed_at: new Date(started.getTime() + seconds * 1000).toISOString(),
+        conclusion,
+        html_url: `https://github.test/jobs/${runId}`,
+    };
+}
+export function makeExecutor(runs, jobsByRun) {
+    return async (request) => {
+        const { endpoint } = request;
+        if (endpoint.includes('/actions/workflows?')) {
+            return {
+                workflows: endpoint.includes('page=1')
+                    ? [
+                        { id: 1, name: 'CI', state: 'active' },
+                        { id: 2, name: 'Main CI (web)', state: 'active' },
+                        { id: 3, name: 'Other', state: 'active' },
+                    ]
+                    : [],
+            };
+        }
+        if (endpoint.includes('/actions/workflows/1/runs?')) {
+            return {
+                workflow_runs: endpoint.includes('page=1')
+                    ? runs.filter((run) => run.name === 'CI')
+                    : [],
+            };
+        }
+        if (endpoint.includes('/actions/workflows/2/runs?')) {
+            return {
+                workflow_runs: endpoint.includes('page=1')
+                    ? runs.filter((run) => run.name === 'Main CI (web)')
+                    : [],
+            };
+        }
+        const match = endpoint.match(/\/actions\/runs\/(\d+)\/jobs/);
+        if (!match)
+            throw new Error(`Unexpected endpoint: ${endpoint}`);
+        return { jobs: jobsByRun[Number(match[1])] };
+    };
+}
+export function makeRun(id, name, event, branch = 'main', conclusion = 'success', createdAt = new Date(Date.UTC(2026, 0, id)).toISOString(), headBranch = branch) {
+    return {
+        id,
+        name,
+        event,
+        conclusion,
+        created_at: createdAt,
+        html_url: `https://github.test/runs/${id}`,
+        head_branch: headBranch,
+        pull_requests: event === 'pull_request' ? [{ base: { ref: branch } }] : [],
+    };
+}

package/dist/gha-runtime-audit/model.d.mts

@@ -0,0 +1,60 @@
+export interface GhApiRequest {
+    endpoint: string;
+    jq: string;
+}
+export type GhApiExecutor = (request: GhApiRequest) => Promise<unknown>;
+export interface WorkflowRecord {
+    id: number;
+    name: string;
+    state: string;
+}
+export interface RunRecord {
+    id: number;
+    name: string;
+    event: string;
+    conclusion: string;
+    createdAt: string;
+    url: string;
+    headBranch: string | null;
+    pullRequestBaseBranches: string[];
+}
+export interface RuntimeSample {
+    runId: number;
+    runUrl: string;
+    jobId: number;
+    jobUrl: string;
+    startedAt: string;
+    completedAt: string;
+    durationSeconds: number;
+}
+export type RuntimeViolationReason = 'sample-at-or-above-hard-ceiling' | 'five-sample-median-above-threshold';
+export interface RuntimeJobResult {
+    key: string;
+    workflow: string;
+    job: string;
+    sampleCount: number;
+    medianSeconds: number | null;
+    maximumSeconds: number;
+    reasons: RuntimeViolationReason[];
+    samples: RuntimeSample[];
+}
+export interface RuntimeAuditResult {
+    scope: {
+        repository: string;
+        sampleLimit: number;
+        recentCompletedRunHorizon: number;
+        medianThresholdSeconds: number;
+        hardCeilingSeconds: number;
+        branch: string;
+    };
+    jobs: RuntimeJobResult[];
+    violations: RuntimeJobResult[];
+}
+export declare function parseObject(value: unknown, detail: string): Record<string, unknown>;
+export declare function parseArray(value: unknown, detail: string): unknown[];
+export declare function parseRun(value: unknown): RunRecord;
+export declare function parseWorkflow(value: unknown): WorkflowRecord;
+export declare function parseSample(value: unknown, run: RunRecord): {
+    name: string;
+    sample: RuntimeSample;
+} | null;

package/dist/gha-runtime-audit/model.mjs

@@ -0,0 +1,83 @@
+function malformed(detail) {
+    throw new Error(`Malformed GitHub API data: ${detail}`);
+}
+export function parseObject(value, detail) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        malformed(detail);
+    return value;
+}
+function parseString(value, detail) {
+    if (typeof value !== 'string' || value.length === 0)
+        malformed(detail);
+    return value;
+}
+function parseNumber(value, detail) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0)
+        malformed(detail);
+    return value;
+}
+export function parseArray(value, detail) {
+    if (!Array.isArray(value))
+        malformed(detail);
+    return value;
+}
+function parseTimestamp(value, detail) {
+    const timestamp = parseString(value, `${detail} must be a non-empty string`);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        malformed(`${detail} must be an ISO timestamp`);
+    return timestamp;
+}
+export function parseRun(value) {
+    const run = parseObject(value, 'workflow run must be an object');
+    const pullRequests = parseArray(run['pull_requests'], 'workflow run pull_requests must be an array');
+    const pullRequestBaseBranches = [];
+    for (const [index, entry] of pullRequests.entries()) {
+        const pullRequest = parseObject(entry, `pull_requests[${index}] must be an object`);
+        const base = parseObject(pullRequest['base'], `pull_requests[${index}].base must be an object`);
+        pullRequestBaseBranches.push(parseString(base['ref'], `pull_requests[${index}].base.ref must be a string`));
+    }
+    return {
+        id: parseNumber(run['id'], 'workflow run id must be a positive integer'),
+        name: parseString(run['name'], 'workflow run name must be a non-empty string'),
+        event: parseString(run['event'], 'workflow run event must be a non-empty string'),
+        conclusion: parseString(run['conclusion'], 'workflow run conclusion must be a non-empty string'),
+        createdAt: parseTimestamp(run['created_at'], 'workflow run created_at'),
+        url: parseString(run['html_url'], 'workflow run html_url must be a non-empty string'),
+        headBranch: run['head_branch'] === null
+            ? null
+            : parseString(run['head_branch'], 'workflow run head_branch'),
+        pullRequestBaseBranches,
+    };
+}
+export function parseWorkflow(value) {
+    const workflow = parseObject(value, 'workflow must be an object');
+    return {
+        id: parseNumber(workflow['id'], 'workflow id must be a positive integer'),
+        name: parseString(workflow['name'], 'workflow name must be a non-empty string'),
+        state: parseString(workflow['state'], 'workflow state must be a non-empty string'),
+    };
+}
+export function parseSample(value, run) {
+    const job = parseObject(value, `job in run ${run.id} must be an object`);
+    const conclusion = parseString(job['conclusion'], `job in run ${run.id} conclusion must be a string`);
+    if (conclusion !== 'success')
+        return null;
+    const startedAt = parseTimestamp(job['started_at'], `job in run ${run.id} started_at`);
+    const completedAt = parseTimestamp(job['completed_at'], `job in run ${run.id} completed_at`);
+    const durationSeconds = (Date.parse(completedAt) - Date.parse(startedAt)) / 1000;
+    if (!Number.isFinite(durationSeconds) || durationSeconds < 0) {
+        malformed(`job in run ${run.id} has an invalid execution interval`);
+    }
+    return {
+        name: parseString(job['name'], `job in run ${run.id} name must be a non-empty string`),
+        sample: {
+            runId: run.id,
+            runUrl: run.url,
+            jobId: parseNumber(job['id'], `job in run ${run.id} id must be a positive integer`),
+            jobUrl: parseString(job['html_url'], `job in run ${run.id} html_url must be a string`),
+            startedAt,
+            completedAt,
+            durationSeconds,
+        },
+    };
+}

package/dist/gha-runtime-audit/results.d.mts

@@ -0,0 +1,15 @@
+import type { RuntimeJobResult, RuntimeSample } from './model.mts';
+export interface RuntimeSamplesByJob {
+    workflow: string;
+    job: string;
+    samples: RuntimeSample[];
+}
+export type RuntimeThresholds = {
+    medianThresholdSeconds: number;
+    hardCeilingSeconds: number;
+};
+export declare function violationOrder(a: RuntimeJobResult, b: RuntimeJobResult): number;
+export declare function buildRuntimeResults(samplesByKey: ReadonlyMap<string, RuntimeSamplesByJob>, thresholds: RuntimeThresholds): {
+    jobs: RuntimeJobResult[];
+    violations: RuntimeJobResult[];
+};

package/dist/gha-runtime-audit/results.mjs

@@ -0,0 +1,48 @@
+function summarize(entry, thresholds) {
+    const durations = [];
+    for (const sample of entry.samples)
+        durations.push(sample.durationSeconds);
+    durations.sort((a, b) => a - b);
+    const medianSeconds = durations.length === 5 ? durations[2] : null;
+    const reasons = [];
+    if (durations.some((duration) => duration >= thresholds.hardCeilingSeconds)) {
+        reasons.push('sample-at-or-above-hard-ceiling');
+    }
+    if (medianSeconds !== null && medianSeconds > thresholds.medianThresholdSeconds) {
+        reasons.push('five-sample-median-above-threshold');
+    }
+    return {
+        key: `${entry.workflow} / ${entry.job}`,
+        workflow: entry.workflow,
+        job: entry.job,
+        sampleCount: entry.samples.length,
+        medianSeconds,
+        maximumSeconds: Math.max(...durations),
+        reasons,
+        samples: entry.samples,
+    };
+}
+export function violationOrder(a, b) {
+    const aHard = a.reasons.includes('sample-at-or-above-hard-ceiling');
+    const bHard = b.reasons.includes('sample-at-or-above-hard-ceiling');
+    if (aHard && !bHard)
+        return -1;
+    if (!aHard && bHard)
+        return 1;
+    const aScore = aHard ? a.maximumSeconds : a.medianSeconds;
+    const bScore = bHard ? b.maximumSeconds : b.medianSeconds;
+    return bScore - aScore || a.key.localeCompare(b.key);
+}
+export function buildRuntimeResults(samplesByKey, thresholds) {
+    const jobs = [];
+    for (const entry of samplesByKey.values())
+        jobs.push(summarize(entry, thresholds));
+    jobs.sort((a, b) => a.key.localeCompare(b.key));
+    const violations = [];
+    for (const job of jobs) {
+        if (job.reasons.length > 0)
+            violations.push(job);
+    }
+    violations.sort(violationOrder);
+    return { jobs, violations };
+}

package/dist/gha-runtime-audit/scope.d.mts

@@ -0,0 +1,29 @@
+import type { RunRecord, WorkflowRecord } from './model.mts';
+export type WorkflowNameMatch = string | RegExp;
+export type RuntimeAuditWorkflowFilter = {
+    name: WorkflowNameMatch;
+    event: 'pull_request' | 'push';
+};
+export type RuntimeAuditOptions = {
+    repository: string;
+    workflows: RuntimeAuditWorkflowFilter[];
+    branch?: string;
+    sampleLimit?: number;
+    recentCompletedRunHorizon?: number;
+    medianThresholdSeconds?: number;
+    hardCeilingSeconds?: number;
+};
+export type ResolvedRuntimeAuditOptions = {
+    repository: string;
+    workflows: RuntimeAuditWorkflowFilter[];
+    branch: string;
+    sampleLimit: number;
+    recentCompletedRunHorizon: number;
+    medianThresholdSeconds: number;
+    hardCeilingSeconds: number;
+};
+export declare function parseWorkflowNameMatch(value: string): WorkflowNameMatch;
+export declare function resolveRuntimeAuditOptions(options: RuntimeAuditOptions): ResolvedRuntimeAuditOptions;
+export declare function matchingWorkflowFilter(name: string, filters: readonly RuntimeAuditWorkflowFilter[]): RuntimeAuditWorkflowFilter | undefined;
+export declare function isSelectedWorkflow(workflow: WorkflowRecord, filters: readonly RuntimeAuditWorkflowFilter[]): boolean;
+export declare function isRunInScope(run: RunRecord, filter: RuntimeAuditWorkflowFilter, branch: string): boolean;

package/dist/gha-runtime-audit/scope.mjs

@@ -0,0 +1,39 @@
+function matchesWorkflowName(name, match) {
+    return typeof match === 'string' ? name === match : match.test(name);
+}
+export function parseWorkflowNameMatch(value) {
+    if (value.length >= 2 && value.startsWith('/') && value.endsWith('/')) {
+        return new RegExp(value.slice(1, -1));
+    }
+    return value;
+}
+export function resolveRuntimeAuditOptions(options) {
+    if (!/^[^/]+\/[^/]+$/.test(options.repository)) {
+        throw new Error('Repository must be owner/name');
+    }
+    if (options.workflows.length === 0) {
+        throw new Error('At least one workflow filter is required');
+    }
+    return {
+        repository: options.repository,
+        workflows: options.workflows,
+        branch: options.branch ?? 'main',
+        sampleLimit: options.sampleLimit ?? 5,
+        recentCompletedRunHorizon: options.recentCompletedRunHorizon ?? 10,
+        medianThresholdSeconds: options.medianThresholdSeconds ?? 360,
+        hardCeilingSeconds: options.hardCeilingSeconds ?? 600,
+    };
+}
+export function matchingWorkflowFilter(name, filters) {
+    return filters.find((filter) => matchesWorkflowName(name, filter.name));
+}
+export function isSelectedWorkflow(workflow, filters) {
+    return workflow.state === 'active' && matchingWorkflowFilter(workflow.name, filters) !== undefined;
+}
+export function isRunInScope(run, filter, branch) {
+    if (run.event !== filter.event)
+        return false;
+    if (filter.event === 'pull_request')
+        return run.pullRequestBaseBranches.includes(branch);
+    return run.headBranch === branch;
+}

package/dist/index.d.mts

@@ -3,3 +3,11 @@ export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-p
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
 export type { ForeignKey, SqlCreateIndexMetadata, SqlCreateTableColumn, SqlCreateTableMetadata, SqlDropIndexMetadata, SqlIndexParam, SqlMigrationConstraintMetadata, } from './sql-ast/index.mts';
 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 { formatReleaseAgeFailure, 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

@@ -1,3 +1,7 @@
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mjs';
 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 { formatReleaseAgeFailure, 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,5 @@
+export { runInstallLifecycle } from './runner.mts';
+export { parseInstallOptions } from './support.mts';
+export type { InstallOptions, Lifecycle } from './support.mts';
+export { formatReleaseAgeFailure, isReleaseAgeViolation, parseReleaseAgeViolations, } from './release-age.mts';
+export { INSTALL_TERMINATION_FAILED } from './process.mts';

package/dist/pnpm-install/index.mjs

@@ -0,0 +1,4 @@
+export { runInstallLifecycle } from './runner.mjs';
+export { parseInstallOptions } from './support.mjs';
+export { formatReleaseAgeFailure, isReleaseAgeViolation, parseReleaseAgeViolations, } from './release-age.mjs';
+export { INSTALL_TERMINATION_FAILED } from './process.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>;