vouchington-tooling 0.53.0 → 0.55.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 (197) hide show
  1. package/README.md +99 -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/optional-peer.d.mts +5 -0
  12. package/dist/cli/optional-peer.mjs +17 -0
  13. package/dist/cli/parse-forwarded-commands.d.mts +3 -0
  14. package/dist/cli/parse-forwarded-commands.mjs +2 -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 +5 -1
  20. package/dist/cli/parse.mjs +3 -0
  21. package/dist/cli/story-coverage-lazy.d.mts +3 -0
  22. package/dist/cli/story-coverage-lazy.mjs +6 -0
  23. package/dist/cli/usage.d.mts +1 -1
  24. package/dist/cli/usage.mjs +8 -7
  25. package/dist/host-storage/check.d.mts +38 -0
  26. package/dist/host-storage/check.mjs +109 -0
  27. package/dist/host-storage/cli.d.mts +7 -0
  28. package/dist/host-storage/cli.mjs +102 -0
  29. package/dist/host-storage/host-storage.test-helpers.d.mts +26 -0
  30. package/dist/host-storage/host-storage.test-helpers.mjs +58 -0
  31. package/dist/host-storage/index.d.mts +3 -0
  32. package/dist/host-storage/index.mjs +3 -0
  33. package/dist/host-storage/preflight.d.mts +22 -0
  34. package/dist/host-storage/preflight.mjs +105 -0
  35. package/dist/index.d.mts +2 -0
  36. package/dist/index.mjs +1 -0
  37. package/dist/playwright/assertions.d.mts +1 -0
  38. package/dist/playwright/assertions.mjs +5 -0
  39. package/dist/playwright/blocked-external-network.d.mts +15 -0
  40. package/dist/playwright/blocked-external-network.mjs +73 -0
  41. package/dist/playwright/browser-dialog-issues.d.mts +12 -0
  42. package/dist/playwright/browser-dialog-issues.mjs +29 -0
  43. package/dist/playwright/browser-errors.d.mts +23 -0
  44. package/dist/playwright/browser-errors.mjs +130 -0
  45. package/dist/playwright/browser-issue-monitor.test-helpers.d.mts +31 -0
  46. package/dist/playwright/browser-issue-monitor.test-helpers.mjs +51 -0
  47. package/dist/playwright/browser-issue-records.d.mts +42 -0
  48. package/dist/playwright/browser-issue-records.mjs +148 -0
  49. package/dist/playwright/browser-test.d.mts +22 -0
  50. package/dist/playwright/browser-test.mjs +68 -0
  51. package/dist/playwright/expect-no-broken-images.d.mts +17 -0
  52. package/dist/playwright/expect-no-broken-images.mjs +39 -0
  53. package/dist/playwright/index.d.mts +32 -0
  54. package/dist/playwright/index.mjs +22 -0
  55. package/dist/playwright/mobile-assertions.d.mts +14 -0
  56. package/dist/playwright/mobile-assertions.mjs +43 -0
  57. package/dist/playwright/monitored-test-info.d.mts +14 -0
  58. package/dist/playwright/monitored-test-info.mjs +1 -0
  59. package/dist/playwright/navigate-to.d.mts +27 -0
  60. package/dist/playwright/navigate-to.mjs +39 -0
  61. package/dist/playwright/radix-select.d.mts +18 -0
  62. package/dist/playwright/radix-select.mjs +19 -0
  63. package/dist/playwright/random-id.d.mts +34 -0
  64. package/dist/playwright/random-id.mjs +37 -0
  65. package/dist/playwright/retry-on-connection-lost.d.mts +7 -0
  66. package/dist/playwright/retry-on-connection-lost.mjs +107 -0
  67. package/dist/playwright/scroll-to-load-more.d.mts +37 -0
  68. package/dist/playwright/scroll-to-load-more.mjs +158 -0
  69. package/dist/playwright/storybook.d.mts +2 -0
  70. package/dist/playwright/storybook.mjs +13 -0
  71. package/dist/playwright/test-fixtures.d.mts +1 -0
  72. package/dist/playwright/test-fixtures.mjs +2 -0
  73. package/dist/playwright/test-lifecycle-reporter.d.mts +27 -0
  74. package/dist/playwright/test-lifecycle-reporter.mjs +57 -0
  75. package/dist/playwright/totp.d.mts +6 -0
  76. package/dist/playwright/totp.mjs +37 -0
  77. package/dist/playwright/turnstile-stub.d.mts +8 -0
  78. package/dist/playwright/turnstile-stub.mjs +61 -0
  79. package/dist/playwright/viewport-constants.d.mts +30 -0
  80. package/dist/playwright/viewport-constants.mjs +9 -0
  81. package/dist/playwright/virtual-authenticator.d.mts +5 -0
  82. package/dist/playwright/virtual-authenticator.mjs +15 -0
  83. package/dist/playwright/wait-for-hydration.d.mts +29 -0
  84. package/dist/playwright/wait-for-hydration.mjs +81 -0
  85. package/dist/shell-parse/ansi-c-string.d.mts +12 -0
  86. package/dist/shell-parse/ansi-c-string.mjs +80 -0
  87. package/dist/shell-parse/index.d.mts +20 -0
  88. package/dist/shell-parse/index.mjs +15 -0
  89. package/dist/shell-parse/shell-command-substitution-reads.d.mts +8 -0
  90. package/dist/shell-parse/shell-command-substitution-reads.mjs +53 -0
  91. package/dist/shell-parse/shell-command-substitutions.d.mts +8 -0
  92. package/dist/shell-parse/shell-command-substitutions.mjs +52 -0
  93. package/dist/shell-parse/shell-command-wrappers.d.mts +26 -0
  94. package/dist/shell-parse/shell-command-wrappers.mjs +143 -0
  95. package/dist/shell-parse/shell-commands.d.mts +24 -0
  96. package/dist/shell-parse/shell-commands.mjs +155 -0
  97. package/dist/shell-parse/shell-heredoc-delimiter.d.mts +5 -0
  98. package/dist/shell-parse/shell-heredoc-delimiter.mjs +52 -0
  99. package/dist/shell-parse/shell-heredoc-parser.d.mts +7 -0
  100. package/dist/shell-parse/shell-heredoc-parser.mjs +49 -0
  101. package/dist/shell-parse/shell-heredoc-quote-state.d.mts +19 -0
  102. package/dist/shell-parse/shell-heredoc-quote-state.mjs +40 -0
  103. package/dist/shell-parse/shell-heredoc.d.mts +10 -0
  104. package/dist/shell-parse/shell-heredoc.mjs +90 -0
  105. package/dist/shell-parse/shell-redirections.d.mts +5 -0
  106. package/dist/shell-parse/shell-redirections.mjs +34 -0
  107. package/dist/shell-parse/shell-script-operand.d.mts +13 -0
  108. package/dist/shell-parse/shell-script-operand.mjs +103 -0
  109. package/dist/shell-parse/shell-stdin-script.d.mts +6 -0
  110. package/dist/shell-parse/shell-stdin-script.mjs +61 -0
  111. package/dist/shell-parse/shell-token-utils.d.mts +9 -0
  112. package/dist/shell-parse/shell-token-utils.mjs +33 -0
  113. package/dist/shell-parse/shell-tokenizer-comments.d.mts +1 -0
  114. package/dist/shell-parse/shell-tokenizer-comments.mjs +57 -0
  115. package/dist/shell-parse/shell-tokenizer-operators.d.mts +14 -0
  116. package/dist/shell-parse/shell-tokenizer-operators.mjs +47 -0
  117. package/dist/shell-parse/shell-tokenizer.d.mts +12 -0
  118. package/dist/shell-parse/shell-tokenizer.mjs +104 -0
  119. package/dist/story-coverage/analyze.d.mts +8 -0
  120. package/dist/story-coverage/analyze.mjs +24 -0
  121. package/dist/story-coverage/check.d.mts +11 -0
  122. package/dist/story-coverage/check.mjs +42 -0
  123. package/dist/story-coverage/components.d.mts +10 -0
  124. package/dist/story-coverage/components.mjs +40 -0
  125. package/dist/story-coverage/coverage.d.mts +10 -0
  126. package/dist/story-coverage/coverage.mjs +43 -0
  127. package/dist/story-coverage/index.d.mts +13 -0
  128. package/dist/story-coverage/index.mjs +7 -0
  129. package/dist/story-coverage/messages.d.mts +10 -0
  130. package/dist/story-coverage/messages.mjs +42 -0
  131. package/dist/story-coverage/options.d.mts +27 -0
  132. package/dist/story-coverage/options.mjs +51 -0
  133. package/dist/story-coverage/workspace.d.mts +2 -0
  134. package/dist/story-coverage/workspace.mjs +27 -0
  135. package/dist/test-helpers/cancel-runs.test-helpers.d.mts +39 -0
  136. package/dist/test-helpers/cancel-runs.test-helpers.mjs +124 -0
  137. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.d.mts +12 -0
  138. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.mjs +68 -0
  139. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.d.mts +18 -0
  140. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.mjs +162 -0
  141. package/dist/vitest-diagnostics/browser.d.mts +2 -0
  142. package/dist/vitest-diagnostics/browser.mjs +6 -0
  143. package/dist/vitest-diagnostics/index.d.mts +14 -23
  144. package/dist/vitest-diagnostics/index.mjs +8 -124
  145. package/dist/vitest-diagnostics/report-summary.d.mts +22 -0
  146. package/dist/vitest-diagnostics/report-summary.mjs +123 -0
  147. package/dist/vitest-diagnostics/vitest-fake-timer-guard.d.mts +6 -0
  148. package/dist/vitest-diagnostics/vitest-fake-timer-guard.mjs +34 -0
  149. package/dist/vitest-diagnostics/vitest-fork-leak-detection.d.mts +1 -0
  150. package/dist/vitest-diagnostics/vitest-fork-leak-detection.mjs +8 -0
  151. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.d.mts +17 -1
  152. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.mjs +44 -2
  153. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.d.mts +55 -0
  154. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.mjs +74 -0
  155. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.d.mts +19 -0
  156. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.mjs +136 -0
  157. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.d.mts +7 -0
  158. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.mjs +54 -0
  159. package/dist/vitest-diagnostics/vitest-network-allowlist-host.d.mts +8 -0
  160. package/dist/vitest-diagnostics/vitest-network-allowlist-host.mjs +48 -0
  161. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.d.mts +14 -0
  162. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.mjs +39 -0
  163. package/dist/vitest-diagnostics/vitest-network-allowlist.d.mts +7 -0
  164. package/dist/vitest-diagnostics/vitest-network-allowlist.mjs +72 -0
  165. package/dist/vitest-diagnostics/vitest-process-resources.d.mts +10 -0
  166. package/dist/vitest-diagnostics/vitest-process-resources.mjs +54 -0
  167. package/dist/vitest-effective-timeout/cap.d.mts +9 -0
  168. package/dist/vitest-effective-timeout/cap.mjs +28 -0
  169. package/dist/vitest-effective-timeout/check-profiles.d.mts +15 -0
  170. package/dist/vitest-effective-timeout/check-profiles.mjs +52 -0
  171. package/dist/vitest-effective-timeout/config-file.d.mts +6 -0
  172. package/dist/vitest-effective-timeout/config-file.mjs +23 -0
  173. package/dist/vitest-effective-timeout/fixtures.d.mts +2 -0
  174. package/dist/vitest-effective-timeout/fixtures.mjs +18 -0
  175. package/dist/vitest-effective-timeout/index.d.mts +7 -0
  176. package/dist/vitest-effective-timeout/index.mjs +4 -0
  177. package/dist/vitest-effective-timeout/profiles.d.mts +10 -0
  178. package/dist/vitest-effective-timeout/profiles.mjs +33 -0
  179. package/dist/vitest-effective-timeout/run-profile.d.mts +31 -0
  180. package/dist/vitest-effective-timeout/run-profile.mjs +95 -0
  181. package/docs/mcp-server.md +2 -13
  182. package/package.json +37 -2
  183. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  184. package/scripts/chromium-launch-probe.d.mts +7 -0
  185. package/scripts/chromium-launch-probe.mjs +101 -0
  186. package/scripts/run-bounded-fixtures/run-bounded-backpressure.py +186 -0
  187. package/scripts/run-bounded-fixtures/run-bounded-merged-output.py +75 -0
  188. package/scripts/run-bounded-fixtures/run-bounded-reset-socket.py +25 -0
  189. package/scripts/run-bounded.py +199 -0
  190. package/scripts/run_bounded_process.py +129 -0
  191. package/scripts/worktree/git-index-lock.sh +16 -0
  192. package/scripts/worktree/git-worktrees.sh +23 -20
  193. package/scripts/worktree/reset-worktree-run.sh +199 -0
  194. package/scripts/worktree/reset-worktree.sh +122 -0
  195. package/skills/blackboard/SKILL.md +4 -64
  196. package/skills/stacked-prs/SKILL.md +1 -1
  197. package/skills/stacked-prs/references/drain.md +2 -2
package/README.md CHANGED
@@ -73,8 +73,7 @@ vouchington wait-for-apt-locks
73
73
  vouchington retrospective-transcript --jsonl /path/to/transcript.jsonl
74
74
  vouchington retrospective-facts --pr 49 --repo vouchington/vouchington-infra --raw
75
75
  vouchington agent-blackboard probe
76
- vouchington agent-blackboard journal append --session-id <uuid> --agent codex --version 1 --file note.md --repository owner/repo --mode autonomous --source-event-id event:1 --work-outcome in-progress --coverage-status partial --timestamp 2026-01-01T00:00:00.000Z
77
- vouchington agent-blackboard journal entries --session-id <uuid>
76
+ vouchington agent-blackboard distill classify <partition.jsonl> --retro-cutoff <iso> --session-cutoff <iso>
78
77
  vouchington agent-blackboard snapshot partition --snapshot <snapshot.jsonl> --checksum <sha256> --counts <counts.json>
79
78
  vouchington agent-blackboard snapshot cleanup --snapshot <snapshot.jsonl> --partition-directory <partitions-dir> --receipt <receipt-json>
80
79
  vouchington mcp
@@ -196,12 +195,10 @@ as not merged to main, and a missing base is unavailable.
196
195
 
197
196
  Agent Blackboard support is optional: only the `agent-blackboard` subpath and its CLI commands
198
197
  need `agent-blackboard@^0.6.0`. Snapshot cleanup accepts only package-generated temporary paths.
199
- `appendJournal` and the journal CLI now require explicit mode, stable source-event identity, work
198
+ `appendJournal` now requires explicit mode, stable source-event identity, work
200
199
  outcome, feedback coverage, and exact repositories. This is a breaking pre-1.0 API change; adopt the
201
200
  shared contract before upgrading consumers. `appendJournal` reads a bounded UTF-8 note and delegates
202
- to `writeFeedback`, returning delivered or pending state rather than a success-shaped message. The CLI accepts one or more
203
- `--repository owner/name` flags; it records the entry's exact repositories and updates the session's
204
- cumulative repository list before appending.
201
+ to `writeFeedback`, returning delivered or pending state rather than a success-shaped message.
205
202
  Programmatic callers launched from a different workspace directory pass their own module URL as
206
203
  `dependencies: { resolveFrom: import.meta.url }`; the CLI defaults to the current package context.
207
204
  It captures a target under a private tombstone, validates partition names, permissions, JSONL,
@@ -223,12 +220,32 @@ Host-lock environment:
223
220
  | `HOST_LOCK_PROCESS_GROUP_DRAIN_SECONDS` | `30` | Time to wait for the command process group |
224
221
  | `HOST_LOCK_ACTIVE` | unset | Set while a lock is held; nested locks fail |
225
222
 
223
+ `vouchington host-storage --path <path>` checks free space for each path. Paths on the same device
224
+ are measured once. The default floor is 5 GiB (`--minimum-free-bytes`). `--pnpm-store` discovers the
225
+ pnpm store. `--docker-root` checks Docker Desktop's `Docker.raw` on macOS and `docker info` on Linux.
226
+ Discovery waits 5 seconds unless `--discovery-timeout-ms` sets an integer from 1 through 2147483647. A required path that is missing or low
227
+ fails before optional discovery runs. Optional discovery failures are warnings; low space on a
228
+ discovered filesystem still fails. `inspectHostStorage` and `probeHostStorage` are exported from
229
+ `vouchington-tooling/host-storage`.
230
+
226
231
  ## Sourceable Bash libraries
227
232
 
228
233
  `scripts/worktree/git-worktrees.sh` is included in the published package. Source it to parse
229
- `git worktree list --porcelain` with `git_worktree_*` helpers. Its
234
+ `git worktree list --porcelain` with `git_worktree_*` helpers. Path queries fail when git fails,
235
+ and `git_worktree_main_path` fails when git reports no worktree. Its
230
236
  `git_worktree_canonical_path_hash <path>` helper resolves the physical path and prints a stable
231
237
  `d` plus the first 12 lowercase hexadecimal characters of its SHA-256 digest.
238
+ `scripts/worktree/git-index-lock.sh` removes only a 0-byte `index.lock`. A non-empty lock is left
239
+ in place.
240
+
241
+ `scripts/worktree/reset-worktree.sh --base-ref <ref>` checks out a new `reset-<hex>` branch and
242
+ hard-resets it to `<ref>`. A `remote/branch` ref is fetched first; `refs/...` and a local ref are
243
+ not. It refuses uncommitted or untracked changes unless `--force` is set, refuses a non-empty
244
+ `index.lock`, and deletes a zero-byte `index.lock`. Repeat `--cache <relative-path>` for caller-owned
245
+ outputs. `--pre` runs after fetch and before the branch switch; `--post` runs after cache removal.
246
+ The script also deletes `.cache` directories and the direct `.cache`, `.vite`, and `.vitest`
247
+ directories inside `node_modules`. It needs `flock` or `lockf` and holds
248
+ `.local/reset-worktree.lock` for the run.
232
249
 
233
250
  ## Reclaiming finished worktrees
234
251
 
@@ -366,8 +383,11 @@ import {
366
383
  shellScriptViolations,
367
384
  workflowYamlViolations,
368
385
  } from 'vouchington-tooling/gh-api-shell-quoting'
386
+ import { tokenizeShellWords } from 'vouchington-tooling/shell-parse'
369
387
  ```
370
388
 
389
+ `vouchington-tooling/shell-parse` splits shell text into words, heredocs, redirections, and command prefixes. Callers pass the text. The parser does not decide which commands are allowed. `stripQuotedShellText` and `commandsToInspect*` do not scan `$(...)` substitutions in the command text: call `extractShellCommandSubstitutions` and inspect each result too.
390
+
371
391
  `processDiffCommand` runs a caller-supplied `git diff` or `gh pr diff` executable and argv without
372
392
  a shell, emitting complete unified-diff file blocks without accumulating the whole patch. It keeps
373
393
  at most one file block (which can itself be large), preserves preambles and line content, and drains
@@ -537,9 +557,67 @@ watch reruns, and prints an attribution summary only for abnormal worker exits.
537
557
  a synchronous stderr line and one JSONL file per PID; a start record without an exit record
538
558
  identifies a fork killed before its handler could run. `createForkLeakDetector` accepts tracked
539
559
  resource names and warmup, threshold, and sustained-growth settings; the caller supplies each
540
- checkpoint's resource counts. Use a caller-owned run directory: the reporter clears only regular
541
- numeric PID `.jsonl` files there at construction and leaves the directory and other files alone.
542
- Application metrics and CI artifact handling stay with the caller.
560
+ checkpoint's resource counts. `getForkLeakDetector` keeps one detector for the process.
561
+ `formatForkLeakDiagnostics` stays a one-line summary unless resource counts are passed, in which
562
+ case it prints the multi-line report and optional pool metrics. `waitForForkLeakHandshakeSettle`
563
+ waits for a caller-supplied pool snapshot to settle. `installTestNetworkAllowlist` takes the
564
+ allowed hosts, an exempt predicate, and the state key. `checkAndRestoreFakeTimers` restores real
565
+ timers and returns a diagnostic when a test left fake timers installed.
566
+ `countResourcesByType` turns resource names into per-type counts and `recordForkLeakCheckpoint`
567
+ feeds a handshake settlement's counts to a detector. `formatForkLeakDiagnostics` takes an optional
568
+ fourth argument, `{ poolMetricsLabel }`, to replace the default `pool metrics:` label (for example
569
+ `'PostgreSQL pool metrics:'`).
570
+
571
+ `vouchington-tooling/vitest-diagnostics/browser` is the browser-safe entry for Storybook and Vitest
572
+ browser projects, for example a root fake-timer setup file shared with a Node project. It exports
573
+ only `checkAndRestoreFakeTimers`, `formatFakeTimerLeakDiagnostics`, and the `FakeTimerController`
574
+ type, and its import graph contains no `node:*` imports (a test enforces this), so it needs no Vite
575
+ `optimizeDeps` entry. The resource, fork-leak, reporter, and network-allowlist helpers stay in the
576
+ Node entry, and the effective-timeout cap is a config-time plugin that belongs in Node config.
577
+
578
+ Use a caller-owned run directory: the reporter clears only regular numeric PID `.jsonl` files
579
+ there at construction and leaves the directory and other files alone. Application metrics and CI artifact handling stay with the caller.
580
+
581
+ `vitest-effective-timeout` exports `effectiveTimeoutCap`. The plugin rejects a project whose effective
582
+ `testTimeout` or `hookTimeout` is missing, non-finite, non-positive, or above the caller-supplied cap
583
+ (default 30 seconds). The plugin name, the expected root config filename, and the profile scratch
584
+ directory are parameters. `checkFiniteTimeoutProfiles` writes one scratch project per admission
585
+ profile and can take a caller-supplied runner.
586
+
587
+ `playwright` monitors browser console errors, web errors, dialogs, page crashes, and failed
588
+ requests during Playwright tests. `@playwright/test` is an optional peer. `createBrowserTest` and
589
+ `withMonitoredPage` install the generic telemetry blocks (Google Tag Manager, Google Analytics, and
590
+ DoubleClick) and fail the test when an unallowlisted issue remains. Passing `rules` replaces those
591
+ generic defaults rather than adding to them; spread `BLOCKED_EXTERNAL_NETWORK_RULES` to extend them. The default request-failure allowlist follows
592
+ the active rules, and when two rules match one URL the later rule wins. `assertTimeout` runs in both
593
+ `createBrowserTest` and `withMonitoredPage`.
594
+ Pass host-specific block rules and request-failure allowlist entries, a warning pattern, and a timeout checker; the default warning
595
+ pattern records React hydration and render warnings. The fixture does not import a product timeout
596
+ guard: pass `assertTimeout` when the caller owns the timeout cap.
597
+
598
+ `playwright` waits for below-fold hydration, retries transient local connection loss, navigates
599
+ through an injectable Turnstile stub, and scrolls a caller-supplied sentinel into view.
600
+ `@playwright/test` is an optional peer. The stub's attribute name and token default to `data-pw`
601
+ and `PLAYWRIGHT_TURNSTILE_TOKEN`. The scroll helper's sentinel test id defaults to
602
+ `infinite-scroll-sentinel`.
603
+
604
+ `playwright` provides small Playwright helpers: a virtual authenticator, a Radix dropdown opener,
605
+ a Storybook index probe, required-value and mobile overflow assertions, an image-response guard,
606
+ random suffixes, viewport sizes, a 1x1 PNG fixture, RFC 6238 TOTP codes, and a test-lifecycle
607
+ reporter. The reporter prints one JSON line per test with the marker `playwright-test-lifecycle`.
608
+ `@playwright/test` is an optional peer. TOTP setup and cleanup stay with the caller.
609
+
610
+ `createBrowserErrorsFixture`, `withMonitoredPage`, and `BrowserIssueMonitor` take the narrow
611
+ exported `MonitoredTestInfo` type (`attach`, `status`, `expectedStatus`, `timeout`) instead of
612
+ Playwright's full `TestInfo`. A real `TestInfo` is assignable to it, so no cast is needed.
613
+
614
+ `TestLifecycleReporter` accepts `failOnSkippedTests`, a plain boolean that defaults to `false`; the
615
+ reporter never reads `process.env.CI`, so the caller opts in explicitly:
616
+ `reporter: [[TestLifecycleReporter.modulePath, { failOnSkippedTests: Boolean(process.env.CI) }]]`.
617
+ When enabled, a run that would otherwise pass fails through the reporter's `onEnd` result status,
618
+ and stderr lists each skipped test's title path and `file:line`. Every test whose latest attempt
619
+ is `skipped` counts, including `test.fixme`, `test.skip`, and runtime `test.skip()`, because
620
+ Playwright reports all of them as `skipped`. A run that already failed keeps its status.
543
621
 
544
622
  `browser-session-runner` supervises caller-created browser-test processes. Callers supply command
545
623
  construction, line classification, retry/outcome policy, and budgets; the library owns process-group
@@ -654,8 +732,7 @@ Verified delivery retains its receipt when local cleanup fails, returning
654
732
  safe to replay: an event is identified by session, `sourceEventId`, and content, and a duplicate that
655
733
  differs only in `timestamp` is the same event, so it reports the stored record's `timestamp` and
656
734
  receipt and the retained duplicate is removed.
657
- Use `vouchington agent-blackboard journal flush --outbox-directory PATH` to replay unchanged pending
658
- records after connectivity returns.
735
+ Use the `outbox_flush` MCP tool to replay unchanged pending records after connectivity returns.
659
736
 
660
737
  Autonomous mode prohibits the filesystem outbox. `verifyFreshFeedback` requires a fresh source-event
661
738
  write plus readback of its own append receipt and rejects visible duplicate source records. This
@@ -734,6 +811,16 @@ reexports, and literal dynamic/require loads. Missing or incomplete facts for a
734
811
  throw; external specifiers resolve to `null`. The default file inventory limit is 10,000
735
812
  files and can be reduced with `maxFiles`.
736
813
 
814
+ ## Story coverage
815
+
816
+ `vouchington-tooling/story-coverage` exports `checkStoryCoverage`. It reports component exports
817
+ that no reachable story imports. Callers pass the repository root, component directory, story
818
+ directory, source extensions, component extensions, a marker regular expression, a story-file
819
+ pattern, path aliases, and an optional exclusions map. An empty map is the zero-exclusion
820
+ ratchet: any exclusion entry, even one that matches no component, makes `ok` false. Namespace imports of the component directory fail
821
+ the check because coverage cannot see which export was used. `vouchington story-coverage` runs
822
+ the same check and needs the optional `no-mistakes` peer.
823
+
737
824
  ## Retrospective distill classifier
738
825
 
739
826
  `vouchington-tooling/retrospective-distill` exports `classifySession(session, entries, cutoffs)`,
@@ -15,7 +15,6 @@ export declare function appendJournal(input: JournalInput & {
15
15
  markdownFile: string;
16
16
  }): Promise<FeedbackDeliveryResult>;
17
17
  export declare function readJournal(sessionId: string, env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<unknown[]>;
18
- export declare function formatJournalEntries(sessionId: string, entries: unknown[]): string;
19
18
  export { BlackboardNotInstalledError, resolveBlackboardConnection } from './client.mts';
20
19
  export type { BlackboardConnection, BlackboardClientModule, BlackboardClientDependencies, } from './client.mts';
21
20
  export type * from './feedback-types.mts';
@@ -36,29 +36,6 @@ export async function readJournal(sessionId, env, dependencies) {
36
36
  entries.push(entry);
37
37
  return entries;
38
38
  }
39
- export function formatJournalEntries(sessionId, entries) {
40
- const journals = entries.flatMap((entry) => {
41
- if (typeof entry !== 'object' ||
42
- entry === null ||
43
- !('createdAt' in entry) ||
44
- !('data' in entry) ||
45
- typeof entry.createdAt !== 'string' ||
46
- typeof entry.data !== 'object' ||
47
- entry.data === null ||
48
- !('type' in entry.data) ||
49
- !('markdown' in entry.data) ||
50
- entry.data.type !== 'journal' ||
51
- typeof entry.data.markdown !== 'string')
52
- return [];
53
- return [{ createdAt: entry.createdAt, markdown: entry.data.markdown }];
54
- });
55
- if (!journals.length)
56
- return `No journal entries found for session ${sessionId}.`;
57
- return journals
58
- .sort((left, right) => left.createdAt.localeCompare(right.createdAt))
59
- .map(({ createdAt, markdown }) => `## ${createdAt}\n\n${markdown}`)
60
- .join('\n\n');
61
- }
62
39
  export { BlackboardNotInstalledError, resolveBlackboardConnection } from "./client.mjs";
63
40
  export { createFeedbackEnvelope, validateFeedbackEnvelope } from "./feedback-codec.mjs";
64
41
  export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from "./feedback-delivery.mjs";
@@ -1,4 +1,3 @@
1
1
  export declare function flagsToValues(flags: string[]): Record<string, string>;
2
2
  export declare function assertAllowed(values: Record<string, string>, allowed: string[]): void;
3
3
  export declare function required(values: Record<string, string>, key: string): string;
4
- export declare function validatedSessionId(sessionId: string | undefined): string | undefined;
@@ -1,4 +1,3 @@
1
- import { assertSessionId } from "../../agent-blackboard/session-id.mjs";
2
1
  export function flagsToValues(flags) {
3
2
  const values = {};
4
3
  for (let index = 0; index < flags.length; index += 2) {
@@ -24,11 +23,3 @@ export function required(values, key) {
24
23
  throw new Error(`--${key} is required`);
25
24
  return value;
26
25
  }
27
- export function validatedSessionId(sessionId) {
28
- if (sessionId !== undefined) {
29
- assertSessionId(sessionId);
30
- if (sessionId.length > 256)
31
- throw new Error('session identity is too long');
32
- }
33
- return sessionId;
34
- }
@@ -1,3 +1 @@
1
- import { readJournal } from '../../agent-blackboard/index.mts';
2
- export declare function setJournalReaderForTest(reader?: typeof readJournal): void;
3
1
  export declare function runAgentBlackboardCommand(args: string[]): Promise<number>;
@@ -1,12 +1,8 @@
1
- import { assertAllowed, flagsToValues, required, validatedSessionId, } from "./agent-blackboard-flags.mjs";
2
1
  import { runSnapshot } from "./agent-blackboard-snapshot.mjs";
3
2
  import { runSessionStart } from "./agent-blackboard-session-start.mjs";
4
- import { appendJournal, feedbackOutboxCounts, flushFeedbackOutbox, formatJournalEntries, probeBlackboard, readJournal, } from "../../agent-blackboard/index.mjs";
3
+ import { probeBlackboard } from "../../agent-blackboard/index.mjs";
4
+ import { runDistillClassify } from "../../retrospective-distill/index.mjs";
5
5
  const dependencies = { resolveFrom: import.meta.url };
6
- let journalReader = readJournal;
7
- export function setJournalReaderForTest(reader) {
8
- journalReader = reader ?? readJournal;
9
- }
10
6
  export async function runAgentBlackboardCommand(args) {
11
7
  try {
12
8
  const [command, ...rest] = args;
@@ -14,128 +10,18 @@ export async function runAgentBlackboardCommand(args) {
14
10
  await probeBlackboard(undefined, dependencies);
15
11
  return 0;
16
12
  }
17
- if (command === 'journal')
18
- return await runJournal(rest);
19
13
  if (command === 'snapshot')
20
14
  return await runSnapshot(rest);
21
15
  if (command === 'session-start')
22
16
  return await runSessionStart(rest);
23
- throw new Error('usage: agent-blackboard probe | session-start | journal append|entries|flush|status | snapshot partition|cleanup');
17
+ if (command === 'distill' && rest[0] === 'classify') {
18
+ process.stdout.write(`${await runDistillClassify(rest.slice(1))}\n`);
19
+ return 0;
20
+ }
21
+ throw new Error('usage: agent-blackboard probe | session-start | distill classify | snapshot partition|cleanup');
24
22
  }
25
23
  catch (error) {
26
24
  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
27
25
  return 2;
28
26
  }
29
27
  }
30
- async function runJournal(args) {
31
- const [action, ...flags] = args;
32
- const { repositories, remaining } = action === 'append' ? extractRepositories(flags) : { repositories: [], remaining: flags };
33
- const values = flagsToValues(remaining);
34
- if (action === 'flush' || action === 'status') {
35
- assertAllowed(values, ['outbox-directory', 'session-id']);
36
- const directory = required(values, 'outbox-directory');
37
- const sessionId = validatedSessionId(action === 'status' ? required(values, 'session-id') : values['session-id']);
38
- const result = action === 'flush'
39
- ? await flushFeedbackOutbox({ directory, dependencies })
40
- : { pendingCount: 0 };
41
- const counts = sessionId !== undefined ? feedbackOutboxCounts(directory, sessionId) : result;
42
- process.stdout.write(`${JSON.stringify({
43
- ...result,
44
- ...counts,
45
- sessionId,
46
- status: counts.pendingCount ? 'pending' : 'empty',
47
- })}\n`);
48
- return 0;
49
- }
50
- if (action === 'entries') {
51
- assertAllowed(values, ['session-id']);
52
- const sessionId = required(values, 'session-id');
53
- let entries;
54
- try {
55
- entries = await journalReader(sessionId, undefined, dependencies);
56
- }
57
- catch (error) {
58
- if (!isNotFound(error))
59
- throw error;
60
- entries = [];
61
- }
62
- process.stdout.write(`${formatJournalEntries(sessionId, entries)}\n`);
63
- return 0;
64
- }
65
- if (action === 'append') {
66
- assertAllowed(values, [
67
- 'session-id',
68
- 'agent',
69
- 'version',
70
- 'file',
71
- 'parent-session-id',
72
- 'timestamp',
73
- 'mode',
74
- 'source-event-id',
75
- 'work-outcome',
76
- 'coverage-status',
77
- 'coverage-source',
78
- 'dropped-count',
79
- 'outbox-directory',
80
- ]);
81
- const result = await appendJournal({
82
- dependencies,
83
- mode: required(values, 'mode'),
84
- sourceEventId: required(values, 'source-event-id'),
85
- workOutcome: required(values, 'work-outcome'),
86
- feedbackCoverage: {
87
- status: required(values, 'coverage-status'),
88
- sources: values['coverage-source']?.split(',') ?? [],
89
- droppedCount: Number(values['dropped-count'] ?? '0'),
90
- },
91
- ...(values['outbox-directory'] ? { outboxDirectory: values['outbox-directory'] } : {}),
92
- sessionId: required(values, 'session-id'),
93
- agent: required(values, 'agent'),
94
- version: values.version ?? 'unknown',
95
- repositories: requiredRepositories(repositories),
96
- markdownFile: required(values, 'file'),
97
- ...('timestamp' in values ? { timestamp: values.timestamp } : {}),
98
- parentSessionId: values['parent-session-id'] ?? null,
99
- });
100
- // Autonomous mode has no outbox, so its receipt must not depend on one.
101
- const counts = values.mode === 'autonomous'
102
- ? { pendingCount: 0, worktreePendingCount: 0 }
103
- : pendingCounts(required(values, 'outbox-directory'), required(values, 'session-id'));
104
- const storedVersion = result.status === 'delivered' ? result.receipt.storedVersion : undefined;
105
- // JSON.stringify drops an undefined `storedVersion`.
106
- process.stdout.write(`${JSON.stringify({ ...result, storedVersion, ...counts })}\n`);
107
- return 0;
108
- }
109
- throw new Error('usage: agent-blackboard journal append|entries|flush|status');
110
- }
111
- function extractRepositories(flags) {
112
- const repositories = [];
113
- const remaining = [];
114
- for (let index = 0; index < flags.length; index += 2) {
115
- const flag = flags[index];
116
- const value = flags[index + 1];
117
- if (!flag?.startsWith('--') || value === undefined)
118
- throw new Error(`invalid option: ${flag ?? ''}`);
119
- if (flag === '--repository')
120
- repositories.push(value);
121
- else
122
- remaining.push(flag, value);
123
- }
124
- return { repositories, remaining };
125
- }
126
- function requiredRepositories(repositories) {
127
- if (repositories.length === 0)
128
- throw new Error('--repository is required');
129
- return repositories;
130
- }
131
- /** An append receipt reports only unsent records; rejected records are not pending. */
132
- function pendingCounts(directory, sessionId) {
133
- const { pendingCount, worktreePendingCount } = feedbackOutboxCounts(directory, sessionId);
134
- return { pendingCount, worktreePendingCount };
135
- }
136
- function isNotFound(error) {
137
- return (typeof error === 'object' &&
138
- error !== null &&
139
- (('status' in error && error.status === 404) ||
140
- ('statusCode' in error && error.statusCode === 404)));
141
- }
@@ -0,0 +1,2 @@
1
+ import type { ParsedStoryCoverage } from '../parse-story-coverage.mts';
2
+ export declare function runStoryCoverage(parsed: ParsedStoryCoverage): Promise<number>;
@@ -0,0 +1,56 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { checkStoryCoverage } from "../../story-coverage/index.mjs";
3
+ export async function runStoryCoverage(parsed) {
4
+ let marker;
5
+ let storyFilePattern;
6
+ let exclusions;
7
+ try {
8
+ marker = compile(parsed.marker, '--marker');
9
+ storyFilePattern = compile(parsed.storyPattern, '--story-pattern');
10
+ exclusions = parsed.exclusionsFile ? await readExclusions(parsed.exclusionsFile) : {};
11
+ }
12
+ catch (error) {
13
+ process.stderr.write(`${error.message}\n`);
14
+ return 2;
15
+ }
16
+ const report = await checkStoryCoverage({
17
+ root: parsed.root,
18
+ componentRoot: parsed.componentRoot,
19
+ storyRoot: parsed.storyRoot,
20
+ aliases: parsed.aliases,
21
+ sourceExtensions: parsed.sourceExtensions,
22
+ componentExtensions: parsed.componentExtensions,
23
+ marker,
24
+ storyFilePattern,
25
+ exclusions,
26
+ ...(parsed.exclusionsLabel === undefined ? {} : { exclusionsLabel: parsed.exclusionsLabel }),
27
+ });
28
+ for (const message of report.messages)
29
+ process.stderr.write(`${message}\n`);
30
+ if (!report.ok) {
31
+ process.stderr.write('Component story coverage check failed\n');
32
+ return 1;
33
+ }
34
+ return 0;
35
+ }
36
+ function compile(source, flag) {
37
+ try {
38
+ return new RegExp(source);
39
+ }
40
+ catch {
41
+ throw new Error(`story-coverage ${flag} is not a valid regular expression`);
42
+ }
43
+ }
44
+ async function readExclusions(file) {
45
+ let parsed;
46
+ try {
47
+ parsed = JSON.parse(await readFile(file, 'utf8'));
48
+ }
49
+ catch {
50
+ throw new Error(`story-coverage could not read exclusions: ${file}`);
51
+ }
52
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
53
+ throw new Error('story-coverage exclusions must be a JSON object');
54
+ }
55
+ return parsed;
56
+ }
@@ -21,6 +21,7 @@ import { runRetrospectiveFactsCommand } from "./commands/retrospective-facts.mjs
21
21
  import { runAgentBlackboardCommand } from "./commands/agent-blackboard.mjs";
22
22
  import { runMcpCommand } from "./commands/mcp.mjs";
23
23
  import { runWorktreeCommand } from "./commands/worktree.mjs";
24
+ import { runHostStoragePreflightCli } from "../host-storage/cli.mjs";
24
25
  import { runWithHostLock } from "./commands/with-host-lock.mjs";
25
26
  import { runFreshBase } from "./commands/fresh-base.mjs";
26
27
  import { runRequireUpToDate } from "./commands/require-up-to-date.mjs";
@@ -29,6 +30,7 @@ import { runAstGrepPackCommand } from "./commands/ast-grep-pack.mjs";
29
30
  import { runGhaWorkspacePolicy } from "./commands/gha-workspace-policy.mjs";
30
31
  import { readInstalledVersion } from "./installed-version.mjs";
31
32
  import { parseCli } from "./parse.mjs";
33
+ import { runStoryCoverageLazy } from "./story-coverage-lazy.mjs";
32
34
  import { packageScriptPath } from "./script-path.mjs";
33
35
  import { commandUsage, printUsage } from "./usage.mjs";
34
36
  const SCRIPT_PATHS = {
@@ -99,6 +101,8 @@ export function runCli(argv = process.argv) {
99
101
  return runRunnerPortPolicy(parsed);
100
102
  case 'with-host-lock':
101
103
  return runWithHostLock(parsed.args);
104
+ case 'host-storage':
105
+ return runHostStoragePreflightCli(parsed.args);
102
106
  case 'gha-runtime-audit':
103
107
  return runGhaRuntimeAudit(parsed);
104
108
  case 'script': {
@@ -125,6 +129,8 @@ export function runCli(argv = process.argv) {
125
129
  return runHttpOrigin(parsed.field, parsed.value);
126
130
  case 'gha-artifacts-cleanup':
127
131
  return runGhaArtifactsCleanup(parsed);
132
+ case 'story-coverage':
133
+ return runStoryCoverageLazy(parsed);
128
134
  case 'retrospective-transcript':
129
135
  return runRetrospectiveTranscriptCommand(parsed.args);
130
136
  case 'link-skill':
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Loads a command module that value-imports an optional peer dependency. A missing peer becomes
3
+ * an actionable error; any other load failure is rethrown unchanged.
4
+ */
5
+ export declare function loadWithOptionalPeer<T>(command: string, peer: string, load: () => Promise<T>): Promise<T>;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Loads a command module that value-imports an optional peer dependency. A missing peer becomes
3
+ * an actionable error; any other load failure is rethrown unchanged.
4
+ */
5
+ export async function loadWithOptionalPeer(command, peer, load) {
6
+ try {
7
+ return await load();
8
+ }
9
+ catch (error) {
10
+ if (error.code === 'ERR_MODULE_NOT_FOUND' &&
11
+ error instanceof Error &&
12
+ error.message.includes(`'${peer}'`)) {
13
+ throw new Error(`${command} requires the optional peer dependency ${peer}; install it alongside vouchington-tooling`, { cause: error });
14
+ }
15
+ throw error;
16
+ }
17
+ }
@@ -1,6 +1,9 @@
1
1
  type ForwardedCommand = {
2
2
  kind: 'with-host-lock';
3
3
  args: string[];
4
+ } | {
5
+ kind: 'host-storage';
6
+ args: string[];
4
7
  } | {
5
8
  kind: 'pnpm-install';
6
9
  args: string[];
@@ -1,6 +1,8 @@
1
1
  export function parseForwardedCommand(command, args) {
2
2
  if (command === 'with-host-lock')
3
3
  return { kind: 'with-host-lock', args };
4
+ if (command === 'host-storage')
5
+ return { kind: 'host-storage', args };
4
6
  if (command === 'pnpm-install')
5
7
  return { kind: 'pnpm-install', args };
6
8
  if (command === 'vitest-blob-manifest')
@@ -0,0 +1,19 @@
1
+ export type ParsedStoryCoverage = {
2
+ kind: 'story-coverage';
3
+ root: string;
4
+ componentRoot: string;
5
+ storyRoot: string;
6
+ aliases: Record<string, string>;
7
+ sourceExtensions: string[];
8
+ componentExtensions: string[];
9
+ marker: string;
10
+ storyPattern: string;
11
+ exclusionsFile?: string;
12
+ exclusionsLabel?: string;
13
+ };
14
+ export declare function emptyParsed(): ParsedStoryCoverage;
15
+ export declare function applyFlag(parsed: ParsedStoryCoverage, flag: string, value: string): string | undefined;
16
+ export declare function missingField(parsed: ParsedStoryCoverage): {
17
+ kind: 'error';
18
+ message: string;
19
+ } | undefined;
@@ -0,0 +1,69 @@
1
+ export function emptyParsed() {
2
+ return {
3
+ kind: 'story-coverage',
4
+ root: '',
5
+ componentRoot: '',
6
+ storyRoot: '',
7
+ aliases: {},
8
+ sourceExtensions: [],
9
+ componentExtensions: [],
10
+ marker: '',
11
+ storyPattern: '',
12
+ };
13
+ }
14
+ export function applyFlag(parsed, flag, value) {
15
+ if (value === '')
16
+ return `${flag} requires a value`;
17
+ if (flag === '--alias')
18
+ return applyAlias(parsed, value);
19
+ if (flag === '--source-extension') {
20
+ parsed.sourceExtensions.push(value);
21
+ return undefined;
22
+ }
23
+ if (flag === '--component-extension') {
24
+ parsed.componentExtensions.push(value);
25
+ return undefined;
26
+ }
27
+ const field = scalarField(flag);
28
+ if (field)
29
+ parsed[field] = value;
30
+ else
31
+ parsed.exclusionsLabel = value;
32
+ return undefined;
33
+ }
34
+ function scalarField(flag) {
35
+ if (flag === '--root')
36
+ return 'root';
37
+ if (flag === '--component-root')
38
+ return 'componentRoot';
39
+ if (flag === '--story-root')
40
+ return 'storyRoot';
41
+ if (flag === '--marker')
42
+ return 'marker';
43
+ if (flag === '--story-pattern')
44
+ return 'storyPattern';
45
+ if (flag === '--exclusions')
46
+ return 'exclusionsFile';
47
+ return undefined;
48
+ }
49
+ function applyAlias(parsed, value) {
50
+ const split = value.indexOf('=');
51
+ if (split <= 0 || split === value.length - 1)
52
+ return '--alias must be <prefix>=<path>';
53
+ parsed.aliases[value.slice(0, split)] = value.slice(split + 1);
54
+ return undefined;
55
+ }
56
+ export function missingField(parsed) {
57
+ const missing = [
58
+ [parsed.root, '--root'],
59
+ [parsed.componentRoot, '--component-root'],
60
+ [parsed.storyRoot, '--story-root'],
61
+ [parsed.sourceExtensions.length > 0 ? 'set' : '', '--source-extension'],
62
+ [parsed.componentExtensions.length > 0 ? 'set' : '', '--component-extension'],
63
+ [parsed.marker, '--marker'],
64
+ [parsed.storyPattern, '--story-pattern'],
65
+ ].find(([value]) => value === '');
66
+ if (!missing)
67
+ return undefined;
68
+ return { kind: 'error', message: `story-coverage requires ${missing[1]}` };
69
+ }
@@ -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
+ };