vouchington-tooling 0.52.1 → 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 (199) hide show
  1. package/README.md +103 -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/commands/worktree.d.mts +2 -0
  11. package/dist/cli/commands/worktree.mjs +21 -0
  12. package/dist/cli/index.mjs +9 -0
  13. package/dist/cli/parse-forwarded-commands.d.mts +6 -0
  14. package/dist/cli/parse-forwarded-commands.mjs +4 -0
  15. package/dist/cli/parse-story-coverage-fields.d.mts +19 -0
  16. package/dist/cli/parse-story-coverage-fields.mjs +69 -0
  17. package/dist/cli/parse-story-coverage.d.mts +8 -0
  18. package/dist/cli/parse-story-coverage.mjs +34 -0
  19. package/dist/cli/parse.d.mts +8 -1
  20. package/dist/cli/parse.mjs +3 -0
  21. package/dist/cli/usage.d.mts +1 -1
  22. package/dist/cli/usage.mjs +14 -7
  23. package/dist/git-worktrees/assess.d.mts +14 -0
  24. package/dist/git-worktrees/assess.mjs +68 -0
  25. package/dist/git-worktrees/list.d.mts +10 -0
  26. package/dist/git-worktrees/list.mjs +34 -0
  27. package/dist/git-worktrees/reclaim.d.mts +15 -0
  28. package/dist/git-worktrees/reclaim.mjs +80 -0
  29. package/dist/git-worktrees/reclaim.test-helpers.d.mts +16 -0
  30. package/dist/git-worktrees/reclaim.test-helpers.mjs +113 -0
  31. package/dist/git-worktrees/run.d.mts +13 -0
  32. package/dist/git-worktrees/run.mjs +50 -0
  33. package/dist/host-storage/check.d.mts +38 -0
  34. package/dist/host-storage/check.mjs +109 -0
  35. package/dist/host-storage/cli.d.mts +7 -0
  36. package/dist/host-storage/cli.mjs +102 -0
  37. package/dist/host-storage/host-storage.test-helpers.d.mts +26 -0
  38. package/dist/host-storage/host-storage.test-helpers.mjs +58 -0
  39. package/dist/host-storage/index.d.mts +3 -0
  40. package/dist/host-storage/index.mjs +3 -0
  41. package/dist/host-storage/preflight.d.mts +22 -0
  42. package/dist/host-storage/preflight.mjs +105 -0
  43. package/dist/index.d.mts +2 -0
  44. package/dist/index.mjs +1 -0
  45. package/dist/playwright/assertions.d.mts +1 -0
  46. package/dist/playwright/assertions.mjs +5 -0
  47. package/dist/playwright/blocked-external-network.d.mts +15 -0
  48. package/dist/playwright/blocked-external-network.mjs +73 -0
  49. package/dist/playwright/browser-dialog-issues.d.mts +12 -0
  50. package/dist/playwright/browser-dialog-issues.mjs +29 -0
  51. package/dist/playwright/browser-errors.d.mts +22 -0
  52. package/dist/playwright/browser-errors.mjs +130 -0
  53. package/dist/playwright/browser-issue-monitor.test-helpers.d.mts +31 -0
  54. package/dist/playwright/browser-issue-monitor.test-helpers.mjs +51 -0
  55. package/dist/playwright/browser-issue-records.d.mts +42 -0
  56. package/dist/playwright/browser-issue-records.mjs +148 -0
  57. package/dist/playwright/browser-test.d.mts +21 -0
  58. package/dist/playwright/browser-test.mjs +68 -0
  59. package/dist/playwright/expect-no-broken-images.d.mts +17 -0
  60. package/dist/playwright/expect-no-broken-images.mjs +39 -0
  61. package/dist/playwright/index.d.mts +30 -0
  62. package/dist/playwright/index.mjs +22 -0
  63. package/dist/playwright/mobile-assertions.d.mts +14 -0
  64. package/dist/playwright/mobile-assertions.mjs +43 -0
  65. package/dist/playwright/navigate-to.d.mts +27 -0
  66. package/dist/playwright/navigate-to.mjs +39 -0
  67. package/dist/playwright/radix-select.d.mts +18 -0
  68. package/dist/playwright/radix-select.mjs +19 -0
  69. package/dist/playwright/random-id.d.mts +34 -0
  70. package/dist/playwright/random-id.mjs +37 -0
  71. package/dist/playwright/retry-on-connection-lost.d.mts +7 -0
  72. package/dist/playwright/retry-on-connection-lost.mjs +107 -0
  73. package/dist/playwright/scroll-to-load-more.d.mts +37 -0
  74. package/dist/playwright/scroll-to-load-more.mjs +158 -0
  75. package/dist/playwright/storybook.d.mts +2 -0
  76. package/dist/playwright/storybook.mjs +13 -0
  77. package/dist/playwright/test-fixtures.d.mts +1 -0
  78. package/dist/playwright/test-fixtures.mjs +2 -0
  79. package/dist/playwright/test-lifecycle-reporter.d.mts +11 -0
  80. package/dist/playwright/test-lifecycle-reporter.mjs +35 -0
  81. package/dist/playwright/totp.d.mts +6 -0
  82. package/dist/playwright/totp.mjs +37 -0
  83. package/dist/playwright/turnstile-stub.d.mts +8 -0
  84. package/dist/playwright/turnstile-stub.mjs +61 -0
  85. package/dist/playwright/viewport-constants.d.mts +30 -0
  86. package/dist/playwright/viewport-constants.mjs +9 -0
  87. package/dist/playwright/virtual-authenticator.d.mts +5 -0
  88. package/dist/playwright/virtual-authenticator.mjs +15 -0
  89. package/dist/playwright/wait-for-hydration.d.mts +29 -0
  90. package/dist/playwright/wait-for-hydration.mjs +81 -0
  91. package/dist/shell-parse/ansi-c-string.d.mts +12 -0
  92. package/dist/shell-parse/ansi-c-string.mjs +80 -0
  93. package/dist/shell-parse/index.d.mts +20 -0
  94. package/dist/shell-parse/index.mjs +15 -0
  95. package/dist/shell-parse/shell-command-substitution-reads.d.mts +8 -0
  96. package/dist/shell-parse/shell-command-substitution-reads.mjs +53 -0
  97. package/dist/shell-parse/shell-command-substitutions.d.mts +8 -0
  98. package/dist/shell-parse/shell-command-substitutions.mjs +52 -0
  99. package/dist/shell-parse/shell-command-wrappers.d.mts +26 -0
  100. package/dist/shell-parse/shell-command-wrappers.mjs +143 -0
  101. package/dist/shell-parse/shell-commands.d.mts +24 -0
  102. package/dist/shell-parse/shell-commands.mjs +155 -0
  103. package/dist/shell-parse/shell-heredoc-delimiter.d.mts +5 -0
  104. package/dist/shell-parse/shell-heredoc-delimiter.mjs +52 -0
  105. package/dist/shell-parse/shell-heredoc-parser.d.mts +7 -0
  106. package/dist/shell-parse/shell-heredoc-parser.mjs +49 -0
  107. package/dist/shell-parse/shell-heredoc-quote-state.d.mts +19 -0
  108. package/dist/shell-parse/shell-heredoc-quote-state.mjs +40 -0
  109. package/dist/shell-parse/shell-heredoc.d.mts +10 -0
  110. package/dist/shell-parse/shell-heredoc.mjs +90 -0
  111. package/dist/shell-parse/shell-redirections.d.mts +5 -0
  112. package/dist/shell-parse/shell-redirections.mjs +34 -0
  113. package/dist/shell-parse/shell-script-operand.d.mts +13 -0
  114. package/dist/shell-parse/shell-script-operand.mjs +103 -0
  115. package/dist/shell-parse/shell-stdin-script.d.mts +6 -0
  116. package/dist/shell-parse/shell-stdin-script.mjs +61 -0
  117. package/dist/shell-parse/shell-token-utils.d.mts +9 -0
  118. package/dist/shell-parse/shell-token-utils.mjs +33 -0
  119. package/dist/shell-parse/shell-tokenizer-comments.d.mts +1 -0
  120. package/dist/shell-parse/shell-tokenizer-comments.mjs +57 -0
  121. package/dist/shell-parse/shell-tokenizer-operators.d.mts +14 -0
  122. package/dist/shell-parse/shell-tokenizer-operators.mjs +47 -0
  123. package/dist/shell-parse/shell-tokenizer.d.mts +12 -0
  124. package/dist/shell-parse/shell-tokenizer.mjs +104 -0
  125. package/dist/story-coverage/analyze.d.mts +8 -0
  126. package/dist/story-coverage/analyze.mjs +24 -0
  127. package/dist/story-coverage/check.d.mts +11 -0
  128. package/dist/story-coverage/check.mjs +42 -0
  129. package/dist/story-coverage/components.d.mts +10 -0
  130. package/dist/story-coverage/components.mjs +40 -0
  131. package/dist/story-coverage/coverage.d.mts +10 -0
  132. package/dist/story-coverage/coverage.mjs +43 -0
  133. package/dist/story-coverage/index.d.mts +13 -0
  134. package/dist/story-coverage/index.mjs +7 -0
  135. package/dist/story-coverage/messages.d.mts +10 -0
  136. package/dist/story-coverage/messages.mjs +42 -0
  137. package/dist/story-coverage/options.d.mts +27 -0
  138. package/dist/story-coverage/options.mjs +51 -0
  139. package/dist/story-coverage/workspace.d.mts +2 -0
  140. package/dist/story-coverage/workspace.mjs +27 -0
  141. package/dist/test-helpers/cancel-runs.test-helpers.d.mts +39 -0
  142. package/dist/test-helpers/cancel-runs.test-helpers.mjs +124 -0
  143. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.d.mts +12 -0
  144. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.mjs +68 -0
  145. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.d.mts +18 -0
  146. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.mjs +162 -0
  147. package/dist/vitest-diagnostics/index.d.mts +9 -1
  148. package/dist/vitest-diagnostics/index.mjs +5 -1
  149. package/dist/vitest-diagnostics/vitest-fake-timer-guard.d.mts +6 -0
  150. package/dist/vitest-diagnostics/vitest-fake-timer-guard.mjs +34 -0
  151. package/dist/vitest-diagnostics/vitest-fork-leak-detection.d.mts +1 -0
  152. package/dist/vitest-diagnostics/vitest-fork-leak-detection.mjs +8 -0
  153. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.d.mts +10 -1
  154. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.mjs +43 -2
  155. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.d.mts +50 -0
  156. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.mjs +69 -0
  157. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.d.mts +19 -0
  158. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.mjs +136 -0
  159. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.d.mts +7 -0
  160. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.mjs +54 -0
  161. package/dist/vitest-diagnostics/vitest-network-allowlist-host.d.mts +8 -0
  162. package/dist/vitest-diagnostics/vitest-network-allowlist-host.mjs +48 -0
  163. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.d.mts +14 -0
  164. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.mjs +39 -0
  165. package/dist/vitest-diagnostics/vitest-network-allowlist.d.mts +7 -0
  166. package/dist/vitest-diagnostics/vitest-network-allowlist.mjs +72 -0
  167. package/dist/vitest-diagnostics/vitest-process-resources.d.mts +6 -0
  168. package/dist/vitest-diagnostics/vitest-process-resources.mjs +51 -0
  169. package/dist/vitest-effective-timeout/cap.d.mts +9 -0
  170. package/dist/vitest-effective-timeout/cap.mjs +28 -0
  171. package/dist/vitest-effective-timeout/check-profiles.d.mts +15 -0
  172. package/dist/vitest-effective-timeout/check-profiles.mjs +52 -0
  173. package/dist/vitest-effective-timeout/config-file.d.mts +6 -0
  174. package/dist/vitest-effective-timeout/config-file.mjs +23 -0
  175. package/dist/vitest-effective-timeout/fixtures.d.mts +2 -0
  176. package/dist/vitest-effective-timeout/fixtures.mjs +18 -0
  177. package/dist/vitest-effective-timeout/index.d.mts +7 -0
  178. package/dist/vitest-effective-timeout/index.mjs +4 -0
  179. package/dist/vitest-effective-timeout/profiles.d.mts +10 -0
  180. package/dist/vitest-effective-timeout/profiles.mjs +33 -0
  181. package/dist/vitest-effective-timeout/run-profile.d.mts +31 -0
  182. package/dist/vitest-effective-timeout/run-profile.mjs +95 -0
  183. package/docs/mcp-server.md +2 -13
  184. package/package.json +32 -2
  185. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  186. package/scripts/chromium-launch-probe.d.mts +7 -0
  187. package/scripts/chromium-launch-probe.mjs +101 -0
  188. package/scripts/run-bounded-fixtures/run-bounded-backpressure.py +186 -0
  189. package/scripts/run-bounded-fixtures/run-bounded-merged-output.py +75 -0
  190. package/scripts/run-bounded-fixtures/run-bounded-reset-socket.py +25 -0
  191. package/scripts/run-bounded.py +199 -0
  192. package/scripts/run_bounded_process.py +129 -0
  193. package/scripts/worktree/git-index-lock.sh +16 -0
  194. package/scripts/worktree/git-worktrees.sh +23 -20
  195. package/scripts/worktree/reset-worktree-run.sh +199 -0
  196. package/scripts/worktree/reset-worktree.sh +122 -0
  197. package/skills/blackboard/SKILL.md +4 -64
  198. package/skills/stacked-prs/SKILL.md +1 -1
  199. package/skills/stacked-prs/references/drain.md +2 -2
@@ -0,0 +1,8 @@
1
+ import { type ParsedStoryCoverage } from './parse-story-coverage-fields.mts';
2
+ export type { ParsedStoryCoverage };
3
+ export declare function parseStoryCoverage(args: readonly string[]): ParsedStoryCoverage | {
4
+ kind: 'help';
5
+ } | {
6
+ kind: 'error';
7
+ message: string;
8
+ };
@@ -0,0 +1,34 @@
1
+ import { applyFlag, emptyParsed, missingField, } from "./parse-story-coverage-fields.mjs";
2
+ const FLAGS = new Set([
3
+ '--root',
4
+ '--component-root',
5
+ '--story-root',
6
+ '--alias',
7
+ '--source-extension',
8
+ '--component-extension',
9
+ '--marker',
10
+ '--story-pattern',
11
+ '--exclusions',
12
+ '--exclusions-label',
13
+ ]);
14
+ export function parseStoryCoverage(args) {
15
+ if (args.length === 0)
16
+ return { kind: 'error', message: 'story-coverage requires --root' };
17
+ if (args.includes('--help') || args.includes('-h'))
18
+ return { kind: 'help' };
19
+ const parsed = emptyParsed();
20
+ for (let index = 0; index < args.length; index += 1) {
21
+ const flag = args[index] ?? '';
22
+ if (!FLAGS.has(flag))
23
+ return { kind: 'error', message: `unknown story-coverage option: ${flag}` };
24
+ const value = args[index + 1];
25
+ if (value === undefined || value.startsWith('--')) {
26
+ return { kind: 'error', message: `${flag} requires a value` };
27
+ }
28
+ index += 1;
29
+ const invalid = applyFlag(parsed, flag, value);
30
+ if (invalid)
31
+ return { kind: 'error', message: invalid };
32
+ }
33
+ return missingField(parsed) ?? parsed;
34
+ }
@@ -1,4 +1,5 @@
1
1
  import { type ParsedGhaArtifactsCleanup } from './parse-gha-artifacts-cleanup.mts';
2
+ import { type ParsedStoryCoverage } from './parse-story-coverage.mts';
2
3
  import { type ParsedGhaRuntimeAudit } from './parse-gha-runtime-audit.mts';
3
4
  export type ParsedCli = {
4
5
  kind: 'help';
@@ -17,6 +18,9 @@ export type ParsedCli = {
17
18
  } | {
18
19
  kind: 'with-host-lock';
19
20
  args: string[];
21
+ } | {
22
+ kind: 'host-storage';
23
+ args: string[];
20
24
  } | {
21
25
  kind: 'script';
22
26
  command: ScriptCommand;
@@ -66,6 +70,9 @@ export type ParsedCli = {
66
70
  } | {
67
71
  kind: 'mcp';
68
72
  args: string[];
73
+ } | {
74
+ kind: 'worktree';
75
+ args: string[];
69
76
  } | {
70
77
  kind: 'require-up-to-date';
71
78
  remote: string;
@@ -90,7 +97,7 @@ export type ParsedCli = {
90
97
  root?: string;
91
98
  workflowDirectories?: string[];
92
99
  actionDirectories?: string[];
93
- } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
100
+ } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup | ParsedStoryCoverage;
94
101
  export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'harness-assert-gates' | 'gha-collaborator-trust';
95
102
  export declare function parseCli(argv: readonly string[]): ParsedCli;
96
103
  export declare function parseCommandHelp(command: string | undefined, rest: readonly string[]): {
@@ -1,4 +1,5 @@
1
1
  import { parseGhaArtifactsCleanup, } from "./parse-gha-artifacts-cleanup.mjs";
2
+ import { parseStoryCoverage } from "./parse-story-coverage.mjs";
2
3
  import { parseGhaRuntimeAudit } from "./parse-gha-runtime-audit.mjs";
3
4
  import { parseForwardedCommand } from "./parse-forwarded-commands.mjs";
4
5
  import { parseFreshBase } from "./parse-fresh-base.mjs";
@@ -63,6 +64,8 @@ export function parseCli(argv) {
63
64
  return parseGhaWorkspacePolicy(rest);
64
65
  if (command === 'gha-artifacts-cleanup')
65
66
  return parseGhaArtifactsCleanup(rest);
67
+ if (command === 'story-coverage')
68
+ return parseStoryCoverage(rest);
66
69
  if (command !== undefined && SCRIPT_COMMANDS.has(command)) {
67
70
  return { kind: 'script', command: command, args: rest };
68
71
  }
@@ -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\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";
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,8 +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)
51
+ worktree Reclaim finished git worktrees (dry run unless --yes)
52
+ story-coverage Check component exports are imported by stories
50
53
 
51
54
  Options:
52
55
  -h, --help Show this help
@@ -66,6 +69,8 @@ with-host-lock
66
69
  [--on-acquire-timeout fail|run-unlocked]
67
70
  -- <command> [args...]
68
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
+
69
74
  gha-runtime-audit
70
75
  [--repository owner/name] Default GITHUB_REPOSITORY
71
76
  [--branch main]
@@ -119,12 +124,7 @@ link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>
119
124
  retrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]
120
125
  agent-blackboard probe
121
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)
122
- 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]
123
- agent-blackboard journal entries --session-id UUID
124
- agent-blackboard journal status --session-id UUID --outbox-directory PATH
125
- agent-blackboard journal flush --outbox-directory PATH [--session-id UUID]
126
- Interactive journal append requires --outbox-directory PATH.
127
- 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
128
128
  agent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{"sessions":N,"entries":N,"records":N,"bytes":N}'
129
129
  agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]
130
130
  mcp
@@ -134,6 +134,13 @@ mcp
134
134
  snapshot_export, snapshot_cleanup, and session_archive over stdio.
135
135
  Needs the optional @modelcontextprotocol/sdk peer (and zod).
136
136
  Launch it from inside the repository's git worktree.
137
+
138
+ worktree reclaim [--yes] [--json]
139
+ Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the
140
+ branch is merged or closed at exactly HEAD, using git worktree remove (never forced).
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>]
137
144
  `;
138
145
  export function printUsage(stream = process.stdout) {
139
146
  stream.write(USAGE);
@@ -0,0 +1,14 @@
1
+ import { type RunOptions } from './run.mts';
2
+ export type Assessment = {
3
+ readonly head: string;
4
+ } | {
5
+ readonly reason: string;
6
+ };
7
+ export declare function readRepository(main: RunOptions): string | undefined;
8
+ /** Clean status and no hidden index entries. Returns the HEAD commit or a reason. */
9
+ export declare function assessLocal(worktree: RunOptions): Assessment;
10
+ /**
11
+ * Needs a merged or closed same-repository PR for this branch whose head is exactly HEAD. That
12
+ * also proves HEAD is published on GitHub, so deleted branches (squash merges) need no remote ref.
13
+ */
14
+ export declare function assessPullRequest(branch: string, head: string, repository: string | undefined, main: RunOptions): string | undefined;
@@ -0,0 +1,68 @@
1
+ import { git, LOCAL_ENV, run, withoutVariables } from "./run.mjs";
2
+ const FINISHED = new Set(['MERGED', 'CLOSED']);
3
+ function parseJson(text) {
4
+ try {
5
+ return text === undefined ? undefined : JSON.parse(text);
6
+ }
7
+ catch {
8
+ return undefined;
9
+ }
10
+ }
11
+ /** Repo-local git variables, GH_REPO and GH_HOST must not redirect the lookup away from the main checkout. */
12
+ function runGh(args, main) {
13
+ const env = withoutVariables(main.env, [...LOCAL_ENV, 'GH_REPO', 'GH_HOST']);
14
+ return run('gh', args, { cwd: main.cwd, env });
15
+ }
16
+ export function readRepository(main) {
17
+ const repo = parseJson(runGh(['repo', 'view', '--json', 'nameWithOwner'], main));
18
+ return repo?.nameWithOwner?.toLowerCase();
19
+ }
20
+ /** Clean status and no hidden index entries. Returns the HEAD commit or a reason. */
21
+ export function assessLocal(worktree) {
22
+ const status = git(['status', '--porcelain', '--untracked-files=all', '--ignore-submodules=none'], worktree);
23
+ if (status === undefined)
24
+ return { reason: 'cannot read status' };
25
+ if (status !== '')
26
+ return { reason: 'uncommitted changes' };
27
+ const files = git(['ls-files', '-v', '-z'], worktree);
28
+ if (files === undefined)
29
+ return { reason: 'cannot read index' };
30
+ if (files.split('\0').some((entry) => /^[a-zS]/.test(entry))) {
31
+ return { reason: 'hidden index entries (assume-unchanged or skip-worktree)' };
32
+ }
33
+ const headOutput = git(['rev-parse', 'HEAD'], worktree);
34
+ if (headOutput === undefined)
35
+ return { reason: 'cannot read HEAD' };
36
+ const head = headOutput.trim();
37
+ return { head };
38
+ }
39
+ const PAGE = 1000;
40
+ function listPulls(branch, state, main) {
41
+ const fields = 'state,headRefOid,isCrossRepository,headRepository,headRepositoryOwner';
42
+ const args = ['pr', 'list', '--head', branch, '--state', state, '--limit', String(PAGE)];
43
+ const listed = parseJson(runGh([...args, '--json', fields], main));
44
+ return Array.isArray(listed) && listed.length < PAGE ? listed : undefined;
45
+ }
46
+ /**
47
+ * Needs a merged or closed same-repository PR for this branch whose head is exactly HEAD. That
48
+ * also proves HEAD is published on GitHub, so deleted branches (squash merges) need no remote ref.
49
+ */
50
+ export function assessPullRequest(branch, head, repository, main) {
51
+ if (repository === undefined)
52
+ return 'cannot read repository';
53
+ // Open PRs are queried on their own so a long history cannot hide one; a full page is unreadable.
54
+ const open = listPulls(branch, 'open', main);
55
+ const all = listPulls(branch, 'all', main);
56
+ if (open === undefined || all === undefined)
57
+ return 'cannot read PR state';
58
+ const own = [...open, ...all].filter((pr) => pr.isCrossRepository === false &&
59
+ `${pr.headRepositoryOwner?.login}/${pr.headRepository?.name}`.toLowerCase() === repository);
60
+ if (own.some((pr) => pr.state === 'OPEN'))
61
+ return 'open PR';
62
+ const finished = own.filter((pr) => FINISHED.has(pr.state));
63
+ if (finished.length === 0)
64
+ return 'no finished PR from this repository';
65
+ if (!finished.some((pr) => pr.headRefOid === head))
66
+ return 'PR head differs from HEAD';
67
+ return undefined;
68
+ }
@@ -0,0 +1,10 @@
1
+ export interface WorktreeRecord {
2
+ readonly path: string;
3
+ readonly branch?: string;
4
+ readonly head?: string;
5
+ readonly locked: boolean;
6
+ readonly bare: boolean;
7
+ readonly detached: boolean;
8
+ }
9
+ /** Parses `git worktree list --porcelain -z` (NUL fields, an empty field ends each record). */
10
+ export declare function parseWorktreeList(porcelain: string | undefined): WorktreeRecord[];
@@ -0,0 +1,34 @@
1
+ const BRANCH_PREFIX = 'branch refs/heads/';
2
+ function parseRecord(fields) {
3
+ const path = fields.find((field) => field.startsWith('worktree '))?.slice('worktree '.length);
4
+ if (path === undefined)
5
+ return undefined;
6
+ const branch = fields
7
+ .find((field) => field.startsWith(BRANCH_PREFIX))
8
+ ?.slice(BRANCH_PREFIX.length);
9
+ const head = fields.find((field) => field.startsWith('HEAD '))?.slice('HEAD '.length);
10
+ return {
11
+ path,
12
+ locked: fields.some((field) => field === 'locked' || field.startsWith('locked ')),
13
+ bare: fields.includes('bare'),
14
+ detached: fields.includes('detached'),
15
+ ...(branch === undefined ? {} : { branch }),
16
+ ...(head === undefined ? {} : { head }),
17
+ };
18
+ }
19
+ /** Parses `git worktree list --porcelain -z` (NUL fields, an empty field ends each record). */
20
+ export function parseWorktreeList(porcelain) {
21
+ const records = [];
22
+ let fields = [];
23
+ for (const field of [...(porcelain ?? '').split('\0'), '']) {
24
+ if (field !== '') {
25
+ fields.push(field);
26
+ continue;
27
+ }
28
+ const record = parseRecord(fields);
29
+ if (record !== undefined)
30
+ records.push(record);
31
+ fields = [];
32
+ }
33
+ return records;
34
+ }
@@ -0,0 +1,15 @@
1
+ import { type RunOptions } from './run.mts';
2
+ interface ReclaimEntry {
3
+ readonly path: string;
4
+ readonly branch: string;
5
+ readonly status: 'reclaimed' | 'would reclaim' | 'kept';
6
+ readonly reason?: string;
7
+ }
8
+ export interface ReclaimReport {
9
+ readonly dryRun: boolean;
10
+ readonly worktrees: ReclaimEntry[];
11
+ }
12
+ /** Lists finished worktrees and, with `yes`, removes them with a plain (never forced) `git worktree remove`. */
13
+ export declare function reclaimWorktrees(yes: boolean, runtime: RunOptions): ReclaimReport;
14
+ export declare function formatReport(report: ReclaimReport): string;
15
+ export {};
@@ -0,0 +1,80 @@
1
+ import { existsSync, realpathSync } from 'node:fs';
2
+ import { sep } from 'node:path';
3
+ import { assessLocal, assessPullRequest, readRepository } from "./assess.mjs";
4
+ import { parseWorktreeList } from "./list.mjs";
5
+ import { git } from "./run.mjs";
6
+ /** Assesses (and with `yes` removes) one worktree; undefined means it is not a candidate. */
7
+ function reclaimOne(record, context) {
8
+ const { path, branch, locked, bare, detached } = record;
9
+ if (locked || bare || detached || branch === undefined)
10
+ return undefined;
11
+ if (!existsSync(path) || realpathSync(path) === context.selfReal)
12
+ return undefined;
13
+ const keep = (reason) => ({ path, branch, status: 'kept', reason });
14
+ const nests = (paths) => paths.some((other) => other.startsWith(path + sep));
15
+ if (nests(context.registered)) {
16
+ return keep('contains another worktree');
17
+ }
18
+ const worktree = { cwd: path, env: context.runtime.env };
19
+ const local = assessLocal(worktree);
20
+ if ('reason' in local)
21
+ return keep(local.reason);
22
+ const reason = assessPullRequest(branch, local.head, context.repository, context.mainRun);
23
+ if (reason !== undefined)
24
+ return keep(reason);
25
+ if (!context.yes)
26
+ return { path, branch, status: 'would reclaim' };
27
+ const again = assessLocal(worktree);
28
+ const pullAgain = assessPullRequest(branch, local.head, context.repository, context.mainRun);
29
+ const listed = parseWorktreeList(git(['worktree', 'list', '--porcelain', '-z'], context.runtime));
30
+ const same = listed.some((entry) => entry.path === path && entry.branch === branch && entry.head === local.head);
31
+ if (nests(listed.map((entry) => entry.path)))
32
+ return keep('contains another worktree');
33
+ if ('reason' in again || again.head !== local.head || pullAgain !== undefined || !same)
34
+ return keep('changed since check');
35
+ if (git(['worktree', 'remove', path], { ...context.mainRun, timeout: 0 }) === undefined) {
36
+ return keep('git worktree remove refused');
37
+ }
38
+ return { path, branch, status: 'reclaimed' };
39
+ }
40
+ /** Lists finished worktrees and, with `yes`, removes them with a plain (never forced) `git worktree remove`. */
41
+ export function reclaimWorktrees(yes, runtime) {
42
+ const listing = git(['worktree', 'list', '--porcelain', '-z'], runtime);
43
+ const self = git(['rev-parse', '--show-toplevel'], runtime)?.replace(/\n$/, '');
44
+ const [main, ...others] = parseWorktreeList(listing);
45
+ if (main === undefined || !self)
46
+ throw new Error('not inside a git worktree');
47
+ const mainRun = { cwd: main.path, env: runtime.env };
48
+ const context = {
49
+ yes,
50
+ runtime,
51
+ mainRun,
52
+ selfReal: realpathSync(self),
53
+ registered: [main, ...others].map((record) => record.path),
54
+ repository: readRepository(mainRun),
55
+ };
56
+ const worktrees = [];
57
+ for (const record of others) {
58
+ try {
59
+ const entry = reclaimOne(record, context);
60
+ if (entry !== undefined)
61
+ worktrees.push(entry);
62
+ }
63
+ catch (error) {
64
+ const reason = `error: ${error.message}`;
65
+ worktrees.push({ path: record.path, branch: record.branch, status: 'kept', reason });
66
+ }
67
+ }
68
+ return { dryRun: !yes, worktrees };
69
+ }
70
+ function escape(text) {
71
+ return text.replace(/\p{Cc}/gu, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`);
72
+ }
73
+ export function formatReport(report) {
74
+ return report.worktrees
75
+ .map((entry) => {
76
+ const status = entry.status === 'kept' ? `kept: ${entry.reason}` : entry.status;
77
+ return `${escape(entry.path)}: ${escape(status)}\n`;
78
+ })
79
+ .join('');
80
+ }
@@ -0,0 +1,16 @@
1
+ export interface Fixture {
2
+ readonly root: string;
3
+ readonly main: string;
4
+ readonly caller: string;
5
+ readonly env: NodeJS.ProcessEnv;
6
+ git(cwd: string, ...args: string[]): string;
7
+ /** Adds a worktree on a new branch with one commit; optionally pushes it to origin. */
8
+ addWorktree(name: string, options?: {
9
+ push?: boolean;
10
+ dir?: string;
11
+ }): string;
12
+ /** Writes the fake `gh pr list` answer; a PR with no head defaults to the branch tip. */
13
+ setPrs(branch: string, prs: object[]): void;
14
+ cleanup(): void;
15
+ }
16
+ export declare function createFixture(): Fixture;
@@ -0,0 +1,113 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
3
+ import { tmpdir } from 'node:os';
4
+ import { join } from 'node:path';
5
+ // Answers `gh repo view` and `gh pr list --head <branch>` from files, like the real CLI.
6
+ const FAKE_GH = `#!${process.execPath}
7
+ const fs = require('node:fs')
8
+ const args = process.argv.slice(2)
9
+ const env = process.env
10
+ if (env.FAKE_GH_FAIL) process.exit(1)
11
+ if (env.FAKE_GH_NO_GIT_DIR && env.GIT_DIR) process.exit(1)
12
+ if (args[0] === 'repo') {
13
+ console.log(JSON.stringify({ nameWithOwner: env.GH_REPO || 'Acme/Widgets' }))
14
+ process.exit(0)
15
+ }
16
+ if (env.FAKE_GH_GARBAGE) {
17
+ console.log('not json')
18
+ process.exit(0)
19
+ }
20
+ const state = args[args.indexOf('--state') + 1]
21
+ // Simulates a change that lands between the first assessment and the re-check.
22
+ if (state === 'all') {
23
+ const { execFileSync } = require('node:child_process')
24
+ const run = (cwd, ...a) => execFileSync('git', a, { cwd, stdio: 'ignore' })
25
+ if (env.FAKE_GH_NEST && !fs.existsSync(env.FAKE_GH_DIR + '/nested')) {
26
+ fs.writeFileSync(env.FAKE_GH_DIR + '/nested', '')
27
+ run(env.FAKE_GH_NEST, 'worktree', 'add', '-b', 'kid', 'sub/kid')
28
+ }
29
+ if (env.FAKE_GH_TOUCH) fs.writeFileSync(env.FAKE_GH_TOUCH, 'x')
30
+ if (env.FAKE_GH_SWITCH) run(env.FAKE_GH_SWITCH, 'checkout', '-b', 'switched')
31
+ if (env.FAKE_GH_ADVANCE) {
32
+ run(env.FAKE_GH_ADVANCE, 'commit', '--allow-empty', '-m', 'late')
33
+ run(env.FAKE_GH_ADVANCE, 'push', 'origin', 'HEAD')
34
+ }
35
+ }
36
+ const branch = args[args.indexOf('--head') + 1]
37
+ const file = env.FAKE_GH_DIR + '/' + branch.replaceAll('/', '_') + '.json'
38
+ let pulls = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : []
39
+ if (state === 'open') pulls = pulls.filter((pr) => pr.state === 'OPEN')
40
+ const pad = Number(env['FAKE_GH_PAD_' + state.toUpperCase()] || 0)
41
+ for (let i = 0; i < pad; i += 1) pulls.push({ state: 'CLOSED' })
42
+ console.log(JSON.stringify(pulls))
43
+ // Reopen every PR after the first full answer, as if it changed before the re-check.
44
+ if (state === 'all' && env.FAKE_GH_REOPEN && !fs.existsSync(file + '.reopened')) {
45
+ fs.writeFileSync(file, JSON.stringify(pulls.map((pr) => ({ ...pr, state: 'OPEN' }))))
46
+ fs.writeFileSync(file + '.reopened', '')
47
+ }
48
+ `;
49
+ const realGit = execFileSync('which', ['git'], { encoding: 'utf8' }).trim();
50
+ export function createFixture() {
51
+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'worktree-reclaim-')));
52
+ const bin = join(root, 'bin');
53
+ const ghDir = join(root, 'gh');
54
+ mkdirSync(bin);
55
+ mkdirSync(ghDir);
56
+ writeFileSync(join(bin, 'gh'), FAKE_GH);
57
+ chmodSync(join(bin, 'gh'), 0o755);
58
+ // A git wrapper that fails any invocation containing the words in FAKE_GIT_FAIL, to reach error paths.
59
+ writeFileSync(join(bin, 'git'), `#!/bin/sh\ncase " $* " in *" $FAKE_GIT_FAIL "*) [ -n "$FAKE_GIT_FAIL" ] && exit 1;; esac\nexec '${realGit}' "$@"\n`);
60
+ chmodSync(join(bin, 'git'), 0o755);
61
+ const env = {
62
+ ...process.env,
63
+ PATH: `${bin}:${process.env.PATH ?? ''}`,
64
+ FAKE_GH_DIR: ghDir,
65
+ GIT_CONFIG_GLOBAL: '/dev/null',
66
+ GIT_CONFIG_SYSTEM: '/dev/null',
67
+ GIT_AUTHOR_NAME: 'Test',
68
+ GIT_AUTHOR_EMAIL: 'test@example.com',
69
+ GIT_COMMITTER_NAME: 'Test',
70
+ GIT_COMMITTER_EMAIL: 'test@example.com',
71
+ };
72
+ const git = (cwd, ...args) => execFileSync('git', args, { cwd, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
73
+ const origin = join(root, 'origin.git');
74
+ const main = join(root, 'main');
75
+ git(root, 'init', '--bare', '-b', 'main', origin);
76
+ git(root, 'init', '-b', 'main', main);
77
+ writeFileSync(join(main, 'README.md'), 'base\n');
78
+ git(main, 'add', '.');
79
+ git(main, 'commit', '-m', 'base');
80
+ git(main, 'remote', 'add', 'origin', origin);
81
+ git(main, 'push', '-u', 'origin', 'main');
82
+ const caller = join(root, 'worktrees', 'caller');
83
+ git(main, 'worktree', 'add', '-b', 'caller', caller);
84
+ return {
85
+ root,
86
+ main,
87
+ caller,
88
+ env,
89
+ git,
90
+ addWorktree: (name, options = {}) => {
91
+ const path = join(root, 'worktrees', options.dir ?? name);
92
+ git(main, 'worktree', 'add', '-b', name, path);
93
+ writeFileSync(join(path, `${name}.txt`), `${name}\n`);
94
+ git(path, 'add', '.');
95
+ git(path, 'commit', '-m', name);
96
+ if (options.push)
97
+ git(path, 'push', '-u', 'origin', name);
98
+ return path;
99
+ },
100
+ setPrs: (branch, prs) => {
101
+ const tip = git(main, 'rev-parse', `refs/heads/${branch}`).trim();
102
+ const filled = prs.map((pr) => ({
103
+ headRefOid: tip,
104
+ isCrossRepository: false,
105
+ headRepository: { name: 'Widgets' },
106
+ headRepositoryOwner: { login: 'acme' },
107
+ ...pr,
108
+ }));
109
+ writeFileSync(join(ghDir, `${branch.replaceAll('/', '_')}.json`), JSON.stringify(filled));
110
+ },
111
+ cleanup: () => rmSync(root, { force: true, recursive: true }),
112
+ };
113
+ }
@@ -0,0 +1,13 @@
1
+ export interface RunOptions {
2
+ readonly cwd: string;
3
+ readonly env: NodeJS.ProcessEnv;
4
+ /** Milliseconds before a read-only call is killed; 0 for none (worktree removal). */
5
+ readonly timeout?: number;
6
+ }
7
+ /** Runs a command without a shell; returns stdout, or undefined when it fails to start or exits non-zero. */
8
+ export declare function run(file: string, args: readonly string[], options: RunOptions): string | undefined;
9
+ export declare const LOCAL_ENV: string[];
10
+ /** A copy of `env` without the named variables. */
11
+ export declare function withoutVariables(env: NodeJS.ProcessEnv, names: readonly string[]): NodeJS.ProcessEnv;
12
+ /** git with fsmonitor disabled so a repository config can never execute a hook. */
13
+ export declare function git(args: readonly string[], options: RunOptions): string | undefined;
@@ -0,0 +1,50 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ /** Runs a command without a shell; returns stdout, or undefined when it fails to start or exits non-zero. */
3
+ export function run(file, args, options) {
4
+ try {
5
+ return execFileSync(file, args, {
6
+ cwd: options.cwd,
7
+ env: options.env,
8
+ encoding: 'utf8',
9
+ maxBuffer: 64 * 1024 * 1024,
10
+ stdio: ['ignore', 'pipe', 'ignore'],
11
+ timeout: options.timeout ?? 120_000,
12
+ });
13
+ }
14
+ catch {
15
+ return undefined;
16
+ }
17
+ }
18
+ // Repo-local overrides (see `git rev-parse --local-env-vars`): the cwd must pick the repository.
19
+ export const LOCAL_ENV = [
20
+ 'GIT_DIR',
21
+ 'GIT_WORK_TREE',
22
+ 'GIT_INDEX_FILE',
23
+ 'GIT_OBJECT_DIRECTORY',
24
+ 'GIT_ALTERNATE_OBJECT_DIRECTORIES',
25
+ 'GIT_COMMON_DIR',
26
+ 'GIT_PREFIX',
27
+ 'GIT_NAMESPACE',
28
+ 'GIT_CONFIG',
29
+ 'GIT_CONFIG_PARAMETERS',
30
+ 'GIT_CONFIG_COUNT',
31
+ 'GIT_GRAFT_FILE',
32
+ 'GIT_IMPLICIT_WORK_TREE',
33
+ 'GIT_INTERNAL_SUPER_PREFIX',
34
+ 'GIT_SHALLOW_FILE',
35
+ 'GIT_REPLACE_REF_BASE',
36
+ 'GIT_NO_REPLACE_OBJECTS',
37
+ 'GIT_QUARANTINE_PATH',
38
+ ];
39
+ /** A copy of `env` without the named variables. */
40
+ export function withoutVariables(env, names) {
41
+ const copy = { ...env };
42
+ for (const name of names)
43
+ delete copy[name];
44
+ return copy;
45
+ }
46
+ /** git with fsmonitor disabled so a repository config can never execute a hook. */
47
+ export function git(args, options) {
48
+ const env = withoutVariables(options.env, LOCAL_ENV);
49
+ return run('git', ['-c', 'core.fsmonitor=false', ...args], { ...options, env });
50
+ }