@cbartens/bkit 5.2.3 → 5.3.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 (254) hide show
  1. package/.bkit/README.md +29 -12
  2. package/.bkit/core/.agents/context.md +1 -1
  3. package/.bkit/core/.agents/docs.md +1 -1
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
  5. package/.bkit/core/.agents/rules.md +11 -0
  6. package/.bkit/core/.bkit/README.md +28 -11
  7. package/.bkit/core/.bkit/cloud.md +9 -8
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +15 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +345 -0
  12. package/.bkit/core/.bkit/prompts.md +88 -73
  13. package/.bkit/core/.bkit/providers.md +41 -22
  14. package/.bkit/core/.bkit/templates.md +125 -18
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +51 -45
  17. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
  18. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
  19. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
  20. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +9 -1
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +10 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +22 -10
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +29 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +11 -3
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +19 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -5
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +14 -5
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -1
  55. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  56. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  57. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  58. package/.bkit/core/engine/checks/after/github.ts +29 -120
  59. package/.bkit/core/engine/checks/after/index.ts +2 -2
  60. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  61. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  62. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  63. package/.bkit/core/engine/checks/before/index.ts +7 -43
  64. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  65. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  66. package/.bkit/core/engine/checks/status-holes.ts +4 -5
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +70 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  70. package/.bkit/core/engine/cli.ts +39 -16
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +17 -16
  73. package/.bkit/core/engine/commands/harvest.ts +12 -12
  74. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  75. package/.bkit/core/engine/commands/install/install.ts +62 -126
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +58 -53
  78. package/.bkit/core/engine/commands/lib.ts +35 -10
  79. package/.bkit/core/engine/commands/tips.ts +8 -5
  80. package/.bkit/core/engine/commands/workflow/branches.ts +65 -11
  81. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  82. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  83. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  84. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  85. package/.bkit/core/engine/commands/workflow/repo.ts +18 -4
  86. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  87. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  88. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  89. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  90. package/.bkit/core/engine/commands/workflow/workflows.ts +19 -17
  91. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  92. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  93. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  94. package/.bkit/core/engine/install/manifest.ts +14 -7
  95. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  96. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  97. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  98. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  99. package/.bkit/core/engine/install/modules/core.ts +91 -70
  100. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  101. package/.bkit/core/engine/install/modules/index.ts +7 -1
  102. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  103. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  104. package/.bkit/core/engine/install/placeholders.ts +3 -18
  105. package/.bkit/core/engine/install/write.ts +59 -12
  106. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  107. package/.bkit/core/engine/render/hosts.ts +47 -67
  108. package/.bkit/core/engine/render/models.ts +29 -11
  109. package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
  110. package/.bkit/core/engine/shared/branches.ts +13 -0
  111. package/.bkit/core/engine/shared/egress.ts +3 -3
  112. package/.bkit/core/engine/shared/json.ts +18 -1
  113. package/.bkit/core/engine/shared/package-json.ts +63 -0
  114. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  115. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  116. package/.bkit/core/engine/shared/settings.ts +36 -0
  117. package/.bkit/core/engine/shared/timeouts.ts +6 -0
  118. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  119. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  120. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  121. package/.bkit/core/prompts/bkit-audit-generate.md +65 -10
  122. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  123. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  124. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  125. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  126. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  127. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  128. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  130. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  132. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  133. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  134. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  135. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  136. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  137. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  138. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  139. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  140. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  141. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  142. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  143. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  144. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  145. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  146. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  148. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  149. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  150. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  151. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  152. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  153. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  154. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  155. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  156. package/.bkit/core/workflows/bkit-build.md +4 -4
  157. package/.bkit/core/workflows/bkit-debug.md +70 -34
  158. package/.bkit/core/workflows/bkit-design.md +3 -3
  159. package/.bkit/core/workflows/bkit-plan.md +12 -5
  160. package/.bkit/core/workflows/bkit-ship.md +6 -6
  161. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  162. package/.bkit/shared/.claude/settings.json +18 -0
  163. package/.bkit/shared/.cursor/mcp.json +2 -1
  164. package/.bkit/shared/.opencode/opencode.json +19 -1
  165. package/.bkit/shared/docs/deployments.md +20 -4
  166. package/.bkit/shared/docs/security.md +8 -6
  167. package/.bkit/shared/docs/testing.md +9 -5
  168. package/.bkit/templates/.cursor/Dockerfile +30 -16
  169. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  170. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  171. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  172. package/.bkit/templates/.github/renovate.json5 +91 -12
  173. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  174. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  175. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  176. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  177. package/.bkit/templates/.husky/pre-push +15 -3
  178. package/.bkit/templates/.oxlintrc.json +21 -0
  179. package/.bkit/templates/docs/capabilities.md +1 -1
  180. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  181. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  182. package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
  183. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  184. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  185. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  186. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  187. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  188. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  189. package/CHANGELOG.md +67 -3
  190. package/README.md +258 -129
  191. package/dist/checks/after/auth.js +10 -11
  192. package/dist/checks/after/ci-yml.js +11 -14
  193. package/dist/checks/after/github.js +32 -125
  194. package/dist/checks/after/index.js +3 -2
  195. package/dist/checks/after/managed.js +8 -24
  196. package/dist/checks/after/tools.js +3 -16
  197. package/dist/checks/before/context-fetch.js +1 -21
  198. package/dist/checks/before/index.js +6 -42
  199. package/dist/checks/before/mcp.js +14 -9
  200. package/dist/checks/before/repo.js +8 -11
  201. package/dist/checks/status-holes.js +5 -6
  202. package/dist/checks/tips/catalogue.js +60 -18
  203. package/dist/checks/tips/detect.js +41 -2
  204. package/dist/checks/tips/index.js +25 -5
  205. package/dist/cli.js +34 -14
  206. package/dist/commands/analysis.js +21 -5
  207. package/dist/commands/comply.js +20 -18
  208. package/dist/commands/harvest.js +12 -13
  209. package/dist/commands/install/doctor.js +55 -23
  210. package/dist/commands/install/install.js +62 -118
  211. package/dist/commands/install/uninstall.js +165 -31
  212. package/dist/commands/install/upgrade.js +55 -49
  213. package/dist/commands/lib.js +32 -10
  214. package/dist/commands/tips.js +6 -3
  215. package/dist/commands/workflow/branches.js +57 -13
  216. package/dist/commands/workflow/counters.js +17 -7
  217. package/dist/commands/workflow/fids.js +39 -0
  218. package/dist/commands/workflow/ledgers.js +3 -1
  219. package/dist/commands/workflow/prs.js +3 -3
  220. package/dist/commands/workflow/repo.js +16 -4
  221. package/dist/commands/workflow/roadmap.js +4 -4
  222. package/dist/commands/workflow/runs.js +5 -5
  223. package/dist/commands/workflow/steps.js +1 -0
  224. package/dist/commands/workflow/tests.js +16 -3
  225. package/dist/commands/workflow/workflows.js +19 -18
  226. package/dist/commands/workflow/workstreams.js +2 -1
  227. package/dist/commands/workflow/worktrees.js +4 -5
  228. package/dist/install/cloud-env.js +10 -23
  229. package/dist/install/manifest.js +14 -7
  230. package/dist/install/modules/antigravity.js +15 -26
  231. package/dist/install/modules/claude.js +17 -21
  232. package/dist/install/modules/cloud.js +6 -2
  233. package/dist/install/modules/codex.js +15 -29
  234. package/dist/install/modules/core.js +82 -63
  235. package/dist/install/modules/cursor.js +6 -9
  236. package/dist/install/modules/index.js +6 -1
  237. package/dist/install/modules/opencode.js +41 -72
  238. package/dist/install/network-allowlist.js +62 -0
  239. package/dist/install/placeholders.js +3 -16
  240. package/dist/install/write.js +55 -15
  241. package/dist/ledgers/telemetry.js +5 -4
  242. package/dist/render/hosts.js +30 -55
  243. package/dist/render/models.js +20 -9
  244. package/dist/shared/bkit-latest.js +150 -0
  245. package/dist/shared/branches.js +11 -0
  246. package/dist/shared/egress.js +0 -2
  247. package/dist/shared/json.js +14 -0
  248. package/dist/shared/package-json.js +61 -0
  249. package/dist/shared/package-roots.js +0 -8
  250. package/dist/shared/protected-paths.js +5 -122
  251. package/dist/shared/settings.js +18 -1
  252. package/dist/shared/timeouts.js +6 -0
  253. package/package.json +21 -17
  254. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -0,0 +1,176 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/ci/ and own it. bkit install does not write this file
3
+ // and does not overwrite a copy.
4
+ /**
5
+ * check-capstone.mjs — the decision behind the `bkit-tests-check` capstone.
6
+ *
7
+ * Reads the capstone's `needs` context from the environment and reds when green would prove
8
+ * nothing. It fails when:
9
+ * - a lane's result is not `success` (failed, skipped or cancelled),
10
+ * - a lane ran although the plan said skip (`run_level` is `none`),
11
+ * - a lane succeeded having executed 0 tests, or reports a count that is not a number,
12
+ * - the plan does not parse (not JSON, not an object, or no `run_level`),
13
+ * - the planner job (`SCOPE_RESULT`) did not succeed,
14
+ * - no lane is named, or a lane's result was never wired in.
15
+ * It asserts nothing for a lane that `<LANE>_CACHE_SKIP=true` marks as proven on a cached
16
+ * SHA, and nothing about a skipped lane when `run_level` is `none`.
17
+ *
18
+ * Environment:
19
+ * LANES comma-separated lane names, e.g. `static,unit`. The job named
20
+ * `bkit-tests-<lane>` is read from `<LANE>_RESULT` (name upper-cased,
21
+ * `-` becomes `_`: `e2e-web` reads `E2E_WEB_RESULT`).
22
+ * <LANE>_RESULT `needs.<job>.result`.
23
+ * <LANE>_RAN `needs.<job>.outputs.tests_ran`. Setting the variable (even empty)
24
+ * makes the lane counted: it must report a number above 0. A lane
25
+ * with no such variable is not count-checked.
26
+ * <LANE>_CACHE_SKIP `needs.<job>.outputs.cache_skip`; `true` skips the count check.
27
+ * PLAN optional planner JSON (`needs.bkit-tests-scope.outputs.plan`). Unset
28
+ * means every listed lane is expected to run. Set, it must parse and
29
+ * carry a `run_level`; `none` expects every lane to be skipped.
30
+ * SCOPE_RESULT optional `needs.bkit-tests-scope.result`; must be `success`.
31
+ * EMPTY_COUNT `warn` turns a lane that reports no count yet into a warning. Any
32
+ * other value fails it. A count of 0 or a non-number always fails.
33
+ *
34
+ * Usage: node scripts/ci/check-capstone.mjs
35
+ * Exit: 0 = every expectation met, 1 = at least one failure.
36
+ */
37
+
38
+ import path from "node:path";
39
+ import { fileURLToPath } from "node:url";
40
+
41
+ const LANE_NAME = /^[a-z][a-z0-9-]*$/i;
42
+ const PREFIX = (lane) => lane.toUpperCase().replace(/-/g, "_");
43
+
44
+ /** The planner's `run_level` from `raw`, or why `raw` is not a usable plan. */
45
+ function readPlan(raw) {
46
+ let plan;
47
+ try {
48
+ plan = JSON.parse(raw);
49
+ } catch (err) {
50
+ return { runLevel: null, problem: err.message };
51
+ }
52
+ if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
53
+ return { runLevel: null, problem: "not a JSON object" };
54
+ }
55
+ if (typeof plan.run_level !== "string" || plan.run_level === "") {
56
+ return { runLevel: null, problem: "no run_level" };
57
+ }
58
+ return { runLevel: plan.run_level, problem: null };
59
+ }
60
+
61
+ /**
62
+ * Judge the capstone from its environment.
63
+ * @param {Record<string, string | undefined>} env
64
+ * @returns {{ errors: string[], warnings: string[], summary: string }}
65
+ */
66
+ export function checkCapstone(env) {
67
+ const errors = [];
68
+ const warnings = [];
69
+
70
+ const lanes = (env.LANES ?? "")
71
+ .split(",")
72
+ .map((l) => l.trim())
73
+ .filter(Boolean);
74
+ if (lanes.length === 0) {
75
+ errors.push("LANES names no lane — a capstone that watches nothing proves nothing.");
76
+ }
77
+
78
+ if (env.SCOPE_RESULT !== undefined && env.SCOPE_RESULT !== "success") {
79
+ errors.push(`bkit-tests-scope did not succeed (result=${env.SCOPE_RESULT})`);
80
+ }
81
+
82
+ let runLevel = null;
83
+ if (env.PLAN !== undefined) {
84
+ const plan = readPlan(env.PLAN);
85
+ runLevel = plan.runLevel;
86
+ if (plan.problem !== null) {
87
+ errors.push(
88
+ `the plan does not parse (${plan.problem}) — expected a JSON object with a run_level, got ${JSON.stringify(env.PLAN.slice(0, 80))}`,
89
+ );
90
+ }
91
+ }
92
+ const expectSkip = runLevel === "none";
93
+ const why = runLevel === null ? "" : `plan.run_level=${runLevel} but `;
94
+
95
+ const parts = [];
96
+ for (const lane of lanes) {
97
+ const job = `bkit-tests-${lane}`;
98
+ if (!LANE_NAME.test(lane)) {
99
+ errors.push(`LANES entry '${lane}' is not a lane name (letters, digits and '-').`);
100
+ continue;
101
+ }
102
+ const prefix = PREFIX(lane);
103
+ const result = env[`${prefix}_RESULT`];
104
+ if (result === undefined) {
105
+ errors.push(`${prefix}_RESULT is not set — the capstone cannot read ${job}'s result.`);
106
+ continue;
107
+ }
108
+
109
+ if (expectSkip) {
110
+ if (result !== "skipped") {
111
+ errors.push(
112
+ `plan.run_level=none says skip but ${job} ran (result=${result}) — plan and lane disagree.`,
113
+ );
114
+ }
115
+ parts.push(`${lane}=${result}`);
116
+ continue;
117
+ }
118
+
119
+ if (result !== "success") {
120
+ errors.push(
121
+ runLevel === null
122
+ ? `${job} result=${result} (expected success)`
123
+ : `${why}${job} result=${result}`,
124
+ );
125
+ parts.push(`${lane}=${result}`);
126
+ continue;
127
+ }
128
+
129
+ const ranKey = `${prefix}_RAN`;
130
+ const counted = Object.hasOwn(env, ranKey);
131
+ if (!counted || env[`${prefix}_CACHE_SKIP`] === "true") {
132
+ parts.push(`${lane}=${result}`);
133
+ continue;
134
+ }
135
+
136
+ const ran = env[ranKey] ?? "";
137
+ if (ran === "" && env.EMPTY_COUNT === "warn") {
138
+ warnings.push(
139
+ `${job} writes no executed-test count — green does not prove tests ran (see its test step).`,
140
+ );
141
+ parts.push(`${lane}=${result} (count unreported)`);
142
+ } else if (!/^[0-9]+$/.test(ran)) {
143
+ errors.push(
144
+ `${job} succeeded but its executed-test count is non-numeric ('${ran}') — cannot confirm tests ran.`,
145
+ );
146
+ parts.push(`${lane}=${result}`);
147
+ } else if (Number(ran) === 0) {
148
+ errors.push(`${job} succeeded but executed 0 tests — vacuous green (expected >0).`);
149
+ parts.push(`${lane}=${result} (0 tests)`);
150
+ } else {
151
+ parts.push(`${lane}=${result} (${Number(ran)} tests)`);
152
+ }
153
+ }
154
+
155
+ const level = runLevel === null ? "" : `, run_level=${runLevel}`;
156
+ return {
157
+ errors,
158
+ warnings,
159
+ summary: `bkit-tests-check passed — ${parts.join(", ")}${level}.`,
160
+ };
161
+ }
162
+
163
+ function main() {
164
+ const { errors, warnings, summary } = checkCapstone(process.env);
165
+ for (const w of warnings) console.log(`::warning::${w}`);
166
+ for (const e of errors) console.log(`::error::${e}`);
167
+ if (errors.length > 0) {
168
+ console.log("::error::bkit-tests-check FAILED — see above.");
169
+ process.exit(1);
170
+ }
171
+ console.log(`✅ ${summary}`);
172
+ }
173
+
174
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
175
+ main();
176
+ }
@@ -0,0 +1,311 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/ci/ and own it. bkit install does not write this file
3
+ // and does not overwrite a copy.
4
+ /**
5
+ * check-capstone.test.mjs — unit tests for the capstone gate.
6
+ *
7
+ * Pure Node, no runner: `node scripts/ci/check-capstone.test.mjs`.
8
+ * Exit: 0 = all tests passed, 1 = at least one test failed.
9
+ */
10
+
11
+ import { spawnSync } from "node:child_process";
12
+ import path from "node:path";
13
+ import { fileURLToPath } from "node:url";
14
+ import { checkCapstone } from "./check-capstone.mjs";
15
+
16
+ const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "check-capstone.mjs");
17
+
18
+ let passed = 0;
19
+ let failed = 0;
20
+
21
+ function test(name, fn) {
22
+ try {
23
+ fn();
24
+ passed++;
25
+ console.log(` ok ${name}`);
26
+ } catch (err) {
27
+ failed++;
28
+ console.log(` FAIL ${name} — ${err.message}`);
29
+ }
30
+ }
31
+
32
+ function assert(cond, message) {
33
+ if (!cond) throw new Error(message);
34
+ }
35
+
36
+ /** The environment of a capstone that watches a static lane and a counted unit lane. */
37
+ const base = (extra = {}) => ({
38
+ LANES: "static,unit",
39
+ STATIC_RESULT: "success",
40
+ UNIT_RESULT: "success",
41
+ UNIT_RAN: "12",
42
+ UNIT_CACHE_SKIP: "",
43
+ ...extra,
44
+ });
45
+
46
+ /** The planner shape: scope + a run level, with a counted integration lane too. */
47
+ const planned = (extra = {}) => ({
48
+ LANES: "static,unit,integration",
49
+ PLAN: JSON.stringify({ run_level: "full" }),
50
+ SCOPE_RESULT: "success",
51
+ STATIC_RESULT: "success",
52
+ UNIT_RESULT: "success",
53
+ UNIT_RAN: "12",
54
+ UNIT_CACHE_SKIP: "false",
55
+ INTEGRATION_RESULT: "success",
56
+ INTEGRATION_RAN: "4",
57
+ INTEGRATION_CACHE_SKIP: "false",
58
+ ...extra,
59
+ });
60
+
61
+ const skipPlan = (extra = {}) =>
62
+ planned({
63
+ PLAN: JSON.stringify({ run_level: "none" }),
64
+ STATIC_RESULT: "skipped",
65
+ UNIT_RESULT: "skipped",
66
+ UNIT_RAN: "",
67
+ UNIT_CACHE_SKIP: "",
68
+ INTEGRATION_RESULT: "skipped",
69
+ INTEGRATION_RAN: "",
70
+ INTEGRATION_CACHE_SKIP: "",
71
+ ...extra,
72
+ });
73
+
74
+ const reds = (env, needle) => {
75
+ const r = checkCapstone(env);
76
+ assert(r.errors.length > 0, `expected a failure, got ${JSON.stringify(r)}`);
77
+ if (needle) {
78
+ assert(
79
+ r.errors.some((e) => e.includes(needle)),
80
+ `no error mentions ${JSON.stringify(needle)}: ${JSON.stringify(r.errors)}`,
81
+ );
82
+ }
83
+ return r;
84
+ };
85
+
86
+ const greens = (env) => {
87
+ const r = checkCapstone(env);
88
+ assert(r.errors.length === 0, `expected a pass, got ${JSON.stringify(r.errors)}`);
89
+ return r;
90
+ };
91
+
92
+ // ── the clean pass ───────────────────────────────────────────────────────────
93
+
94
+ test("every lane succeeded and the counted lane ran tests: passes", () => {
95
+ const r = greens(base());
96
+ assert(r.warnings.length === 0, `warnings ${JSON.stringify(r.warnings)}`);
97
+ });
98
+
99
+ test("with a plan: scope, every lane and every count good passes", () => {
100
+ greens(planned());
101
+ });
102
+
103
+ // ── case 1: a lane whose result is not success ──────────────────────────────
104
+
105
+ test("a failed lane fails, naming the lane and its result", () => {
106
+ reds(base({ STATIC_RESULT: "failure" }), "bkit-tests-static");
107
+ const r = reds(base({ UNIT_RESULT: "failure" }), "result=failure");
108
+ assert(
109
+ r.errors.some((e) => e.includes("bkit-tests-unit")),
110
+ "lane not named",
111
+ );
112
+ });
113
+
114
+ test("a skipped or cancelled lane fails when the lane was expected to run", () => {
115
+ reds(base({ STATIC_RESULT: "skipped" }), "result=skipped");
116
+ reds(base({ UNIT_RESULT: "cancelled" }), "result=cancelled");
117
+ });
118
+
119
+ test("with a plan, a failed lane fails naming the run level", () => {
120
+ reds(planned({ INTEGRATION_RESULT: "failure" }), "run_level=full");
121
+ });
122
+
123
+ test("a lane whose result was never wired in fails", () => {
124
+ const env = base();
125
+ delete env.STATIC_RESULT;
126
+ reds(env, "STATIC_RESULT");
127
+ });
128
+
129
+ test("a failed scope job fails even when every lane succeeded", () => {
130
+ reds(planned({ SCOPE_RESULT: "failure" }), "bkit-tests-scope");
131
+ });
132
+
133
+ // ── case 2: a gated lane ran although the plan said skip ────────────────────
134
+
135
+ test("run_level=none with every lane skipped passes", () => {
136
+ greens(skipPlan());
137
+ });
138
+
139
+ test("run_level=none but a lane ran (success) fails", () => {
140
+ reds(skipPlan({ UNIT_RESULT: "success", UNIT_RAN: "5" }), "bkit-tests-unit");
141
+ });
142
+
143
+ test("run_level=none but a lane ran (failure) fails", () => {
144
+ reds(skipPlan({ STATIC_RESULT: "failure" }), "bkit-tests-static");
145
+ });
146
+
147
+ test("run_level=none ignores counts on skipped lanes", () => {
148
+ greens(skipPlan({ UNIT_RAN: "0", INTEGRATION_RAN: "not-a-number" }));
149
+ });
150
+
151
+ // ── case 3: success with 0 tests, or a count that is not a number ───────────
152
+
153
+ test("a lane that succeeded having run 0 tests fails", () => {
154
+ reds(base({ UNIT_RAN: "0" }), "0 tests");
155
+ });
156
+
157
+ test("a zero written with leading zeros is still zero", () => {
158
+ reds(base({ UNIT_RAN: "00" }), "0 tests");
159
+ });
160
+
161
+ test("a non-numeric count fails", () => {
162
+ reds(base({ UNIT_RAN: "abc" }), "non-numeric");
163
+ reds(base({ UNIT_RAN: "-3" }), "non-numeric");
164
+ reds(base({ UNIT_RAN: "1.5" }), "non-numeric");
165
+ reds(base({ UNIT_RAN: " 4" }), "non-numeric");
166
+ });
167
+
168
+ test("an empty count fails by default", () => {
169
+ reds(base({ UNIT_RAN: "" }), "non-numeric");
170
+ });
171
+
172
+ test("a positive count passes", () => {
173
+ greens(base({ UNIT_RAN: "1" }));
174
+ greens(base({ UNIT_RAN: "0042" }));
175
+ });
176
+
177
+ test("each counted lane is checked on its own", () => {
178
+ reds(planned({ UNIT_RAN: "9", INTEGRATION_RAN: "0" }), "bkit-tests-integration");
179
+ reds(planned({ UNIT_RAN: "0", INTEGRATION_RAN: "9" }), "bkit-tests-unit");
180
+ });
181
+
182
+ test("a lane with no <LANE>_RAN variable is not count-checked", () => {
183
+ const env = base();
184
+ assert(!("STATIC_RAN" in env), "fixture sets STATIC_RAN");
185
+ greens(env);
186
+ });
187
+
188
+ test("a count on a lane that did not succeed is not double-reported", () => {
189
+ const r = reds(base({ UNIT_RESULT: "failure", UNIT_RAN: "0" }), "result=failure");
190
+ assert(r.errors.length === 1, `errors ${JSON.stringify(r.errors)}`);
191
+ });
192
+
193
+ // ── case 4: a plan that will not parse ──────────────────────────────────────
194
+
195
+ test("a plan that is not JSON fails", () => {
196
+ reds(planned({ PLAN: "{not json" }), "plan");
197
+ });
198
+
199
+ test("an empty plan fails (a planner that emitted nothing)", () => {
200
+ reds(planned({ PLAN: "" }), "plan");
201
+ });
202
+
203
+ test("a plan that is not an object, or has no run_level, fails", () => {
204
+ reds(planned({ PLAN: "[]" }), "plan");
205
+ reds(planned({ PLAN: "null" }), "plan");
206
+ reds(planned({ PLAN: '"full"' }), "plan");
207
+ reds(planned({ PLAN: "{}" }), "plan");
208
+ reds(planned({ PLAN: '{"run_level":""}' }), "plan");
209
+ reds(planned({ PLAN: '{"run_level":3}' }), "plan");
210
+ });
211
+
212
+ test("an unparseable plan never lets a skipped lane pass as 'nothing planned'", () => {
213
+ reds(skipPlan({ PLAN: "{not json" }), "plan");
214
+ });
215
+
216
+ // ── the exemptions ──────────────────────────────────────────────────────────
217
+
218
+ test("cache_skip=true asserts no count", () => {
219
+ greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "" }));
220
+ greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "0" }));
221
+ greens(planned({ INTEGRATION_CACHE_SKIP: "true", INTEGRATION_RAN: "0" }));
222
+ });
223
+
224
+ test("cache_skip=true does not excuse a failed lane", () => {
225
+ reds(base({ UNIT_RESULT: "failure", UNIT_CACHE_SKIP: "true" }), "result=failure");
226
+ });
227
+
228
+ test("only the exact string 'true' is a cache skip", () => {
229
+ reds(base({ UNIT_CACHE_SKIP: "yes", UNIT_RAN: "0" }), "0 tests");
230
+ reds(base({ UNIT_CACHE_SKIP: "TRUE", UNIT_RAN: "0" }), "0 tests");
231
+ });
232
+
233
+ test("EMPTY_COUNT=warn turns an unreported count into a warning, not a failure", () => {
234
+ const r = greens(base({ EMPTY_COUNT: "warn", UNIT_RAN: "" }));
235
+ assert(r.warnings.length === 1, `warnings ${JSON.stringify(r.warnings)}`);
236
+ assert(r.warnings[0].includes("bkit-tests-unit"), "lane not named in the warning");
237
+ });
238
+
239
+ test("EMPTY_COUNT=warn still fails a zero or non-numeric count", () => {
240
+ reds(base({ EMPTY_COUNT: "warn", UNIT_RAN: "0" }), "0 tests");
241
+ reds(base({ EMPTY_COUNT: "warn", UNIT_RAN: "abc" }), "non-numeric");
242
+ });
243
+
244
+ test("an EMPTY_COUNT value other than warn is the strict default", () => {
245
+ reds(base({ EMPTY_COUNT: "ignore", UNIT_RAN: "" }), "non-numeric");
246
+ });
247
+
248
+ // ── the wiring ──────────────────────────────────────────────────────────────
249
+
250
+ test("no LANES fails: a gate that watches nothing proves nothing", () => {
251
+ reds({}, "LANES");
252
+ reds({ LANES: "" }, "LANES");
253
+ reds({ LANES: " , " }, "LANES");
254
+ });
255
+
256
+ test("a lane name that cannot be an env prefix fails", () => {
257
+ reds({ LANES: "unit;rm", UNIT_RESULT: "success" }, "unit;rm");
258
+ });
259
+
260
+ test("a hyphenated lane reads <LANE>_ variables with underscores", () => {
261
+ greens({
262
+ LANES: "e2e-web",
263
+ E2E_WEB_RESULT: "success",
264
+ E2E_WEB_RAN: "3",
265
+ E2E_WEB_CACHE_SKIP: "",
266
+ });
267
+ reds(
268
+ { LANES: "e2e-web", E2E_WEB_RESULT: "success", E2E_WEB_RAN: "0", E2E_WEB_CACHE_SKIP: "" },
269
+ "bkit-tests-e2e-web",
270
+ );
271
+ });
272
+
273
+ test("lane names tolerate spaces around the commas", () => {
274
+ greens(base({ LANES: " static , unit " }));
275
+ });
276
+
277
+ // ── the command line ────────────────────────────────────────────────────────
278
+
279
+ function run(env) {
280
+ const r = spawnSync(process.execPath, [SCRIPT], { env, encoding: "utf-8" });
281
+ return { status: r.status, out: `${r.stdout}${r.stderr}` };
282
+ }
283
+
284
+ test("exits 0 and prints a pass line when the lanes are good", () => {
285
+ const r = run(base());
286
+ assert(r.status === 0, `status ${r.status}: ${r.out}`);
287
+ assert(r.out.includes("bkit-tests-check passed"), `output ${r.out}`);
288
+ });
289
+
290
+ test("exits 1 and prints ::error:: lines when a lane failed", () => {
291
+ const r = run(base({ UNIT_RESULT: "failure" }));
292
+ assert(r.status === 1, `status ${r.status}`);
293
+ assert(r.out.includes("::error::bkit-tests-unit"), `output ${r.out}`);
294
+ assert(r.out.includes("bkit-tests-check FAILED"), `output ${r.out}`);
295
+ });
296
+
297
+ test("exits 1 on a zero count, and prints ::warning:: for an unreported one", () => {
298
+ assert(run(base({ UNIT_RAN: "0" })).status === 1, "zero count passed");
299
+ const r = run(base({ EMPTY_COUNT: "warn", UNIT_RAN: "" }));
300
+ assert(r.status === 0, `status ${r.status}: ${r.out}`);
301
+ assert(r.out.includes("::warning::bkit-tests-unit"), `output ${r.out}`);
302
+ });
303
+
304
+ test("exits 1 on a plan that will not parse", () => {
305
+ const r = run(planned({ PLAN: "{not json" }));
306
+ assert(r.status === 1, `status ${r.status}`);
307
+ assert(r.out.includes("::error::"), `output ${r.out}`);
308
+ });
309
+
310
+ console.log(`\n${passed} passed, ${failed} failed`);
311
+ process.exit(failed ? 1 : 0);
@@ -0,0 +1,115 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/cleanup/ and own it. bkit install does not write this file
3
+ // and does not overwrite a copy.
4
+ /**
5
+ * bkit-tmp-prune.mjs — deletes files under the checkout's `tmp/` last modified more than
6
+ * `--days` days ago, then the folders that leaves empty.
7
+ *
8
+ * Scope: `tmp/` at the top of the checkout the cwd sits in; each worktree has its own.
9
+ * Symlinks are never followed: a symlinked `tmp/` is left alone; a symlink inside it is
10
+ * aged and removed like a file. A folder goes only when empty and either this sweep
11
+ * emptied it or its own last change is past the cutoff, so a fresh empty folder another
12
+ * process just made stays. An entry another process removes or fills mid-sweep is skipped.
13
+ *
14
+ * Usage: node scripts/cleanup/bkit-tmp-prune.mjs [--days=<n>] (default 7)
15
+ * Exit: 0 = swept or no `tmp/`, 1 = an entry could not be removed, 2 = bad arguments.
16
+ */
17
+
18
+ import { spawnSync } from "node:child_process";
19
+ import fs from "node:fs";
20
+ import path from "node:path";
21
+ import { fileURLToPath } from "node:url";
22
+
23
+ export const DEFAULT_DAYS = 7;
24
+
25
+ const DAY_MS = 24 * 60 * 60 * 1000;
26
+
27
+ /** Codes meaning another process changed the entry mid-sweep: skip it, not a failure. */
28
+ const RACE_CODES = new Set(["ENOENT", "ENOTDIR", "ENOTEMPTY", "EEXIST"]);
29
+
30
+ /** Remove one entry; true when it is gone. */
31
+ function remove(full, isDir, result) {
32
+ try {
33
+ if (isDir) fs.rmdirSync(full);
34
+ else fs.unlinkSync(full);
35
+ } catch (err) {
36
+ if (!RACE_CODES.has(err.code)) result.failed.push(`${full}: ${err.code ?? err.message}`);
37
+ return err.code === "ENOENT";
38
+ }
39
+ if (isDir) result.dirs++;
40
+ else result.files++;
41
+ return true;
42
+ }
43
+
44
+ /** Prune `dir`'s contents; true when `dir` itself should go. `stat` is read before the sweep. */
45
+ function sweep(dir, stat, cutoff, result) {
46
+ let names;
47
+ try {
48
+ names = fs.readdirSync(dir);
49
+ } catch (err) {
50
+ if (!RACE_CODES.has(err.code)) result.failed.push(`${dir}: ${err.code ?? err.message}`);
51
+ return false;
52
+ }
53
+ let kept = 0;
54
+ let removed = 0;
55
+ for (const name of names) {
56
+ const full = path.join(dir, name);
57
+ const entry = fs.lstatSync(full, { throwIfNoEntry: false });
58
+ if (!entry) continue;
59
+ const gone = entry.isDirectory()
60
+ ? sweep(full, entry, cutoff, result) && remove(full, true, result)
61
+ : entry.mtimeMs < cutoff && remove(full, false, result);
62
+ if (gone) removed++;
63
+ else kept++;
64
+ }
65
+ return kept === 0 && (removed > 0 || stat.mtimeMs < cutoff);
66
+ }
67
+
68
+ /**
69
+ * Delete everything under `dir` older than `days` days; `dir` itself always stays.
70
+ * @returns {{ files: number, dirs: number, failed: string[] }}
71
+ */
72
+ export function pruneTmp(dir, { days = DEFAULT_DAYS, now = Date.now() } = {}) {
73
+ const result = { files: 0, dirs: 0, failed: [] };
74
+ const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
75
+ if (stat?.isDirectory()) sweep(dir, stat, now - days * DAY_MS, result);
76
+ return result;
77
+ }
78
+
79
+ /** Top of the checkout the cwd sits in; the cwd itself outside git. */
80
+ function checkoutTop(cwd) {
81
+ const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
82
+ return r.status === 0 ? r.stdout.trim() : cwd;
83
+ }
84
+
85
+ /** `--days=<n>` with n >= 1; null on anything else. */
86
+ export function parseDays(argv) {
87
+ let days = DEFAULT_DAYS;
88
+ for (const arg of argv) {
89
+ const m = /^--days=([1-9]\d*)$/.exec(arg);
90
+ if (!m) return null;
91
+ days = Number(m[1]);
92
+ }
93
+ return days;
94
+ }
95
+
96
+ export function main(argv, { cwd = process.cwd(), log = console.log, err = console.error } = {}) {
97
+ const days = parseDays(argv);
98
+ if (days === null) {
99
+ err("usage: node scripts/cleanup/bkit-tmp-prune.mjs [--days=<n>] (n >= 1, default 7)");
100
+ return 2;
101
+ }
102
+ const { files, dirs, failed } = pruneTmp(path.join(checkoutTop(cwd), "tmp"), { days });
103
+ if (files + dirs > 0) {
104
+ const n = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
105
+ log(
106
+ `[tmp-prune] removed ${n(files, "file")} and ${n(dirs, "folder")} older than ${n(days, "day")} from tmp/`,
107
+ );
108
+ }
109
+ for (const line of failed) err(`[tmp-prune] could not remove ${line}`);
110
+ return failed.length > 0 ? 1 : 0;
111
+ }
112
+
113
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
114
+ process.exit(main(process.argv.slice(2)));
115
+ }
@@ -133,10 +133,10 @@ def inside_callable(path, line):
133
133
 
134
134
 
135
135
  # --- who imports this, transitively -------------------------------------------
136
- # graph.json already carries the ~540 imports graphify cannot resolve — a `.js`
136
+ # graph.json already carries the imports graphify cannot resolve — a `.js`
137
137
  # specifier never reaching a `.tsx` file, and workspace subpaths through an
138
138
  # `exports` map. bkit-graph-repair.py injects them during `pnpm graph`, so they are
139
- # read here like any other edge; warns if the graph predates that step.
139
+ # read here like any other edge; warns if graph.json lacks any of them.
140
140
  INBOUND = collections.defaultdict(set)
141
141
  for link in raw["links"]:
142
142
  if link.get("relation") not in DEP_RELATIONS: