vouchington-tooling 0.0.14 → 0.0.16

package/README.md

@@ -28,6 +28,11 @@ vouchington gha-artifacts-cleanup run --run-id 123 --keep-pattern 'plan-*' --del
 vouchington http-origin --field cdn_origin https://images.example.com
 vouchington vitest-blob-manifest <suite> [reports-directory]
 vouchington pnpm-install --runner-lifecycle persistent --install-scripts true
+vouchington check-cache-size /tmp/cache 1048576 node-modules
+vouchington make-shard-matrix 4
+vouchington load-runner-env
+vouchington clean-workspace
+vouchington install-github-release --repo lycheeverse/lychee --version 0.24.2 --asset 'lychee-{platform}.tar.gz' --bin lychee
 ```
 
 Host-lock environment:
@@ -79,6 +84,14 @@ import { readResponseBody } from 'vouchington-tooling/http-body'
 import { runAstGrepRule } from 'vouchington-tooling/ast-grep-rule'
 import { parseReviewPayload, remapReviewComments } from 'vouchington-tooling/gha-review-payload'
 import { nextPageUrlFromLinkHeader } from 'vouchington-tooling/http-link-pagination'
+import { cmdUpload, mintPresignedControl } from 'vouchington-tooling/coverage-transport'
+import { pruneDeployedRuntimeDeps } from 'vouchington-tooling/pnpm-deploy'
+import { parseDockerfileRuntimeImages } from 'vouchington-tooling/dockerfile-parse'
+import { checkSccComplexity } from 'vouchington-tooling/scc-complexity'
+import { runCiLocal } from 'vouchington-tooling/ci-local'
+import { rateLimitDelay } from 'vouchington-tooling/gha-rate-limit'
+import { parseCheckpoint } from 'vouchington-tooling/gha-pr-checkpoint'
+import { checkWorkspaceGatesPolicy } from 'vouchington-tooling/workspace-gates'
 ```
 
 The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their

package/dist/ci-local/index.d.mts

@@ -0,0 +1,5 @@
+import type { CiLocalTarget, RunCiLocalOptions } from './types.mts';
+export type { CiLocalCommand, CiLocalSpawn, CiLocalSpawnOptions, CiLocalSpawnResult, CiLocalTarget, LineWriter, ParsedCiLocalArgs, RunCiLocalOptions, } from './types.mts';
+export { parseCiLocalArgs } from './parse.mts';
+export declare function assertWorkflowCommandDrift(targets: Record<string, CiLocalTarget>, rootDir?: string): void;
+export declare function runCiLocal({ args, targets, cwd, spawn, stdout, stderr, usage, }: RunCiLocalOptions): number;

package/dist/ci-local/index.mjs

@@ -0,0 +1,79 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseCiLocalArgs } from './parse.mjs';
+export { parseCiLocalArgs } from './parse.mjs';
+const DEFAULT_USAGE = 'Usage: ci-local [--list] | <target> [--dry-run]';
+export function assertWorkflowCommandDrift(targets, rootDir = process.cwd()) {
+    for (const target of Object.values(targets)) {
+        for (const command of target.commands) {
+            if (!command.source)
+                continue;
+            const { workflow: sourceWorkflow, contains } = command.source;
+            const workflow = readFileSync(path.join(rootDir, sourceWorkflow), 'utf8');
+            const expectedCommands = Array.isArray(contains) ? contains : [contains];
+            if (expectedCommands.every((expectedCommand) => workflow.includes(expectedCommand)))
+                continue;
+            throw new Error(`ci-local drift: ${command.description} command was not found in ${command.source.workflow}`);
+        }
+    }
+}
+function defaultSpawn(command, args, options) {
+    const result = spawnSync(command, [...args], options);
+    return { error: result.error, status: result.status };
+}
+function writeLine(stream, line) {
+    stream.write(`${line}\n`);
+}
+function runCommand(command, dryRun, cwd, spawn, stdout) {
+    const envPreview = Object.keys(command.env ?? {})
+        .filter((key) => command.env?.[key] !== undefined)
+        .join(',');
+    const renderedCommand = envPreview
+        ? `env ${envPreview} bash -c ${JSON.stringify(command.command)}`
+        : command.command;
+    writeLine(stdout, `\n$ ${renderedCommand}`);
+    if (dryRun)
+        return 0;
+    const result = spawn('/bin/bash', ['-c', command.command], {
+        cwd,
+        env: {
+            ...process.env,
+            ...command.env,
+        },
+        stdio: 'inherit',
+    });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}
+export function runCiLocal({ args, targets, cwd = process.cwd(), spawn = defaultSpawn, stdout = process.stdout, stderr = process.stderr, usage = DEFAULT_USAGE, }) {
+    try {
+        const targetNames = Object.keys(targets);
+        const parsed = parseCiLocalArgs(args, targetNames);
+        if (parsed.help) {
+            writeLine(stdout, usage);
+            return 0;
+        }
+        if (parsed.list || !parsed.target) {
+            for (const [name, target] of Object.entries(targets)) {
+                writeLine(stdout, `${name} - ${target.description}`);
+            }
+            return 0;
+        }
+        const target = targets[parsed.target];
+        assertWorkflowCommandDrift({ [parsed.target]: target }, cwd);
+        writeLine(stdout, `${parsed.target}: ${target.description}`);
+        for (const command of target.commands) {
+            const status = runCommand(command, parsed.dryRun, cwd, spawn, stdout);
+            if (status !== 0)
+                return status;
+        }
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr.write(`${message}\n`);
+        return 1;
+    }
+}

package/dist/ci-local/parse.d.mts

@@ -0,0 +1,3 @@
+import * as nodeUtil from 'node:util';
+import type { ParsedCiLocalArgs } from './types.mts';
+export declare function parseCiLocalArgs(args: readonly string[], targetNames: readonly string[], parseArgs?: typeof nodeUtil.parseArgs): ParsedCiLocalArgs;

package/dist/ci-local/parse.mjs

@@ -0,0 +1,43 @@
+import * as nodeUtil from 'node:util';
+export function parseCiLocalArgs(args, targetNames, parseArgs = nodeUtil.parseArgs) {
+    const helpArgs = args.filter((arg) => arg === '-h' || arg === '--help');
+    const help = helpArgs.length === 1 && args.length === 1;
+    if (helpArgs.length > 0 && !help)
+        throw new Error('help must be used by itself');
+    if (args.filter((arg) => arg === '--dry-run').length > 1 ||
+        args.filter((arg) => arg === '--list').length > 1) {
+        throw new Error('Options may only be specified once.');
+    }
+    let dryRun;
+    let list;
+    let positionals;
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {
+                'dry-run': { type: 'boolean' },
+                help: { short: 'h', type: 'boolean' },
+                list: { type: 'boolean' },
+            },
+            strict: true,
+            allowPositionals: true,
+        });
+        dryRun = parsed.values['dry-run'] ?? false;
+        list = parsed.values.list ?? false;
+        positionals = parsed.positionals;
+    }
+    catch (error) {
+        throw new Error(error instanceof Error ? error.message : String(error), { cause: error });
+    }
+    if (positionals.length > 1)
+        throw new Error('Only one target may be specified.');
+    if (list && (dryRun || positionals.length > 0))
+        throw new Error('--list must be used by itself.');
+    const target = positionals[0];
+    if (dryRun && !target)
+        throw new Error('--dry-run requires a target.');
+    if (target && !targetNames.includes(target)) {
+        throw new Error(`Unknown target "${target}". Valid targets: ${targetNames.join(', ')}`);
+    }
+    return target ? { dryRun, help, list, target } : { dryRun, help, list };
+}

package/dist/ci-local/types.d.mts

@@ -0,0 +1,41 @@
+export interface CiLocalCommand {
+    command: string;
+    description: string;
+    env?: Record<string, string | undefined>;
+    source?: {
+        workflow: string;
+        contains: string | string[];
+    };
+}
+export interface CiLocalTarget {
+    description: string;
+    commands: CiLocalCommand[];
+}
+export interface ParsedCiLocalArgs {
+    dryRun: boolean;
+    help: boolean;
+    list: boolean;
+    target?: string;
+}
+export interface CiLocalSpawnResult {
+    error?: Error | undefined;
+    status: number | null;
+}
+export interface CiLocalSpawnOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio: 'inherit';
+}
+export type CiLocalSpawn = (command: string, args: readonly string[], options: CiLocalSpawnOptions) => CiLocalSpawnResult;
+export interface LineWriter {
+    write(chunk: string): unknown;
+}
+export interface RunCiLocalOptions {
+    args: readonly string[];
+    targets: Record<string, CiLocalTarget>;
+    cwd?: string;
+    spawn?: CiLocalSpawn;
+    stdout?: LineWriter;
+    stderr?: LineWriter;
+    usage?: string;
+}

package/dist/ci-local/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/cli/index.mjs

@@ -34,6 +34,11 @@ const SCRIPT_PATHS = {
         path: 'scripts/gha/diagnose-port-collision.sh',
     },
     'prepare-trivy-db': { command: 'bash', path: 'scripts/gha/prepare-trivy-db.sh' },
+    'check-cache-size': { command: 'bash', path: 'scripts/gha/check-cache-size.sh' },
+    'make-shard-matrix': { command: 'bash', path: 'scripts/gha/make-shard-matrix.sh' },
+    'load-runner-env': { command: 'bash', path: 'scripts/gha/load-runner-env.sh' },
+    'clean-workspace': { command: 'bash', path: 'scripts/gha/clean-workspace.sh' },
+    'install-github-release': { command: 'bash', path: 'scripts/gha/install-github-release.sh' },
 };
 export function runCli(argv = process.argv) {
     const parsed = parseCli(argv);

package/dist/cli/parse.d.mts

@@ -29,5 +29,5 @@ export type ParsedCli = {
     field: string;
     value: string;
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
-export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db';
+export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -8,6 +8,11 @@ const SCRIPT_COMMANDS = new Set([
     'allocate-browser-safe-ports',
     'diagnose-port-collision',
     'prepare-trivy-db',
+    'check-cache-size',
+    'make-shard-matrix',
+    'load-runner-env',
+    'clean-workspace',
+    'install-github-release',
 ]);
 export function parseCli(argv) {
     const args = argv.slice(2);

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  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  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\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]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\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  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\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  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\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]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -15,6 +15,11 @@ Commands:
   http-origin                   Validate an optional HTTP(S) origin
   vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file
   pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast
+  check-cache-size              Measure a path and decide whether to save a GHA cache
+  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix
+  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards
+  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate
+  install-github-release        Download a checksum-verified GitHub Release binary
 
 Options:
   -h, --help       Show this help
@@ -52,6 +57,11 @@ gha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--dele
 http-origin [--field NAME] [value]
 vitest-blob-manifest <suite> [reports-directory]
 pnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false
+check-cache-size <path> <max-bytes> <label>
+make-shard-matrix <total>
+load-runner-env
+clean-workspace
+install-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/coverage-transport/constants.d.mts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_COVERAGE_MANIFEST_FILENAME = "coverage-manifest.json";
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+export declare function assertCoverageManifestFilename(filename: string): void;

package/dist/coverage-transport/constants.mjs

@@ -0,0 +1,11 @@
+export const DEFAULT_COVERAGE_MANIFEST_FILENAME = 'coverage-manifest.json';
+export const DEFAULT_MAX_BODY_BYTES = 32 * 1024 * 1024;
+const MANIFEST_FILENAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.json$/;
+export function assertCoverageManifestFilename(filename) {
+    if (filename.includes('/') ||
+        filename.includes('\\') ||
+        filename.includes('..') ||
+        !MANIFEST_FILENAME_PATTERN.test(filename)) {
+        throw new Error('Coverage manifest filename is invalid');
+    }
+}

package/dist/coverage-transport/control.d.mts

@@ -0,0 +1,47 @@
+export interface PresignedCoverageUrls {
+    lcovPut: string;
+    lcovGet: string;
+    manifestPut: string;
+    manifestGet: string;
+}
+export interface PresignedBlobUrls {
+    put: string;
+    get: string;
+}
+interface TransportControlBase {
+    readonly version: 1;
+    readonly repository: string;
+    readonly revision: string;
+    readonly run: {
+        readonly id: string;
+        readonly controlAttempt: number;
+    };
+}
+export interface PresignedTransportControl extends TransportControlBase {
+    readonly mode: 'presigned';
+    readonly expiresAt: string;
+    readonly coverage: Record<string, PresignedCoverageUrls>;
+    readonly blobs: Record<string, PresignedBlobUrls>;
+}
+export interface FallbackOnlyTransportControl extends TransportControlBase {
+    readonly mode: 'fallback-only';
+    readonly reason: string;
+}
+export type TransportControl = PresignedTransportControl | FallbackOnlyTransportControl;
+export interface ExpectedTransportIdentity {
+    readonly repository: string;
+    readonly revision: string;
+    readonly runId: string;
+    readonly currentAttempt: number;
+}
+export interface RequestOptions {
+    readonly retryDelayMs?: number;
+    readonly timeoutMs?: number;
+    readonly maxBodyBytes?: number;
+    readonly maxMemberBytes?: number;
+    readonly log?: (line: string) => void;
+}
+export declare function parseTransportControl(raw: unknown): TransportControl;
+export declare function writeTransportControl(path: string, control: TransportControl): void;
+export declare function readTransportControl(path: string, expected?: ExpectedTransportIdentity): TransportControl;
+export {};

package/dist/coverage-transport/control.mjs

@@ -0,0 +1,112 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { VITEST_SUITE_PATTERN } from '../vitest-blob-manifest/index.mjs';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function assertUrlMap(raw, fields, label) {
+    if (!isRecord(raw))
+        throw new Error(`${label} URL map must be an object`);
+    for (const [suite, urls] of Object.entries(raw)) {
+        if (!VITEST_SUITE_PATTERN.test(suite) ||
+            !isRecord(urls) ||
+            Object.keys(urls).toSorted().join('\0') !== fields.toSorted().join('\0')) {
+            throw new Error(`${label} URL map has an invalid entry`);
+        }
+        for (const field of fields) {
+            const value = urls[field];
+            if (typeof value !== 'string' || !URL.canParse(value) || !/^https?:/i.test(value)) {
+                throw new Error(`${label} URL map has an invalid URL`);
+            }
+        }
+    }
+}
+export function parseTransportControl(raw) {
+    if (!isRecord(raw) || raw.version !== 1 || !isRecord(raw.run)) {
+        throw new Error('Coverage transport control has an unsupported schema');
+    }
+    if (typeof raw.repository !== 'string' ||
+        !raw.repository ||
+        typeof raw.revision !== 'string' ||
+        !/^[0-9a-f]{40}$/.test(raw.revision) ||
+        typeof raw.run.id !== 'string' ||
+        !/^[1-9][0-9]*$/.test(raw.run.id) ||
+        !positiveInteger(raw.run.controlAttempt)) {
+        throw new Error('Coverage transport control has invalid identity fields');
+    }
+    if (Object.keys(raw.run).toSorted().join('\0') !== ['controlAttempt', 'id'].join('\0')) {
+        throw new Error('Coverage transport control run schema is invalid');
+    }
+    if (raw.mode === 'fallback-only') {
+        const fallbackKeys = ['mode', 'reason', 'repository', 'revision', 'run', 'version'];
+        if (Object.keys(raw).toSorted().join('\0') !== fallbackKeys.toSorted().join('\0') ||
+            typeof raw.reason !== 'string' ||
+            !raw.reason) {
+            throw new Error('Fallback-only coverage transport control is invalid');
+        }
+        return raw;
+    }
+    const presignedKeys = [
+        'blobs',
+        'coverage',
+        'expiresAt',
+        'mode',
+        'repository',
+        'revision',
+        'run',
+        'version',
+    ];
+    if (raw.mode !== 'presigned' ||
+        Object.keys(raw).toSorted().join('\0') !== presignedKeys.toSorted().join('\0') ||
+        typeof raw.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(raw.expiresAt))) {
+        throw new Error('Presigned coverage transport control is invalid');
+    }
+    assertUrlMap(raw.coverage, ['lcovGet', 'lcovPut', 'manifestGet', 'manifestPut'], 'Coverage');
+    assertUrlMap(raw.blobs, ['get', 'put'], 'Blob');
+    return raw;
+}
+export function writeTransportControl(path, control) {
+    const validated = parseTransportControl(control);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(validated, null, 2)}\n`, {
+            flag: 'wx',
+            mode: 0o600,
+        });
+        chmodSync(temporary, 0o600);
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // The write/rename failure is the actionable error.
+        }
+        throw error;
+    }
+}
+export function readTransportControl(path, expected) {
+    if ((statSync(path).mode & 0o777) !== 0o600) {
+        throw new Error('Coverage transport control file must have mode 0600');
+    }
+    const control = parseTransportControl(JSON.parse(readFileSync(path, 'utf8')));
+    if (expected && !positiveInteger(expected.currentAttempt)) {
+        throw new Error('Coverage transport control identity does not match this run');
+    }
+    if (expected &&
+        (control.repository !== expected.repository ||
+            control.revision !== expected.revision ||
+            control.run.id !== expected.runId ||
+            control.run.controlAttempt > expected.currentAttempt)) {
+        throw new Error('Coverage transport control identity does not match this run');
+    }
+    if (control.mode === 'presigned' && Date.parse(control.expiresAt) <= Date.now()) {
+        throw new Error('Coverage transport control has expired');
+    }
+    return control;
+}

package/dist/coverage-transport/http.d.mts

@@ -0,0 +1,6 @@
+import type { RequestOptions } from './control.mts';
+export declare function redactTransportLog(value: unknown): string;
+export declare function coveragePresignFailureLog(error: unknown): string;
+export declare function logTransport(options: RequestOptions, line: string): void;
+export declare function fetchPut(url: string, body: Buffer, options?: RequestOptions): Promise<boolean>;
+export declare function fetchGet(url: string, options?: RequestOptions): Promise<Buffer | null>;

package/dist/coverage-transport/http.mjs

@@ -0,0 +1,99 @@
+import { DEFAULT_MAX_BODY_BYTES } from './constants.mjs';
+const FETCH_TIMEOUT_MS = 30_000;
+const FETCH_ATTEMPTS = 2;
+const DEFAULT_RETRY_DELAY_MS = 1000;
+function formatTransportError(value, seen) {
+    if (typeof value === 'object' && value !== null) {
+        if (seen.has(value))
+            return '[circular]';
+        seen.add(value);
+    }
+    if (value instanceof Error) {
+        const cause = value.cause !== undefined ? `; cause: ${formatTransportError(value.cause, seen)}` : '';
+        return `${value.name}: ${value.message}${cause}`;
+    }
+    return String(value);
+}
+export function redactTransportLog(value) {
+    return formatTransportError(value, new WeakSet()).replaceAll(/https?:\/\/[^\s]+/gi, '[redacted-url]');
+}
+export function coveragePresignFailureLog(error) {
+    return `[coverage-transport] presign failed: ${redactTransportLog(error)}; artifact fallback required`;
+}
+export function logTransport(options, line) {
+    ;
+    (options.log ?? ((message) => process.stderr.write(`${message}\n`)))(redactTransportLog(line));
+}
+async function delay(milliseconds) {
+    if (milliseconds <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function cancelBody(response) {
+    await response.body?.cancel();
+}
+async function readLimitedBody(response, maxBytes) {
+    if (response.body === null)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return Buffer.concat(chunks);
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new Error('[coverage-transport] GET body exceeds size limit');
+        }
+        chunks.push(value);
+    }
+}
+async function request(method, url, body, options) {
+    for (let attempt = 1; attempt <= FETCH_ATTEMPTS; attempt += 1) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? FETCH_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, {
+                method,
+                ...(body ? { body: new Uint8Array(body) } : {}),
+                signal: controller.signal,
+            });
+            // A missing presigned object is terminal. Let fetchGet yield null or fetchPut yield false
+            // without retrying the same URL or emitting a misleading transport-error diagnostic.
+            if (response.ok || response.status === 404) {
+                const payload = method === 'GET' && response.ok
+                    ? await readLimitedBody(response, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES)
+                    : undefined;
+                if (payload === undefined)
+                    await cancelBody(response);
+                return { ok: response.ok, status: response.status, body: payload };
+            }
+            await cancelBody(response);
+            logTransport(options, `[coverage-transport] ${method} failed: HTTP ${response.status}`);
+        }
+        catch (error) {
+            logTransport(options, `[coverage-transport] ${method} error: ${redactTransportLog(error)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (attempt < FETCH_ATTEMPTS) {
+            await delay(options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS);
+        }
+    }
+    return null;
+}
+export async function fetchPut(url, body, options = {}) {
+    const response = await request('PUT', url, body, options);
+    return response?.ok === true;
+}
+export async function fetchGet(url, options = {}) {
+    const response = await request('GET', url, undefined, options);
+    if (response?.status === 404)
+        return null;
+    if (!response?.ok)
+        throw new Error('[coverage-transport] GET exhausted');
+    return response.body;
+}

package/dist/coverage-transport/index.d.mts

@@ -0,0 +1,6 @@
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME, cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, } from './lib.mts';
+export { parseTransportControl, readTransportControl, writeTransportControl, type ExpectedTransportIdentity, type FallbackOnlyTransportControl, type PresignedBlobUrls, type PresignedCoverageUrls, type PresignedTransportControl, type RequestOptions, type TransportControl, } from './control.mts';
+export { coveragePresignFailureLog, fetchGet, fetchPut, logTransport, redactTransportLog, } from './http.mts';
+export { assertCoverageTransportBlobOutcome, assertCoverageTransportOutcome, isBlobPrimaryState, isStepOutcome, writeUploadOutcomeOutput, type AppendOutput, type BlobPrimaryState, type StepOutcome, } from './outcome.mts';
+export { downloadVitestBlobBundles, packVitestBlobBundle } from './vitest-blob-transport.mts';
+export { mintPresignedControl, transportObjectKeys, type MintPresignedControlOptions, type ObjectSigner, type PresignIdentity, } from './presign.mts';

package/dist/coverage-transport/index.mjs

@@ -0,0 +1,6 @@
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME, cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, } from './lib.mjs';
+export { parseTransportControl, readTransportControl, writeTransportControl, } from './control.mjs';
+export { coveragePresignFailureLog, fetchGet, fetchPut, logTransport, redactTransportLog, } from './http.mjs';
+export { assertCoverageTransportBlobOutcome, assertCoverageTransportOutcome, isBlobPrimaryState, isStepOutcome, writeUploadOutcomeOutput, } from './outcome.mjs';
+export { downloadVitestBlobBundles, packVitestBlobBundle } from './vitest-blob-transport.mjs';
+export { mintPresignedControl, transportObjectKeys, } from './presign.mjs';

package/dist/coverage-transport/lib.d.mts

@@ -0,0 +1,17 @@
+import { type ExpectedTransportIdentity, type RequestOptions } from './control.mts';
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME } from './constants.mts';
+interface UploadOptions extends RequestOptions {
+    readonly cwd?: string;
+    readonly expectedIdentity: ExpectedTransportIdentity;
+    readonly coverageManifestFilename?: string;
+}
+interface DownloadOptions extends RequestOptions {
+    readonly expectedIdentity: ExpectedTransportIdentity;
+    readonly coverageManifestFilename?: string;
+}
+export declare function cmdUpload(controlPath: string, suite: string, options: UploadOptions): Promise<{
+    coverage: boolean;
+    blob: boolean;
+}>;
+export declare function cmdDownloadCoverage(controlPath: string, destinationRoot: string, options: DownloadOptions): Promise<void>;
+export declare function cmdDownloadVitestBlobs(controlPath: string, destinationRoot: string, options: DownloadOptions): Promise<void>;