vouchington-tooling 0.0.14 → 0.0.15

package/README.md

@@ -79,6 +79,7 @@ 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'
 ```
 
 The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their

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>;

package/dist/coverage-transport/lib.mjs

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DEFAULT_COVERAGE_MANIFEST_FILENAME, DEFAULT_MAX_BODY_BYTES, assertCoverageManifestFilename, } from './constants.mjs';
+import { readTransportControl, } from './control.mjs';
+import { fetchGet, fetchPut, logTransport } from './http.mjs';
+import { downloadVitestBlobBundles, packVitestBlobBundle } from './vitest-blob-transport.mjs';
+export { DEFAULT_COVERAGE_MANIFEST_FILENAME } from './constants.mjs';
+export async function cmdUpload(controlPath, suite, options) {
+    const control = readTransportControl(controlPath, options.expectedIdentity);
+    if (control.mode === 'fallback-only') {
+        logTransport(options, `[coverage-transport] S3 unavailable for ${suite}; artifact fallback required`);
+        return { coverage: false, blob: false };
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const manifestFilename = options.coverageManifestFilename ?? DEFAULT_COVERAGE_MANIFEST_FILENAME;
+    assertCoverageManifestFilename(manifestFilename);
+    const coverageUrls = control.coverage[suite];
+    const lcovPath = join(cwd, 'coverage', 'lcov.info');
+    const manifestPath = join(cwd, 'coverage', manifestFilename);
+    const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const lcov = coverageUrls && existsSync(lcovPath) && existsSync(manifestPath)
+        ? await readFile(lcovPath)
+        : null;
+    const manifest = lcov === null ? null : await readFile(manifestPath);
+    const lcovStored = coverageUrls &&
+        lcov !== null &&
+        manifest !== null &&
+        lcov.byteLength <= maxBytes &&
+        manifest.byteLength <= maxBytes
+        ? await fetchPut(coverageUrls.lcovPut, lcov, options)
+        : false;
+    const coverage = lcovStored && coverageUrls && manifest !== null && manifest.byteLength <= maxBytes
+        ? await fetchPut(coverageUrls.manifestPut, manifest, options)
+        : false;
+    if (coverageUrls && existsSync(lcovPath) && existsSync(manifestPath)) {
+        logTransport(options, coverage
+            ? `[coverage-transport] Uploaded coverage pair for ${suite}`
+            : `[coverage-transport] Coverage pair upload failed for ${suite}`);
+    }
+    const blobUrls = control.blobs[suite];
+    const blobData = blobUrls
+        ? packVitestBlobBundle(cwd, suite, options.expectedIdentity, options)
+        : null;
+    const blob = Boolean(blobUrls && blobData && (await fetchPut(blobUrls.put, blobData, options)));
+    if (blob)
+        logTransport(options, `[coverage-transport] Uploaded vitest blob for ${suite}`);
+    else if (blobUrls && blobData) {
+        logTransport(options, `[coverage-transport] Vitest blob upload failed for ${suite}`);
+    }
+    return { coverage, blob };
+}
+export async function cmdDownloadCoverage(controlPath, destinationRoot, options) {
+    const control = readTransportControl(controlPath, options.expectedIdentity);
+    if (control.mode === 'fallback-only') {
+        logTransport(options, '[coverage-transport] S3 unavailable; artifact fallback required');
+        return;
+    }
+    const manifestFilename = options.coverageManifestFilename ?? DEFAULT_COVERAGE_MANIFEST_FILENAME;
+    assertCoverageManifestFilename(manifestFilename);
+    await Promise.all(Object.entries(control.coverage).map(async ([suite, urls]) => {
+        const [lcov, manifest] = await Promise.all([
+            fetchGet(urls.lcovGet, options),
+            fetchGet(urls.manifestGet, options),
+        ]);
+        if (!lcov || !manifest) {
+            logTransport(options, `[coverage-transport] Skipped incomplete coverage pair for ${suite}`);
+            return;
+        }
+        const destination = join(destinationRoot, `coverage-${suite}`);
+        mkdirSync(destination, { recursive: true });
+        writeFileSync(join(destination, 'lcov.info'), lcov);
+        writeFileSync(join(destination, manifestFilename), manifest, { mode: 0o600 });
+        logTransport(options, `[coverage-transport] Downloaded coverage pair for ${suite}`);
+    }));
+}
+export async function cmdDownloadVitestBlobs(controlPath, destinationRoot, options) {
+    const control = readTransportControl(controlPath, options.expectedIdentity);
+    if (control.mode === 'fallback-only') {
+        logTransport(options, '[coverage-transport] S3 unavailable; artifact fallback required');
+        return;
+    }
+    await downloadVitestBlobBundles(control.blobs, destinationRoot, options);
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Transport exhaustion guards for a coverage pair and a Vitest blob, plus the
+ * `$GITHUB_OUTPUT` writer producers use when the upload exit code is not the blob signal.
+ */
+export type StepOutcome = 'success' | 'failure' | 'cancelled' | 'skipped';
+/**
+ * CLI argv values arrive as plain strings (or `undefined` when a positional arg was omitted); this
+ * narrows to `StepOutcome` so a caller can validate a step-outcome argument without an unchecked
+ * `as` cast.
+ */
+export declare function isStepOutcome(value: string | undefined): value is StepOutcome;
+export declare function assertCoverageTransportOutcome(suite: string, primary: StepOutcome, artifactAttempt1: StepOutcome, artifactAttempt2: StepOutcome, emit?: (line: string) => void): boolean;
+export type BlobPrimaryState = 'true' | 'false' | 'skipped';
+export declare function isBlobPrimaryState(value: string | undefined): value is BlobPrimaryState;
+/**
+ * Sibling to `assertCoverageTransportOutcome` for the Vitest blob. `true`/`false` are the S3
+ * upload step's `blob` output; `skipped` means that step never ran. GitHub fallback is always
+ * attempted when enabled — workflows must not gate it on `blob != 'true'`.
+ */
+export declare function assertCoverageTransportBlobOutcome(suite: string, primaryPersisted: BlobPrimaryState, artifactAttempt1: StepOutcome, artifactAttempt2: StepOutcome, emit?: (line: string) => void): boolean;
+export type AppendOutput = (path: string, data: string) => void;
+/**
+ * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. GitHub-fallback blob upload
+ * must always be attempted when enabled; do not gate it on this signal. The upload subcommand's
+ * exit code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
+ */
+export declare function writeUploadOutcomeOutput(outcome: {
+    readonly blob: boolean;
+}, githubOutputPath: string | undefined, appendOutput?: AppendOutput): void;

package/dist/coverage-transport/outcome.mjs

@@ -0,0 +1,70 @@
+import { appendFileSync } from 'node:fs';
+const STEP_OUTCOMES = new Set([
+    'success',
+    'failure',
+    'cancelled',
+    'skipped',
+]);
+/**
+ * CLI argv values arrive as plain strings (or `undefined` when a positional arg was omitted); this
+ * narrows to `StepOutcome` so a caller can validate a step-outcome argument without an unchecked
+ * `as` cast.
+ */
+export function isStepOutcome(value) {
+    return value !== undefined && STEP_OUTCOMES.has(value);
+}
+export function assertCoverageTransportOutcome(suite, primary, artifactAttempt1, artifactAttempt2, emit = (line) => process.stderr.write(`${line}\n`)) {
+    const primarySucceeded = primary === 'success';
+    const artifactSucceeded = artifactAttempt1 === 'success' || artifactAttempt2 === 'success';
+    if (primarySucceeded && artifactSucceeded)
+        return true;
+    if (primarySucceeded) {
+        emit(`::warning::Coverage persisted only to S3 for suite=${suite}; GitHub artifact fallback is degraded.`);
+        return true;
+    }
+    if (artifactSucceeded) {
+        emit(`::warning::Coverage persisted only to GitHub artifacts for suite=${suite}; S3 primary is degraded.`);
+        return true;
+    }
+    emit(`::error::COVERAGE_TRANSPORT_EXHAUSTED suite=${suite} Neither S3 nor GitHub artifacts persisted the coverage pair.`);
+    return false;
+}
+const BLOB_PRIMARY_STATES = new Set([
+    'true',
+    'false',
+    'skipped',
+]);
+export function isBlobPrimaryState(value) {
+    return value !== undefined && BLOB_PRIMARY_STATES.has(value);
+}
+/**
+ * Sibling to `assertCoverageTransportOutcome` for the Vitest blob. `true`/`false` are the S3
+ * upload step's `blob` output; `skipped` means that step never ran. GitHub fallback is always
+ * attempted when enabled — workflows must not gate it on `blob != 'true'`.
+ */
+export function assertCoverageTransportBlobOutcome(suite, primaryPersisted, artifactAttempt1, artifactAttempt2, emit = (line) => process.stderr.write(`${line}\n`)) {
+    const artifactSucceeded = artifactAttempt1 === 'success' || artifactAttempt2 === 'success';
+    if (primaryPersisted === 'true') {
+        if (!artifactSucceeded) {
+            emit(`::warning::Vitest blob persisted only to S3 for suite=${suite}; GitHub artifact fallback is degraded.`);
+        }
+        return true;
+    }
+    if (artifactSucceeded) {
+        if (primaryPersisted === 'false') {
+            emit(`::warning::Vitest blob persisted only to GitHub artifacts for suite=${suite}; S3 primary is degraded.`);
+        }
+        return true;
+    }
+    emit(`::error::COVERAGE_TRANSPORT_BLOB_EXHAUSTED suite=${suite} Neither S3 nor GitHub artifacts persisted the vitest blob.`);
+    return false;
+}
+/**
+ * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. GitHub-fallback blob upload
+ * must always be attempted when enabled; do not gate it on this signal. The upload subcommand's
+ * exit code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
+ */
+export function writeUploadOutcomeOutput(outcome, githubOutputPath, appendOutput = appendFileSync) {
+    if (githubOutputPath)
+        appendOutput(githubOutputPath, `blob=${String(outcome.blob)}\n`);
+}

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

@@ -0,0 +1,22 @@
+import type { PresignedTransportControl } from './control.mts';
+export interface PresignIdentity {
+    readonly repository: string;
+    readonly revision: string;
+    readonly runId: string;
+    readonly controlAttempt: number;
+}
+export interface ObjectSigner {
+    signPut(key: string, ttlSeconds: number): Promise<string>;
+    signGet(key: string, ttlSeconds: number): Promise<string>;
+}
+export interface MintPresignedControlOptions {
+    readonly ttlSeconds?: number;
+    readonly now?: () => Date;
+    readonly manifestFilename?: string;
+}
+export declare function transportObjectKeys(repository: string, runId: string, controlAttempt: number, suite: string, manifestFilename?: string): {
+    readonly lcov: string;
+    readonly manifest: string;
+    readonly blob: string;
+};
+export declare function mintPresignedControl(identity: PresignIdentity, coverageSuites: readonly string[], blobSuites: readonly string[], signer: ObjectSigner, options?: MintPresignedControlOptions): Promise<PresignedTransportControl>;

package/dist/coverage-transport/presign.mjs

@@ -0,0 +1,51 @@
+import { assertCoverageManifestFilename, DEFAULT_COVERAGE_MANIFEST_FILENAME } from './constants.mjs';
+const DEFAULT_PRESIGN_TTL_SECONDS = 14_400;
+export function transportObjectKeys(repository, runId, controlAttempt, suite, manifestFilename = DEFAULT_COVERAGE_MANIFEST_FILENAME) {
+    assertCoverageManifestFilename(manifestFilename);
+    if (repository.includes('..') ||
+        !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) ||
+        !/^[1-9][0-9]*$/.test(runId) ||
+        !Number.isSafeInteger(controlAttempt) ||
+        controlAttempt < 1 ||
+        !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(suite)) {
+        throw new Error('Coverage transport key identity is invalid');
+    }
+    const prefix = `coverage-transport/${repository}/${runId}/${controlAttempt}`;
+    return {
+        lcov: `${prefix}/coverage/${suite}/lcov.info`,
+        manifest: `${prefix}/coverage/${suite}/${manifestFilename}`,
+        blob: `${prefix}/blobs/${suite}.tar.gz`,
+    };
+}
+export async function mintPresignedControl(identity, coverageSuites, blobSuites, signer, options = {}) {
+    const ttlSeconds = options.ttlSeconds ?? DEFAULT_PRESIGN_TTL_SECONDS;
+    const expiresAt = new Date((options.now?.() ?? new Date()).getTime() + ttlSeconds * 1000);
+    const manifestFilename = options.manifestFilename ?? DEFAULT_COVERAGE_MANIFEST_FILENAME;
+    const control = {
+        version: 1,
+        mode: 'presigned',
+        repository: identity.repository,
+        revision: identity.revision,
+        run: { id: identity.runId, controlAttempt: identity.controlAttempt },
+        expiresAt: expiresAt.toISOString(),
+        coverage: {},
+        blobs: {},
+    };
+    for (const suite of coverageSuites) {
+        const keys = transportObjectKeys(identity.repository, identity.runId, identity.controlAttempt, suite, manifestFilename);
+        control.coverage[suite] = {
+            lcovPut: await signer.signPut(keys.lcov, ttlSeconds),
+            lcovGet: await signer.signGet(keys.lcov, ttlSeconds),
+            manifestPut: await signer.signPut(keys.manifest, ttlSeconds),
+            manifestGet: await signer.signGet(keys.manifest, ttlSeconds),
+        };
+    }
+    for (const suite of blobSuites) {
+        const key = transportObjectKeys(identity.repository, identity.runId, identity.controlAttempt, suite, manifestFilename).blob;
+        control.blobs[suite] = {
+            put: await signer.signPut(key, ttlSeconds),
+            get: await signer.signGet(key, ttlSeconds),
+        };
+    }
+    return control;
+}

package/dist/coverage-transport/vitest-blob-transport.d.mts

@@ -0,0 +1,5 @@
+import type { ExpectedTransportIdentity, PresignedBlobUrls, RequestOptions } from './control.mts';
+export declare function packVitestBlobBundle(cwd: string, suite: string, identity: ExpectedTransportIdentity, options: RequestOptions): Buffer | null;
+export declare function tarVerboseMemberSize(line: string): number;
+export declare function assertTarMemberSizes(verboseLines: readonly string[], maxMemberBytes?: number): void;
+export declare function downloadVitestBlobBundles(blobs: Readonly<Record<string, PresignedBlobUrls>>, destinationRoot: string, options: RequestOptions): Promise<void>;

package/dist/coverage-transport/vitest-blob-transport.mjs

@@ -0,0 +1,129 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fetchGet, logTransport, redactTransportLog } from './http.mjs';
+import { inspectVitestBlobBundle, VITEST_BLOB_MANIFEST_FILENAME, VITEST_SUITE_PATTERN, vitestBlobBundlePaths, writeVitestBlobManifest, } from '../vitest-blob-manifest/index.mjs';
+function archiveWorkspace(suite) {
+    assertVitestSuite(suite);
+    const root = mkdtempSync(join(tmpdir(), `ct-blob-${suite}-`));
+    chmodSync(root, 0o700);
+    return { root, archive: join(root, 'bundle.tar.gz') };
+}
+function assertVitestSuite(suite) {
+    if (!VITEST_SUITE_PATTERN.test(suite))
+        throw new Error('Invalid Vitest suite');
+}
+export function packVitestBlobBundle(cwd, suite, identity, options) {
+    const directory = join(cwd, '.vitest-reports');
+    const { root, archive } = archiveWorkspace(suite);
+    try {
+        writeVitestBlobManifest(directory, {
+            suite,
+            repository: identity.repository,
+            revision: identity.revision,
+            runId: identity.runId,
+            runAttempt: identity.currentAttempt,
+        });
+        const paths = vitestBlobBundlePaths(directory, suite);
+        const limit = options.maxMemberBytes ?? MAX_VITEST_BLOB_MEMBER_BYTES;
+        if (paths.some((path) => statSync(path).size > limit)) {
+            throw new Error('Vitest blob member exceeds size limit');
+        }
+        const names = paths.map((path) => basename(path));
+        execFileSync('tar', ['czf', archive, '-C', directory, ...names], {
+            stdio: ['ignore', 'ignore', 'inherit'],
+        });
+        return readFileSync(archive);
+    }
+    catch (error) {
+        logTransport(options, `[coverage-transport] vitest blob pack failed: ${redactTransportLog(error)}`);
+        return null;
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+export function tarVerboseMemberSize(line) {
+    const match = line.match(/\s(\d+)\s+\d{4}-\d{2}-\d{2}(?:\s|$)/) ??
+        line.match(/\s(\d+)\s+[A-Z][a-z]{2}\s+\d{1,2}\s/);
+    const size = match === null ? Number.NaN : Number(match[1]);
+    if (!Number.isSafeInteger(size) || size < 0) {
+        throw new Error('Vitest blob archive listing is malformed');
+    }
+    return size;
+}
+const MAX_VITEST_BLOB_MEMBER_BYTES = 32 * 1024 * 1024;
+export function assertTarMemberSizes(verboseLines, maxMemberBytes = MAX_VITEST_BLOB_MEMBER_BYTES) {
+    if (verboseLines.some((line) => tarVerboseMemberSize(line) > maxMemberBytes)) {
+        throw new Error('Vitest blob archive exceeds the member size limit');
+    }
+}
+function validateArchive(archive, suite, maxMemberBytes) {
+    const entries = execFileSync('tar', ['tzf', archive], { encoding: 'utf8' })
+        .split('\n')
+        .filter(Boolean);
+    const expected = [VITEST_BLOB_MANIFEST_FILENAME, `${suite}.json`].toSorted();
+    if (entries.length !== 2 || entries.toSorted().join('\0') !== expected.join('\0')) {
+        throw new Error(`Vitest blob archive for ${suite} has unexpected entries`);
+    }
+    const verbose = execFileSync('tar', ['tvzf', archive], { encoding: 'utf8' })
+        .split('\n')
+        .filter(Boolean);
+    if (verbose.length !== 2 || verbose.some((line) => !line.startsWith('-'))) {
+        throw new Error(`Vitest blob archive for ${suite} must contain regular files`);
+    }
+    assertTarMemberSizes(verbose, maxMemberBytes);
+    return entries;
+}
+function extractValidatedBundle(archive, destinationRoot, suite, maxMemberBytes) {
+    const entries = validateArchive(archive, suite, maxMemberBytes);
+    mkdirSync(destinationRoot, { recursive: true });
+    const temporary = mkdtempSync(join(destinationRoot, `.vitest-blob-${suite}-`));
+    try {
+        execFileSync('tar', ['xzf', archive, '-C', temporary, ...entries], {
+            stdio: ['ignore', 'ignore', 'inherit'],
+        });
+        for (const entry of entries)
+            chmodSync(join(temporary, entry), 0o600);
+        inspectVitestBlobBundle(temporary);
+        const destination = join(destinationRoot, `vitest-blob-${suite}`);
+        rmSync(destination, { recursive: true, force: true });
+        renameSync(temporary, destination);
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+    }
+}
+export async function downloadVitestBlobBundles(blobs, destinationRoot, options) {
+    mkdirSync(destinationRoot, { recursive: true });
+    await Promise.all(Object.entries(blobs).map(async ([suite, urls]) => {
+        assertVitestSuite(suite);
+        const data = await fetchGet(urls.get, options);
+        if (!data) {
+            logTransport(options, `[coverage-transport] No vitest blob available for ${suite}`);
+            return;
+        }
+        const { root, archive } = archiveWorkspace(suite);
+        const invalidMarker = join(destinationRoot, `.invalid-${suite}`);
+        try {
+            writeFileSync(archive, data, { flag: 'wx', mode: 0o600 });
+            extractValidatedBundle(archive, destinationRoot, suite, options.maxMemberBytes ?? MAX_VITEST_BLOB_MEMBER_BYTES);
+            rmSync(invalidMarker, { recursive: true, force: true });
+            logTransport(options, `[coverage-transport] Downloaded vitest blob for ${suite}`);
+        }
+        catch (error) {
+            try {
+                rmSync(invalidMarker, { force: true });
+                writeFileSync(invalidMarker, 'invalid archive\n', { flag: 'wx', mode: 0o600 });
+            }
+            catch {
+                // The original archive failure is more actionable than a diagnostic-write failure.
+            }
+            throw error;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }));
+}

package/dist/index.d.mts

@@ -34,3 +34,5 @@ export type { AstGrepRuleInvocation, RunAstGrepRuleOptions } from './ast-grep-ru
 export { bodyOnlyReviewFallback, indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mts';
 export type { CommentableIndex, CommentableLine, LineKind, PayloadRequirement, ReviewComment, ReviewFile, ReviewSide, SanitizedReview, } from './gha-review-payload/index.mts';
 export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mts';
+export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mts';
+export type { ExpectedTransportIdentity, ObjectSigner, PresignIdentity, TransportControl, } from './coverage-transport/index.mts';

package/dist/index.mjs

@@ -20,3 +20,4 @@ export { MissingResponseBodyError, readResponseBody, readResponseBodyAsBuffer, R
 export { parseAstGrepRuleArgs, runAstGrepRule } from './ast-grep-rule/index.mjs';
 export { bodyOnlyReviewFallback, indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mjs';
 export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mjs';
+export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mjs';

package/dist/transient-retry/decision-evaluator.d.mts

@@ -14,5 +14,7 @@ export type DecisionResult = {
 };
 export interface EvaluateRulesOptions {
     afterRuleEvaluated?: (context: RetryContext, rule: RetryRule) => Promise<void> | void;
+    /** Defaults to `no-match`. Use `dispatch` when unmatched work should leave the retry engine. */
+    unmatchedDecision?: 'no-match' | 'dispatch';
 }
 export declare function decide(context: RetryContext, rules: readonly RetryRule[], options?: EvaluateRulesOptions): Promise<DecisionResult>;

package/dist/transient-retry/decision-evaluator.mjs

@@ -46,11 +46,17 @@ export async function decide(context, rules, options = {}) {
         if (rule.decision !== undefined && rule.decision !== 'rerun') {
             return { decision: rule.decision, matchedRule: rule.id };
         }
+        if (rule.retryTarget === undefined) {
+            return { decision: 'rerun', matchedRule: rule.id, targetName: '' };
+        }
         const resolved = resolveTargetName(rule.retryTarget, context);
         if (resolved.targetName === undefined) {
             return { decision: 'no-match', matchedRule: rule.id, reason: resolved.reason };
         }
         return { decision: 'rerun', matchedRule: rule.id, targetName: resolved.targetName };
     }
+    if (options.unmatchedDecision === 'dispatch') {
+        return { decision: 'dispatch', matchedRule: '' };
+    }
     return { decision: 'no-match', matchedRule: '', reason: 'no-rule' };
 }

package/dist/transient-retry/types.d.mts

@@ -9,7 +9,7 @@ export interface RetryContext {
     /** Targets that the provider resolved for this run. */
     targetNames?: ReadonlySet<string>;
 }
-export type RetryDecision = 'rerun' | 'ignore' | 'fresh-plan' | 'reap-lock';
+export type RetryDecision = 'rerun' | 'ignore' | 'fresh-plan' | 'reap-lock' | 'dispatch';
 export type RetryTarget = {
     targetName: string;
     targetFamily?: never;
@@ -30,8 +30,8 @@ interface RetryRuleBase {
 }
 export type RetryRule = (RetryRuleBase & {
     decision?: 'rerun';
-    /** Reruns must name a resolved target; full-provider reruns stay private. */
-    retryTarget: RetryTarget;
+    /** When omitted, the match is an untargeted provider-level rerun. */
+    retryTarget?: RetryTarget;
 }) | (RetryRuleBase & {
     decision: Exclude<RetryDecision, 'rerun'>;
     retryTarget?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -130,6 +130,11 @@
       "import": "./dist/http-link-pagination/index.mjs",
       "default": "./dist/http-link-pagination/index.mjs"
     },
+    "./coverage-transport": {
+      "types": "./dist/coverage-transport/index.d.mts",
+      "import": "./dist/coverage-transport/index.mjs",
+      "default": "./dist/coverage-transport/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {