vouchington-tooling 0.0.15 → 0.0.16

package/README.md

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

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

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

package/dist/ci-local/index.mjs

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

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

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

package/dist/ci-local/parse.mjs

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

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

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

package/dist/ci-local/types.mjs

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

package/dist/cli/index.mjs

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

package/dist/cli/parse.d.mts

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

package/dist/cli/parse.mjs

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

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

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

package/dist/dockerfile-parse/index.d.mts

@@ -0,0 +1,4 @@
+export { parseDockerfileRuntimeImages } from './runtime-cmd.mts';
+export type { DockerfileRuntimeImage, ParseDockerfileRuntimeImagesOptions } from './runtime-cmd.mts';
+export { parseDockerfilePrewarmStages } from './prewarm-ports.mts';
+export type { DockerfilePrewarmStage, ParseDockerfilePrewarmOptions } from './prewarm-ports.mts';

package/dist/dockerfile-parse/index.mjs

@@ -0,0 +1,2 @@
+export { parseDockerfileRuntimeImages } from './runtime-cmd.mjs';
+export { parseDockerfilePrewarmStages } from './prewarm-ports.mjs';

package/dist/dockerfile-parse/prewarm-ports.d.mts

@@ -0,0 +1,12 @@
+export interface DockerfilePrewarmStage {
+    stage: string;
+    copySource: string | undefined;
+    monitoredPort: number | undefined;
+    envPort: number | undefined;
+}
+export interface ParseDockerfilePrewarmOptions {
+    copySourcePrefix?: string;
+    prewarmBinary?: string;
+    prewarmPortEnv?: string;
+}
+export declare function parseDockerfilePrewarmStages(dockerfile: string, { copySourcePrefix, prewarmBinary, prewarmPortEnv, }?: ParseDockerfilePrewarmOptions): DockerfilePrewarmStage[];

package/dist/dockerfile-parse/prewarm-ports.mjs

@@ -0,0 +1,59 @@
+import { Copy, DockerfileParser, Run } from 'dockerfile-ast';
+import { collectStages } from './stages.mjs';
+export function parseDockerfilePrewarmStages(dockerfile, { copySourcePrefix = '/prod/', prewarmBinary = 'node-prewarm', prewarmPortEnv = 'NODE_PREWARM_PORT', } = {}) {
+    const parser = DockerfileParser.parse(dockerfile);
+    const stages = collectStages(parser);
+    const prewarmStages = [];
+    for (const { stage, instructions } of stages) {
+        const prewarmRun = instructions.find((instruction) => instruction instanceof Run && isPrewarmRun(instruction, prewarmBinary));
+        if (!prewarmRun)
+            continue;
+        const args = runArguments(prewarmRun);
+        prewarmStages.push({
+            stage,
+            copySource: matchCopySource(instructions, copySourcePrefix),
+            monitoredPort: matchMonitoredPort(args),
+            envPort: matchEnvPort(args, prewarmPortEnv),
+        });
+    }
+    return prewarmStages;
+}
+function runArguments(instruction) {
+    return instruction.getArguments().map((argument) => argument.getValue());
+}
+function isPrewarmRun(instruction, prewarmBinary) {
+    return runArguments(instruction).some((argument) => argument === prewarmBinary || argument.startsWith(`${prewarmBinary}@`));
+}
+function matchCopySource(instructions, copySourcePrefix) {
+    for (const instruction of instructions) {
+        if (!(instruction instanceof Copy))
+            continue;
+        if (!instruction.getFlags().some((flag) => flag.getName() === 'from'))
+            continue;
+        const args = instruction.getArguments();
+        if (args.at(-1)?.getValue() !== './' && args.at(-1)?.getValue() !== '.')
+            continue;
+        const sourcePath = args[0]?.getValue();
+        if (sourcePath?.startsWith(copySourcePrefix))
+            return sourcePath;
+    }
+    return undefined;
+}
+function matchMonitoredPort(args) {
+    const index = args.indexOf('--port');
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    return value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined;
+}
+function matchEnvPort(args, prewarmPortEnv) {
+    const prefix = `${prewarmPortEnv}=`;
+    for (const argument of args) {
+        if (!argument.startsWith(prefix))
+            continue;
+        const value = argument.slice(prefix.length);
+        if (/^\d+$/.test(value))
+            return Number(value);
+    }
+    return undefined;
+}

package/dist/dockerfile-parse/runtime-cmd.d.mts

@@ -0,0 +1,11 @@
+export interface DockerfileRuntimeImage {
+    stage: string;
+    pnpmFilter: string;
+    cmdPath: string;
+    workspaceDir: string;
+}
+export interface ParseDockerfileRuntimeImagesOptions {
+    monorepoRoot: string;
+    copySourcePrefix?: string;
+}
+export declare function parseDockerfileRuntimeImages(dockerfile: string, { monorepoRoot, copySourcePrefix }: ParseDockerfileRuntimeImagesOptions): DockerfileRuntimeImage[];

package/dist/dockerfile-parse/runtime-cmd.mjs

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { Cmd, Copy, DockerfileParser, Run } from 'dockerfile-ast';
+import { expandWorkspaceGlob } from '../workspace-glob.mjs';
+import { collectStages } from './stages.mjs';
+const CMD_SCRIPT = /\.(?:[cm]?[jt]s|tsx)$/u;
+export function parseDockerfileRuntimeImages(dockerfile, { monorepoRoot, copySourcePrefix = '/prod/' }) {
+    const parser = DockerfileParser.parse(dockerfile);
+    const stages = collectStages(parser);
+    const targetToFilter = collectDeployTargets(stages);
+    const images = [];
+    for (const { stage, instructions } of stages) {
+        const target = matchCopyTarget(instructions, copySourcePrefix);
+        if (!target)
+            continue;
+        const pnpmFilter = targetToFilter.get(deployKey(target.fromStage, target.sourcePath));
+        if (!pnpmFilter)
+            continue;
+        const cmdPath = matchCmdScriptPath(instructions);
+        if (!cmdPath)
+            continue;
+        images.push({
+            stage,
+            pnpmFilter,
+            cmdPath,
+            workspaceDir: findWorkspaceDirByPackageName(monorepoRoot, pnpmFilter),
+        });
+    }
+    return images;
+}
+function deployKey(stage, target) {
+    return `${stage}\0${target}`;
+}
+function collectDeployTargets(stages) {
+    const targetToFilter = new Map();
+    for (const { stage, instructions } of stages) {
+        for (const instruction of instructions) {
+            if (!(instruction instanceof Run))
+                continue;
+            const runText = instruction
+                .getArguments()
+                .map((argument) => argument.getValue())
+                .join(' ');
+            for (const { filter, target } of parsePnpmDeploys(runText)) {
+                targetToFilter.set(deployKey(stage, target), filter);
+            }
+        }
+    }
+    return targetToFilter;
+}
+function parsePnpmDeploys(runText) {
+    const found = [];
+    for (const command of runText.split(/\s*(?:&&|;)\s*/)) {
+        const parsed = parsePnpmDeploy(command);
+        if (parsed)
+            found.push(parsed);
+    }
+    return found;
+}
+function parsePnpmDeploy(command) {
+    const tokens = command.split(/\s+/).filter(Boolean);
+    const pnpm = tokens.indexOf('pnpm');
+    if (pnpm === -1)
+        return undefined;
+    const deploy = tokens.indexOf('deploy', pnpm + 1);
+    if (deploy === -1)
+        return undefined;
+    const filter = flagValue(tokens, pnpm, tokens.length, 'filter');
+    const prodTarget = flagValue(tokens, deploy + 1, tokens.length, 'prod');
+    const positional = tokens[deploy + 1];
+    const target = prodTarget ??
+        (tokens.slice(pnpm, deploy).includes('--prod') && positional?.startsWith('/')
+            ? positional
+            : undefined);
+    return filter && target ? { filter, target } : undefined;
+}
+function flagValue(tokens, start, end, name) {
+    const flag = `--${name}`;
+    for (let index = start; index < end; index += 1) {
+        const token = tokens[index];
+        if (token === flag)
+            return tokens[index + 1];
+        if (token?.startsWith(`${flag}=`))
+            return token.slice(flag.length + 1);
+    }
+    return undefined;
+}
+function matchCopyTarget(instructions, copySourcePrefix) {
+    for (const instruction of instructions) {
+        if (!(instruction instanceof Copy))
+            continue;
+        const fromStage = instruction
+            .getFlags()
+            .find((flag) => flag.getName() === 'from')
+            ?.getValue();
+        if (!fromStage)
+            continue;
+        const args = instruction.getArguments();
+        if (args.at(-1)?.getValue() !== './' && args.at(-1)?.getValue() !== '.')
+            continue;
+        const sourcePath = args[0]?.getValue();
+        if (sourcePath?.startsWith(copySourcePrefix))
+            return { fromStage, sourcePath };
+    }
+    return undefined;
+}
+function matchCmdScriptPath(instructions) {
+    const cmds = instructions.filter((instruction) => instruction instanceof Cmd);
+    if (cmds.length === 0)
+        return undefined;
+    const parts = cmds
+        .at(-1)
+        .getJSONStrings()
+        ?.map((argument) => argument.getJSONValue());
+    return parts?.find((part) => CMD_SCRIPT.test(part));
+}
+function findWorkspaceDirByPackageName(monorepoRoot, packageName) {
+    if (packageName.startsWith('.') || packageName.startsWith('/')) {
+        const dir = path.resolve(monorepoRoot, packageName);
+        if (existsSync(path.join(dir, 'package.json')))
+            return dir;
+        throw new Error(`Workspace package not found for filter: ${packageName}`);
+    }
+    const monorepoPackage = JSON.parse(readFileSync(path.join(monorepoRoot, 'package.json'), 'utf8'));
+    const workspaces = Array.isArray(monorepoPackage.workspaces)
+        ? monorepoPackage.workspaces
+        : [];
+    for (const pattern of workspaces) {
+        for (const dir of expandWorkspaceGlob(monorepoRoot, pattern)) {
+            if (matchesPackage(dir, packageName))
+                return dir;
+        }
+    }
+    throw new Error(`Workspace package not found for filter: ${packageName}`);
+}
+function matchesPackage(dir, packageName) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    const { name } = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return name === packageName;
+}

package/dist/dockerfile-parse/stages.d.mts

@@ -0,0 +1,7 @@
+import { Cmd, Copy, From, Run, type Dockerfile } from 'dockerfile-ast';
+export type StageInstruction = From | Copy | Cmd | Run;
+export interface ParsedStage {
+    stage: string;
+    instructions: StageInstruction[];
+}
+export declare function collectStages(parser: Dockerfile): ParsedStage[];

package/dist/dockerfile-parse/stages.mjs

@@ -0,0 +1,18 @@
+import { Cmd, Copy, From, Run } from 'dockerfile-ast';
+export function collectStages(parser) {
+    const stages = [];
+    let currentStage;
+    for (const instruction of parser.getInstructions()) {
+        if (instruction instanceof From) {
+            const stage = instruction.getBuildStage() ?? String(stages.length);
+            currentStage = { stage, instructions: [instruction] };
+            stages.push(currentStage);
+            continue;
+        }
+        if (currentStage &&
+            (instruction instanceof Copy || instruction instanceof Cmd || instruction instanceof Run)) {
+            currentStage.instructions.push(instruction);
+        }
+    }
+    return stages;
+}

package/dist/gha-pr-checkpoint/index.d.mts

@@ -0,0 +1,58 @@
+export declare const CHECKPOINT_MARKER = "pr-checkpoint:v1";
+export type CheckpointStatus = 'queued' | 'running' | 'awaiting_verification' | 'failed' | 'deadline' | 'unresumable' | 'complete';
+export type Checkpoint = {
+    marker: string;
+    repository: string;
+    pr: number;
+    /** Absent on checkpoints posted before trigger ids were recorded; keep optional so resume can still parse them. */
+    triggerCommentId?: number;
+    headRef: string;
+    startSha: string;
+    sessionStartSha: string;
+    runId: string;
+    runUrl: string;
+    actor: string;
+    sessionId: string;
+    /** Absent from v1 checkpoints created before session URLs were exposed. */
+    sessionUrl?: string;
+    resumeSourceRunId: string;
+    status: CheckpointStatus;
+    createdAt: string;
+    updatedAt: string;
+};
+export type GitHubComment = {
+    id: number;
+    user?: {
+        login?: string;
+        type?: string;
+    };
+    performed_via_github_app?: {
+        slug?: string;
+    } | null;
+    body?: string;
+    created_at?: string;
+};
+export interface CheckpointCodecOptions {
+    marker?: string;
+    sessionIdPattern?: RegExp;
+}
+export interface TrustedCheckpointActor {
+    actor: string;
+    userType?: string;
+    appSlug?: string;
+}
+/**
+ * Anti-forgery predicate: a checkpoint HTML comment is plain text any PR commenter can paste,
+ * so `parseCheckpoint` alone proves shape, not provenance. This proves the comment itself was
+ * authored by the expected App identity.
+ */
+export declare function isTrustedCheckpointComment(comment: GitHubComment, context: TrustedCheckpointActor): boolean;
+export declare function renderCheckpoint(checkpoint: Checkpoint, options?: {
+    marker?: string;
+}): string;
+export declare function parseCheckpoint(body: string, options?: CheckpointCodecOptions): Checkpoint | undefined;
+export declare function validateCheckpoint(value: unknown, options?: CheckpointCodecOptions): Checkpoint | undefined;
+export declare function sortedCheckpointCandidates(comments: GitHubComment[], options?: CheckpointCodecOptions): {
+    comment: GitHubComment;
+    checkpoint: Checkpoint;
+}[];