vouchington-tooling 0.87.1 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -8
- package/dist/agent-blackboard/feedback-journal-audit.mjs +14 -6
- package/dist/agent-blackboard/feedback-journal-sandbox.d.mts +4 -2
- package/dist/agent-blackboard/feedback-journal-sandbox.mjs +14 -6
- package/dist/agent-blackboard/snapshot-cleanup-receipt.d.mts +2 -2
- package/dist/agent-blackboard/snapshot-cleanup-receipt.mjs +20 -12
- package/dist/agent-blackboard/snapshot-partition-cleanup.d.mts +1 -0
- package/dist/agent-blackboard/snapshot-partition-cleanup.mjs +3 -0
- package/dist/agent-blackboard/snapshot-partitions.mjs +1 -1
- package/dist/agent-blackboard/snapshot-types.d.mts +8 -0
- package/dist/audit-journal/audit-block.d.mts +2 -0
- package/dist/audit-journal/audit-block.mjs +13 -8
- package/dist/audit-journal/ci-failures.d.mts +6 -2
- package/dist/audit-journal/ci-failures.mjs +12 -6
- package/dist/audit-journal/journal.d.mts +2 -0
- package/dist/audit-journal/journal.mjs +18 -3
- package/dist/audit-journal/scope.d.mts +25 -0
- package/dist/audit-journal/scope.mjs +47 -0
- package/dist/audit-journal/types.d.mts +3 -0
- package/dist/cli/index.mjs +0 -6
- package/dist/cli/parse-forwarded-commands.d.mts +1 -1
- package/dist/cli/parse-forwarded-commands.mjs +0 -2
- package/dist/cli/parse.d.mts +1 -7
- package/dist/cli/parse.mjs +0 -1
- package/dist/cli/script-paths.mjs +0 -1
- package/dist/cli/usage-text.d.mts +1 -1
- package/dist/cli/usage-text.mjs +0 -6
- package/dist/gh-cli/exec.d.mts +8 -2
- package/dist/gh-cli/exec.mjs +3 -3
- package/dist/gha-review-payload/index.d.mts +0 -2
- package/dist/gha-review-payload/index.mjs +0 -1
- package/dist/index.d.mts +2 -8
- package/dist/index.mjs +1 -4
- package/dist/mcp-server/dispatch.mjs +1 -1
- package/dist/mcp-server/handlers-pr.mjs +1 -1
- package/dist/mcp-server/handlers-snapshot-cleanup.mjs +8 -0
- package/dist/mcp-server/handlers-snapshot-partition.mjs +6 -1
- package/dist/mcp-server/install-info.d.mts +2 -2
- package/dist/mcp-server/install-info.mjs +10 -6
- package/dist/mcp-server/pr-diff-size.d.mts +16 -0
- package/dist/mcp-server/pr-diff-size.mjs +49 -0
- package/dist/mcp-server/pr-live.d.mts +3 -0
- package/dist/mcp-server/pr-live.mjs +8 -2
- package/dist/mcp-server/pr-prepare.mjs +20 -12
- package/dist/mcp-server/server.mjs +2 -1
- package/dist/mcp-server/snapshot-recovery.d.mts +8 -0
- package/dist/mcp-server/snapshot-recovery.mjs +76 -0
- package/dist/mcp-server/snapshot-registry.d.mts +3 -1
- package/dist/mcp-server/snapshot-registry.mjs +3 -1
- package/dist/mcp-server/tools-pr.mjs +2 -1
- package/dist/mcp-server/tools.mjs +16 -5
- package/dist/mcp-server/worktree.mjs +4 -1
- package/docs/mcp-server.md +43 -10
- package/package.json +1 -16
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/agent-workflow/SKILL.md +7 -1
- package/skills/dependabot/SKILL.md +4 -3
- package/skills/final-review/references/orchestrator.md +3 -3
- package/skills/manifest.json +25 -33
- package/skills/planning/SKILL.md +3 -0
- package/skills/retrospective/SKILL.md +2 -1
- package/skills/review-ci-logs/SKILL.md +2 -0
- package/skills/stacked-prs/SKILL.md +8 -2
- package/skills/stacked-prs/references/drain.md +3 -1
- package/skills/triage-loop/SKILL.md +125 -21
- package/skills/triage-loop/references/shepherd.md +45 -0
- package/skills/triage-prs/SKILL.md +15 -18
- package/skills/triage-prs/references/rubric.md +2 -2
- package/skills/triage-sweep/SKILL.md +40 -12
- package/dist/gha-check-run/cli.d.mts +0 -2
- package/dist/gha-check-run/cli.mjs +0 -81
- package/dist/gha-check-run/github.d.mts +0 -30
- package/dist/gha-check-run/github.mjs +0 -63
- package/dist/gha-check-run/index.d.mts +0 -2
- package/dist/gha-check-run/index.mjs +0 -2
- package/dist/gha-claude-post-review/index.d.mts +0 -3
- package/dist/gha-claude-post-review/index.mjs +0 -2
- package/dist/gha-post-review/claude-token.d.mts +0 -25
- package/dist/gha-post-review/claude-token.mjs +0 -109
- package/dist/gha-post-review/cli.d.mts +0 -1
- package/dist/gha-post-review/cli.mjs +0 -22
- package/dist/gha-post-review/github.d.mts +0 -13
- package/dist/gha-post-review/github.mjs +0 -58
- package/dist/gha-post-review/index.d.mts +0 -13
- package/dist/gha-post-review/index.mjs +0 -8
- package/dist/gha-post-review/post.d.mts +0 -24
- package/dist/gha-post-review/post.mjs +0 -39
- package/dist/gha-post-review/pull-io.d.mts +0 -13
- package/dist/gha-post-review/pull-io.mjs +0 -88
- package/dist/gha-post-review/token.d.mts +0 -9
- package/dist/gha-post-review/token.mjs +0 -21
- package/dist/gha-review-payload/cli.d.mts +0 -1
- package/dist/gha-review-payload/cli.mjs +0 -24
- package/dist/gha-review-payload/file.d.mts +0 -7
- package/dist/gha-review-payload/file.mjs +0 -62
- package/scripts/gha/materialize-pr-context.sh +0 -123
- package/skills/ready-and-shepherd/SKILL.md +0 -110
|
@@ -1 +1 @@
|
|
|
1
|
-
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 host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\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 agent-issue-labels Map changed paths to labels; create missing repository labels\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 (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n runner-policy Check workflow runner labels and jobs against a config\n dead-code Gate unused code against a committed jscpd baseline\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 an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n final-review Post, revoke, check, or benchmark multi-pillar final reviews\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\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]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\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 [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\nrunner-policy [--config FILE] [--root DIR]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\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 session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\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]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update, snapshot_export, snapshot_partition,\n snapshot_archive, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\nfinal-review post --repo owner/name --pr N --head-sha SHA --input findings.json [--dry-run]\nfinal-review diff --repo owner/name --pr N\nfinal-review revoke --repo owner/name --pr N\nfinal-review status --repo owner/name --pr N\nfinal-review bench --cases cases.json --prompts DIR --out DIR [--pillar NAME]... [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL]\nfinal-review bench-verifier --cases cases.json --findings-from DIR --prompts DIR --out DIR [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL] [--checker MODEL]\n post renders verified findings as one or more COMMENT reviews (verdict, reviewed SHA and effort in\n the header; inline comments where the diff allows, the rest in the body) and adds the \"final\n approval\" label on Approve or removes it otherwise. It refuses when the head moved. diff prints the pull request\n diff with base and head line numbers on every line, for reviewers to cite. revoke removes\n the label before a re-review. status exits 0 only when the newest final review approved the current\n head and the label is present. bench runs each pillar prompt against labeled cases from a git-free\n snapshot of the pre-merge head and scores recall and precision; --judge grades by claim\n with a model instead of by location. bench-verifier runs only the verifier, one call per case\n and no subagents, on the pillar findings a bench --out DIR saved (each judged-real finding is\n also planted under a second pillar), and scores real findings kept, label recall, severity\n agreement, duplicates merged, and other blocking and high findings confirmed by --checker;\n --prompts is the skill's references directory.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI command in a workflow run block or shell script (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
|
1
|
+
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 host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\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 agent-issue-labels Map changed paths to labels; create missing repository labels\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 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 (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n runner-policy Check workflow runner labels and jobs against a config\n dead-code Gate unused code against a committed jscpd baseline\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\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 an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n final-review Post, revoke, check, or benchmark multi-pillar final reviews\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\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]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\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...]\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\nrunner-policy [--config FILE] [--root DIR]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\nswift-semantic-equal <base> <head> <file.swift>\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 session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\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]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update, snapshot_export, snapshot_partition,\n snapshot_archive, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\nfinal-review post --repo owner/name --pr N --head-sha SHA --input findings.json [--dry-run]\nfinal-review diff --repo owner/name --pr N\nfinal-review revoke --repo owner/name --pr N\nfinal-review status --repo owner/name --pr N\nfinal-review bench --cases cases.json --prompts DIR --out DIR [--pillar NAME]... [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL]\nfinal-review bench-verifier --cases cases.json --findings-from DIR --prompts DIR --out DIR [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL] [--checker MODEL]\n post renders verified findings as one or more COMMENT reviews (verdict, reviewed SHA and effort in\n the header; inline comments where the diff allows, the rest in the body) and adds the \"final\n approval\" label on Approve or removes it otherwise. It refuses when the head moved. diff prints the pull request\n diff with base and head line numbers on every line, for reviewers to cite. revoke removes\n the label before a re-review. status exits 0 only when the newest final review approved the current\n head and the label is present. bench runs each pillar prompt against labeled cases from a git-free\n snapshot of the pre-merge head and scores recall and precision; --judge grades by claim\n with a model instead of by location. bench-verifier runs only the verifier, one call per case\n and no subagents, on the pillar findings a bench --out DIR saved (each judged-real finding is\n also planted under a second pillar), and scores real findings kept, label recall, severity\n agreement, duplicates merged, and other blocking and high findings confirmed by --checker;\n --prompts is the skill's references directory.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI command in a workflow run block or shell script (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
package/dist/cli/usage-text.mjs
CHANGED
|
@@ -34,7 +34,6 @@ Commands:
|
|
|
34
34
|
install-github-release Download a checksum-verified GitHub Release binary
|
|
35
35
|
run-with-timeout Run a command with GNU timeout or a Perl fallback
|
|
36
36
|
lint-links Two-pass lychee: internal links fail, external warn
|
|
37
|
-
materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl
|
|
38
37
|
wait-for-apt-locks Wait until apt/dpkg lock files are free
|
|
39
38
|
install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json
|
|
40
39
|
ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)
|
|
@@ -45,8 +44,6 @@ Commands:
|
|
|
45
44
|
runner-policy Check workflow runner labels and jobs against a config
|
|
46
45
|
dead-code Gate unused code against a committed jscpd baseline
|
|
47
46
|
swift-semantic-equal Compare Swift sources ignoring comments and whitespace
|
|
48
|
-
post-review Post one COMMENT review from a staged payload file
|
|
49
|
-
stage-review-payload Validate a review payload file into a staging directory
|
|
50
47
|
retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts
|
|
51
48
|
link-skill Link one packaged skill into an explicit consumer directory
|
|
52
49
|
retrospective-facts Gather immutable facts for a retrospective
|
|
@@ -120,7 +117,6 @@ clean-workspace
|
|
|
120
117
|
install-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]
|
|
121
118
|
run-with-timeout <timeout-seconds> <kill-after-seconds> <command...>
|
|
122
119
|
lint-links [--offline] [--config PATH] [--glob PATTERN] [files...]
|
|
123
|
-
materialize-pr-context
|
|
124
120
|
wait-for-apt-locks
|
|
125
121
|
install-playwright-chromium-arm64 [name:archive...]
|
|
126
122
|
ghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]
|
|
@@ -131,8 +127,6 @@ verify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MO
|
|
|
131
127
|
runner-policy [--config FILE] [--root DIR]
|
|
132
128
|
dead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...
|
|
133
129
|
swift-semantic-equal <base> <head> <file.swift>
|
|
134
|
-
post-review
|
|
135
|
-
stage-review-payload optional|required <source> <destination>
|
|
136
130
|
retrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]
|
|
137
131
|
link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill
|
|
138
132
|
retrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]
|
package/dist/gh-cli/exec.d.mts
CHANGED
|
@@ -1,9 +1,14 @@
|
|
|
1
|
+
/** Per-call limits: the child is killed after `timeout` ms, and output past `maxBuffer` bytes fails. */
|
|
2
|
+
type CommandLimits = {
|
|
3
|
+
timeout?: number;
|
|
4
|
+
maxBuffer?: number;
|
|
5
|
+
};
|
|
1
6
|
/** A text-mode command runner: argv in, stdout out. Rejects on a non-zero exit. */
|
|
2
|
-
export type RunTextCommand = (args: string[]) => Promise<string>;
|
|
7
|
+
export type RunTextCommand = (args: string[], limits?: CommandLimits) => Promise<string>;
|
|
3
8
|
/** The `child_process.execFile` shape `createCommandRunner` wraps — injectable for tests. */
|
|
4
9
|
export type ExecFileText = (command: string, args: string[], options?: {
|
|
5
10
|
env: NodeJS.ProcessEnv;
|
|
6
|
-
}) => Promise<{
|
|
11
|
+
} & CommandLimits) => Promise<{
|
|
7
12
|
stdout: string;
|
|
8
13
|
}>;
|
|
9
14
|
/**
|
|
@@ -17,3 +22,4 @@ export declare function createCommandRunner(command: string, exec?: ExecFileText
|
|
|
17
22
|
export declare const runGh: RunTextCommand;
|
|
18
23
|
/** Runs `git` and returns its stdout. */
|
|
19
24
|
export declare const runGit: RunTextCommand;
|
|
25
|
+
export {};
|
package/dist/gh-cli/exec.mjs
CHANGED
|
@@ -10,9 +10,9 @@ const MAX_OUTPUT_BYTES = 256 * 1024 * 1024;
|
|
|
10
10
|
* are this factory applied to the two binaries this module cares about. `buildEnv` maps the
|
|
11
11
|
* parent environment to the one the child is spawned with (identity by default).
|
|
12
12
|
*/
|
|
13
|
-
export function createCommandRunner(command, exec = (cmd, args, options) => execFileAsync(cmd, args, {
|
|
14
|
-
return async (args) => {
|
|
15
|
-
const { stdout } = await exec(command, args, { env: buildEnv(process.env) });
|
|
13
|
+
export function createCommandRunner(command, exec = (cmd, args, options) => execFileAsync(cmd, args, { encoding: 'utf8', maxBuffer: MAX_OUTPUT_BYTES, ...options }), buildEnv = (env) => env) {
|
|
14
|
+
return async (args, limits) => {
|
|
15
|
+
const { stdout } = await exec(command, args, { env: buildEnv(process.env), ...limits });
|
|
16
16
|
return stdout;
|
|
17
17
|
};
|
|
18
18
|
}
|
|
@@ -3,5 +3,3 @@ export type { ReviewComment, ReviewSide, SanitizedReview } from './payload.mts';
|
|
|
3
3
|
export { indexReviewFiles, parsePatchCommentable, parseReviewFilesJson } from './diff.mts';
|
|
4
4
|
export type { CommentableIndex, CommentableLine, LineKind, ReviewFile } from './diff.mts';
|
|
5
5
|
export { nearestReviewLine, placeReviewComment, remapReviewComments, rewriteSnappedSuggestion, snapReviewNote, } from './remap.mts';
|
|
6
|
-
export { readRegularReviewPayload, stageReviewPayload, writeStagedOutput } from './file.mts';
|
|
7
|
-
export type { PayloadRequirement } from './file.mts';
|
|
@@ -1,4 +1,3 @@
|
|
|
1
1
|
export { MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, ReviewPayloadError, parseReviewPayload, reviewCommentSubject, } from "./payload.mjs";
|
|
2
2
|
export { indexReviewFiles, parsePatchCommentable, parseReviewFilesJson } from "./diff.mjs";
|
|
3
3
|
export { nearestReviewLine, placeReviewComment, remapReviewComments, rewriteSnappedSuggestion, snapReviewNote, } from "./remap.mjs";
|
|
4
|
-
export { readRegularReviewPayload, stageReviewPayload, writeStagedOutput } from "./file.mjs";
|
package/dist/index.d.mts
CHANGED
|
@@ -68,14 +68,8 @@ export { MissingResponseBodyError, readResponseBody, readResponseBodyAsBuffer, R
|
|
|
68
68
|
export type { ReadResponseBodyOptions } from './http-body/index.mts';
|
|
69
69
|
export { parseAstGrepRuleArgs, runAstGrepRule } from './ast-grep-rule/index.mts';
|
|
70
70
|
export type { AstGrepRuleInvocation, RunAstGrepRuleOptions } from './ast-grep-rule/index.mts';
|
|
71
|
-
export { indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload,
|
|
72
|
-
export type { CommentableIndex, CommentableLine, LineKind,
|
|
73
|
-
export { PostReviewError, requireEnv, runPostReview, runPostReviewCli, postReviewWithTokenFromEnv, } from './gha-post-review/index.mts';
|
|
74
|
-
export type { PostResult, PostReviewIo, PullFile } from './gha-post-review/index.mts';
|
|
75
|
-
/** @deprecated Import Claude helpers from vouchington-tooling/gha-claude-post-review. */
|
|
76
|
-
export { CLAUDE_OIDC_AUDIENCE, createActionsClaudeTokenIo, mintClaudeAppToken, resolveReviewPostToken, revokeClaudeAppToken, withClaudeAppToken, } from './gha-post-review/index.mts';
|
|
77
|
-
/** @deprecated Import Claude helpers from vouchington-tooling/gha-claude-post-review. */
|
|
78
|
-
export type { ClaudeTokenIo, ReviewPostToken } from './gha-post-review/index.mts';
|
|
71
|
+
export { indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, } from './gha-review-payload/index.mts';
|
|
72
|
+
export type { CommentableIndex, CommentableLine, LineKind, ReviewComment, ReviewFile, ReviewSide, SanitizedReview, } from './gha-review-payload/index.mts';
|
|
79
73
|
export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mts';
|
|
80
74
|
export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mts';
|
|
81
75
|
export type { ExpectedTransportIdentity, ObjectSigner, PresignIdentity, TransportControl, } from './coverage-transport/index.mts';
|
package/dist/index.mjs
CHANGED
|
@@ -36,10 +36,7 @@ export { decide, deriveRetryAttempt } from "./transient-retry/index.mjs";
|
|
|
36
36
|
export { escapeSpreadsheetFormula, parseCsvRows, streamCsvRows, stripCsvBom } from "./csv/index.mjs";
|
|
37
37
|
export { MissingResponseBodyError, readResponseBody, readResponseBodyAsBuffer, ResponseBodyTooLargeError, } from "./http-body/index.mjs";
|
|
38
38
|
export { parseAstGrepRuleArgs, runAstGrepRule } from "./ast-grep-rule/index.mjs";
|
|
39
|
-
export { indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload,
|
|
40
|
-
export { PostReviewError, requireEnv, runPostReview, runPostReviewCli, postReviewWithTokenFromEnv, } from "./gha-post-review/index.mjs";
|
|
41
|
-
/** @deprecated Import Claude helpers from vouchington-tooling/gha-claude-post-review. */
|
|
42
|
-
export { CLAUDE_OIDC_AUDIENCE, createActionsClaudeTokenIo, mintClaudeAppToken, resolveReviewPostToken, revokeClaudeAppToken, withClaudeAppToken, } from "./gha-post-review/index.mjs";
|
|
39
|
+
export { indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, } from "./gha-review-payload/index.mjs";
|
|
43
40
|
export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from "./http-link-pagination/index.mjs";
|
|
44
41
|
export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from "./coverage-transport/index.mjs";
|
|
45
42
|
export { EPOCH_PRUNED_AT, normalizeDeployedLayer, pruneDeployedRuntimeDeps, restoreDeployedWorkspacePackages, } from "./pnpm-deploy/index.mjs";
|
|
@@ -40,7 +40,7 @@ const DIAGNOSTIC_HINTS = {
|
|
|
40
40
|
'authentication-rejected': 'the blackboard rejected AGENT_BLACKBOARD_TOKEN',
|
|
41
41
|
'blackboard-unavailable': 'the blackboard could not be reached or returned an error',
|
|
42
42
|
'configuration-invalid': 'AGENT_BLACKBOARD_URL or AGENT_BLACKBOARD_TOKEN is missing or invalid',
|
|
43
|
-
'client-unavailable': 'agent-blackboard is not installed next to vouchington-tooling',
|
|
43
|
+
'client-unavailable': 'agent-blackboard is not installed next to vouchington-tooling; if the install directory was removed, reinstall it first when it lives at a fixed path, then reconnect the server (`/mcp` in Claude Code, or restart Codex)',
|
|
44
44
|
'readback-unconfirmed': 'the write could not be confirmed; retry the same call (same sourceEventId and content)',
|
|
45
45
|
'delivery-timeout': 'delivery timed out; retry the same call (same sourceEventId and content)',
|
|
46
46
|
};
|
|
@@ -15,7 +15,7 @@ function rejectErrors(prepared) {
|
|
|
15
15
|
}
|
|
16
16
|
export const handlePrValidate = async (args, context) => {
|
|
17
17
|
const { body, errors, warnings } = await prepare(args, context, 'validate', readPr(args, false));
|
|
18
|
-
return { body, errors, warnings };
|
|
18
|
+
return { ok: errors.length === 0, body, errors, warnings };
|
|
19
19
|
};
|
|
20
20
|
export const handlePrCreate = async (args, context) => {
|
|
21
21
|
const prepared = await prepare(args, context, 'create', undefined);
|
|
@@ -1,12 +1,20 @@
|
|
|
1
1
|
import { cleanupSnapshotPartitions } from "../agent-blackboard/index.mjs";
|
|
2
2
|
import { loadClient } from "../agent-blackboard/client.mjs";
|
|
3
3
|
import { requiredString } from "./args.mjs";
|
|
4
|
+
import { recoverSnapshot } from "./snapshot-recovery.mjs";
|
|
4
5
|
/**
|
|
5
6
|
* Deletes the files one `snapshot_export` recorded. The caller supplies only the token: the paths
|
|
6
7
|
* and the signed receipt come from the server's own record, and the record is checked against the
|
|
7
8
|
* caller's sessionId and resolved worktree before any filesystem call.
|
|
8
9
|
*/
|
|
9
10
|
export const snapshotCleanup = async (args, context) => {
|
|
11
|
+
if (args.cleanupToken !== undefined && args.recoveryDirectory !== undefined)
|
|
12
|
+
throw new Error('pass exactly one of cleanupToken or recoveryDirectory, not both');
|
|
13
|
+
if (args.recoveryDirectory !== undefined) {
|
|
14
|
+
// After a restart the registry is empty; the signed receipt, not the caller, proves ownership.
|
|
15
|
+
await recoverSnapshot(requiredString(args, 'recoveryDirectory'), context.sessionId, context.worktree);
|
|
16
|
+
return { sessionId: context.sessionId, cleaned: true };
|
|
17
|
+
}
|
|
10
18
|
const token = requiredString(args, 'cleanupToken');
|
|
11
19
|
// Taking the record is synchronous, so a concurrent second call finds the token already spent.
|
|
12
20
|
const record = context.snapshots.take(token, context.sessionId, context.worktree);
|
|
@@ -59,8 +59,13 @@ export const snapshotPartition = async (args, context) => {
|
|
|
59
59
|
// A client that wrote an ownership marker partitions only with its own capability. An export
|
|
60
60
|
// without one came from an older client, whose partitions the in-tree code splits and signs.
|
|
61
61
|
let result;
|
|
62
|
+
// The in-tree receipt is signed with the owner and source file, so a restarted server can
|
|
63
|
+
// prove who the directory belongs to; see `snapshot-recovery.mts`.
|
|
62
64
|
if (record.clientToken === undefined)
|
|
63
|
-
result = await partitionSnapshot(
|
|
65
|
+
result = await partitionSnapshot({
|
|
66
|
+
...options,
|
|
67
|
+
owner: { sessionId: context.sessionId, worktree: context.worktree, source: record.path },
|
|
68
|
+
});
|
|
64
69
|
else if (client.partitionSnapshot)
|
|
65
70
|
result = await client.partitionSnapshot({ ...options, cleanupToken: record.clientToken });
|
|
66
71
|
else
|
|
@@ -7,5 +7,5 @@ export type InstallInfo = {
|
|
|
7
7
|
};
|
|
8
8
|
export declare function captureInstall(version?: string): InstallInfo;
|
|
9
9
|
export declare function describeInstall(install: InstallInfo): string;
|
|
10
|
-
/** The suffix appended to every tool error so a stale or
|
|
11
|
-
export declare function installSuffix(error: unknown, install: InstallInfo): string;
|
|
10
|
+
/** The suffix appended to every tool error so a stale, swapped, or removed install is obvious. */
|
|
11
|
+
export declare function installSuffix(error: unknown, install: InstallInfo, exists?: (path: string) => boolean): string;
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
1
2
|
import { isAbsolute, relative, sep } from 'node:path';
|
|
2
3
|
import { fileURLToPath } from 'node:url';
|
|
3
4
|
import { readInstalledVersion } from "../cli/installed-version.mjs";
|
|
@@ -36,10 +37,13 @@ function isInstallSwapped(error, install) {
|
|
|
36
37
|
const rel = relative(install.location, target);
|
|
37
38
|
return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
|
|
38
39
|
}
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
40
|
+
const RECONNECT = 'reconnect the server (`/mcp` in Claude Code, or restart Codex)';
|
|
41
|
+
/** The suffix appended to every tool error so a stale, swapped, or removed install is obvious. */
|
|
42
|
+
export function installSuffix(error, install, exists = existsSync) {
|
|
43
|
+
let hint = '';
|
|
44
|
+
if (!exists(install.location))
|
|
45
|
+
hint = ` The server's install directory (${install.location}) was removed: if it was installed at a fixed path, reinstall it and its peer dependencies there first, then ${RECONNECT}.`;
|
|
46
|
+
else if (isInstallSwapped(error, install))
|
|
47
|
+
hint = ` The server install changed underneath it: ${RECONNECT}.`;
|
|
48
|
+
return `${hint}\n[${describeInstall(install)}]`;
|
|
45
49
|
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { RunTextCommand } from '../gh-cli/exec.mts';
|
|
2
|
+
import type { LivePullRequest } from './pr-live.mts';
|
|
3
|
+
/** What the policy's `validatePullRequest` learns about the size of the change. */
|
|
4
|
+
export type DiffSize = {
|
|
5
|
+
additions: number;
|
|
6
|
+
deletions: number;
|
|
7
|
+
changedFiles: number;
|
|
8
|
+
source: 'github' | 'git';
|
|
9
|
+
} | {
|
|
10
|
+
unavailable: string;
|
|
11
|
+
};
|
|
12
|
+
export declare const DIFF_MAX_OUTPUT: number;
|
|
13
|
+
/** Sums `git diff --numstat` output; a binary file (`-`) counts as a file with no lines. */
|
|
14
|
+
export declare function parseNumstat(output: string): DiffSize;
|
|
15
|
+
/** GitHub's own counts for a live pull request, else the local numstat. Never throws. */
|
|
16
|
+
export declare function diffFor(git: RunTextCommand, live: LivePullRequest | undefined, base: string): Promise<DiffSize>;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/** The longest the local diff may run, and the most numstat output it may produce. */
|
|
2
|
+
const DIFF_TIMEOUT_MS = 30_000;
|
|
3
|
+
export const DIFF_MAX_OUTPUT = 1024 * 1024;
|
|
4
|
+
/** Sums `git diff --numstat` output; a binary file (`-`) counts as a file with no lines. */
|
|
5
|
+
export function parseNumstat(output) {
|
|
6
|
+
let additions = 0;
|
|
7
|
+
let deletions = 0;
|
|
8
|
+
let changedFiles = 0;
|
|
9
|
+
for (const line of output.split('\n')) {
|
|
10
|
+
if (line === '')
|
|
11
|
+
continue;
|
|
12
|
+
const [added, removed] = line.split('\t');
|
|
13
|
+
changedFiles += 1;
|
|
14
|
+
additions += Number(added) || 0;
|
|
15
|
+
deletions += Number(removed) || 0;
|
|
16
|
+
}
|
|
17
|
+
return { additions, deletions, changedFiles, source: 'git' };
|
|
18
|
+
}
|
|
19
|
+
/** execFile kills the child on its timeout (`killed`, with a signal) and fails on a full buffer. */
|
|
20
|
+
function failureReason(error, base) {
|
|
21
|
+
const { killed, code } = (error ?? {});
|
|
22
|
+
if (killed === true)
|
|
23
|
+
return 'git diff timed out';
|
|
24
|
+
if (code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER')
|
|
25
|
+
return 'git diff output too large';
|
|
26
|
+
return `git diff origin/${base}...HEAD failed`;
|
|
27
|
+
}
|
|
28
|
+
/** The change a pull request with no live counterpart would carry: `origin/<base>...HEAD`. */
|
|
29
|
+
async function localDiff(git, base) {
|
|
30
|
+
try {
|
|
31
|
+
const output = await git(['diff', '--numstat', '--no-ext-diff', `origin/${base}...HEAD`, '--'], {
|
|
32
|
+
timeout: DIFF_TIMEOUT_MS,
|
|
33
|
+
maxBuffer: DIFF_MAX_OUTPUT,
|
|
34
|
+
});
|
|
35
|
+
if (output.length > DIFF_MAX_OUTPUT)
|
|
36
|
+
return { unavailable: 'git diff output too large' };
|
|
37
|
+
return parseNumstat(output);
|
|
38
|
+
}
|
|
39
|
+
catch (error) {
|
|
40
|
+
return { unavailable: failureReason(error, base) };
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/** GitHub's own counts for a live pull request, else the local numstat. Never throws. */
|
|
44
|
+
export async function diffFor(git, live, base) {
|
|
45
|
+
if (live === undefined)
|
|
46
|
+
return localDiff(git, base);
|
|
47
|
+
const { additions, deletions, changedFiles } = live;
|
|
48
|
+
return { additions, deletions, changedFiles, source: 'github' };
|
|
49
|
+
}
|
|
@@ -5,6 +5,9 @@ export type LivePullRequest = {
|
|
|
5
5
|
headRefOid: string;
|
|
6
6
|
baseRefName: string;
|
|
7
7
|
state: string;
|
|
8
|
+
additions: number;
|
|
9
|
+
deletions: number;
|
|
10
|
+
changedFiles: number;
|
|
8
11
|
};
|
|
9
12
|
/** The live pull request as gh reports it, whatever its state. */
|
|
10
13
|
export declare function readLivePullRequest(gh: RunTextCommand, pr: number): Promise<LivePullRequest>;
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { findShepherdJournal } from "./pr-journal.mjs";
|
|
2
|
-
const
|
|
2
|
+
const TEXT_FIELDS = ['body', 'headRefName', 'headRefOid', 'baseRefName', 'state'];
|
|
3
|
+
const COUNT_FIELDS = ['additions', 'deletions', 'changedFiles'];
|
|
4
|
+
const FIELDS = [...TEXT_FIELDS, ...COUNT_FIELDS];
|
|
3
5
|
/** The live pull request as gh reports it, whatever its state. */
|
|
4
6
|
export async function readLivePullRequest(gh, pr) {
|
|
5
7
|
const output = await gh(['pr', 'view', String(pr), '--json', FIELDS.join(',')]);
|
|
@@ -17,7 +19,11 @@ export async function livePullRequest(gh, pr) {
|
|
|
17
19
|
return live;
|
|
18
20
|
}
|
|
19
21
|
function isLive(value) {
|
|
20
|
-
return
|
|
22
|
+
return (TEXT_FIELDS.every((field) => typeof value?.[field] === 'string') &&
|
|
23
|
+
COUNT_FIELDS.every((field) => {
|
|
24
|
+
const count = value?.[field];
|
|
25
|
+
return typeof count === 'number' && Number.isSafeInteger(count) && count >= 0;
|
|
26
|
+
}));
|
|
21
27
|
}
|
|
22
28
|
/**
|
|
23
29
|
* The base to validate an existing pull request against: its live base. An explicit `base` that
|
|
@@ -7,11 +7,12 @@ import { createGhRunner, ghEnvironment } from "./pr-gh.mjs";
|
|
|
7
7
|
import { checkTitleLength, readPullRequestInput } from "./pr-input.mjs";
|
|
8
8
|
import { preserveShepherdJournal } from "./pr-journal.mjs";
|
|
9
9
|
import { credentials, liveBase, livePullRequest, readLivePullRequest, redactCredentials, } from "./pr-live.mjs";
|
|
10
|
+
import { diffFor } from "./pr-diff-size.mjs";
|
|
10
11
|
import { noSourceStatement } from "./pr-no-source.mjs";
|
|
11
12
|
import { runValidator } from "./policy-run.mjs";
|
|
12
13
|
import { parseWorktreeList } from "./worktree.mjs";
|
|
13
14
|
export function gitIn(context) {
|
|
14
|
-
return (args) => context.runGit(['-C', context.worktree, ...args]);
|
|
15
|
+
return (args, limits) => context.runGit(['-C', context.worktree, ...args], limits);
|
|
15
16
|
}
|
|
16
17
|
export function ghIn(context) {
|
|
17
18
|
const run = context.runGh ?? createGhRunner(context.env);
|
|
@@ -25,11 +26,10 @@ export function policyFor(context) {
|
|
|
25
26
|
...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
|
|
26
27
|
};
|
|
27
28
|
}
|
|
29
|
+
/** The checked-out branch, or undefined for a detached HEAD. */
|
|
28
30
|
async function currentBranch(git) {
|
|
29
31
|
const branch = (await git(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
|
|
30
|
-
|
|
31
|
-
throw new Error('the worktree has a detached HEAD: check out a branch');
|
|
32
|
-
return branch;
|
|
32
|
+
return branch === 'HEAD' ? undefined : branch;
|
|
33
33
|
}
|
|
34
34
|
async function label(context, git) {
|
|
35
35
|
const listing = await git(['worktree', 'list', '--porcelain', '-z']);
|
|
@@ -43,17 +43,21 @@ async function liveFor(kind, context, pr) {
|
|
|
43
43
|
: readLivePullRequest(ghIn(context), pr);
|
|
44
44
|
}
|
|
45
45
|
/**
|
|
46
|
-
* The head to validate. An update accepts the worktree branch, or an alias branch
|
|
47
|
-
* the live head commit, and then uses the live head name; anything else is rejected.
|
|
46
|
+
* The head to validate. An update accepts the worktree branch, or an alias branch or detached HEAD
|
|
47
|
+
* at the live head commit, and then uses the live head name; anything else is rejected. A detached
|
|
48
|
+
* HEAD (worktreeHead undefined) is only acceptable that way, for an update of a live pull request.
|
|
48
49
|
*/
|
|
49
50
|
async function headFor(kind, git, live, pr, worktreeHead) {
|
|
50
|
-
if (
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
if (live === undefined || kind !== 'update') {
|
|
52
|
+
if (worktreeHead === undefined)
|
|
53
|
+
throw new Error('the worktree has a detached HEAD: check out a branch');
|
|
54
|
+
return worktreeHead;
|
|
55
|
+
}
|
|
56
|
+
if (live.headRefName === worktreeHead)
|
|
53
57
|
return worktreeHead;
|
|
54
58
|
const sha = (await git(['rev-parse', 'HEAD'])).trim();
|
|
55
59
|
if (sha !== live.headRefOid)
|
|
56
|
-
throw new Error(`pull request ${pr} has head ${live.headRefName} at ${live.headRefOid}, not the worktree branch ${worktreeHead} at ${sha}`);
|
|
60
|
+
throw new Error(`pull request ${pr} has head ${live.headRefName} at ${live.headRefOid}, not the worktree ${worktreeHead === undefined ? 'detached HEAD' : `branch ${worktreeHead}`} at ${sha}`);
|
|
57
61
|
return live.headRefName;
|
|
58
62
|
}
|
|
59
63
|
/** Renders the body, preserves the live journal for an update, and runs the policy validator. */
|
|
@@ -67,11 +71,14 @@ export async function prepare(args, context, kind, pr) {
|
|
|
67
71
|
const git = gitIn(context);
|
|
68
72
|
const live = await liveFor(kind, context, pr);
|
|
69
73
|
// A read-only validation of an existing pull request judges the head that pull request has.
|
|
70
|
-
const
|
|
74
|
+
const readOnly = live !== undefined && kind === 'validate';
|
|
75
|
+
const worktreeHead = readOnly ? undefined : await currentBranch(git);
|
|
71
76
|
// The local branch is checked before any diagnostic or alias resolution can echo or drop it.
|
|
72
77
|
if (worktreeHead !== undefined && secrets.some((secret) => worktreeHead.includes(secret)))
|
|
73
78
|
throw new Error('the worktree branch name contains a server credential: rename the branch');
|
|
74
|
-
const head =
|
|
79
|
+
const head = readOnly
|
|
80
|
+
? live.headRefName
|
|
81
|
+
: await headFor(kind, git, live, pr, worktreeHead);
|
|
75
82
|
// Branch names are refs passed to gh as is: redacting one would name a branch that does not exist.
|
|
76
83
|
if (secrets.some((secret) => head.includes(secret)))
|
|
77
84
|
throw new Error('the worktree branch name contains a server credential: rename the branch');
|
|
@@ -109,6 +116,7 @@ export async function prepare(args, context, kind, pr) {
|
|
|
109
116
|
mode: input.mode,
|
|
110
117
|
...(input.noSourceIssue === undefined ? {} : { noSourceIssue: input.noSourceIssue }),
|
|
111
118
|
...(pr === undefined ? {} : { pr }),
|
|
119
|
+
diff: await diffFor(git, live, input.base),
|
|
112
120
|
},
|
|
113
121
|
});
|
|
114
122
|
const errors = 'errors' in report ? report.errors : [];
|
|
@@ -8,7 +8,8 @@ const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consu
|
|
|
8
8
|
'Code mcp__vouchington-tooling__<tool>, Codex mcp__vouchington_tooling__<tool>, Grok ' +
|
|
9
9
|
'vouchington-tooling__<tool> (through search_tool and use_tool), Cursor the vouchington-tooling ' +
|
|
10
10
|
'namespace (through GetDynamicTools and CallDynamicTool). Search for journal_append before ' +
|
|
11
|
-
'concluding this server is unavailable. Tool errors are actionable; do not fall back to a CLI.'
|
|
11
|
+
'concluding this server is unavailable. Tool errors are actionable; do not fall back to a CLI. ' +
|
|
12
|
+
'If the install directory was removed, reinstall it first when it lives at a fixed path, then reconnect the server (`/mcp` in Claude Code, or restart Codex).';
|
|
12
13
|
/**
|
|
13
14
|
* Builds the server. The tool list and call handlers go on the low-level `server` because the
|
|
14
15
|
* high-level `registerTool` path needs zod schemas, and this package keeps zod out of its own code.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Removes a generated partition directory and its source snapshot after a server restart. The
|
|
3
|
+
* caller's path only selects a candidate; deletion follows the signed receipt and reuses the
|
|
4
|
+
* receipt cleanup's own checks (generated names, temp location, no symlinks, directory identity,
|
|
5
|
+
* partition checksums). Every proof failure is one message, so probing learns nothing. The
|
|
6
|
+
* directory is gone afterward, so a second call is rejected, and a concurrent call is too.
|
|
7
|
+
*/
|
|
8
|
+
export declare function recoverSnapshot(directory: unknown, sessionId: string, worktree: string): Promise<void>;
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { constants } from 'node:fs';
|
|
2
|
+
import { lstat, open } from 'node:fs/promises';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { assertGeneratedPartitionDirectory, cleanupSnapshotPartitions, } from "../agent-blackboard/snapshot-partition-cleanup.mjs";
|
|
5
|
+
import { RECEIPT_NAME, verifyCleanupReceipt, } from "../agent-blackboard/snapshot-cleanup-receipt.mjs";
|
|
6
|
+
const REJECTED = 'recoveryDirectory is not a snapshot partition directory this session and worktree generated ' +
|
|
7
|
+
'and this server can still verify; nothing was deleted';
|
|
8
|
+
const MAX_MARKER_BYTES = 64 * 1024;
|
|
9
|
+
const inFlight = new Set();
|
|
10
|
+
/** Reads the owner-only receipt marker through a no-follow descriptor, never a followed link. */
|
|
11
|
+
async function readMarker(directory) {
|
|
12
|
+
const marker = join(directory, RECEIPT_NAME);
|
|
13
|
+
const info = await lstat(marker);
|
|
14
|
+
if (info.isSymbolicLink() || !info.isFile() || info.nlink !== 1 || info.size > MAX_MARKER_BYTES)
|
|
15
|
+
throw new Error('marker is not a regular file');
|
|
16
|
+
const handle = await open(marker, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
17
|
+
try {
|
|
18
|
+
return JSON.parse(await handle.readFile('utf8'));
|
|
19
|
+
}
|
|
20
|
+
finally {
|
|
21
|
+
await handle.close();
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Proves a partition directory is one this server generated for this caller, without any state
|
|
26
|
+
* from before a restart. The directory must be a direct, non-symlink child of the temp directory
|
|
27
|
+
* with the generated name; its marker must carry a valid HMAC signature under the server's
|
|
28
|
+
* persistent key; and the signed owner must equal the caller's sessionId and worktree. Receipts
|
|
29
|
+
* signed without an owner (older ones) are never recoverable.
|
|
30
|
+
*/
|
|
31
|
+
async function proveOwnership(directory, sessionId, worktree) {
|
|
32
|
+
if (typeof directory !== 'string')
|
|
33
|
+
throw new Error('not a path');
|
|
34
|
+
assertGeneratedPartitionDirectory(directory);
|
|
35
|
+
const info = await lstat(directory);
|
|
36
|
+
if (info.isSymbolicLink() || !info.isDirectory())
|
|
37
|
+
throw new Error('not a directory');
|
|
38
|
+
const receipt = (await readMarker(directory));
|
|
39
|
+
await verifyCleanupReceipt(receipt);
|
|
40
|
+
const { owner } = receipt;
|
|
41
|
+
if (receipt.directory !== directory ||
|
|
42
|
+
owner?.sessionId !== sessionId ||
|
|
43
|
+
owner.worktree !== worktree)
|
|
44
|
+
throw new Error('not the owner');
|
|
45
|
+
return receipt;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Removes a generated partition directory and its source snapshot after a server restart. The
|
|
49
|
+
* caller's path only selects a candidate; deletion follows the signed receipt and reuses the
|
|
50
|
+
* receipt cleanup's own checks (generated names, temp location, no symlinks, directory identity,
|
|
51
|
+
* partition checksums). Every proof failure is one message, so probing learns nothing. The
|
|
52
|
+
* directory is gone afterward, so a second call is rejected, and a concurrent call is too.
|
|
53
|
+
*/
|
|
54
|
+
export async function recoverSnapshot(directory, sessionId, worktree) {
|
|
55
|
+
const key = typeof directory === 'string' ? directory : '';
|
|
56
|
+
if (inFlight.has(key))
|
|
57
|
+
throw new Error(REJECTED);
|
|
58
|
+
inFlight.add(key);
|
|
59
|
+
try {
|
|
60
|
+
let receipt;
|
|
61
|
+
try {
|
|
62
|
+
receipt = await proveOwnership(directory, sessionId, worktree);
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
throw new Error(REJECTED);
|
|
66
|
+
}
|
|
67
|
+
await cleanupSnapshotPartitions({
|
|
68
|
+
path: receipt.owner.source,
|
|
69
|
+
directory: receipt.directory,
|
|
70
|
+
receipt,
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
finally {
|
|
74
|
+
inFlight.delete(key);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
@@ -23,6 +23,8 @@ export type SnapshotRegistry = {
|
|
|
23
23
|
export declare const MAX_RECORDS = 256;
|
|
24
24
|
/**
|
|
25
25
|
* Tokens live in memory only. A server restart forgets every binding, so an old token is then
|
|
26
|
-
* rejected as unknown
|
|
26
|
+
* rejected as unknown. A partitioned snapshot can still be removed through `snapshot-recovery.mts`,
|
|
27
|
+
* which proves ownership from the signed receipt on disk; a plain export file has no receipt, so
|
|
28
|
+
* it is left for the operating system to reap from its temp directory.
|
|
27
29
|
*/
|
|
28
30
|
export declare function createSnapshotRegistry(): SnapshotRegistry;
|
|
@@ -3,7 +3,9 @@ export const MAX_RECORDS = 256;
|
|
|
3
3
|
const REJECTED = 'cleanupToken is unknown, already used, or bound to another session or worktree; nothing was deleted';
|
|
4
4
|
/**
|
|
5
5
|
* Tokens live in memory only. A server restart forgets every binding, so an old token is then
|
|
6
|
-
* rejected as unknown
|
|
6
|
+
* rejected as unknown. A partitioned snapshot can still be removed through `snapshot-recovery.mts`,
|
|
7
|
+
* which proves ownership from the signed receipt on disk; a plain export file has no receipt, so
|
|
8
|
+
* it is left for the operating system to reap from its temp directory.
|
|
7
9
|
*/
|
|
8
10
|
export function createSnapshotRegistry() {
|
|
9
11
|
const records = new Map();
|