@cbartens/bkit 0.0.0-stage → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +417 -0
  2. package/.bkit/core/.agents/context.md +95 -0
  3. package/.bkit/core/.agents/docs.md +62 -0
  4. package/.bkit/core/.agents/rules.md +147 -0
  5. package/.bkit/core/.agents/skills.md +43 -0
  6. package/.bkit/core/.bkit/LICENSE.md +151 -0
  7. package/.bkit/core/.bkit/README.md +417 -0
  8. package/.bkit/core/.bkit/cloud.md +493 -0
  9. package/.bkit/core/.bkit/comparison.md +321 -0
  10. package/.bkit/core/.bkit/install.md +401 -0
  11. package/.bkit/core/.bkit/jsonl.md +497 -0
  12. package/.bkit/core/.bkit/prompts.md +474 -0
  13. package/.bkit/core/.bkit/providers.md +598 -0
  14. package/.bkit/core/.bkit/templates.md +470 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1550 -0
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
  22. package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
  24. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
  26. package/.bkit/core/AGENTS.md +77 -0
  27. package/.bkit/core/LICENSE.md +149 -0
  28. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
  29. package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
  30. package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
  31. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
  32. package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
  33. package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
  34. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
  35. package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
  36. package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
  37. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
  38. package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
  39. package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
  40. package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
  41. package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
  42. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
  43. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
  44. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
  45. package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
  46. package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
  47. package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
  48. package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
  49. package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
  50. package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
  51. package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
  52. package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
  53. package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
  54. package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
  55. package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
  56. package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
  57. package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
  58. package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
  59. package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
  60. package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
  61. package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
  62. package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
  63. package/.bkit/core/docs/templates/bkit-plan.md +476 -0
  64. package/.bkit/core/engine/checks/after/auth.ts +149 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +701 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +530 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/suppression.ts +53 -0
  70. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +187 -0
  73. package/.bkit/core/engine/checks/before/files.ts +204 -0
  74. package/.bkit/core/engine/checks/before/index.ts +206 -0
  75. package/.bkit/core/engine/checks/before/mcp.ts +127 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +77 -0
  77. package/.bkit/core/engine/checks/before/version.ts +67 -0
  78. package/.bkit/core/engine/checks/status-holes.ts +479 -0
  79. package/.bkit/core/engine/cli.ts +867 -0
  80. package/.bkit/core/engine/commands/analysis.ts +550 -0
  81. package/.bkit/core/engine/commands/ci/ci.ts +483 -0
  82. package/.bkit/core/engine/commands/comply.ts +415 -0
  83. package/.bkit/core/engine/commands/harvest.ts +459 -0
  84. package/.bkit/core/engine/commands/install/check.ts +70 -0
  85. package/.bkit/core/engine/commands/install/doctor.ts +254 -0
  86. package/.bkit/core/engine/commands/install/install.ts +550 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +995 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1037 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +495 -0
  91. package/.bkit/core/engine/commands/registry.ts +53 -0
  92. package/.bkit/core/engine/commands/setup/setup.ts +184 -0
  93. package/.bkit/core/engine/commands/telemetry.ts +32 -0
  94. package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
  95. package/.bkit/core/engine/commands/workflow/context.ts +961 -0
  96. package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
  97. package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
  98. package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
  99. package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
  100. package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
  101. package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
  102. package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
  103. package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
  104. package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
  105. package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
  106. package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
  107. package/.bkit/core/engine/commands/workflow/status.ts +455 -0
  108. package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
  109. package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
  110. package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
  111. package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
  112. package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
  113. package/.bkit/core/engine/install/cloud-env.ts +924 -0
  114. package/.bkit/core/engine/install/managed-block.ts +212 -0
  115. package/.bkit/core/engine/install/manifest.ts +448 -0
  116. package/.bkit/core/engine/install/modules/claude.ts +362 -0
  117. package/.bkit/core/engine/install/modules/cloud.ts +173 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +620 -0
  120. package/.bkit/core/engine/install/modules/cursor.ts +231 -0
  121. package/.bkit/core/engine/install/modules/index.ts +242 -0
  122. package/.bkit/core/engine/install/modules/opencode.ts +573 -0
  123. package/.bkit/core/engine/install/payload-links.ts +150 -0
  124. package/.bkit/core/engine/install/placeholders.ts +108 -0
  125. package/.bkit/core/engine/install/template-copies.ts +119 -0
  126. package/.bkit/core/engine/install/version-file.ts +284 -0
  127. package/.bkit/core/engine/install/write.ts +467 -0
  128. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  129. package/.bkit/core/engine/ledgers/status.ts +213 -0
  130. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  131. package/.bkit/core/engine/render/hosts.ts +372 -0
  132. package/.bkit/core/engine/render/models.ts +323 -0
  133. package/.bkit/core/engine/render/parts.ts +38 -0
  134. package/.bkit/core/engine/render/trackers.ts +170 -0
  135. package/.bkit/core/engine/shared/egress.ts +345 -0
  136. package/.bkit/core/engine/shared/json.ts +16 -0
  137. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  138. package/.bkit/core/engine/shared/package-json.ts +29 -0
  139. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  140. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  141. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  142. package/.bkit/core/engine/shared/settings.ts +72 -0
  143. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  144. package/.bkit/core/engine/tools/wording.ts +748 -0
  145. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  146. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  147. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  148. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  149. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  150. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  155. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  156. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  157. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  158. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  159. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  160. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  161. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  162. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  165. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  166. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  169. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  170. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  171. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  172. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  173. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  174. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  175. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  176. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  178. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  179. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  180. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  181. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  182. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  185. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  186. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  187. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  188. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  189. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  198. package/.bkit/core/workflows/bkit-auto.md +121 -0
  199. package/.bkit/core/workflows/bkit-build.md +802 -0
  200. package/.bkit/core/workflows/bkit-debug.md +649 -0
  201. package/.bkit/core/workflows/bkit-design.md +495 -0
  202. package/.bkit/core/workflows/bkit-plan.md +510 -0
  203. package/.bkit/core/workflows/bkit-ship.md +650 -0
  204. package/.bkit/shared/.bkit/.env.example +86 -0
  205. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  206. package/.bkit/shared/.claude/settings.json +88 -0
  207. package/.bkit/shared/.codex/hooks.json +26 -0
  208. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  209. package/.bkit/shared/.cursor/hooks.json +26 -0
  210. package/.bkit/shared/.cursor/mcp.json +15 -0
  211. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  212. package/.bkit/shared/.gitattributes +37 -0
  213. package/.bkit/shared/.mcp.json +16 -0
  214. package/.bkit/shared/.opencode/opencode.json +62 -0
  215. package/.bkit/shared/CLAUDE.md +11 -0
  216. package/.bkit/shared/LICENSE.md +22 -0
  217. package/.bkit/shared/docs/architecture.md +19 -0
  218. package/.bkit/shared/docs/data-schema.md +19 -0
  219. package/.bkit/shared/docs/deployments.md +433 -0
  220. package/.bkit/shared/docs/design.md +39 -0
  221. package/.bkit/shared/docs/noise.md +19 -0
  222. package/.bkit/shared/docs/observability.md +25 -0
  223. package/.bkit/shared/docs/security.md +42 -0
  224. package/.bkit/shared/docs/setup.md +30 -0
  225. package/.bkit/shared/docs/technology.md +18 -0
  226. package/.bkit/shared/docs/testing.md +413 -0
  227. package/.bkit/shared/gitignore +97 -0
  228. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +187 -0
  229. package/.bkit/templates/.cursor/Dockerfile +68 -0
  230. package/.bkit/templates/.cursor/environment.json +6 -0
  231. package/.bkit/templates/.cursor/settings.json +11 -0
  232. package/.bkit/templates/.envrc +7 -0
  233. package/.bkit/templates/.github/dependabot.yml +52 -0
  234. package/.bkit/templates/.github/renovate.json5 +224 -0
  235. package/.bkit/templates/.github/workflows/bkit-ci.yml +1062 -0
  236. package/.bkit/templates/.github/workflows/bkit-cloud.yml +564 -0
  237. package/.bkit/templates/.github/workflows/bkit-renovate.yml +102 -0
  238. package/.bkit/templates/.graphifyignore +108 -0
  239. package/.bkit/templates/.husky/pre-commit +16 -0
  240. package/.bkit/templates/.husky/pre-push +91 -0
  241. package/.bkit/templates/.lintstagedrc.json +3 -0
  242. package/.bkit/templates/.prettierignore +41 -0
  243. package/.bkit/templates/.serena/project.yml +243 -0
  244. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  245. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  246. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  247. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  248. package/.bkit/templates/.vale.ini +67 -0
  249. package/.bkit/templates/LICENSE.md +22 -0
  250. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  251. package/.bkit/templates/context/bkit-expo.md +186 -0
  252. package/.bkit/templates/context/bkit-github.md +79 -0
  253. package/.bkit/templates/context/bkit-inngest.md +45 -0
  254. package/.bkit/templates/context/bkit-maestro.md +76 -0
  255. package/.bkit/templates/context/bkit-playwright.md +62 -0
  256. package/.bkit/templates/context/bkit-resend.md +36 -0
  257. package/.bkit/templates/context/bkit-sentry.md +65 -0
  258. package/.bkit/templates/context/bkit-serena.md +33 -0
  259. package/.bkit/templates/context/bkit-stripe.md +36 -0
  260. package/.bkit/templates/context/bkit-supabase.md +59 -0
  261. package/.bkit/templates/context/bkit-tavily.md +49 -0
  262. package/.bkit/templates/context/bkit-vercel.md +64 -0
  263. package/.bkit/templates/docs/capabilities.md +72 -0
  264. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  266. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  268. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  280. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  281. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  282. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  283. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  284. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  286. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  288. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  289. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  290. package/.bkit/templates/slop-scan.config.json +120 -0
  291. package/CHANGELOG.md +1503 -0
  292. package/LICENSE.md +161 -0
  293. package/README.md +184 -2
  294. package/dist/checks/after/auth.js +140 -0
  295. package/dist/checks/after/ci-yml.js +681 -0
  296. package/dist/checks/after/github.js +400 -0
  297. package/dist/checks/after/index.js +431 -0
  298. package/dist/checks/after/managed.js +187 -0
  299. package/dist/checks/after/suppression.js +39 -0
  300. package/dist/checks/after/tools.js +351 -0
  301. package/dist/checks/before/context-fetch.js +426 -0
  302. package/dist/checks/before/env.js +163 -0
  303. package/dist/checks/before/files.js +187 -0
  304. package/dist/checks/before/index.js +162 -0
  305. package/dist/checks/before/mcp.js +111 -0
  306. package/dist/checks/before/repo.js +71 -0
  307. package/dist/checks/before/version.js +60 -0
  308. package/dist/checks/status-holes.js +393 -0
  309. package/dist/cli.js +688 -0
  310. package/dist/commands/analysis.js +325 -0
  311. package/dist/commands/ci/ci.js +438 -0
  312. package/dist/commands/comply.js +310 -0
  313. package/dist/commands/harvest.js +354 -0
  314. package/dist/commands/install/check.js +61 -0
  315. package/dist/commands/install/doctor.js +209 -0
  316. package/dist/commands/install/install.js +475 -0
  317. package/dist/commands/install/uninstall.js +839 -0
  318. package/dist/commands/install/upgrade.js +782 -0
  319. package/dist/commands/launch.js +118 -0
  320. package/dist/commands/lib.js +363 -0
  321. package/dist/commands/registry.js +50 -0
  322. package/dist/commands/setup/setup.js +158 -0
  323. package/dist/commands/telemetry.js +29 -0
  324. package/dist/commands/workflow/branches.js +1265 -0
  325. package/dist/commands/workflow/context.js +846 -0
  326. package/dist/commands/workflow/counters.js +227 -0
  327. package/dist/commands/workflow/fids.js +224 -0
  328. package/dist/commands/workflow/issues.js +585 -0
  329. package/dist/commands/workflow/ledgers.js +472 -0
  330. package/dist/commands/workflow/locks.js +364 -0
  331. package/dist/commands/workflow/prs.js +904 -0
  332. package/dist/commands/workflow/repo.js +199 -0
  333. package/dist/commands/workflow/roadmap.js +495 -0
  334. package/dist/commands/workflow/runs.js +1717 -0
  335. package/dist/commands/workflow/runtime.js +257 -0
  336. package/dist/commands/workflow/skills.js +110 -0
  337. package/dist/commands/workflow/status.js +392 -0
  338. package/dist/commands/workflow/steps.js +1093 -0
  339. package/dist/commands/workflow/tests.js +144 -0
  340. package/dist/commands/workflow/workflows.js +1342 -0
  341. package/dist/commands/workflow/workstreams.js +141 -0
  342. package/dist/commands/workflow/worktrees.js +473 -0
  343. package/dist/install/cloud-env.js +818 -0
  344. package/dist/install/managed-block.js +182 -0
  345. package/dist/install/manifest.js +376 -0
  346. package/dist/install/modules/claude.js +288 -0
  347. package/dist/install/modules/cloud.js +151 -0
  348. package/dist/install/modules/codex.js +193 -0
  349. package/dist/install/modules/core.js +531 -0
  350. package/dist/install/modules/cursor.js +186 -0
  351. package/dist/install/modules/index.js +152 -0
  352. package/dist/install/modules/opencode.js +504 -0
  353. package/dist/install/payload-links.js +119 -0
  354. package/dist/install/placeholders.js +87 -0
  355. package/dist/install/template-copies.js +106 -0
  356. package/dist/install/version-file.js +204 -0
  357. package/dist/install/write.js +342 -0
  358. package/dist/ledgers/clamp-log.js +27 -0
  359. package/dist/ledgers/status.js +156 -0
  360. package/dist/ledgers/telemetry.js +637 -0
  361. package/dist/render/hosts.js +339 -0
  362. package/dist/render/models.js +288 -0
  363. package/dist/render/parts.js +33 -0
  364. package/dist/render/trackers.js +135 -0
  365. package/dist/shared/egress.js +299 -0
  366. package/dist/shared/json.js +16 -0
  367. package/dist/shared/log-prefix.js +7 -0
  368. package/dist/shared/package-json.js +22 -0
  369. package/dist/shared/package-manager.js +32 -0
  370. package/dist/shared/package-roots.js +145 -0
  371. package/dist/shared/protected-paths.js +153 -0
  372. package/dist/shared/settings.js +44 -0
  373. package/dist/shared/timeouts.js +19 -0
  374. package/dist/tools/wording.js +680 -0
  375. package/package.json +101 -4
@@ -0,0 +1,818 @@
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`*.
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
6
+ // stack-agnostic resolution: it reads whatever dotenv files the repo's `.envrc`
7
+ // sources, honours the `.envrc` `unset` lines, and drops session-hijack keys.
8
+ // bkit hardcodes NO stack-specific key lists — the stack knowledge lives in the
9
+ // consumer's `.envrc`, keeping bkit's shipped surface stack-independent.
10
+ //
11
+ // Excluded keys are exactly the vars `.envrc` unsets, and the review key is
12
+ // BKIT_ANTHROPIC_API_KEY — both derived here without a bespoke key list.
13
+ import * as fs from "node:fs";
14
+ import * as path from "node:path";
15
+ import { getSharedRoot } from "../shared/package-roots.js";
16
+ import { applyTokens } from "./placeholders.js";
17
+ import { BKIT_EGRESS_SOURCES } from "../shared/egress.js";
18
+ import { sha256 } from "./version-file.js";
19
+ // Consumer-relative paths of the generated docs. Shared so the upgrade template walk
20
+ // (commands/install/install.ts) can exclude them — they are generated OUTPUT files, never
21
+ // templates to reconcile. One per cloud host (Claude Code on the web / Cursor
22
+ // Background Agents); both inline resolved secrets, both gitignored + chmod 600.
23
+ export const CLAUDE_CLOUD_RELPATH = path.join(".claude", "bkit-cloud.md");
24
+ export const CURSOR_CLOUD_RELPATH = path.join(".cursor", "bkit-cloud.md");
25
+ // Session-hijack keys: exporting these into a cloud env redirects Claude Code's
26
+ // OWN model calls onto API-key billing instead of the user's subscription
27
+ // (`.bkit/cloud.md` § Environment variables). Always dropped from the paste block.
28
+ export const SESSION_HIJACK_KEYS = [
29
+ "ANTHROPIC_API_KEY",
30
+ "BKIT_ANTHROPIC_API_KEY",
31
+ "ANTHROPIC_AUTH_TOKEN",
32
+ ];
33
+ // bkit baseline env-var NAMES every Claude-on-web environment needs. Emitted as a
34
+ // placeholder ONLY when absent from the resolved `.envrc` set — a present value
35
+ // (e.g. BKIT_GH_TOKEN already in `.bkit/.env`) keeps its real resolved value.
36
+ const BASELINE_TOKEN_PLACEHOLDERS = [
37
+ ["BKIT_GH_TOKEN", "<fine-grained PAT — see .bkit/cloud.md § BKIT_GH_TOKEN permissions>"],
38
+ ];
39
+ // Earlier-compaction override — a bkit constant, not a secret. Appended to the
40
+ // block when not already resolved from a source file. Claude-harness-only knob —
41
+ // Cursor has no equivalent, so it is NOT in the Cursor policy's constants.
42
+ const AUTOCOMPACT_KEY = "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE";
43
+ const AUTOCOMPACT_VALUE = "70";
44
+ // Claude Code on the web: GitHub tracker, autocompact override.
45
+ export const CLAUDE_CLOUD_POLICY = {
46
+ baseline: BASELINE_TOKEN_PLACEHOLDERS,
47
+ constants: [[AUTOCOMPACT_KEY, AUTOCOMPACT_VALUE]],
48
+ };
49
+ // Cursor Background Agents: `BKIT_LINEAR_API_KEY` prepended for the Linear tracker
50
+ // (bkit-preflight.sh calls the Linear GraphQL API and hard-fails without it); GitHub
51
+ // tracker uses the same GH baseline as Claude, minus the autocompact knob.
52
+ const CURSOR_LINEAR_PLACEHOLDER = [
53
+ "BKIT_LINEAR_API_KEY",
54
+ "<Linear personal API key — https://linear.app/settings/api>",
55
+ ];
56
+ export function cursorCloudPolicy(tracker) {
57
+ return {
58
+ baseline: tracker === "linear"
59
+ ? [CURSOR_LINEAR_PLACEHOLDER, ...BASELINE_TOKEN_PLACEHOLDERS]
60
+ : BASELINE_TOKEN_PLACEHOLDERS,
61
+ constants: [],
62
+ };
63
+ }
64
+ /** Strip one layer of matching surrounding single/double quotes. */
65
+ function stripQuotes(v) {
66
+ const t = v.trim();
67
+ if (t.length >= 2 &&
68
+ ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")))) {
69
+ return t.slice(1, -1);
70
+ }
71
+ return t;
72
+ }
73
+ /**
74
+ * Parse an `.envrc` for the direnv directives bkit follows: `dotenv` /
75
+ * `dotenv_if_exists <file>` targets (in order), `unset <VAR...>` lines, and direct
76
+ * `export KEY=value` assignments. Arbitrary bash (conditionals, PATH_add, etc.) is
77
+ * ignored — bkit never executes the `.envrc`, it reads these declarative lines.
78
+ */
79
+ export function parseEnvrc(content) {
80
+ const dotenvFiles = [];
81
+ const unsets = [];
82
+ const exports = [];
83
+ for (const raw of content.split("\n")) {
84
+ const line = raw.trim();
85
+ if (line === "" || line.startsWith("#"))
86
+ continue;
87
+ let m;
88
+ if ((m = line.match(/^dotenv(?:_if_exists)?\s+(.+)$/))) {
89
+ dotenvFiles.push(stripQuotes(m[1].trim()));
90
+ }
91
+ else if ((m = line.match(/^unset\s+(.+)$/))) {
92
+ for (const v of m[1].split(/\s+/))
93
+ if (v)
94
+ unsets.push(v);
95
+ }
96
+ else if ((m = line.match(/^export\s+([A-Za-z_][A-Za-z0-9_]*)=(.*)$/))) {
97
+ exports.push([m[1], stripQuotes(m[2])]);
98
+ }
99
+ }
100
+ return { dotenvFiles, unsets, exports };
101
+ }
102
+ /** Parse a dotenv file into ordered KEY/value pairs (values quote-stripped). */
103
+ export function parseDotenv(content) {
104
+ const out = [];
105
+ for (const raw of content.split("\n")) {
106
+ const line = raw.trim();
107
+ if (line === "" || line.startsWith("#"))
108
+ continue;
109
+ // `(.*)$` keeps `=` characters inside the value intact.
110
+ const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
111
+ if (!m)
112
+ continue;
113
+ out.push([m[1], stripQuotes(m[2])]);
114
+ }
115
+ return out;
116
+ }
117
+ /**
118
+ * Resolve the cloud env-var set by following the consumer's `.envrc`. Later dotenv
119
+ * sources override earlier (direnv last-wins); direct `export`s win over files.
120
+ * Applies `.envrc` unsets, then drops session-hijack keys. Returns empty when no
121
+ * `.envrc` exists — the caller still emits a usable placeholder doc.
122
+ */
123
+ export function resolveCloudEnvVars(cwd, policy = CLAUDE_CLOUD_POLICY) {
124
+ const res = {
125
+ included: [],
126
+ unset: [],
127
+ hijackDropped: [],
128
+ emptySkipped: [],
129
+ placeholders: [],
130
+ sources: [],
131
+ hasEnvrc: false,
132
+ };
133
+ const envrcPath = path.join(cwd, ".envrc");
134
+ let dotenvFiles = [];
135
+ let unsets = [];
136
+ let exports = [];
137
+ if (fs.existsSync(envrcPath)) {
138
+ res.hasEnvrc = true;
139
+ ({ dotenvFiles, unsets, exports } = parseEnvrc(fs.readFileSync(envrcPath, "utf-8")));
140
+ }
141
+ // Accumulate. A Map preserves first-seen insertion order; re-setting an existing
142
+ // key updates its value in place, giving "first-seen order, last-source value".
143
+ const map = new Map();
144
+ for (const rel of dotenvFiles) {
145
+ const p = path.join(cwd, rel);
146
+ if (!fs.existsSync(p))
147
+ continue;
148
+ res.sources.push(rel);
149
+ for (const [k, v] of parseDotenv(fs.readFileSync(p, "utf-8")))
150
+ map.set(k, v);
151
+ }
152
+ for (const [k, v] of exports)
153
+ map.set(k, v);
154
+ // Honour `.envrc` unsets (record only those a source actually set).
155
+ for (const k of unsets) {
156
+ if (map.has(k)) {
157
+ res.unset.push(k);
158
+ map.delete(k);
159
+ }
160
+ }
161
+ // Drop session-hijack keys.
162
+ for (const k of SESSION_HIJACK_KEYS) {
163
+ if (map.has(k)) {
164
+ res.hijackDropped.push(k);
165
+ map.delete(k);
166
+ }
167
+ }
168
+ // Partition non-empty (included) vs empty (skipped).
169
+ for (const [k, v] of map) {
170
+ if (v === "")
171
+ res.emptySkipped.push(k);
172
+ else
173
+ res.included.push([k, v]);
174
+ }
175
+ // Baseline names absent from the resolved set → emitted as placeholders.
176
+ const present = new Set(res.included.map(([k]) => k));
177
+ for (const [name] of policy.baseline) {
178
+ if (!present.has(name))
179
+ res.placeholders.push(name);
180
+ }
181
+ return res;
182
+ }
183
+ /**
184
+ * Render the `.env`-format paste block: resolved KEY=value lines, then placeholder
185
+ * lines for any absent baseline token, then the autocompact override if unset.
186
+ */
187
+ export function renderCloudEnvBlock(res, policy = CLAUDE_CLOUD_POLICY) {
188
+ const lines = [];
189
+ for (const [k, v] of res.included)
190
+ lines.push(`${k}=${v}`);
191
+ for (const [name, placeholder] of policy.baseline) {
192
+ if (res.placeholders.includes(name))
193
+ lines.push(`${name}=${placeholder}`);
194
+ }
195
+ for (const [key, value] of policy.constants) {
196
+ if (!res.included.some(([k]) => k === key))
197
+ lines.push(`${key}=${value}`);
198
+ }
199
+ return lines.join("\n");
200
+ }
201
+ function fmtList(items) {
202
+ return items.map((x) => `\`${x}\``).join(", ");
203
+ }
204
+ /** Render the markdown notes under the env-var block (transparency for what was dropped). */
205
+ export function renderCloudEnvNotes(res) {
206
+ if (!res.hasEnvrc) {
207
+ return ("_No `.envrc` found — the block above lists only the bkit baseline token names as " +
208
+ "placeholders. Add your `.envrc` (`bkit install` seeds one) and re-run to inline real values._");
209
+ }
210
+ const bullets = [];
211
+ if (res.placeholders.length) {
212
+ bullets.push(`- **Fill in (absent from your env files):** ${fmtList(res.placeholders)} — placeholder values above.`);
213
+ }
214
+ if (res.unset.length) {
215
+ bullets.push(`- **Dropped — \`.envrc\` unsets these:** ${fmtList(res.unset)} — kept out of the cloud env by design.`);
216
+ }
217
+ if (res.hijackDropped.length) {
218
+ bullets.push(`- **Dropped — session-billing hijack:** ${fmtList(res.hijackDropped)} — would redirect the agent's own model calls onto API-key billing instead of your subscription.`);
219
+ }
220
+ if (res.emptySkipped.length) {
221
+ bullets.push(`- **Empty in source (skipped):** ${fmtList(res.emptySkipped)}`);
222
+ }
223
+ const header = `_${res.included.length} var${res.included.length === 1 ? "" : "s"} resolved${res.sources.length ? ` from ${fmtList(res.sources)}` : ""}._`;
224
+ return bullets.length ? `${header}\n\n${bullets.join("\n")}` : header;
225
+ }
226
+ /** Parse the pnpm `X.Y.Z` from `package.json` `packageManager` ("" if absent/non-pnpm). */
227
+ export function resolveConsumerPnpm(cwd) {
228
+ try {
229
+ const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
230
+ const pm = typeof pkg["packageManager"] === "string" ? pkg["packageManager"] : "";
231
+ const m = pm.match(/^pnpm@(\d+\.\d+\.\d+)/);
232
+ return m?.[1] ?? "";
233
+ }
234
+ catch {
235
+ return "";
236
+ }
237
+ }
238
+ /**
239
+ * Render the setup-script corepack line from the consumer's own `packageManager`
240
+ * pin (NOT bkit's — the pin is a snapshot pre-warm, non-load-bearing: corepack
241
+ * resolves each repo's `packageManager` in-repo). Degrades to bare `corepack
242
+ * enable` when the pin is absent.
243
+ */
244
+ export function renderCorepackLine(cwd) {
245
+ const v = resolveConsumerPnpm(cwd);
246
+ return v
247
+ ? `corepack enable && corepack prepare pnpm@${v} --activate`
248
+ : `corepack enable # pnpm resolved from package.json "packageManager" in-repo`;
249
+ }
250
+ /**
251
+ * Extract the bash body of every `context-fetch:provision <name>` block the consumer
252
+ * enabled below `<!-- bkit:end -->` in `.agents/context.md`. Stack-agnostic: bkit
253
+ * hardcodes no CLI names — the install recipe lives in the consumer's context.md,
254
+ * co-located with the fetch block that needs the CLI. `bkit context list-blocks` returns
255
+ * the same list as `provision`, which `.claude/hooks/bkit-cloud-bootstrap.sh` runs, so the web
256
+ * setup-script snapshot and the per-session hook provision the same CLIs. Returns one
257
+ * string per block (bash body).
258
+ */
259
+ export function extractContextFetchProvisionRecipes(cwd) {
260
+ const filePath = path.join(cwd, ".agents", "context.md");
261
+ if (!fs.existsSync(filePath))
262
+ return [];
263
+ const content = fs.readFileSync(filePath, "utf-8");
264
+ const endIdx = content.search(/^<!-- bkit:end -->$/m);
265
+ if (endIdx === -1)
266
+ return [];
267
+ const consumer = content.slice(endIdx);
268
+ const recipes = [];
269
+ let cur = null;
270
+ let inProv = false;
271
+ let inFence = false;
272
+ for (const line of consumer.split("\n")) {
273
+ if (/^<!-- context-fetch:provision/.test(line)) {
274
+ inProv = true;
275
+ inFence = false;
276
+ cur = [];
277
+ continue;
278
+ }
279
+ if (/^<!-- context-fetch:(start|end|none)/.test(line)) {
280
+ if (inProv && cur && cur.length > 0)
281
+ recipes.push(cur.join("\n"));
282
+ inProv = false;
283
+ inFence = false;
284
+ cur = null;
285
+ continue;
286
+ }
287
+ if (inProv && /^```/.test(line)) {
288
+ inFence = !inFence;
289
+ continue;
290
+ }
291
+ if (inProv && inFence && cur)
292
+ cur.push(line);
293
+ }
294
+ return recipes;
295
+ }
296
+ /**
297
+ * Render the `@@CLOUD_CACHE_BUST@@` line — a `# cache-bust YYYY-MM-DD-N` comment at
298
+ * the top of the setup script. claude.ai/code snapshots the setup script keyed on its
299
+ * exact text and reuses that snapshot; a changing cache-bust line forces a fresh
300
+ * snapshot on the next paste, so "latest"-resolved downloads (gh, gcloud SDK) and
301
+ * base-image drift get re-pulled even when the rest of the script is byte-identical.
302
+ * The counter increments per regeneration WITHIN a day (read back from the prior doc)
303
+ * and resets to 1 on a new date, so every regeneration yields a distinct value —
304
+ * guaranteeing a re-paste always busts. `today` (YYYY-MM-DD) is injected so the caller
305
+ * owns the clock and this stays deterministic under test.
306
+ */
307
+ export function renderCloudCacheBust(cwd, today) {
308
+ const dst = path.join(cwd, CLAUDE_CLOUD_RELPATH);
309
+ let counter = 1;
310
+ if (fs.existsSync(dst)) {
311
+ const prev = fs.readFileSync(dst, "utf-8");
312
+ const m = prev.match(/^# cache-bust (\d{4}-\d{2}-\d{2})-(\d+)$/m);
313
+ if (m && m[1] === today)
314
+ counter = Number.parseInt(m[2], 10) + 1;
315
+ }
316
+ return `# cache-bust ${today}-${counter}`;
317
+ }
318
+ /**
319
+ * `pnpm add -g` aborts ("The configured global bin directory … is not in PATH")
320
+ * unless pnpm's global-bin dir is on PATH. corepack-activated pnpm never runs
321
+ * `pnpm setup`, so under the setup script's `set -euo pipefail` a single `pnpm add
322
+ * -g <cli>` provision block kills the whole snapshot build (observed in cloud with
323
+ * `pnpm@11`). Prepend an explicit `PNPM_HOME` + PATH export so every provision
324
+ * recipe runs in a shell where `pnpm add -g` succeeds. `$PNPM_HOME` and
325
+ * `$PNPM_HOME/bin` are both added — pnpm's global-bin dir has differed by version.
326
+ */
327
+ const CLOUD_PNPM_GLOBAL_PATH_SETUP = "# pnpm refuses `add -g` unless its global-bin dir is on PATH (corepack pnpm skips `pnpm setup`).\n" +
328
+ 'export PNPM_HOME="${PNPM_HOME:-$HOME/.local/share/pnpm}"\n' +
329
+ 'export PATH="$PNPM_HOME:$PNPM_HOME/bin:$PATH"';
330
+ /**
331
+ * Render the `@@CLOUD_CONTEXT_FETCH_PROVISION@@` setup-script region: the consumer's
332
+ * `context-fetch:provision` recipes, or "" when none are enabled. Placed AFTER the
333
+ * corepack line in the template so `pnpm add -g …` recipes have pnpm available.
334
+ *
335
+ * Recipes run in a best-effort `( set +e … ) || …` subshell: the setup script is
336
+ * `set -euo pipefail`, so without this a single failing recipe (e.g. a heavy `curl |
337
+ * bash` CLI installer that trips over a missing base-image dep) aborts the whole
338
+ * snapshot build and discards every CLI provisioned before it. `set +e` also lets a
339
+ * later recipe run after an earlier one fails. Mirrors the non-blocking per-session
340
+ * hook (`… | bash || log`), keeping the two cloud provision paths behaviourally equal.
341
+ */
342
+ export function renderCloudContextFetchProvision(cwd) {
343
+ const recipes = extractContextFetchProvisionRecipes(cwd);
344
+ if (recipes.length === 0)
345
+ return "";
346
+ return ("# context-fetch CLIs (from .agents/context.md provision blocks) — self-guarded, best-effort.\n" +
347
+ CLOUD_PNPM_GLOBAL_PATH_SETUP +
348
+ "\n" +
349
+ "(\n" +
350
+ " set +e\n" +
351
+ recipes.join("\n") +
352
+ "\n" +
353
+ ') || echo "[cloud-setup] a context-fetch provision recipe failed (non-blocking); its CLI will be absent" >&2');
354
+ }
355
+ /**
356
+ * Entries of every `<!-- {tag}:start --> … <!-- {tag}:end -->` list block BELOW
357
+ * `<!-- bkit:end -->` in `.agents/context.md` — one entry per line; blank, `#` comment
358
+ * and marker lines ignored. Blocks above the marker are never read. Returns entries
359
+ * verbatim, in order.
360
+ */
361
+ function extractConsumerListBlock(cwd, tag) {
362
+ const filePath = path.join(cwd, ".agents", "context.md");
363
+ if (!fs.existsSync(filePath))
364
+ return [];
365
+ const content = fs.readFileSync(filePath, "utf-8");
366
+ const endIdx = content.search(/^<!-- bkit:end -->$/m);
367
+ if (endIdx === -1)
368
+ return [];
369
+ const consumer = content.slice(endIdx);
370
+ const entries = [];
371
+ let inBlock = false;
372
+ for (const line of consumer.split("\n")) {
373
+ if (line.startsWith(`<!-- ${tag}:start`)) {
374
+ inBlock = true;
375
+ continue;
376
+ }
377
+ if (line.startsWith(`<!-- ${tag}:end`) || line.startsWith(`<!-- ${tag}:none`)) {
378
+ inBlock = false;
379
+ continue;
380
+ }
381
+ if (!inBlock)
382
+ continue;
383
+ const t = line.trim();
384
+ if (!t || t.startsWith("#") || t.startsWith("<!--"))
385
+ continue;
386
+ entries.push(t);
387
+ }
388
+ return entries;
389
+ }
390
+ /**
391
+ * Cloud network-allowlist domains the consumer declared in `allowed-domains` blocks
392
+ * (one registrable domain per line). Stack-agnostic: bkit hardcodes no domains — the
393
+ * consumer declares which log-backend / API / app hosts their cloud sessions must
394
+ * reach. Returns declared entries verbatim (pre-expansion), in order.
395
+ */
396
+ export function extractAllowedDomains(cwd) {
397
+ return extractConsumerListBlock(cwd, "allowed-domains");
398
+ }
399
+ /**
400
+ * MCP server names the consumer declared in `mcp-servers` blocks (one per line,
401
+ * spelled exactly as each host names the server in its tool ids). Every tool on a
402
+ * listed server is pre-approved on every host — see `.bkit/providers.md` § MCP
403
+ * servers. Deduplicated, declaration order kept.
404
+ */
405
+ export function extractMcpServers(cwd) {
406
+ return [...new Set(extractConsumerListBlock(cwd, "mcp-servers"))];
407
+ }
408
+ /**
409
+ * Expand each declared registrable domain to BOTH the apex and a `*.` wildcard so the
410
+ * WHOLE domain is allowlisted — the egress proxy matches apex and subdomains
411
+ * separately, so `inngest.com` alone misses `api.inngest.com` and vice-versa. A
412
+ * consumer entry already written as `*.x` is normalised to its apex `x` first, then
413
+ * both forms are emitted. Grouped apex-then-wildcard per domain, domains sorted.
414
+ */
415
+ export function expandAllowedDomains(declared) {
416
+ const bases = [
417
+ ...new Set(declared.map((d) => d.replace(/^\*\./, "").trim()).filter(Boolean)),
418
+ ].sort();
419
+ return bases.flatMap((b) => [b, `*.${b}`]);
420
+ }
421
+ /** True for a bracketed IPv6 literal or a dotted-quad IPv4 literal. */
422
+ export function isIpLiteral(host) {
423
+ return host.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
424
+ }
425
+ /**
426
+ * Propose the registrable base for a provider `baseURL`, or `""` when the URL
427
+ * contributes no allowlistable host. `URL.canParse` gates the parse, so this never
428
+ * throws and carries no `try` / `catch`; an unparseable value contributes nothing.
429
+ *
430
+ * Contributes nothing for an empty host, `localhost` and its subdomains, an IP
431
+ * literal, and any host of fewer than two labels: none of those is reachable through
432
+ * a cloud egress allowlist. Everything else collapses to its last two labels.
433
+ *
434
+ * The collapse is the naive last-two-labels rule. Multi-label public suffixes and
435
+ * shared-tenant apexes are a DENY at authoring time in the registry gate test, never a
436
+ * base rewrite here.
437
+ */
438
+ export function proposeEgressBase(baseURL) {
439
+ if (!URL.canParse(baseURL))
440
+ return "";
441
+ const host = new URL(baseURL).hostname;
442
+ if (host === "" || isIpLiteral(host))
443
+ return "";
444
+ if (host === "localhost" || host.endsWith(".localhost"))
445
+ return "";
446
+ const labels = host.split(".");
447
+ if (labels.length < 2)
448
+ return "";
449
+ return labels.slice(-2).join(".");
450
+ }
451
+ /**
452
+ * Sorted-unique `hosts` and `bases` across a set of egress sources. Pure: takes the
453
+ * rows rather than reading {@link BKIT_EGRESS_SOURCES}, so a test can inject a fixture
454
+ * set without mocking the module.
455
+ */
456
+ export function deriveEgressEntries(rows) {
457
+ return {
458
+ hosts: [...new Set(rows.flatMap((r) => r.hosts))].sort(),
459
+ bases: [...new Set(rows.flatMap((r) => r.bases))].sort(),
460
+ };
461
+ }
462
+ /**
463
+ * Stack-agnostic tooling bases, derived from {@link BKIT_EGRESS_SOURCES} rather than
464
+ * hand-typed — adding a provider, tracker or shipped tooling host updates this export
465
+ * by editing one registry row. **Never** ship observability / app stacks here (Vercel,
466
+ * Supabase, Sentry, …) — those come solely from the consumer's `.agents/context.md`
467
+ * `allowed-domains` block (after `<!-- bkit:end -->`) via {@link resolveNetworkAllowlist}.
468
+ */
469
+ export const BKIT_SHIPPED_NETWORK_DOMAINS = deriveEgressEntries(BKIT_EGRESS_SOURCES).bases;
470
+ /**
471
+ * The exact hostnames behind {@link BKIT_SHIPPED_NETWORK_DOMAINS}. Consumers of the
472
+ * base list allowlist a whole domain; this is the narrower set, for surfaces that
473
+ * match a literal host.
474
+ */
475
+ export const BKIT_SHIPPED_NETWORK_HOSTS = deriveEgressEntries(BKIT_EGRESS_SOURCES).hosts;
476
+ /**
477
+ * Apex-only unique bases from an expanded (apex + `*.`) domain list.
478
+ *
479
+ * Single call site (injectOpencodeDerivedAllows in install/modules/index.ts). Same apex-collapse
480
+ * shape as expandAllowedDomains above.
481
+ */
482
+ export function networkAllowlistBases(expanded) {
483
+ return [...new Set(expanded.map((d) => d.replace(/^\*\./, "").trim()).filter(Boolean))].sort();
484
+ }
485
+ /**
486
+ * Local + cloud network allowlist: stack-agnostic tooling defaults ∪ consumer
487
+ * `allowed-domains` from `.agents/context.md` (after `<!-- bkit:end -->`), each as
488
+ * apex + `*.` wildcard. Empty consumer block ⇒ tooling hosts only — no Vercel/etc.
489
+ */
490
+ export function resolveNetworkAllowlist(cwd) {
491
+ return expandAllowedDomains([...BKIT_SHIPPED_NETWORK_DOMAINS, ...extractAllowedDomains(cwd)]);
492
+ }
493
+ /**
494
+ * Every `permissions.allow` row bkit derives into `.claude/settings.json`: one
495
+ * `WebFetch(domain:…)` per {@link resolveNetworkAllowlist} entry, then two MCP rows per
496
+ * {@link extractMcpServers} entry — `mcp__<s>__*` (`.mcp.json` servers, and claude.ai
497
+ * connectors in cloud sessions) and `mcp__claude_ai_<s>__*` (claude.ai connectors in
498
+ * the local CLI). Single source for install / upgrade enrichment and uninstall strip.
499
+ */
500
+ export function resolveClaudeDerivedAllows(cwd) {
501
+ return [
502
+ ...resolveNetworkAllowlist(cwd).map((d) => `WebFetch(domain:${d})`),
503
+ ...extractMcpServers(cwd).flatMap((s) => [`mcp__${s}__*`, `mcp__claude_ai_${s}__*`]),
504
+ ];
505
+ }
506
+ /** Cursor-relative path of the install-written curl/wget allowlist (guardrails). */
507
+ export const NETWORK_ALLOWLIST_RELPATH = path.join(".cursor", "allowlist.json");
508
+ /**
509
+ * Write `.cursor/allowlist.json` for Cursor `bkit-guardrails.cjs` (runtime curl/wget host
510
+ * checks). Claude/OpenCode bake the same domain set into their own configs at
511
+ * install/upgrade — they do not read this file. Call only when the cursor module
512
+ * is installed (do not create `.cursor/` for claude-only consumers).
513
+ */
514
+ export function writeNetworkAllowlistArtifact(cwd, dryRun) {
515
+ const domains = resolveNetworkAllowlist(cwd);
516
+ const rel = NETWORK_ALLOWLIST_RELPATH;
517
+ return { path: rel, domains, wrote: writeGeneratedJson(cwd, rel, { domains }, dryRun) };
518
+ }
519
+ /** Cursor-relative path of the install-written Cursor CLI permissions (MCP allows). */
520
+ export const CURSOR_CLI_PERMISSIONS_RELPATH = path.join(".cursor", "cli.json");
521
+ /**
522
+ * Write `.cursor/cli.json` — the project-level Cursor CLI / cloud-agent permissions —
523
+ * with one `Mcp(<server>:*)` allow per {@link extractMcpServers} entry. bkit-owned and
524
+ * regenerated whole, like `.cursor/allowlist.json`: hand edits do not survive, the
525
+ * `mcp-servers` block is the source. Call only when the cursor module is installed.
526
+ */
527
+ export function writeCursorCliPermissionsArtifact(cwd, dryRun) {
528
+ const allow = extractMcpServers(cwd).map((s) => `Mcp(${s}:*)`);
529
+ const rel = CURSOR_CLI_PERMISSIONS_RELPATH;
530
+ const doc = { permissions: { allow, deny: [] } };
531
+ return { path: rel, wrote: writeGeneratedJson(cwd, rel, doc, dryRun) };
532
+ }
533
+ /**
534
+ * Write a whole-file generated JSON artifact. Returns whether the on-disk bytes differ
535
+ * from the rendered body — under `dryRun` that is computed without writing, so dry
536
+ * and real runs report the identical write set (the `bkit check` drift signal).
537
+ */
538
+ function writeGeneratedJson(cwd, rel, doc, dryRun) {
539
+ const abs = path.join(cwd, rel);
540
+ const body = JSON.stringify(doc, null, 2) + "\n";
541
+ const prev = fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
542
+ if (prev === body)
543
+ return false;
544
+ if (!dryRun) {
545
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
546
+ fs.writeFileSync(abs, body, "utf-8");
547
+ }
548
+ return true;
549
+ }
550
+ /**
551
+ * 8-hex fingerprint of the DERIVED egress set only — bases and hosts, sorted, never
552
+ * the consumer union. Hosts are included (the Cursor paste is hosts-only). Editing
553
+ * `allowed-domains` never moves it; editing a registry row does.
554
+ */
555
+ export function egressFingerprint() {
556
+ const derived = [
557
+ ...new Set([...BKIT_SHIPPED_NETWORK_DOMAINS, ...BKIT_SHIPPED_NETWORK_HOSTS]),
558
+ ].sort();
559
+ return sha256(derived.join("\n")).slice(0, 8);
560
+ }
561
+ /**
562
+ * Render the `@@CLOUD_NETWORK_ALLOWLIST@@` region — the whole `## Network access`
563
+ * body. Always emits a **Custom** paste block: the list is the derived shipped bases
564
+ * union whatever the consumer declared, so it is never empty and there is no
565
+ * zero-declaration branch. Declaring nothing narrows the list, it does not change the
566
+ * instruction.
567
+ */
568
+ export function renderCloudNetworkAllowlist(cwd) {
569
+ const declared = extractAllowedDomains(cwd);
570
+ const domains = resolveNetworkAllowlist(cwd);
571
+ const derivedCount = BKIT_SHIPPED_NETWORK_DOMAINS.length;
572
+ const declaredNote = declared.length === 0
573
+ ? "\n\n_No `allowed-domains` block is declared in `.agents/context.md`. The list above is\n" +
574
+ "bkit's own shipped hosts. If you run cloud `/bkit-debug` or e2e against a deployment,\n" +
575
+ "declare your log-backend + app domains there (apex per line) and they join this list._"
576
+ : "";
577
+ return ("Set to **Custom** and tick **Also include default list of common package\n" +
578
+ "managers** — this EXTENDS the trusted defaults (package registries, GitHub,\n" +
579
+ "cloud SDKs), it does not replace them. Paste into the **Allowed domains** field\n" +
580
+ "(one per line):\n\n" +
581
+ "```text\n" +
582
+ domains.join("\n") +
583
+ "\n```\n\n" +
584
+ `_${domains.length} entries — ${derivedCount} derived from bkit's shipped egress registry ` +
585
+ `and ${declared.length} declared in \`allowed-domains\` in \`.agents/context.md\`, ` +
586
+ "each as apex + `*.` wildcard. Derived set fingerprint `" +
587
+ egressFingerprint() +
588
+ "`._" +
589
+ declaredNote +
590
+ "\n\nUnder **Trusted**, your app domains and most observability / API hosts are\n" +
591
+ "unreachable, so cloud `/bkit-debug` gets no runtime logs and e2e can't hit your\n" +
592
+ "deployment. **Full** works too but opens all egress.");
593
+ }
594
+ /**
595
+ * Parent directory Claude Code on the web clones a repo into.
596
+ *
597
+ * Observed on the current image (`/home/user/<repo-name>`, agent running as uid=0
598
+ * with `HOME=/root`) and NOT a documented contract: no environment variable in the
599
+ * container names the repo root. The setup script bakes the resolved path and
600
+ * `bkit-cloud-bootstrap.sh` checks the DISCOVERED one, warning loudly on mismatch.
601
+ */
602
+ const CLOUD_REPO_PARENT = "/home/user";
603
+ /** The path {@link renderCloudWorkspaceTrust} bakes into the setup script. */
604
+ export function cloudRepoPath(cwd) {
605
+ return `${CLOUD_REPO_PARENT}/${path.basename(path.resolve(cwd))}`;
606
+ }
607
+ /**
608
+ * Render the `@@CLOUD_WORKSPACE_TRUST@@` setup-script region — the workspace-trust flip.
609
+ *
610
+ * `permissions.allow` and `permissions.additionalDirectories` in a project's
611
+ * `.claude/settings.json` GRANT capability, so Claude Code applies them only once the
612
+ * workspace trust dialog has been accepted — and it never shows that dialog in a
613
+ * `claude -p` or SDK session. (`deny` and `ask` are unaffected; they only restrict.)
614
+ *
615
+ * Runs in the setup script: as root, before the clone, before Claude Code starts, with
616
+ * its filesystem snapshotted. Settings resolve before SessionStart, and `.claude/` is a
617
+ * protected path allow rules never pre-approve.
618
+ *
619
+ * Merges into the file (it may or may not exist at snapshot time, and Claude Code
620
+ * stores its own state alongside the key on first run).
621
+ */
622
+ export function renderCloudWorkspaceTrust(cwd) {
623
+ const repoPath = cloudRepoPath(cwd);
624
+ return ("# Workspace trust. Without this Claude Code IGNORES every permissions.allow row in\n" +
625
+ "# .claude/settings.json — it only applies them once the trust dialog is accepted, and\n" +
626
+ "# cloud sessions never show that dialog. deny/ask are unaffected. Nothing inside the\n" +
627
+ "# session can set this: settings resolve before SessionStart, and .claude/ is a\n" +
628
+ "# protected path that allow rules never pre-approve.\n" +
629
+ 'CLAUDE_JSON="${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json"\n' +
630
+ 'mkdir -p "$(dirname "$CLAUDE_JSON")"\n' +
631
+ '[ -f "$CLAUDE_JSON" ] || printf \'{}\' > "$CLAUDE_JSON"\n' +
632
+ `jq --arg p '${repoPath}' '.projects[$p].hasTrustDialogAccepted = true' \\\n` +
633
+ ' "$CLAUDE_JSON" > "$CLAUDE_JSON.tmp" && mv "$CLAUDE_JSON.tmp" "$CLAUDE_JSON"');
634
+ }
635
+ /**
636
+ * Environment entries seeded into `~/.claude/settings.json` by {@link renderCloudUserSettings}.
637
+ *
638
+ * `"$defaults"` is NOT optional: omitting it replaces the entire built-in list for that
639
+ * section, which for `environment` discards every built-in trust slot (including
640
+ * "Trusted repo"). It is always emitted first, and asserted in the tests.
641
+ *
642
+ * Unconfigured, the classifier trusts only the working repo and its configured remotes,
643
+ * and `Host containment` defaults to "an ordinary developer machine or CI runner with
644
+ * open internet". These entries name the context-fetch hosts, the egress-allowlisted
645
+ * sandbox, and the session's identity.
646
+ */
647
+ export function cloudAutoModeEnvironment(cwd) {
648
+ const entries = [
649
+ "$defaults",
650
+ "Host containment: Claude Code runs inside the Claude Code on the web sandbox — a " +
651
+ "single-tenant container with no neighbouring workloads to reach, and egress " +
652
+ "restricted to the allowed-domains list configured on that environment. The cloud " +
653
+ "metadata endpoint is not used and should stay unreachable. The only credentials " +
654
+ "in the session are the environment variables set in the Claude app, so nothing " +
655
+ "should ever request credentials belonging to the host itself.",
656
+ ];
657
+ const bases = networkAllowlistBases(resolveNetworkAllowlist(cwd));
658
+ if (bases.length > 0) {
659
+ entries.push(`Trusted internal domains: ${bases.join(", ")} — all on the egress allowlist for ` +
660
+ "this environment, rendered from declarations in this repository, and the hosts " +
661
+ "context-fetch blocks read logs and diagnostics from during /bkit-debug.");
662
+ }
663
+ // Apostrophes would terminate the single-quoted `--argjson` literal in the generated
664
+ // setup script; keep the seeded prose free of them (asserted in the tests).
665
+ return entries;
666
+ }
667
+ /**
668
+ * Render the `@@CLOUD_USER_SETTINGS@@` setup-script region — the auto-mode classifier config.
669
+ *
670
+ * Written host-side: the classifier does NOT read `autoMode` from `.claude/settings.json`
671
+ * or `.claude/settings.local.json`.
672
+ *
673
+ * Seeds with `//=`, not `=`: a consumer's own `autoMode.environment` is never stomped by a
674
+ * re-pasted setup script, and later bkit changes to the seeded entries do not reach a
675
+ * container that already has them.
676
+ */
677
+ export function renderCloudUserSettings(cwd) {
678
+ const env = JSON.stringify(cloudAutoModeEnvironment(cwd));
679
+ return ("# Auto-mode classifier config. The classifier does NOT read `autoMode` from\n" +
680
+ "# .claude/settings.json or .claude/settings.local.json — deliberately, so a checked-in\n" +
681
+ "# repo cannot inject its own classifier rules — so this cannot be shipped in the repo.\n" +
682
+ "# Seeded with //= so a consumer's existing entries are never overwritten.\n" +
683
+ 'CLAUDE_SETTINGS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"\n' +
684
+ 'mkdir -p "$(dirname "$CLAUDE_SETTINGS")"\n' +
685
+ '[ -f "$CLAUDE_SETTINGS" ] || printf \'{}\' > "$CLAUDE_SETTINGS"\n' +
686
+ `jq --argjson e '${env}' '.autoMode.environment //= $e' \\\n` +
687
+ ' "$CLAUDE_SETTINGS" > "$CLAUDE_SETTINGS.tmp" && mv "$CLAUDE_SETTINGS.tmp" "$CLAUDE_SETTINGS"');
688
+ }
689
+ /**
690
+ * Generate `.claude/bkit-cloud.md` — a copy-paste-ready Claude Code on the web setup doc
691
+ * with the env-var block resolved to REAL VALUES from the consumer's `.envrc`.
692
+ *
693
+ * The file is gitignored + chmod 600 and holds live secrets: it is UNTRACKED (not
694
+ * pushed to any WriteSet / manifest / canonicalHashes) so it never enters `bkit
695
+ * check` drift or the upgrade template walk — its values are machine-local and
696
+ * expected to differ. Shared by install (runClaudeModule) and upgrade so a rotated
697
+ * secret or version bump reaches the doc either way. Callers MUST guard on
698
+ * `!dryRun` (never write secrets during `bkit check` / `--dry-run`) and on the
699
+ * claude host being installed. Returns true when a file was written (false when the
700
+ * template is absent). Never logs the resolved values.
701
+ */
702
+ export function writeClaudeCloudDoc(cwd, tokens) {
703
+ const src = path.join(getSharedRoot(), ".claude", "bkit-cloud.md");
704
+ if (!fs.existsSync(src))
705
+ return false;
706
+ const res = resolveCloudEnvVars(cwd);
707
+ // UTC day drives the cache-bust; renderCloudCacheBust reads the PRIOR dst below to
708
+ // continue the per-day counter, before dst is overwritten.
709
+ const today = new Date().toISOString().slice(0, 10);
710
+ // Function-form replacers: resolved secret values may contain `$`, which a string
711
+ // replacement would interpret ($&, $1, …).
712
+ const content = applyTokens(fs.readFileSync(src, "utf-8"), tokens)
713
+ .replace(/@@CLOUD_CACHE_BUST@@/g, () => renderCloudCacheBust(cwd, today))
714
+ .replace(/@@CLOUD_NETWORK_ALLOWLIST@@/g, () => renderCloudNetworkAllowlist(cwd))
715
+ .replace(/@@CLOUD_WORKSPACE_TRUST@@/g, () => renderCloudWorkspaceTrust(cwd))
716
+ .replace(/@@CLOUD_USER_SETTINGS@@/g, () => renderCloudUserSettings(cwd))
717
+ .replace(/@@CLOUD_COREPACK@@/g, () => renderCorepackLine(cwd))
718
+ .replace(/@@CLOUD_CONTEXT_FETCH_PROVISION@@/g, () => renderCloudContextFetchProvision(cwd))
719
+ .replace(/@@CLOUD_ENV_VARS@@/g, () => renderCloudEnvBlock(res))
720
+ .replace(/@@CLOUD_ENV_NOTES@@/g, () => renderCloudEnvNotes(res));
721
+ const dst = path.join(cwd, CLAUDE_CLOUD_RELPATH);
722
+ fs.mkdirSync(path.dirname(dst), { recursive: true });
723
+ fs.writeFileSync(dst, content, "utf-8");
724
+ fs.chmodSync(dst, 0o600);
725
+ return true;
726
+ }
727
+ /**
728
+ * Render the `@@CURSOR_CONTEXT_FETCH@@` region of `.cursor/bkit-cloud.md`: the consumer's
729
+ * `context-fetch:provision` recipes formatted for the Cursor mechanic, or "" when none
730
+ * are enabled. On Claude these CLIs are baked into the pasted setup script (see
731
+ * renderCloudContextFetchProvision); Cursor has no setup script, so — to keep the two
732
+ * cloud environments aligned — the same recipes are surfaced as a copy-paste block for
733
+ * the per-snapshot `install` command in `.cursor/environment.json`. The recipes are
734
+ * already idempotent (`command -v X || pnpm add -g X`), so they are safe to re-run on
735
+ * every snapshot build. Reuses the SAME extractor as the Claude path so the two clouds
736
+ * never diverge on which CLIs they provision.
737
+ */
738
+ export function renderCursorContextFetchProvision(cwd) {
739
+ const recipes = extractContextFetchProvisionRecipes(cwd);
740
+ // Empty → "" and the template's sentinel line collapses to a single blank between
741
+ // sections; non-empty → a self-contained section with its own leading/trailing blank.
742
+ if (recipes.length === 0)
743
+ return "";
744
+ return ("\n## Context-fetch CLIs (parity with the Claude setup script)\n\n" +
745
+ "Your `.agents/context.md` declares these context-fetch CLIs. The Claude setup script\n" +
746
+ "bakes them into its snapshot; for the SAME tools on Cursor, chain them into the\n" +
747
+ "`install` command in `.cursor/environment.json` (idempotent — safe every rebuild):\n\n" +
748
+ "```bash\n" +
749
+ recipes.join("\n") +
750
+ "\n```\n");
751
+ }
752
+ /**
753
+ * Render the `@@CURSOR_NETWORK@@` region — Cursor Cloud Agents DO have an egress
754
+ * allowlist (dashboard → Security: "Allow all" / "Default + allowlist" / "Allowlist
755
+ * only"), unlike the earlier assumption. Reuses the SAME declared `allowed-domains`
756
+ * as the Claude side, but — critically — does NOT apply Claude's apex+`*.`
757
+ * expansion: Cursor's own docs warn that a broad wildcard (`*.s3….amazonaws.com`)
758
+ * opens egress far wider than intended, so the declared apex entries are emitted
759
+ * verbatim with a note to add only the specific subdomains you need.
760
+ */
761
+ export function renderCursorNetworkAllowlist(cwd) {
762
+ const declared = extractAllowedDomains(cwd);
763
+ // Exact hosts, never apex + `*.`: Cursor's own docs warn a broad wildcard opens
764
+ // egress far wider than intended, so the shipped set contributes its HOSTS here
765
+ // while the Claude side takes the wildcard-expanded bases.
766
+ const entries = [...new Set([...BKIT_SHIPPED_NETWORK_HOSTS, ...declared])].sort();
767
+ return ("If your org runs Cloud Agents in **Allowlist only** / **Default + allowlist** mode\n" +
768
+ "(dashboard → **Security**), add these hosts so cloud `/bkit-debug` + e2e can reach\n" +
769
+ "bkit's own tooling and your app and log backends:\n\n" +
770
+ "```text\n" +
771
+ entries.join("\n") +
772
+ "\n```\n\n" +
773
+ `_${entries.length} host(s) — ${BKIT_SHIPPED_NETWORK_HOSTS.length} derived from bkit's shipped ` +
774
+ `egress registry and ${declared.length} declared in \`allowed-domains\` in ` +
775
+ "`.agents/context.md`. Derived set fingerprint `" +
776
+ egressFingerprint() +
777
+ "`._ Add only the\n" +
778
+ "specific subdomains you need (e.g. `api.example.com`) — Cursor warns that a broad `*.`\n" +
779
+ "wildcard opens egress far wider than intended. (The Claude side auto-expands to apex + `*.`;\n" +
780
+ "Cursor's allowlist is deliberately narrower.)");
781
+ }
782
+ /**
783
+ * Generate `.cursor/bkit-cloud.md` — the Cursor Cloud Agents analogue of
784
+ * `.claude/bkit-cloud.md`. Both describe the SAME bkit cloud environment; only the
785
+ * mechanics differ. On Claude the doc carries a pasted setup script + network
786
+ * selector; on Cursor the toolchain lives in `.cursor/Dockerfile` + the per-snapshot
787
+ * `.cursor/environment.json` `install` (both committed, nothing to paste), so this doc
788
+ * is narrower: it resolves the **dashboard environment variables** to real values from
789
+ * the consumer's `.envrc` (Cursor policy — Linear tracker adds `BKIT_LINEAR_API_KEY`, no
790
+ * autocompact knob) and surfaces any context-fetch CLIs for parity.
791
+ *
792
+ * Like `.claude/bkit-cloud.md` it is gitignored + chmod 600 and UNTRACKED (never pushed to
793
+ * any WriteSet / manifest / canonicalHashes) — its values are machine-local and
794
+ * expected to differ, so it never enters `bkit check` drift or the upgrade template
795
+ * walk. Shared by install (runCursorModule) and upgrade. Callers MUST guard on
796
+ * `!dryRun` (never write secrets during `bkit check` / `--dry-run`) and on the cursor
797
+ * host being installed. Returns true when a file was written (false when the template
798
+ * is absent). Never logs the resolved values.
799
+ */
800
+ export function writeCursorCloudDoc(cwd, tokens, tracker) {
801
+ const src = path.join(getSharedRoot(), ".cursor", "bkit-cloud.md");
802
+ if (!fs.existsSync(src))
803
+ return false;
804
+ const policy = cursorCloudPolicy(tracker);
805
+ const res = resolveCloudEnvVars(cwd, policy);
806
+ // Function-form replacers: resolved secret values may contain `$`, which a string
807
+ // replacement would interpret ($&, $1, …).
808
+ const content = applyTokens(fs.readFileSync(src, "utf-8"), tokens)
809
+ .replace(/@@CLOUD_ENV_VARS@@/g, () => renderCloudEnvBlock(res, policy))
810
+ .replace(/@@CLOUD_ENV_NOTES@@/g, () => renderCloudEnvNotes(res))
811
+ .replace(/@@CURSOR_NETWORK@@/g, () => renderCursorNetworkAllowlist(cwd))
812
+ .replace(/@@CURSOR_CONTEXT_FETCH@@/g, () => renderCursorContextFetchProvision(cwd));
813
+ const dst = path.join(cwd, CURSOR_CLOUD_RELPATH);
814
+ fs.mkdirSync(path.dirname(dst), { recursive: true });
815
+ fs.writeFileSync(dst, content, "utf-8");
816
+ fs.chmodSync(dst, 0o600);
817
+ return true;
818
+ }