vouchington-tooling 0.53.0 → 0.54.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.
Files changed (187) hide show
  1. package/README.md +76 -12
  2. package/dist/agent-blackboard/index.d.mts +0 -1
  3. package/dist/agent-blackboard/index.mjs +0 -23
  4. package/dist/cli/commands/agent-blackboard-flags.d.mts +0 -1
  5. package/dist/cli/commands/agent-blackboard-flags.mjs +0 -9
  6. package/dist/cli/commands/agent-blackboard.d.mts +0 -2
  7. package/dist/cli/commands/agent-blackboard.mjs +7 -121
  8. package/dist/cli/commands/story-coverage.d.mts +2 -0
  9. package/dist/cli/commands/story-coverage.mjs +56 -0
  10. package/dist/cli/index.mjs +6 -0
  11. package/dist/cli/parse-forwarded-commands.d.mts +3 -0
  12. package/dist/cli/parse-forwarded-commands.mjs +2 -0
  13. package/dist/cli/parse-story-coverage-fields.d.mts +19 -0
  14. package/dist/cli/parse-story-coverage-fields.mjs +69 -0
  15. package/dist/cli/parse-story-coverage.d.mts +8 -0
  16. package/dist/cli/parse-story-coverage.mjs +34 -0
  17. package/dist/cli/parse.d.mts +5 -1
  18. package/dist/cli/parse.mjs +3 -0
  19. package/dist/cli/usage.d.mts +1 -1
  20. package/dist/cli/usage.mjs +8 -7
  21. package/dist/host-storage/check.d.mts +38 -0
  22. package/dist/host-storage/check.mjs +109 -0
  23. package/dist/host-storage/cli.d.mts +7 -0
  24. package/dist/host-storage/cli.mjs +102 -0
  25. package/dist/host-storage/host-storage.test-helpers.d.mts +26 -0
  26. package/dist/host-storage/host-storage.test-helpers.mjs +58 -0
  27. package/dist/host-storage/index.d.mts +3 -0
  28. package/dist/host-storage/index.mjs +3 -0
  29. package/dist/host-storage/preflight.d.mts +22 -0
  30. package/dist/host-storage/preflight.mjs +105 -0
  31. package/dist/index.d.mts +2 -0
  32. package/dist/index.mjs +1 -0
  33. package/dist/playwright/assertions.d.mts +1 -0
  34. package/dist/playwright/assertions.mjs +5 -0
  35. package/dist/playwright/blocked-external-network.d.mts +15 -0
  36. package/dist/playwright/blocked-external-network.mjs +73 -0
  37. package/dist/playwright/browser-dialog-issues.d.mts +12 -0
  38. package/dist/playwright/browser-dialog-issues.mjs +29 -0
  39. package/dist/playwright/browser-errors.d.mts +22 -0
  40. package/dist/playwright/browser-errors.mjs +130 -0
  41. package/dist/playwright/browser-issue-monitor.test-helpers.d.mts +31 -0
  42. package/dist/playwright/browser-issue-monitor.test-helpers.mjs +51 -0
  43. package/dist/playwright/browser-issue-records.d.mts +42 -0
  44. package/dist/playwright/browser-issue-records.mjs +148 -0
  45. package/dist/playwright/browser-test.d.mts +21 -0
  46. package/dist/playwright/browser-test.mjs +68 -0
  47. package/dist/playwright/expect-no-broken-images.d.mts +17 -0
  48. package/dist/playwright/expect-no-broken-images.mjs +39 -0
  49. package/dist/playwright/index.d.mts +30 -0
  50. package/dist/playwright/index.mjs +22 -0
  51. package/dist/playwright/mobile-assertions.d.mts +14 -0
  52. package/dist/playwright/mobile-assertions.mjs +43 -0
  53. package/dist/playwright/navigate-to.d.mts +27 -0
  54. package/dist/playwright/navigate-to.mjs +39 -0
  55. package/dist/playwright/radix-select.d.mts +18 -0
  56. package/dist/playwright/radix-select.mjs +19 -0
  57. package/dist/playwright/random-id.d.mts +34 -0
  58. package/dist/playwright/random-id.mjs +37 -0
  59. package/dist/playwright/retry-on-connection-lost.d.mts +7 -0
  60. package/dist/playwright/retry-on-connection-lost.mjs +107 -0
  61. package/dist/playwright/scroll-to-load-more.d.mts +37 -0
  62. package/dist/playwright/scroll-to-load-more.mjs +158 -0
  63. package/dist/playwright/storybook.d.mts +2 -0
  64. package/dist/playwright/storybook.mjs +13 -0
  65. package/dist/playwright/test-fixtures.d.mts +1 -0
  66. package/dist/playwright/test-fixtures.mjs +2 -0
  67. package/dist/playwright/test-lifecycle-reporter.d.mts +11 -0
  68. package/dist/playwright/test-lifecycle-reporter.mjs +35 -0
  69. package/dist/playwright/totp.d.mts +6 -0
  70. package/dist/playwright/totp.mjs +37 -0
  71. package/dist/playwright/turnstile-stub.d.mts +8 -0
  72. package/dist/playwright/turnstile-stub.mjs +61 -0
  73. package/dist/playwright/viewport-constants.d.mts +30 -0
  74. package/dist/playwright/viewport-constants.mjs +9 -0
  75. package/dist/playwright/virtual-authenticator.d.mts +5 -0
  76. package/dist/playwright/virtual-authenticator.mjs +15 -0
  77. package/dist/playwright/wait-for-hydration.d.mts +29 -0
  78. package/dist/playwright/wait-for-hydration.mjs +81 -0
  79. package/dist/shell-parse/ansi-c-string.d.mts +12 -0
  80. package/dist/shell-parse/ansi-c-string.mjs +80 -0
  81. package/dist/shell-parse/index.d.mts +20 -0
  82. package/dist/shell-parse/index.mjs +15 -0
  83. package/dist/shell-parse/shell-command-substitution-reads.d.mts +8 -0
  84. package/dist/shell-parse/shell-command-substitution-reads.mjs +53 -0
  85. package/dist/shell-parse/shell-command-substitutions.d.mts +8 -0
  86. package/dist/shell-parse/shell-command-substitutions.mjs +52 -0
  87. package/dist/shell-parse/shell-command-wrappers.d.mts +26 -0
  88. package/dist/shell-parse/shell-command-wrappers.mjs +143 -0
  89. package/dist/shell-parse/shell-commands.d.mts +24 -0
  90. package/dist/shell-parse/shell-commands.mjs +155 -0
  91. package/dist/shell-parse/shell-heredoc-delimiter.d.mts +5 -0
  92. package/dist/shell-parse/shell-heredoc-delimiter.mjs +52 -0
  93. package/dist/shell-parse/shell-heredoc-parser.d.mts +7 -0
  94. package/dist/shell-parse/shell-heredoc-parser.mjs +49 -0
  95. package/dist/shell-parse/shell-heredoc-quote-state.d.mts +19 -0
  96. package/dist/shell-parse/shell-heredoc-quote-state.mjs +40 -0
  97. package/dist/shell-parse/shell-heredoc.d.mts +10 -0
  98. package/dist/shell-parse/shell-heredoc.mjs +90 -0
  99. package/dist/shell-parse/shell-redirections.d.mts +5 -0
  100. package/dist/shell-parse/shell-redirections.mjs +34 -0
  101. package/dist/shell-parse/shell-script-operand.d.mts +13 -0
  102. package/dist/shell-parse/shell-script-operand.mjs +103 -0
  103. package/dist/shell-parse/shell-stdin-script.d.mts +6 -0
  104. package/dist/shell-parse/shell-stdin-script.mjs +61 -0
  105. package/dist/shell-parse/shell-token-utils.d.mts +9 -0
  106. package/dist/shell-parse/shell-token-utils.mjs +33 -0
  107. package/dist/shell-parse/shell-tokenizer-comments.d.mts +1 -0
  108. package/dist/shell-parse/shell-tokenizer-comments.mjs +57 -0
  109. package/dist/shell-parse/shell-tokenizer-operators.d.mts +14 -0
  110. package/dist/shell-parse/shell-tokenizer-operators.mjs +47 -0
  111. package/dist/shell-parse/shell-tokenizer.d.mts +12 -0
  112. package/dist/shell-parse/shell-tokenizer.mjs +104 -0
  113. package/dist/story-coverage/analyze.d.mts +8 -0
  114. package/dist/story-coverage/analyze.mjs +24 -0
  115. package/dist/story-coverage/check.d.mts +11 -0
  116. package/dist/story-coverage/check.mjs +42 -0
  117. package/dist/story-coverage/components.d.mts +10 -0
  118. package/dist/story-coverage/components.mjs +40 -0
  119. package/dist/story-coverage/coverage.d.mts +10 -0
  120. package/dist/story-coverage/coverage.mjs +43 -0
  121. package/dist/story-coverage/index.d.mts +13 -0
  122. package/dist/story-coverage/index.mjs +7 -0
  123. package/dist/story-coverage/messages.d.mts +10 -0
  124. package/dist/story-coverage/messages.mjs +42 -0
  125. package/dist/story-coverage/options.d.mts +27 -0
  126. package/dist/story-coverage/options.mjs +51 -0
  127. package/dist/story-coverage/workspace.d.mts +2 -0
  128. package/dist/story-coverage/workspace.mjs +27 -0
  129. package/dist/test-helpers/cancel-runs.test-helpers.d.mts +39 -0
  130. package/dist/test-helpers/cancel-runs.test-helpers.mjs +124 -0
  131. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.d.mts +12 -0
  132. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.mjs +68 -0
  133. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.d.mts +18 -0
  134. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.mjs +162 -0
  135. package/dist/vitest-diagnostics/index.d.mts +9 -1
  136. package/dist/vitest-diagnostics/index.mjs +5 -1
  137. package/dist/vitest-diagnostics/vitest-fake-timer-guard.d.mts +6 -0
  138. package/dist/vitest-diagnostics/vitest-fake-timer-guard.mjs +34 -0
  139. package/dist/vitest-diagnostics/vitest-fork-leak-detection.d.mts +1 -0
  140. package/dist/vitest-diagnostics/vitest-fork-leak-detection.mjs +8 -0
  141. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.d.mts +10 -1
  142. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.mjs +43 -2
  143. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.d.mts +50 -0
  144. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.mjs +69 -0
  145. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.d.mts +19 -0
  146. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.mjs +136 -0
  147. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.d.mts +7 -0
  148. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.mjs +54 -0
  149. package/dist/vitest-diagnostics/vitest-network-allowlist-host.d.mts +8 -0
  150. package/dist/vitest-diagnostics/vitest-network-allowlist-host.mjs +48 -0
  151. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.d.mts +14 -0
  152. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.mjs +39 -0
  153. package/dist/vitest-diagnostics/vitest-network-allowlist.d.mts +7 -0
  154. package/dist/vitest-diagnostics/vitest-network-allowlist.mjs +72 -0
  155. package/dist/vitest-diagnostics/vitest-process-resources.d.mts +6 -0
  156. package/dist/vitest-diagnostics/vitest-process-resources.mjs +51 -0
  157. package/dist/vitest-effective-timeout/cap.d.mts +9 -0
  158. package/dist/vitest-effective-timeout/cap.mjs +28 -0
  159. package/dist/vitest-effective-timeout/check-profiles.d.mts +15 -0
  160. package/dist/vitest-effective-timeout/check-profiles.mjs +52 -0
  161. package/dist/vitest-effective-timeout/config-file.d.mts +6 -0
  162. package/dist/vitest-effective-timeout/config-file.mjs +23 -0
  163. package/dist/vitest-effective-timeout/fixtures.d.mts +2 -0
  164. package/dist/vitest-effective-timeout/fixtures.mjs +18 -0
  165. package/dist/vitest-effective-timeout/index.d.mts +7 -0
  166. package/dist/vitest-effective-timeout/index.mjs +4 -0
  167. package/dist/vitest-effective-timeout/profiles.d.mts +10 -0
  168. package/dist/vitest-effective-timeout/profiles.mjs +33 -0
  169. package/dist/vitest-effective-timeout/run-profile.d.mts +31 -0
  170. package/dist/vitest-effective-timeout/run-profile.mjs +95 -0
  171. package/docs/mcp-server.md +2 -13
  172. package/package.json +32 -2
  173. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  174. package/scripts/chromium-launch-probe.d.mts +7 -0
  175. package/scripts/chromium-launch-probe.mjs +101 -0
  176. package/scripts/run-bounded-fixtures/run-bounded-backpressure.py +186 -0
  177. package/scripts/run-bounded-fixtures/run-bounded-merged-output.py +75 -0
  178. package/scripts/run-bounded-fixtures/run-bounded-reset-socket.py +25 -0
  179. package/scripts/run-bounded.py +199 -0
  180. package/scripts/run_bounded_process.py +129 -0
  181. package/scripts/worktree/git-index-lock.sh +16 -0
  182. package/scripts/worktree/git-worktrees.sh +23 -20
  183. package/scripts/worktree/reset-worktree-run.sh +199 -0
  184. package/scripts/worktree/reset-worktree.sh +122 -0
  185. package/skills/blackboard/SKILL.md +4 -64
  186. package/skills/stacked-prs/SKILL.md +1 -1
  187. package/skills/stacked-prs/references/drain.md +2 -2
@@ -1,4 +1,4 @@
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 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 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 harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\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 mcp Serve the agent-blackboard journal tools over stdio (MCP)\n worktree Reclaim finished git worktrees (dry run unless --yes)\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 [--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]\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>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\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 session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\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,\n snapshot_export, 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\nworktree reclaim [--yes] [--json]\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";
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 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 harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\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 an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n worktree Reclaim finished git worktrees (dry run unless --yes)\n story-coverage Check component exports are imported by stories\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]\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>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\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 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,\n snapshot_export, 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\nworktree reclaim [--yes] [--json]\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\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";
2
2
  export declare function printUsage(stream?: NodeJS.WritableStream): void;
3
3
  export declare function commandNames(usage?: string): string[];
4
4
  export declare function commandUsage(command: string, usage?: string): string;
@@ -3,6 +3,7 @@ export const USAGE = `Usage: vouchington <command> [options]
3
3
  Commands:
4
4
  runner-port-policy Print or validate a runner port policy
5
5
  with-host-lock Run a command under a host-wide lock
6
+ host-storage Check free space on caller-supplied paths
6
7
  gha-runtime-audit Audit successful GitHub Actions job runtimes
7
8
  require-up-to-date Require HEAD to include a fetched remote branch
8
9
  fresh-base Classify the worktree against a remote base branch
@@ -45,9 +46,10 @@ Commands:
45
46
  retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts
46
47
  link-skill Link one packaged skill into an explicit consumer directory
47
48
  retrospective-facts Gather immutable facts for a retrospective
48
- agent-blackboard Probe and journal an Agent Blackboard deployment
49
+ agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots
49
50
  mcp Serve the agent-blackboard journal tools over stdio (MCP)
50
51
  worktree Reclaim finished git worktrees (dry run unless --yes)
52
+ story-coverage Check component exports are imported by stories
51
53
 
52
54
  Options:
53
55
  -h, --help Show this help
@@ -67,6 +69,8 @@ with-host-lock
67
69
  [--on-acquire-timeout fail|run-unlocked]
68
70
  -- <command> [args...]
69
71
 
72
+ host-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]
73
+
70
74
  gha-runtime-audit
71
75
  [--repository owner/name] Default GITHUB_REPOSITORY
72
76
  [--branch main]
@@ -120,12 +124,7 @@ link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>
120
124
  retrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]
121
125
  agent-blackboard probe
122
126
  agent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)
123
- agent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]
124
- agent-blackboard journal entries --session-id UUID
125
- agent-blackboard journal status --session-id UUID --outbox-directory PATH
126
- agent-blackboard journal flush --outbox-directory PATH [--session-id UUID]
127
- Interactive journal append requires --outbox-directory PATH.
128
- agent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.
127
+ agent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601
129
128
  agent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{"sessions":N,"entries":N,"records":N,"bytes":N}'
130
129
  agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]
131
130
  mcp
@@ -140,6 +139,8 @@ worktree reclaim [--yes] [--json]
140
139
  Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the
141
140
  branch is merged or closed at exactly HEAD, using git worktree remove (never forced).
142
141
  Skips the main checkout, the current worktree, and locked, bare or detached worktrees.
142
+
143
+ story-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>]
143
144
  `;
144
145
  export function printUsage(stream = process.stdout) {
145
146
  stream.write(USAGE);
@@ -0,0 +1,38 @@
1
+ export declare const HOST_STORAGE_MINIMUM_FREE_BYTES: bigint;
2
+ export interface HostStorageProbeDependencies {
3
+ realpath(path: string): Promise<string>;
4
+ stat(path: string): Promise<{
5
+ dev: bigint;
6
+ }>;
7
+ statfs(path: string): Promise<{
8
+ bavail: bigint;
9
+ bsize: bigint;
10
+ }>;
11
+ }
12
+ export type StorageCandidate = {
13
+ label: string;
14
+ path: string;
15
+ recovery: string;
16
+ required: boolean;
17
+ };
18
+ export type HostStorageIssue = {
19
+ label: string;
20
+ message: string;
21
+ severity: 'error' | 'warning';
22
+ type: 'low-space' | 'probe' | 'resolution';
23
+ };
24
+ export type HostStorageFilesystem = {
25
+ availableBytes: bigint;
26
+ device: bigint;
27
+ labels: string[];
28
+ path: string;
29
+ };
30
+ export type HostStorageResult = {
31
+ filesystems: HostStorageFilesystem[];
32
+ issues: HostStorageIssue[];
33
+ ok: boolean;
34
+ };
35
+ export declare function errorMessage(error: unknown): string;
36
+ export declare function formatGiB(bytes: bigint): string;
37
+ export declare function makeResolutionIssue(candidate: StorageCandidate, detail: string): HostStorageIssue;
38
+ export declare function probeHostStorage(candidates: StorageCandidate[], dependencies: HostStorageProbeDependencies, minimumFreeBytes?: bigint): Promise<HostStorageResult>;
@@ -0,0 +1,109 @@
1
+ export const HOST_STORAGE_MINIMUM_FREE_BYTES = 5n * 1024n ** 3n;
2
+ export function errorMessage(error) {
3
+ return error instanceof Error ? error.message : String(error);
4
+ }
5
+ function shellQuote(value) {
6
+ return `'${value.replaceAll("'", `'"'"'`)}'`;
7
+ }
8
+ export function formatGiB(bytes) {
9
+ const hundredths = (bytes * 100n) / 1024n ** 3n;
10
+ return `${hundredths / 100n}.${(hundredths % 100n).toString().padStart(2, '0')} GiB`;
11
+ }
12
+ export function makeResolutionIssue(candidate, detail) {
13
+ return {
14
+ label: candidate.label,
15
+ message: `Could not resolve host storage for ${candidate.label} (${shellQuote(candidate.path)}): ${detail}. ${candidate.recovery}`,
16
+ severity: candidate.required ? 'error' : 'warning',
17
+ type: 'resolution',
18
+ };
19
+ }
20
+ function makeProbeIssue(candidate, detail) {
21
+ return {
22
+ label: candidate.label,
23
+ message: `Could not measure free host storage for ${candidate.label} (${shellQuote(candidate.path)}): ${detail}. Inspect it with: df -h ${shellQuote(candidate.path)}. ${candidate.recovery}`,
24
+ severity: candidate.required ? 'error' : 'warning',
25
+ type: 'probe',
26
+ };
27
+ }
28
+ function makeLowSpaceIssue(filesystem, label, recovery, minimumFreeBytes) {
29
+ return {
30
+ label,
31
+ message: `Insufficient host storage for ${filesystem.labels.join(', ')}: ${formatGiB(filesystem.availableBytes)} free; ${formatGiB(minimumFreeBytes)} required. Inspect it with: df -h ${shellQuote(filesystem.path)}. ${recovery}`,
32
+ severity: 'error',
33
+ type: 'low-space',
34
+ };
35
+ }
36
+ async function resolveCandidate(candidate, dependencies) {
37
+ let resolvedPath;
38
+ try {
39
+ resolvedPath = await dependencies.realpath(candidate.path);
40
+ }
41
+ catch (err) {
42
+ return { issue: makeResolutionIssue(candidate, errorMessage(err)) };
43
+ }
44
+ try {
45
+ const pathStat = await dependencies.stat(resolvedPath);
46
+ return { resolved: { ...candidate, device: pathStat.dev, resolvedPath } };
47
+ }
48
+ catch (err) {
49
+ return { issue: makeProbeIssue({ ...candidate, path: resolvedPath }, errorMessage(err)) };
50
+ }
51
+ }
52
+ function groupResolved(resolved) {
53
+ const groups = [];
54
+ for (const candidate of resolved) {
55
+ const group = groups.find((item) => item.representative.device === candidate.device);
56
+ if (group) {
57
+ group.candidates.push(candidate);
58
+ continue;
59
+ }
60
+ groups.push({ candidates: [candidate], representative: candidate });
61
+ }
62
+ return groups;
63
+ }
64
+ async function probeFilesystem(group, dependencies, minimumFreeBytes) {
65
+ const { candidates, representative } = group;
66
+ let availableBytes;
67
+ try {
68
+ const filesystem = await dependencies.statfs(representative.resolvedPath);
69
+ availableBytes = filesystem.bavail * filesystem.bsize;
70
+ }
71
+ catch (err) {
72
+ const required = candidates.some((candidate) => candidate.required);
73
+ return {
74
+ issues: [
75
+ makeProbeIssue({
76
+ label: candidates.map((candidate) => candidate.label).join(', '),
77
+ path: representative.resolvedPath,
78
+ recovery: required
79
+ ? 'Free host storage or repair access to this filesystem, then retry.'
80
+ : representative.recovery,
81
+ required,
82
+ }, errorMessage(err)),
83
+ ],
84
+ };
85
+ }
86
+ const filesystem = {
87
+ availableBytes,
88
+ device: representative.device,
89
+ labels: candidates.map((candidate) => candidate.label),
90
+ path: representative.resolvedPath,
91
+ };
92
+ const issues = availableBytes < minimumFreeBytes
93
+ ? [
94
+ makeLowSpaceIssue(filesystem, representative.label, [...new Set(candidates.map((candidate) => candidate.recovery))].join(' '), minimumFreeBytes),
95
+ ]
96
+ : [];
97
+ return { filesystem, issues };
98
+ }
99
+ export async function probeHostStorage(candidates, dependencies, minimumFreeBytes = HOST_STORAGE_MINIMUM_FREE_BYTES) {
100
+ const resolutions = await Promise.all(candidates.map((candidate) => resolveCandidate(candidate, dependencies)));
101
+ const issues = resolutions.flatMap((result) => (result.issue ? [result.issue] : []));
102
+ const probes = await Promise.all(groupResolved(resolutions.flatMap((result) => (result.resolved ? [result.resolved] : []))).map((group) => probeFilesystem(group, dependencies, minimumFreeBytes)));
103
+ issues.push(...probes.flatMap((probe) => probe.issues));
104
+ return {
105
+ filesystems: probes.flatMap((probe) => (probe.filesystem ? [probe.filesystem] : [])),
106
+ issues,
107
+ ok: !issues.some((issue) => issue.severity === 'error'),
108
+ };
109
+ }
@@ -0,0 +1,7 @@
1
+ import { type HostStorageDependencies, type HostStorageInspectOptions } from './preflight.mts';
2
+ export type HostStorageOutput = {
3
+ error(message: string): void;
4
+ log(message: string): void;
5
+ };
6
+ export declare function parseHostStorageCliArguments(args: string[]): HostStorageInspectOptions;
7
+ export declare function runHostStoragePreflightCli(args: string[], dependencies?: HostStorageDependencies, output?: HostStorageOutput): Promise<number>;
@@ -0,0 +1,102 @@
1
+ import { formatGiB, HOST_STORAGE_MINIMUM_FREE_BYTES, errorMessage } from "./check.mjs";
2
+ import { inspectHostStorage, MAX_DISCOVERY_TIMEOUT_MS, } from "./preflight.mjs";
3
+ const RECOVERY = 'Free host storage, then retry.';
4
+ export function parseHostStorageCliArguments(args) {
5
+ const paths = [];
6
+ let minimumFreeBytes;
7
+ let discoveryTimeoutMs;
8
+ let dockerDesktopPath;
9
+ let discoverPnpmStore = false;
10
+ let discoverDockerRoot = false;
11
+ let index = 0;
12
+ while (index < args.length) {
13
+ const arg = args[index];
14
+ if (arg === '--pnpm-store') {
15
+ discoverPnpmStore = true;
16
+ index += 1;
17
+ continue;
18
+ }
19
+ if (arg === '--docker-root') {
20
+ discoverDockerRoot = true;
21
+ index += 1;
22
+ continue;
23
+ }
24
+ if (arg === '--path' ||
25
+ arg === '--minimum-free-bytes' ||
26
+ arg === '--discovery-timeout-ms' ||
27
+ arg === '--docker-desktop-path') {
28
+ const value = readFlagValue(args, index, arg);
29
+ index += 2;
30
+ if (arg === '--path') {
31
+ paths.push({ label: value, path: value, recovery: RECOVERY, required: true });
32
+ }
33
+ else if (arg === '--docker-desktop-path') {
34
+ dockerDesktopPath = value;
35
+ }
36
+ else if (arg === '--discovery-timeout-ms') {
37
+ discoveryTimeoutMs = parsePositiveInteger(value, arg);
38
+ }
39
+ else {
40
+ minimumFreeBytes = parseNonNegativeBigint(value, arg);
41
+ }
42
+ continue;
43
+ }
44
+ throw new Error(`unknown argument: ${arg}`);
45
+ }
46
+ if (paths.length === 0)
47
+ throw new Error('--path requires a path');
48
+ return {
49
+ discoverDockerRoot,
50
+ discoverPnpmStore,
51
+ paths,
52
+ ...(minimumFreeBytes === undefined ? {} : { minimumFreeBytes }),
53
+ ...(discoveryTimeoutMs === undefined ? {} : { discoveryTimeoutMs }),
54
+ ...(dockerDesktopPath === undefined ? {} : { dockerDesktopPath }),
55
+ };
56
+ }
57
+ function readFlagValue(args, index, flag) {
58
+ const value = args[index + 1];
59
+ if (value === undefined || value.startsWith('--'))
60
+ throw new Error(`${flag} requires a value`);
61
+ return value;
62
+ }
63
+ function parsePositiveInteger(value, flag) {
64
+ if (!/^[1-9]\d*$/.test(value))
65
+ throw new Error(`${flag} requires a positive integer`);
66
+ const parsed = Number(value);
67
+ if (!Number.isSafeInteger(parsed) || parsed > MAX_DISCOVERY_TIMEOUT_MS) {
68
+ throw new Error(`${flag} requires a positive integer no greater than ${MAX_DISCOVERY_TIMEOUT_MS}`);
69
+ }
70
+ return parsed;
71
+ }
72
+ function parseNonNegativeBigint(value, flag) {
73
+ if (!/^\d+$/.test(value))
74
+ throw new Error(`${flag} requires a whole number`);
75
+ return BigInt(value);
76
+ }
77
+ export async function runHostStoragePreflightCli(args, dependencies, output = console) {
78
+ let options;
79
+ try {
80
+ options = parseHostStorageCliArguments(args);
81
+ }
82
+ catch (err) {
83
+ output.error(`Host storage preflight usage error: ${errorMessage(err)}`);
84
+ return 2;
85
+ }
86
+ try {
87
+ const result = dependencies === undefined
88
+ ? await inspectHostStorage(options)
89
+ : await inspectHostStorage(options, dependencies);
90
+ for (const issue of result.issues) {
91
+ output.error(`${issue.severity === 'error' ? 'Error' : 'Warning'}: ${issue.message}`);
92
+ }
93
+ if (!result.ok)
94
+ return 1;
95
+ output.log(`Host storage preflight passed: ${formatGiB(options.minimumFreeBytes ?? HOST_STORAGE_MINIMUM_FREE_BYTES)} minimum free.`);
96
+ return 0;
97
+ }
98
+ catch (err) {
99
+ output.error(`Host storage preflight failed: ${errorMessage(err)}`);
100
+ return 1;
101
+ }
102
+ }
@@ -0,0 +1,26 @@
1
+ import type { HostStorageDependencies } from './preflight.mts';
2
+ import type { StorageCandidate } from './check.mts';
3
+ export type FakeFilesystem = {
4
+ availableBytes: bigint;
5
+ device: bigint;
6
+ };
7
+ export declare function requiredPath(label: string, path: string): StorageCandidate;
8
+ export declare function standardPaths(home?: string, temporaryDirectory?: string, worktree?: string): StorageCandidate[];
9
+ export declare function makeDependencies({ commandResults, filesystems, home, platform, realpathFailures, statFailures, statfsFailures, thrown, }?: {
10
+ commandResults?: Map<string, Error | string>;
11
+ filesystems?: Map<string, FakeFilesystem>;
12
+ home?: string;
13
+ platform?: NodeJS.Platform;
14
+ realpathFailures?: Set<string>;
15
+ statFailures?: Set<string>;
16
+ statfsFailures?: Set<string>;
17
+ thrown?: Map<string, unknown>;
18
+ }): {
19
+ commandCalls: {
20
+ args: string[];
21
+ command: string;
22
+ timeout: number;
23
+ }[];
24
+ dependencies: HostStorageDependencies;
25
+ statfsCalls: string[];
26
+ };
@@ -0,0 +1,58 @@
1
+ const RECOVERY = 'Free host storage, then retry.';
2
+ export function requiredPath(label, path) {
3
+ return { label, path, recovery: RECOVERY, required: true };
4
+ }
5
+ export function standardPaths(home = '/home/developer', temporaryDirectory = '/tmp', worktree = '/repo') {
6
+ return [
7
+ requiredPath('worktree', worktree),
8
+ requiredPath('home directory', home),
9
+ requiredPath('temporary directory', temporaryDirectory),
10
+ ];
11
+ }
12
+ export function makeDependencies({ commandResults = new Map(), filesystems = new Map(), home = '/home/developer', platform = 'linux', realpathFailures = new Set(), statFailures = new Set(), statfsFailures = new Set(), thrown = new Map(), } = {}) {
13
+ const commandCalls = [];
14
+ const statfsCalls = [];
15
+ const dependencies = {
16
+ execFile: async (command, args, options) => {
17
+ commandCalls.push({ args, command, timeout: options.timeout });
18
+ const key = `${command} ${args.join(' ')}`;
19
+ const failure = thrown.get(key);
20
+ if (failure !== undefined)
21
+ throw failure;
22
+ const result = commandResults.get(key);
23
+ if (result instanceof Error)
24
+ throw result;
25
+ if (result === undefined)
26
+ throw new Error(`unexpected command: ${key}`);
27
+ return { stdout: result };
28
+ },
29
+ homedir: () => home,
30
+ platform,
31
+ realpath: async (path) => {
32
+ if (realpathFailures.has(path))
33
+ throw new Error(`cannot resolve ${path}`);
34
+ const failure = thrown.get(path);
35
+ if (failure !== undefined)
36
+ throw failure;
37
+ return path;
38
+ },
39
+ stat: async (path) => {
40
+ if (statFailures.has(path))
41
+ throw new Error(`cannot stat ${path}`);
42
+ const filesystem = filesystems.get(path);
43
+ if (!filesystem)
44
+ throw new Error(`missing fake filesystem for ${path}`);
45
+ return { dev: filesystem.device };
46
+ },
47
+ statfs: async (path) => {
48
+ statfsCalls.push(path);
49
+ if (statfsFailures.has(path))
50
+ throw new Error(`cannot statfs ${path}`);
51
+ const filesystem = filesystems.get(path);
52
+ if (!filesystem)
53
+ throw new Error(`missing fake filesystem for ${path}`);
54
+ return { bavail: filesystem.availableBytes, bsize: 1n };
55
+ },
56
+ };
57
+ return { commandCalls, dependencies, statfsCalls };
58
+ }
@@ -0,0 +1,3 @@
1
+ export { HOST_STORAGE_MINIMUM_FREE_BYTES, errorMessage, formatGiB, probeHostStorage, type HostStorageFilesystem, type HostStorageIssue, type HostStorageProbeDependencies, type HostStorageResult, type StorageCandidate, } from './check.mts';
2
+ export { DOCKER_DESKTOP_STORAGE_RELATIVE_PATH, HOST_STORAGE_DISCOVERY_TIMEOUT_MS, MAX_DISCOVERY_TIMEOUT_MS, inspectHostStorage, type HostStorageDependencies, type HostStorageInspectOptions, } from './preflight.mts';
3
+ export { parseHostStorageCliArguments, runHostStoragePreflightCli, type HostStorageOutput, } from './cli.mts';
@@ -0,0 +1,3 @@
1
+ export { HOST_STORAGE_MINIMUM_FREE_BYTES, errorMessage, formatGiB, probeHostStorage, } from "./check.mjs";
2
+ export { DOCKER_DESKTOP_STORAGE_RELATIVE_PATH, HOST_STORAGE_DISCOVERY_TIMEOUT_MS, MAX_DISCOVERY_TIMEOUT_MS, inspectHostStorage, } from "./preflight.mjs";
3
+ export { parseHostStorageCliArguments, runHostStoragePreflightCli, } from "./cli.mjs";
@@ -0,0 +1,22 @@
1
+ import { type HostStorageProbeDependencies, type HostStorageResult, type StorageCandidate } from './check.mts';
2
+ export declare const HOST_STORAGE_DISCOVERY_TIMEOUT_MS = 5000;
3
+ export declare const MAX_DISCOVERY_TIMEOUT_MS = 2147483647;
4
+ export declare const DOCKER_DESKTOP_STORAGE_RELATIVE_PATH = "Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw";
5
+ export interface HostStorageDependencies extends HostStorageProbeDependencies {
6
+ execFile(command: string, args: string[], options: {
7
+ timeout: number;
8
+ }): Promise<{
9
+ stdout: string;
10
+ }>;
11
+ homedir(): string;
12
+ platform: NodeJS.Platform;
13
+ }
14
+ export type HostStorageInspectOptions = {
15
+ discoverDockerRoot?: boolean;
16
+ discoverPnpmStore?: boolean;
17
+ discoveryTimeoutMs?: number;
18
+ dockerDesktopPath?: string;
19
+ minimumFreeBytes?: bigint;
20
+ paths: StorageCandidate[];
21
+ };
22
+ export declare function inspectHostStorage(options: HostStorageInspectOptions, dependencies?: HostStorageDependencies): Promise<HostStorageResult>;
@@ -0,0 +1,105 @@
1
+ import { execFile } from 'node:child_process';
2
+ import { realpath, stat, statfs } from 'node:fs/promises';
3
+ import { homedir, platform } from 'node:os';
4
+ import { join } from 'node:path';
5
+ import { promisify } from 'node:util';
6
+ import { errorMessage, HOST_STORAGE_MINIMUM_FREE_BYTES, makeResolutionIssue, probeHostStorage, } from "./check.mjs";
7
+ export const HOST_STORAGE_DISCOVERY_TIMEOUT_MS = 5_000;
8
+ export const MAX_DISCOVERY_TIMEOUT_MS = 2_147_483_647;
9
+ export const DOCKER_DESKTOP_STORAGE_RELATIVE_PATH = 'Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw';
10
+ const execFileAsync = promisify(execFile);
11
+ const defaultDependencies = {
12
+ execFile: async (command, args, options) => {
13
+ const { stdout } = await execFileAsync(command, args, {
14
+ encoding: 'utf8',
15
+ maxBuffer: 1024 * 1024,
16
+ timeout: options.timeout,
17
+ });
18
+ return { stdout };
19
+ },
20
+ homedir,
21
+ platform: platform(),
22
+ realpath,
23
+ stat: async (path) => ({ dev: (await stat(path, { bigint: true })).dev }),
24
+ statfs: async (path) => {
25
+ const result = await statfs(path, { bigint: true });
26
+ return { bavail: result.bavail, bsize: result.bsize };
27
+ },
28
+ };
29
+ async function discoverCommandPath(command, args, label, recovery, dependencies, timeoutMs) {
30
+ const fallback = { label, path: `${command} ${args.join(' ')}`, recovery, required: false };
31
+ try {
32
+ const { stdout } = await dependencies.execFile(command, args, { timeout: timeoutMs });
33
+ const path = stdout.trim();
34
+ if (!path)
35
+ throw new Error('command returned an empty path');
36
+ return { candidate: { ...fallback, path } };
37
+ }
38
+ catch (err) {
39
+ return { issue: makeResolutionIssue(fallback, errorMessage(err)) };
40
+ }
41
+ }
42
+ function resolveDiscoveryTimeout(timeoutMs) {
43
+ const timeout = timeoutMs ?? HOST_STORAGE_DISCOVERY_TIMEOUT_MS;
44
+ if (!Number.isInteger(timeout) || timeout < 1 || timeout > MAX_DISCOVERY_TIMEOUT_MS) {
45
+ throw new Error(`discoveryTimeoutMs requires an integer from 1 through ${MAX_DISCOVERY_TIMEOUT_MS}`);
46
+ }
47
+ return timeout;
48
+ }
49
+ function dockerDesktopCandidate(path) {
50
+ return {
51
+ label: 'Docker Desktop storage',
52
+ path,
53
+ recovery: 'Review Docker Desktop disk usage and reclaim unused images, containers, or volumes intentionally.',
54
+ required: false,
55
+ };
56
+ }
57
+ async function discoverOptionalStorage(options, dependencies) {
58
+ const candidates = [];
59
+ const issues = [];
60
+ const timeoutMs = resolveDiscoveryTimeout(options.discoveryTimeoutMs);
61
+ if (options.discoverPnpmStore) {
62
+ const result = await discoverCommandPath('pnpm', ['store', 'path'], 'pnpm store', 'Confirm pnpm is installed; after reviewing its contents, `pnpm store prune` can remove unused packages.', dependencies, timeoutMs);
63
+ if (result.candidate)
64
+ candidates.push(result.candidate);
65
+ if (result.issue)
66
+ issues.push(result.issue);
67
+ }
68
+ if (!options.discoverDockerRoot)
69
+ return { candidates, issues };
70
+ if (dependencies.platform === 'darwin') {
71
+ candidates.push(dockerDesktopCandidate(options.dockerDesktopPath ??
72
+ join(dependencies.homedir(), DOCKER_DESKTOP_STORAGE_RELATIVE_PATH)));
73
+ }
74
+ else if (dependencies.platform === 'linux') {
75
+ const result = await discoverCommandPath('docker', ['info', '--format', '{{.DockerRootDir}}'], 'Docker root', 'Run `docker system df`, then reclaim only Docker images, containers, or volumes you have confirmed are unused.', dependencies, timeoutMs);
76
+ if (result.candidate)
77
+ candidates.push(result.candidate);
78
+ if (result.issue)
79
+ issues.push(result.issue);
80
+ }
81
+ else {
82
+ issues.push(makeResolutionIssue({
83
+ label: 'Docker root',
84
+ path: 'Docker host storage',
85
+ recovery: 'Inspect Docker storage using the platform-specific Docker tooling.',
86
+ required: false,
87
+ }, `unsupported host platform ${dependencies.platform}`));
88
+ }
89
+ return { candidates, issues };
90
+ }
91
+ export async function inspectHostStorage(options, dependencies = defaultDependencies) {
92
+ const minimumFreeBytes = options.minimumFreeBytes ?? HOST_STORAGE_MINIMUM_FREE_BYTES;
93
+ const required = await probeHostStorage(options.paths, dependencies, minimumFreeBytes);
94
+ if (!required.ok)
95
+ return required;
96
+ const optional = await discoverOptionalStorage(options, dependencies);
97
+ const result = optional.candidates.length === 0
98
+ ? required
99
+ : await probeHostStorage([...options.paths, ...optional.candidates], dependencies, minimumFreeBytes);
100
+ return {
101
+ ...result,
102
+ issues: [...optional.issues, ...result.issues],
103
+ ok: ![...optional.issues, ...result.issues].some((issue) => issue.severity === 'error'),
104
+ };
105
+ }
package/dist/index.d.mts CHANGED
@@ -107,3 +107,5 @@ export { formatReferenceKey, hasClosingIssueReference, parseClosingIssueReferenc
107
107
  export type { ClosingIssueReference } from './gh-cli/index.mts';
108
108
  export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from './pull-request-diff/index.mts';
109
109
  export type { DiffLineChanges, LargeDiffThresholds } from './pull-request-diff/index.mts';
110
+ export { tokenizeShellWords, tokenizeShellWordsDetailed } from './shell-parse/index.mts';
111
+ export type { ShellWord } from './shell-parse/index.mts';
package/dist/index.mjs CHANGED
@@ -58,3 +58,4 @@ export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from "./gh-cli/i
58
58
  export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from "./gh-cli/index.mjs";
59
59
  export { formatReferenceKey, hasClosingIssueReference, parseClosingIssueReferences, parseNonClosingRefs, } from "./gh-cli/index.mjs";
60
60
  export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from "./pull-request-diff/index.mjs";
61
+ export { tokenizeShellWords, tokenizeShellWordsDetailed } from "./shell-parse/index.mjs";
@@ -0,0 +1 @@
1
+ export declare function requireTestValue<T>(value: T | null | undefined, message: string): T;
@@ -0,0 +1,5 @@
1
+ export function requireTestValue(value, message) {
2
+ if (value === null || value === undefined)
3
+ throw new Error(message);
4
+ return value;
5
+ }
@@ -0,0 +1,15 @@
1
+ import type { BrowserContext, Route } from '@playwright/test';
2
+ import type { BrowserIssueAllowlistEntry } from './browser-issue-records.mts';
3
+ export interface BlockedExternalNetworkRule {
4
+ pattern: RegExp;
5
+ reason: string;
6
+ response: Parameters<Route['fulfill']>[0];
7
+ }
8
+ export declare const BLOCKED_EXTERNAL_NETWORK_RULES: BlockedExternalNetworkRule[];
9
+ export declare function blockedExternalRequestFailureAllowlist(extra?: readonly BrowserIssueAllowlistEntry[], rules?: readonly BlockedExternalNetworkRule[]): BrowserIssueAllowlistEntry[];
10
+ export declare function isBlockedExternalNetworkUrl(url: string, rules?: readonly BlockedExternalNetworkRule[]): boolean;
11
+ /**
12
+ * Playwright prefers the most recently registered matching route, so when two rules match the same
13
+ * URL the later rule in `rules` wins.
14
+ */
15
+ export declare function installBlockedExternalNetwork(context: BrowserContext, rules?: readonly BlockedExternalNetworkRule[]): Promise<() => Promise<void>>;