rungate 0.4.1 → 0.6.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 (87) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/agents-md-sections.ts +144 -0
  11. package/lib/branch-diff.ts +139 -0
  12. package/lib/bun-version.ts +268 -0
  13. package/lib/ci-checkout.ts +1 -1
  14. package/lib/cli-commands.ts +7 -1
  15. package/lib/compliance.ts +13 -11
  16. package/lib/config-loader.ts +12 -0
  17. package/lib/conformity.ts +1147 -116
  18. package/lib/context-docs.ts +143 -28
  19. package/lib/create-brief.ts +2 -1
  20. package/lib/create-sc.ts +90 -4
  21. package/lib/doc-scan-targets.ts +9 -0
  22. package/lib/evidence-command-transport.ts +160 -0
  23. package/lib/evidence-prevalidator.ts +22 -0
  24. package/lib/fallow-availability.ts +129 -0
  25. package/lib/gate-refusal-currency.ts +112 -0
  26. package/lib/gate-timeouts.ts +82 -0
  27. package/lib/generators/agent-briefs.ts +4 -1
  28. package/lib/generators/agents-md.ts +71 -23
  29. package/lib/generators/code-map.ts +2 -1
  30. package/lib/generators/types.ts +8 -0
  31. package/lib/git-dates.ts +55 -0
  32. package/lib/github.ts +195 -0
  33. package/lib/js-top-level-code.ts +27 -2
  34. package/lib/junit-checks.ts +484 -0
  35. package/lib/local-calendar-day.ts +78 -0
  36. package/lib/package-closure.ts +278 -2
  37. package/lib/project-state-shape.ts +59 -0
  38. package/lib/promote-outputs.ts +6 -2
  39. package/lib/release-preflight.ts +196 -0
  40. package/lib/report-provenance.ts +156 -0
  41. package/lib/sc-claim-forms.ts +75 -0
  42. package/lib/sc-id-cross-tree.ts +311 -0
  43. package/lib/scaffold/ai-review-step.ts +180 -0
  44. package/lib/scaffold/defaults.ts +40 -0
  45. package/lib/scaffold/managed-workflow.ts +125 -27
  46. package/lib/scaffold/owned-files.ts +48 -2
  47. package/lib/scaffold/profiles.ts +94 -0
  48. package/lib/scaffold/rehearsal.ts +232 -73
  49. package/lib/scaffold/steps.ts +777 -152
  50. package/lib/scaffold/write-steps.ts +56 -13
  51. package/lib/scanner.ts +38 -12
  52. package/lib/source-anchor.ts +144 -0
  53. package/lib/spec-listing.ts +148 -0
  54. package/lib/spec-requirements.ts +209 -0
  55. package/lib/success-doc.ts +779 -0
  56. package/lib/suite-run-reading.ts +364 -0
  57. package/lib/test-census.ts +199 -0
  58. package/lib/test-command.ts +133 -0
  59. package/lib/test-suite-lock.ts +166 -10
  60. package/lib/tool-probe.ts +120 -0
  61. package/lib/tracked-vs-ignored.ts +234 -0
  62. package/lib/trajectory.ts +377 -0
  63. package/lib/validators/spec-validators.ts +35 -6
  64. package/lib/workflow-security.ts +101 -0
  65. package/lib/workflow-test-harness.ts +349 -0
  66. package/package.json +6 -1
  67. package/scripts/audit-specs.ts +247 -12
  68. package/scripts/audit-transcript.ts +2 -1
  69. package/scripts/convert-spec.ts +2 -1
  70. package/scripts/create-sc.ts +17 -7
  71. package/scripts/create-spec.ts +2 -1
  72. package/scripts/create-success.ts +163 -0
  73. package/scripts/extract-constraints.ts +90 -19
  74. package/scripts/generate-code-map.ts +53 -12
  75. package/scripts/scaffold-project.ts +31 -4
  76. package/scripts/split-spec.ts +2 -1
  77. package/scripts/sync-sc-status.ts +57 -5
  78. package/scripts/sync-spec-tests.ts +2 -1
  79. package/specs/SPEC-TEMPLATE.md +200 -0
  80. package/templates/SUCCESS-TEMPLATE.md +72 -0
  81. package/templates/agent-briefs/_shared.md +9 -0
  82. package/templates/agent-briefs/aditi.md +46 -0
  83. package/templates/agent-briefs/discovery.md +37 -0
  84. package/templates/agent-briefs/marcus.md +39 -0
  85. package/templates/agent-briefs/quinn.md +67 -0
  86. package/templates/agent-briefs/rook.md +40 -0
  87. package/templates/agent-briefs/serena.md +39 -0
@@ -0,0 +1,133 @@
1
+ /**
2
+ * The one test command for a project (#488).
3
+ *
4
+ * The scaffold read `dev.testCmd` in four places and wrote it into
5
+ * everything an agent reads — AGENTS.md's Commands table, the agent briefs,
6
+ * the ship workflow — and then generated a CI workflow that ran `bun test`
7
+ * regardless. `createCiWorkflows` had `harness` in scope and reached for
8
+ * `harness?.ci?.bunVersion`, `?.runner` and `?.branches` four lines above
9
+ * the hardcode.
10
+ *
11
+ * The divergence is silent in both directions. If the consumer's command is
12
+ * a superset, CI is weaker than the gate every agent was told about. If
13
+ * `bun test` does not work in their project at all, CI is red for a reason
14
+ * no config change can fix, because the field that would fix it is not
15
+ * read.
16
+ *
17
+ * ## Why this is a module and not four `||` chains that agree
18
+ *
19
+ * They did not agree. Four sites resolved the same question four ways:
20
+ *
21
+ * | Site | Ladder |
22
+ * |---|---|
23
+ * | `createCiWorkflows` | `"bun test"` |
24
+ * | `generateAgentsMdContent` | `dev.testCmd \|\| "bun test"` |
25
+ * | `scanProject` | `package.json scripts.test \|\| "bun test"` |
26
+ * | `generateAgentBriefs` | `dev.testCmd \|\| scan.testCmd \|\| "bun test"` |
27
+ *
28
+ * So a consumer with a `scripts.test` and no `dev.testCmd` was told one
29
+ * command by AGENTS.md and another by CI, and two sites that happen to
30
+ * agree today are one decider too many — only a mutation of a SHARED
31
+ * binding can show that the agreement is load-bearing rather than
32
+ * coincidental. This is #87's fix for the type check, applied to the step
33
+ * directly below the one #87 collapsed.
34
+ *
35
+ * ## The rungs, and what each one is not
36
+ *
37
+ * 1. **`dev.testCmd` from the rungate config.** The operator said so, in
38
+ * the field the harness documents for exactly this.
39
+ * 2. **`package.json` `scripts.test`, verbatim.** The value, not `bun run
40
+ * test`. That is the existing behaviour of `scanProject`, so this rung
41
+ * is a collapse rather than a new judgement — and `bun run test` would
42
+ * fire `pretest`/`posttest`, which on this repo means CI running
43
+ * `sync-sc-status.ts` and writing to the tree.
44
+ * 3. **`bun test`.** Unchanged for every consumer that declares neither.
45
+ *
46
+ * ## What this does NOT cover
47
+ *
48
+ * `workflows/ship.js` resolves `test.command || dev.testCmd || 'bun test'`
49
+ * and cannot import (#69). It is the fifth site and it stays its own, which
50
+ * is a known gap rather than an oversight — the subprocess boundary is how
51
+ * workflows comply with `.claude/rules/config-access.md`.
52
+ */
53
+ import { existsSync, readFileSync } from "fs";
54
+ import { join } from "path";
55
+ import { tryLoadRungateConfig } from "./config-loader";
56
+
57
+ export type TestCommandSource = "config" | "package-script" | "default";
58
+
59
+ export interface TestCommandDecision {
60
+ /** The shell command. Never null — every project can run something. */
61
+ command: string;
62
+ source: TestCommandSource;
63
+ /** Why this command and not another. */
64
+ reason: string;
65
+ }
66
+
67
+ export const DEFAULT_TEST_COMMAND = "bun test";
68
+
69
+ export function testCommandDecision(root: string): TestCommandDecision {
70
+ // Through the loader, never a constructed path to `.claude/rungate*`
71
+ // (`.claude/rules/config-access.md`). It also means both config layouts
72
+ // are honoured — a consumer who followed the documented migration to the
73
+ // directory form is the exact population a monolith-only read loses.
74
+ //
75
+ // It THROWS on a malformed config, deliberately: a corrupt config is
76
+ // never a missing config, and `catch {}` here is the conversion that rule
77
+ // exists to forbid. The one caller that must survive corruption is the
78
+ // config REPAIR step, and it calls `inferredTestCommand` instead — see
79
+ // below for why that is not a loophole.
80
+ const config = tryLoadRungateConfig(root) as { dev?: { testCmd?: unknown } } | null;
81
+ const declared = config?.dev?.testCmd;
82
+ if (typeof declared === "string" && declared.trim() !== "") {
83
+ return {
84
+ command: declared,
85
+ source: "config",
86
+ reason: "the project declares `dev.testCmd`, which beats anything inferred",
87
+ };
88
+ }
89
+
90
+ return inferredTestCommand(root);
91
+ }
92
+
93
+ /**
94
+ * The same decision with the config rung removed — what this project's test
95
+ * command would be if the config said nothing.
96
+ *
97
+ * Exactly one caller, and it is not a convenience: `generateOrAuditProjectHarness`
98
+ * chooses the value to WRITE into `dev.testCmd`, so asking the loader for
99
+ * `dev.testCmd` first is circular, and it runs against trees whose config is
100
+ * malformed — that is what it exists to repair. Routing it through the
101
+ * throwing loader killed the repair with `SyntaxError: JSON Parse error` in
102
+ * the step whose job is to fix that file.
103
+ *
104
+ * Split rather than flagged, because a boolean parameter makes the two
105
+ * behaviours one call site's argument rather than two named things, and the
106
+ * shared rungs stay shared either way.
107
+ */
108
+ export function inferredTestCommand(root: string): TestCommandDecision {
109
+ const pkgPath = join(root, "package.json");
110
+ if (existsSync(pkgPath)) {
111
+ try {
112
+ const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
113
+ const script = pkg?.scripts?.test;
114
+ if (typeof script === "string" && script.trim() !== "") {
115
+ return {
116
+ command: script,
117
+ source: "package-script",
118
+ reason: "the project declares a `test` script and no `dev.testCmd`",
119
+ };
120
+ }
121
+ } catch {
122
+ // An unreadable package.json is not a reason to lose the test command.
123
+ // The default below needs no package.json at all, and this module's
124
+ // neighbours already shrug at this rather than killing the scaffold.
125
+ }
126
+ }
127
+
128
+ return {
129
+ command: DEFAULT_TEST_COMMAND,
130
+ source: "default",
131
+ reason: "the project declares neither `dev.testCmd` nor a `test` script",
132
+ };
133
+ }
@@ -26,6 +26,7 @@ import {
26
26
  mkdirSync,
27
27
  openSync,
28
28
  readFileSync,
29
+ realpathSync,
29
30
  renameSync,
30
31
  statSync,
31
32
  unlinkSync,
@@ -708,6 +709,13 @@ export function acquireFullSuiteSlot(
708
709
 
709
710
  export interface GateDecision {
710
711
  allow: boolean;
712
+ /**
713
+ * Present when the run was allowed because it is not a run of THIS
714
+ * repository (#510). Allowed-and-quiet would make an exemption
715
+ * indistinguishable from a budget that was never spent, so it is named
716
+ * here and recorded on disk.
717
+ */
718
+ exempt?: string;
711
719
  /** Present when refused — shown verbatim to the caller. Never silent. */
712
720
  reason?: string;
713
721
  /**
@@ -860,6 +868,117 @@ export interface GateOptions extends LockOptions {
860
868
  runId?: string;
861
869
  /** Overrides the per-run ceiling. Tests only; there is no environment path. */
862
870
  maxRunsPerPipeline?: number;
871
+ /**
872
+ * The working directory the command will run in (#510). Used to decide
873
+ * whether this is a run of the guarded repository or of a scratch tree
874
+ * somewhere else. Absent means UNKNOWN, which is charged — the budget
875
+ * fails closed, as the rest of this module does.
876
+ */
877
+ cwd?: string;
878
+ /** Injected scope, so a test need not build a git repository to drive it. */
879
+ scope?: RunScope;
880
+ }
881
+
882
+ /**
883
+ * Whose suite this is.
884
+ *
885
+ * - `project` — a tree of the repository this guard belongs to, including
886
+ * every one of its worktrees. Charged.
887
+ * - `scratch` — a directory that EXISTS and is not part of it: a `git
888
+ * archive` export under /tmp, a fixture repo a test just created, another
889
+ * checkout entirely. Not charged.
890
+ * - `unknown` — the question could not be answered: no cwd, a path that is
891
+ * not there, a git that would not run. Charged, because a guard that opens
892
+ * on an error is the shape this repo keeps finding.
893
+ *
894
+ * The line between the last two is "I looked and it is not this repository"
895
+ * against "I could not look". A `git archive` export has no `.git` and is
896
+ * the case that filed #510, so a git-less directory must be scratch — but
897
+ * only once something has confirmed the directory is really there.
898
+ */
899
+ export type RunScope = "project" | "scratch" | "unknown";
900
+
901
+ /** The guarded repository's shared git directory, resolved once. */
902
+ function projectCommonDir(): string | null {
903
+ try {
904
+ const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
905
+ cwd: join(import.meta.dir, ".."),
906
+ encoding: "utf-8",
907
+ timeout: 10_000,
908
+ stdio: ["ignore", "pipe", "pipe"],
909
+ });
910
+ return realpathSync(out.trim());
911
+ } catch {
912
+ return null;
913
+ }
914
+ }
915
+
916
+ /**
917
+ * Is this working directory part of the repository the guard is installed in?
918
+ *
919
+ * The comparison is the **shared git directory**, not the path: all 110
920
+ * worktrees of this repository answer with one `.git`, and they are all real
921
+ * runs that must be charged. A `git archive` export has no `.git` at all, and
922
+ * a fixture built by `git init` has its own — both scratch.
923
+ *
924
+ * ## Why this is not a /tmp denylist
925
+ *
926
+ * A path prefix is a detector narrower than what it detects: a reviewer's
927
+ * probe under `~/scratch` would be charged, and a real checkout under /tmp
928
+ * would be exempt. The question is "whose suite is this", and git already
929
+ * answers it exactly.
930
+ */
931
+ export function runScope(cwd: string | undefined, projectDir?: string | null): RunScope {
932
+ if (!cwd) return "unknown";
933
+ try {
934
+ if (!statSync(cwd).isDirectory()) return "unknown";
935
+ } catch {
936
+ return "unknown";
937
+ }
938
+ const project = projectDir === undefined ? projectCommonDir() : projectDir;
939
+ if (project === null) return "unknown";
940
+ try {
941
+ const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
942
+ cwd,
943
+ encoding: "utf-8",
944
+ timeout: 10_000,
945
+ stdio: ["ignore", "pipe", "pipe"],
946
+ });
947
+ return realpathSync(out.trim()) === project ? "project" : "scratch";
948
+ } catch {
949
+ // The directory is there and git will not claim it: not a repository at
950
+ // all, which is what a `git archive` export is. Not a run of the guarded
951
+ // project, and charging it is the thing #510 is about.
952
+ return "scratch";
953
+ }
954
+ }
955
+
956
+ /** Where exempted runs are recorded, so the exemption is auditable. */
957
+ export function scratchRunsPath(lockDir: string): string {
958
+ return join(lockDir, "full-suite.scratch-runs.json");
959
+ }
960
+
961
+ /**
962
+ * Record an exempted run. Best-effort, like the budget counter — but it is
963
+ * the only trace an exemption leaves, so losing it costs visibility rather
964
+ * than enforcement.
965
+ */
966
+ function recordScratchRun(lockDir: string, now: number, cwd: string | undefined): void {
967
+ try {
968
+ const path = scratchRunsPath(lockDir);
969
+ let runs: Array<{ at: number; cwd: string }> = [];
970
+ try {
971
+ const parsed = JSON.parse(readFileSync(path, "utf-8"));
972
+ if (Array.isArray(parsed?.runs)) runs = parsed.runs;
973
+ } catch {
974
+ // An unreadable or absent log starts a new one. This file is a record,
975
+ // never an input to a decision, so a lost entry cannot open a gate.
976
+ }
977
+ runs.push({ at: now, cwd: cwd ?? "" });
978
+ writeFileSync(path, JSON.stringify({ runs: runs.slice(-200) }));
979
+ } catch {
980
+ // Recording must never be able to block a run it is not guarding.
981
+ }
863
982
  }
864
983
 
865
984
  interface BudgetView {
@@ -1045,19 +1164,53 @@ export function evaluateFullSuiteRequest(
1045
1164
  command: string,
1046
1165
  options: GateOptions = {},
1047
1166
  ): GateDecision {
1048
- const predicted = wouldAllowFullSuite(sessionId, command, options);
1049
- if (!predicted.allow) return predicted;
1050
- // Targeted runs are neither capped nor counted, so there is nothing to spend.
1167
+ // Targeted runs are neither capped nor counted, so there is nothing to
1168
+ // spend. Asked FIRST, because the scope question below costs a subprocess
1169
+ // and the overwhelming majority of Bash commands are not suites at all.
1051
1170
  if (!isFullSuiteCommand(command)) return { allow: true };
1052
1171
 
1053
1172
  const lockDir = options.lockDir ?? defaultLockDir();
1054
1173
  const now = options.now ?? Date.now();
1055
1174
 
1175
+ // A full suite of somebody else's tree is not this repository's suite
1176
+ // (#510). A reviewer's mutation probe on a `git archive` export is twenty
1177
+ // tests and under a second, and charging it against a budget sized for a
1178
+ // 400-second 12,000-test run made careful review the thing the guard
1179
+ // rationed. Scope is decided here and only here: `wouldAllowFullSuite`
1180
+ // below must not answer the same question, or there would be two deciders
1181
+ // and no behavioural test could tell them apart.
1182
+ //
1183
+ // It exempts the BUDGET and not the concurrency slot, and the distinction
1184
+ // is the whole of the design. The budget is a rate — the wrong unit for a
1185
+ // one-second probe. The slot is simultaneity, which is what rebooted the
1186
+ // machine in #67, and a scratch tree can be a full clone. Two further
1187
+ // reasons it must not skip the slot: `TestSuiteRelease` releases on the
1188
+ // same `isFullSuiteCommand` predicate with no notion of scope, so an
1189
+ // acquire this side skipped would free a slot somebody else is holding;
1190
+ // and "cd into /tmp to escape the cap" would be a bypass anyone could
1191
+ // reach for.
1192
+ const scope = options.scope ?? runScope(options.cwd);
1193
+
1194
+ const predicted = scope === "scratch" ? { allow: true } : wouldAllowFullSuite(sessionId, command, options);
1195
+ if (!predicted.allow) return predicted;
1196
+
1056
1197
  // The prediction above is advisory; this is the atomic claim. Another session
1057
1198
  // can take the last slot in between, and then the acquirer's answer wins.
1058
1199
  const slot = acquireFullSuiteSlot(sessionId, options);
1059
1200
  if (!slot.ok) return concurrencyRefusal(sessionId, slot.holders ?? []);
1060
1201
 
1202
+ if (scope === "scratch") {
1203
+ recordScratchRun(lockDir, now, options.cwd);
1204
+ return {
1205
+ allow: true,
1206
+ exempt:
1207
+ `not a run of this repository (${options.cwd ?? "unknown cwd"}), so it is not charged ` +
1208
+ `against DIR-L29 — recorded in ${scratchRunsPath(lockDir)}. It still holds a ` +
1209
+ `concurrency slot, which is what the cap is actually for.`,
1210
+ ...(slot.degraded ? { warning: degradedWarning(lockDir) } : {}),
1211
+ };
1212
+ }
1213
+
1061
1214
  try {
1062
1215
  // Only the in-window runs are carried forward, and never more than the
1063
1216
  // tracked maximum, so neither a long session nor a poisoned file can leave
@@ -1078,17 +1231,20 @@ export function evaluateFullSuiteRequest(
1078
1231
  }
1079
1232
 
1080
1233
  if (slot.degraded) {
1081
- return {
1082
- allow: true,
1083
- warning:
1084
- `Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
1085
- `was allowed without taking a slot. The cap is not being enforced right now. ` +
1086
- `Check with other sessions before starting a full suite.`,
1087
- };
1234
+ return { allow: true, warning: degradedWarning(lockDir) };
1088
1235
  }
1089
1236
  return { allow: true };
1090
1237
  }
1091
1238
 
1239
+ /** One wording for the degraded case, so the two exits cannot drift apart. */
1240
+ function degradedWarning(lockDir: string): string {
1241
+ return (
1242
+ `Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
1243
+ `was allowed without taking a slot. The cap is not being enforced right now. ` +
1244
+ `Check with other sessions before starting a full suite.`
1245
+ );
1246
+ }
1247
+
1092
1248
  /**
1093
1249
  * Give up ONE slot for a finished suite. Releasing one you do not hold is a no-op.
1094
1250
  *
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Asking whether an external tool is there, with three answers instead of one
3
+ * (#626 AC-10, #597).
4
+ *
5
+ * `lib/compliance.ts` asked it with a boolean:
6
+ *
7
+ * function checkToolAvailable(command, args): boolean {
8
+ * try {
9
+ * const result = Bun.spawnSync([command, ...args], { timeout: 5_000 });
10
+ * return result.exitCode === 0 || result.stdout.toString().length > 0;
11
+ * } catch { return false; }
12
+ * }
13
+ *
14
+ * `false` meant "the tool is not installed", "the tool is installed and the
15
+ * probe failed", and "npx went to the registry and the registry was slow"
16
+ * alike. That is the fail-open shape `.claude/rules/checks-must-be-able-to-fail.md`
17
+ * opens with, in the place it costs the most: three Layer 1 compliance tests
18
+ * go red or green in CI depending on whether `npx @reporails/cli version`
19
+ * reaches the network, and the verdict cannot say which of the three happened
20
+ * — proven on #597 by re-running an identical SHA red to green with no code
21
+ * change.
22
+ *
23
+ * So the probe has three outcomes and a `reason`, and the boolean every
24
+ * existing caller wants is derived from the outcome rather than being the
25
+ * whole reading. A consumer that only needs "can I run this" keeps working;
26
+ * a consumer that needs to report UNMEASURED now has something to report it
27
+ * from.
28
+ *
29
+ * ## Why `absent` is decided by the spawn failing, not by an exit code
30
+ *
31
+ * A tool that is not on `PATH` makes `Bun.spawnSync` throw before any process
32
+ * exists; a tool that is there and unhappy exits non-zero. Those are the two
33
+ * facts, and they arrive by two different routes, which is what makes the
34
+ * distinction honest rather than a reading of an exit code nobody standardised.
35
+ *
36
+ * `npx <pkg> version` is the awkward case and is deliberately NOT special-cased:
37
+ * `npx` is always present, so an uninstalled package surfaces as `errored`, not
38
+ * `absent`. That is the truth about what was observed — the probe ran and did
39
+ * not succeed — and inventing `absent` from a parse of npx's stderr would be a
40
+ * detector narrower than what it detects.
41
+ */
42
+
43
+ /** The three things a probe can find. Ordered as they are reported. */
44
+ export const TOOL_PROBE_OUTCOMES = ["available", "absent", "errored"] as const;
45
+
46
+ export type ToolProbeOutcome = (typeof TOOL_PROBE_OUTCOMES)[number];
47
+
48
+ export interface ToolProbe {
49
+ outcome: ToolProbeOutcome;
50
+ /**
51
+ * The old boolean, derived. Present so a caller that genuinely only needs
52
+ * "can I run this" does not have to re-derive it — and so the collapse is
53
+ * visible as a projection of the reading rather than as the reading itself.
54
+ */
55
+ available: boolean;
56
+ /** The command probed, as it was asked for. */
57
+ tool: string;
58
+ /** The exit code, or null when no process ever existed. */
59
+ exitCode: number | null;
60
+ /** One line a log reader can act on. */
61
+ reason: string;
62
+ }
63
+
64
+ export interface ToolProbeOptions {
65
+ timeoutMs?: number;
66
+ }
67
+
68
+ /** The probe's own budget. A tool that cannot answer in five seconds is not ready to be used in a gate. */
69
+ export const TOOL_PROBE_TIMEOUT_MS = 5_000;
70
+
71
+ export function probeExternalTool(command: string, args: string[] = [], opts?: ToolProbeOptions): ToolProbe {
72
+ const tool = [command, ...args].join(" ");
73
+ let exitCode: number | null = null;
74
+ let stdout = "";
75
+ let stderr = "";
76
+
77
+ try {
78
+ const result = Bun.spawnSync([command, ...args], {
79
+ timeout: opts?.timeoutMs ?? TOOL_PROBE_TIMEOUT_MS,
80
+ stdout: "pipe",
81
+ stderr: "pipe",
82
+ });
83
+ exitCode = typeof result.exitCode === "number" ? result.exitCode : null;
84
+ stdout = result.stdout?.toString() ?? "";
85
+ stderr = result.stderr?.toString() ?? "";
86
+ } catch (e) {
87
+ // No process was created at all. That is the one condition that means the
88
+ // tool is not here, and it is why this branch is not merged with a
89
+ // non-zero exit below.
90
+ const message = e instanceof Error ? e.message : String(e);
91
+ return {
92
+ outcome: "absent",
93
+ available: false,
94
+ tool,
95
+ exitCode: null,
96
+ reason: `${command} is not on PATH: ${message.split("\n")[0]}`,
97
+ };
98
+ }
99
+
100
+ if (exitCode === 0 || stdout.trim().length > 0) {
101
+ return {
102
+ outcome: "available",
103
+ available: true,
104
+ tool,
105
+ exitCode,
106
+ reason: `${tool} ran and answered (exit ${exitCode})`,
107
+ };
108
+ }
109
+
110
+ return {
111
+ outcome: "errored",
112
+ available: false,
113
+ tool,
114
+ exitCode,
115
+ reason:
116
+ `${tool} ran and did not succeed (exit ${exitCode})` +
117
+ (stderr.trim() ? `: ${stderr.trim().split("\n")[0].slice(0, 200)}` : "") +
118
+ ` — the tool was reachable, so this is not the same as it being absent`,
119
+ };
120
+ }