vouchington-tooling 0.0.3 → 0.0.5

package/README.md

@@ -16,6 +16,14 @@ vouchington runner-port-policy
 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:
@@ -37,4 +45,8 @@ import {
 } from 'vouchington-tooling/runner-port-policy'
 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/gha-runtime-audit.d.mts

@@ -0,0 +1,3 @@
+import { type GhApiExecutor } from '../../gha-runtime-audit/index.mts';
+import type { ParsedGhaRuntimeAudit } from '../parse-gha-runtime-audit.mts';
+export declare function runGhaRuntimeAudit(parsed: ParsedGhaRuntimeAudit, execute?: GhApiExecutor, env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/cli/commands/gha-runtime-audit.mjs

@@ -0,0 +1,23 @@
+import { execFileSync } from 'node:child_process';
+import { auditCiJobRuntime } from '../../gha-runtime-audit/index.mjs';
+/* v8 ignore next 10 -- live `gh api` adapter */
+function defaultGhApiExecutor() {
+    return async (request) => JSON.parse(execFileSync('gh', ['api', request.endpoint, '--jq', request.jq], {
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+    }));
+}
+export async function runGhaRuntimeAudit(parsed, execute = defaultGhApiExecutor(), env = process.env) {
+    const repository = parsed.repository ?? env['GITHUB_REPOSITORY'];
+    if (!repository) {
+        process.stderr.write('vouchington: --repository or GITHUB_REPOSITORY is required\n');
+        return 2;
+    }
+    const result = await auditCiJobRuntime(execute, {
+        repository,
+        workflows: parsed.workflows,
+        ...(parsed.branch === undefined ? {} : { branch: parsed.branch }),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+}

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.d.mts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export declare function runCli(argv?: readonly string[]): number;
+export declare function runCli(argv?: readonly string[]): number | Promise<number>;
 export declare function isMainModule(metaUrl: string, argv1: string | undefined): boolean;

package/dist/cli/index.mjs

@@ -3,10 +3,31 @@ import { readFileSync, realpathSync } from 'node:fs';
 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) {
@@ -24,6 +45,16 @@ export function runCli(argv = process.argv) {
             return runRunnerPortPolicy(parsed);
         case 'with-host-lock':
             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() {
@@ -39,7 +70,17 @@ export function isMainModule(metaUrl, argv1) {
         return metaUrl === pathToFileURL(resolve(argv1)).href;
     }
 }
-/* v8 ignore next 3 */
+/* v8 ignore next 8 */
 if (isMainModule(import.meta.url, process.argv[1])) {
-    process.exitCode = runCli();
+    const result = runCli();
+    if (typeof result === 'number')
+        process.exitCode = result;
+    else {
+        result.then((code) => {
+            process.exitCode = code;
+        }, (error) => {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        });
+    }
 }

package/dist/cli/parse-gha-runtime-audit.d.mts

@@ -0,0 +1,13 @@
+import { type RuntimeAuditWorkflowFilter } from '../gha-runtime-audit/scope.mts';
+export type ParsedGhaRuntimeAudit = {
+    kind: 'gha-runtime-audit';
+    repository?: string;
+    branch?: string;
+    workflows: RuntimeAuditWorkflowFilter[];
+};
+export declare function parseGhaRuntimeAudit(args: readonly string[]): ParsedGhaRuntimeAudit | {
+    kind: 'help';
+} | {
+    kind: 'error';
+    message: string;
+};

package/dist/cli/parse-gha-runtime-audit.mjs

@@ -0,0 +1,44 @@
+import { parseWorkflowNameMatch, } from '../gha-runtime-audit/scope.mjs';
+export function parseGhaRuntimeAudit(args) {
+    let repository;
+    let branch;
+    const workflows = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === '--help' || flag === '-h')
+            return { kind: 'help' };
+        if (flag === '--repository' ||
+            flag === '--pr-workflow' ||
+            flag === '--push-workflow' ||
+            flag === '--branch') {
+            const value = args[index + 1];
+            if (value === undefined)
+                return { kind: 'error', message: `${flag} requires a value` };
+            index += 1;
+            if (flag === '--repository')
+                repository = value;
+            else if (flag === '--branch')
+                branch = value;
+            else {
+                workflows.push({
+                    name: parseWorkflowNameMatch(value),
+                    event: flag === '--pr-workflow' ? 'pull_request' : 'push',
+                });
+            }
+            continue;
+        }
+        return { kind: 'error', message: `unknown gha-runtime-audit option: ${flag}` };
+    }
+    if (workflows.length === 0) {
+        return {
+            kind: 'error',
+            message: 'gha-runtime-audit requires --pr-workflow or --push-workflow',
+        };
+    }
+    return {
+        kind: 'gha-runtime-audit',
+        workflows,
+        ...(repository === undefined ? {} : { repository }),
+        ...(branch === undefined ? {} : { branch }),
+    };
+}

package/dist/cli/parse.d.mts

@@ -1,3 +1,4 @@
+import { type ParsedGhaRuntimeAudit } from './parse-gha-runtime-audit.mts';
 export type ParsedCli = {
     kind: 'help';
 } | {
@@ -12,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,3 +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')
@@ -9,6 +17,15 @@ export function parseCli(argv) {
         return parseRunnerPortPolicy(rest);
     if (command === 'with-host-lock')
         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\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";
+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,6 +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-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
@@ -21,6 +29,20 @@ with-host-lock
   [--failure-diagnostics <absolute-script>]
   [--on-acquire-timeout fail|run-unlocked]
   -- <command> [args...]
+
+gha-runtime-audit
+  [--repository owner/name]   Default GITHUB_REPOSITORY
+  [--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/gha-runtime-audit/audit.d.mts

@@ -0,0 +1,3 @@
+import { type GhApiExecutor, type RuntimeAuditResult } from './model.mts';
+import { type RuntimeAuditOptions } from './scope.mts';
+export declare function auditCiJobRuntime(execute: GhApiExecutor, options: RuntimeAuditOptions): Promise<RuntimeAuditResult>;

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

@@ -0,0 +1,106 @@
+import { parseArray, parseObject, parseRun, parseSample, parseWorkflow, } from './model.mjs';
+import { buildRuntimeResults } from './results.mjs';
+import { isRunInScope, isSelectedWorkflow, matchingWorkflowFilter, resolveRuntimeAuditOptions, } from './scope.mjs';
+async function discoverWorkflows(execute, options) {
+    const selected = [];
+    for (let page = 1;; page += 1) {
+        const response = parseObject(await execute({
+            endpoint: `/repos/${options.repository}/actions/workflows?per_page=100&page=${page}`,
+            jq: '{workflows: [.workflows[] | {id, name, state}]}',
+        }), 'workflows response must be an object');
+        const pageWorkflows = parseArray(response['workflows'], 'workflows must be an array');
+        for (const value of pageWorkflows) {
+            const workflow = parseWorkflow(value);
+            if (isSelectedWorkflow(workflow, options.workflows))
+                selected.push(workflow);
+        }
+        if (pageWorkflows.length < 100)
+            break;
+    }
+    return selected.toSorted((a, b) => a.name.localeCompare(b.name) || a.id - b.id);
+}
+function runsQuery(filter, branch) {
+    if (filter.event === 'push')
+        return `event=push&branch=${encodeURIComponent(branch)}`;
+    return 'event=pull_request';
+}
+async function recentRuns(execute, workflow, options) {
+    const selected = [];
+    const filter = matchingWorkflowFilter(workflow.name, options.workflows);
+    /* v8 ignore next */
+    if (!filter)
+        return selected;
+    const query = runsQuery(filter, options.branch);
+    for (let page = 1;; page += 1) {
+        const response = parseObject(await execute({
+            endpoint: `/repos/${options.repository}/actions/workflows/${workflow.id}/runs?${query}&status=completed&per_page=100&page=${page}`,
+            jq: '{workflow_runs: [.workflow_runs[] | {id, name, event, conclusion, created_at, html_url, head_branch, pull_requests: [(.pull_requests // [])[] | {base: {ref: .base.ref}}]}]}',
+        }), 'workflow runs response must be an object');
+        const pageRuns = parseArray(response['workflow_runs'], 'workflow_runs must be an array');
+        const inScope = [];
+        for (const value of pageRuns) {
+            const run = parseRun(value);
+            if (isRunInScope(run, filter, options.branch))
+                inScope.push(run);
+        }
+        inScope.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || b.id - a.id);
+        for (const run of inScope) {
+            if (selected.length === options.recentCompletedRunHorizon)
+                break;
+            selected.push(run);
+        }
+        if (selected.length === options.recentCompletedRunHorizon || pageRuns.length < 100)
+            break;
+    }
+    return selected;
+}
+async function collectRunSamples(execute, options, run, samplesByKey) {
+    for (let page = 1;; page += 1) {
+        const response = parseObject(await execute({
+            endpoint: `/repos/${options.repository}/actions/runs/${run.id}/jobs?filter=latest&per_page=100&page=${page}`,
+            jq: '{jobs: [.jobs[] | {id, name, started_at, completed_at, conclusion, html_url}]}',
+        }), `jobs response for run ${run.id} must be an object`);
+        const jobs = parseArray(response['jobs'], `jobs for run ${run.id} must be an array`);
+        for (const value of jobs) {
+            const parsed = parseSample(value, run);
+            if (!parsed)
+                continue;
+            const key = `${run.name} / ${parsed.name}`;
+            const entry = samplesByKey.get(key) ?? {
+                workflow: run.name,
+                job: parsed.name,
+                samples: [],
+            };
+            if (entry.samples.length < options.sampleLimit)
+                entry.samples.push(parsed.sample);
+            samplesByKey.set(key, entry);
+        }
+        if (jobs.length < 100)
+            break;
+    }
+}
+export async function auditCiJobRuntime(execute, options) {
+    const resolved = resolveRuntimeAuditOptions(options);
+    const samplesByKey = new Map();
+    const seenRunIds = new Set();
+    for (const workflow of await discoverWorkflows(execute, resolved)) {
+        for (const run of await recentRuns(execute, workflow, resolved)) {
+            if (seenRunIds.has(run.id))
+                continue;
+            seenRunIds.add(run.id);
+            await collectRunSamples(execute, resolved, run, samplesByKey);
+        }
+    }
+    const results = buildRuntimeResults(samplesByKey, resolved);
+    return {
+        scope: {
+            repository: resolved.repository,
+            sampleLimit: resolved.sampleLimit,
+            recentCompletedRunHorizon: resolved.recentCompletedRunHorizon,
+            medianThresholdSeconds: resolved.medianThresholdSeconds,
+            hardCeilingSeconds: resolved.hardCeilingSeconds,
+            branch: resolved.branch,
+        },
+        ...results,
+    };
+}

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

@@ -0,0 +1,5 @@
+export { auditCiJobRuntime } from './audit.mts';
+export { violationOrder } from './results.mts';
+export type { GhApiExecutor, GhApiRequest, RuntimeAuditResult, RuntimeJobResult, RuntimeSample, RuntimeViolationReason, } from './model.mts';
+export { parseWorkflowNameMatch } from './scope.mts';
+export type { RuntimeAuditOptions, RuntimeAuditWorkflowFilter } from './scope.mts';

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

@@ -0,0 +1,3 @@
+export { auditCiJobRuntime } from './audit.mjs';
+export { violationOrder } from './results.mjs';
+export { parseWorkflowNameMatch } from './scope.mjs';

package/dist/gha-runtime-audit/index.test-helpers.d.mts

@@ -0,0 +1,14 @@
+import type { GhApiExecutor } from './model.mts';
+import type { RuntimeAuditOptions } from './scope.mts';
+export type FixtureJob = {
+    id: number;
+    name: string;
+    started_at: string;
+    completed_at: string;
+    conclusion: 'success' | 'failure';
+    html_url: string;
+};
+export declare const exampleAuditOptions: Omit<RuntimeAuditOptions, 'repository'>;
+export declare function makeJob(runId: number, name: string, seconds: number, queueMinutes?: number, conclusion?: FixtureJob['conclusion']): FixtureJob;
+export declare function makeExecutor(runs: unknown[], jobsByRun: Readonly<Record<number, FixtureJob[]>>): GhApiExecutor;
+export declare function makeRun(id: number, name: string, event: 'pull_request' | 'push', branch?: string, conclusion?: string, createdAt?: string, headBranch?: string | null): unknown;