@cbartens/bkit 5.1.0 → 5.2.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 (194) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +90 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  136. package/.bkit/templates/.prettierignore +1 -1
  137. package/.bkit/templates/context/bkit-expo.md +22 -13
  138. package/.bkit/templates/context/bkit-github.md +20 -6
  139. package/.bkit/templates/context/bkit-inngest.md +10 -4
  140. package/.bkit/templates/context/bkit-maestro.md +5 -5
  141. package/.bkit/templates/context/bkit-playwright.md +3 -3
  142. package/.bkit/templates/context/bkit-sentry.md +6 -5
  143. package/.bkit/templates/context/bkit-stripe.md +31 -8
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  145. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  147. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  148. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  149. package/.bkit/templates/slop-scan.config.json +7 -2
  150. package/CHANGELOG.md +42 -0
  151. package/LICENSE.md +21 -161
  152. package/README.md +58 -28
  153. package/dist/checks/after/auth.js +28 -0
  154. package/dist/checks/after/github.js +4 -4
  155. package/dist/checks/after/index.js +29 -45
  156. package/dist/checks/after/managed.js +40 -1
  157. package/dist/checks/before/index.js +5 -4
  158. package/dist/checks/before/mcp.js +53 -53
  159. package/dist/checks/status-holes.js +1 -1
  160. package/dist/checks/tips/catalogue.js +297 -0
  161. package/dist/checks/tips/detect.js +130 -0
  162. package/dist/checks/tips/index.js +146 -0
  163. package/dist/cli.js +47 -9
  164. package/dist/commands/install/doctor.js +5 -1
  165. package/dist/commands/install/install.js +27 -7
  166. package/dist/commands/install/uninstall.js +31 -16
  167. package/dist/commands/install/upgrade.js +15 -32
  168. package/dist/commands/launch.js +27 -11
  169. package/dist/commands/tips.js +10 -0
  170. package/dist/commands/workflow/runs.js +52 -16
  171. package/dist/commands/workflow/runtime.js +8 -0
  172. package/dist/commands/workflow/steps.js +1 -0
  173. package/dist/commands/workflow/tests.js +541 -4
  174. package/dist/commands/workflow/workstreams.js +4 -4
  175. package/dist/install/cloud-env.js +3 -14
  176. package/dist/install/hosts.js +22 -0
  177. package/dist/install/managed-block.js +36 -0
  178. package/dist/install/manifest.js +45 -4
  179. package/dist/install/modules/antigravity.js +8 -7
  180. package/dist/install/modules/claude.js +6 -6
  181. package/dist/install/modules/cloud.js +2 -2
  182. package/dist/install/modules/codex.js +5 -5
  183. package/dist/install/modules/core.js +14 -5
  184. package/dist/install/modules/cursor.js +6 -6
  185. package/dist/install/modules/opencode.js +4 -4
  186. package/dist/install/payload-links.js +5 -5
  187. package/dist/install/placeholders.js +1 -1
  188. package/dist/install/version-file.js +12 -3
  189. package/dist/install/write.js +61 -2
  190. package/dist/shared/package-roots.js +8 -11
  191. package/package.json +4 -6
  192. package/.bkit/core/LICENSE.md +0 -149
  193. package/.bkit/shared/LICENSE.md +0 -22
  194. package/.bkit/templates/LICENSE.md +0 -22
@@ -17,6 +17,9 @@
17
17
  // CLAUDE_CODE_REMOTE truthy CLOUD_CLAUDE
18
18
  // GITHUB_ACTIONS or CI truthy GITHUB_ACTION
19
19
  // otherwise LOCAL
20
+ //
21
+ // `runtimeHeadless` (no human attends the session) is derived from `runtime`, never
22
+ // stored on the row.
20
23
  import * as fs from "node:fs";
21
24
  import * as path from "node:path";
22
25
  import { statusTimestamp } from "../../ledgers/status.js";
@@ -82,6 +85,8 @@ export function classify(env, root, log) {
82
85
  * session's proxy only lets it push the current branch, so it gets neither.
83
86
  */
84
87
  const capable = (runtime) => runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
88
+ /** No human attends the session: a runner, a triggered Cursor agent, or a runtime bkit cannot place. */
89
+ const headless = (runtime) => runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR" || runtime === "UNKNOWN";
85
90
  /** The full table: classification, default capabilities, and the one live gh probe. */
86
91
  export function detect(cwd, root, log) {
87
92
  const runtime = classify(process.env, root, log);
@@ -95,6 +100,7 @@ export function detect(cwd, root, log) {
95
100
  runtime,
96
101
  runtimeWorktrees: capable(runtime),
97
102
  runtimeDevPushes: capable(runtime),
103
+ runtimeHeadless: headless(runtime),
98
104
  runtimeGithubCli: ok,
99
105
  runtimeGithubCliExit: gh.status,
100
106
  runtimeGithubCliErr: err,
@@ -135,6 +141,7 @@ const TABLE_OUTPUT = {
135
141
  runtime: RUNTIMES.join(" | "),
136
142
  runtimeWorktrees: "may mint git worktrees (default per runtime)",
137
143
  runtimeDevPushes: "may push dev (a default, never probed)",
144
+ runtimeHeadless: "no human attends the session (GITHUB_ACTION | CLOUD_CURSOR | UNKNOWN); derived from runtime",
138
145
  runtimeGithubCli: "gh auth status succeeded",
139
146
  runtimeGithubCliExit: "gh auth status exit code (127 when gh is not on PATH)",
140
147
  runtimeGithubCliErr: "last non-empty line of gh auth status stderr",
@@ -243,6 +250,7 @@ export const runtimeCommand = {
243
250
  runtime: row.runtime,
244
251
  runtimeWorktrees: row.runtimeWorktrees,
245
252
  runtimeDevPushes: row.runtimeDevPushes,
253
+ runtimeHeadless: headless(row.runtime),
246
254
  runtimeGithubCli: row.runtimeGithubCli,
247
255
  runtimeGithubCliExit: typeof row.runtimeGithubCliExit === "number" ? row.runtimeGithubCliExit : null,
248
256
  runtimeGithubCliErr: typeof row.runtimeGithubCliErr === "string" ? row.runtimeGithubCliErr : "",
@@ -208,6 +208,7 @@ export function failuresProblem(verdict, failures) {
208
208
  * calls (a finish call's `--agent` writes `strategy` when its prompt declares one).
209
209
  */
210
210
  export const ROW_FIELDS = {
211
+ "design/design-grill": ["attempt"],
211
212
  "design/design-brainstorm-ideate": ["attempt"],
212
213
  "design/design-generate": ["attempt"],
213
214
  "design/design-review": ["attempt"],
@@ -6,14 +6,22 @@
6
6
  // order is the contract). Nothing declared is its own exit code, never an empty
7
7
  // command that exits 0 and reads as a clean run. A gate that exits 126 / 127 never
8
8
  // ran (not executable / not found), so it is not recorded as a failing test.
9
+ //
10
+ // bkit tests red / green — test-first evidence for build tasks. Both run one test
11
+ // file through the consumer's `bkit:test:file` script and judge its JUnit report,
12
+ // never its exit code alone: a misspelled path, a syntax error and an import of
13
+ // unwritten code all exit non-zero exactly like a real failure. A red counts only
14
+ // when the NAMED test ran and failed; green only when it ran and passed.
9
15
  import { spawnSync } from "node:child_process";
10
16
  import * as fs from "node:fs";
11
17
  import * as os from "node:os";
12
18
  import * as path from "node:path";
19
+ import { BKIT_TEST_FILE_SCRIPT } from "../../install/manifest.js";
13
20
  import { CommandError, EXIT, git } from "../lib.js";
14
21
  import { readPackageJson } from "../../shared/package-json.js";
15
22
  import { COULD_NOT_RUN_EXIT_CODES, scriptCommand } from "../../shared/package-manager.js";
16
- import { str } from "./status.js";
23
+ import { FILE_FLAG, SUB_PLAN_FLAG, WORKFLOW_FLAG, positiveInt, readStatusRows, statusFile, str, } from "./status.js";
24
+ import { writeStepRow } from "./steps.js";
17
25
  /** Exit code: no candidate gate is declared in package.json. */
18
26
  export const EXIT_NO_GATE = 3;
19
27
  /** Exit code: the gate could not run (exit 126 / 127, or the package runner is missing). */
@@ -42,10 +50,14 @@ export const gateScope = (gate) => scriptCommand(gate).join(" ");
42
50
  * Run argv with stdout and stderr interleaved into `log` (like `> log 2>&1`).
43
51
  * Exit 127 when the binary is missing; 128 + n when killed by signal n.
44
52
  */
45
- export function runToLog(argv, cwd, log) {
53
+ export function runToLog(argv, cwd, log, env) {
46
54
  fs.mkdirSync(path.dirname(log), { recursive: true });
47
55
  const fd = fs.openSync(log, "w");
48
- const res = spawnSync(argv[0], argv.slice(1), { cwd, stdio: ["ignore", fd, fd] });
56
+ const res = spawnSync(argv[0], argv.slice(1), {
57
+ cwd,
58
+ stdio: ["ignore", fd, fd],
59
+ env: env === undefined ? process.env : { ...process.env, ...env },
60
+ });
49
61
  fs.closeSync(fd);
50
62
  if (res.error) {
51
63
  fs.appendFileSync(log, `${argv[0]}: not found on PATH (${res.error.message})\n`);
@@ -56,9 +68,220 @@ export function runToLog(argv, cwd, log) {
56
68
  return 128 + ((res.signal ? os.constants.signals[res.signal] : undefined) ?? 1);
57
69
  }
58
70
  const tailLines = (file, n) => fs.readFileSync(file, "utf-8").replace(/\n$/, "").split("\n").slice(-n);
71
+ // ---------------------------------------------------------------------------
72
+ // Test-first: JUnit reading, plan `Test first:` lines, red / green judgement
73
+ // ---------------------------------------------------------------------------
74
+ /** The env var naming the JUnit report path `bkit:test:file` must write. */
75
+ export const REPORT_ENV = "BKIT_TEST_REPORT";
76
+ /** The status row step a recorded red writes. */
77
+ export const RED_STEP = "build-task-red";
78
+ const NO_TEST_FILE_HINT = `declare "${BKIT_TEST_FILE_SCRIPT}" in package.json: it runs the one test file passed as its ` +
79
+ `argument and writes a JUnit report to $${REPORT_ENV} ` +
80
+ "(.bkit/workflows.md § Local gate scripts)";
81
+ const XML_ENTITIES = {
82
+ amp: "&",
83
+ lt: "<",
84
+ gt: ">",
85
+ quot: '"',
86
+ apos: "'",
87
+ };
88
+ function decodeXml(s) {
89
+ return s.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, e) => {
90
+ if (!e.startsWith("#"))
91
+ return XML_ENTITIES[e.toLowerCase()] ?? whole;
92
+ const cp = /^#x/i.test(e) ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
93
+ return cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : whole;
94
+ });
95
+ }
96
+ const ATTRS = String.raw `((?:\s+[\w:.-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)`;
97
+ function attr(attrs, name) {
98
+ const m = new RegExp(String.raw `\s${name}\s*=\s*(?:"([^"]*)"|'([^']*)')`).exec(attrs);
99
+ return m ? decodeXml(m[1] ?? m[2] ?? "") : undefined;
100
+ }
101
+ /** Every `<testcase>` in a JUnit report: its name, outcome and first failure message. */
102
+ export function parseJunit(xml) {
103
+ const body = xml.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, "").replace(/<!--[\s\S]*?-->/g, "");
104
+ const cases = [];
105
+ const testcase = new RegExp(String.raw `<testcase${ATTRS}\s*(?:\/>|>([\s\S]*?)<\/testcase>)`, "g");
106
+ const outcome = new RegExp(String.raw `<(failure|error|skipped)${ATTRS}`);
107
+ for (const m of body.matchAll(testcase)) {
108
+ const child = outcome.exec(m[2] ?? "");
109
+ cases.push({
110
+ name: attr(m[1] ?? "", "name") ?? "",
111
+ state: child ? child[1] : "passed",
112
+ message: child ? (attr(child[2] ?? "", "message") ?? "") : "",
113
+ });
114
+ }
115
+ return cases;
116
+ }
117
+ /** A report case is the named test when its name is the name, or ends with it as the last segment. */
118
+ export const isNamedCase = (caseName, want) => caseName === want || caseName.endsWith(` ${want}`);
119
+ const caseNames = (cases) => cases.length === 0
120
+ ? "the report holds no tests"
121
+ : `the report holds ${cases
122
+ .slice(0, 5)
123
+ .map((c) => `"${c.name}"`)
124
+ .join(", ")}${cases.length > 5 ? ", …" : ""}`;
125
+ /** Why a run is not a valid red for `want` (kind + reason), or null when it is one. */
126
+ export function judgeRed(exitCode, cases, want) {
127
+ if (cases === null)
128
+ return {
129
+ kind: "no-report",
130
+ reason: `no JUnit report at $${REPORT_ENV} — ${BKIT_TEST_FILE_SCRIPT} must write one`,
131
+ };
132
+ const named = cases.filter((c) => isNamedCase(c.name, want));
133
+ if (named.length === 0)
134
+ return { kind: "not-run", reason: `the named test "${want}" did not run; ${caseNames(cases)}` };
135
+ if (named.some((c) => c.state === "passed"))
136
+ return {
137
+ kind: "passed",
138
+ reason: `"${want}" passed — a red must fail before the task's code exists`,
139
+ };
140
+ if (named.some((c) => c.state === "skipped"))
141
+ return { kind: "skipped", reason: `"${want}" was skipped, not run` };
142
+ if (exitCode === 0)
143
+ return {
144
+ kind: "exit-mismatch",
145
+ reason: `"${want}" failed in the report but the script exited 0`,
146
+ };
147
+ return null;
148
+ }
149
+ /** Why a run is not green for `want`, or null when every case of the named test passed. */
150
+ export function judgeGreen(cases, want) {
151
+ if (cases === null)
152
+ return `no JUnit report at $${REPORT_ENV} — ${BKIT_TEST_FILE_SCRIPT} must write one`;
153
+ const named = cases.filter((c) => isNamedCase(c.name, want));
154
+ if (named.length === 0)
155
+ return `the named test "${want}" did not run; ${caseNames(cases)}`;
156
+ const bad = named.find((c) => c.state !== "passed");
157
+ return bad === undefined
158
+ ? null
159
+ : `"${want}" ${bad.state}${bad.message ? `: ${bad.message}` : ""}`;
160
+ }
161
+ const TASK_LINE = /^\s*- \[[ xX]\] \*\*Task (\d+):\*\*/;
162
+ const TEST_FIRST = "**Test first:**";
163
+ /** `text` split on `;` outside backticks. */
164
+ function splitEntries(text) {
165
+ const out = [];
166
+ let cur = "";
167
+ let quoted = false;
168
+ for (const ch of text) {
169
+ if (ch === "`")
170
+ quoted = !quoted;
171
+ if (ch === ";" && !quoted) {
172
+ out.push(cur);
173
+ cur = "";
174
+ }
175
+ else
176
+ cur += ch;
177
+ }
178
+ return [...out, cur];
179
+ }
180
+ /**
181
+ * Each runbook task's `Test first:` line: one or more tests separated by `;` (per entry,
182
+ * first backticked span = file, second = test name), `n/a — {reason}`, missing, or
183
+ * malformed (an entry with one span, or no test at all). A task's text runs from its
184
+ * bullet to the next bullet or heading.
185
+ */
186
+ export function readTestFirst(plan) {
187
+ const out = [];
188
+ const lines = plan.split("\n");
189
+ for (let i = 0; i < lines.length; i++) {
190
+ const head = TASK_LINE.exec(lines[i]);
191
+ if (!head)
192
+ continue;
193
+ let text = lines[i];
194
+ for (let j = i + 1; j < lines.length && !/^\s*(- |#)/.test(lines[j]); j++)
195
+ text += ` ${lines[j]}`;
196
+ const task = Number(head[1]);
197
+ const at = text.indexOf(TEST_FIRST);
198
+ if (at < 0) {
199
+ out.push({ task, kind: "missing" });
200
+ continue;
201
+ }
202
+ const rest = text.slice(at + TEST_FIRST.length).trim();
203
+ if (/^n\/a\b/i.test(rest)) {
204
+ out.push({ task, kind: "na", reason: rest.replace(/^n\/a\s*[—–-]?\s*/i, "") });
205
+ continue;
206
+ }
207
+ const entries = splitEntries(rest).map((e) => [...e.matchAll(/`([^`]+)`/g)].map((m) => m[1].trim()));
208
+ const tests = entries
209
+ .filter((spans) => spans.length >= 2)
210
+ .map((spans) => ({ test: path.posix.normalize(spans[0]), name: spans[1] }));
211
+ out.push(tests.length > 0 && !entries.some((spans) => spans.length === 1)
212
+ ? { task, kind: "test", tests }
213
+ : { task, kind: "malformed" });
214
+ }
215
+ return out;
216
+ }
217
+ /** `test` as a repo-relative path inside `top`; usage error when absolute, outside, or absent. */
218
+ function repoTestPath(top, test) {
219
+ const rel = path.relative(top, path.resolve(top, test));
220
+ if (path.isAbsolute(test) || rel.startsWith("..") || rel === "")
221
+ throw new CommandError(EXIT.USAGE, `--test must be a path inside the repo, got "${test}"`);
222
+ if (!fs.statSync(path.join(top, rel), { throwIfNoEntry: false })?.isFile())
223
+ throw new CommandError(EXIT.USAGE, `--test ${rel} is not a file`);
224
+ return rel.split(path.sep).join("/");
225
+ }
226
+ /** Run one test file through `bkit:test:file`; the report is read and removed. */
227
+ function runTestFile(top, test, log) {
228
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bkit-test-report-"));
229
+ const report = path.join(dir, "junit.xml");
230
+ const exitCode = runToLog([...scriptCommand(BKIT_TEST_FILE_SCRIPT), test], top, log, {
231
+ [REPORT_ENV]: report,
232
+ });
233
+ const cases = fs.existsSync(report) ? parseJunit(fs.readFileSync(report, "utf-8")) : null;
234
+ fs.rmSync(dir, { recursive: true, force: true });
235
+ return { exitCode, cases };
236
+ }
237
+ const couldNotRunMessage = (exitCode) => `${gateScope(BKIT_TEST_FILE_SCRIPT)} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no test executed`;
238
+ /** The copy of the test file a red keeps beside its log. */
239
+ export const snapshotPath = (log) => `${log.replace(/\.md$/, "")}.snapshot`;
240
+ const toplevel = (cwd) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
241
+ /** A fence longer than any backtick run in `text`. */
242
+ const fenceFor = (text) => "`".repeat(Math.max(3, ...[...text.matchAll(/`+/g)].map((m) => m[0].length + 1)));
243
+ /** The red rows of status.jsonl for this workflow and sub-plan, oldest first. */
244
+ function redRows(file, workflow, subPlan) {
245
+ return readStatusRows(file).filter((r) => {
246
+ const row = r;
247
+ return (row.type === "step-done" &&
248
+ row.workflow === workflow &&
249
+ row.step === RED_STEP &&
250
+ (subPlan === undefined || row.subPlan === subPlan));
251
+ });
252
+ }
253
+ function writeAuditReport(log, o) {
254
+ const out = [`Enforced: ${o.enforced}`, `Gaps: ${o.gaps.length}`, "", "<!-- verdict:end -->", ""];
255
+ out.push("# Test-First Audit", "");
256
+ if (o.plan)
257
+ out.push(`Plan: \`${o.plan}\``, "");
258
+ if (!o.enforced)
259
+ out.push(`Not enforced: ${o.reason}.`, "");
260
+ if (o.rows.length > 0) {
261
+ out.push("| Task | Test | Red | Changed since red | Green |", "| --- | --- | --- | --- | --- |");
262
+ for (const r of o.rows)
263
+ out.push(`| ${r.task} | ${r.test} | ${r.red} | ${r.changed} | ${r.green} |`);
264
+ out.push("");
265
+ }
266
+ out.push("## Gaps", "");
267
+ if (o.gaps.length === 0)
268
+ out.push("None.");
269
+ for (const g of o.gaps)
270
+ out.push(`- Task ${g.task} \`${g.kind}\` — ${g.detail}`);
271
+ for (const d of o.diffs) {
272
+ const fence = fenceFor(d.diff);
273
+ out.push("", `## Diff since red — Task ${d.task} \`${d.test}\``, "", `${fence}diff`, d.diff, fence);
274
+ }
275
+ for (const t of o.outputs) {
276
+ const fence = fenceFor(t.tail);
277
+ out.push("", `## Runner output — \`${t.test}\``, "", fence, t.tail, fence);
278
+ }
279
+ fs.mkdirSync(path.dirname(log), { recursive: true });
280
+ fs.writeFileSync(log, `${out.join("\n")}\n`);
281
+ }
59
282
  export const testsCommand = {
60
283
  noun: "tests",
61
- summary: "Run the deepest declared local gate, save its full output, and report the verdict.",
284
+ summary: "Run the deepest declared local gate, or one test file to record a red and audit a green.",
62
285
  verbs: {
63
286
  run: {
64
287
  summary: "Run the first declared --gate; exit 0 PASS, 1 FAIL, 4 could not run.",
@@ -140,5 +363,319 @@ export const testsCommand = {
140
363
  return verdict === "PASS" ? EXIT.OK : EXIT.NO;
141
364
  },
142
365
  },
366
+ red: {
367
+ summary: "Run a task's new test before its code exists; exit 0 red recorded, 1 not a red (the named test did not run, passed, or was skipped).",
368
+ flags: [
369
+ FILE_FLAG,
370
+ WORKFLOW_FLAG,
371
+ SUB_PLAN_FLAG,
372
+ {
373
+ name: "task",
374
+ type: "string",
375
+ required: true,
376
+ help: "plan task number (positive integer)",
377
+ },
378
+ {
379
+ name: "test",
380
+ type: "string",
381
+ required: true,
382
+ help: "the test file, repo-relative — passed whole to bkit:test:file",
383
+ },
384
+ {
385
+ name: "name",
386
+ type: "string",
387
+ required: true,
388
+ help: "the test's name as the runner reports it, or its last segment",
389
+ },
390
+ {
391
+ name: "log",
392
+ type: "string",
393
+ required: true,
394
+ help: "file the runner output is saved to; the test file's copy lands beside it as .snapshot",
395
+ },
396
+ ],
397
+ output: {
398
+ recorded: "true when the red row was written, or already recorded for this unchanged test",
399
+ already: "true when an earlier red for this task, test and name stands (test unchanged); nothing ran",
400
+ refused: "no-report | not-run | passed | skipped | exit-mismatch (when recorded is false)",
401
+ reason: "why the run is not a red (when recorded is false)",
402
+ exitCode: "the script's exit code",
403
+ row: "the build-task-red row written (when recorded)",
404
+ log: "where the runner output was saved (as given)",
405
+ },
406
+ exitCodes: {
407
+ [EXIT_NO_GATE]: `${BKIT_TEST_FILE_SCRIPT} is not declared in package.json`,
408
+ [EXIT_COULD_NOT_RUN]: "the script could not run (exit 126 / 127)",
409
+ },
410
+ run: (ctx) => {
411
+ const workflow = String(ctx.flags.workflow);
412
+ const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
413
+ const task = positiveInt(ctx.flags.task, "task");
414
+ const name = String(ctx.flags.name).trim();
415
+ if (name === "")
416
+ throw new CommandError(EXIT.USAGE, "--name must be non-empty");
417
+ const logArg = String(ctx.flags.log);
418
+ if (logArg === "")
419
+ throw new CommandError(EXIT.USAGE, "--log must be non-empty");
420
+ const top = toplevel(ctx.cwd);
421
+ if (resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null) {
422
+ ctx.log(`${BKIT_TEST_FILE_SCRIPT} is not declared — ${NO_TEST_FILE_HINT}`);
423
+ return EXIT_NO_GATE;
424
+ }
425
+ const test = repoTestPath(top, String(ctx.flags.test));
426
+ const blob = git(top, ["hash-object", "--", test]);
427
+ const status = statusFile(ctx);
428
+ const prior = fs.existsSync(status)
429
+ ? redRows(status, workflow, subPlan)
430
+ .reverse()
431
+ .find((r) => r.task === task && r.test === test && r.testName === name)
432
+ : undefined;
433
+ if (prior !== undefined && prior.testBlob === blob) {
434
+ const priorLog = Array.isArray(prior.artifacts) ? String(prior.artifacts[0]) : null;
435
+ ctx.emit({ recorded: true, already: true, row: prior, log: priorLog });
436
+ ctx.log(`red already recorded for task ${task}: "${name}" (test unchanged since)`);
437
+ return EXIT.OK;
438
+ }
439
+ const log = path.resolve(ctx.cwd, logArg);
440
+ const { exitCode, cases } = runTestFile(top, test, log);
441
+ if (COULD_NOT_RUN_EXIT_CODES.has(exitCode)) {
442
+ ctx.log(couldNotRunMessage(exitCode));
443
+ return EXIT_COULD_NOT_RUN;
444
+ }
445
+ const refusal = judgeRed(exitCode, cases, name);
446
+ if (refusal !== null) {
447
+ ctx.emit({
448
+ recorded: false,
449
+ refused: refusal.kind,
450
+ reason: refusal.reason,
451
+ exitCode,
452
+ log: logArg,
453
+ });
454
+ ctx.log(`not a red (${refusal.kind}): ${refusal.reason} — full output in ${logArg}`);
455
+ return EXIT.NO;
456
+ }
457
+ const snapshot = snapshotPath(log);
458
+ fs.copyFileSync(path.join(top, test), snapshot);
459
+ const failed = cases.find((c) => isNamedCase(c.name, name));
460
+ const written = writeStepRow(ctx.cwd, {
461
+ file: statusFile(ctx),
462
+ workflow,
463
+ step: RED_STEP,
464
+ subPlan,
465
+ artifacts: [path.relative(ctx.cwd, log), path.relative(ctx.cwd, snapshot)],
466
+ extras: {
467
+ task,
468
+ test,
469
+ testName: name,
470
+ testBlob: blob,
471
+ exitCode,
472
+ failure: failed.message.slice(0, 200),
473
+ },
474
+ commit: "none",
475
+ }, ctx.log);
476
+ ctx.emit({ recorded: true, exitCode, row: written.row, log: logArg });
477
+ ctx.log(`red recorded for task ${task}: "${name}" failed (${failed.state})`);
478
+ return EXIT.OK;
479
+ },
480
+ },
481
+ green: {
482
+ summary: "Audit a sub-plan's test-first evidence (a red per planned test, the test unchanged since, the named test passing now); exit 0 no gaps, 1 gaps.",
483
+ flags: [
484
+ FILE_FLAG,
485
+ WORKFLOW_FLAG,
486
+ SUB_PLAN_FLAG,
487
+ {
488
+ name: "plan",
489
+ type: "string",
490
+ required: true,
491
+ repeatable: true,
492
+ help: "candidate plan file; the first that exists is audited",
493
+ },
494
+ {
495
+ name: "log",
496
+ type: "string",
497
+ required: true,
498
+ help: "file the audit report is written to (directories are created)",
499
+ },
500
+ ],
501
+ output: {
502
+ enforced: "false when there is nothing to audit (reason says why)",
503
+ reason: "why test-first is not enforced",
504
+ plan: "the plan file audited",
505
+ gaps: "[{task, kind, detail}]: no-test-first | test-first-malformed | no-red | red-mismatch | red-evidence-missing | test-changed | not-green",
506
+ log: "where the report was written (as given)",
507
+ },
508
+ exitCodes: {
509
+ [EXIT_COULD_NOT_RUN]: `${BKIT_TEST_FILE_SCRIPT} could not run (exit 126 / 127)`,
510
+ },
511
+ run: (ctx) => {
512
+ const workflow = String(ctx.flags.workflow);
513
+ const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
514
+ const logArg = String(ctx.flags.log);
515
+ if (logArg === "")
516
+ throw new CommandError(EXIT.USAGE, "--log must be non-empty");
517
+ const log = path.resolve(ctx.cwd, logArg);
518
+ const top = toplevel(ctx.cwd);
519
+ const plan = ctx.flags.plan.find((p) => fs.existsSync(path.resolve(ctx.cwd, p)));
520
+ const specs = plan
521
+ ? readTestFirst(fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8"))
522
+ : [];
523
+ const reason = plan === undefined
524
+ ? "no plan file — the build runs from its brief"
525
+ : !specs.some((s) => s.kind !== "missing")
526
+ ? "the plan has no `Test first:` lines"
527
+ : resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
528
+ ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
529
+ : undefined;
530
+ const empty = { rows: [], gaps: [], diffs: [], outputs: [] };
531
+ if (reason !== undefined) {
532
+ writeAuditReport(log, { enforced: false, reason, plan, ...empty });
533
+ ctx.emit({ enforced: false, reason, plan: plan ?? null, gaps: [], log: logArg });
534
+ ctx.log(`test-first not enforced: ${reason}`);
535
+ return EXIT.OK;
536
+ }
537
+ const reds = redRows(statusFile(ctx), workflow, subPlan);
538
+ const gaps = [];
539
+ const rows = [];
540
+ const diffs = [];
541
+ const outputs = [];
542
+ const greens = new Map();
543
+ /** One run per test file; null when the script could not run. */
544
+ const greenRun = (test) => {
545
+ const cached = greens.get(test);
546
+ if (cached !== undefined)
547
+ return cached;
548
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bkit-test-green-"));
549
+ const runLog = path.join(dir, "output.log");
550
+ const { exitCode, cases } = runTestFile(top, test, runLog);
551
+ const tail = tailLines(runLog, DEFAULT_TAIL).join("\n");
552
+ fs.rmSync(dir, { recursive: true, force: true });
553
+ if (COULD_NOT_RUN_EXIT_CODES.has(exitCode)) {
554
+ ctx.log(couldNotRunMessage(exitCode));
555
+ return null;
556
+ }
557
+ const run = { cases, tail };
558
+ greens.set(test, run);
559
+ return run;
560
+ };
561
+ for (const s of specs) {
562
+ if (s.kind === "na")
563
+ continue;
564
+ if (s.kind !== "test") {
565
+ gaps.push({
566
+ task: s.task,
567
+ kind: s.kind === "missing" ? "no-test-first" : "test-first-malformed",
568
+ detail: s.kind === "missing"
569
+ ? "the task has no `Test first:` line"
570
+ : "`Test first:` is neither `n/a — {reason}` nor `;`-separated entries of a backticked test file and test name",
571
+ });
572
+ continue;
573
+ }
574
+ const taskReds = reds.filter((r) => r.task === s.task);
575
+ const planned = (r) => s.tests.some((t) => t.test === r.test && t.name === r.testName);
576
+ for (const t of s.tests) {
577
+ const row = {
578
+ task: s.task,
579
+ test: `\`${t.test}\` "${t.name}"`,
580
+ red: "missing",
581
+ changed: "—",
582
+ green: "—",
583
+ };
584
+ rows.push(row);
585
+ const red = [...taskReds]
586
+ .reverse()
587
+ .find((r) => r.test === t.test && r.testName === t.name);
588
+ const unplanned = taskReds.filter((r) => !planned(r));
589
+ if (red === undefined && unplanned.length > 0) {
590
+ const recorded = [];
591
+ for (const r of unplanned) {
592
+ const rTest = String(r.test);
593
+ const rName = String(r.testName);
594
+ let now = "file missing";
595
+ if (fs.existsSync(path.join(top, rTest))) {
596
+ const run = greenRun(rTest);
597
+ if (run === null)
598
+ return EXIT_COULD_NOT_RUN;
599
+ const why = judgeGreen(run.cases, rName);
600
+ now = why === null ? "passes now" : `not passing: ${why}`;
601
+ }
602
+ recorded.push(`\`${rTest}\` "${rName}" (${now})`);
603
+ }
604
+ gaps.push({
605
+ task: s.task,
606
+ kind: "red-mismatch",
607
+ detail: `no red for \`${t.test}\` "${t.name}"; reds recorded for ${recorded.join(", ")}`,
608
+ });
609
+ }
610
+ else if (red === undefined) {
611
+ gaps.push({
612
+ task: s.task,
613
+ kind: "no-red",
614
+ detail: `no red recorded for "${t.name}" — the test was never seen failing before the code`,
615
+ });
616
+ }
617
+ else {
618
+ row.red = `recorded ${String(red.at)}`;
619
+ const snap = (Array.isArray(red.artifacts) ? red.artifacts : [])
620
+ .map(String)
621
+ .find((a) => a.endsWith(".snapshot"));
622
+ const snapAbs = snap === undefined ? undefined : path.resolve(ctx.cwd, snap);
623
+ const testAbs = path.join(top, t.test);
624
+ if (snapAbs === undefined || !fs.existsSync(snapAbs)) {
625
+ row.changed = "unknown";
626
+ gaps.push({
627
+ task: s.task,
628
+ kind: "red-evidence-missing",
629
+ detail: `the red's test snapshot ${snap ?? "(none recorded)"} is missing`,
630
+ });
631
+ }
632
+ else if (!fs.existsSync(testAbs)) {
633
+ row.changed = "deleted";
634
+ gaps.push({
635
+ task: s.task,
636
+ kind: "test-changed",
637
+ detail: `\`${t.test}\` no longer exists`,
638
+ });
639
+ }
640
+ else if (!fs.readFileSync(snapAbs).equals(fs.readFileSync(testAbs))) {
641
+ row.changed = "yes";
642
+ gaps.push({
643
+ task: s.task,
644
+ kind: "test-changed",
645
+ detail: `\`${t.test}\` differs from its red snapshot for "${t.name}" (diff below)`,
646
+ });
647
+ const diff = spawnSync("git", ["diff", "--no-index", "--no-color", "--", path.relative(top, snapAbs), t.test], { cwd: top, encoding: "utf-8" });
648
+ diffs.push({ task: s.task, test: t.test, diff: diff.stdout.trimEnd() });
649
+ }
650
+ else
651
+ row.changed = "no";
652
+ }
653
+ if (!fs.existsSync(path.join(top, t.test))) {
654
+ row.green = "file missing";
655
+ gaps.push({
656
+ task: s.task,
657
+ kind: "not-green",
658
+ detail: `\`${t.test}\` does not exist`,
659
+ });
660
+ continue;
661
+ }
662
+ const green = greenRun(t.test);
663
+ if (green === null)
664
+ return EXIT_COULD_NOT_RUN;
665
+ const why = judgeGreen(green.cases, t.name);
666
+ row.green = why === null ? "passed" : "not passed";
667
+ if (why !== null) {
668
+ gaps.push({ task: s.task, kind: "not-green", detail: why });
669
+ if (!outputs.some((o) => o.test === t.test))
670
+ outputs.push({ test: t.test, tail: green.tail });
671
+ }
672
+ }
673
+ }
674
+ writeAuditReport(log, { enforced: true, plan, rows, gaps, diffs, outputs });
675
+ ctx.emit({ enforced: true, plan, gaps, log: logArg });
676
+ ctx.log(`test-first audit: ${gaps.length} gap(s) — report in ${logArg}`);
677
+ return gaps.length === 0 ? EXIT.OK : EXIT.NO;
678
+ },
679
+ },
143
680
  },
144
681
  };
@@ -1,4 +1,4 @@
1
- // bkit workstreams parse|comment — design Step 10: read the organised design's
1
+ // bkit workstreams parse|comment — design Step 11: read the organised design's
2
2
  // `## Suggested Workstreams` and build the advisory comment for the feature's
3
3
  // own issue.
4
4
  //
@@ -70,12 +70,12 @@ export function parseWorkstreams(md) {
70
70
  }
71
71
  /** `[]` or `[WS-1, WS-2]`. */
72
72
  export const requiresList = (w) => `[${w.requires.join(", ")}]`;
73
- /** The Step 10 comment: one line per workstream, then the design doc link. */
73
+ /** The Step 11 comment: one line per workstream, then the design doc link. */
74
74
  export function commentBody(ws, opts) {
75
75
  const doc = `docs/plans/${opts.month}/${opts.fid}-design.md`;
76
76
  return [
77
77
  "###### bkit:generated",
78
- "### Step 10 — Suggested Workstreams",
78
+ "### Step 11 — Suggested Workstreams",
79
79
  "Advisory only. NEVER auto-trigger.",
80
80
  ...ws.map((w) => `- ${w.id}: ${w.name}. Requires: ${requiresList(w)}`),
81
81
  `[${doc}](https://github.com/${opts.ownerRepo}/blob/dev/${doc})`,
@@ -112,7 +112,7 @@ export const workstreamsCommand = {
112
112
  },
113
113
  },
114
114
  comment: {
115
- summary: "The Step 10 comment body for the feature's own issue (posted via MCP by the workflow).",
115
+ summary: "The Step 11 comment body for the feature's own issue (posted via MCP by the workflow).",
116
116
  flags: [
117
117
  ARTIFACT_FLAG,
118
118
  { name: "fid", type: "string", required: true, help: "feature id" },