@cbartens/bkit 0.0.0-stage → 5.0.1

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 (375) hide show
  1. package/.bkit/README.md +417 -0
  2. package/.bkit/core/.agents/context.md +95 -0
  3. package/.bkit/core/.agents/docs.md +62 -0
  4. package/.bkit/core/.agents/rules.md +147 -0
  5. package/.bkit/core/.agents/skills.md +43 -0
  6. package/.bkit/core/.bkit/LICENSE.md +151 -0
  7. package/.bkit/core/.bkit/README.md +417 -0
  8. package/.bkit/core/.bkit/cloud.md +493 -0
  9. package/.bkit/core/.bkit/comparison.md +321 -0
  10. package/.bkit/core/.bkit/install.md +401 -0
  11. package/.bkit/core/.bkit/jsonl.md +497 -0
  12. package/.bkit/core/.bkit/prompts.md +474 -0
  13. package/.bkit/core/.bkit/providers.md +598 -0
  14. package/.bkit/core/.bkit/templates.md +470 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1550 -0
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
  22. package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
  24. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
  26. package/.bkit/core/AGENTS.md +77 -0
  27. package/.bkit/core/LICENSE.md +149 -0
  28. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
  29. package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
  30. package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
  31. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
  32. package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
  33. package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
  34. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
  35. package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
  36. package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
  37. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
  38. package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
  39. package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
  40. package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
  41. package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
  42. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
  43. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
  44. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
  45. package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
  46. package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
  47. package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
  48. package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
  49. package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
  50. package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
  51. package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
  52. package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
  53. package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
  54. package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
  55. package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
  56. package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
  57. package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
  58. package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
  59. package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
  60. package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
  61. package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
  62. package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
  63. package/.bkit/core/docs/templates/bkit-plan.md +476 -0
  64. package/.bkit/core/engine/checks/after/auth.ts +149 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +701 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +530 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/suppression.ts +53 -0
  70. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +187 -0
  73. package/.bkit/core/engine/checks/before/files.ts +204 -0
  74. package/.bkit/core/engine/checks/before/index.ts +206 -0
  75. package/.bkit/core/engine/checks/before/mcp.ts +127 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +77 -0
  77. package/.bkit/core/engine/checks/before/version.ts +67 -0
  78. package/.bkit/core/engine/checks/status-holes.ts +479 -0
  79. package/.bkit/core/engine/cli.ts +867 -0
  80. package/.bkit/core/engine/commands/analysis.ts +550 -0
  81. package/.bkit/core/engine/commands/ci/ci.ts +483 -0
  82. package/.bkit/core/engine/commands/comply.ts +415 -0
  83. package/.bkit/core/engine/commands/harvest.ts +459 -0
  84. package/.bkit/core/engine/commands/install/check.ts +70 -0
  85. package/.bkit/core/engine/commands/install/doctor.ts +254 -0
  86. package/.bkit/core/engine/commands/install/install.ts +550 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +995 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1037 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +495 -0
  91. package/.bkit/core/engine/commands/registry.ts +53 -0
  92. package/.bkit/core/engine/commands/setup/setup.ts +184 -0
  93. package/.bkit/core/engine/commands/telemetry.ts +32 -0
  94. package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
  95. package/.bkit/core/engine/commands/workflow/context.ts +961 -0
  96. package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
  97. package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
  98. package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
  99. package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
  100. package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
  101. package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
  102. package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
  103. package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
  104. package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
  105. package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
  106. package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
  107. package/.bkit/core/engine/commands/workflow/status.ts +455 -0
  108. package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
  109. package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
  110. package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
  111. package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
  112. package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
  113. package/.bkit/core/engine/install/cloud-env.ts +924 -0
  114. package/.bkit/core/engine/install/managed-block.ts +212 -0
  115. package/.bkit/core/engine/install/manifest.ts +448 -0
  116. package/.bkit/core/engine/install/modules/claude.ts +362 -0
  117. package/.bkit/core/engine/install/modules/cloud.ts +173 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +620 -0
  120. package/.bkit/core/engine/install/modules/cursor.ts +231 -0
  121. package/.bkit/core/engine/install/modules/index.ts +242 -0
  122. package/.bkit/core/engine/install/modules/opencode.ts +573 -0
  123. package/.bkit/core/engine/install/payload-links.ts +150 -0
  124. package/.bkit/core/engine/install/placeholders.ts +108 -0
  125. package/.bkit/core/engine/install/template-copies.ts +119 -0
  126. package/.bkit/core/engine/install/version-file.ts +284 -0
  127. package/.bkit/core/engine/install/write.ts +467 -0
  128. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  129. package/.bkit/core/engine/ledgers/status.ts +213 -0
  130. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  131. package/.bkit/core/engine/render/hosts.ts +372 -0
  132. package/.bkit/core/engine/render/models.ts +323 -0
  133. package/.bkit/core/engine/render/parts.ts +38 -0
  134. package/.bkit/core/engine/render/trackers.ts +170 -0
  135. package/.bkit/core/engine/shared/egress.ts +345 -0
  136. package/.bkit/core/engine/shared/json.ts +16 -0
  137. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  138. package/.bkit/core/engine/shared/package-json.ts +29 -0
  139. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  140. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  141. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  142. package/.bkit/core/engine/shared/settings.ts +72 -0
  143. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  144. package/.bkit/core/engine/tools/wording.ts +748 -0
  145. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  146. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  147. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  148. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  149. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  150. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  155. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  156. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  157. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  158. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  159. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  160. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  161. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  162. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  165. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  166. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  169. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  170. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  171. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  172. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  173. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  174. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  175. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  176. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  178. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  179. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  180. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  181. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  182. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  185. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  186. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  187. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  188. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  189. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  198. package/.bkit/core/workflows/bkit-auto.md +121 -0
  199. package/.bkit/core/workflows/bkit-build.md +802 -0
  200. package/.bkit/core/workflows/bkit-debug.md +649 -0
  201. package/.bkit/core/workflows/bkit-design.md +495 -0
  202. package/.bkit/core/workflows/bkit-plan.md +510 -0
  203. package/.bkit/core/workflows/bkit-ship.md +650 -0
  204. package/.bkit/shared/.bkit/.env.example +86 -0
  205. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  206. package/.bkit/shared/.claude/settings.json +88 -0
  207. package/.bkit/shared/.codex/hooks.json +26 -0
  208. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  209. package/.bkit/shared/.cursor/hooks.json +26 -0
  210. package/.bkit/shared/.cursor/mcp.json +15 -0
  211. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  212. package/.bkit/shared/.gitattributes +37 -0
  213. package/.bkit/shared/.mcp.json +16 -0
  214. package/.bkit/shared/.opencode/opencode.json +62 -0
  215. package/.bkit/shared/CLAUDE.md +11 -0
  216. package/.bkit/shared/LICENSE.md +22 -0
  217. package/.bkit/shared/docs/architecture.md +19 -0
  218. package/.bkit/shared/docs/data-schema.md +19 -0
  219. package/.bkit/shared/docs/deployments.md +433 -0
  220. package/.bkit/shared/docs/design.md +39 -0
  221. package/.bkit/shared/docs/noise.md +19 -0
  222. package/.bkit/shared/docs/observability.md +25 -0
  223. package/.bkit/shared/docs/security.md +42 -0
  224. package/.bkit/shared/docs/setup.md +30 -0
  225. package/.bkit/shared/docs/technology.md +18 -0
  226. package/.bkit/shared/docs/testing.md +413 -0
  227. package/.bkit/shared/gitignore +97 -0
  228. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +187 -0
  229. package/.bkit/templates/.cursor/Dockerfile +68 -0
  230. package/.bkit/templates/.cursor/environment.json +6 -0
  231. package/.bkit/templates/.cursor/settings.json +11 -0
  232. package/.bkit/templates/.envrc +7 -0
  233. package/.bkit/templates/.github/dependabot.yml +52 -0
  234. package/.bkit/templates/.github/renovate.json5 +224 -0
  235. package/.bkit/templates/.github/workflows/bkit-ci.yml +1062 -0
  236. package/.bkit/templates/.github/workflows/bkit-cloud.yml +564 -0
  237. package/.bkit/templates/.github/workflows/bkit-renovate.yml +102 -0
  238. package/.bkit/templates/.graphifyignore +108 -0
  239. package/.bkit/templates/.husky/pre-commit +16 -0
  240. package/.bkit/templates/.husky/pre-push +91 -0
  241. package/.bkit/templates/.lintstagedrc.json +3 -0
  242. package/.bkit/templates/.prettierignore +41 -0
  243. package/.bkit/templates/.serena/project.yml +243 -0
  244. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  245. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  246. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  247. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  248. package/.bkit/templates/.vale.ini +67 -0
  249. package/.bkit/templates/LICENSE.md +22 -0
  250. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  251. package/.bkit/templates/context/bkit-expo.md +186 -0
  252. package/.bkit/templates/context/bkit-github.md +79 -0
  253. package/.bkit/templates/context/bkit-inngest.md +45 -0
  254. package/.bkit/templates/context/bkit-maestro.md +76 -0
  255. package/.bkit/templates/context/bkit-playwright.md +62 -0
  256. package/.bkit/templates/context/bkit-resend.md +36 -0
  257. package/.bkit/templates/context/bkit-sentry.md +65 -0
  258. package/.bkit/templates/context/bkit-serena.md +33 -0
  259. package/.bkit/templates/context/bkit-stripe.md +36 -0
  260. package/.bkit/templates/context/bkit-supabase.md +59 -0
  261. package/.bkit/templates/context/bkit-tavily.md +49 -0
  262. package/.bkit/templates/context/bkit-vercel.md +64 -0
  263. package/.bkit/templates/docs/capabilities.md +72 -0
  264. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  266. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  268. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  280. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  281. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  282. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  283. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  284. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  286. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  288. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  289. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  290. package/.bkit/templates/slop-scan.config.json +120 -0
  291. package/CHANGELOG.md +1503 -0
  292. package/LICENSE.md +161 -0
  293. package/README.md +184 -2
  294. package/dist/checks/after/auth.js +140 -0
  295. package/dist/checks/after/ci-yml.js +681 -0
  296. package/dist/checks/after/github.js +400 -0
  297. package/dist/checks/after/index.js +431 -0
  298. package/dist/checks/after/managed.js +187 -0
  299. package/dist/checks/after/suppression.js +39 -0
  300. package/dist/checks/after/tools.js +351 -0
  301. package/dist/checks/before/context-fetch.js +426 -0
  302. package/dist/checks/before/env.js +163 -0
  303. package/dist/checks/before/files.js +187 -0
  304. package/dist/checks/before/index.js +162 -0
  305. package/dist/checks/before/mcp.js +111 -0
  306. package/dist/checks/before/repo.js +71 -0
  307. package/dist/checks/before/version.js +60 -0
  308. package/dist/checks/status-holes.js +393 -0
  309. package/dist/cli.js +688 -0
  310. package/dist/commands/analysis.js +325 -0
  311. package/dist/commands/ci/ci.js +438 -0
  312. package/dist/commands/comply.js +310 -0
  313. package/dist/commands/harvest.js +354 -0
  314. package/dist/commands/install/check.js +61 -0
  315. package/dist/commands/install/doctor.js +209 -0
  316. package/dist/commands/install/install.js +475 -0
  317. package/dist/commands/install/uninstall.js +839 -0
  318. package/dist/commands/install/upgrade.js +782 -0
  319. package/dist/commands/launch.js +118 -0
  320. package/dist/commands/lib.js +363 -0
  321. package/dist/commands/registry.js +50 -0
  322. package/dist/commands/setup/setup.js +158 -0
  323. package/dist/commands/telemetry.js +29 -0
  324. package/dist/commands/workflow/branches.js +1265 -0
  325. package/dist/commands/workflow/context.js +846 -0
  326. package/dist/commands/workflow/counters.js +227 -0
  327. package/dist/commands/workflow/fids.js +224 -0
  328. package/dist/commands/workflow/issues.js +585 -0
  329. package/dist/commands/workflow/ledgers.js +472 -0
  330. package/dist/commands/workflow/locks.js +364 -0
  331. package/dist/commands/workflow/prs.js +904 -0
  332. package/dist/commands/workflow/repo.js +199 -0
  333. package/dist/commands/workflow/roadmap.js +495 -0
  334. package/dist/commands/workflow/runs.js +1717 -0
  335. package/dist/commands/workflow/runtime.js +257 -0
  336. package/dist/commands/workflow/skills.js +110 -0
  337. package/dist/commands/workflow/status.js +392 -0
  338. package/dist/commands/workflow/steps.js +1093 -0
  339. package/dist/commands/workflow/tests.js +144 -0
  340. package/dist/commands/workflow/workflows.js +1342 -0
  341. package/dist/commands/workflow/workstreams.js +141 -0
  342. package/dist/commands/workflow/worktrees.js +473 -0
  343. package/dist/install/cloud-env.js +818 -0
  344. package/dist/install/managed-block.js +182 -0
  345. package/dist/install/manifest.js +376 -0
  346. package/dist/install/modules/claude.js +288 -0
  347. package/dist/install/modules/cloud.js +151 -0
  348. package/dist/install/modules/codex.js +193 -0
  349. package/dist/install/modules/core.js +531 -0
  350. package/dist/install/modules/cursor.js +186 -0
  351. package/dist/install/modules/index.js +152 -0
  352. package/dist/install/modules/opencode.js +504 -0
  353. package/dist/install/payload-links.js +119 -0
  354. package/dist/install/placeholders.js +87 -0
  355. package/dist/install/template-copies.js +106 -0
  356. package/dist/install/version-file.js +204 -0
  357. package/dist/install/write.js +342 -0
  358. package/dist/ledgers/clamp-log.js +27 -0
  359. package/dist/ledgers/status.js +156 -0
  360. package/dist/ledgers/telemetry.js +637 -0
  361. package/dist/render/hosts.js +339 -0
  362. package/dist/render/models.js +288 -0
  363. package/dist/render/parts.js +33 -0
  364. package/dist/render/trackers.js +135 -0
  365. package/dist/shared/egress.js +299 -0
  366. package/dist/shared/json.js +16 -0
  367. package/dist/shared/log-prefix.js +7 -0
  368. package/dist/shared/package-json.js +22 -0
  369. package/dist/shared/package-manager.js +32 -0
  370. package/dist/shared/package-roots.js +145 -0
  371. package/dist/shared/protected-paths.js +153 -0
  372. package/dist/shared/settings.js +44 -0
  373. package/dist/shared/timeouts.js +19 -0
  374. package/dist/tools/wording.js +680 -0
  375. package/package.json +101 -4
@@ -0,0 +1,150 @@
1
+ // install/payload-links.ts — the consumer's `.bkit/core` and `.bkit/shared` view
2
+ // links: relative symlinks into the installed package payload (#525), so the
3
+ // workflow / prompt / hook sources are browsable from the consumer repo without
4
+ // copying. Views, not copies — always the installed version, never hashed.
5
+
6
+ import * as fs from "node:fs";
7
+ import * as path from "node:path";
8
+ import { getCoreRoot, getPkgRoot, getSharedRoot } from "../shared/package-roots.js";
9
+ import type { WriteSet } from "./write.js";
10
+
11
+ // The two view links: a symlink at the consumer-relative `relPath` pointing at the
12
+ // package payload dir `target()` resolves to. Relative targets, so the link keeps
13
+ // working when the repo moves; both dangle on a fresh clone or in CI (no
14
+ // node_modules), which is why the managed `.gitignore` block carries both paths
15
+ // and checks/before/files.ts BKIT_GITIGNORE_LINES lists them.
16
+ export const PAYLOAD_LINKS: ReadonlyArray<{ relPath: string; target: () => string }> = [
17
+ { relPath: path.join(".bkit", "core"), target: getCoreRoot },
18
+ { relPath: path.join(".bkit", "shared"), target: getSharedRoot },
19
+ ];
20
+
21
+ /** The consumer-relative paths above, as a lookup set (version-hash exclusion). */
22
+ export const PAYLOAD_LINK_RELPATHS: ReadonlySet<string> = new Set(
23
+ PAYLOAD_LINKS.map((l) => l.relPath),
24
+ );
25
+
26
+ /** What a sync did, per link path. */
27
+ export interface PayloadLinkChanges {
28
+ created: string[];
29
+ repaired: string[];
30
+ kept: string[];
31
+ /** Real directory or file at the link path — never clobbered; advisory-worthy. */
32
+ skippedRealDir: string[];
33
+ /** Platform refused the symlink (e.g. Windows without Developer Mode). Advisory, never fatal. */
34
+ failed: string[];
35
+ }
36
+
37
+ /**
38
+ * Create the view link at `linkAbs` pointing at `targetAbs`: a relative `dir`
39
+ * symlink first; where the platform refuses it (Windows without Developer Mode or
40
+ * elevation) fall back to an absolute `junction`, which needs no privilege.
41
+ * `symlinkFn` is injectable so the platform branch is testable off-Windows.
42
+ */
43
+ export function createPayloadLink(
44
+ targetAbs: string,
45
+ linkAbs: string,
46
+ symlinkFn: (target: string, link: string, type?: "dir" | "junction") => void = fs.symlinkSync,
47
+ ): "relative" | "junction" {
48
+ const relTarget = path.relative(path.dirname(linkAbs), targetAbs);
49
+ try {
50
+ symlinkFn(relTarget, linkAbs, "dir");
51
+ return "relative";
52
+ } catch {
53
+ symlinkFn(targetAbs, linkAbs, "junction");
54
+ return "junction";
55
+ }
56
+ }
57
+
58
+ // Create or refresh the consumer's `.bkit/core` + `.bkit/shared` view links into
59
+ // the package payload. Idempotent: a correct link is kept, a dangling or
60
+ // mis-pointed symlink is re-pointed, a real directory or file is NEVER clobbered
61
+ // (skippedRealDir) and a platform refusal is only recorded (failed). Every create
62
+ // or repair pushes a ws write in dry-run and live alike, so `bkit check` flags a
63
+ // missing or broken link as drift. No-op in dogfood: there `.bkit/core` IS the
64
+ // package source, never a view onto it.
65
+ export function syncPayloadLinks(
66
+ cwd: string,
67
+ opts: { dryRun: boolean; ws: WriteSet },
68
+ ): PayloadLinkChanges {
69
+ const changes: PayloadLinkChanges = {
70
+ created: [],
71
+ repaired: [],
72
+ kept: [],
73
+ skippedRealDir: [],
74
+ failed: [],
75
+ };
76
+ if (path.resolve(cwd) === getPkgRoot()) return changes;
77
+
78
+ for (const { relPath, target } of PAYLOAD_LINKS) {
79
+ const linkAbs = path.join(cwd, relPath);
80
+ const targetAbs = target();
81
+ if (!fs.existsSync(targetAbs)) {
82
+ changes.failed.push(relPath); // package payload missing — package corrupt?
83
+ continue;
84
+ }
85
+
86
+ // lstat, not stat: the symlink itself is what matters, never its target.
87
+ let st: fs.Stats | null = null;
88
+ try {
89
+ st = fs.lstatSync(linkAbs);
90
+ } catch {
91
+ st = null; // absent
92
+ }
93
+
94
+ if (st !== null && !st.isSymbolicLink()) {
95
+ changes.skippedRealDir.push(relPath); // consumer content — never clobber
96
+ continue;
97
+ }
98
+
99
+ if (st !== null) {
100
+ // A symlink: keep when it already resolves to the payload, re-point otherwise
101
+ // (dangling — realpathSync throws — or pointing somewhere else).
102
+ let resolves = false;
103
+ try {
104
+ resolves = fs.realpathSync(linkAbs) === fs.realpathSync(targetAbs);
105
+ } catch {
106
+ resolves = false;
107
+ }
108
+ if (resolves) {
109
+ changes.kept.push(relPath);
110
+ continue;
111
+ }
112
+ if (!opts.dryRun) fs.rmSync(linkAbs);
113
+ }
114
+
115
+ if (!opts.dryRun) {
116
+ fs.mkdirSync(path.dirname(linkAbs), { recursive: true });
117
+ try {
118
+ createPayloadLink(targetAbs, linkAbs);
119
+ } catch {
120
+ changes.failed.push(relPath);
121
+ continue;
122
+ }
123
+ }
124
+ (st !== null ? changes.repaired : changes.created).push(relPath);
125
+ opts.ws.writes.push({ path: relPath, action: "write" });
126
+ }
127
+ return changes;
128
+ }
129
+
130
+ // The upgrade report for a link sync: one line per created, repaired, skipped or
131
+ // failed link. Empty when every link was already correct.
132
+ export function formatPayloadLinkChanges(changes: PayloadLinkChanges): string {
133
+ const lines = [
134
+ ...changes.created.map((p) => ` linked: ${p}`),
135
+ ...changes.repaired.map((p) => ` repaired: ${p}`),
136
+ ...changes.skippedRealDir.map(
137
+ (p) =>
138
+ ` skipped: ${p} — a real directory or file, never overwritten; remove it yourself to get the view link`,
139
+ ),
140
+ ...changes.failed.map(
141
+ (p) =>
142
+ ` failed: ${p} — platform refused the symlink (browse-only; bkit reads its payload from the package regardless)`,
143
+ ),
144
+ ];
145
+ if (lines.length === 0) return "";
146
+ return [
147
+ "Payload view links — `.bkit/core` + `.bkit/shared` point into the installed package (gitignored, browse-only):",
148
+ ...lines,
149
+ ].join("\n");
150
+ }
@@ -0,0 +1,108 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { execSync } from "node:child_process";
4
+ import { getPkgRoot } from "../shared/package-roots.js";
5
+ import { managedVersionMarker } from "./version-file.js";
6
+ import { gitEnv, resolveRepoSlug } from "../ledgers/telemetry.js";
7
+
8
+ export interface TokenMap {
9
+ DEFAULT_BRANCH: string;
10
+ PROJECT_NAME: string;
11
+ // `owner/repo` slug parsed from the `origin` remote, substituted for
12
+ // `{{REPO_SLUG}}`. Empty string when origin is absent/unparseable.
13
+ REPO_SLUG: string;
14
+ // INSTALLING bkit version, stamped by the `{{BKIT_MANAGED_MARKER}}` token. Optional
15
+ // so the many TokenMap literals (tests, the resolveTokens-failure fallback) need
16
+ // not set it — applyTokens reads the package version on demand when the token is
17
+ // present.
18
+ BKIT_VERSION?: string;
19
+ }
20
+
21
+ // Read the INSTALLING bkit version from the package root (NOT the consumer's
22
+ // package.json — that is a different version). Mirrors readInstallingVersion
23
+ // (install/modules/index.ts) / readPkgVersion (checks/after/index.ts); kept local to avoid a
24
+ // tokens → modules import cycle. "0.0.0" on any read failure.
25
+ function readInstallingBkitVersion(): string {
26
+ try {
27
+ const pkg = JSON.parse(fs.readFileSync(path.join(getPkgRoot(), "package.json"), "utf-8")) as {
28
+ version?: string;
29
+ };
30
+ return pkg.version ?? "0.0.0";
31
+ } catch {
32
+ return "0.0.0";
33
+ }
34
+ }
35
+
36
+ // Resolve DEFAULT_BRANCH: git symbolic-ref refs/remotes/origin/HEAD → "main"
37
+ function resolveDefaultBranch(cwd: string): string {
38
+ try {
39
+ const raw = execSync("git symbolic-ref refs/remotes/origin/HEAD", {
40
+ cwd,
41
+ encoding: "utf-8",
42
+ stdio: ["ignore", "pipe", "ignore"],
43
+ env: gitEnv(),
44
+ }).trim();
45
+ // raw is like "refs/remotes/origin/main"
46
+ const parts = raw.split("/");
47
+ const branch = parts[parts.length - 1];
48
+ if (branch) return branch;
49
+ } catch {
50
+ // not a git repo or no remote HEAD configured — fall back
51
+ }
52
+ return "main";
53
+ }
54
+
55
+ // Read and parse package.json from cwd. Throws if absent.
56
+ function readPackageJson(cwd: string): Record<string, unknown> {
57
+ const pkgPath = path.join(cwd, "package.json");
58
+ if (!fs.existsSync(pkgPath)) {
59
+ throw new Error(`[bkit-placeholders] package.json not found at ${pkgPath}`);
60
+ }
61
+ const raw = fs.readFileSync(pkgPath, "utf-8");
62
+ return JSON.parse(raw) as Record<string, unknown>;
63
+ }
64
+
65
+ // Resolve all tokens in a single read-once pass at install-start.
66
+ // Hard-fails (throws) if package.json.name is absent.
67
+ export async function resolveTokens(cwd: string): Promise<TokenMap> {
68
+ const pkg = readPackageJson(cwd);
69
+
70
+ const name = pkg["name"];
71
+ if (typeof name !== "string" || name.trim() === "") {
72
+ throw new Error(
73
+ `[bkit-placeholders] package.json.name is required but missing or empty in ${cwd}`,
74
+ );
75
+ }
76
+
77
+ return {
78
+ DEFAULT_BRANCH: resolveDefaultBranch(cwd),
79
+ PROJECT_NAME: name.trim(),
80
+ REPO_SLUG: resolveRepoSlug(cwd),
81
+ BKIT_VERSION: readInstallingBkitVersion(),
82
+ };
83
+ }
84
+
85
+ // Substitute {{TOKEN}} placeholders in content string.
86
+ // Substitution happens at write-time (caller's responsibility), not at template-read time.
87
+ // Uses function-form replacers to prevent $& / $1 / $$ substitution patterns from leaking
88
+ // through when token values contain dollar signs.
89
+ export function applyTokens(content: string, tokens: TokenMap): string {
90
+ const defaultBranch = tokens.DEFAULT_BRANCH;
91
+ const projectName = tokens.PROJECT_NAME;
92
+ const repoSlug = tokens.REPO_SLUG;
93
+ let out = content
94
+ .replace(/\{\{DEFAULT_BRANCH\}\}/g, () => defaultBranch)
95
+ .replace(/\{\{PROJECT_NAME\}\}/g, () => projectName)
96
+ .replace(/\{\{REPO_SLUG\}\}/g, () => repoSlug);
97
+ // {{BKIT_MANAGED_MARKER}} → the managed-version marker. A token after `// ` at a line
98
+ // start resolves to the slash form (JS); every other occurrence to the HTML comment,
99
+ // so `# {{BKIT_MANAGED_MARKER}}` yields the hash form. The version is read from the
100
+ // package only when the token is present and the TokenMap omits BKIT_VERSION.
101
+ if (out.includes("{{BKIT_MANAGED_MARKER}}")) {
102
+ const version = tokens.BKIT_VERSION ?? readInstallingBkitVersion();
103
+ out = out
104
+ .replace(/^\/\/ \{\{BKIT_MANAGED_MARKER\}\}/gm, () => managedVersionMarker(version, "slash"))
105
+ .replace(/\{\{BKIT_MANAGED_MARKER\}\}/g, () => managedVersionMarker(version));
106
+ }
107
+ return out;
108
+ }
@@ -0,0 +1,119 @@
1
+ // install/template-copies.ts — the consumer's `.bkit/templates/` copies: the sync that
2
+ // refreshes them, and the dotfile remap they share with the install/upgrade walk.
3
+
4
+ import * as fs from "node:fs";
5
+ import * as path from "node:path";
6
+ import {
7
+ NPM_STRIP_REMAP,
8
+ getPkgRoot,
9
+ getTemplatesRoot,
10
+ TEMPLATE_COPIES_DIR,
11
+ } from "../shared/package-roots.js";
12
+ import type { WriteSet } from "./write.js";
13
+
14
+ export function listFilesRecursive(dir: string): string[] {
15
+ if (!fs.existsSync(dir)) return [];
16
+ const out: string[] = [];
17
+ for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
18
+ const p = path.join(dir, ent.name);
19
+ if (ent.isDirectory()) out.push(...listFilesRecursive(p));
20
+ else if (ent.isFile()) out.push(p);
21
+ }
22
+ return out;
23
+ }
24
+
25
+ // The dotfile remap: the one table lives in shared/package-roots.ts (NPM_STRIP_REMAP); the
26
+ // module install pass (install/modules/index.ts) and the `bkit upgrade` template walk both
27
+ // call this, so they never disagree about how a payload basename maps to its dest.
28
+ export function remapTemplateDest(rel: string): string {
29
+ const dir = path.dirname(rel);
30
+ const base = path.basename(rel);
31
+ const mapped = NPM_STRIP_REMAP[base];
32
+ if (mapped === undefined) return rel;
33
+ return dir === "." ? mapped : path.join(dir, mapped);
34
+ }
35
+
36
+ /** Template paths (relative to `.bkit/templates/`) a sync changed, added or removed. */
37
+ export interface TemplateCopyChanges {
38
+ changed: string[];
39
+ added: string[];
40
+ removed: string[];
41
+ }
42
+
43
+ // Copy the whole templates root from the package into the consumer's
44
+ // `.bkit/templates/`, raw: no token substitution, so the copy is the package bytes and
45
+ // `git diff .bkit/templates` on an upgrade commit is the template changelog. Byte-compares
46
+ // first, keeps the source mode (hooks and scripts are executable), and prunes copies that
47
+ // left the set. Every change pushes a ws write in dry-run and live alike, so `bkit check`
48
+ // flags a stale copy. No-op in dogfood: there the folder IS the package's template source.
49
+ export function syncTemplateCopies(
50
+ cwd: string,
51
+ opts: { dryRun: boolean; ws: WriteSet },
52
+ ): TemplateCopyChanges {
53
+ const changes: TemplateCopyChanges = { changed: [], added: [], removed: [] };
54
+ if (path.resolve(cwd) === getPkgRoot()) return changes;
55
+ const srcRoot = getTemplatesRoot();
56
+ const dstRoot = path.join(cwd, TEMPLATE_COPIES_DIR);
57
+
58
+ const shipped = new Set<string>();
59
+ for (const srcPath of listFilesRecursive(srcRoot)) {
60
+ const rel = path.relative(srcRoot, srcPath);
61
+ shipped.add(rel);
62
+ const dstPath = path.join(dstRoot, rel);
63
+ const exists = fs.existsSync(dstPath);
64
+ if (exists && fs.readFileSync(srcPath).equals(fs.readFileSync(dstPath))) continue;
65
+ (exists ? changes.changed : changes.added).push(rel);
66
+ if (!opts.dryRun) {
67
+ fs.mkdirSync(path.dirname(dstPath), { recursive: true });
68
+ fs.copyFileSync(srcPath, dstPath);
69
+ fs.chmodSync(dstPath, fs.statSync(srcPath).mode);
70
+ }
71
+ opts.ws.writes.push({
72
+ path: path.join(TEMPLATE_COPIES_DIR, rel),
73
+ action: exists ? "update" : "write",
74
+ });
75
+ }
76
+
77
+ for (const dstPath of listFilesRecursive(dstRoot)) {
78
+ const rel = path.relative(dstRoot, dstPath);
79
+ if (shipped.has(rel)) continue;
80
+ changes.removed.push(rel);
81
+ if (!opts.dryRun) fs.rmSync(dstPath);
82
+ opts.ws.writes.push({ path: path.join(TEMPLATE_COPIES_DIR, rel), action: "update" });
83
+ }
84
+ if (!opts.dryRun) pruneEmptyDirs(dstRoot);
85
+ return changes;
86
+ }
87
+
88
+ // Remove empty folders under `root`, deepest first. `root` itself stays.
89
+ function pruneEmptyDirs(root: string): void {
90
+ if (!fs.existsSync(root)) return;
91
+ for (const ent of fs.readdirSync(root, { withFileTypes: true })) {
92
+ if (!ent.isDirectory()) continue;
93
+ const dir = path.join(root, ent.name);
94
+ pruneEmptyDirs(dir);
95
+ if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
96
+ }
97
+ }
98
+
99
+ /** One-line pointer to the template docs, shared by the install and upgrade messages. */
100
+ export const TEMPLATES_POINTER =
101
+ "Templates (adopt, do not skip): read .bkit/templates.md; bkit never applies templates, so adopt each copy in .bkit/templates/ unless adoption would break existing functionality — state which you did not adopt and why. (If your own gates scan the repo, ignore .bkit/templates/.)";
102
+
103
+ /**
104
+ * The upgrade report for a template sync: one line per changed, added or removed
105
+ * template, then where to read about adopting them. Empty when nothing changed.
106
+ */
107
+ export function formatTemplateChanges(changes: TemplateCopyChanges): string {
108
+ const lines = [
109
+ ...changes.changed.map((p) => ` changed: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
110
+ ...changes.added.map((p) => ` added: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
111
+ ...changes.removed.map((p) => ` removed: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
112
+ ];
113
+ if (lines.length === 0) return "";
114
+ return [
115
+ `Templates updated (${lines.length}). bkit never applies these; diff them against your own copies and adopt what you want:`,
116
+ ...lines,
117
+ TEMPLATES_POINTER,
118
+ ].join("\n");
119
+ }
@@ -0,0 +1,284 @@
1
+ // install/version-file.ts — Schema for .bkit/version.
2
+ //
3
+ // Shape: JSON { pinnedVersion, canonicalHashes, claudeAllowDerived }. Content that is
4
+ // empty or not a JSON object reads as absent (null).
5
+ //
6
+ // `canonicalHashes`: map of consumer-relative path → sha256 hex of the file
7
+ // content bkit wrote. Used by `bkit upgrade` to detect consumer drift and by
8
+ // `bkit uninstall` to delete an owned file only when it is unchanged since bkit
9
+ // wrote it. Absent means "unknown" → treat as consumer-modified (preserve).
10
+ //
11
+ // Security note: sha256 used for content identity only, not cryptographic
12
+ // authentication. No secrets are stored here.
13
+
14
+ import * as fs from "node:fs";
15
+ import * as path from "node:path";
16
+ import * as crypto from "node:crypto";
17
+ import { parseJson } from "../shared/json.js";
18
+ import { getTemplatesRoot, templateRelPath } from "../shared/package-roots.js";
19
+
20
+ // ---------------------------------------------------------------------------
21
+ // Schema types
22
+ // ---------------------------------------------------------------------------
23
+
24
+ export interface BkitVersion {
25
+ /** Semver string of the installed bkit version, e.g. "0.7.0". */
26
+ pinnedVersion: string;
27
+ /**
28
+ * sha256 hex digests of ALL bkit-canonical managed files at install time.
29
+ *
30
+ * Key: consumer-relative path (e.g. ".claude/agents/bkit-foo.md")
31
+ * Value: sha256 hex of the bkit-written file content at install time.
32
+ *
33
+ * Used by `bkit upgrade` diff engine: if the current on-disk hash for a
34
+ * path differs from its canonicalHash, the consumer modified the file since
35
+ * install → do NOT silently overwrite during upgrade.
36
+ *
37
+ * Absent means "unknown": parses to {}, and every file reads as
38
+ * "consumer-modified" to the upgrade engine (no silent overwrites).
39
+ */
40
+ canonicalHashes: Record<string, string>;
41
+ /**
42
+ * The `permissions.allow` rows bkit itself derived and wrote into
43
+ * `.claude/settings.json` at install time (`WebFetch(domain:…)` from
44
+ * `allowed-domains`, `mcp__…` from `mcp-servers`) — the provenance record that lets
45
+ * a later run prune a row it added without touching one the consumer added by hand.
46
+ *
47
+ * Absent means "unknown" → defaults to `[]`, i.e. bkit claims authorship of nothing
48
+ * and prunes nothing. That is the conservative direction: the cost is a stale row
49
+ * surviving, never a consumer's own row being deleted.
50
+ */
51
+ claudeAllowDerived: string[];
52
+ }
53
+
54
+ // ---------------------------------------------------------------------------
55
+ // Parse
56
+ // ---------------------------------------------------------------------------
57
+
58
+ /**
59
+ * Parse `.bkit/version` content into a BkitVersion object. Returns null when the
60
+ * content is empty or is not a JSON object (treat as absent). A missing
61
+ * `canonicalHashes` reads as {} (every file "unknown" → no silent overwrites) and a
62
+ * missing `claudeAllowDerived` as [] (bkit prunes nothing).
63
+ */
64
+ export function parseBkitVersion(content: string): BkitVersion | null {
65
+ const trimmed = content.trim();
66
+ if (!trimmed.startsWith("{")) return null;
67
+ const json = parseJson(trimmed);
68
+ if (!json.ok || typeof json.value !== "object" || json.value === null) return null;
69
+ const parsed = json.value as Partial<BkitVersion>;
70
+ const pinnedVersion = typeof parsed.pinnedVersion === "string" ? parsed.pinnedVersion : "";
71
+ const hashes = parsed.canonicalHashes;
72
+ const canonicalHashes =
73
+ hashes && typeof hashes === "object" && !Array.isArray(hashes) ? { ...hashes } : {};
74
+ const claudeAllowDerived = Array.isArray(parsed.claudeAllowDerived)
75
+ ? parsed.claudeAllowDerived
76
+ : [];
77
+ return { pinnedVersion, canonicalHashes, claudeAllowDerived };
78
+ }
79
+
80
+ /**
81
+ * Read and parse `.bkit/version` from an absolute path.
82
+ * Returns null if the file is absent or content is empty.
83
+ */
84
+ export function readBkitVersion(versionFilePath: string): BkitVersion | null {
85
+ if (!fs.existsSync(versionFilePath)) return null;
86
+ const content = fs.readFileSync(versionFilePath, "utf-8");
87
+ return parseBkitVersion(content);
88
+ }
89
+
90
+ // ---------------------------------------------------------------------------
91
+ // Write — serialize to JSON
92
+ // ---------------------------------------------------------------------------
93
+
94
+ /**
95
+ * Serialize a BkitVersion to JSON for writing to `.bkit/version`.
96
+ * Always writes pretty-printed JSON with a trailing newline, schema fields only.
97
+ */
98
+ export function serializeBkitVersion(v: BkitVersion): string {
99
+ const { pinnedVersion, canonicalHashes, claudeAllowDerived } = v;
100
+ return JSON.stringify({ pinnedVersion, canonicalHashes, claudeAllowDerived }, null, 2) + "\n";
101
+ }
102
+
103
+ /**
104
+ * Write a BkitVersion to disk at `versionFilePath`.
105
+ */
106
+ export function writeBkitVersion(versionFilePath: string, v: BkitVersion): void {
107
+ fs.mkdirSync(path.dirname(versionFilePath), { recursive: true });
108
+ fs.writeFileSync(versionFilePath, serializeBkitVersion(v), "utf-8");
109
+ }
110
+
111
+ // ---------------------------------------------------------------------------
112
+ // canonicalHashes helpers (P4.T4)
113
+ // ---------------------------------------------------------------------------
114
+
115
+ /**
116
+ * Decide whether a managed file has been modified by the consumer since install.
117
+ *
118
+ * Returns true (treat as consumer-modified — block silent overwrite) when:
119
+ * - `canonicalHashes` has a recorded hash for `relPath` and the current on-disk
120
+ * content hash differs from it (true drift), OR
121
+ * - `canonicalHashes` has no entry for `relPath` (unknown hash state); upgrade then
122
+ * surfaces a conflict for the consumer to resolve.
123
+ *
124
+ * Returns false (no drift — safe to upgrade) only when:
125
+ * - The current on-disk content matches the recorded canonical hash, OR
126
+ * - The file is absent (nothing to compare).
127
+ *
128
+ * `relPath`: consumer-relative path (e.g. ".claude/agents/bkit-foo.md")
129
+ * `absolutePath`: absolute path to the file on disk
130
+ * `canonicalHashes`: the hashes map from the BkitVersion record
131
+ */
132
+ export function isConsumerModified(
133
+ relPath: string,
134
+ absolutePath: string,
135
+ canonicalHashes: Record<string, string>,
136
+ ): boolean {
137
+ const current = hashFile(absolutePath);
138
+ if (!current) return false; // absent → nothing to compare
139
+
140
+ const recorded = canonicalHashes[relPath];
141
+ if (!recorded) return true; // unknown → treat as modified to prevent silent overwrites
142
+
143
+ return current !== recorded;
144
+ }
145
+
146
+ /**
147
+ * The merge both writers share (install's postDispatch and
148
+ * `updateCanonicalHashesAfterUpgrade`): fresh entries overwrite, and entries whose
149
+ * path is no longer on disk — or that belong to the copy-and-own template set —
150
+ * are dropped.
151
+ *
152
+ * A recorded hash is only ever consulted for a file that exists — drift detection
153
+ * reads the file, uninstall deletes it — so an entry for an absent path is dead
154
+ * bookkeeping, and a file recreated at that path later would be misclassified as
155
+ * bkit-owned. A template-set path is never a file bkit owns: install copies it
156
+ * byte-for-byte into `.bkit/templates/` and never writes the consumer's own copy,
157
+ * so it must carry no ownership hash. Retired and renamed managed files leave such
158
+ * entries behind, and a pure merge would preserve them forever (the
159
+ * `.bkit/scripts/…` entry a #507 move left and the `scripts/graphify/**` +
160
+ * `scripts/serena/bkit-serena-mcp.sh` entries a #489 move left are the observed
161
+ * cases; the latter survive the absent-path prune because the adopted copy stays on
162
+ * disk).
163
+ *
164
+ * `pruned` counts the dropped entries so callers can treat a prune-only merge as a
165
+ * change that is still worth writing.
166
+ */
167
+ export function mergeCanonicalHashes(
168
+ cwd: string,
169
+ existing: Record<string, string>,
170
+ fresh: Record<string, string>,
171
+ ): { canonicalHashes: Record<string, string>; pruned: number } {
172
+ const canonicalHashes: Record<string, string> = {};
173
+ let pruned = 0;
174
+ for (const [relPath, hash] of Object.entries(existing)) {
175
+ if (!fs.existsSync(path.join(cwd, relPath)) || isTemplateSetPath(relPath)) {
176
+ pruned++;
177
+ continue;
178
+ }
179
+ canonicalHashes[relPath] = hash;
180
+ }
181
+ return { canonicalHashes: { ...canonicalHashes, ...fresh }, pruned };
182
+ }
183
+
184
+ /** True when `dest` is a member of the package's copy-and-own template set. */
185
+ function isTemplateSetPath(dest: string): boolean {
186
+ return fs.existsSync(path.join(getTemplatesRoot(), templateRelPath(dest)));
187
+ }
188
+
189
+ // ---------------------------------------------------------------------------
190
+ // sha256 — content hashing for canonicalHashes
191
+ // ---------------------------------------------------------------------------
192
+
193
+ /**
194
+ * Compute the sha256 hex digest of a string or Buffer.
195
+ * Used to record the content of the files bkit writes.
196
+ */
197
+ export function sha256(content: string | Buffer): string {
198
+ return crypto.createHash("sha256").update(content).digest("hex");
199
+ }
200
+
201
+ /**
202
+ * Read a file and return its sha256 hex digest. Returns null if absent.
203
+ */
204
+ export function hashFile(filePath: string): string | null {
205
+ if (!fs.existsSync(filePath)) return null;
206
+ const content = fs.readFileSync(filePath);
207
+ return sha256(content);
208
+ }
209
+
210
+ // ---------------------------------------------------------------------------
211
+ // Managed-version marker — single source of truth for the marker every file bkit
212
+ // writes or refreshes carries (JSON files excepted: JSON has no comments).
213
+ //
214
+ // One marker text, wrapped in the file's comment syntax:
215
+ // html `<!-- bkit:managed vX.Y.Z — … -->` markdown, `.mdc`
216
+ // hash `# <!-- bkit:managed vX.Y.Z — … -->` shell, `.gitignore`, `.env.example`, TOML
217
+ // slash `// bkit:managed vX.Y.Z — …` JS (`.cjs` / `.js` / `.mjs`)
218
+ //
219
+ // The marker names the licence the bkit-written files are under (PolyForm Noncommercial
220
+ // or Small Business, the pair `.bkit/LICENSE.md` carries in full) and the licences-index
221
+ // URL, so a copy passed on in a public repo carries the terms URL with it (PolyForm's
222
+ // Notices section). `.bkit/LICENSE.md` is written by runBkitDocs (install/modules/core.ts).
223
+ //
224
+ // Rendered agents / commands / skills are stamped at render (stampManagedVersion);
225
+ // every other file carries the `{{BKIT_MANAGED_MARKER}}` token in its source, which
226
+ // applyTokens (install/placeholders.ts) resolves to the form its comment prefix selects. The
227
+ // `bkit check` gate (detectManagedStale, checks/after/index.ts) reads the stamp back
228
+ // with readManagedVersion.
229
+ // ---------------------------------------------------------------------------
230
+
231
+ /** Comment syntax a managed-version marker is written in. */
232
+ export type ManagedMarkerForm = "html" | "hash" | "slash";
233
+
234
+ // Matches a stamped marker line in any form (anchored at a line start) including its
235
+ // trailing newline, so re-stamping replaces rather than appends (idempotent). Inline
236
+ // prose that quotes the marker never starts a line with it, so it never matches.
237
+ export const MANAGED_MARKER_LINE_RE = /^(?:<!-- |# <!-- |\/\/ )bkit:managed v[^\n]*\n?/m;
238
+ // Extracts the stamped version. `\S+` stops at the space before the em-dash.
239
+ export const MANAGED_MARKER_VERSION_RE = /bkit:managed v(\S+)/;
240
+
241
+ /** Build the managed-version marker for a given version, in the given comment syntax. */
242
+ export function managedVersionMarker(version: string, form: ManagedMarkerForm = "html"): string {
243
+ const text = `bkit:managed v${version} — PolyForm Noncommercial 1.0.0 / Small Business 1.0.0 (https://polyformproject.org/licenses/) — do not edit; run \`bkit upgrade\` to refresh`;
244
+ if (form === "slash") return `// ${text}`;
245
+ return form === "hash" ? `# <!-- ${text} -->` : `<!-- ${text} -->`;
246
+ }
247
+
248
+ /** Version of the first full-line managed-version marker in `content`, or null when none. */
249
+ export function readManagedVersion(content: string): string | null {
250
+ const line = content.match(MANAGED_MARKER_LINE_RE)?.[0];
251
+ return line?.match(MANAGED_MARKER_VERSION_RE)?.[1] ?? null;
252
+ }
253
+
254
+ /**
255
+ * Insert (or replace) the managed-version marker immediately after the rendered
256
+ * file's frontmatter fence, always followed by exactly one blank line. Idempotent:
257
+ * any existing marker is stripped first and leading body blanks are collapsed, so
258
+ * stamping the same content twice yields identical bytes. With no frontmatter (e.g.
259
+ * cursor/opencode commands whose transforms strip the frontmatter), the marker sinks
260
+ * below the content's first Markdown heading instead, so it never becomes the
261
+ * IDE-visible first line; falls back to a top prepend only when there is no heading
262
+ * either, also followed by a blank line.
263
+ */
264
+ export function stampManagedVersion(content: string, version: string): string {
265
+ const stripped = content.replace(MANAGED_MARKER_LINE_RE, "");
266
+ const marker = managedVersionMarker(version);
267
+ const fm = stripped.match(/^---\n[\s\S]*?\n---\n/);
268
+ if (fm) {
269
+ const cut = fm[0].length;
270
+ const body = stripped.slice(cut).replace(/^\n+/, "");
271
+ return stripped.slice(0, cut) + marker + "\n\n" + body;
272
+ }
273
+ // No frontmatter — the cursor/opencode command transforms remove it (applyT1 /
274
+ // applyOpencodeCommand). A marker on line 1 would be the IDE-visible command
275
+ // description, so it sinks below the first heading when there is one.
276
+ const heading = stripped.match(/^#{1,6} .*$/m);
277
+ if (heading?.index !== undefined) {
278
+ const cut = heading.index + heading[0].length;
279
+ const head = stripped.slice(0, cut);
280
+ const rest = stripped.slice(cut).replace(/^\n+/, "");
281
+ return rest ? `${head}\n\n${marker}\n\n${rest}` : `${head}\n\n${marker}\n`;
282
+ }
283
+ return marker + "\n\n" + stripped.replace(/^\n+/, "");
284
+ }