vouchington-tooling 0.0.9 → 0.0.10

package/README.md

@@ -22,6 +22,10 @@ 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 diagnose-port-collision --ports "2200 2216"
+vouchington prepare-trivy-db
+vouchington gha-artifacts-cleanup run --run-id 123 --keep-pattern 'plan-*' --delete-pattern 'coverage-*'
+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
 ```
@@ -48,5 +52,16 @@ import { splitSqlStatements, stripSqlComments } from 'vouchington-tooling/sql-sc
 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'
+import {
+  buildSharedContext,
+  installFakeGit,
+  runNamedChecks,
+} from 'vouchington-tooling/shared-context'
+import {
+  decodeSelectedFiles,
+  writeSelectedFilesOutput,
+} from 'vouchington-tooling/gha-selected-files'
+import { createArtifactClassifier, runCleanup } from 'vouchington-tooling/gha-artifacts-cleanup'
+import { validateOptionalHttpOrigin } from 'vouchington-tooling/http-origin'
+import { boundPendingLine, splitCompleteLines } from 'vouchington-tooling/process-line-buffer'
 ```

package/dist/cli/commands/gha-artifacts-cleanup.d.mts

@@ -0,0 +1,6 @@
+import type { ParsedGhaArtifactsCleanup } from '../parse-gha-artifacts-cleanup.mts';
+export declare function loadCleanupPatterns(parsed: ParsedGhaArtifactsCleanup): {
+    keepPatterns: string[];
+    deletePatterns: string[];
+};
+export declare function runGhaArtifactsCleanup(parsed: ParsedGhaArtifactsCleanup, env?: Record<string, string | undefined>): Promise<number>;

package/dist/cli/commands/gha-artifacts-cleanup.mjs

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { createArtifactClassifier, parseArtifactPatternsJson, runCleanup, sweepCleanup, } from '../../gha-artifacts-cleanup/index.mjs';
+function usage() {
+    return [
+        'Usage: vouchington gha-artifacts-cleanup run --run-id <id> [pattern options]',
+        '       vouchington gha-artifacts-cleanup sweep --older-than-hours <n> [pattern options]',
+        '',
+        'Pattern options: --keep-pattern <glob> --delete-pattern <glob> --patterns-file <json>',
+        'Requires GITHUB_TOKEN or GH_TOKEN and GITHUB_REPOSITORY (owner/repo) in the env.',
+    ].join('\n');
+}
+function logSummary(subcommand, summary) {
+    const mb = (summary.bytesFreed / (1024 * 1024)).toFixed(1);
+    console.log(`[gha-artifacts-cleanup] ${subcommand}: deleted ${summary.deletedCount} artifact(s), freed ~${mb} MB`);
+}
+export function loadCleanupPatterns(parsed) {
+    const fromFile = parsed.patternsFile === undefined
+        ? { keepPatterns: [], deletePatterns: [] }
+        : parseArtifactPatternsJson(JSON.parse(readFileSync(parsed.patternsFile, 'utf8')));
+    return {
+        keepPatterns: [...fromFile.keepPatterns, ...parsed.keepPatterns],
+        deletePatterns: [...fromFile.deletePatterns, ...parsed.deletePatterns],
+    };
+}
+export async function runGhaArtifactsCleanup(parsed, env = process.env) {
+    const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
+    const repo = env.GITHUB_REPOSITORY;
+    if (!token || !repo) {
+        console.error('[gha-artifacts-cleanup] missing GITHUB_TOKEN/GH_TOKEN or GITHUB_REPOSITORY');
+        return 0;
+    }
+    const patterns = loadCleanupPatterns(parsed);
+    const { classify } = createArtifactClassifier(patterns);
+    if (parsed.subcommand === 'run') {
+        const runId = parsed.runId;
+        if (runId === undefined) {
+            console.error(usage());
+            return 2;
+        }
+        logSummary('run', await runCleanup({ repo, token, classify, runId }));
+        return 0;
+    }
+    const olderThanHours = parsed.olderThanHours;
+    if (olderThanHours === undefined) {
+        console.error(usage());
+        return 2;
+    }
+    logSummary('sweep', await sweepCleanup({ repo, token, classify, olderThanHours }));
+    return 0;
+}

package/dist/cli/commands/http-origin.d.mts

@@ -0,0 +1,2 @@
+export declare function formatCliError(error: unknown): string;
+export declare function runHttpOrigin(field: string, value: string): number;

package/dist/cli/commands/http-origin.mjs

@@ -0,0 +1,14 @@
+import { validateOptionalHttpOrigin } from '../../http-origin/index.mjs';
+export function formatCliError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function runHttpOrigin(field, value) {
+    try {
+        validateOptionalHttpOrigin(value, field);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${formatCliError(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -3,7 +3,9 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { readPackageVersion } from '../package-version.mjs';
+import { runGhaArtifactsCleanup } from './commands/gha-artifacts-cleanup.mjs';
 import { runGhaRuntimeAudit } from './commands/gha-runtime-audit.mjs';
+import { runHttpOrigin } from './commands/http-origin.mjs';
 import { runPnpmInstallCli } from './commands/pnpm-install.mjs';
 import { runRunnerPortPolicy } from './commands/runner-port-policy.mjs';
 import { runScript } from './commands/spawn-script.mjs';
@@ -27,6 +29,11 @@ const SCRIPT_PATHS = {
         command: 'python3',
         path: 'scripts/allocate-browser-safe-ports.py',
     },
+    'diagnose-port-collision': {
+        command: 'bash',
+        path: 'scripts/gha/diagnose-port-collision.sh',
+    },
+    'prepare-trivy-db': { command: 'bash', path: 'scripts/gha/prepare-trivy-db.sh' },
 };
 export function runCli(argv = process.argv) {
     const parsed = parseCli(argv);
@@ -55,6 +62,10 @@ export function runCli(argv = process.argv) {
             return runPnpmInstallCli(parsed.args);
         case 'vitest-blob-manifest':
             return runVitestBlobManifestCommand(parsed.args);
+        case 'http-origin':
+            return runHttpOrigin(parsed.field, parsed.value);
+        case 'gha-artifacts-cleanup':
+            return runGhaArtifactsCleanup(parsed);
     }
 }
 function readInstalledVersion() {

package/dist/cli/parse-gha-artifacts-cleanup.d.mts

@@ -0,0 +1,15 @@
+export type ParsedGhaArtifactsCleanup = {
+    kind: 'gha-artifacts-cleanup';
+    subcommand: 'run' | 'sweep';
+    runId?: string;
+    olderThanHours?: number;
+    keepPatterns: string[];
+    deletePatterns: string[];
+    patternsFile?: string;
+};
+export declare function parseGhaArtifactsCleanup(args: readonly string[]): ParsedGhaArtifactsCleanup | {
+    kind: 'help';
+} | {
+    kind: 'error';
+    message: string;
+};

package/dist/cli/parse-gha-artifacts-cleanup.mjs

@@ -0,0 +1,74 @@
+export function parseGhaArtifactsCleanup(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === '--help' || subcommand === '-h' || subcommand === undefined) {
+        return subcommand === undefined
+            ? { kind: 'error', message: 'gha-artifacts-cleanup requires run or sweep' }
+            : { kind: 'help' };
+    }
+    if (subcommand !== 'run' && subcommand !== 'sweep') {
+        return { kind: 'error', message: `unknown gha-artifacts-cleanup subcommand: ${subcommand}` };
+    }
+    let runId;
+    let olderThanHours;
+    let patternsFile;
+    const keepPatterns = [];
+    const deletePatterns = [];
+    for (let index = 0; index < rest.length; index += 1) {
+        const flag = rest[index];
+        if (flag === '--help' || flag === '-h')
+            return { kind: 'help' };
+        if (flag === '--run-id' || flag === '--older-than-hours' || flag === '--patterns-file') {
+            const value = rest[index + 1];
+            if (value === undefined)
+                return { kind: 'error', message: `${flag} requires a value` };
+            index += 1;
+            if (flag === '--run-id')
+                runId = value;
+            else if (flag === '--patterns-file')
+                patternsFile = value;
+            else {
+                const parsed = Number(value.trim());
+                if (!value.trim() || !Number.isFinite(parsed) || parsed < 0) {
+                    return { kind: 'error', message: '--older-than-hours must be a non-negative number' };
+                }
+                olderThanHours = parsed;
+            }
+            continue;
+        }
+        if (flag === '--keep-pattern' || flag === '--delete-pattern') {
+            const value = rest[index + 1];
+            if (value === undefined)
+                return { kind: 'error', message: `${flag} requires a value` };
+            index += 1;
+            if (flag === '--keep-pattern')
+                keepPatterns.push(value);
+            else
+                deletePatterns.push(value);
+            continue;
+        }
+        return { kind: 'error', message: `unknown gha-artifacts-cleanup option: ${flag}` };
+    }
+    if (subcommand === 'run') {
+        if (!runId)
+            return { kind: 'error', message: 'gha-artifacts-cleanup run requires --run-id' };
+        return {
+            kind: 'gha-artifacts-cleanup',
+            subcommand: 'run',
+            runId,
+            keepPatterns,
+            deletePatterns,
+            ...(patternsFile === undefined ? {} : { patternsFile }),
+        };
+    }
+    if (olderThanHours === undefined) {
+        return { kind: 'error', message: 'gha-artifacts-cleanup sweep requires --older-than-hours' };
+    }
+    return {
+        kind: 'gha-artifacts-cleanup',
+        subcommand: 'sweep',
+        olderThanHours,
+        keepPatterns,
+        deletePatterns,
+        ...(patternsFile === undefined ? {} : { patternsFile }),
+    };
+}

package/dist/cli/parse.d.mts

@@ -1,3 +1,4 @@
+import { type ParsedGhaArtifactsCleanup } from './parse-gha-artifacts-cleanup.mts';
 import { type ParsedGhaRuntimeAudit } from './parse-gha-runtime-audit.mts';
 export type ParsedCli = {
     kind: 'help';
@@ -23,6 +24,10 @@ export type ParsedCli = {
 } | {
     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';
+} | {
+    kind: 'http-origin';
+    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 declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -1,3 +1,4 @@
+import { parseGhaArtifactsCleanup, } from './parse-gha-artifacts-cleanup.mjs';
 import { parseGhaRuntimeAudit } from './parse-gha-runtime-audit.mjs';
 const SCRIPT_COMMANDS = new Set([
     'gha-output',
@@ -5,6 +6,8 @@ const SCRIPT_COMMANDS = new Set([
     'download-with-diagnostics',
     'host-pressure-diagnostics',
     'allocate-browser-safe-ports',
+    'diagnose-port-collision',
+    'prepare-trivy-db',
 ]);
 export function parseCli(argv) {
     const args = argv.slice(2);
@@ -23,6 +26,10 @@ export function parseCli(argv) {
         return { kind: 'pnpm-install', args: rest };
     if (command === 'vitest-blob-manifest')
         return { kind: 'vitest-blob-manifest', args: rest };
+    if (command === 'http-origin')
+        return parseHttpOrigin(rest);
+    if (command === 'gha-artifacts-cleanup')
+        return parseGhaArtifactsCleanup(rest);
     if (command !== undefined && SCRIPT_COMMANDS.has(command)) {
         return { kind: 'script', command: command, args: rest };
     }
@@ -62,3 +69,32 @@ function parseRunnerPortPolicy(args) {
         ...(reserved === undefined ? {} : { reserved }),
     };
 }
+function parseHttpOrigin(args) {
+    let field = 'origin';
+    const values = [];
+    let index = 0;
+    while (index < args.length) {
+        const flag = args[index];
+        index += 1;
+        if (flag === '--help' || flag === '-h')
+            return { kind: 'help' };
+        if (flag === '--field') {
+            const value = args[index];
+            if (value === undefined)
+                return { kind: 'error', message: '--field requires a name' };
+            field = value;
+            index += 1;
+            continue;
+        }
+        if (flag === '--') {
+            values.push(...args.slice(index));
+            break;
+        }
+        if (flag.startsWith('-'))
+            return { kind: 'error', message: `unknown http-origin option: ${flag}` };
+        values.push(flag);
+    }
+    if (values.length > 1)
+        return { kind: 'error', message: 'http-origin accepts at most one value' };
+    return { kind: 'http-origin', field, value: values[0] ?? '' };
+}

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  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 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 function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -9,6 +9,10 @@ Commands:
   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
+  diagnose-port-collision       Capture bounded localhost port diagnostics
+  prepare-trivy-db              Download the Trivy vulnerability database
+  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts
+  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
 
@@ -41,6 +45,11 @@ gha-needs-results [label]
 download-with-diagnostics <url> <destination> [-- curl-args...]
 host-pressure-diagnostics
 allocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]
+diagnose-port-collision [--ports "2200 2216"] [--output-dir PATH]
+prepare-trivy-db
+gha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]
+gha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]
+http-origin [--field NAME] [value]
 vitest-blob-manifest <suite> [reports-directory]
 pnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false
 `;

package/dist/gha-artifacts-cleanup/classify.d.mts

@@ -0,0 +1,14 @@
+export type ArtifactClassification = 'keep' | 'delete';
+export type ArtifactClassifier = {
+    classify: (name: string) => ArtifactClassification;
+    isExplicitlyClassified: (name: string) => boolean;
+};
+export type ArtifactPatterns = {
+    keepPatterns: readonly string[];
+    deletePatterns: readonly string[];
+};
+export declare function createArtifactClassifier(patterns: ArtifactPatterns): ArtifactClassifier;
+export declare function parseArtifactPatternsJson(value: unknown): {
+    keepPatterns: string[];
+    deletePatterns: string[];
+};

package/dist/gha-artifacts-cleanup/classify.mjs

@@ -0,0 +1,32 @@
+import picomatch from 'picomatch';
+function matcher(patterns) {
+    if (patterns.length === 0)
+        return () => false;
+    return picomatch([...patterns]);
+}
+export function createArtifactClassifier(patterns) {
+    const isKeep = matcher(patterns.keepPatterns);
+    const isDelete = matcher(patterns.deletePatterns);
+    return {
+        classify: (name) => (isKeep(name) ? 'keep' : 'delete'),
+        isExplicitlyClassified: (name) => isKeep(name) || isDelete(name),
+    };
+}
+export function parseArtifactPatternsJson(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('patterns file must be a JSON object with keep and delete arrays');
+    }
+    const record = value;
+    return {
+        keepPatterns: stringArray(record.keep, 'keep'),
+        deletePatterns: stringArray(record.delete, 'delete'),
+    };
+}
+function stringArray(value, field) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`patterns file ${field} must be an array of strings`);
+    }
+    return value;
+}

package/dist/gha-artifacts-cleanup/commands.d.mts

@@ -0,0 +1,23 @@
+import type { ArtifactClassification } from './classify.mts';
+import { deleteArtifact, getRunConclusion, listArtifactsPage, listRunArtifacts } from './github.mts';
+import { type DeletionSummary } from './plan.mts';
+export interface CleanupDeps {
+    listRunArtifacts: typeof listRunArtifacts;
+    listArtifactsPage: typeof listArtifactsPage;
+    getRunConclusion: typeof getRunConclusion;
+    deleteArtifact: typeof deleteArtifact;
+}
+export declare const defaultDeps: CleanupDeps;
+export type CleanupRequest = {
+    repo: string;
+    token: string;
+    classify: (name: string) => ArtifactClassification;
+    deps?: CleanupDeps;
+    log?: (message: string) => void;
+};
+export declare function runCleanup(request: CleanupRequest & {
+    runId: string;
+}): Promise<DeletionSummary>;
+export declare function sweepCleanup(request: CleanupRequest & {
+    olderThanHours: number;
+}): Promise<DeletionSummary>;

package/dist/gha-artifacts-cleanup/commands.mjs

@@ -0,0 +1,55 @@
+import { deleteArtifact, getRunConclusion, listArtifactsPage, listRunArtifacts, } from './github.mjs';
+import { isSweepCandidate, nextPagingState, planRunDeletions, planSweepDeletions, shouldStopPaging, summarize, } from './plan.mjs';
+export const defaultDeps = {
+    listRunArtifacts,
+    listArtifactsPage,
+    getRunConclusion,
+    deleteArtifact,
+};
+async function deleteAll(repo, token, artifacts, deps, log) {
+    const deleted = [];
+    for (const artifact of artifacts) {
+        const outcome = await deps.deleteArtifact(repo, token, artifact.id);
+        if (outcome === 'failed') {
+            log(`[gha-artifacts-cleanup] failed to delete ${artifact.name} (id ${artifact.id})`);
+            continue;
+        }
+        if (outcome === 'not-found')
+            continue;
+        deleted.push(artifact);
+    }
+    return summarize(deleted);
+}
+export async function runCleanup(request) {
+    const deps = request.deps ?? defaultDeps;
+    const log = request.log ?? console.error;
+    const artifacts = await deps.listRunArtifacts(request.repo, request.token, request.runId);
+    const toDelete = planRunDeletions(artifacts, request.classify);
+    return deleteAll(request.repo, request.token, toDelete, deps, log);
+}
+async function collectSweepCandidates(request, cutoffIso, deps) {
+    const candidates = [];
+    let state = { page: 1, consecutiveExpiredPages: 0 };
+    for (;;) {
+        const page = await deps.listArtifactsPage(request.repo, request.token, state.page);
+        const pageArtifacts = page ?? [];
+        if (page != null) {
+            candidates.push(...pageArtifacts.filter((artifact) => isSweepCandidate(artifact, cutoffIso, request.classify)));
+        }
+        if (page == null)
+            break;
+        state = nextPagingState(pageArtifacts, state);
+        if (shouldStopPaging(pageArtifacts, state))
+            break;
+    }
+    return candidates;
+}
+export async function sweepCleanup(request) {
+    const deps = request.deps ?? defaultDeps;
+    const log = request.log ?? console.error;
+    const cutoffIso = new Date(Date.now() - request.olderThanHours * 60 * 60 * 1000).toISOString();
+    const candidates = await collectSweepCandidates(request, cutoffIso, deps);
+    const cache = new Map();
+    const toDelete = await planSweepDeletions(candidates, (runId) => deps.getRunConclusion(request.repo, request.token, runId, cache));
+    return deleteAll(request.repo, request.token, toDelete, deps, log);
+}

package/dist/gha-artifacts-cleanup/github.d.mts

@@ -0,0 +1,16 @@
+export interface GithubArtifact {
+    id: number;
+    name: string;
+    size_in_bytes: number;
+    expired: boolean;
+    created_at: string;
+    workflow_run?: {
+        id: number;
+    };
+}
+export type DeleteOutcome = 'deleted' | 'not-found' | 'failed';
+export declare function githubGet(path: string, token: string, sleepFn?: (ms: number) => Promise<void>): Promise<Response>;
+export declare function deleteArtifact(repo: string, token: string, artifactId: number, sleepFn?: (ms: number) => Promise<void>): Promise<DeleteOutcome>;
+export declare function listRunArtifacts(repo: string, token: string, runId: string): Promise<GithubArtifact[]>;
+export declare function listArtifactsPage(repo: string, token: string, page: number): Promise<GithubArtifact[] | null>;
+export declare function getRunConclusion(repo: string, token: string, runId: number, cache: Map<number, string | null>): Promise<string | null>;

package/dist/gha-artifacts-cleanup/github.mjs

@@ -0,0 +1,100 @@
+const API_BASE = 'https://api.github.com';
+const API_VERSION = '2022-11-28';
+const MAX_RETRIES = 4;
+const PER_PAGE = 100;
+function authHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': API_VERSION,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function retryDelayMs(response, attempt) {
+    const retryAfter = Number(response?.headers.get('retry-after'));
+    if (Number.isFinite(retryAfter) && retryAfter > 0)
+        return retryAfter * 1000;
+    return Math.min(1000 * 2 ** attempt, 30_000);
+}
+export async function githubGet(path, token, sleepFn = sleep) {
+    for (let attempt = 0;; attempt += 1) {
+        let response;
+        try {
+            response = await fetch(`${API_BASE}${path}`, { headers: authHeaders(token) });
+        }
+        catch {
+            if (attempt === MAX_RETRIES)
+                return new Response(null, { status: 599 });
+            await sleepFn(retryDelayMs(null, attempt));
+            continue;
+        }
+        if (response.status !== 403 && response.status !== 429)
+            return response;
+        if (attempt === MAX_RETRIES)
+            return response;
+        await sleepFn(retryDelayMs(response, attempt));
+    }
+}
+export async function deleteArtifact(repo, token, artifactId, sleepFn = sleep) {
+    for (let attempt = 0;; attempt += 1) {
+        let response;
+        try {
+            response = await fetch(`${API_BASE}/repos/${repo}/actions/artifacts/${artifactId}`, {
+                method: 'DELETE',
+                headers: authHeaders(token),
+            });
+        }
+        catch {
+            if (attempt === MAX_RETRIES)
+                return 'failed';
+            await sleepFn(retryDelayMs(null, attempt));
+            continue;
+        }
+        if (response.status === 404)
+            return 'not-found';
+        if (response.ok)
+            return 'deleted';
+        if (response.status !== 403 && response.status !== 429)
+            return 'failed';
+        if (attempt === MAX_RETRIES)
+            return 'failed';
+        await sleepFn(retryDelayMs(response, attempt));
+    }
+}
+export async function listRunArtifacts(repo, token, runId) {
+    const artifacts = [];
+    for (let page = 1;; page += 1) {
+        const path = `/repos/${repo}/actions/runs/${runId}/artifacts?per_page=${PER_PAGE}&page=${page}`;
+        const response = await githubGet(path, token);
+        if (!response.ok)
+            break;
+        const body = (await response.json());
+        artifacts.push(...body.artifacts);
+        if (body.artifacts.length < PER_PAGE)
+            break;
+    }
+    return artifacts;
+}
+export async function listArtifactsPage(repo, token, page) {
+    const path = `/repos/${repo}/actions/artifacts?per_page=${PER_PAGE}&page=${page}`;
+    const response = await githubGet(path, token);
+    if (!response.ok)
+        return null;
+    const body = (await response.json());
+    return body.artifacts;
+}
+export async function getRunConclusion(repo, token, runId, cache) {
+    if (cache.has(runId))
+        return cache.get(runId);
+    const response = await githubGet(`/repos/${repo}/actions/runs/${runId}`, token);
+    if (!response.ok) {
+        cache.set(runId, null);
+        return null;
+    }
+    const body = (await response.json());
+    const conclusion = body.status === 'completed' ? body.conclusion : null;
+    cache.set(runId, conclusion);
+    return conclusion;
+}

package/dist/gha-artifacts-cleanup/index.d.mts

@@ -0,0 +1,8 @@
+export { createArtifactClassifier, parseArtifactPatternsJson } from './classify.mts';
+export type { ArtifactClassification, ArtifactClassifier, ArtifactPatterns } from './classify.mts';
+export { defaultDeps, runCleanup, sweepCleanup } from './commands.mts';
+export type { CleanupDeps, CleanupRequest } from './commands.mts';
+export { deleteArtifact, getRunConclusion, githubGet, listArtifactsPage, listRunArtifacts, } from './github.mts';
+export type { DeleteOutcome, GithubArtifact } from './github.mts';
+export { isSweepCandidate, nextPagingState, planRunDeletions, planSweepDeletions, shouldStopPaging, summarize, } from './plan.mts';
+export type { ArtifactLike, DeletionSummary, PagingState } from './plan.mts';

package/dist/gha-artifacts-cleanup/index.mjs

@@ -0,0 +1,4 @@
+export { createArtifactClassifier, parseArtifactPatternsJson } from './classify.mjs';
+export { defaultDeps, runCleanup, sweepCleanup } from './commands.mjs';
+export { deleteArtifact, getRunConclusion, githubGet, listArtifactsPage, listRunArtifacts, } from './github.mjs';
+export { isSweepCandidate, nextPagingState, planRunDeletions, planSweepDeletions, shouldStopPaging, summarize, } from './plan.mjs';

package/dist/gha-artifacts-cleanup/plan.d.mts

@@ -0,0 +1,17 @@
+import type { ArtifactClassification } from './classify.mts';
+import type { GithubArtifact as ArtifactLike } from './github.mts';
+export type { ArtifactLike };
+export interface DeletionSummary {
+    deletedCount: number;
+    bytesFreed: number;
+}
+export declare function summarize(deleted: Array<Pick<ArtifactLike, 'size_in_bytes'>>): DeletionSummary;
+export declare function planRunDeletions(artifacts: ArtifactLike[], classify: (name: string) => ArtifactClassification): ArtifactLike[];
+export declare function isSweepCandidate(artifact: ArtifactLike, cutoffIso: string, classify: (name: string) => ArtifactClassification): boolean;
+export interface PagingState {
+    page: number;
+    consecutiveExpiredPages: number;
+}
+export declare function shouldStopPaging(pageArtifacts: ArtifactLike[], state: PagingState): boolean;
+export declare function nextPagingState(pageArtifacts: ArtifactLike[], state: PagingState): PagingState;
+export declare function planSweepDeletions(candidates: ArtifactLike[], getConclusion: (runId: number) => Promise<string | null>): Promise<ArtifactLike[]>;

package/dist/gha-artifacts-cleanup/plan.mjs

@@ -0,0 +1,40 @@
+export function summarize(deleted) {
+    return {
+        deletedCount: deleted.length,
+        bytesFreed: deleted.reduce((total, artifact) => total + artifact.size_in_bytes, 0),
+    };
+}
+export function planRunDeletions(artifacts, classify) {
+    return artifacts.filter((artifact) => !artifact.expired && classify(artifact.name) === 'delete');
+}
+export function isSweepCandidate(artifact, cutoffIso, classify) {
+    return (!artifact.expired && artifact.created_at < cutoffIso && classify(artifact.name) === 'delete');
+}
+const MAX_CONSECUTIVE_EXPIRED_PAGES = 5;
+const MAX_PAGES = 150;
+export function shouldStopPaging(pageArtifacts, state) {
+    if (state.page >= MAX_PAGES)
+        return true;
+    if (pageArtifacts.length === 0)
+        return true;
+    return state.consecutiveExpiredPages >= MAX_CONSECUTIVE_EXPIRED_PAGES;
+}
+export function nextPagingState(pageArtifacts, state) {
+    const pageFullyExpired = pageArtifacts.every((artifact) => artifact.expired);
+    return {
+        page: state.page + 1,
+        consecutiveExpiredPages: pageFullyExpired ? state.consecutiveExpiredPages + 1 : 0,
+    };
+}
+export async function planSweepDeletions(candidates, getConclusion) {
+    const toDelete = [];
+    for (const artifact of candidates) {
+        const runId = artifact.workflow_run?.id;
+        if (runId == null)
+            continue;
+        const conclusion = await getConclusion(runId);
+        if (conclusion === 'success' || conclusion === 'cancelled')
+            toDelete.push(artifact);
+    }
+    return toDelete;
+}

package/dist/gha-selected-files/index.d.mts

@@ -0,0 +1,6 @@
+export declare function encodeSelectedFiles(files: readonly string[]): string;
+export declare const SELECTED_FILES_ENV_MAX_BYTES = 120000;
+export declare function selectedFilesExceedEnvBudget(files: readonly string[]): boolean;
+export declare function decodeSelectedFiles(raw: string | undefined | null): string[];
+export declare function formatMultilineOutput(key: string, value: string, createId?: () => string): string;
+export declare function writeSelectedFilesOutput(key: string, files: readonly string[], createId?: () => string): void;

package/dist/gha-selected-files/index.mjs

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+export function encodeSelectedFiles(files) {
+    return files.join('\n');
+}
+// Linux MAX_ARG_STRLEN is 131072. GitHub Actions interpolates selected-file
+// lists into a step env block, so the encoded list plus the variable prefix
+// must fit in one exec argument.
+export const SELECTED_FILES_ENV_MAX_BYTES = 120_000;
+export function selectedFilesExceedEnvBudget(files) {
+    return Buffer.byteLength(encodeSelectedFiles(files), 'utf8') > SELECTED_FILES_ENV_MAX_BYTES;
+}
+export function decodeSelectedFiles(raw) {
+    if (!raw)
+        return [];
+    return raw.split('\n').filter((file) => file.trim().length > 0);
+}
+export function formatMultilineOutput(key, value, createId = randomUUID) {
+    const delimiter = collisionFreeDelimiter(key, value, createId);
+    const body = value === '' ? '' : `${value}\n`;
+    return `${key}<<${delimiter}\n${body}${delimiter}\n`;
+}
+export function writeSelectedFilesOutput(key, files, createId = randomUUID) {
+    const target = process.env.GITHUB_OUTPUT;
+    if (target) {
+        appendFileSync(target, formatMultilineOutput(key, encodeSelectedFiles(files), createId));
+    }
+    console.log(`[select] ${key} (${files.length} file${files.length === 1 ? '' : 's'})`);
+}
+function collisionFreeDelimiter(key, value, createId) {
+    const prefix = key.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const candidate = `${prefix}_${createId().toUpperCase().replaceAll('-', '_')}`;
+        if (!value.includes(candidate))
+            return candidate;
+    }
+    throw new Error(`could not create a collision-free GitHub output delimiter for ${key} after 10 attempts`);
+}

package/dist/http-origin/index.d.mts

@@ -0,0 +1 @@
+export declare function validateOptionalHttpOrigin(value: string, fieldName?: string): void;

package/dist/http-origin/index.mjs

@@ -0,0 +1,23 @@
+export function validateOptionalHttpOrigin(value, fieldName = 'origin') {
+    if (!value)
+        return;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw invalidOriginError(fieldName);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.pathname !== '/' ||
+        url.search !== '' ||
+        url.hash !== '' ||
+        ![url.origin, `${url.origin}/`].includes(value)) {
+        throw invalidOriginError(fieldName);
+    }
+}
+function invalidOriginError(fieldName) {
+    return new Error(`${fieldName} must be empty or a pure HTTP(S) origin without credentials, path, query, or fragment`);
+}

package/dist/index.d.mts

@@ -9,5 +9,10 @@ export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManif
 export type { InspectedVitestBlobBundle, VitestBlobIdentity, VitestBlobManifest, } from './vitest-blob-manifest/index.mts';
 export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mts';
 export type { InstallOptions, Lifecycle } from './pnpm-install/index.mts';
-export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mts';
-export type { NamedCheck, SharedContext } from './shared-context/index.mts';
+export { buildContextFromTrackedFiles, buildSharedContext, clearFakeGitEnv, gitEnv, installFakeGit, runNamedChecks, setFakeGitTrackedFiles, } from './shared-context/index.mts';
+export type { FakeGitOptions, NamedCheck, SharedContext } from './shared-context/index.mts';
+export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECTED_FILES_ENV_MAX_BYTES, selectedFilesExceedEnvBudget, writeSelectedFilesOutput, } from './gha-selected-files/index.mts';
+export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions, runCleanup, sweepCleanup, } from './gha-artifacts-cleanup/index.mts';
+export type { ArtifactClassification, ArtifactClassifier, ArtifactPatterns, CleanupRequest, DeletionSummary, } from './gha-artifacts-cleanup/index.mts';
+export { validateOptionalHttpOrigin } from './http-origin/index.mts';
+export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/index.mts';

package/dist/index.mjs

@@ -4,4 +4,8 @@ export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, re
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mjs';
 export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManifest, serializeVitestBlobManifest, VITEST_BLOB_MANIFEST_FILENAME, VITEST_BLOB_MANIFEST_VERSION, vitestBlobBundlePaths, writeVitestBlobManifest, } from './vitest-blob-manifest/index.mjs';
 export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mjs';
-export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mjs';
+export { buildContextFromTrackedFiles, buildSharedContext, clearFakeGitEnv, gitEnv, installFakeGit, runNamedChecks, setFakeGitTrackedFiles, } from './shared-context/index.mjs';
+export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECTED_FILES_ENV_MAX_BYTES, selectedFilesExceedEnvBudget, writeSelectedFilesOutput, } from './gha-selected-files/index.mjs';
+export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions, runCleanup, sweepCleanup, } from './gha-artifacts-cleanup/index.mjs';
+export { validateOptionalHttpOrigin } from './http-origin/index.mjs';
+export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/index.mjs';

package/dist/process-line-buffer/index.d.mts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_TRUNCATED_LINE_MARKER = " [oversized line truncated] ";
+export declare const DEFAULT_MAX_PENDING_LINE_LENGTH: number;
+export declare function boundPendingLine(value: string, marker?: string, maxLength?: number): string;
+export declare function splitCompleteLines(value: string): {
+    complete: string[];
+    pending: string;
+};

package/dist/process-line-buffer/index.mjs

@@ -0,0 +1,28 @@
+export const DEFAULT_TRUNCATED_LINE_MARKER = ' [oversized line truncated] ';
+export const DEFAULT_MAX_PENDING_LINE_LENGTH = 64 * 1024;
+export function boundPendingLine(value, marker = DEFAULT_TRUNCATED_LINE_MARKER, maxLength = DEFAULT_MAX_PENDING_LINE_LENGTH) {
+    if (value.length <= maxLength)
+        return value;
+    if (marker.length >= maxLength)
+        return marker;
+    const retainedLength = maxLength - marker.length;
+    const headLength = Math.floor(retainedLength / 2);
+    const tailLength = retainedLength - headLength;
+    return value.slice(0, headLength) + marker + value.slice(-tailLength);
+}
+export function splitCompleteLines(value) {
+    const complete = [];
+    let start = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (character !== '\n' && character !== '\r')
+            continue;
+        if (character === '\r' && index === value.length - 1)
+            break;
+        if (character === '\r' && value[index + 1] === '\n')
+            index += 1;
+        complete.push(value.slice(start, index + 1));
+        start = index + 1;
+    }
+    return { complete, pending: value.slice(start) };
+}

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

@@ -8,4 +8,5 @@ export type FakeGitOptions = {
     trackedFiles?: readonly string[];
 };
 export declare function installFakeGit({ binDir, isInsideWorkTree, lsFilesExitCode, lsFilesStderr, pathPrefix, repoRoot, trackedFiles, }: FakeGitOptions): void;
+export declare function setFakeGitTrackedFiles(files: readonly string[]): void;
 export declare function clearFakeGitEnv(): void;

package/dist/shared-context/{fake-git.test-helpers.mjs → fake-git.mjs}

@@ -15,7 +15,10 @@ export function installFakeGit({ binDir, isInsideWorkTree = true, lsFilesExitCod
     process.env[FAKE_GIT_LS_FILES_STDERR] = lsFilesStderr;
     if (repoRoot !== undefined)
         process.env[FAKE_GIT_ROOT] = repoRoot;
-    process.env[FAKE_GIT_FILES] = [...trackedFiles].toSorted().join('\n');
+    setFakeGitTrackedFiles(trackedFiles);
+}
+export function setFakeGitTrackedFiles(files) {
+    process.env[FAKE_GIT_FILES] = [...files].toSorted().join('\n');
 }
 export function clearFakeGitEnv() {
     process.env.FAKE_GIT_INSIDE = 'false';

package/dist/shared-context/index.d.mts

@@ -1,3 +1,5 @@
+export { clearFakeGitEnv, installFakeGit, setFakeGitTrackedFiles } from './fake-git.mts';
+export type { FakeGitOptions } from './fake-git.mts';
 export declare function gitEnv(): NodeJS.ProcessEnv;
 export interface SharedContext {
     repoRoot: string;

package/dist/shared-context/index.mjs

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
+export { clearFakeGitEnv, installFakeGit, setFakeGitTrackedFiles } from './fake-git.mjs';
 export function gitEnv() {
     return Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -65,6 +65,26 @@
       "import": "./dist/shared-context/index.mjs",
       "default": "./dist/shared-context/index.mjs"
     },
+    "./gha-selected-files": {
+      "types": "./dist/gha-selected-files/index.d.mts",
+      "import": "./dist/gha-selected-files/index.mjs",
+      "default": "./dist/gha-selected-files/index.mjs"
+    },
+    "./gha-artifacts-cleanup": {
+      "types": "./dist/gha-artifacts-cleanup/index.d.mts",
+      "import": "./dist/gha-artifacts-cleanup/index.mjs",
+      "default": "./dist/gha-artifacts-cleanup/index.mjs"
+    },
+    "./http-origin": {
+      "types": "./dist/http-origin/index.d.mts",
+      "import": "./dist/http-origin/index.mjs",
+      "default": "./dist/http-origin/index.mjs"
+    },
+    "./process-line-buffer": {
+      "types": "./dist/process-line-buffer/index.d.mts",
+      "import": "./dist/process-line-buffer/index.mjs",
+      "default": "./dist/process-line-buffer/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -75,6 +95,12 @@
     "prepack": "pnpm run build",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
+  "dependencies": {
+    "picomatch": "4.0.5"
+  },
+  "devDependencies": {
+    "@types/picomatch": "^4.0.3"
+  },
   "optionalDependencies": {
     "@libpg-query/parser": "^18.0.0"
   },

package/scripts/gha/diagnose-port-collision.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+
+PORTS="${PORTS:-}"
+OUTPUT_DIR="${OUTPUT_DIR:-${RUNNER_TEMP:-/tmp}/port-diagnostics}"
+
+if [ "${PORT_DIAGNOSTICS_BOUNDED_CHILD:-}" != 1 ]; then
+  PORT_DIAGNOSTICS_BOUNDED_CHILD=1 python3 - \
+    "${PORT_DIAGNOSTICS_TIMEOUT_SECONDS:-45}" "$0" "$@" <<'PY'
+import os
+import signal
+import subprocess
+import sys
+
+try:
+    timeout_seconds = float(sys.argv[1])
+    if timeout_seconds <= 0 or timeout_seconds > 300:
+        raise ValueError
+except ValueError:
+    timeout_seconds = 45
+
+try:
+    process = subprocess.Popen(
+        ["bash", sys.argv[2], *sys.argv[3:]],
+        env=os.environ.copy(),
+        start_new_session=True,
+    )
+except OSError as error:
+    print(f"::warning::Could not start port diagnostics: {error}", file=sys.stderr)
+    sys.exit(0)
+
+try:
+    process.wait(timeout=timeout_seconds)
+except subprocess.TimeoutExpired:
+    os.killpg(process.pid, signal.SIGTERM)
+    try:
+        process.wait(timeout=2)
+    except subprocess.TimeoutExpired:
+        os.killpg(process.pid, signal.SIGKILL)
+        process.wait()
+    print(
+        f"::warning::Port diagnostics collector exceeded {timeout_seconds:g}s; uploading partial evidence",
+        file=sys.stderr,
+    )
+PY
+  exit 0
+fi
+
+usage() {
+  cat <<'USAGE'
+Usage: diagnose-port-collision [--ports "2200 2216"] [--output-dir PATH]
+
+Best-effort, non-masking diagnostics for a failed workflow that allocated localhost ports.
+The script never returns a failure for an unavailable probe or an occupied port.
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --ports)
+      [ "$#" -ge 2 ] || { usage >&2; exit 0; }
+      PORTS="$2"
+      shift
+      ;;
+    --output-dir)
+      [ "$#" -ge 2 ] || { usage >&2; exit 0; }
+      OUTPUT_DIR="$2"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "::warning::Ignoring unknown diagnostics argument: $1" >&2
+      ;;
+  esac
+  shift
+done
+
+if ! mkdir -p "$OUTPUT_DIR" 2>/dev/null; then
+  echo "::warning::Could not create port diagnostics directory: $OUTPUT_DIR" >&2
+  exit 0
+fi
+
+REPORT="$OUTPUT_DIR/summary.txt"
+LISTENERS="$OUTPUT_DIR/listeners.txt"
+DOCKER_REPORT="$OUTPUT_DIR/docker.txt"
+KERNEL_REPORT="$OUTPUT_DIR/kernel.txt"
+RUNNER_REPORT="$OUTPUT_DIR/runner.txt"
+
+write_report_header() {
+  local path="$1"
+  {
+    echo "generated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unavailable)"
+    echo "workflow=${GITHUB_WORKFLOW:-unavailable}"
+    echo "job=${GITHUB_JOB:-unavailable}"
+    echo "run_id=${GITHUB_RUN_ID:-unavailable}"
+    echo "run_attempt=${GITHUB_RUN_ATTEMPT:-unavailable}"
+    echo "runner_name=${RUNNER_NAME:-unavailable}"
+    echo "runner_os=${RUNNER_OS:-unavailable}"
+    echo "workspace=${GITHUB_WORKSPACE:-unavailable}"
+    echo "allocated_ports=${PORTS:-none}"
+  } > "$path" 2>/dev/null || true
+}
+
+write_report_header "$REPORT"
+
+run_bounded() {
+  local seconds="$1"
+  shift
+  python3 - "$seconds" "$@" <<'PY'
+import subprocess
+import sys
+try:
+    subprocess.run(sys.argv[2:], check=False, timeout=float(sys.argv[1]))
+except subprocess.TimeoutExpired:
+    print(f'probe=timed-out after {sys.argv[1]}s', file=sys.stderr)
+except OSError as error:
+    print(f'probe=unavailable ({error})', file=sys.stderr)
+PY
+}
+
+valid_ports=()
+invalid_ports=()
+read -r -a requested_ports <<< "$PORTS"
+for port in "${requested_ports[@]}"; do
+  case "$port" in
+    ''|*[!0-9]*) invalid_ports+=("$port") ;;
+    *)
+      if [ "$port" -ge 1 ] && [ "$port" -le 65535 ]; then
+        valid_ports+=("$port")
+      else
+        invalid_ports+=("$port")
+      fi
+      ;;
+  esac
+done
+
+{
+  echo "requested_port_count=${#requested_ports[@]}"
+  echo "valid_port_count=${#valid_ports[@]}"
+  echo "invalid_ports=${invalid_ports[*]:-none}"
+} >> "$REPORT" 2>/dev/null || true
+
+{
+  echo "# Linux kernel port contract (best effort)"
+  if command -v sysctl >/dev/null 2>&1; then
+    echo "ip_local_reserved_ports=$(sysctl -n net.ipv4.ip_local_reserved_ports 2>/dev/null || echo unavailable)"
+    echo "ip_local_port_range=$(sysctl -n net.ipv4.ip_local_port_range 2>/dev/null || echo unavailable)"
+  else
+    echo "sysctl=unavailable"
+  fi
+  for path in /proc/sys/net/ipv4/ip_local_reserved_ports /proc/sys/net/ipv4/ip_local_port_range; do
+    if [ -r "$path" ]; then
+      echo "$path=$(tr -d '\n' < "$path" 2>/dev/null || true)"
+    fi
+  done
+} > "$KERNEL_REPORT" 2>/dev/null || true
+
+{
+  echo "# TCP socket diagnostics (best effort)"
+  lsof_available=false
+  ss_available=false
+  lsof_output=''
+  if command -v lsof >/dev/null 2>&1; then
+    lsof_available=true
+    lsof_output=$(run_bounded 10 lsof -nP -iTCP 2>&1 || true)
+  elif command -v ss >/dev/null 2>&1; then
+    ss_available=true
+  fi
+  for port in "${valid_ports[@]}"; do
+    occupied=false
+    echo "port=$port"
+    if [ "$lsof_available" = true ]; then
+      if lsof_filtered=$(printf '%s\n' "$lsof_output" | awk -v port="$port" '
+        /^probe=/ { print; next }
+        $1 == "COMMAND" { header = $0; next }
+        {
+          local_endpoint = $9
+          sub(/->.*/, "", local_endpoint)
+          if (local_endpoint ~ (":" port "$")) {
+            if (!printed_header && header != "") {
+              print header
+              printed_header = 1
+            }
+            print
+            found = 1
+          }
+        }
+        END { exit found ? 0 : 1 }
+      '); then
+        occupied=true
+      fi
+      [ -z "$lsof_filtered" ] || printf '%s\n' "$lsof_filtered"
+    elif [ "$ss_available" = true ]; then
+      ss -ntp "( sport = :$port )" 2>&1 || true
+      if ss -nt "( sport = :$port )" 2>/dev/null | tail -n +2 | grep -q .; then
+        occupied=true
+      fi
+    else
+      echo "probe=unavailable (neither lsof nor ss is installed)"
+    fi
+    echo "status=$([ "$occupied" = true ] && echo occupied || echo free-or-unobserved)"
+    echo
+  done
+} > "$LISTENERS" 2>/dev/null || true
+
+{
+  echo "# Docker diagnostics (best effort)"
+  if command -v docker >/dev/null 2>&1; then
+    run_bounded 10 docker version --format 'server={{.Server.Version}}' 2>&1 || true
+    docker_ps_output=$(run_bounded 10 docker ps --no-trunc --format 'container={{.ID}} names={{.Names}} ports={{.Ports}}' 2>&1 || true)
+    for port in "${valid_ports[@]}"; do
+      echo "published_port=$port"
+      printf '%s\n' "$docker_ps_output" | awk -v port="$port" '/^probe=/ || $0 ~ "(^|[^0-9])" port "->"' || true
+    done
+  else
+    echo "docker=unavailable"
+  fi
+} > "$DOCKER_REPORT" 2>/dev/null || true
+
+{
+  echo "# Runner context (deliberately excludes the process environment)"
+  uname -a 2>&1 || true
+  hostname 2>&1 || true
+  id 2>&1 || true
+  echo "runner_temp=${RUNNER_TEMP:-unavailable}"
+  echo "github_actions=${GITHUB_ACTIONS:-unavailable}"
+} > "$RUNNER_REPORT" 2>/dev/null || true
+
+echo "::notice::Port diagnostics captured under $OUTPUT_DIR"
+exit 0

package/scripts/gha/prepare-trivy-db.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mirror_repository="${TRIVY_DB_MIRROR_REPOSITORY:-mirror.gcr.io/aquasec/trivy-db:2}"
+official_repository="${TRIVY_DB_OFFICIAL_REPOSITORY:-ghcr.io/aquasecurity/trivy-db:2}"
+download_timeout="${TRIVY_DB_TIMEOUT:-75s}"
+
+download_database() {
+  trivy image \
+    --download-db-only \
+    --no-progress \
+    --timeout "$download_timeout" \
+    --db-repository "$1"
+}
+
+mirror_exit=0
+download_database "$mirror_repository" || mirror_exit=$?
+if [ "$mirror_exit" -eq 0 ]; then
+  echo "Trivy vulnerability database prepared from the Google mirror"
+  exit 0
+fi
+
+echo "Trivy database mirror failed with exit ${mirror_exit}; retrying from official GHCR"
+official_exit=0
+download_database "$official_repository" || official_exit=$?
+if [ "$official_exit" -eq 0 ]; then
+  echo "Trivy vulnerability database prepared from official GHCR"
+  exit 0
+fi
+
+echo "Trivy vulnerability database download failed from the Google mirror (exit ${mirror_exit}) and official GHCR (exit ${official_exit})" >&2
+exit "$official_exit"