@cbartens/bkit 5.5.1 → 6.1.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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -0,0 +1,75 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/ci/ and own it. bkit install does not write this file.
3
+ // Usage: node scripts/ci/bkit-test-awake.mjs command [args...]
4
+ // Chains: node scripts/ci/bkit-test-awake.mjs --shell 'first && second'
5
+
6
+ import { spawn } from "node:child_process";
7
+ import spawnCommand from "cross-spawn";
8
+ import { once } from "node:events";
9
+ import { constants } from "node:os";
10
+ import { pathToFileURL } from "node:url";
11
+
12
+ /** Run a command with a macOS sleep assertion owned by this process. */
13
+ export async function runAwake(command, args, platform = process.platform) {
14
+ let assertion;
15
+ if (platform === "darwin") {
16
+ assertion = spawn("/usr/bin/caffeinate", ["-is", "-w", String(process.pid)], {
17
+ stdio: "ignore",
18
+ detached: true,
19
+ });
20
+ try {
21
+ await once(assertion, "spawn");
22
+ } catch (error) {
23
+ console.error(`bkit-test-awake: caffeinate could not run: ${error.message}`);
24
+ return 127;
25
+ }
26
+ }
27
+
28
+ const child = spawnCommand(command, args, {
29
+ stdio: "inherit",
30
+ });
31
+ const forward = (signal) => {
32
+ if (!child.pid) return;
33
+ try {
34
+ child.kill(signal);
35
+ } catch (error) {
36
+ if (error.code !== "ESRCH") throw error;
37
+ }
38
+ };
39
+ const handlers = ["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => {
40
+ const handler = () => forward(signal);
41
+ process.on(signal, handler);
42
+ return [signal, handler];
43
+ });
44
+ try {
45
+ const [code, signal] = await once(child, "close");
46
+ return code ?? 128 + (constants.signals[signal] ?? 1);
47
+ } catch (error) {
48
+ const reason = error.code === "ENOENT" ? "not found on PATH" : "could not run";
49
+ console.error(`bkit-test-awake: ${command} ${reason}: ${error.message}`);
50
+ return error.code === "EACCES" ? 126 : 127;
51
+ } finally {
52
+ for (const [signal, handler] of handlers) process.off(signal, handler);
53
+ if (assertion && assertion.exitCode === null && assertion.signalCode === null) {
54
+ const closed = once(assertion, "close");
55
+ assertion.kill();
56
+ await closed;
57
+ }
58
+ }
59
+ }
60
+
61
+ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
62
+ const [command, ...args] = process.argv.slice(2);
63
+ if (!command || (command === "--shell" && args.length !== 1)) {
64
+ console.error("bkit-test-awake: name a command, or --shell followed by one command string");
65
+ process.exitCode = 2;
66
+ } else if (command === "--shell") {
67
+ const windows = process.platform === "win32";
68
+ process.exitCode = await runAwake(
69
+ windows ? process.env.ComSpec || "cmd.exe" : "/bin/sh",
70
+ windows ? ["/d", "/s", "/c", args[0]] : ["-c", args[0]],
71
+ );
72
+ } else {
73
+ process.exitCode = await runAwake(command, args);
74
+ }
75
+ }
@@ -0,0 +1,160 @@
1
+ // Example. Copy into scripts/ci/ and own it. bkit install does not write this file.
2
+ import assert from "node:assert/strict";
3
+ import { spawn, spawnSync } from "node:child_process";
4
+ import { once } from "node:events";
5
+ import { existsSync, readFileSync } from "node:fs";
6
+ import { test } from "node:test";
7
+ import { fileURLToPath } from "node:url";
8
+
9
+ const script = fileURLToPath(new URL("./bkit-test-awake.mjs", import.meta.url));
10
+
11
+ function isRunning(pid) {
12
+ try {
13
+ process.kill(pid, 0);
14
+ if (process.platform === "linux") {
15
+ const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
16
+ return stat.slice(stat.lastIndexOf(")") + 2, stat.lastIndexOf(")") + 3) !== "Z";
17
+ }
18
+ return true;
19
+ } catch (error) {
20
+ if (error.code === "ESRCH" || error.code === "ENOENT") return false;
21
+ throw error;
22
+ }
23
+ }
24
+
25
+ test("ships a command-scoped sleep prevention wrapper", () => {
26
+ assert.ok(existsSync(script));
27
+ });
28
+
29
+ test("preserves arguments, output and nonzero exit status", () => {
30
+ const result = spawnSync(
31
+ process.execPath,
32
+ [
33
+ script,
34
+ process.execPath,
35
+ "-e",
36
+ 'console.log(JSON.stringify(process.argv.slice(1))); console.error("failure detail"); process.exit(23)',
37
+ "a b",
38
+ "$(echo unsafe)",
39
+ "",
40
+ "--flag",
41
+ ],
42
+ { encoding: "utf8" },
43
+ );
44
+ assert.equal(result.status, 23);
45
+ assert.deepEqual(JSON.parse(result.stdout), ["a b", "$(echo unsafe)", "", "--flag"]);
46
+ assert.equal(result.stderr, "failure detail\n");
47
+ });
48
+
49
+ test("runs an entire shell chain and retains its failure", () => {
50
+ const result = spawnSync(
51
+ process.execPath,
52
+ [script, "--shell", "echo first && echo second && exit 19"],
53
+ { encoding: "utf8" },
54
+ );
55
+ assert.equal(result.status, 19);
56
+ assert.match(result.stdout, /first\r?\nsecond\r?\n/);
57
+ });
58
+
59
+ test("reports a missing command as 127", () => {
60
+ const result = spawnSync(process.execPath, [script, "bkit-command-that-does-not-exist"], {
61
+ encoding: "utf8",
62
+ });
63
+ assert.equal(result.status, 127);
64
+ assert.match(result.stderr, /bkit-command-that-does-not-exist/);
65
+ });
66
+
67
+ test("requires a command", () => {
68
+ const result = spawnSync(process.execPath, [script], { encoding: "utf8" });
69
+ assert.equal(result.status, 2);
70
+ assert.match(result.stderr, /command/);
71
+ });
72
+
73
+ test("non-macOS platform selection runs commands without sleep prevention", async () => {
74
+ const { runAwake } = await import("./bkit-test-awake.mjs");
75
+ for (const platform of ["linux", "win32"]) {
76
+ assert.equal(await runAwake(process.execPath, ["-e", "process.exit(17)"], platform), 17);
77
+ }
78
+ });
79
+
80
+ test(
81
+ "hard timeout escalation reaches a command that ignores TERM",
82
+ { skip: process.platform === "win32" },
83
+ async () => {
84
+ const child = spawn(
85
+ process.execPath,
86
+ [
87
+ script,
88
+ process.execPath,
89
+ "-e",
90
+ 'process.on("SIGTERM", () => {}); console.log(String(process.pid)); setInterval(() => {}, 1000)',
91
+ ],
92
+ {
93
+ detached: true,
94
+ stdio: ["ignore", "pipe", "pipe"],
95
+ env: { ...process.env, FORCE_COLOR: "1" },
96
+ },
97
+ );
98
+ const exited = once(child, "exit");
99
+ const [data] = await once(child.stdout, "data");
100
+ const pid = Number(data.toString().trim());
101
+ assert.ok(pid > 0);
102
+ process.kill(-child.pid, "SIGTERM");
103
+ await new Promise((resolve) => setTimeout(resolve, 100));
104
+ process.kill(-child.pid, "SIGKILL");
105
+ await exited;
106
+ for (let attempt = 0; attempt < 40 && isRunning(pid); attempt++) {
107
+ await new Promise((resolve) => setTimeout(resolve, 25));
108
+ }
109
+ const alive = isRunning(pid);
110
+ if (alive) process.kill(pid, "SIGKILL");
111
+ child.stdout.destroy();
112
+ child.stderr.destroy();
113
+ assert.equal(alive, false, "a hard timeout must kill the test command too");
114
+ },
115
+ );
116
+
117
+ test(
118
+ "forwards POSIX cancellation to the command and releases the assertion",
119
+ { skip: process.platform === "win32" },
120
+ async () => {
121
+ const child = spawn(
122
+ process.execPath,
123
+ [
124
+ script,
125
+ process.execPath,
126
+ "-e",
127
+ "console.log(String(process.pid)); setInterval(() => {}, 1000)",
128
+ ],
129
+ { stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, FORCE_COLOR: "1" } },
130
+ );
131
+ const closed = once(child, "close");
132
+ const [data] = await once(child.stdout, "data");
133
+ const pid = Number(data.toString().trim());
134
+ assert.ok(pid > 0);
135
+ child.kill("SIGTERM");
136
+ const [code] = await closed;
137
+ assert.equal(code, 143);
138
+ assert.throws(() => process.kill(pid, 0), { code: "ESRCH" });
139
+ },
140
+ );
141
+
142
+ test(
143
+ "holds a real macOS assertion only while the command runs",
144
+ { skip: process.platform !== "darwin" },
145
+ () => {
146
+ const probe = `
147
+ const { execFileSync } = require("node:child_process");
148
+ const pid = Number(execFileSync("pgrep", ["-P", String(process.ppid), "caffeinate"], {encoding:"utf8"}).trim());
149
+ const command = execFileSync("ps", ["-p", String(pid), "-o", "command="], {encoding:"utf8"});
150
+ console.log(JSON.stringify({pid, command, owner:process.ppid}));
151
+ `;
152
+ const result = spawnSync(process.execPath, [script, process.execPath, "-e", probe], {
153
+ encoding: "utf8",
154
+ });
155
+ assert.equal(result.status, 0, result.stderr);
156
+ const { pid, command, owner } = JSON.parse(result.stdout);
157
+ assert.match(command, new RegExp("caffeinate -is -w " + owner));
158
+ assert.throws(() => process.kill(pid, 0), { code: "ESRCH" });
159
+ },
160
+ );
@@ -2,7 +2,7 @@
2
2
  // Example. Copy into scripts/ci/lanes/ and own it. bkit install does not write this file
3
3
  // and does not overwrite a copy.
4
4
  /**
5
- * resolve-push-base.mjs — the diff base for a push run's test plan.
5
+ * bkit-resolve-push-base.mjs — the diff base for a push run's test plan.
6
6
  *
7
7
  * A newer run on a branch cancels the older one, so the previous push's run may never have
8
8
  * finished — and `github.event.before` is that previous push. Diffing against it would leave
@@ -17,9 +17,9 @@
17
17
  * in for `event.before`, and ancestry is tested against the pushed commit (`--head`), which is
18
18
  * not always the checked-out one. gh uses its own login.
19
19
  *
20
- * Usage: node scripts/ci/lanes/resolve-push-base.mjs
20
+ * Usage: node scripts/ci/lanes/bkit-resolve-push-base.mjs
21
21
  * (env: GH_TOKEN, REPO, BRANCH, BEFORE_SHA, WORKFLOW_FILE; optional SOURCE_FILE)
22
- * node scripts/ci/lanes/resolve-push-base.mjs --local --branch=dev --head=<pushed sha>
22
+ * node scripts/ci/lanes/bkit-resolve-push-base.mjs --local --branch=dev --head=<pushed sha>
23
23
  * (env: optional WORKFLOW_FILE, SOURCE_FILE)
24
24
  * Output: the base SHA on stdout; the chosen source (`last-green-run`, `event-before`, ...;
25
25
  * `origin/<branch>` in place of `event-before` in local mode) on stderr, and in
@@ -2,9 +2,9 @@
2
2
  // Example. Copy into scripts/ci/lanes/ and own it. bkit install does not write this file
3
3
  // and does not overwrite a copy.
4
4
  /**
5
- * resolve-push-base.test.mjs — unit tests for the push-run diff base.
5
+ * bkit-resolve-push-base.test.mjs — unit tests for the push-run diff base.
6
6
  *
7
- * Pure Node, no runner: `node scripts/ci/lanes/resolve-push-base.test.mjs`.
7
+ * Pure Node, no runner: `node scripts/ci/lanes/bkit-resolve-push-base.test.mjs`.
8
8
  * Exit: 0 = all tests passed, 1 = at least one test failed.
9
9
  */
10
10
 
@@ -18,9 +18,9 @@ import {
18
18
  newestRunSha,
19
19
  parseArgs,
20
20
  repoFromRemoteUrl,
21
- } from "./resolve-push-base.mjs";
21
+ } from "./bkit-resolve-push-base.mjs";
22
22
 
23
- const SCRIPT = fileURLToPath(new URL("./resolve-push-base.mjs", import.meta.url));
23
+ const SCRIPT = fileURLToPath(new URL("./bkit-resolve-push-base.mjs", import.meta.url));
24
24
 
25
25
  /** Run the script with fake `gh` / `git` binaries first on PATH; `gh` calls land in gh.log. */
26
26
  function runWithFakes({ gh, git, args = [], env = {} }) {
@@ -71,9 +71,17 @@ function judge(cwd, wt, fid) {
71
71
  const git = (...args) => spawnSync("git", ["-C", wt, ...args], { encoding: "utf8" });
72
72
  if (fs.globSync(path.join(cwd, "docs/plans/*/logs", fid, ".lock")).length > 0)
73
73
  return { keep: "a bkit workflow holds its lock" };
74
+ // git in a plain folder inside the checkout answers for the checkout itself, so a folder is
75
+ // a worktree only when git names it as its own top.
76
+ if (
77
+ !fs.existsSync(wt) ||
78
+ git("rev-parse", "--show-toplevel").stdout.trim() !== fs.realpathSync(wt)
79
+ )
80
+ return { note: "not a git worktree; delete the folder if unneeded" };
74
81
  if (idleDays(wt) < 2) return { keep: "committed to in the last 2 days" };
75
82
  const status = git("status", "--porcelain");
76
- if (status.status !== 0) return { note: "not a git worktree; delete the folder if unneeded" };
83
+ if (status.status !== 0)
84
+ return { note: `git status failed (\`git -C .worktrees/${fid} status\`)` };
77
85
  if (status.stdout.trim() !== "")
78
86
  return { note: `uncommitted or untracked files (\`git -C .worktrees/${fid} status\`)` };
79
87
  if (git("rev-list", "HEAD", "--not", "--remotes").stdout.trim() !== "") {
@@ -87,7 +95,7 @@ function judge(cwd, wt, fid) {
87
95
 
88
96
  /** Remove worktree `wt`; null when gone, else why not. */
89
97
  function removeWorktree(cwd, wt, fid) {
90
- const r = spawnSync("pnpm", ["-s", "bkit", "worktrees", "remove", `--fid=${fid}`], {
98
+ const r = spawnSync("pnpm", ["-s", "bkit", "worktrees", "remove", `--fid=${fid}`, "--json"], {
91
99
  cwd,
92
100
  encoding: "utf8",
93
101
  });
@@ -5,7 +5,7 @@
5
5
  #!/usr/bin/env python3
6
6
  """Compute per-capability drift status by literal-pattern scan, for the generated diagram.
7
7
 
8
- Called by `pnpm graph:rollup` (scripts/graphify/bkit-graphify.sh). Reads
8
+ Called by `pnpm bkit:graph:rollup` (scripts/graphify/bkit-graphify.sh). Reads
9
9
  bkit-graph-drift-rules.json, walks the source tree once, and writes an overlay JSON
10
10
  that bkit-graphify-rollup.py paints onto the Mermaid nodes.
11
11
 
@@ -5,7 +5,7 @@
5
5
  #!/usr/bin/env python3
6
6
  """Find modules that do work when they are imported, and count who pays for it.
7
7
 
8
- Called by `pnpm graph:rollup` (scripts/graphify/bkit-graphify.sh). Writes a JSON that
8
+ Called by `pnpm bkit:graph:rollup` (scripts/graphify/bkit-graphify.sh). Writes a JSON that
9
9
  bkit-graphify-rollup.py renders as the import-time side-effect table in
10
10
  docs/capabilities.md.
11
11
 
@@ -135,7 +135,7 @@ def inside_callable(path, line):
135
135
  # --- who imports this, transitively -------------------------------------------
136
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
- # `exports` map. bkit-graph-repair.py injects them during `pnpm graph`, so they are
138
+ # `exports` map. bkit-graph-repair.py injects them during `pnpm bkit:graph`, so they are
139
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"]:
@@ -232,5 +232,5 @@ print(f"[eager] {REPAIRED} of those edges came from bkit-graph-repair.py — imp
232
232
  f"graphify cannot resolve (.js -> .tsx, workspace exports subpaths)")
233
233
  if ungraphed:
234
234
  print(f"[eager] {ungraphed} scanned files absent from graph.json (column-0 filter only) "
235
- f"— run 'pnpm graph:update' to close the gap", file=sys.stderr)
235
+ f"— run 'pnpm bkit:graph:update' to close the gap", file=sys.stderr)
236
236
  print(f"[eager] wrote {args.eager_out}", file=sys.stderr)
@@ -0,0 +1,63 @@
1
+ # Example. Copy into the repo and own it.
2
+ # bkit install does not write this file and does not overwrite a copy.
3
+ # List the docs to embed into in GRAPH_EMBED_DOCS (bkit-graphify.sh).
4
+
5
+ #!/usr/bin/env python3
6
+ """Copy the packages diagram from the capability register into other docs.
7
+
8
+ Called by `pnpm bkit:graph:rollup`, `:register` and `:refresh` (write) and by
9
+ `pnpm bkit:graph:check` (--check), scripts/graphify/bkit-graphify.sh, for every doc in
10
+ GRAPH_EMBED_DOCS. Runs on system python (stdlib only).
11
+
12
+ bkit-graph-embed.py <capabilities.md> <doc>... [--check]
13
+
14
+ Each doc holds one block between the two markers below. Write mode replaces what
15
+ is between them with the fenced Mermaid block under `## Architecture — packages`
16
+ in the register, byte for byte. --check writes nothing and exits 1 when any doc's
17
+ block differs. A doc without both markers exits 2: a listed doc that cannot take
18
+ the diagram is a setup error, not a clean result.
19
+ """
20
+
21
+ import argparse
22
+ import re
23
+ import sys
24
+
25
+ START, END = "<!-- graph:packages:start -->", "<!-- graph:packages:end -->"
26
+ HEADING = "## Architecture — packages"
27
+
28
+ ap = argparse.ArgumentParser()
29
+ ap.add_argument("capabilities_doc")
30
+ ap.add_argument("docs", nargs="+")
31
+ ap.add_argument("--check", action="store_true")
32
+ args = ap.parse_args()
33
+
34
+ register = open(args.capabilities_doc, encoding="utf-8").read()
35
+ if HEADING not in register:
36
+ sys.exit(f"[graph] {args.capabilities_doc}: no `{HEADING}` section — run pnpm bkit:graph:rollup first")
37
+ m = re.search(r"```mermaid\n.*?\n```", register.split(HEADING, 1)[1], re.S)
38
+ if not m:
39
+ sys.exit(f"[graph] {args.capabilities_doc}: `{HEADING}` has no ```mermaid block")
40
+ block = f"{START}\n\n{m.group(0)}\n\n{END}"
41
+
42
+ stale = []
43
+ for doc in args.docs:
44
+ text = open(doc, encoding="utf-8").read()
45
+ if text.count(START) != 1 or text.count(END) != 1 or text.index(START) > text.index(END):
46
+ print(f"[graph] {doc}: needs exactly one {START} … {END} pair", file=sys.stderr)
47
+ sys.exit(2)
48
+ head, rest = text.split(START, 1)
49
+ tail = rest.split(END, 1)[1]
50
+ fresh = head + block + tail
51
+ if fresh == text:
52
+ continue
53
+ if args.check:
54
+ stale.append(doc)
55
+ else:
56
+ with open(doc, "w", encoding="utf-8") as fh:
57
+ fh.write(fresh)
58
+ print(f"[graph] {doc}: packages diagram rewritten")
59
+
60
+ if stale:
61
+ print(f"[graph] DRIFT: the packages diagram in {', '.join(stale)} is not the one in "
62
+ f"{args.capabilities_doc}.", file=sys.stderr)
63
+ sys.exit(1)
@@ -9,7 +9,7 @@ the sibling `graph-*.py` scripts, which are standalone and cannot be imported
9
9
  themselves.
10
10
 
11
11
  ONE WRITER. `bkit-graph-repair.py` is the only script that writes
12
- `resolved_import_edges()` into graph.json, during `pnpm graph`, so `graphify affected` /
12
+ `resolved_import_edges()` into graph.json, during `pnpm bkit:graph`, so `graphify affected` /
13
13
  `explain` / `path` / `query` see the same edges these scripts do. bkit-graph-eager.py
14
14
  and bkit-graphify-rollup.py call `warn_if_unrepaired()`, which compares the same set
15
15
  against graph.json, and otherwise just read the graph.
@@ -147,7 +147,7 @@ def warn_if_unrepaired(graph, who, stream=None):
147
147
  if missing:
148
148
  print(f"[{who}] WARNING: graph.json lacks {len(missing)} imports that "
149
149
  f"bkit-graph-repair.py adds, so reachability and blast-radius numbers "
150
- f"below are UNDERSTATED. Run 'pnpm graph:update'.",
150
+ f"below are UNDERSTATED. Run 'pnpm bkit:graph:update'.",
151
151
  file=stream or _sys.stderr)
152
152
  return repair_state(graph)
153
153
 
@@ -4,39 +4,90 @@
4
4
  # copy lacks that call → re-copy the "Capability register" block from the template.
5
5
  # bkit install does not write this file and does not overwrite a copy.
6
6
  #
7
- # Capability register current on dev. BLOCKS a push to dev when docs/capabilities.md is not
8
- # what the pushed commit builds. Reads PUSH_DEV_SHA (commit pushed to dev), set by the bkit
9
- # pre-push template while reading git's ref list on stdin; stdin is consumed by now.
7
+ # Capability register current wherever CI checks it. BLOCKS a push to dev, and a push of a
8
+ # branch with an open PR into dev, when docs/capabilities.md is not what the pushed commit
9
+ # builds: CI's Check Capability Register fails both. Reads PUSH_DEV_SHA (commit pushed to dev),
10
+ # BRANCH (the checked-out branch) and PUSH_BRANCH_SHA (commit pushed to that branch, empty when
11
+ # the push does not update it), set by the bkit pre-push template while reading git's ref list
12
+ # on stdin; stdin is consumed by now. An older hook copy sets no BRANCH / PUSH_BRANCH_SHA → the
13
+ # checked-out branch and HEAD stand in.
10
14
  #
11
15
  # graphify reads the working tree → check runs in a throwaway checkout of the pushed commit
12
16
  # (`check-at`): uncommitted edits, a concurrent session's included, cannot change the answer.
13
17
  # Other graphify release → blocked, with the install command. graphify NOT INSTALLED → warn
14
18
  # only, saying the check did not run: a cloud session without it must still push; CI's Check
15
- # Capability Register runs the same check on every push to dev. Revert pushes (IS_REVERT=1)
16
- # skip it, as they skip the test tiers. Other branches → warn-only staleness note.
19
+ # Capability Register runs the same check on every push to dev and every pull request. The
20
+ # open-PR lookup needs gh: gh NOT INSTALLED, or its call FAILING (offline, not signed in) →
21
+ # warn only, as with graphify; a lookup that cannot answer is never read as "no PR". Revert pushes
22
+ # (IS_REVERT=1) skip it, as they skip the test tiers. A branch with no open PR → warn-only
23
+ # staleness note.
17
24
  CAP_DOC="docs/capabilities.md"
18
25
  if [ -f scripts/graphify/bkit-graphify.sh ] && [ -f "$CAP_DOC" ]; then
19
- if [ -n "${PUSH_DEV_SHA:-}" ] && [ "${IS_REVERT:-0}" != "1" ]; then
26
+ # The commit to check, and what the push is; empty → the warn-only note.
27
+ CAP_GATE_SHA=""
28
+ CAP_GATE_WHAT=""
29
+ if [ "${IS_REVERT:-0}" = "1" ]; then
30
+ :
31
+ elif [ -n "${PUSH_DEV_SHA:-}" ]; then
32
+ CAP_GATE_SHA="$PUSH_DEV_SHA"
33
+ CAP_GATE_WHAT="this push to dev"
34
+ else
35
+ CAP_BRANCH="${BRANCH:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")}"
36
+ if [ -n "${PUSH_BRANCH_SHA+set}" ]; then
37
+ CAP_PUSHED="$PUSH_BRANCH_SHA"
38
+ else
39
+ CAP_PUSHED=$(git rev-parse HEAD 2>/dev/null || echo "")
40
+ fi
41
+ case "$CAP_BRANCH" in
42
+ "" | HEAD | dev | main) ;;
43
+ *)
44
+ if [ -z "$CAP_PUSHED" ]; then
45
+ :
46
+ else
47
+ # Why the lookup could not answer; empty → it answered (a PR number, or none).
48
+ CAP_UNKNOWN=""
49
+ if ! command -v gh >/dev/null 2>&1; then
50
+ CAP_UNKNOWN="gh is not installed"
51
+ # strip hook-injected GIT_DIR/GIT_WORK_TREE so gh resolves the repo from cwd (worktree-safe)
52
+ elif CAP_PR=$(env -u GIT_DIR -u GIT_WORK_TREE gh pr list --head "$CAP_BRANCH" --base dev --state open --json number --jq '.[0].number' 2>/dev/null); then
53
+ if [ -n "$CAP_PR" ]; then
54
+ CAP_GATE_SHA="$CAP_PUSHED"
55
+ CAP_GATE_WHAT="PR #$CAP_PR into dev"
56
+ fi
57
+ else
58
+ CAP_UNKNOWN="gh pr list failed (offline, or gh not signed in)"
59
+ fi
60
+ if [ -n "$CAP_UNKNOWN" ]; then
61
+ echo "[pre-push] WARNING: $CAP_DOC was NOT checked — $CAP_UNKNOWN, so whether '$CAP_BRANCH' has an open PR is unknown." >&2
62
+ echo "[pre-push] If a PR is open, CI's Check Capability Register fails it on a stale register; run" >&2
63
+ echo "[pre-push] pnpm bkit:graph:refresh, commit, and push again." >&2
64
+ fi
65
+ fi
66
+ ;;
67
+ esac
68
+ fi
69
+ if [ -n "$CAP_GATE_SHA" ]; then
20
70
  if ! command -v graphify >/dev/null 2>&1; then
21
71
  echo "[pre-push] WARNING: $CAP_DOC was NOT checked — graphify is not installed." >&2
22
- echo "[pre-push] CI's Check Capability Register checks it on this push; if it reds there, run" >&2
23
- echo "[pre-push] pnpm graph:refresh, commit, and push again. Install graphify to check before pushing:" >&2
72
+ echo "[pre-push] CI's Check Capability Register checks it for $CAP_GATE_WHAT; if it reds there, run" >&2
73
+ echo "[pre-push] pnpm bkit:graph:refresh, commit, and push again. Install graphify to check before pushing:" >&2
24
74
  echo "[pre-push] brew install uv && uv tool install '$(bash scripts/graphify/bkit-graphify.sh spec)'" >&2
25
- elif ! bash scripts/graphify/bkit-graphify.sh check-at "$PUSH_DEV_SHA" < /dev/null; then
26
- echo "[pre-push] BLOCKED: $CAP_DOC is not what the pushed commit builds (diff above)." >&2
27
- echo "[pre-push] Fix: pnpm graph:refresh && git add $CAP_DOC && git commit, then push again." >&2
75
+ elif ! bash scripts/graphify/bkit-graphify.sh check-at "$CAP_GATE_SHA" < /dev/null; then
76
+ echo "[pre-push] BLOCKED: $CAP_DOC is not what the pushed commit builds (diff above); CI fails $CAP_GATE_WHAT on it." >&2
77
+ echo "[pre-push] Fix: pnpm bkit:graph:refresh, git add the files it rewrote, git commit, then push again." >&2
28
78
  exit 1
29
79
  fi
30
80
  else
31
- # Warn-only. A fresh register is stamped at the parent of its commit → staleness =
32
- # source files changed since that stamp.
33
- CAP_SHA=$(sed -n 's/.*Diagrams from `graph\.json` @ `\([0-9a-f]\{7,\}\)`.*/\1/p' "$CAP_DOC" | head -1)
34
- if [ -n "$CAP_SHA" ] && git cat-file -e "$CAP_SHA^{commit}" 2>/dev/null; then
81
+ # Warn-only. Staleness = source files changed since the last commit that changed the
82
+ # register. A rebuild that changes nothing commits nothing, so the count can include
83
+ # files that left the register as it was.
84
+ CAP_SHA=$(git log -1 --format=%h -- "$CAP_DOC" 2>/dev/null || true)
85
+ if [ -n "$CAP_SHA" ]; then
35
86
  CAP_CHANGED=$(git diff --name-only "$CAP_SHA..HEAD" -- '*.ts' '*.tsx' 2>/dev/null | wc -l | tr -d ' ')
36
87
  if [ "${CAP_CHANGED:-0}" -gt 0 ]; then
37
- echo "[pre-push] NOTE: $CAP_DOC diagrams were built at $CAP_SHA; $CAP_CHANGED source files changed since." >&2
38
- echo "[pre-push] Refresh when convenient: pnpm graph:refresh" >&2
39
- echo "[pre-push] Not a gate on this branch. A push to dev is blocked until it is current." >&2
88
+ echo "[pre-push] NOTE: $CAP_DOC last changed in $CAP_SHA; $CAP_CHANGED source files changed since." >&2
89
+ echo "[pre-push] Refresh when convenient: pnpm bkit:graph:refresh" >&2
90
+ echo "[pre-push] Not a gate on this branch until it has an open PR into dev; a push to dev is blocked until it is current." >&2
40
91
  fi
41
92
  fi
42
93
  fi
@@ -5,7 +5,7 @@
5
5
  #!/usr/bin/env python3
6
6
  """Inject the import edges graphify could not resolve back into graph.json.
7
7
 
8
- Called by `pnpm graph`, `:clean` and `:update` (scripts/graphify/bkit-graphify.sh),
8
+ Called by `pnpm bkit:graph`, `:clean` and `:update` (scripts/graphify/bkit-graphify.sh),
9
9
  between `extract` and `cluster-only`.
10
10
 
11
11
  bkit-graph-repair.py <graph.json> [--rules R] [--quiet]
@@ -16,9 +16,9 @@ checks, the generated doc, and `graphify affected`, `god-nodes`, `explain`,
16
16
  this step says so.
17
17
 
18
18
  `graphify update` rewrites graph.json without the injected edges, so every
19
- wrapper command that writes the file (`pnpm graph`, `:clean`, `:update`) runs
19
+ wrapper command that writes the file (`pnpm bkit:graph`, `:clean`, `:update`) runs
20
20
  this step at the end. The step is idempotent: after a raw `graphify update .`,
21
- run `pnpm graph:update`.
21
+ run `pnpm bkit:graph:update`.
22
22
 
23
23
  ORDER MATTERS: this runs BEFORE clustering, so communities, the god-node
24
24
  ranking and the cycle list in graph-report.md are computed from the repaired graph.
@@ -5,7 +5,7 @@
5
5
  #!/usr/bin/env python3
6
6
  """Link user-facing routes to the backend capabilities they reach.
7
7
 
8
- Called by `pnpm graph:rollup` (scripts/graphify/bkit-graphify.sh). Writes a JSON the
8
+ Called by `pnpm bkit:graph:rollup` (scripts/graphify/bkit-graphify.sh). Writes a JSON the
9
9
  capabilities doc renders as its route layer.
10
10
 
11
11
  bkit-graph-surface.py <graph.json> <surface-out.json> [--quiet]
@@ -5,7 +5,7 @@
5
5
  #!/usr/bin/env python3
6
6
  """Export the full symbol graph to GraphML for Gephi / yEd.
7
7
 
8
- Called by `pnpm graph:graphml` (scripts/graphify/bkit-graphify.sh) through GRAPHIFY'S
8
+ Called by `pnpm bkit:graph:graphml` (scripts/graphify/bkit-graphify.sh) through GRAPHIFY'S
9
9
  OWN interpreter — it imports graphify itself.
10
10
 
11
11
  bkit-graphify-graphml.py <graph.json> <out.graphml>