@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
@@ -1,194 +0,0 @@
1
- #!/bin/bash
2
- # Example. Copy into scripts/ci/ and own it.
3
- # bkit install does not write this file and does not overwrite a copy.
4
- #
5
- # bkit-local-stack-lock.sh — one run at a time on a local stack every checkout shares.
6
- #
7
- # . scripts/ci/bkit-local-stack-lock.sh
8
- # take_local_stack_lock "<who>" || exit 1 # waits while another run holds it
9
- # try_local_stack_lock "<who>" # returns 1 at once while another run holds it
10
- # release_local_stack_lock # optional: the lock frees itself when the caller exits
11
- #
12
- # bash scripts/ci/bkit-local-stack-lock.sh run "<who>" -- <command> [args…] # package.json
13
- #
14
- # WHY. Agents work in several worktrees of one repo at once, and every worktree talks to the
15
- # SAME local services: a Docker database, an emulator, anything whose container names and ports
16
- # come from the repo's config. Nothing stops two worktrees using them at once, so a database
17
- # reset from one wipes the data under a test run in another, and a dev server that stops "its"
18
- # stack on exit stops it under someone else's run. Both show up as test failures nobody caused.
19
- # A run that starts, resets or stops the stack, or tests against it, takes this lock first; a
20
- # second run waits and says who it is waiting for.
21
- #
22
- # Wiring:
23
- # - package.json: wrap each script that starts, resets or stops the stack, e.g.
24
- # "db:reset": "bash scripts/ci/bkit-local-stack-lock.sh run db:reset -- <your reset command>"
25
- # - local runners that test against the stack: source this file and call take_local_stack_lock
26
- # before the first command that touches the stack.
27
- # - fix hints and docs name those scripts, never the raw command, which skips the lock.
28
- #
29
- # The lock is named after the stack: BKIT_LOCAL_STACK when set, otherwise the folder name of the
30
- # repo's main checkout, so every worktree of one repo finds the same lock. A throwaway stack with
31
- # names and ports of its own sets BKIT_LOCAL_STACK to its own name and never waits on the shared
32
- # one. The lock file sits outside the checkout: ~/.cache/bkit/local-stack-lock/<name>.lock
33
- # ($XDG_CACHE_HOME when set). A small perl process holds it (flock) and exits within a second of
34
- # the caller exiting, however the caller ends (its parent changes), so a killed run cannot leave
35
- # a stale lock behind. perl by its full path, so a PATH shim cannot stand in for it.
36
- #
37
- # A runner started by a runner that holds the lock (LOCAL_STACK_LOCK_OWNER, exported on success)
38
- # does not wait on its own parent. Safe under a caller's `set -e`. CI (CI=true or CI=1): no-op,
39
- # as a CI runner has one job and its own Docker. LOCAL_STACK_LOCK_WAIT_S (default 3600) caps
40
- # the wait. Needs bash and /usr/bin/perl (macOS and Linux ship both).
41
-
42
- _LOCAL_STACK_LOCK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
43
- _LOCAL_STACK_LOCK_ROOT="$(git -C "$_LOCAL_STACK_LOCK_DIR" rev-parse --show-toplevel 2>/dev/null || echo "$_LOCAL_STACK_LOCK_DIR")"
44
- LOCAL_STACK_LOCK_PID=""
45
-
46
- # The stack's name: BKIT_LOCAL_STACK, else the main checkout's folder name, the same from every
47
- # worktree. Characters outside A-Z a-z 0-9 . _ - become _.
48
- local_stack_lock_name() {
49
- _lsl_name="${BKIT_LOCAL_STACK:-}"
50
- if [ -z "$_lsl_name" ]; then
51
- _lsl_common="$(git -C "$_LOCAL_STACK_LOCK_DIR" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" || return 1
52
- [ -n "$_lsl_common" ] || return 1
53
- case "$(basename "$_lsl_common")" in
54
- .git) _lsl_name="$(basename "$(dirname "$_lsl_common")")" ;;
55
- *) _lsl_name="$(basename "$_lsl_common" .git)" ;;
56
- esac
57
- fi
58
- printf '%s\n' "$_lsl_name" | LC_ALL=C tr -c 'A-Za-z0-9._\n-' '_'
59
- }
60
-
61
- # The lock file for the stack this checkout uses.
62
- local_stack_lock_file() {
63
- _lsl_stack="$(local_stack_lock_name)" || return 1
64
- echo "${XDG_CACHE_HOME:-$HOME/.cache}/bkit/local-stack-lock/${_lsl_stack}.lock"
65
- }
66
-
67
- # "<who> — <checkout> (pid N, since HH:MM:SS)" for the run holding the lock, or nothing.
68
- local_stack_lock_holder() {
69
- _lsl_held="$(local_stack_lock_file)" || return 0
70
- cat "${_lsl_held}.holder" 2>/dev/null
71
- return 0
72
- }
73
-
74
- _local_stack_lock() {
75
- _lsl_mode="$1"
76
- _lsl_who="$2"
77
- if [ "${CI:-}" = "true" ] || [ "${CI:-}" = "1" ]; then return 0; fi
78
- if [ -n "${LOCAL_STACK_LOCK_OWNER:-}" ] && kill -0 "$LOCAL_STACK_LOCK_OWNER" 2>/dev/null; then return 0; fi
79
- if [ -n "$LOCAL_STACK_LOCK_PID" ] && kill -0 "$LOCAL_STACK_LOCK_PID" 2>/dev/null; then return 0; fi
80
-
81
- if ! _lsl_file="$(local_stack_lock_file)"; then
82
- echo "[local-stack-lock] ❌ cannot name the local stack: run inside a git checkout, or set BKIT_LOCAL_STACK" >&2
83
- return 1
84
- fi
85
- _lsl_label="$(basename "$_lsl_file" .lock)"
86
- if [ ! -x /usr/bin/perl ]; then
87
- echo "[local-stack-lock] ❌ could not take the lock for the local stack $_lsl_label: /usr/bin/perl not found" >&2
88
- return 1
89
- fi
90
- mkdir -p "$(dirname "$_lsl_file")" || return 1
91
- _lsl_fifo="$(mktemp -u "${TMPDIR:-/tmp}/local-stack-lock.XXXXXX")"
92
- mkfifo "$_lsl_fifo" || return 1
93
-
94
- # The holder answers on the fifo once: ok, busy <holder>, timeout <holder> or error <why>.
95
- /usr/bin/perl -e '
96
- use strict;
97
- use Fcntl qw(:flock);
98
- use POSIX qw(strftime);
99
- my ($file, $owner, $who, $checkout, $fifo, $wait_s, $mode, $label) = @ARGV;
100
- # The caller is the parent of this process. When it exits, this process goes to init (or a
101
- # subreaper) at once, while `kill 0` would still find it until whoever started it reaps it.
102
- my $parent = getppid();
103
- my $caller_alive = sub { getppid() == $parent };
104
- open(my $out, ">", $fifo) or exit 1;
105
- $out->autoflush(1);
106
- my $holder = sub { open(my $h, "<", "$file.holder") or return "another run"; my $l = <$h>; chomp $l; $l };
107
- my $lock;
108
- open($lock, ">>", $file) or do { print $out "error cannot open $file: $!\n"; exit 1 };
109
- my $start = time;
110
- my $next_note = 0;
111
- until (flock($lock, LOCK_EX | LOCK_NB)) {
112
- exit 0 unless $caller_alive->();
113
- if ($mode eq "try") { print $out "busy " . $holder->() . "\n"; exit 0 }
114
- if (time - $start >= $wait_s) { print $out "timeout " . $holder->() . "\n"; exit 0 }
115
- if (time >= $next_note) {
116
- my $m = int((time - $start) / 60);
117
- my $so_far = $m ? " (still, $m min so far)" : "";
118
- print STDERR "[local-stack-lock] ⏳ $who is waiting for the local stack $label$so_far: in use by " . $holder->() . "\n";
119
- $next_note = time + 60;
120
- }
121
- sleep 1;
122
- }
123
- $SIG{TERM} = $SIG{INT} = $SIG{HUP} = sub { unlink "$file.holder"; exit 0 };
124
- if (open(my $h, ">", "$file.holder")) {
125
- print $h "$who — $checkout (pid $owner, since " . strftime("%H:%M:%S", localtime) . ")\n";
126
- close $h;
127
- }
128
- print $out "ok\n";
129
- close $out;
130
- sleep 1 while $caller_alive->();
131
- unlink "$file.holder";
132
- ' "$_lsl_file" "$$" "$_lsl_who" "$_LOCAL_STACK_LOCK_ROOT" "$_lsl_fifo" "${LOCAL_STACK_LOCK_WAIT_S:-3600}" "$_lsl_mode" "$_lsl_label" </dev/null >/dev/null &
133
- _lsl_pid=$!
134
- # The fifo is opened read-write, so the read never blocks on a holder that died before it
135
- # answered (a failed fork under load, a killed perl): the loop stops once it is gone.
136
- _lsl_reply="$(
137
- exec 3<>"$_lsl_fifo"
138
- while :; do
139
- if IFS= read -r -t 1 _lsl_line <&3; then
140
- printf '%s' "$_lsl_line"
141
- break
142
- fi
143
- kill -0 "$_lsl_pid" 2>/dev/null || break
144
- done
145
- )" || true
146
- rm -f "$_lsl_fifo"
147
-
148
- case "$_lsl_reply" in
149
- ok)
150
- LOCAL_STACK_LOCK_PID="$_lsl_pid"
151
- export LOCAL_STACK_LOCK_OWNER="$$"
152
- return 0
153
- ;;
154
- busy\ *)
155
- echo "[local-stack-lock] the local stack $_lsl_label is in use by ${_lsl_reply#busy }" >&2
156
- ;;
157
- timeout\ *)
158
- echo "[local-stack-lock] ❌ $_lsl_who gave up after ${LOCAL_STACK_LOCK_WAIT_S:-3600}s waiting for the local stack $_lsl_label, in use by ${_lsl_reply#timeout }" >&2
159
- echo "[local-stack-lock] Let that run finish, or stop it. LOCAL_STACK_LOCK_WAIT_S sets how long to wait." >&2
160
- ;;
161
- "")
162
- echo "[local-stack-lock] ❌ could not take the lock for the local stack $_lsl_label: the perl process holding it stopped before it answered" >&2
163
- ;;
164
- *)
165
- echo "[local-stack-lock] ❌ could not take the lock for the local stack $_lsl_label: ${_lsl_reply#error }" >&2
166
- ;;
167
- esac
168
- wait "$_lsl_pid" 2>/dev/null || true
169
- return 1
170
- }
171
-
172
- take_local_stack_lock() { _local_stack_lock wait "$1"; }
173
- try_local_stack_lock() { _local_stack_lock try "$1"; }
174
-
175
- release_local_stack_lock() {
176
- [ -n "$LOCAL_STACK_LOCK_PID" ] || return 0
177
- kill "$LOCAL_STACK_LOCK_PID" 2>/dev/null || true
178
- wait "$LOCAL_STACK_LOCK_PID" 2>/dev/null || true
179
- LOCAL_STACK_LOCK_PID=""
180
- unset LOCAL_STACK_LOCK_OWNER
181
- return 0
182
- }
183
-
184
- if [ "${BASH_SOURCE[0]}" = "$0" ]; then
185
- if [ "${1:-}" != "run" ] || [ -z "${2:-}" ]; then
186
- echo "usage: bash scripts/ci/bkit-local-stack-lock.sh run \"<who>\" -- <command> [args…]" >&2
187
- exit 2
188
- fi
189
- _lsl_run_who="$2"
190
- shift 2
191
- [ "${1:-}" = "--" ] && shift
192
- take_local_stack_lock "$_lsl_run_who" || exit 1
193
- "$@"
194
- fi
@@ -1,353 +0,0 @@
1
- // commands/harvest.ts — Cross-repo harvest CLI.
2
- //
3
- // MOVES consumer `.bkit/friction.jsonl` and COPIES `.bkit/stats.jsonl` into bkit's
4
- // central store at `harvest/`. COUNT-ONLY aggregates `docs/{deferrals,failures}.jsonl`
5
- // (dimensional counts from envelope metadata; prose NOT copied). Deduplicates by
6
- // row content; entity counts fold by per-kind composite identity.
7
- //
8
- // INVARIANTS (PII guard + move/copy contract):
9
- // - Touches ONLY the named .jsonl ledgers — never any .env/secret files.
10
- // - NEVER commits in any repo (bkit's or a consumer's) — the caller commits.
11
- // - stats.jsonl is COPY-ONLY: consumer mtime + content unchanged.
12
- // - friction.jsonl is MOVE: harvested rows are pruned from the consumer, but ONLY
13
- // after that exact row is durably fsync'd + read back from the central store.
14
- // - The prune gate is byte-for-byte CONTENT, never identity.
15
- // - The central store ACCUMULATES across runs (never cleared) and holds every
16
- // DISTINCT row, deduped by content only. It is never rewritten from the fold. It is
17
- // gitignored (private consumer content), so it is the only record of pruned consumer
18
- // friction; readers fold it.
19
- // - Malformed consumer lines are NEVER pruned (not ours to delete).
20
- // - Grep-able [bkit-harvest] log lines.
21
- // - Relies on the tolerant `parse` for half-written tails.
22
- //
23
- // Friction is moved, not copied: consumers start each cycle clean. Ordering is
24
- // copy -> fsync -> verify -> prune; a crash at any point re-copies idempotently on the
25
- // next run.
26
- //
27
- // Consumers are listed in `harvest/consumers.md` (one absolute path per line).
28
- // See DE-34 for the shared-entrypoint + crash-isolation contract.
29
- import * as fs from "node:fs";
30
- import * as path from "node:path";
31
- import { fold, parse, resolveRepoSlug, } from "../ledgers/telemetry.js";
32
- import { parseJson } from "../shared/json.js";
33
- // ---------------------------------------------------------------------------
34
- // Constants
35
- // ---------------------------------------------------------------------------
36
- /** Files to COPY from each consumer's `.bkit/` directory (content + dedup). */
37
- export const HARVEST_COPY_FILES = ["stats.jsonl", "friction.jsonl"];
38
- /**
39
- * Files PRUNED from the consumer after their rows are durably in the central store.
40
- * Must be a subset of HARVEST_COPY_FILES. `stats.jsonl` is absent: it is copied, never
41
- * moved.
42
- */
43
- export const HARVEST_PRUNE_FILES = ["friction.jsonl"];
44
- /** Files to COUNT-ONLY from each consumer's `docs/` directory (metadata only). */
45
- export const HARVEST_COUNT_FILES = ["deferrals.jsonl", "failures.jsonl"];
46
- /** Path (relative to bkit repo root) for the consumers list. */
47
- export const CONSUMERS_FILE = "harvest/consumers.md";
48
- /**
49
- * Destination directory in bkit for harvested data. Repo root, NOT under `.bkit/`
50
- * (bkit's managed/installed surface).
51
- */
52
- export const HARVEST_DEST_DIR = "harvest";
53
- // ---------------------------------------------------------------------------
54
- // Read consumer list from `harvest/consumers.md`
55
- // ---------------------------------------------------------------------------
56
- /**
57
- * Read the list of consumer repo root paths from `harvest/consumers.md`.
58
- * Returns an array of absolute paths (non-empty lines, comments stripped).
59
- */
60
- export function readConsumerPaths(bkitRoot) {
61
- const consumersFile = path.join(bkitRoot, CONSUMERS_FILE);
62
- if (!fs.existsSync(consumersFile)) {
63
- console.error(`[bkit-harvest] consumers file not found: ${consumersFile}`);
64
- return [];
65
- }
66
- const raw = fs.readFileSync(consumersFile, "utf-8");
67
- return raw
68
- .split("\n")
69
- .map((line) => line.trim())
70
- .filter((line) => line.length > 0 && !line.startsWith("#"));
71
- }
72
- // ---------------------------------------------------------------------------
73
- // Harvest a single consumer
74
- // ---------------------------------------------------------------------------
75
- /**
76
- * Harvest one consumer's `.bkit/{stats,friction}.jsonl` (COPY) and
77
- * `docs/{deferrals,failures}.jsonl` (COUNT-ONLY).
78
- * NEVER writes to the consumer repo.
79
- */
80
- export function harvestConsumer(consumerPath, bkitRoot) {
81
- const result = {
82
- consumerPath,
83
- copiedRows: 0,
84
- countOnlyRows: {},
85
- countOnlyRawRows: {},
86
- malformedLineCount: 0,
87
- skipped: false,
88
- prunedRows: {},
89
- };
90
- if (!fs.existsSync(consumerPath)) {
91
- result.skipped = true;
92
- result.skipReason = `consumer path not found: ${consumerPath}`;
93
- console.error(`[bkit-harvest] SKIP ${consumerPath} — path not found`);
94
- return result;
95
- }
96
- const destDir = path.join(bkitRoot, HARVEST_DEST_DIR);
97
- if (!fs.existsSync(destDir)) {
98
- fs.mkdirSync(destDir, { recursive: true });
99
- }
100
- // COPY: .bkit/{stats,friction}.jsonl
101
- for (const filename of HARVEST_COPY_FILES) {
102
- const srcPath = path.join(consumerPath, ".bkit", filename);
103
- if (!fs.existsSync(srcPath)) {
104
- console.error(`[bkit-harvest] ${consumerPath}/.bkit/${filename} — not found, skipping`);
105
- continue;
106
- }
107
- // Record mtime BEFORE reading (copy-only invariant verification support)
108
- const statBefore = fs.statSync(srcPath);
109
- const raw = fs.readFileSync(srcPath, "utf-8");
110
- const statAfter = fs.statSync(srcPath);
111
- // Verify consumer file was not modified by our read (should always hold)
112
- if (statBefore.mtimeMs !== statAfter.mtimeMs) {
113
- console.error(`[bkit-harvest] WARNING: ${srcPath} mtime changed during read — harvest continues but data may be inconsistent`);
114
- }
115
- const parsed = parse(raw);
116
- result.copiedRows += parsed.events.length;
117
- result.malformedLineCount += parsed.malformedLineCount;
118
- // Stamp repo on each event if missing
119
- const consumerSlug = consumerPathToSlug(consumerPath);
120
- const stamped = parsed.events.map((ev) => stampRepo(ev, consumerSlug));
121
- // Write to harvest dest (append)
122
- const destPath = path.join(destDir, filename);
123
- for (const ev of stamped) {
124
- fs.appendFileSync(destPath, JSON.stringify(ev) + "\n", "utf-8");
125
- }
126
- console.error(`[bkit-harvest] ${consumerPath}/.bkit/${filename} — copied ${parsed.events.length} rows (malformed: ${parsed.malformedLineCount})`);
127
- }
128
- // COUNT-ONLY: docs/{deferrals,failures}.jsonl
129
- for (const filename of HARVEST_COUNT_FILES) {
130
- const srcPath = path.join(consumerPath, "docs", filename);
131
- if (!fs.existsSync(srcPath)) {
132
- continue;
133
- }
134
- const raw = fs.readFileSync(srcPath, "utf-8");
135
- const parsed = parse(raw);
136
- // Count ENTITIES, not lines: updating a deferral appends a new same-key row, and
137
- // `fold` collapses same-key rows to the current state. See .bkit/jsonl.md § Updating
138
- // a Row.
139
- const folded = fold(parsed.events);
140
- result.countOnlyRows[filename] = folded.size;
141
- result.countOnlyRawRows[filename] = parsed.events.length;
142
- result.malformedLineCount += parsed.malformedLineCount;
143
- console.error(`[bkit-harvest] ${consumerPath}/docs/${filename} — count-only: ${folded.size} entities (${parsed.events.length} rows)`);
144
- }
145
- return result;
146
- }
147
- // ---------------------------------------------------------------------------
148
- // Prune — remove durably-stored rows from a consumer ledger
149
- // ---------------------------------------------------------------------------
150
- /**
151
- * Stamp `repo` on an event when the consumer wrote the row without one.
152
- * MUST be applied on both the store side and the prune side, or the two contents
153
- * diverge and a stored row is never recognised as prunable.
154
- */
155
- export function stampRepo(event, consumerSlug) {
156
- return {
157
- ...event,
158
- repo: event.repo && event.repo.length > 0 ? event.repo : consumerSlug,
159
- };
160
- }
161
- /**
162
- * Remove from `srcPath` exactly those rows whose CONTENT is durably in the store.
163
- *
164
- * Gated on byte-for-byte content, NOT on identity.
165
- *
166
- * Line-level, NOT event-level: a line that does not parse is kept verbatim.
167
- *
168
- * Re-reads the file at prune time, so rows appended by the consumer DURING the harvest
169
- * survive.
170
- *
171
- * Writes via temp-file + rename; an interrupted prune never leaves a torn ledger.
172
- */
173
- export function pruneConsumerFile(srcPath, consumerSlug, durable) {
174
- const raw = fs.readFileSync(srcPath, "utf-8");
175
- const kept = [];
176
- let removed = 0;
177
- for (const line of raw.split("\n")) {
178
- if (line.trim() === "")
179
- continue;
180
- const parsed = parseJson(line.trim());
181
- if (!parsed.ok) {
182
- kept.push(line); // malformed — never ours to delete
183
- continue;
184
- }
185
- const event = parsed.value;
186
- if (durable.rows.has(canonicalRow(stampRepo(event, consumerSlug)))) {
187
- removed++;
188
- continue;
189
- }
190
- kept.push(line);
191
- }
192
- if (removed === 0)
193
- return { removed: 0, kept: kept.length };
194
- const next = kept.length > 0 ? kept.join("\n") + "\n" : "";
195
- const tmpPath = `${srcPath}.bkit-harvest.tmp`;
196
- fs.writeFileSync(tmpPath, next, "utf-8");
197
- fs.renameSync(tmpPath, srcPath);
198
- return { removed, kept: kept.length };
199
- }
200
- /**
201
- * Canonical serialisation used to compare a consumer row against a stored row.
202
- * Safe as a plain `JSON.stringify`: the store was written from exactly this function's
203
- * output, and a JSON.parse -> JSON.stringify round-trip preserves key order, so the
204
- * store's own rewrite is byte-stable.
205
- */
206
- function canonicalRow(event) {
207
- return JSON.stringify(event);
208
- }
209
- /** fsync a file to disk, so a durability check is not just a page-cache read. */
210
- function fsyncFile(filePath) {
211
- const fd = fs.openSync(filePath, "r+");
212
- try {
213
- fs.fsyncSync(fd);
214
- }
215
- finally {
216
- fs.closeSync(fd);
217
- }
218
- }
219
- // ---------------------------------------------------------------------------
220
- // Run harvest across all consumers
221
- // ---------------------------------------------------------------------------
222
- /**
223
- * Run harvest across all consumers listed in `harvest/consumers.md`.
224
- * Deduplicates the store by row content after collecting all rows.
225
- */
226
- export function runHarvest(bkitRoot) {
227
- const consumerPaths = readConsumerPaths(bkitRoot);
228
- console.error(`[bkit-harvest] Found ${consumerPaths.length} consumer(s) in ${CONSUMERS_FILE}`);
229
- const consumerResults = [];
230
- let totalCopied = 0;
231
- const totalCountOnly = {};
232
- // The central store ACCUMULATES — it is NEVER cleared between runs. Re-copied rows
233
- // collapse via the content dedup below.
234
- const destDir = path.join(bkitRoot, HARVEST_DEST_DIR);
235
- for (const consumerPath of consumerPaths) {
236
- console.error(`[bkit-harvest] Harvesting: ${consumerPath}`);
237
- const res = harvestConsumer(consumerPath, bkitRoot);
238
- consumerResults.push(res);
239
- if (!res.skipped) {
240
- totalCopied += res.copiedRows;
241
- for (const [k, v] of Object.entries(res.countOnlyRows)) {
242
- totalCountOnly[k] = (totalCountOnly[k] ?? 0) + v;
243
- }
244
- }
245
- }
246
- // Deduplicate by content: drop exact re-copies, keep every distinct row in first-seen
247
- // order. Entity counts come from the fold, which is a read — never what is written.
248
- let mergedState = new Map();
249
- let dedupedRows = 0;
250
- /** Per-file durable content read BACK OFF DISK — the prune gate. */
251
- const durableByFile = {};
252
- for (const filename of HARVEST_COPY_FILES) {
253
- const destPath = path.join(destDir, filename);
254
- if (!fs.existsSync(destPath))
255
- continue;
256
- const raw = fs.readFileSync(destPath, "utf-8");
257
- const parsed = parse(raw);
258
- const folded = fold(parsed.events);
259
- mergedState = new Map([...mergedState, ...folded]);
260
- dedupedRows += folded.size;
261
- const distinctLines = [...new Set(parsed.events.map((ev) => canonicalRow(ev)))].join("\n");
262
- fs.writeFileSync(destPath, distinctLines + (distinctLines.length > 0 ? "\n" : ""), "utf-8");
263
- // Durability gate: fsync, then read the rows BACK OFF DISK; prune against those.
264
- fsyncFile(destPath);
265
- const verified = parse(fs.readFileSync(destPath, "utf-8"));
266
- durableByFile[filename] = {
267
- rows: new Set(verified.events.map((ev) => canonicalRow(ev))),
268
- };
269
- }
270
- // Prune ONLY now — every row below is confirmed byte-for-byte in the store on disk.
271
- let totalPruned = 0;
272
- let totalKept = 0;
273
- for (const res of consumerResults) {
274
- if (res.skipped)
275
- continue;
276
- const consumerSlug = consumerPathToSlug(res.consumerPath);
277
- for (const filename of HARVEST_PRUNE_FILES) {
278
- const srcPath = path.join(res.consumerPath, ".bkit", filename);
279
- if (!fs.existsSync(srcPath))
280
- continue;
281
- const durable = durableByFile[filename];
282
- if (!durable || durable.rows.size === 0)
283
- continue;
284
- const { removed, kept } = pruneConsumerFile(srcPath, consumerSlug, durable);
285
- if (removed > 0) {
286
- res.prunedRows[filename] = removed;
287
- totalPruned += removed;
288
- console.error(`[bkit-harvest] ${res.consumerPath}/.bkit/${filename} — pruned ${removed} harvested row(s)`);
289
- }
290
- if (kept > 0) {
291
- totalKept += kept;
292
- console.error(`[bkit-harvest] ${res.consumerPath}/.bkit/${filename} — kept ${kept} line(s) not in the store (malformed, or appended after the copy)`);
293
- }
294
- }
295
- }
296
- console.error(`[bkit-harvest] Done — total rows collected: ${totalCopied}, entities after fold: ${dedupedRows}, pruned from consumers: ${totalPruned}, kept in consumers: ${totalKept}`);
297
- if (totalPruned > 0) {
298
- console.error(`[bkit-harvest] ${totalPruned} row(s) now exist ONLY in ${HARVEST_DEST_DIR}/ (gitignored) — back it up to make them durable.`);
299
- }
300
- return {
301
- consumers: consumerResults,
302
- totalCopiedRows: totalCopied,
303
- totalCountOnly,
304
- dedupedRows,
305
- totalPrunedRows: totalPruned,
306
- mergedState,
307
- };
308
- }
309
- // ---------------------------------------------------------------------------
310
- // Helpers
311
- // ---------------------------------------------------------------------------
312
- /** Convert an absolute consumer path to a repo slug for stamping. */
313
- export function consumerPathToSlug(consumerPath) {
314
- // The consumer's OWN git remote — the only authoritative source.
315
- const slug = resolveRepoSlug(consumerPath);
316
- if (slug)
317
- return slug;
318
- // Last resort, and loud: a remote-less consumer still harvests.
319
- const parts = consumerPath
320
- .replace(/\/+$/, "")
321
- .split("/")
322
- .filter((p) => p.length > 0);
323
- const fallback = parts[parts.length - 1] ?? consumerPath;
324
- console.error(`[bkit-harvest] no git remote at ${consumerPath} — falling back to path-derived slug "${fallback}". ` +
325
- `This is NOT an owner/repo slug and will not join rows from the same repo harvested elsewhere.`);
326
- return fallback;
327
- }
328
- // harvest — cross-repo harvest CLI.
329
- // Copies consumer .bkit/stats.jsonl and MOVES .bkit/friction.jsonl into harvest/;
330
- // COUNT-ONLY for docs/{deferrals,failures}.jsonl. Friction rows are pruned from the
331
- // consumer only after they are fsync'd + read back from the store. Fail-open: exits 0.
332
- // See DE-34 for the shared-entrypoint + crash-isolation contract.
333
- export function runHarvestCommand() {
334
- try {
335
- const cwd = process.cwd();
336
- console.log("[bkit-harvest] Starting cross-repo harvest...");
337
- const result = runHarvest(cwd);
338
- console.log(`[bkit-harvest] Harvest complete — consumers: ${result.consumers.length}, rows copied: ${result.totalCopiedRows}, entities after fold: ${result.dedupedRows}, pruned from consumers: ${result.totalPrunedRows}`);
339
- const countOnlyEntries = Object.entries(result.totalCountOnly);
340
- if (countOnlyEntries.length > 0) {
341
- for (const [file, count] of countOnlyEntries) {
342
- console.log(`[bkit-harvest] count-only ${file}: ${count} rows (not copied)`);
343
- }
344
- }
345
- if (result.totalPrunedRows > 0) {
346
- console.log(`[bkit-harvest] ${result.totalPrunedRows} friction row(s) were REMOVED from consumers and now exist only in ${HARVEST_DEST_DIR}/ — commit it.`);
347
- }
348
- }
349
- catch (err) {
350
- const msg = err instanceof Error ? err.message : String(err);
351
- console.error(`[bkit-harvest] harvest error (fail-open): ${msg}`);
352
- }
353
- }