@cbartens/bkit 0.0.0-stage → 5.0.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 (373) hide show
  1. package/.bkit/README.md +421 -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 +421 -0
  8. package/.bkit/core/.bkit/cloud.md +502 -0
  9. package/.bkit/core/.bkit/comparison.md +318 -0
  10. package/.bkit/core/.bkit/install.md +496 -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 +471 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1546 -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 +247 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +739 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +556 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  70. package/.bkit/core/engine/checks/after/vercel.ts +101 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +201 -0
  73. package/.bkit/core/engine/checks/before/files.ts +202 -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 +871 -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 +247 -0
  86. package/.bkit/core/engine/commands/install/install.ts +528 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +972 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1026 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +494 -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 +925 -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 +174 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +600 -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/placeholders.ts +108 -0
  124. package/.bkit/core/engine/install/template-copies.ts +119 -0
  125. package/.bkit/core/engine/install/version-file.ts +284 -0
  126. package/.bkit/core/engine/install/write.ts +467 -0
  127. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  128. package/.bkit/core/engine/ledgers/status.ts +213 -0
  129. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  130. package/.bkit/core/engine/render/hosts.ts +372 -0
  131. package/.bkit/core/engine/render/models.ts +323 -0
  132. package/.bkit/core/engine/render/parts.ts +38 -0
  133. package/.bkit/core/engine/render/trackers.ts +170 -0
  134. package/.bkit/core/engine/shared/egress.ts +345 -0
  135. package/.bkit/core/engine/shared/json.ts +16 -0
  136. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  137. package/.bkit/core/engine/shared/package-json.ts +29 -0
  138. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  139. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  140. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  141. package/.bkit/core/engine/shared/settings.ts +72 -0
  142. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  143. package/.bkit/core/engine/tools/wording.ts +748 -0
  144. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  145. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  146. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  147. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  148. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  149. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  150. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  155. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  156. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  157. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  158. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  159. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  160. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  161. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  162. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  165. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  166. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  169. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  170. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  171. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  172. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  173. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  174. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  175. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  176. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  178. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  179. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  180. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  181. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  182. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  185. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  186. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  187. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  188. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  189. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  190. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  191. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  192. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  193. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  194. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  195. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  196. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  197. package/.bkit/core/workflows/bkit-auto.md +121 -0
  198. package/.bkit/core/workflows/bkit-build.md +802 -0
  199. package/.bkit/core/workflows/bkit-debug.md +642 -0
  200. package/.bkit/core/workflows/bkit-design.md +495 -0
  201. package/.bkit/core/workflows/bkit-plan.md +510 -0
  202. package/.bkit/core/workflows/bkit-ship.md +650 -0
  203. package/.bkit/shared/.bkit/.env.example +108 -0
  204. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  205. package/.bkit/shared/.claude/settings.json +88 -0
  206. package/.bkit/shared/.codex/hooks.json +26 -0
  207. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  208. package/.bkit/shared/.cursor/hooks.json +26 -0
  209. package/.bkit/shared/.cursor/mcp.json +15 -0
  210. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  211. package/.bkit/shared/.gitattributes +37 -0
  212. package/.bkit/shared/.mcp.json +16 -0
  213. package/.bkit/shared/.opencode/opencode.json +62 -0
  214. package/.bkit/shared/CLAUDE.md +11 -0
  215. package/.bkit/shared/LICENSE.md +22 -0
  216. package/.bkit/shared/docs/architecture.md +19 -0
  217. package/.bkit/shared/docs/data-schema.md +19 -0
  218. package/.bkit/shared/docs/deployments.md +438 -0
  219. package/.bkit/shared/docs/design.md +39 -0
  220. package/.bkit/shared/docs/noise.md +19 -0
  221. package/.bkit/shared/docs/observability.md +25 -0
  222. package/.bkit/shared/docs/security.md +42 -0
  223. package/.bkit/shared/docs/setup.md +30 -0
  224. package/.bkit/shared/docs/technology.md +18 -0
  225. package/.bkit/shared/docs/testing.md +413 -0
  226. package/.bkit/shared/gitignore +92 -0
  227. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +192 -0
  228. package/.bkit/templates/.cursor/Dockerfile +68 -0
  229. package/.bkit/templates/.cursor/environment.json +6 -0
  230. package/.bkit/templates/.cursor/settings.json +11 -0
  231. package/.bkit/templates/.envrc +7 -0
  232. package/.bkit/templates/.github/dependabot.yml +52 -0
  233. package/.bkit/templates/.github/renovate.json5 +239 -0
  234. package/.bkit/templates/.github/workflows/bkit-ci.yml +1082 -0
  235. package/.bkit/templates/.github/workflows/bkit-cloud.yml +566 -0
  236. package/.bkit/templates/.github/workflows/bkit-renovate.yml +107 -0
  237. package/.bkit/templates/.graphifyignore +108 -0
  238. package/.bkit/templates/.husky/pre-commit +16 -0
  239. package/.bkit/templates/.husky/pre-push +91 -0
  240. package/.bkit/templates/.lintstagedrc.json +3 -0
  241. package/.bkit/templates/.prettierignore +41 -0
  242. package/.bkit/templates/.serena/project.yml +243 -0
  243. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  244. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  245. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  246. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  247. package/.bkit/templates/.vale.ini +67 -0
  248. package/.bkit/templates/LICENSE.md +22 -0
  249. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  250. package/.bkit/templates/context/bkit-expo.md +186 -0
  251. package/.bkit/templates/context/bkit-github.md +79 -0
  252. package/.bkit/templates/context/bkit-inngest.md +45 -0
  253. package/.bkit/templates/context/bkit-maestro.md +76 -0
  254. package/.bkit/templates/context/bkit-playwright.md +62 -0
  255. package/.bkit/templates/context/bkit-resend.md +36 -0
  256. package/.bkit/templates/context/bkit-sentry.md +65 -0
  257. package/.bkit/templates/context/bkit-serena.md +33 -0
  258. package/.bkit/templates/context/bkit-stripe.md +36 -0
  259. package/.bkit/templates/context/bkit-supabase.md +59 -0
  260. package/.bkit/templates/context/bkit-tavily.md +49 -0
  261. package/.bkit/templates/context/bkit-vercel.md +64 -0
  262. package/.bkit/templates/docs/capabilities.md +72 -0
  263. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  264. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  266. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  268. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  280. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  281. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  282. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  283. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  284. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  286. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  288. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  289. package/.bkit/templates/slop-scan.config.json +120 -0
  290. package/CHANGELOG.md +1486 -0
  291. package/LICENSE.md +161 -0
  292. package/README.md +185 -2
  293. package/dist/checks/after/auth.js +232 -0
  294. package/dist/checks/after/ci-yml.js +718 -0
  295. package/dist/checks/after/github.js +400 -0
  296. package/dist/checks/after/index.js +447 -0
  297. package/dist/checks/after/managed.js +187 -0
  298. package/dist/checks/after/tools.js +351 -0
  299. package/dist/checks/after/vercel.js +102 -0
  300. package/dist/checks/before/context-fetch.js +426 -0
  301. package/dist/checks/before/env.js +173 -0
  302. package/dist/checks/before/files.js +185 -0
  303. package/dist/checks/before/index.js +162 -0
  304. package/dist/checks/before/mcp.js +111 -0
  305. package/dist/checks/before/repo.js +71 -0
  306. package/dist/checks/before/version.js +60 -0
  307. package/dist/checks/status-holes.js +393 -0
  308. package/dist/cli.js +692 -0
  309. package/dist/commands/analysis.js +325 -0
  310. package/dist/commands/ci/ci.js +438 -0
  311. package/dist/commands/comply.js +310 -0
  312. package/dist/commands/harvest.js +354 -0
  313. package/dist/commands/install/check.js +61 -0
  314. package/dist/commands/install/doctor.js +207 -0
  315. package/dist/commands/install/install.js +461 -0
  316. package/dist/commands/install/uninstall.js +815 -0
  317. package/dist/commands/install/upgrade.js +771 -0
  318. package/dist/commands/launch.js +118 -0
  319. package/dist/commands/lib.js +362 -0
  320. package/dist/commands/registry.js +50 -0
  321. package/dist/commands/setup/setup.js +158 -0
  322. package/dist/commands/telemetry.js +29 -0
  323. package/dist/commands/workflow/branches.js +1265 -0
  324. package/dist/commands/workflow/context.js +846 -0
  325. package/dist/commands/workflow/counters.js +227 -0
  326. package/dist/commands/workflow/fids.js +224 -0
  327. package/dist/commands/workflow/issues.js +585 -0
  328. package/dist/commands/workflow/ledgers.js +472 -0
  329. package/dist/commands/workflow/locks.js +364 -0
  330. package/dist/commands/workflow/prs.js +904 -0
  331. package/dist/commands/workflow/repo.js +199 -0
  332. package/dist/commands/workflow/roadmap.js +495 -0
  333. package/dist/commands/workflow/runs.js +1717 -0
  334. package/dist/commands/workflow/runtime.js +257 -0
  335. package/dist/commands/workflow/skills.js +110 -0
  336. package/dist/commands/workflow/status.js +392 -0
  337. package/dist/commands/workflow/steps.js +1093 -0
  338. package/dist/commands/workflow/tests.js +144 -0
  339. package/dist/commands/workflow/workflows.js +1342 -0
  340. package/dist/commands/workflow/workstreams.js +141 -0
  341. package/dist/commands/workflow/worktrees.js +473 -0
  342. package/dist/install/cloud-env.js +819 -0
  343. package/dist/install/managed-block.js +182 -0
  344. package/dist/install/manifest.js +376 -0
  345. package/dist/install/modules/claude.js +288 -0
  346. package/dist/install/modules/cloud.js +152 -0
  347. package/dist/install/modules/codex.js +193 -0
  348. package/dist/install/modules/core.js +511 -0
  349. package/dist/install/modules/cursor.js +186 -0
  350. package/dist/install/modules/index.js +152 -0
  351. package/dist/install/modules/opencode.js +504 -0
  352. package/dist/install/placeholders.js +87 -0
  353. package/dist/install/template-copies.js +106 -0
  354. package/dist/install/version-file.js +204 -0
  355. package/dist/install/write.js +342 -0
  356. package/dist/ledgers/clamp-log.js +27 -0
  357. package/dist/ledgers/status.js +156 -0
  358. package/dist/ledgers/telemetry.js +637 -0
  359. package/dist/render/hosts.js +339 -0
  360. package/dist/render/models.js +288 -0
  361. package/dist/render/parts.js +33 -0
  362. package/dist/render/trackers.js +135 -0
  363. package/dist/shared/egress.js +299 -0
  364. package/dist/shared/json.js +16 -0
  365. package/dist/shared/log-prefix.js +7 -0
  366. package/dist/shared/package-json.js +22 -0
  367. package/dist/shared/package-manager.js +32 -0
  368. package/dist/shared/package-roots.js +145 -0
  369. package/dist/shared/protected-paths.js +153 -0
  370. package/dist/shared/settings.js +44 -0
  371. package/dist/shared/timeouts.js +19 -0
  372. package/dist/tools/wording.js +680 -0
  373. package/package.json +101 -4
@@ -0,0 +1,426 @@
1
+ // checks/before/context-fetch.ts — the context-fetch blocks in `.agents/context.md`: present,
2
+ // covering each context, sources enabled, provision blocks in place.
3
+ import * as fs from "node:fs";
4
+ import * as path from "node:path";
5
+ import { getTemplatesRoot } from "../../shared/package-roots.js";
6
+ import { readPackageJson } from "../../shared/package-json.js";
7
+ /**
8
+ * Line-anchored consumer opt-out marker for the context-fetch advisories. A repo
9
+ * that legitimately enables no runtime-log source places this below
10
+ * `<!-- bkit:end -->` to dismiss both `context-fetch-missing` and
11
+ * `context-fetch-source-not-enabled`.
12
+ */
13
+ const CONTEXT_FETCH_NONE_RE = /^<!-- context-fetch:none(?: [^>]*)? -->$/m;
14
+ /**
15
+ * Every `context=` a `context-fetch` block may declare, in the order coverage is
16
+ * narrated. `runtime` is the default when the attribute is absent. The one list: the
17
+ * `bkit context` runner (commands/workflow/context.ts) and these advisories both read it.
18
+ */
19
+ export const CONTEXT_FETCH_CONTEXTS = ["runtime", "ci", "diff", "e2e", "web"];
20
+ /**
21
+ * Contexts whose absence means an entire class of failure evidence is never fetched,
22
+ * each with the evidence it carries.
23
+ *
24
+ * A subset of {@link CONTEXT_FETCH_CONTEXTS}: `web` is valid-but-not-required (its
25
+ * self-skip names the host's built-in web tools as the fallback). `runtime` is covered
26
+ * by `context-fetch-missing` instead.
27
+ */
28
+ const CONTEXT_FETCH_EVIDENCE_CONTEXTS = {
29
+ ci: "CI job/step failures and logs",
30
+ diff: "diff vs the last commit that passed CI",
31
+ e2e: "e2e reports / traces / device evidence",
32
+ };
33
+ /**
34
+ * Contexts named on a `<!-- context-fetch:none ... -->` marker, which dismisses the
35
+ * context-coverage advisory for those contexts ONLY — a repo with no e2e lane says
36
+ * so without also silencing the advisories that catch a genuinely unwired repo.
37
+ * A bare marker names none and keeps its whole-file meaning.
38
+ */
39
+ function contextFetchNoneContexts(consumer) {
40
+ const m = /^<!-- context-fetch:none((?: [\w.-]+)*) -->$/m.exec(consumer);
41
+ if (!m)
42
+ return new Set();
43
+ return new Set(m[1].split(/\s+/).filter((t) => CONTEXT_FETCH_CONTEXTS.includes(t)));
44
+ }
45
+ /**
46
+ * True ONLY for the blanket opt-out: a `context-fetch:none` marker naming no known
47
+ * context. A context-scoped marker (`context-fetch:none e2e`) dismisses that context's
48
+ * coverage advisory and nothing else — it must never silence the advisories that
49
+ * catch a repo with no blocks or an unenabled source.
50
+ */
51
+ function contextFetchDismissesAll(consumer) {
52
+ return CONTEXT_FETCH_NONE_RE.test(consumer) && contextFetchNoneContexts(consumer).size === 0;
53
+ }
54
+ /**
55
+ * Parse a `<!-- context-fetch:start [name] [context=<context>] -->` line. Attribute order
56
+ * is free and both parts are optional: a bare `context-fetch:start` is an unnamed
57
+ * `runtime` block. Runs of spaces and tabs separate tokens; the last name token wins.
58
+ * Returns `null` for non-matching lines. The one parser: the `bkit context` runner
59
+ * (commands/workflow/context.ts) and these advisories both read it.
60
+ */
61
+ export function parseContextFetchStart(line) {
62
+ const m = /^<!-- context-fetch:start((?:[ \t]+[\w.=-]+)*)[ \t]*-->$/.exec(line);
63
+ if (!m)
64
+ return null;
65
+ let name = "";
66
+ let context = "runtime";
67
+ for (const token of m[1].split(/[ \t]+/).filter(Boolean)) {
68
+ if (token.startsWith("context="))
69
+ context = token.slice("context=".length);
70
+ else
71
+ name = token;
72
+ }
73
+ return { name, context };
74
+ }
75
+ /** Every `context-fetch:start` block declared in a section, in document order. */
76
+ function parseContextFetchStarts(section) {
77
+ const out = [];
78
+ for (const line of section.split("\n")) {
79
+ const parsed = parseContextFetchStart(line);
80
+ if (parsed)
81
+ out.push(parsed);
82
+ }
83
+ return out;
84
+ }
85
+ /**
86
+ * Map of context-fetch source name -> predicate proving THIS repo actually runs
87
+ * that backend. Evidence-gates `context-fetch-source-not-enabled`
88
+ * so a single-backend consumer (e.g. Vercel-only) is never nagged about a
89
+ * backend it does not use (e.g. Supabase). A shipped template whose name has no
90
+ * entry here is never flagged (cannot prove use => stay quiet).
91
+ */
92
+ const CONTEXT_FETCH_BACKEND_EVIDENCE = {
93
+ supabase: (cwd) => fs.existsSync(path.join(cwd, "supabase", "config.toml")) ||
94
+ readDependencyNames(cwd).some((d) => d.startsWith("@supabase/")),
95
+ vercel: (cwd) => fs.existsSync(path.join(cwd, "vercel.json")) ||
96
+ fs.existsSync(path.join(cwd, ".vercel")) ||
97
+ readDependencyNames(cwd).includes("vercel"),
98
+ };
99
+ /** Every dependency name across the four package.json dependency fields. */
100
+ function readDependencyNames(cwd) {
101
+ const read = readPackageJson(cwd);
102
+ if (!read.ok)
103
+ return [];
104
+ const pkg = read.pkg;
105
+ const names = [];
106
+ for (const field of [
107
+ "dependencies",
108
+ "devDependencies",
109
+ "optionalDependencies",
110
+ "peerDependencies",
111
+ ]) {
112
+ const deps = pkg[field];
113
+ if (deps && typeof deps === "object") {
114
+ names.push(...Object.keys(deps));
115
+ }
116
+ }
117
+ return names;
118
+ }
119
+ /**
120
+ * Advisory: consumer's `.agents/context.md` has the bkit-managed block but no
121
+ * `<!-- context-fetch:start <name> --> ... <!-- context-fetch:end -->` block AFTER
122
+ * `<!-- bkit:end -->`.
123
+ *
124
+ * `/bkit-debug`'s runtime sub-fetch runs every `context-fetch` block occurring
125
+ * after `<!-- bkit:end -->` (consumer section). With no consumer-section block, no
126
+ * runtime-log artifact (`context-runtime-<name>-{ATTEMPT}.md`) is produced
127
+ * on any debug run. Ready-made blocks ship in `.bkit/templates/context/`.
128
+ *
129
+ * Markers may be named (`context-fetch:start vercel`) or unnamed. Only
130
+ * fires when the consumer has the bkit-managed block at all; consumers who fully
131
+ * own `.agents/context.md` (no markers) are not nagged. Dismissable with a
132
+ * `<!-- context-fetch:none ... -->` marker below `<!-- bkit:end -->`.
133
+ */
134
+ export function detectContextFetchMissing(cwd) {
135
+ const filePath = path.join(cwd, ".agents", "context.md");
136
+ if (!fs.existsSync(filePath))
137
+ return null;
138
+ const content = fs.readFileSync(filePath, "utf-8");
139
+ // Require the bkit-managed block (line-anchored `<!-- bkit:end -->`).
140
+ const endIdx = content.search(/^<!-- bkit:end -->$/m);
141
+ if (endIdx === -1)
142
+ return null;
143
+ const afterBkitEnd = content.slice(endIdx);
144
+ // Consumer opt-out: dismiss when a `<!-- context-fetch:none ... -->` marker is
145
+ // present below `<!-- bkit:end -->` (repo legitimately enables no source).
146
+ if (contextFetchDismissesAll(afterBkitEnd))
147
+ return null;
148
+ // Consumer-section markers must be line-anchored to mirror the workflow's
149
+ // `sed`/`awk` extraction (`.bkit/workflows/bkit-debug.md` Step 5). The start
150
+ // marker carries an optional block name (`context-fetch:start vercel`).
151
+ const hasStart = parseContextFetchStarts(afterBkitEnd).length > 0;
152
+ const hasEnd = /^<!-- context-fetch:end -->$/m.test(afterBkitEnd);
153
+ if (hasStart && hasEnd)
154
+ return null;
155
+ return {
156
+ id: "context-fetch-missing",
157
+ severity: "advisory",
158
+ detect: "`.agents/context.md` has the bkit-managed block but no `<!-- context-fetch:start [name] --> ... <!-- context-fetch:end -->` block after `<!-- bkit:end -->`. `/bkit-debug` runs every block in that consumer section — with none, no runtime-log artifact is produced.",
159
+ action: "Copy the blocks of a provider file in `.bkit/templates/context/` (e.g. `bkit-vercel.md`, `bkit-supabase.md`; index in `.bkit/templates.md` § Context-fetch blocks) and paste them after `<!-- bkit:end -->`, then set its env vars. REQUIRED: set the block's non-secret selector (e.g. `VERCEL_SCOPE` / `SUPABASE_PROJECT_ID`) by uncommenting the assignment line at the top of the copied block — committing it there is what makes the block run in headless cloud agents, which never read `.bkit/.env`. For cloud `/bkit-debug`, also set the secret tokens (`VERCEL_TOKEN` / `SUPABASE_ACCESS_TOKEN`) in your Claude/Cursor dashboard (or GitHub Actions secrets) and authenticate non-interactively (env tokens, never `vercel login`). Each block self-gates (missing CLI / token => a `[context-fetch:<name>] skipped — …` stderr breadcrumb, not an error), so enable only the sources you use; add your own block for any other log backend (`gcloud` / `aws` / `datadog`). Keep blocks read-only and idempotent — the agent customises severity / freshness / limit / target environment (e.g. Vercel preview vs production) at run-time.",
160
+ };
161
+ }
162
+ /**
163
+ * Advisory: the consumer section enables context-fetch blocks, but not for every
164
+ * evidence context — so `/bkit-debug` fetches an entire class of failure evidence
165
+ * for no run, ever.
166
+ *
167
+ * `/bkit-debug` Step 4 is fully block-driven: CI logs, the last-passing diff and
168
+ * e2e artifacts each come from a `context=`-tagged block, exactly as runtime logs
169
+ * do. bkit hardcodes no CI host, workflow filename, branch name or e2e framework.
170
+ *
171
+ * Distinct from `context-fetch-missing`, which owns the no-blocks-at-all case; this
172
+ * one only fires once at least one block exists. Dismissable per context —
173
+ * `<!-- context-fetch:none e2e -->` below `<!-- bkit:end -->`. A bare marker dismisses all.
174
+ */
175
+ export function detectContextFetchContextMissing(cwd) {
176
+ const filePath = path.join(cwd, ".agents", "context.md");
177
+ if (!fs.existsSync(filePath))
178
+ return null;
179
+ const content = fs.readFileSync(filePath, "utf-8");
180
+ const endIdx = content.search(/^<!-- bkit:end -->$/m);
181
+ if (endIdx === -1)
182
+ return null;
183
+ const consumer = content.slice(endIdx);
184
+ const enabled = parseContextFetchStarts(consumer);
185
+ // No blocks at all => `context-fetch-missing` owns it (no double-fire).
186
+ if (enabled.length === 0)
187
+ return null;
188
+ const dismissed = contextFetchNoneContexts(consumer);
189
+ // A bare `context-fetch:none` names no context and dismisses every advisory.
190
+ if (contextFetchDismissesAll(consumer))
191
+ return null;
192
+ const contexts = new Set(enabled.map((b) => b.context));
193
+ const missing = Object.keys(CONTEXT_FETCH_EVIDENCE_CONTEXTS).filter((r) => !contexts.has(r) && !dismissed.has(r));
194
+ if (missing.length === 0)
195
+ return null;
196
+ const list = missing
197
+ .map((r) => `\`context=${r}\` (${CONTEXT_FETCH_EVIDENCE_CONTEXTS[r]})`)
198
+ .join(", ");
199
+ const plural = missing.length > 1;
200
+ return {
201
+ id: "context-fetch-context-missing",
202
+ severity: "advisory",
203
+ detect: `\`.agents/context.md\` enables context-fetch blocks below \`<!-- bkit:end -->\` but none for ${list}. \`/bkit-debug\` fetches ALL failure evidence from these blocks — it hardcodes no CI host, workflow filename, branch name or e2e framework — so ${plural ? "those classes" : "that class"} of evidence ${plural ? "are" : "is"} never fetched on any debug run. Every attempt reports \`context=<context> NOT CONFIGURED\`, and diagnosis must treat the gap as unchecked rather than clean.`,
204
+ action: `Copy the matching \`<!-- context-fetch:start <name> context=<context> --> ... <!-- context-fetch:end -->\` block(s) from \`.bkit/templates/context/\` (\`bkit-github.md\` for \`ci\` and \`diff\`, \`bkit-playwright.md\`, …; index in \`.bkit/templates.md\` § Context-fetch blocks) to below \`<!-- bkit:end -->\`, one per missing context: ${list}. The templates assume GitHub Actions and Playwright because that is the common case — they are examples, NOT the contract. Edit them to your setup: \`BASELINE_BRANCH\` / \`BASELINE_WORKFLOW\` must name YOUR trunk branch and workflow file, and \`E2E_ARTIFACT\` / \`E2E_JOB_RE\` must name YOUR upload-artifact and match ONLY the lane that block covers. On another CI host (GitLab, Bitbucket, Buildkite) replace the \`gh\` calls with that host's API — the context contract is just "write the evidence to stdout". A test lane whose evidence never reaches your CI host (a native lane whose reports stay on Expo EAS, Bitrise or Firebase Test Lab) needs its OWN \`context=e2e\` block fetching from that service (Expo EAS: \`bkit-maestro.md\`, the \`expo-workflows\` block in \`bkit-expo.md\`): widening another block's job regex to cover it makes that block download the WRONG lane's report and file it under the failing lane's name, which is worse than fetching nothing. Blocks are self-contained — each discovers the run it needs itself, so there is no ordering between them and none share variables. Give each block a name unique within its context; a repeated \`context\` + name pair writes both blocks to one artifact path. No such lane in this repo → name the context on the opt-out marker below \`<!-- bkit:end -->\`, space-separated for several: \`<!-- context-fetch:none ${missing.join(" ")} -->\`. That dismisses those contexts ONLY; a bare \`<!-- context-fetch:none intentional -->\` dismisses every context-fetch advisory.`,
205
+ };
206
+ }
207
+ /**
208
+ * Named fetch blocks bkit ships as templates, keyed by block name → the template file
209
+ * (`.bkit/templates/context/<file>`) that holds it. Read from the package, so the set
210
+ * follows the shipped templates without a hand-kept list.
211
+ */
212
+ function shippedContextFetchTemplates() {
213
+ const dir = path.join(getTemplatesRoot(), "context");
214
+ const out = new Map();
215
+ if (!fs.existsSync(dir))
216
+ return out;
217
+ for (const file of fs.readdirSync(dir).sort()) {
218
+ if (!file.endsWith(".md"))
219
+ continue;
220
+ for (const { name } of parseContextFetchStarts(fs.readFileSync(path.join(dir, file), "utf-8"))) {
221
+ if (name && !out.has(name))
222
+ out.set(name, file);
223
+ }
224
+ }
225
+ return out;
226
+ }
227
+ /**
228
+ * Advisory: bkit ships a NAMED context-fetch template (e.g. `supabase` in
229
+ * `.bkit/templates/context/bkit-supabase.md`), this repo demonstrably runs that backend,
230
+ * yet the consumer section after `<!-- bkit:end -->` enables no block for it — so
231
+ * `/bkit-debug` fetches no runtime logs for a source the repo uses.
232
+ *
233
+ * Distinct from `context-fetch-missing` (consumer section has NO block at all): this
234
+ * targets PARTIAL enablement — a consumer section holding a `vercel` block while the
235
+ * repo also runs Supabase. The two are mutually exclusive: this one only runs once the
236
+ * consumer section already has at least one block.
237
+ *
238
+ * Evidence-gated: a source is flagged only when `CONTEXT_FETCH_BACKEND_EVIDENCE[name]`
239
+ * proves the repo runs it. A source counts as enabled when its name appears anywhere
240
+ * in the consumer section — a named marker (`context-fetch:start supabase`) OR an
241
+ * unnamed block body (`vercel logs`, `api.supabase.com`). Dismissable via
242
+ * `<!-- context-fetch:none ... -->` below
243
+ * `<!-- bkit:end -->`.
244
+ */
245
+ export function detectContextFetchSourceNotEnabled(cwd) {
246
+ const filePath = path.join(cwd, ".agents", "context.md");
247
+ if (!fs.existsSync(filePath))
248
+ return null;
249
+ const content = fs.readFileSync(filePath, "utf-8");
250
+ const endIdx = content.search(/^<!-- bkit:end -->$/m);
251
+ if (endIdx === -1)
252
+ return null;
253
+ const consumer = content.slice(endIdx);
254
+ // Consumer opt-out marker dismisses the advisory.
255
+ if (contextFetchDismissesAll(consumer))
256
+ return null;
257
+ // Only PARTIAL enablement: when the consumer section has no block at all,
258
+ // `context-fetch-missing` owns that case (avoid double-firing).
259
+ const hasStart = parseContextFetchStarts(consumer).length > 0;
260
+ const hasEnd = /^<!-- context-fetch:end -->$/m.test(consumer);
261
+ if (!(hasStart && hasEnd))
262
+ return null;
263
+ const shipped = shippedContextFetchTemplates();
264
+ const consumerLower = consumer.toLowerCase();
265
+ const missing = [...shipped.keys()].filter((name) => {
266
+ const evidence = CONTEXT_FETCH_BACKEND_EVIDENCE[name];
267
+ if (!evidence || !evidence(cwd))
268
+ return false; // no proof the repo runs it
269
+ return !consumerLower.includes(name.toLowerCase()); // name absent below bkit:end
270
+ });
271
+ if (missing.length === 0)
272
+ return null;
273
+ const names = missing.join(", ");
274
+ const slash = missing.join("/");
275
+ const files = missing.map((n) => `\`.bkit/templates/context/${shipped.get(n)}\``).join(", ");
276
+ const plural = missing.length > 1;
277
+ return {
278
+ id: "context-fetch-source-not-enabled",
279
+ severity: "advisory",
280
+ detect: `bkit ships context-fetch template${plural ? "s" : ""} for ${names} and this repo uses ${plural ? "those backends" : "that backend"}, but \`.agents/context.md\` enables no ${slash} block after \`<!-- bkit:end -->\`. \`/bkit-debug\` will fetch no ${slash} runtime logs.`,
281
+ action: `Copy the blocks of ${files} to after \`<!-- bkit:end -->\` in \`.agents/context.md\`, then set each block's env vars — including committing each block's non-secret selector (e.g. \`VERCEL_SCOPE\` / \`SUPABASE_PROJECT_ID\`) by uncommenting the assignment line at the top of the block, so it runs in headless cloud agents too (they never read \`.bkit/.env\`). Each block self-gates (missing CLI / token => a \`[context-fetch:<name>] skipped — …\` stderr breadcrumb, not an error). If you do not use ${slash} for runtime logs, add \`<!-- context-fetch:none intentional -->\` below \`<!-- bkit:end -->\` to dismiss. Do not edit above \`<!-- bkit:end -->\` (install rewrites it).`,
282
+ };
283
+ }
284
+ /**
285
+ * Non-stack base tools assumed present in every cloud/CI environment: POSIX
286
+ * utilities plus the binaries bkit's own cloud setup installs (vale, gh, jq,
287
+ * pnpm/corepack, node, git, python3). A context-fetch block that self-guards on one
288
+ * of these needs NO `context-fetch:provision` block — only a STACK CLI (vercel,
289
+ * supabase, gcloud, aws, wrangler, …) does; bkit installs no stack CLIs itself. `jq`
290
+ * is here: the cloud setup script provisions it as a base tool, not per-block.
291
+ */
292
+ const CONTEXT_FETCH_BASE_TOOLS = new Set([
293
+ "curl",
294
+ "jq",
295
+ "date",
296
+ "sed",
297
+ "awk",
298
+ "grep",
299
+ "egrep",
300
+ "fgrep",
301
+ "bash",
302
+ "sh",
303
+ "cat",
304
+ "printf",
305
+ "echo",
306
+ "tr",
307
+ "cut",
308
+ "head",
309
+ "tail",
310
+ "sort",
311
+ "uniq",
312
+ "wc",
313
+ "xargs",
314
+ "tee",
315
+ "node",
316
+ "npm",
317
+ "npx",
318
+ "pnpm",
319
+ "corepack",
320
+ "git",
321
+ "python3",
322
+ "gh",
323
+ "vale",
324
+ ]);
325
+ /**
326
+ * Advisory: an enabled `<!-- context-fetch:start <name> -->` block self-guards on a
327
+ * stack CLI (`command -v <cli>`) but ships no matching `<!-- context-fetch:provision
328
+ * <name> -->` block below `<!-- bkit:end -->`. bkit installs no stack CLIs itself,
329
+ * so in cloud that CLI is absent, the block's own guard trips, and it self-skips
330
+ * with a silent `exit 0` — `/bkit-debug` fetches NO runtime logs for that source.
331
+ * Both the `.claude/bkit-cloud.md` web setup-script snapshot and
332
+ * `.claude/hooks/bkit-cloud-bootstrap.sh` provision from the SAME `context-fetch:provision`
333
+ * recipes.
334
+ *
335
+ * Keyed on the block's OWN `command -v <cli>` self-guard, so a curl/jq/API block (no
336
+ * stack-CLI guard) never fires; base tools
337
+ * (`CONTEXT_FETCH_BASE_TOOLS`) are ignored. Only NAMED start blocks are checked (a
338
+ * provision block is matched by name). Dismissable via `<!-- context-fetch:none ...
339
+ * -->` below `<!-- bkit:end -->`.
340
+ */
341
+ export function detectContextFetchProvisionMissing(cwd) {
342
+ const filePath = path.join(cwd, ".agents", "context.md");
343
+ if (!fs.existsSync(filePath))
344
+ return null;
345
+ const content = fs.readFileSync(filePath, "utf-8");
346
+ const endIdx = content.search(/^<!-- bkit:end -->$/m);
347
+ if (endIdx === -1)
348
+ return null;
349
+ const consumer = content.slice(endIdx);
350
+ if (contextFetchDismissesAll(consumer))
351
+ return null;
352
+ const blocks = [];
353
+ let cur = null;
354
+ let inFence = false;
355
+ for (const line of consumer.split("\n")) {
356
+ const startM = parseContextFetchStart(line);
357
+ const provM = /^<!-- context-fetch:provision ([\w.-]+) -->$/.exec(line);
358
+ if (startM) {
359
+ // Unnamed blocks cannot be matched to a provision sibling (which is keyed
360
+ // by name), so they are parked under "" and filtered out downstream.
361
+ cur = { kind: "start", name: startM.name, body: [] };
362
+ inFence = false;
363
+ blocks.push(cur);
364
+ continue;
365
+ }
366
+ if (provM) {
367
+ cur = { kind: "provision", name: provM[1], body: [] };
368
+ inFence = false;
369
+ blocks.push(cur);
370
+ continue;
371
+ }
372
+ if (/^<!-- context-fetch:(end|none|start|provision)/.test(line)) {
373
+ cur = null;
374
+ inFence = false;
375
+ continue;
376
+ }
377
+ if (cur && /^```/.test(line)) {
378
+ inFence = !inFence;
379
+ continue;
380
+ }
381
+ if (cur && inFence)
382
+ cur.body.push(line);
383
+ }
384
+ const provisionNames = new Set(blocks.filter((b) => b.kind === "provision").map((b) => b.name));
385
+ const provisionBody = blocks
386
+ .filter((b) => b.kind === "provision")
387
+ .map((b) => b.body.join("\n"))
388
+ .join("\n");
389
+ // For each enabled named start block, collect the stack CLIs it self-guards on
390
+ // that have no provisioner (matched by same-name block OR a provision body that
391
+ // installs that CLI). First-seen order; one entry per block name.
392
+ const seen = new Set();
393
+ const items = [];
394
+ let firstName = "";
395
+ let firstCli = "";
396
+ for (const b of blocks) {
397
+ // Unnamed blocks are skipped: a provision sibling is matched by name.
398
+ if (b.kind !== "start" || !b.name || seen.has(b.name))
399
+ continue;
400
+ const body = b.body.join("\n");
401
+ for (const m of body.matchAll(/command -v ([\w.-]+)/g)) {
402
+ const cli = m[1];
403
+ if (CONTEXT_FETCH_BASE_TOOLS.has(cli))
404
+ continue;
405
+ if (provisionNames.has(b.name) || provisionBody.includes(cli))
406
+ continue;
407
+ seen.add(b.name);
408
+ items.push(`${b.name} (\`${cli}\`)`);
409
+ if (!firstName) {
410
+ firstName = b.name;
411
+ firstCli = cli;
412
+ }
413
+ break;
414
+ }
415
+ }
416
+ if (items.length === 0)
417
+ return null;
418
+ const list = items.join(", ");
419
+ const plural = items.length > 1;
420
+ return {
421
+ id: "context-fetch-provision-missing",
422
+ severity: "advisory",
423
+ detect: `\`.agents/context.md\` enable${plural ? "" : "s"} context-fetch block${plural ? "s" : ""} that self-guard${plural ? "" : "s"} on a stack CLI but ship${plural ? "" : "s"} no matching \`<!-- context-fetch:provision <name> -->\` block below \`<!-- bkit:end -->\`: ${list}. bkit installs no stack CLIs itself, so in cloud the CLI is absent, the block's own \`command -v\` guard trips, and it self-skips (silent \`exit 0\`) — \`/bkit-debug\` fetches no runtime logs for ${plural ? "those sources" : "that source"} (reads as "clean", not "not wired up").`,
424
+ action: `For each flagged block, add a sibling \`<!-- context-fetch:provision <name> -->\` block below \`<!-- bkit:end -->\` — SAME name as the fetch block — whose bash body installs the CLI, self-guarded and install-only: \`command -v ${firstCli} >/dev/null 2>&1 || <install ${firstCli}>\` (e.g. \`pnpm add -g ${firstCli}\` for an npm-published CLI). If \`.bkit/templates/context/\` ships a ready-made \`context-fetch:provision ${firstName}\` recipe, copy that. Then re-run \`bkit install\` so the recipe bakes into \`.claude/bkit-cloud.md\`'s setup script; \`.claude/hooks/bkit-cloud-bootstrap.sh\` runs the same recipe on gh-runner / resumed sessions. A block that fetches via an MCP tool or only universal tools (curl/jq/date) needs no provision.`,
425
+ };
426
+ }
@@ -0,0 +1,173 @@
1
+ // checks/before/env.ts — local env: `.bkit/.env` missing or with blank keys, direnv missing or
2
+ // not allowed.
3
+ import * as fs from "node:fs";
4
+ import * as path from "node:path";
5
+ import { spawnSync } from "node:child_process";
6
+ // ---------------------------------------------------------------------------
7
+ // [mcp-env] advisories — direnv + .bkit/.env setup (BAR-260)
8
+ // ---------------------------------------------------------------------------
9
+ /**
10
+ * Advisory: .bkit/.env.example exists but .bkit/.env does not.
11
+ * Consumer ran `bkit install` (which seeds .env.example) but has not yet
12
+ * copied it to .bkit/.env and filled in their tokens.
13
+ */
14
+ // `tracker` controls whether `BKIT_LINEAR_API_KEY` appears in the token prose (Linear
15
+ // tracker only). Defaults to `linear` (the superset: every token); the real Phase-3
16
+ // caller passes the consumer's resolved `bkit.issueTracker`.
17
+ export function detectMissingDotenv(cwd, tracker = "linear") {
18
+ const examplePath = path.join(cwd, ".bkit", ".env.example");
19
+ const envPath = path.join(cwd, ".bkit", ".env");
20
+ if (!fs.existsSync(examplePath))
21
+ return null;
22
+ if (fs.existsSync(envPath))
23
+ return null;
24
+ const tokens = tracker === "linear"
25
+ ? "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL, BKIT_LINEAR_API_KEY"
26
+ : "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL";
27
+ return {
28
+ id: "mcp-env-missing-dotenv",
29
+ severity: "advisory",
30
+ detect: `.bkit/.env.example exists but .bkit/.env does not. MCP servers and agent tooling will not have access to ${tokens}.`,
31
+ action: `[mcp-env] Copy .bkit/.env.example to .bkit/.env and fill in your tokens (${tokens}). Then run \`direnv allow\` to auto-export them into your shell. .bkit/.env is gitignored and safe to commit-skip.`,
32
+ };
33
+ }
34
+ /**
35
+ * Advisory: .bkit/.env exists but one or more required keys are blank or absent.
36
+ * Returns one finding per missing/blank key.
37
+ */
38
+ export function detectBlankDotenvKeys(cwd, tracker = "linear") {
39
+ const envPath = path.join(cwd, ".bkit", ".env");
40
+ if (!fs.existsSync(envPath))
41
+ return [];
42
+ const content = fs.readFileSync(envPath, "utf-8");
43
+ const lines = content.split("\n");
44
+ // Build a map of key → value from the .env file (ignore comments and blank lines)
45
+ const kvMap = new Map();
46
+ for (const line of lines) {
47
+ const trimmed = line.trim();
48
+ if (!trimmed || trimmed.startsWith("#"))
49
+ continue;
50
+ const eqIdx = trimmed.indexOf("=");
51
+ if (eqIdx === -1)
52
+ continue;
53
+ const key = trimmed.slice(0, eqIdx).trim();
54
+ const value = trimmed.slice(eqIdx + 1).trim();
55
+ kvMap.set(key, value);
56
+ }
57
+ const REQUIRED_KEYS = [
58
+ {
59
+ key: "BKIT_GH_TOKEN",
60
+ description: "fine-grained PAT for the GitHub MCP server (Contents, Pull requests, Issues, Actions, Workflows, Metadata — read/write)",
61
+ },
62
+ {
63
+ key: "BKIT_GH_TOKEN_INSTALL",
64
+ description: "classic PAT with read:packages scope for authenticating to the GitHub Packages npm registry (@cbartens/* packages)",
65
+ },
66
+ // BKIT_LINEAR_API_KEY is required only under the Linear tracker.
67
+ ...(tracker === "linear"
68
+ ? [
69
+ {
70
+ key: "BKIT_LINEAR_API_KEY",
71
+ description: "Linear personal API key for the Linear MCP server and the Linear preflight hook (generate at https://linear.app/settings/api)",
72
+ },
73
+ ]
74
+ : []),
75
+ ];
76
+ const findings = [];
77
+ for (const { key, description } of REQUIRED_KEYS) {
78
+ const value = kvMap.get(key);
79
+ if (value !== undefined && value !== "")
80
+ continue;
81
+ const reason = value === undefined
82
+ ? `${key} is absent from .bkit/.env`
83
+ : `${key} is set but has an empty value in .bkit/.env`;
84
+ findings.push({
85
+ id: `mcp-env-blank-key-${key.toLowerCase()}`,
86
+ severity: "advisory",
87
+ detect: `${reason}. The associated service will not authenticate.`,
88
+ action: `[mcp-env] Set ${key} in .bkit/.env — ${description}. After editing, run \`direnv allow\` (or re-enter the directory) to reload the env.`,
89
+ });
90
+ }
91
+ return findings;
92
+ }
93
+ /**
94
+ * Returns true when running in a cloud/CI environment where direnv is not
95
+ * applicable (agent reads env vars from the platform dashboard instead).
96
+ */
97
+ export function isCloudOrCi() {
98
+ return !!(process.env.CI || process.env.CLAUDE_CODE_REMOTE || process.env.CURSOR_REMOTE_AGENT);
99
+ }
100
+ /**
101
+ * Advisory: direnv is not installed.
102
+ * Short-circuits in CI / cloud environments where direnv is irrelevant.
103
+ */
104
+ export function detectDirenvMissing(cwd, tracker = "linear") {
105
+ if (isCloudOrCi())
106
+ return null;
107
+ // Only meaningful when .envrc exists (the consumer's copy of bkit's template)
108
+ const envrcPath = path.join(cwd, ".envrc");
109
+ if (!fs.existsSync(envrcPath))
110
+ return null;
111
+ const result = spawnSync("which", ["direnv"], { encoding: "utf-8" });
112
+ if (result.status === 0 && result.stdout.trim())
113
+ return null;
114
+ // BKIT_LINEAR_API_KEY is required only under the Linear tracker.
115
+ const editKeys = tracker === "linear"
116
+ ? "BKIT_GH_TOKEN_INSTALL, BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY"
117
+ : "BKIT_GH_TOKEN_INSTALL, BKIT_GH_TOKEN";
118
+ const exportKeys = tracker === "linear"
119
+ ? "BKIT_GH_TOKEN_INSTALL / BKIT_GH_TOKEN / BKIT_LINEAR_API_KEY"
120
+ : "BKIT_GH_TOKEN_INSTALL / BKIT_GH_TOKEN";
121
+ return {
122
+ id: "mcp-env-direnv-missing",
123
+ severity: "advisory",
124
+ detect: ".envrc exists but direnv is not installed. .bkit/.env will not be auto-loaded into your shell.",
125
+ action: "[mcp-env] direnv auto-loads .bkit/.env into your shell on cd, so tokens stay scoped to the repo. Set it up:\n\n" +
126
+ " # 1. One-time per machine — install direnv\n" +
127
+ " brew install direnv # macOS\n" +
128
+ " # Linux / other: https://direnv.net/docs/installation.html\n\n" +
129
+ " # 2. One-time per machine — add the shell hook, then reload\n" +
130
+ " echo 'eval \"$(direnv hook zsh)\"' >> ~/.zshrc && source ~/.zshrc\n" +
131
+ " # bash: echo 'eval \"$(direnv hook bash)\"' >> ~/.bashrc && source ~/.bashrc\n\n" +
132
+ " # 3. One-time per repo — copy the example, fill in tokens, allow\n" +
133
+ " cp .bkit/.env.example .bkit/.env # if not already done\n" +
134
+ ` # edit .bkit/.env: set ${editKeys}\n` +
135
+ " direnv allow\n\n" +
136
+ `After step 3, restart Claude Code / Cursor sessions in this repo so the new env reaches their MCP servers. Alternative if you do not want direnv: export ${exportKeys} in ~/.zshrc or ~/.bashrc directly — works but leaks tokens into every shell on this machine.`,
137
+ };
138
+ }
139
+ /**
140
+ * Advisory: direnv is installed but the .envrc is blocked (not allowed).
141
+ * Short-circuits in CI / cloud environments.
142
+ */
143
+ export function detectDirenvNotAllowed(cwd, tracker = "linear") {
144
+ if (isCloudOrCi())
145
+ return null;
146
+ // Only meaningful when .envrc exists
147
+ const envrcPath = path.join(cwd, ".envrc");
148
+ if (!fs.existsSync(envrcPath))
149
+ return null;
150
+ // Check direnv is installed first
151
+ const whichResult = spawnSync("which", ["direnv"], { encoding: "utf-8" });
152
+ if (whichResult.status !== 0 || !whichResult.stdout.trim())
153
+ return null;
154
+ // Run `direnv status` and check whether the .envrc is allowed
155
+ const statusResult = spawnSync("direnv", ["status"], {
156
+ cwd,
157
+ encoding: "utf-8",
158
+ timeout: 5000,
159
+ });
160
+ const statusOutput = (statusResult.stdout ?? "") + (statusResult.stderr ?? "");
161
+ // direnv status reports "Found RC allowed false" or "Found RC path ... Blocked" when not allowed
162
+ if (/Found RC\s+allowed\s+false/i.test(statusOutput) ||
163
+ /state:\s*blocked/i.test(statusOutput) ||
164
+ /not allowed/i.test(statusOutput)) {
165
+ return {
166
+ id: "mcp-env-direnv-not-allowed",
167
+ severity: "advisory",
168
+ detect: "direnv is installed but the .envrc in this repo is blocked. .bkit/.env is not being auto-loaded.",
169
+ action: `[mcp-env] Run \`direnv allow\` in this repo to trust the .envrc and enable auto-load of .bkit/.env. direnv will then export ${tracker === "linear" ? "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL, and BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN and BKIT_GH_TOKEN_INSTALL"} into your shell whenever you cd into the repo.`,
170
+ };
171
+ }
172
+ return null;
173
+ }