@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,8 +1,10 @@
1
- // install/cloud-env.ts — resolve a copy-paste-ready Claude Code on the web env-var block
2
- // by *following the consumer's `.envrc`*.
1
+ // install/cloud-env.ts — resolve a copy-paste-ready cloud env-var block by *following
2
+ // the consumer's `.envrc`*.
3
3
  //
4
- // The generated `.claude/bkit-cloud.md` (see runClaudeModule) inlines REAL SECRET
5
- // VALUES so it is gitignored + chmod 600 and never committed. This module owns the
4
+ // The generated `.claude/bkit-cloud.md`, `.cursor/bkit-cloud.md` and
5
+ // `.codex/bkit-cloud.md` (see the claude / cursor / codex host modules) inline REAL
6
+ // SECRET VALUES so they are gitignored + chmod 600 and never committed. All three carry
7
+ // the same env block whatever the issue tracker. This module owns the
6
8
  // stack-agnostic resolution: it reads whatever dotenv files the repo's `.envrc`
7
9
  // sources, honours the `.envrc` `unset` lines, and drops session-hijack keys.
8
10
  // bkit hardcodes NO stack-specific key lists — the stack knowledge lives in the
@@ -13,32 +15,36 @@
13
15
 
14
16
  import * as fs from "node:fs";
15
17
  import * as path from "node:path";
16
- import type { IssueTracker } from "./manifest.js";
17
18
  import { readJsonFile } from "../shared/json.js";
18
19
  import { getSharedRoot } from "../shared/package-roots.js";
19
20
  import { applyTokens, type TokenMap } from "./placeholders.js";
20
- import { BKIT_EGRESS_SOURCES, type EgressSource } from "../shared/egress.js";
21
+ import { BKIT_EGRESS_SOURCES, MULTI_TENANT_APEXES, type EgressSource } from "../shared/egress.js";
21
22
  import { sha256 } from "./version-file.js";
22
23
 
23
24
  // Consumer-relative paths of the generated docs. Shared so the upgrade template walk
24
25
  // (commands/install/install.ts) can exclude them — they are generated OUTPUT files, never
25
26
  // templates to reconcile. One per cloud host (Claude Code on the web / Cursor
26
- // Background Agents); both inline resolved secrets, both gitignored + chmod 600.
27
+ // Background Agents / Codex Cloud); all inline resolved secrets, all gitignored + chmod 600.
27
28
  export const CLAUDE_CLOUD_RELPATH = path.join(".claude", "bkit-cloud.md");
28
29
  export const CURSOR_CLOUD_RELPATH = path.join(".cursor", "bkit-cloud.md");
30
+ export const CODEX_CLOUD_RELPATH = path.join(".codex", "bkit-cloud.md");
29
31
 
30
32
  // Session-hijack keys: exporting these into a cloud env redirects Claude Code's
31
33
  // OWN model calls onto API-key billing instead of the user's subscription
32
- // (`.bkit/cloud.md` § Environment variables). Always dropped from the paste block.
34
+ // (`.bkit/cloud.md` § Tokens by session type). Always dropped from the paste block.
33
35
  export const SESSION_HIJACK_KEYS = [
34
36
  "ANTHROPIC_API_KEY",
35
37
  "BKIT_ANTHROPIC_API_KEY",
36
38
  "ANTHROPIC_AUTH_TOKEN",
37
39
  ] as const;
38
40
 
39
- // bkit baseline env-var NAMES every Claude-on-web environment needs. Emitted as a
40
- // placeholder ONLY when absent from the resolved `.envrc` set — a present value
41
- // (e.g. BKIT_GH_TOKEN already in `.bkit/.env`) keeps its real resolved value.
41
+ // bkit baseline env-var NAMES every cloud environment needs, whatever the tracker:
42
+ // `gh` and the GitHub MCP server read BKIT_GH_TOKEN on every host. Emitted as a
43
+ // placeholder ONLY when absent from the resolved `.envrc` set — a present value keeps
44
+ // its real resolved value. Tracker keys (BKIT_LINEAR_API_KEY, BKIT_JIRA_API_KEY) are
45
+ // never baseline: a consumer on that tracker already sets them in `.envrc`, so they
46
+ // arrive with the resolved set. One baseline for every host keeps the generated docs
47
+ // describing the SAME cloud environment — just different mechanics.
42
48
  const BASELINE_TOKEN_PLACEHOLDERS: ReadonlyArray<readonly [string, string]> = [
43
49
  [
44
50
  "BKIT_GH_TOKEN",
@@ -46,39 +52,6 @@ const BASELINE_TOKEN_PLACEHOLDERS: ReadonlyArray<readonly [string, string]> = [
46
52
  ],
47
53
  ];
48
54
 
49
- // Per-cloud env-var policy. The `.envrc`-following resolver core is identical for
50
- // both clouds (same dotenv sources, same unset/hijack/empty drops) — only the
51
- // baseline placeholder set differs. Claude pairs with the GitHub tracker; Cursor pairs
52
- // with Linear (and so also needs `BKIT_LINEAR_API_KEY`). Keeping one resolver with a
53
- // small policy object is what guarantees the two generated docs describe the SAME
54
- // cloud environment — just different mechanics (pasted setup vs. Dockerfile).
55
- export interface CloudEnvPolicy {
56
- /** Baseline env-var NAMES this cloud always needs; emitted as `NAME=<placeholder>`
57
- * when absent from the resolved `.envrc` set. */
58
- baseline: ReadonlyArray<readonly [string, string]>;
59
- }
60
-
61
- // Claude Code on the web: GitHub tracker.
62
- export const CLAUDE_CLOUD_POLICY: CloudEnvPolicy = {
63
- baseline: BASELINE_TOKEN_PLACEHOLDERS,
64
- };
65
-
66
- // Cursor Background Agents: `BKIT_LINEAR_API_KEY` prepended for the Linear tracker
67
- // (bkit-preflight.sh calls the Linear GraphQL API and hard-fails without it); GitHub
68
- // tracker uses the same GH baseline as Claude.
69
- const CURSOR_LINEAR_PLACEHOLDER: readonly [string, string] = [
70
- "BKIT_LINEAR_API_KEY",
71
- "<Linear personal API key — https://linear.app/settings/api>",
72
- ];
73
- export function cursorCloudPolicy(tracker: IssueTracker): CloudEnvPolicy {
74
- return {
75
- baseline:
76
- tracker === "linear"
77
- ? [CURSOR_LINEAR_PLACEHOLDER, ...BASELINE_TOKEN_PLACEHOLDERS]
78
- : BASELINE_TOKEN_PLACEHOLDERS,
79
- };
80
- }
81
-
82
55
  export interface CloudEnvResolution {
83
56
  /** Resolved KEY/value pairs, non-empty, ordered first-seen with last-source value. */
84
57
  included: Array<[string, string]>;
@@ -157,10 +130,7 @@ export function parseDotenv(content: string): Array<[string, string]> {
157
130
  * Applies `.envrc` unsets, then drops session-hijack keys. Returns empty when no
158
131
  * `.envrc` exists — the caller still emits a usable placeholder doc.
159
132
  */
160
- export function resolveCloudEnvVars(
161
- cwd: string,
162
- policy: CloudEnvPolicy = CLAUDE_CLOUD_POLICY,
163
- ): CloudEnvResolution {
133
+ export function resolveCloudEnvVars(cwd: string): CloudEnvResolution {
164
134
  const res: CloudEnvResolution = {
165
135
  included: [],
166
136
  unset: [],
@@ -215,7 +185,7 @@ export function resolveCloudEnvVars(
215
185
 
216
186
  // Baseline names absent from the resolved set → emitted as placeholders.
217
187
  const present = new Set(res.included.map(([k]) => k));
218
- for (const [name] of policy.baseline) {
188
+ for (const [name] of BASELINE_TOKEN_PLACEHOLDERS) {
219
189
  if (!present.has(name)) res.placeholders.push(name);
220
190
  }
221
191
 
@@ -226,13 +196,10 @@ export function resolveCloudEnvVars(
226
196
  * Render the `.env`-format paste block: resolved KEY=value lines, then placeholder
227
197
  * lines for any absent baseline token.
228
198
  */
229
- export function renderCloudEnvBlock(
230
- res: CloudEnvResolution,
231
- policy: CloudEnvPolicy = CLAUDE_CLOUD_POLICY,
232
- ): string {
199
+ export function renderCloudEnvBlock(res: CloudEnvResolution): string {
233
200
  const lines: string[] = [];
234
201
  for (const [k, v] of res.included) lines.push(`${k}=${v}`);
235
- for (const [name, placeholder] of policy.baseline) {
202
+ for (const [name, placeholder] of BASELINE_TOKEN_PLACEHOLDERS) {
236
203
  if (res.placeholders.includes(name)) lines.push(`${name}=${placeholder}`);
237
204
  }
238
205
  return lines.join("\n");
@@ -304,30 +271,42 @@ export function renderCorepackLine(cwd: string): string {
304
271
  * enabled below `<!-- bkit:end -->` in `.agents/context.md`. Stack-agnostic: bkit
305
272
  * hardcodes no CLI names — the install recipe lives in the consumer's context.md,
306
273
  * co-located with the fetch block that needs the CLI. `bkit context list-blocks` returns
307
- * the same list as `provision`, which `.claude/hooks/bkit-cloud-bootstrap.sh` runs, so the web
308
- * setup-script snapshot and the per-session hook provision the same CLIs. Returns one
309
- * string per block (bash body).
274
+ * the same list as `provision`, so the web setup-script snapshot and the per-session
275
+ * hook provision the same CLIs. Returns one string per block (bash body).
310
276
  */
311
277
  export function extractContextFetchProvisionRecipes(cwd: string): string[] {
278
+ return extractContextFetchProvisionBlocks(cwd).map((b) => b.body);
279
+ }
280
+
281
+ /**
282
+ * {@link extractContextFetchProvisionRecipes} with each block's name — the word after
283
+ * `context-fetch:provision` in its opening marker, limited to `[A-Za-z0-9._-]` so it is
284
+ * safe inside a quoted shell string; "" when the marker names none.
285
+ * {@link renderCloudContextFetchProvision} reports a failing recipe by this name.
286
+ */
287
+ export function extractContextFetchProvisionBlocks(cwd: string): { name: string; body: string }[] {
312
288
  const filePath = path.join(cwd, ".agents", "context.md");
313
289
  if (!fs.existsSync(filePath)) return [];
314
290
  const content = fs.readFileSync(filePath, "utf-8");
315
291
  const endIdx = content.search(/^<!-- bkit:end -->$/m);
316
292
  if (endIdx === -1) return [];
317
293
  const consumer = content.slice(endIdx);
318
- const recipes: string[] = [];
294
+ const recipes: { name: string; body: string }[] = [];
295
+ let name = "";
319
296
  let cur: string[] | null = null;
320
297
  let inProv = false;
321
298
  let inFence = false;
322
299
  for (const line of consumer.split("\n")) {
323
- if (/^<!-- context-fetch:provision/.test(line)) {
300
+ const opening = /^<!-- context-fetch:provision\b\s*([A-Za-z0-9][A-Za-z0-9._-]*)?/.exec(line);
301
+ if (opening) {
302
+ name = opening[1] ?? "";
324
303
  inProv = true;
325
304
  inFence = false;
326
305
  cur = [];
327
306
  continue;
328
307
  }
329
308
  if (/^<!-- context-fetch:(start|end|none)/.test(line)) {
330
- if (inProv && cur && cur.length > 0) recipes.push(cur.join("\n"));
309
+ if (inProv && cur && cur.length > 0) recipes.push({ name, body: cur.join("\n") });
331
310
  inProv = false;
332
311
  inFence = false;
333
312
  cur = null;
@@ -378,30 +357,76 @@ const CLOUD_PNPM_GLOBAL_PATH_SETUP =
378
357
  'export PNPM_HOME="${PNPM_HOME:-$HOME/.local/share/pnpm}"\n' +
379
358
  'export PATH="$PNPM_HOME:$PNPM_HOME/bin:$PATH"';
380
359
 
360
+ /** Where a cloud environment lists the provision recipes that failed in it, from the repo root. */
361
+ export const UNAVAILABLE_RELPATH = ".bkit/.unavailable";
362
+
363
+ /**
364
+ * Runs one provision recipe (a function named in `$2`) in its own `set -e` subshell. Its
365
+ * stdout goes to stderr, so a caller's stdout carries only its own report. A failure is
366
+ * named on stderr with the recipe's last error line, added to `$BKIT_UNAVAILABLE`, and
367
+ * appended to `$BKIT_UNAVAILABLE_FILE` as `<name>: <reason>` when that is set. The
368
+ * subshell is never the left side of `||`: bash ignores `set -e` there, so only the
369
+ * recipe's last command would count.
370
+ */
371
+ const CLOUD_PROVISION_RUNNER =
372
+ "bkit_provision() {\n" +
373
+ " bkit_err=$(mktemp)\n" +
374
+ ' ( set -e; "$2" ) >&2 2>"$bkit_err"\n' +
375
+ " bkit_rc=$?\n" +
376
+ ' cat "$bkit_err" >&2\n' +
377
+ ' if [ "$bkit_rc" -ne 0 ]; then\n' +
378
+ " bkit_why=$(grep -v '^[[:space:]]*$' \"$bkit_err\" | tail -n 1 | cut -c 1-300)\n" +
379
+ ' [ -n "$bkit_why" ] || bkit_why="exit $bkit_rc"\n' +
380
+ " echo \"[cloud-setup] provision '$1' failed (non-blocking): $bkit_why\" >&2\n" +
381
+ ' BKIT_UNAVAILABLE="${BKIT_UNAVAILABLE:+$BKIT_UNAVAILABLE, }$1"\n' +
382
+ ' [ -z "$BKIT_UNAVAILABLE_FILE" ] || printf \'%s: %s\\n\' "$1" "$bkit_why" >> "$BKIT_UNAVAILABLE_FILE"\n' +
383
+ " fi\n" +
384
+ ' rm -f "$bkit_err"\n' +
385
+ "}";
386
+
381
387
  /**
382
388
  * Render the `@@CLOUD_CONTEXT_FETCH_PROVISION@@` setup-script region: the consumer's
383
389
  * `context-fetch:provision` recipes, or "" when none are enabled. Placed AFTER the
384
- * corepack line in the template so `pnpm add -g …` recipes have pnpm available.
390
+ * corepack line in the template so `pnpm add -g …` recipes have pnpm available. `bkit
391
+ * context provision` runs the same region, so every cloud platform runs the recipes one way.
385
392
  *
386
- * Recipes run in a best-effort `( set +e … ) || …` subshell: the setup script is
387
- * `set -euo pipefail`, so without this a single failing recipe (e.g. a heavy `curl |
388
- * bash` CLI installer that trips over a missing base-image dep) aborts the whole
389
- * snapshot build and discards every CLI provisioned before it. `set +e` also lets a
390
- * later recipe run after an earlier one fails. Mirrors the non-blocking per-session
391
- * hook (`… | bash || log`), keeping the two cloud provision paths behaviourally equal.
393
+ * The setup script is `set -euo pipefail`, so a bare failing recipe (e.g. a heavy
394
+ * `curl | bash` CLI installer that trips over a missing base-image dep) would abort the
395
+ * whole snapshot build and discard every CLI provisioned before it. So errexit is off
396
+ * around the region and back on after it, and each recipe runs on its own through
397
+ * {@link CLOUD_PROVISION_RUNNER}: a failing command stops only its own recipe.
398
+ *
399
+ * With `$REPO_ROOT` set, the region rewrites {@link UNAVAILABLE_RELPATH} under it
400
+ * (removed when nothing failed) for the cloud agent to read. The Claude setup script runs
401
+ * before the clone, with no `$REPO_ROOT`; there the session hook writes the file. The
402
+ * region leaves `$BKIT_UNAVAILABLE` set for the script's closing line.
392
403
  */
393
404
  export function renderCloudContextFetchProvision(cwd: string): string {
394
- const recipes = extractContextFetchProvisionRecipes(cwd);
405
+ const recipes = extractContextFetchProvisionBlocks(cwd)
406
+ .map(({ name, body }, i) => ({ label: name === "" ? `#${i + 1}` : name, body }))
407
+ .filter(({ body }) => body.trim() !== "");
395
408
  if (recipes.length === 0) return "";
409
+ const runs = recipes.map(
410
+ ({ label, body }, i) =>
411
+ `bkit_provision_${i + 1}() {\n${body}\n}\nbkit_provision '${label}' bkit_provision_${i + 1}`,
412
+ );
396
413
  return (
397
- "# context-fetch CLIs (from .agents/context.md provision blocks) — self-guarded, best-effort.\n" +
414
+ "# context-fetch provision recipes (from .agents/context.md) — each runs on its own. A\n" +
415
+ "# failing one is named with its last error line and never stops this script.\n" +
398
416
  CLOUD_PNPM_GLOBAL_PATH_SETUP +
417
+ "\nset +e\n" +
418
+ 'BKIT_UNAVAILABLE=""\n' +
419
+ `BKIT_UNAVAILABLE_FILE="\${REPO_ROOT:+$REPO_ROOT/${UNAVAILABLE_RELPATH}}"\n` +
420
+ '[ -z "$BKIT_UNAVAILABLE_FILE" ] || { mkdir -p "${BKIT_UNAVAILABLE_FILE%/*}"; : > "$BKIT_UNAVAILABLE_FILE"; }\n' +
421
+ CLOUD_PROVISION_RUNNER +
399
422
  "\n" +
400
- "(\n" +
401
- " set +e\n" +
402
- recipes.join("\n") +
403
- "\n" +
404
- ') || echo "[cloud-setup] a context-fetch provision recipe failed (non-blocking); its CLI will be absent" >&2'
423
+ runs.join("\n") +
424
+ '\nif [ -n "$BKIT_UNAVAILABLE" ]; then\n' +
425
+ ' echo "[cloud-setup] UNAVAILABLE in this environment: $BKIT_UNAVAILABLE. Their setup failed: treat them as absent and do not retry the install." >&2\n' +
426
+ "else\n" +
427
+ ' [ -z "$BKIT_UNAVAILABLE_FILE" ] || rm -f "$BKIT_UNAVAILABLE_FILE"\n' +
428
+ "fi\n" +
429
+ "set -e"
405
430
  );
406
431
  }
407
432
 
@@ -613,6 +638,24 @@ export function egressFingerprint(): string {
613
638
  return sha256(derived.join("\n")).slice(0, 8);
614
639
  }
615
640
 
641
+ /**
642
+ * The "where these came from" clause of a network list's count note. A declared entry
643
+ * bkit already ships adds nothing to the list, so it counts once, as shipped, and the
644
+ * clause names how many declared entries that was. `declared` and `shipped` are in the
645
+ * list's own unit: apex bases for the Claude list, exact hosts for Cursor and Codex.
646
+ */
647
+ function networkSourceCounts(declared: string[], shipped: readonly string[]): string {
648
+ const shippedSet = new Set(shipped);
649
+ const declaredSet = new Set(declared);
650
+ const added = [...declaredSet].filter((d) => !shippedSet.has(d)).length;
651
+ const overlap = declaredSet.size - added;
652
+ return (
653
+ `${shippedSet.size} from bkit's shipped egress registry and ${added} more from ` +
654
+ "`allowed-domains` in `.agents/context.md`" +
655
+ (overlap > 0 ? ` (${overlap} of its ${declaredSet.size} entries already shipped)` : "")
656
+ );
657
+ }
658
+
616
659
  /**
617
660
  * Render the `@@CLOUD_NETWORK_ALLOWLIST@@` region — the whole `## Network access`
618
661
  * body. Always emits a **Custom** paste block: the list is the derived shipped bases
@@ -623,7 +666,6 @@ export function egressFingerprint(): string {
623
666
  export function renderCloudNetworkAllowlist(cwd: string): string {
624
667
  const declared = extractAllowedDomains(cwd);
625
668
  const domains = resolveNetworkAllowlist(cwd);
626
- const derivedCount = BKIT_SHIPPED_NETWORK_DOMAINS.length;
627
669
  const declaredNote =
628
670
  declared.length === 0
629
671
  ? "\n\n_No `allowed-domains` block is declared in `.agents/context.md`. The list above is\n" +
@@ -638,9 +680,9 @@ export function renderCloudNetworkAllowlist(cwd: string): string {
638
680
  "```text\n" +
639
681
  domains.join("\n") +
640
682
  "\n```\n\n" +
641
- `_${domains.length} entries — ${derivedCount} derived from bkit's shipped egress registry ` +
642
- `and ${declared.length} declared in \`allowed-domains\` in \`.agents/context.md\`, ` +
643
- "each as apex + `*.` wildcard. Derived set fingerprint `" +
683
+ `_${domains.length} entries (${domains.length / 2} domains, each as apex + \`*.\` wildcard): ` +
684
+ networkSourceCounts(networkAllowlistBases(declared), BKIT_SHIPPED_NETWORK_DOMAINS) +
685
+ ". Derived set fingerprint `" +
644
686
  egressFingerprint() +
645
687
  "`._" +
646
688
  declaredNote +
@@ -756,6 +798,24 @@ export function renderCloudUserSettings(cwd: string): string {
756
798
  );
757
799
  }
758
800
 
801
+ /** `# bkit-toolchain:start|end` marker lines in the Claude template's setup script. */
802
+ const TOOLCHAIN_MARKER_LINE = /^# bkit-toolchain:(?:start|end)\n/gm;
803
+
804
+ /**
805
+ * The pinned toolchain installs (Node, vale, gh, jq + the PATH lead) from the Claude
806
+ * template's setup script — the region between the `# bkit-toolchain:start` / `:end`
807
+ * markers, markers stripped. The pins live once, in `.bkit/shared/.claude/bkit-cloud.md`
808
+ * (where Renovate's regex manager bumps them); every other pasted install script inlines
809
+ * this slice so the cloud toolchains never diverge. Throws when the markers are absent:
810
+ * a Codex doc without its toolchain is a broken paste, not an empty one.
811
+ */
812
+ export function extractCloudToolchainScript(): string {
813
+ const src = fs.readFileSync(path.join(getSharedRoot(), ".claude", "bkit-cloud.md"), "utf-8");
814
+ const m = /^# bkit-toolchain:start\n([\s\S]*?)^# bkit-toolchain:end$/m.exec(src);
815
+ if (!m) throw new Error(".claude/bkit-cloud.md template lacks the bkit-toolchain markers");
816
+ return m[1]!.trim();
817
+ }
818
+
759
819
  /**
760
820
  * Generate `.claude/bkit-cloud.md` — a copy-paste-ready Claude Code on the web setup doc
761
821
  * with the env-var block resolved to REAL VALUES from the consumer's `.envrc`.
@@ -779,6 +839,7 @@ export function writeClaudeCloudDoc(cwd: string, tokens: TokenMap): boolean {
779
839
  // Function-form replacers: resolved secret values may contain `$`, which a string
780
840
  // replacement would interpret ($&, $1, …).
781
841
  const content = applyTokens(fs.readFileSync(src, "utf-8"), tokens)
842
+ .replace(TOOLCHAIN_MARKER_LINE, "")
782
843
  .replace(/@@CLOUD_CACHE_BUST@@/g, () => renderCloudCacheBust(cwd, today))
783
844
  .replace(/@@CLOUD_NETWORK_ALLOWLIST@@/g, () => renderCloudNetworkAllowlist(cwd))
784
845
  .replace(/@@CLOUD_WORKSPACE_TRUST@@/g, () => renderCloudWorkspaceTrust(cwd))
@@ -796,61 +857,78 @@ export function writeClaudeCloudDoc(cwd: string, tokens: TokenMap): boolean {
796
857
 
797
858
  /**
798
859
  * Render the `@@CURSOR_CONTEXT_FETCH@@` region of `.cursor/bkit-cloud.md`: the consumer's
799
- * `context-fetch:provision` recipes formatted for the Cursor mechanic, or "" when none
800
- * are enabled. On Claude these CLIs are baked into the pasted setup script (see
801
- * renderCloudContextFetchProvision); Cursor has no setup script, so — to keep the two
802
- * cloud environments aligned — the same recipes are surfaced as a copy-paste block for
803
- * the per-snapshot `install` command in `.cursor/environment.json`. The recipes are
804
- * already idempotent (`command -v X || pnpm add -g X`), so they are safe to re-run on
805
- * every snapshot build. Reuses the SAME extractor as the Claude path so the two clouds
806
- * never diverge on which CLIs they provision.
860
+ * `context-fetch:provision` recipes by name, or "" when none are enabled. On Claude and
861
+ * Codex they are inlined into the pasted script ({@link renderCloudContextFetchProvision});
862
+ * Cursor has no pasted script, so the `install` command in `.cursor/environment.json` runs
863
+ * `bkit context provision`, which runs that same region. The section names the recipes and
864
+ * the line a copy of `environment.json` without it needs.
807
865
  */
808
866
  export function renderCursorContextFetchProvision(cwd: string): string {
809
- const recipes = extractContextFetchProvisionRecipes(cwd);
867
+ const blocks = extractContextFetchProvisionBlocks(cwd);
810
868
  // Empty → "" and the template's sentinel line collapses to a single blank between
811
869
  // sections; non-empty → a self-contained section with its own leading/trailing blank.
812
- if (recipes.length === 0) return "";
870
+ if (blocks.length === 0) return "";
871
+ const names = blocks.map(({ name }, i) => `\`${name === "" ? `#${i + 1}` : name}\``);
813
872
  return (
814
873
  "\n## Context-fetch CLIs (parity with the Claude setup script)\n\n" +
815
- "Your `.agents/context.md` declares these context-fetch CLIs. The Claude setup script\n" +
816
- "bakes them into its snapshot; for the SAME tools on Cursor, chain them into the\n" +
817
- "`install` command in `.cursor/environment.json` (idempotent — safe every rebuild):\n\n" +
874
+ `Your \`.agents/context.md\` declares these provision recipes: ${names.join(", ")}. The\n` +
875
+ "`install` command in `.cursor/environment.json` runs them each snapshot build, after\n" +
876
+ "`pnpm install`, by ending with:\n\n" +
818
877
  "```bash\n" +
819
- recipes.join("\n") +
820
- "\n```\n"
878
+ "&& pnpm exec bkit context provision\n" +
879
+ "```\n\n" +
880
+ "A recipe that fails is named in the install log and listed in `.bkit/.unavailable`\n" +
881
+ "for the agent; the install still succeeds.\n"
821
882
  );
822
883
  }
823
884
 
824
885
  /**
825
- * Render the `@@CURSOR_NETWORK@@` region — Cursor Cloud Agents DO have an egress
826
- * allowlist (dashboard → Security: "Allow all" / "Default + allowlist" / "Allowlist
827
- * only"), unlike the earlier assumption. Reuses the SAME declared `allowed-domains`
828
- * as the Claude side, but — critically — does NOT apply Claude's apex+`*.`
829
- * expansion: Cursor's own docs warn that a broad wildcard (`*.s3….amazonaws.com`)
830
- * opens egress far wider than intended, so the declared apex entries are emitted
831
- * verbatim with a note to add only the specific subdomains you need.
886
+ * The Cursor and Codex allowlist: the fenced paste block and the notes under it. bkit's
887
+ * shipped HOSTS are listed exactly; each declared `allowed-domains` entry bkit does not
888
+ * already ship is listed as the domain and its `*.` wildcard, like the Claude side, since
889
+ * the CLIs and APIs a consumer declares call subdomains (`api.vercel.com` under
890
+ * `vercel.com`). A declared {@link MULTI_TENANT_APEXES} entry is widened the same way,
891
+ * with a note that its wildcard reaches every tenant on the platform, the exfiltration
892
+ * path Cursor's docs warn about.
832
893
  */
833
- export function renderCursorNetworkAllowlist(cwd: string): string {
894
+ function renderWidenedNetworkList(cwd: string): string {
834
895
  const declared = extractAllowedDomains(cwd);
835
- // Exact hosts, never apex + `*.`: Cursor's own docs warn a broad wildcard opens
836
- // egress far wider than intended, so the shipped set contributes its HOSTS here
837
- // while the Claude side takes the wildcard-expanded bases.
838
- const entries = [...new Set([...BKIT_SHIPPED_NETWORK_HOSTS, ...declared])].sort();
896
+ const names = [...new Set([...BKIT_SHIPPED_NETWORK_HOSTS, ...declared])].sort();
897
+ const shipped = new Set(BKIT_SHIPPED_NETWORK_HOSTS);
898
+ const widened = (n: string): boolean => declared.includes(n) && !shipped.has(n);
899
+ const entries = names.flatMap((n) => (widened(n) ? [n, `*.${n}`] : [n]));
900
+ const shared = [...new Set(declared)].filter((d) => MULTI_TENANT_APEXES.includes(d));
901
+ const sharedNote =
902
+ shared.length === 0
903
+ ? ""
904
+ : `\n\n${shared.map((d) => `\`${d}\``).join(", ")}: shared by many tenants, so the ` +
905
+ "`*.` wildcard reaches every tenant on it. To narrow it, declare the exact hosts you " +
906
+ `call there instead (e.g. \`<name>.${shared[0]}\`).`;
839
907
  return (
840
- "If your org runs Cloud Agents in **Allowlist only** / **Default + allowlist** mode\n" +
841
- "(dashboard → **Security**), add these hosts so cloud `/bkit-debug` + e2e can reach\n" +
842
- "bkit's own tooling and your app and log backends:\n\n" +
843
908
  "```text\n" +
844
909
  entries.join("\n") +
845
910
  "\n```\n\n" +
846
- `_${entries.length} host(s) — ${BKIT_SHIPPED_NETWORK_HOSTS.length} derived from bkit's shipped ` +
847
- `egress registry and ${declared.length} declared in \`allowed-domains\` in ` +
848
- "`.agents/context.md`. Derived set fingerprint `" +
911
+ `_${entries.length} entries (${names.length} hosts and domains, each declared domain ` +
912
+ "also as a `*.` wildcard): " +
913
+ networkSourceCounts(declared, BKIT_SHIPPED_NETWORK_HOSTS) +
914
+ ". Derived set fingerprint `" +
849
915
  egressFingerprint() +
850
- "`._ Add only the\n" +
851
- "specific subdomains you need (e.g. `api.example.com`) — Cursor warns that a broad `*.`\n" +
852
- "wildcard opens egress far wider than intended. (The Claude side auto-expands to apex + `*.`;\n" +
853
- "Cursor's allowlist is deliberately narrower.)"
916
+ "`._" +
917
+ sharedNote
918
+ );
919
+ }
920
+
921
+ /**
922
+ * Render the `@@CURSOR_NETWORK@@` region — Cursor Cloud Agents' egress allowlist
923
+ * (dashboard → Security: "Allow all" / "Default + allowlist" / "Allowlist only"), which
924
+ * takes `*.` patterns (Cursor's own default list is written that way).
925
+ */
926
+ export function renderCursorNetworkAllowlist(cwd: string): string {
927
+ return (
928
+ "If your org runs Cloud Agents in **Allowlist only** / **Default + allowlist** mode\n" +
929
+ "(dashboard → **Security**), add these hosts so cloud `/bkit-debug` + e2e can reach\n" +
930
+ "bkit's own tooling and your app and log backends:\n\n" +
931
+ renderWidenedNetworkList(cwd)
854
932
  );
855
933
  }
856
934
 
@@ -861,8 +939,8 @@ export function renderCursorNetworkAllowlist(cwd: string): string {
861
939
  * selector; on Cursor the toolchain lives in `.cursor/Dockerfile` + the per-snapshot
862
940
  * `.cursor/environment.json` `install` (both committed, nothing to paste), so this doc
863
941
  * is narrower: it resolves the **dashboard environment variables** to real values from
864
- * the consumer's `.envrc` (Cursor policy — Linear tracker adds `BKIT_LINEAR_API_KEY`, no
865
- * autocompact knob) and surfaces any context-fetch CLIs for parity.
942
+ * the consumer's `.envrc` (the same tracker-independent set as the Claude doc) and
943
+ * surfaces any context-fetch CLIs for parity.
866
944
  *
867
945
  * Like `.claude/bkit-cloud.md` it is gitignored + chmod 600 and UNTRACKED (never pushed to
868
946
  * any WriteSet / manifest / canonicalHashes) — its values are machine-local and
@@ -872,15 +950,14 @@ export function renderCursorNetworkAllowlist(cwd: string): string {
872
950
  * host being installed. Returns true when a file was written (false when the template
873
951
  * is absent). Never logs the resolved values.
874
952
  */
875
- export function writeCursorCloudDoc(cwd: string, tokens: TokenMap, tracker: IssueTracker): boolean {
953
+ export function writeCursorCloudDoc(cwd: string, tokens: TokenMap): boolean {
876
954
  const src = path.join(getSharedRoot(), ".cursor", "bkit-cloud.md");
877
955
  if (!fs.existsSync(src)) return false;
878
- const policy = cursorCloudPolicy(tracker);
879
- const res = resolveCloudEnvVars(cwd, policy);
956
+ const res = resolveCloudEnvVars(cwd);
880
957
  // Function-form replacers: resolved secret values may contain `$`, which a string
881
958
  // replacement would interpret ($&, $1, …).
882
959
  const content = applyTokens(fs.readFileSync(src, "utf-8"), tokens)
883
- .replace(/@@CLOUD_ENV_VARS@@/g, () => renderCloudEnvBlock(res, policy))
960
+ .replace(/@@CLOUD_ENV_VARS@@/g, () => renderCloudEnvBlock(res))
884
961
  .replace(/@@CLOUD_ENV_NOTES@@/g, () => renderCloudEnvNotes(res))
885
962
  .replace(/@@CURSOR_NETWORK@@/g, () => renderCursorNetworkAllowlist(cwd))
886
963
  .replace(/@@CURSOR_CONTEXT_FETCH@@/g, () => renderCursorContextFetchProvision(cwd));
@@ -890,3 +967,56 @@ export function writeCursorCloudDoc(cwd: string, tokens: TokenMap, tracker: Issu
890
967
  fs.chmodSync(dst, 0o600);
891
968
  return true;
892
969
  }
970
+
971
+ /**
972
+ * Render the `@@CODEX_NETWORK@@` region — Codex Cloud's **Internet access** settings
973
+ * for the environment: the same list as the Cursor doc. Codex's docs describe
974
+ * **Additional allowed domains** as exact hosts (a root domain also allows `www.`) and
975
+ * say nothing of `*.`, so the note marks the wildcard entries untested and names the
976
+ * setting that gets past a host they miss.
977
+ */
978
+ export function renderCodexNetworkAllowlist(cwd: string): string {
979
+ return (
980
+ "Under **Internet access**, keep **Enable package manager domains** on and paste these\n" +
981
+ "into **Additional allowed domains** (one per line) so cloud `/bkit-debug` + e2e can\n" +
982
+ "reach bkit's own tooling and your app and log backends:\n\n" +
983
+ renderWidenedNetworkList(cwd) +
984
+ "\n\nThe `*.` entries are untested on Codex: its docs list exact hosts only. If a task\n" +
985
+ "still cannot reach a subdomain, switch to **Enable all public internet access** (opens\n" +
986
+ "all egress) or add that exact host."
987
+ );
988
+ }
989
+
990
+ /**
991
+ * Generate `.codex/bkit-cloud.md` — the Codex Cloud analogue of `.claude/bkit-cloud.md`:
992
+ * the SAME bkit cloud environment, built by Codex's mechanics. Codex runs a pasted
993
+ * **Install script** (like Claude's setup script) plus the environment's variables, so
994
+ * this doc carries the Claude template's pinned toolchain slice
995
+ * ({@link extractCloudToolchainScript}), the consumer's corepack pnpm and context-fetch
996
+ * provision recipes, the per-snapshot `pnpm install`, the exact-host network list, and
997
+ * the resolved env block.
998
+ *
999
+ * Gitignored + chmod 600 and UNTRACKED like its siblings. Shared by install
1000
+ * (runCodexModule) and upgrade. Callers MUST guard on `!dryRun` and on the codex host
1001
+ * being installed. Returns true when a file was written (false when the template is
1002
+ * absent). Never logs the resolved values.
1003
+ */
1004
+ export function writeCodexCloudDoc(cwd: string, tokens: TokenMap): boolean {
1005
+ const src = path.join(getSharedRoot(), ".codex", "bkit-cloud.md");
1006
+ if (!fs.existsSync(src)) return false;
1007
+ const res = resolveCloudEnvVars(cwd);
1008
+ // Function-form replacers: resolved secret values may contain `$`, which a string
1009
+ // replacement would interpret ($&, $1, …).
1010
+ const content = applyTokens(fs.readFileSync(src, "utf-8"), tokens)
1011
+ .replace(/@@CODEX_TOOLCHAIN@@/g, () => extractCloudToolchainScript())
1012
+ .replace(/@@CODEX_NETWORK@@/g, () => renderCodexNetworkAllowlist(cwd))
1013
+ .replace(/@@CLOUD_COREPACK@@/g, () => renderCorepackLine(cwd))
1014
+ .replace(/@@CLOUD_CONTEXT_FETCH_PROVISION@@/g, () => renderCloudContextFetchProvision(cwd))
1015
+ .replace(/@@CLOUD_ENV_VARS@@/g, () => renderCloudEnvBlock(res))
1016
+ .replace(/@@CLOUD_ENV_NOTES@@/g, () => renderCloudEnvNotes(res));
1017
+ const dst = path.join(cwd, CODEX_CLOUD_RELPATH);
1018
+ fs.mkdirSync(path.dirname(dst), { recursive: true });
1019
+ fs.writeFileSync(dst, content, "utf-8");
1020
+ fs.chmodSync(dst, 0o600);
1021
+ return true;
1022
+ }