vouchington-tooling 0.3.5 → 0.4.0

package/README.md

@@ -7,7 +7,7 @@ npm install vouchington-tooling
 # optional, only if you import vouchington-tooling/sql-ast
 npm install @libpg-query/parser
 # optional, only for vouchington-tooling/agent-blackboard and agent-blackboard CLI commands
-npm install agent-blackboard@^0.3.1
+npm install agent-blackboard@^0.5.0
 ```
 
 ## CLI
@@ -30,6 +30,9 @@ 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 vitest-report-attempt write <directory> <suite>
+vouchington vitest-report-attempt read <root>
+vouchington prepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]
 vouchington pnpm-install --runner-lifecycle persistent --install-scripts true
 vouchington check-cache-size /tmp/cache 1048576 node-modules
 vouchington make-shard-matrix 4
@@ -63,6 +66,10 @@ For persistent `pnpm-install`, v4 metadata tracks structural inputs separately f
 uses one script-suppressed verification install followed by `pnpm rebuild --pending --recursive`.
 When only newly pending dependency package IDs remain, it instead rebuilds those exact IDs without
 rerunning first-party workspace hooks.
+An isolated native-binary mismatch uses one strict forced install only when structural provenance
+matches, workspace links are valid, and pnpm records empty `ignoredBuilds` and `pendingBuilds` ledgers;
+otherwise it retains the script-free then strict reconciliation. Native and workspace-link health
+are verified before its metadata stamp is refreshed.
 The command emits a structured non-secret provenance diagnostic identifying changed structural
 categories, the last script policy, script capability, and native-binary health.
 
@@ -88,7 +95,7 @@ GitHub reports a merged PR whose `baseRefName` is `main`; a merged PR into anoth
 as not merged to main, and a missing base is unavailable.
 
 Agent Blackboard support is optional: only the `agent-blackboard` subpath and its CLI commands
-need `agent-blackboard@^0.3.1`. Snapshot cleanup accepts only package-generated temporary paths.
+need `agent-blackboard@^0.5.0`. Snapshot cleanup accepts only package-generated temporary paths.
 Programmatic callers launched from a different workspace directory pass their own module URL as
 `dependencies: { resolveFrom: import.meta.url }`; the CLI defaults to the current package context.
 It captures a target under a private tombstone, validates partition names, permissions, JSONL,
@@ -154,7 +161,8 @@ import { parseCsvRows, streamCsvRows } from 'vouchington-tooling/csv'
 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 { runPostReview } from 'vouchington-tooling/gha-post-review'
+import { postReviewWithTokenFromEnv, runPostReview } from 'vouchington-tooling/gha-post-review'
+import { postClaudeReviewFromEnv } from 'vouchington-tooling/gha-claude-post-review'
 import { nextPageUrlFromLinkHeader } from 'vouchington-tooling/http-link-pagination'
 import {
   cmdUpload,
@@ -168,6 +176,7 @@ 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'
+import { checkGhaWorkspacePolicy } from 'vouchington-tooling/gha-workspace-policy'
 import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
 import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
 import { parseUniqueSwiftBinaryTargetChecksum } from 'vouchington-tooling/swift-source-offset'
@@ -181,6 +190,10 @@ import { appendJournal, probeBlackboard } from 'vouchington-tooling/agent-blackb
 import { buildSessionFrictionReport, recordFriction } from 'vouchington-tooling/session-friction'
 ```
 
+`checkWorkspaceGatesPolicy` rejects tracked test assertions that hard-code the exact version of a
+dependency declared by a non-fixture package manifest. Assert dependency membership or placement,
+or derive a configuration or documentation package spec from that manifest instead.
+
 `session-friction` is an opt-in capture and reporting library. Callers supply the session id,
 absolute log directory, host-independent observation, and journal loader; it does not inspect host
 environment variables, install hooks, or connect to a journal service by itself. Invoking
@@ -211,8 +224,9 @@ touch. Recording and report log reads are synchronous: on contention they block
 event loop for up to one second before failing explicitly. Avoid these APIs on hot request paths.
 
 The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their
-boundaries. Review posting lives in `gha-post-review` and talks to GitHub only through caller-supplied
-credentials (job token or a minted Claude GitHub App token).
+boundaries. Neutral review posting lives in `gha-post-review` and requires a caller-supplied GitHub
+token. Claude App OIDC is an explicitly selected `gha-claude-post-review` adapter; the legacy
+token-source router remains deprecated for one release line.
 
 `vitest-diagnostics` reads Node diagnostic report JSON from a caller-selected directory. It sorts
 filenames, tolerates partial files, returns only a bounded field allowlist, and never emits raw

package/dist/cli/commands/prepare-vitest-reports.d.mts

@@ -0,0 +1,2 @@
+import { runPrepareVitestReportsCli } from '../../vitest-blob-manifest/reports-cli.mts';
+export declare function runPrepareVitestReportsCommand(args: readonly string[], run?: typeof runPrepareVitestReportsCli): number;

package/dist/cli/commands/prepare-vitest-reports.mjs

@@ -0,0 +1,11 @@
+import { runPrepareVitestReportsCli } from '../../vitest-blob-manifest/reports-cli.mjs';
+export function runPrepareVitestReportsCommand(args, run = runPrepareVitestReportsCli) {
+    try {
+        run(args);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/commands/vitest-report-attempt.d.mts

@@ -0,0 +1,2 @@
+import { runVitestReportAttemptCli } from '../../vitest-blob-manifest/report-attempt-cli.mts';
+export declare function runVitestReportAttemptCommand(args: readonly string[], run?: typeof runVitestReportAttemptCli): number;

package/dist/cli/commands/vitest-report-attempt.mjs

@@ -0,0 +1,11 @@
+import { runVitestReportAttemptCli } from '../../vitest-blob-manifest/report-attempt-cli.mjs';
+export function runVitestReportAttemptCommand(args, run = runVitestReportAttemptCli) {
+    try {
+        run(args);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -14,6 +14,8 @@ import { runPostReviewCommand } from './commands/post-review.mjs';
 import { runStageReviewPayloadCommand } from './commands/stage-review-payload.mjs';
 import { runSwiftSemanticEqualCommand } from './commands/swift-semantic-equal.mjs';
 import { runVitestBlobManifestCommand } from './commands/vitest-blob-manifest.mjs';
+import { runVitestReportAttemptCommand } from './commands/vitest-report-attempt.mjs';
+import { runPrepareVitestReportsCommand } from './commands/prepare-vitest-reports.mjs';
 import { runRetrospectiveTranscriptCommand } from './commands/retrospective-transcript.mjs';
 import { runLinkSkill } from './commands/link-skill.mjs';
 import { runRetrospectiveFactsCommand } from './commands/retrospective-facts.mjs';
@@ -93,6 +95,10 @@ export function runCli(argv = process.argv) {
             return runPnpmInstallCli(parsed.args);
         case 'vitest-blob-manifest':
             return runVitestBlobManifestCommand(parsed.args);
+        case 'vitest-report-attempt':
+            return runVitestReportAttemptCommand(parsed.args);
+        case 'prepare-vitest-reports':
+            return runPrepareVitestReportsCommand(parsed.args);
         case 'nuget-central-version':
             return runNugetCentralVersionCommand(parsed.args);
         case 'swift-semantic-equal':

package/dist/cli/parse.d.mts

@@ -24,6 +24,12 @@ export type ParsedCli = {
 } | {
     kind: 'vitest-blob-manifest';
     args: string[];
+} | {
+    kind: 'vitest-report-attempt';
+    args: string[];
+} | {
+    kind: 'prepare-vitest-reports';
+    args: string[];
 } | {
     kind: 'nuget-central-version';
     args: string[];

package/dist/cli/parse.mjs

@@ -40,6 +40,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 === 'vitest-report-attempt')
+        return { kind: 'vitest-report-attempt', args: rest };
+    if (command === 'prepare-vitest-reports')
+        return { kind: 'prepare-vitest-reports', args: rest };
     if (command === 'nuget-central-version')
         return { kind: 'nuget-central-version', args: rest };
     if (command === 'swift-semantic-equal')

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  download-optional-run-artifacts  Download optional artifacts from the current run\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  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\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...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\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 [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\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  download-optional-run-artifacts  Download optional artifacts from the current run\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  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\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  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\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...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\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]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-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 [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -15,6 +15,8 @@ Commands:
   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
+  vitest-report-attempt         Write or read a Vitest report-attempt marker
+  prepare-vitest-reports        Validate and select Vitest report JSON files
   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
@@ -74,6 +76,8 @@ gha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern
 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]
+vitest-report-attempt <write DIRECTORY SUITE|read ROOT>
+prepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]
 pnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false
 check-cache-size <path> <max-bytes> <label>
 make-shard-matrix <total>

package/dist/gha-claude-post-review/index.d.mts

@@ -0,0 +1,3 @@
+export { CLAUDE_APP_TOKEN_EXCHANGE_URL, CLAUDE_OIDC_AUDIENCE, CLAUDE_POSTER_PERMISSIONS, GITHUB_INSTALLATION_TOKEN_URL, createActionsClaudeTokenIo, mintClaudeAppToken, oidcTokenRequest, revokeClaudeAppToken, withClaudeAppToken, } from '../gha-post-review/claude-token.mts';
+export type { ClaudeTokenIo, FetchLike } from '../gha-post-review/claude-token.mts';
+export { postClaudeReviewFromEnv } from '../gha-post-review/github.mts';

package/dist/gha-claude-post-review/index.mjs

@@ -0,0 +1,2 @@
+export { CLAUDE_APP_TOKEN_EXCHANGE_URL, CLAUDE_OIDC_AUDIENCE, CLAUDE_POSTER_PERMISSIONS, GITHUB_INSTALLATION_TOKEN_URL, createActionsClaudeTokenIo, mintClaudeAppToken, oidcTokenRequest, revokeClaudeAppToken, withClaudeAppToken, } from '../gha-post-review/claude-token.mjs';
+export { postClaudeReviewFromEnv } from '../gha-post-review/github.mjs';

package/dist/gha-post-review/github.d.mts

@@ -17,6 +17,13 @@ export declare function createGhPostReviewIo(options: {
     expectedHeadSha?: string;
     expectedBaseSha?: string;
 }): PostReviewIo;
+/** @deprecated Use postReviewWithTokenFromEnv or postClaudeReviewFromEnv explicitly. */
 export declare function postReviewFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, claudeIo?: import("./claude-token.mts").ClaudeTokenIo): Promise<{
     posted: boolean;
 }>;
+export declare function postReviewWithTokenFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, token?: string | undefined): {
+    posted: boolean;
+};
+export declare function postClaudeReviewFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, claudeIo?: import("./claude-token.mts").ClaudeTokenIo): Promise<{
+    posted: boolean;
+}>;

package/dist/gha-post-review/github.mjs

@@ -103,12 +103,19 @@ export function createGhPostReviewIo(options) {
         },
     };
 }
+/** @deprecated Use postReviewWithTokenFromEnv or postClaudeReviewFromEnv explicitly. */
 export async function postReviewFromEnv(env = process.env, exec = createGhExec(), claudeIo = createActionsClaudeTokenIo(env)) {
+    const token = resolveReviewPostToken(env);
+    if (token.source === 'github-token')
+        return postReviewWithTokenFromEnv(env, exec, token.token);
+    return await postClaudeReviewFromEnv(env, exec, claudeIo);
+}
+function createPostWithToken(env, exec) {
     const repository = requireEnv('GITHUB_REPOSITORY', env);
     const prNumber = requireEnv('PR_NUMBER', env);
     const payloadPath = requireEnv('CODE_REVIEW_PAYLOAD_PATH', env);
     const payloadBytes = readRegularReviewPayload(payloadPath, 'required');
-    const postWithToken = (token) => runPostReview(payloadPath, createGhPostReviewIo({
+    return (token) => runPostReview(payloadPath, createGhPostReviewIo({
         repository,
         prNumber,
         payloadPath,
@@ -118,8 +125,16 @@ export async function postReviewFromEnv(env = process.env, exec = createGhExec()
         expectedHeadSha: env.EXPECTED_HEAD_SHA ?? '',
         expectedBaseSha: env.EXPECTED_BASE_SHA ?? '',
     }));
-    const token = resolveReviewPostToken(env);
-    if (token.source === 'github-token')
-        return postWithToken(token.token);
-    return await withClaudeAppToken(claudeIo, postWithToken);
+}
+function withTokenEnv(exec, env, token) {
+    const tokenEnv = { ...env, GH_TOKEN: token, GITHUB_TOKEN: token };
+    return (args, options) => exec(args, { ...options, env: { ...options?.env, ...tokenEnv } });
+}
+export function postReviewWithTokenFromEnv(env = process.env, exec = createGhExec(), token = env.GH_TOKEN || env.GITHUB_TOKEN) {
+    if (!token)
+        throw new ReviewPayloadError('GH_TOKEN or GITHUB_TOKEN is required.');
+    return createPostWithToken(env, withTokenEnv(exec, env, token))(token);
+}
+export async function postClaudeReviewFromEnv(env = process.env, exec = createGhExec(), claudeIo = createActionsClaudeTokenIo(env)) {
+    return await withClaudeAppToken(claudeIo, (token) => createPostWithToken(env, withTokenEnv(exec, env, token))(token));
 }

package/dist/gha-post-review/index.d.mts

@@ -2,8 +2,12 @@ export { MAX_COMMENTS, MAX_PAYLOAD_BYTES, PostReviewError, runPostReview } from
 export type { PostResult, PostReviewIo, PullFile, ReviewComment, SanitizedReview } from './post.mts';
 export { requireEnv, resolveReviewPostToken } from './token.mts';
 export type { ReviewPostToken } from './token.mts';
+/** @deprecated Import Claude helpers from vouchington-tooling/gha-claude-post-review. */
 export { CLAUDE_APP_TOKEN_EXCHANGE_URL, CLAUDE_OIDC_AUDIENCE, CLAUDE_POSTER_PERMISSIONS, GITHUB_INSTALLATION_TOKEN_URL, createActionsClaudeTokenIo, mintClaudeAppToken, oidcTokenRequest, revokeClaudeAppToken, withClaudeAppToken, } from './claude-token.mts';
+/** @deprecated Import Claude helpers from vouchington-tooling/gha-claude-post-review. */
 export type { ClaudeTokenIo, FetchLike } from './claude-token.mts';
-export { createGhExec, createGhPostReviewIo, postReviewFromEnv, postWithGh, writePostedOutput, } from './github.mts';
+export { createGhExec, createGhPostReviewIo, postReviewWithTokenFromEnv, postWithGh, writePostedOutput, } from './github.mts';
+/** @deprecated Select an explicit posting adapter. */
+export { postClaudeReviewFromEnv, postReviewFromEnv } from './github.mts';
 export type { GhExec } from './github.mts';
 export { runPostReviewCli } from './cli.mts';

package/dist/gha-post-review/index.mjs

@@ -1,5 +1,8 @@
 export { MAX_COMMENTS, MAX_PAYLOAD_BYTES, PostReviewError, runPostReview } from './post.mjs';
 export { requireEnv, resolveReviewPostToken } from './token.mjs';
+/** @deprecated Import Claude helpers from vouchington-tooling/gha-claude-post-review. */
 export { CLAUDE_APP_TOKEN_EXCHANGE_URL, CLAUDE_OIDC_AUDIENCE, CLAUDE_POSTER_PERMISSIONS, GITHUB_INSTALLATION_TOKEN_URL, createActionsClaudeTokenIo, mintClaudeAppToken, oidcTokenRequest, revokeClaudeAppToken, withClaudeAppToken, } from './claude-token.mjs';
-export { createGhExec, createGhPostReviewIo, postReviewFromEnv, postWithGh, writePostedOutput, } from './github.mjs';
+export { createGhExec, createGhPostReviewIo, postReviewWithTokenFromEnv, postWithGh, writePostedOutput, } from './github.mjs';
+/** @deprecated Select an explicit posting adapter. */
+export { postClaudeReviewFromEnv, postReviewFromEnv } from './github.mjs';
 export { runPostReviewCli } from './cli.mjs';

package/dist/gha-post-review/token.d.mts

@@ -4,5 +4,6 @@ export type ReviewPostToken = {
 } | {
     source: 'claude-app';
 };
+/** @deprecated Select an explicit posting adapter instead of the legacy token-source router. */
 export declare function resolveReviewPostToken(env?: NodeJS.ProcessEnv): ReviewPostToken;
 export declare function requireEnv(name: string, env?: NodeJS.ProcessEnv): string;

package/dist/gha-post-review/token.mjs

@@ -1,4 +1,5 @@
 import { ReviewPayloadError } from '../gha-review-payload/index.mjs';
+/** @deprecated Select an explicit posting adapter instead of the legacy token-source router. */
 export function resolveReviewPostToken(env = process.env) {
     const source = env.CODE_REVIEW_TOKEN_SOURCE || 'claude-app';
     if (source === 'github-token') {

package/dist/gha-workspace-policy/docker-workspace-user.d.mts

@@ -0,0 +1,2 @@
+import { type GhaFileKind } from './shared.mts';
+export declare function checkDockerWorkspaceUserDocument(file: string, document: unknown, kind: GhaFileKind, errors: string[]): void;

package/dist/gha-workspace-policy/docker-workspace-user.mjs

@@ -0,0 +1,208 @@
+import { visitRunSteps } from './shared.mjs';
+const WORKSPACE_RE = /(?:\$\{?GITHUB_WORKSPACE\}?|\$\{\{\s*github\.workspace\s*\}\})/iu;
+const DOCKER_GLOBAL_FLAG_OPTIONS = new Set(['--debug', '-D', '--help', '--tls', '--tlsverify']);
+const DOCKER_GLOBAL_VALUE_OPTIONS = new Set([
+    '--config',
+    '--context',
+    '-c',
+    '--host',
+    '-H',
+    '--log-level',
+    '-l',
+    '--tlscacert',
+    '--tlscert',
+    '--tlskey',
+]);
+const FLAG_OPTIONS = new Set([
+    '--detach',
+    '-d',
+    '--init',
+    '--interactive',
+    '-i',
+    '--privileged',
+    '--publish-all',
+    '-P',
+    '--read-only',
+    '--rm',
+    '--tty',
+    '-t',
+]);
+export function checkDockerWorkspaceUserDocument(file, document, kind, errors) {
+    visitRunSteps(document, kind === 'action', (scope, index, step) => {
+        if (typeof step.run !== 'string')
+            return;
+        for (const block of dockerRunBlocks(step.run)) {
+            const options = dockerOptions(block);
+            if (!options)
+                continue;
+            const writable = options.volumes.filter((volume) => WORKSPACE_RE.test(volume) && !isReadOnlyVolume(volume));
+            if (writable.length === 0 || hasHostUserMapping(options.user))
+                continue;
+            errors.push(`::error file=${file}::${file}: ${scope} step ${index} runs Docker with a writable ` +
+                `GITHUB_WORKSPACE mount (${writable.join(', ')}) but no --user host UID:GID mapping. ` +
+                'Use --user "$(id -u):$(id -g)" or make the workspace mount read-only.');
+        }
+    });
+}
+function shellTokens(input) {
+    const tokens = [];
+    let token = '';
+    let quote = '';
+    let substitutionDepth = 0;
+    let githubExpression = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const character = input[index];
+        if (githubExpression) {
+            token += character;
+            if (character === '}' && input[index + 1] === '}') {
+                token += '}';
+                index += 1;
+                githubExpression = false;
+            }
+            continue;
+        }
+        if (substitutionDepth > 0) {
+            token += character;
+            if (character === '(')
+                substitutionDepth += 1;
+            if (character === ')')
+                substitutionDepth -= 1;
+            continue;
+        }
+        if (character === '$' && input[index + 1] === '{' && input[index + 2] === '{') {
+            token += '${{';
+            index += 2;
+            githubExpression = true;
+            continue;
+        }
+        if (character === '$' && input[index + 1] === '(') {
+            token += '$(';
+            substitutionDepth = 1;
+            index += 1;
+            continue;
+        }
+        if (quote) {
+            if (character === '\\' && input[index + 1] !== undefined)
+                token += input[++index];
+            else if (character === quote)
+                quote = '';
+            else
+                token += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (/\s/u.test(character)) {
+            if (token)
+                tokens.push(token);
+            token = '';
+            continue;
+        }
+        if (character === '#' && !token)
+            break;
+        if (character === ';' || character === '|' || character === '&') {
+            if (token)
+                tokens.push(token);
+            token = '';
+            if ((character === '&' || character === '|') && input[index + 1] === character)
+                index += 1;
+            tokens.push(character);
+            continue;
+        }
+        if (character === '\\' && input[index + 1] !== undefined)
+            token += input[++index];
+        else
+            token += character;
+    }
+    if (token)
+        tokens.push(token);
+    return tokens;
+}
+function dockerRunBlocks(run) {
+    const blocks = [];
+    const lines = run.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        if (!/\bdocker\b/u.test(lines[index]))
+            continue;
+        let block = lines[index];
+        while (block.trimEnd().endsWith('\\') && index + 1 < lines.length) {
+            index += 1;
+            block = `${block.trimEnd().slice(0, -1)} ${lines[index]}`;
+        }
+        blocks.push(block);
+    }
+    return blocks;
+}
+function findDockerCommand(tokens) {
+    let commandStart = true;
+    for (const [index, token] of tokens.entries()) {
+        if (token === ';' || token === '|' || token === '&') {
+            commandStart = true;
+            continue;
+        }
+        if (!commandStart)
+            continue;
+        if (/^[A-Za-z_][A-Za-z0-9_]*=.*/u.test(token))
+            continue;
+        if (token === 'docker')
+            return index;
+        commandStart = false;
+    }
+    return -1;
+}
+function dockerOptions(block) {
+    const tokens = shellTokens(block);
+    const dockerIndex = findDockerCommand(tokens);
+    if (dockerIndex < 0)
+        return undefined;
+    let start = dockerIndex + 1;
+    while (start < tokens.length && tokens[start].startsWith('-')) {
+        const option = tokens[start];
+        const name = option.includes('=') ? option.slice(0, option.indexOf('=')) : option;
+        if (DOCKER_GLOBAL_FLAG_OPTIONS.has(name) || option.includes('='))
+            start += 1;
+        else if (DOCKER_GLOBAL_VALUE_OPTIONS.has(name))
+            start += 2;
+        else
+            return undefined;
+    }
+    if (tokens[start] === 'container')
+        start += 1;
+    if (tokens[start] !== 'run')
+        return undefined;
+    start += 1;
+    const volumes = [];
+    let user;
+    for (let index = start; index < tokens.length; index += 1) {
+        const option = tokens[index];
+        if (!option.startsWith('-'))
+            break;
+        const equals = option.indexOf('=');
+        const compact = option.startsWith('-v') || option.startsWith('-u');
+        const name = equals > 0
+            ? option.slice(0, equals)
+            : compact && option.length > 2
+                ? option.slice(0, 2)
+                : option;
+        const inlineValue = equals > 0
+            ? option.slice(equals + 1)
+            : compact && option.length > 2
+                ? option.slice(2)
+                : undefined;
+        const bundledFlags = /^-[diPt]{2,}$/u.test(option);
+        const value = inlineValue ?? (FLAG_OPTIONS.has(name) || bundledFlags ? undefined : tokens[++index]);
+        if ((name === '-v' || name === '--volume' || name === '--mount') && value !== undefined)
+            volumes.push(value);
+        if ((name === '-u' || name === '--user') && value !== undefined)
+            user = value;
+    }
+    return { user, volumes };
+}
+function hasHostUserMapping(value) {
+    return value !== undefined && /^\$\(\s*id\s+-u\s*\):\$\(\s*id\s+-g\s*\)$/u.test(value);
+}
+function isReadOnlyVolume(value) {
+    return /(?:^|:)ro(?:$|,)/u.test(value) || /(?:^|,)readonly(?:$|,)/u.test(value);
+}

package/dist/gha-workspace-policy/index.d.mts

@@ -0,0 +1,8 @@
+import type { SharedContext } from '../shared-context/index.mts';
+export interface GhaWorkspacePolicyOptions {
+    workflowDirectories?: readonly string[];
+    actionDirectories?: readonly string[];
+}
+export declare function checkGhaWorkspacePolicy(ctx: SharedContext, options?: GhaWorkspacePolicyOptions): Promise<{
+    errors: string[];
+}>;

package/dist/gha-workspace-policy/index.mjs

@@ -0,0 +1,17 @@
+import { checkDockerWorkspaceUserDocument } from './docker-workspace-user.mjs';
+import { ghaFileKind, loadWorkflowDocument } from './shared.mjs';
+import { checkNoSparseCheckoutDocument } from './sparse-checkout.mjs';
+export async function checkGhaWorkspacePolicy(ctx, options = {}) {
+    const errors = [];
+    if (!ctx.isInsideGitRepo)
+        return { errors };
+    for (const file of ctx.trackedFiles) {
+        const kind = ghaFileKind(file, options);
+        if (!kind)
+            continue;
+        const document = loadWorkflowDocument(ctx, file, errors);
+        checkNoSparseCheckoutDocument(file, document, kind, errors);
+        checkDockerWorkspaceUserDocument(file, document, kind, errors);
+    }
+    return { errors };
+}

package/dist/gha-workspace-policy/shared.d.mts

@@ -0,0 +1,6 @@
+import type { SharedContext } from '../shared-context/index.mts';
+import type { GhaWorkspacePolicyOptions } from './index.mts';
+export type GhaFileKind = 'workflow' | 'action';
+export declare function ghaFileKind(file: string, options: GhaWorkspacePolicyOptions): GhaFileKind | undefined;
+export declare function loadWorkflowDocument(ctx: SharedContext, file: string, errors: string[]): unknown;
+export declare function visitRunSteps(document: unknown, isAction: boolean, visitor: (scope: string, index: number, step: Record<string, unknown>) => void): void;

package/dist/gha-workspace-policy/shared.mjs

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as load } from 'yaml';
+export function ghaFileKind(file, options) {
+    const workflowDirectories = options.workflowDirectories ?? ['.github/workflows'];
+    const actionDirectories = options.actionDirectories ?? ['.github/actions'];
+    if (workflowDirectories.some((directory) => file.startsWith(`${directory.replace(/\/$/u, '')}/`)) &&
+        /\.ya?ml$/u.test(file))
+        return 'workflow';
+    if (actionDirectories.some((directory) => file.startsWith(`${directory.replace(/\/$/u, '')}/`)) &&
+        /\/action\.ya?ml$/u.test(file))
+        return 'action';
+    return undefined;
+}
+export function loadWorkflowDocument(ctx, file, errors) {
+    try {
+        const content = ctx.readTrackedFile?.(file) ?? readFileSync(join(ctx.repoRoot, file), 'utf8');
+        return load(content);
+    }
+    catch (error) {
+        errors.push(`::error file=${file}::${file}: invalid YAML (${error.message})`);
+        return undefined;
+    }
+}
+export function visitRunSteps(document, isAction, visitor) {
+    if (!document || typeof document !== 'object')
+        return;
+    if (isAction) {
+        const runs = document.runs;
+        if (!runs || typeof runs !== 'object')
+            return;
+        visitSteps('action', runs.steps, visitor);
+        return;
+    }
+    const jobs = document.jobs;
+    if (!jobs || typeof jobs !== 'object')
+        return;
+    for (const [jobId, value] of Object.entries(jobs)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const job = value;
+        if (typeof job.uses === 'string')
+            continue;
+        visitSteps(`job "${jobId}"`, job.steps, visitor);
+    }
+}
+function visitSteps(scope, value, visitor) {
+    if (!Array.isArray(value))
+        return;
+    value.forEach((step, index) => {
+        if (step && typeof step === 'object')
+            visitor(scope, index, step);
+    });
+}

package/dist/gha-workspace-policy/sparse-checkout.d.mts

@@ -0,0 +1,2 @@
+import { type GhaFileKind } from './shared.mts';
+export declare function checkNoSparseCheckoutDocument(file: string, document: unknown, kind: GhaFileKind, errors: string[]): void;