@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,867 @@
1
+ #!/usr/bin/env node
2
+ // cli.ts — the `bkit` bin: parseArgs + printUsage for the v4-3 module-flag CLI surface, and
3
+ // main(), which dispatches each verb to its command and runs when this file is executed.
4
+
5
+ import * as fs from "node:fs";
6
+ import { fileURLToPath } from "node:url";
7
+ import { ISSUE_TRACKERS, type IssueTracker, parseIssueTracker } from "./install/manifest.js";
8
+ import { COMMANDS } from "./commands/registry.js";
9
+ import { LOG_PREFIX, setLogPrefix } from "./shared/log-prefix.js";
10
+ import { runCommand } from "./commands/lib.js";
11
+ import { launchApp } from "./commands/launch.js";
12
+ import { runStatus, runDoctor } from "./commands/install/doctor.js";
13
+ import { runComplyCommand } from "./commands/comply.js";
14
+ import { runHarvestCommand } from "./commands/harvest.js";
15
+ import { runAnalysisCommand } from "./commands/analysis.js";
16
+ import { runTelemetryCommand } from "./commands/telemetry.js";
17
+ import { runUpgradeCommand } from "./commands/install/upgrade.js";
18
+ import { runUninstallCommand } from "./commands/install/uninstall.js";
19
+ import { runInstall } from "./commands/install/install.js";
20
+ import { OPTIN_MODULES } from "./install/manifest.js";
21
+ import { OPENCODE_PROVIDERS } from "./shared/egress.js";
22
+
23
+ export type ModuleFlag = "core" | "claude" | "cursor" | "opencode" | "codex" | "cloud";
24
+
25
+ /** Cloud-agent variant chosen via `--auto=<variant>`. */
26
+ export const CLOUD_VARIANTS = ["claude", "cursor", "opencode"] as const;
27
+ export type CloudVariant = (typeof CLOUD_VARIANTS)[number];
28
+
29
+ /** Narrow an unknown string to `CloudVariant` or return `null` if invalid. */
30
+ export function parseCloudVariant(value: unknown): CloudVariant | null {
31
+ return typeof value === "string" && (CLOUD_VARIANTS as readonly string[]).includes(value)
32
+ ? (value as CloudVariant)
33
+ : null;
34
+ }
35
+
36
+ /**
37
+ * The first words `parseArgs` treats as a verb. A `bkit <noun> <verb>` command whose
38
+ * noun is also listed here routes only when its second word is one of its verbs.
39
+ */
40
+ export const CLASSIC_VERBS: ReadonlySet<string> = new Set([
41
+ "install",
42
+ "check",
43
+ "doctor",
44
+ "status",
45
+ "uninstall",
46
+ "upgrade",
47
+ "comply",
48
+ "harvest",
49
+ "analysis",
50
+ "telemetry",
51
+ "cursor",
52
+ "opencode",
53
+ "help",
54
+ ]);
55
+
56
+ export type Verb =
57
+ | "install"
58
+ | "check"
59
+ | "doctor"
60
+ | "status"
61
+ | "uninstall"
62
+ | "upgrade"
63
+ | "cursor"
64
+ | "opencode"
65
+ | "comply"
66
+ | "harvest"
67
+ | "analysis"
68
+ | "telemetry"
69
+ | "help";
70
+
71
+ // ---------------------------------------------------------------------------
72
+ // telemetry — sub-verb for bkit telemetry <subverb>
73
+ // ---------------------------------------------------------------------------
74
+
75
+ /** Valid sub-verbs accepted by `bkit telemetry <subverb>`. */
76
+ export const TELEMETRY_SUBVERBS = ["summary"] as const;
77
+ export type TelemetrySubverb = (typeof TELEMETRY_SUBVERBS)[number];
78
+
79
+ /** Narrow an unknown string to `TelemetrySubverb` or return null if invalid. */
80
+ export function parseTelemetrySubverb(value: unknown): TelemetrySubverb | null {
81
+ return typeof value === "string" && (TELEMETRY_SUBVERBS as readonly string[]).includes(value)
82
+ ? (value as TelemetrySubverb)
83
+ : null;
84
+ }
85
+
86
+ // ---------------------------------------------------------------------------
87
+ // comply — compliance grader phases
88
+ // ---------------------------------------------------------------------------
89
+
90
+ /** Valid workflow phases accepted by `bkit comply --phase <phase>`. */
91
+ export const COMPLY_PHASES = ["design", "plan", "build", "debug", "ship"] as const;
92
+ export type ComplyPhase = (typeof COMPLY_PHASES)[number];
93
+
94
+ /** Narrow an unknown string to `ComplyPhase` or return null if invalid. */
95
+ export function parseComplyPhase(value: unknown): ComplyPhase | null {
96
+ return typeof value === "string" && (COMPLY_PHASES as readonly string[]).includes(value)
97
+ ? (value as ComplyPhase)
98
+ : null;
99
+ }
100
+
101
+ export interface ParsedArgs {
102
+ verb: Verb;
103
+ /**
104
+ * Resolved module set to dispatch (core implicit; opt-ins + core on a bare uninstall).
105
+ * See resolveModules.
106
+ */
107
+ modules: Set<ModuleFlag>;
108
+ /**
109
+ * The module flags the user EXPLICITLY named, as internal module names (core is
110
+ * never here — it is implicit). Drives the install "≥1 flag required" guard and the
111
+ * check/upgrade "no module flags" guard in main(). `--tracker` / `--auto-revert` are
112
+ * modifiers and are NOT counted here.
113
+ */
114
+ moduleFlags: Set<ModuleFlag>;
115
+ /** Uninstall-specific flags (only populated when verb === "uninstall"). */
116
+ uninstallFlags: UninstallFlags;
117
+ /** Upgrade-specific flags (only populated when verb === "upgrade"). */
118
+ upgradeFlags: UpgradeFlags;
119
+ /** Issue tracker selected via `--tracker=<name>`. null = not specified (use manifest field or default). */
120
+ tracker: IssueTracker | null;
121
+ /** Cloud variant selected via `--auto=claude|cursor`. null = not specified. */
122
+ cloudVariant: CloudVariant | null;
123
+ /**
124
+ * opencode provider selected via `--opencode=<provider>`. null = not specified.
125
+ * Supported: see OPENCODE_PROVIDERS — strict allowlist (openrouter, ollama,
126
+ * opencode-zen, opencode-go).
127
+ * Required when installing the opencode module (additive host, opt-in).
128
+ */
129
+ opencodeProvider: string | null;
130
+ /**
131
+ * Compliance-grader phase selected via `--phase=<phase>`.
132
+ * Only populated when verb === "comply". null = not specified / not applicable.
133
+ * Valid values: design | plan | build | debug | ship.
134
+ */
135
+ complyPhase: ComplyPhase | null;
136
+ /**
137
+ * Sub-verb for the `telemetry` verb (e.g. "summary").
138
+ * Only populated when verb === "telemetry". null = not specified / not applicable.
139
+ */
140
+ telemetrySubverb: TelemetrySubverb | null;
141
+ }
142
+
143
+ export interface UninstallFlags {
144
+ dryRun: boolean;
145
+ force: boolean;
146
+ nuke: boolean;
147
+ yes: boolean;
148
+ autoRevert: boolean;
149
+ }
150
+
151
+ /** Flags for the `upgrade` verb (P4.T5/P4.T6). */
152
+ export interface UpgradeFlags {
153
+ /** Non-interactive mode: auto-apply non-conflicting changes; emit conflict list to stderr; exit non-zero on conflicts. */
154
+ nonInteractive: boolean;
155
+ /** Dry-run: show what would change without writing. */
156
+ dryRun: boolean;
157
+ /**
158
+ * Atomic self-bump target (`--to=<version>`): install this @cbartens/bkit version,
159
+ * then re-render + re-pin in one command so the package bump can never drift from
160
+ * the rendered mirrors. null = no bump (re-render at the installed version).
161
+ */
162
+ toVersion: string | null;
163
+ /** `--latest`: resolve the newest published version from the registry, then self-bump to it. */
164
+ latest: boolean;
165
+ }
166
+
167
+ // Bare module-flag tokens accepted on the CLI. `opencode` (value-bearing) is
168
+ // intercepted by a dedicated branch in parseArgs before this set is consulted; the
169
+ // generic check only ever validates claude/cursor/codex. `full`, `core` and `cloud`
170
+ // are NOT accepted as bare flags: use `--auto=<claude|cursor>`; core is implicit.
171
+ // There is no dependency-updater flag. Copy an example; CI warns when none is present.
172
+ const MODULE_FLAGS = new Set<ModuleFlag>(["claude", "cursor", "opencode", "codex"]);
173
+
174
+ // ALL_MODULES — every non-opt-in module, core first. Used to expand a bare/full
175
+ // uninstall (which additionally pulls in the opt-in add-ons below for zero footprint).
176
+ const ALL_MODULES: ModuleFlag[] = ["core", "claude", "cursor"];
177
+
178
+ /**
179
+ * Resolve the explicit module-flag set into the concrete module set to dispatch.
180
+ * `flags` holds the internal module names the user explicitly named — core is NOT
181
+ * among them (it is implicit). The install "≥1 flag required" rule is enforced by the
182
+ * caller (commands/install/install.ts main), not here.
183
+ *
184
+ * install / check / upgrade / doctor / status → core implicit + the named modules.
185
+ * uninstall (bare) → every module incl. opt-in add-ons + core (zero footprint).
186
+ * uninstall (targeted) → the named modules ONLY (core is removed only by a bare
187
+ * uninstall — a targeted uninstall must not strip the shared
188
+ * foundation, e.g. `uninstall --claude` keeps AGENTS.md).
189
+ */
190
+ export function resolveModules(flags: Set<ModuleFlag>, verb: Verb): Set<ModuleFlag> {
191
+ if (verb === "uninstall") {
192
+ if (flags.size === 0) {
193
+ const out = new Set<ModuleFlag>(ALL_MODULES);
194
+ for (const m of OPTIN_MODULES) out.add(m);
195
+ return out;
196
+ }
197
+ return new Set(flags);
198
+ }
199
+ const out = new Set(flags);
200
+ out.add("core");
201
+ return out;
202
+ }
203
+
204
+ function defaultUninstallFlags(): UninstallFlags {
205
+ return {
206
+ dryRun: false,
207
+ force: false,
208
+ nuke: false,
209
+ yes: false,
210
+ autoRevert: false,
211
+ };
212
+ }
213
+
214
+ function defaultUpgradeFlags(): UpgradeFlags {
215
+ return { nonInteractive: false, dryRun: false, toVersion: null, latest: false };
216
+ }
217
+
218
+ /**
219
+ * Parse argv (process.argv.slice(2)) into a ParsedArgs object.
220
+ * Rejects unknown verbs and flags with process.exit(1).
221
+ */
222
+ export function parseArgs(argv: string[]): ParsedArgs {
223
+ const args = [...argv];
224
+ let verb: Verb = "help";
225
+
226
+ // Verb extraction
227
+ const firstArg = args[0];
228
+ if (
229
+ firstArg === "install" ||
230
+ firstArg === "check" ||
231
+ firstArg === "doctor" ||
232
+ firstArg === "status" ||
233
+ firstArg === "uninstall" ||
234
+ firstArg === "upgrade"
235
+ ) {
236
+ verb = firstArg as Verb;
237
+ args.shift();
238
+ } else if (firstArg === "comply") {
239
+ verb = "comply";
240
+ args.shift();
241
+ } else if (firstArg === "harvest") {
242
+ verb = "harvest";
243
+ args.shift();
244
+ // harvest takes no flags — reject any remaining args
245
+ if (args.length > 0 && !args[0]?.startsWith("-")) {
246
+ console.error(
247
+ `[bkit] \`bkit harvest\` takes no positional args. Run \`bkit help\` for usage.`,
248
+ );
249
+ process.exit(1);
250
+ }
251
+ } else if (firstArg === "analysis") {
252
+ verb = "analysis";
253
+ args.shift();
254
+ // analysis takes no flags — reject any remaining positional args
255
+ if (args.length > 0 && !args[0]?.startsWith("-")) {
256
+ console.error(
257
+ `[bkit] \`bkit analysis\` takes no positional args. Run \`bkit help\` for usage.`,
258
+ );
259
+ process.exit(1);
260
+ }
261
+ } else if (firstArg === "telemetry") {
262
+ verb = "telemetry";
263
+ args.shift();
264
+ } else if (firstArg === "cursor" || firstArg === "opencode") {
265
+ verb = firstArg as Verb;
266
+ args.shift();
267
+ // Launcher verbs take no flags — reject any remaining args up-front.
268
+ if (args.length > 0) {
269
+ console.error(`[bkit] \`bkit ${firstArg}\` takes no flags. Run \`bkit help\` for usage.`);
270
+ process.exit(1);
271
+ }
272
+ } else if (firstArg === "help" || firstArg === "--help" || firstArg === "-h") {
273
+ verb = "help";
274
+ args.shift();
275
+ } else if (firstArg !== undefined && !firstArg.startsWith("-")) {
276
+ console.error(`[bkit] Unknown verb: ${firstArg}. Run \`bkit help\` for usage.`);
277
+ process.exit(1);
278
+ }
279
+
280
+ // Accumulates the internal module names the user explicitly named (no core).
281
+ // resolveModules turns this into the dispatch set; main() reads it for the
282
+ // install/check/upgrade flag guards.
283
+ const moduleFlags = new Set<ModuleFlag>();
284
+ const uninstallFlags = defaultUninstallFlags();
285
+ const upgradeFlags = defaultUpgradeFlags();
286
+ let tracker: IssueTracker | null = null;
287
+ let cloudVariant: CloudVariant | null = null;
288
+ let opencodeProvider: string | null = null;
289
+ let complyPhase: ComplyPhase | null = null;
290
+ let telemetrySubverb: TelemetrySubverb | null = null;
291
+
292
+ // For `telemetry` verb: extract the sub-verb from the first remaining positional arg
293
+ if (verb === "telemetry") {
294
+ const subVerbArg = args[0];
295
+ if (subVerbArg !== undefined && !subVerbArg.startsWith("-")) {
296
+ const parsed = parseTelemetrySubverb(subVerbArg);
297
+ if (parsed === null) {
298
+ console.error(
299
+ `[bkit] Unknown telemetry sub-verb: "${subVerbArg}". Valid values: ${TELEMETRY_SUBVERBS.join(", ")}`,
300
+ );
301
+ process.exit(1);
302
+ }
303
+ telemetrySubverb = parsed;
304
+ args.shift();
305
+ } else if (subVerbArg === undefined) {
306
+ console.error(
307
+ `[bkit] \`bkit telemetry\` requires a sub-verb. Valid values: ${TELEMETRY_SUBVERBS.join(", ")}`,
308
+ );
309
+ process.exit(1);
310
+ }
311
+ }
312
+
313
+ for (const arg of args) {
314
+ // `--help` / `-h` after a verb (e.g. `bkit install --help`) prints usage.
315
+ if (arg === "--help" || arg === "-h") {
316
+ verb = "help";
317
+ break;
318
+ }
319
+ if (arg.startsWith("--")) {
320
+ const flag = arg.slice(2);
321
+
322
+ // Value-bearing flag: --tracker=<github|linear|none>
323
+ if (flag.startsWith("tracker=")) {
324
+ const value = flag.slice("tracker=".length);
325
+ const parsed = parseIssueTracker(value);
326
+ if (parsed === null) {
327
+ console.error(
328
+ `[bkit] Unknown tracker: "${value}". Valid values: ${ISSUE_TRACKERS.join(", ")}`,
329
+ );
330
+ process.exit(1);
331
+ }
332
+ tracker = parsed;
333
+ continue;
334
+ }
335
+
336
+ // Value-bearing flag: --phase=<design|plan|build|debug|ship>
337
+ // `bkit comply` — the workflow phase being graded.
338
+ // `bkit telemetry summary` — the workflow to report a chain rollup for.
339
+ // Rejected for all other verbs.
340
+ if (flag.startsWith("phase=")) {
341
+ if (verb !== "comply" && verb !== "telemetry") {
342
+ console.error(
343
+ `[bkit] --phase is only valid with the \`comply\` and \`telemetry\` verbs. Run \`bkit help\` for usage.`,
344
+ );
345
+ process.exit(1);
346
+ }
347
+ const value = flag.slice("phase=".length);
348
+ const parsed = parseComplyPhase(value);
349
+ if (parsed === null) {
350
+ console.error(
351
+ `[bkit] Unknown phase: "${value}". Valid values: ${COMPLY_PHASES.join(", ")}`,
352
+ );
353
+ process.exit(1);
354
+ }
355
+ complyPhase = parsed;
356
+ continue;
357
+ }
358
+ if (flag === "phase") {
359
+ console.error(
360
+ `[bkit] --phase requires a value: --phase=<${COMPLY_PHASES.join("|")}>. Run \`bkit help\` for usage.`,
361
+ );
362
+ process.exit(1);
363
+ }
364
+
365
+ // Value-bearing flag: --auto=<claude|cursor> — cloud-agent (auto-dispatch) lane;
366
+ // sets the internal `cloud` module. Bare `--auto` (no variant) is accepted only on
367
+ // uninstall (variant read from package.json).
368
+ if (flag === "auto") {
369
+ if (verb !== "uninstall") {
370
+ console.error(
371
+ `[bkit] --auto requires an explicit variant: --auto=claude, --auto=cursor, or --auto=opencode. Run \`bkit help\` for usage.`,
372
+ );
373
+ process.exit(1);
374
+ }
375
+ // uninstall --auto: add the module flag without setting a cloudVariant.
376
+ moduleFlags.add("cloud");
377
+ continue;
378
+ }
379
+ if (flag.startsWith("auto=")) {
380
+ const value = flag.slice("auto=".length);
381
+ const parsed = parseCloudVariant(value);
382
+ if (parsed === null) {
383
+ console.error(
384
+ `[bkit] Unknown cloud variant: "${value}". Valid values: ${CLOUD_VARIANTS.join(", ")}`,
385
+ );
386
+ process.exit(1);
387
+ }
388
+ cloudVariant = parsed;
389
+ moduleFlags.add("cloud");
390
+ continue;
391
+ }
392
+
393
+ // Value-bearing flag: --opencode=<provider>
394
+ // Additive opencode host opt-in. Supported providers: openrouter, ollama,
395
+ // opencode-zen + opencode-go (opencode-native gateways) (strict allowlist).
396
+ // A value is required (provider identifies which API key + base URL to configure).
397
+ if (flag === "opencode") {
398
+ if (verb !== "uninstall") {
399
+ console.error(
400
+ `[bkit] --opencode requires an explicit provider: --opencode=<provider> (e.g. --opencode=opencode-zen). Run \`bkit help\` for usage.`,
401
+ );
402
+ process.exit(1);
403
+ }
404
+ // uninstall --opencode: add the module flag without requiring a provider value.
405
+ moduleFlags.add("opencode");
406
+ continue;
407
+ }
408
+ if (flag.startsWith("codex=")) {
409
+ console.error(
410
+ `[bkit] --codex takes no value (got ${JSON.stringify("--" + flag)}). Codex CLI runs on one gateway (openai), so the flag is bare: --codex. Only --opencode is provider-pluggable.`,
411
+ );
412
+ process.exit(1);
413
+ }
414
+ if (flag.startsWith("opencode=")) {
415
+ const rawValue = flag.slice("opencode=".length);
416
+ if (!rawValue) {
417
+ console.error(
418
+ `[bkit] --opencode= requires a provider value (e.g. --opencode=opencode-zen). Run \`bkit help\` for usage.`,
419
+ );
420
+ process.exit(1);
421
+ }
422
+ if (!(OPENCODE_PROVIDERS as readonly string[]).includes(rawValue)) {
423
+ console.error(
424
+ `[bkit] --opencode= unsupported provider ${JSON.stringify(rawValue)}. Supported: ${OPENCODE_PROVIDERS.join(", ")}.`,
425
+ );
426
+ process.exit(1);
427
+ }
428
+ opencodeProvider = rawValue;
429
+ moduleFlags.add("opencode");
430
+ continue;
431
+ }
432
+
433
+ // Uninstall-specific flags (accepted for all verbs that use them)
434
+ if (flag === "dry-run") {
435
+ uninstallFlags.dryRun = true;
436
+ upgradeFlags.dryRun = true;
437
+ continue;
438
+ }
439
+ if (flag === "force") {
440
+ // Uninstall-only: force-delete whole-file owned files even if consumer-modified.
441
+ uninstallFlags.force = true;
442
+ continue;
443
+ }
444
+ if (flag === "nuke") {
445
+ uninstallFlags.nuke = true;
446
+ continue;
447
+ }
448
+ if (flag === "yes") {
449
+ uninstallFlags.yes = true;
450
+ continue;
451
+ }
452
+ if (flag === "auto-revert") {
453
+ uninstallFlags.autoRevert = true;
454
+ continue;
455
+ }
456
+ // Upgrade-specific flag: --auto-apply —
457
+ // auto-apply non-conflicting changes, emit the conflict list, exit non-zero on
458
+ // any conflict (CI-safe). The internal field is `nonInteractive`.
459
+ if (flag === "auto-apply") {
460
+ upgradeFlags.nonInteractive = true;
461
+ continue;
462
+ }
463
+
464
+ // Upgrade-specific atomic self-bump (see runSelfBump). `--to=<version>` pins a
465
+ // target @cbartens/bkit version; `--latest` resolves the newest published one.
466
+ // Either makes the package bump atomic with the re-render so a bumped package
467
+ // can never drift from its rendered mirrors. Verb/mutual-exclusion guards below.
468
+ if (flag.startsWith("to=")) {
469
+ upgradeFlags.toVersion = flag.slice("to=".length);
470
+ continue;
471
+ }
472
+ if (flag === "latest") {
473
+ upgradeFlags.latest = true;
474
+ continue;
475
+ }
476
+
477
+ // Bare module flags. opencode is intercepted above; only claude/cursor/codex
478
+ // reach here. Everything else hits the generic unknown-flag error.
479
+ const moduleFlag = flag as ModuleFlag;
480
+ if (!MODULE_FLAGS.has(moduleFlag)) {
481
+ console.error(`[bkit] Unknown flag: ${arg}. Run \`bkit help\` for usage.`);
482
+ process.exit(1);
483
+ }
484
+ moduleFlags.add(moduleFlag);
485
+ continue;
486
+ }
487
+
488
+ // Any other positional after verb
489
+ console.error(`[bkit] Unexpected argument: ${arg}. Run \`bkit help\` for usage.`);
490
+ process.exit(1);
491
+ }
492
+
493
+ // Self-bump flags (`--to=`/`--latest`) only apply to the `upgrade` verb, and the
494
+ // two are mutually exclusive (pin a version OR resolve the latest, not both).
495
+ if ((upgradeFlags.toVersion !== null || upgradeFlags.latest) && verb !== "upgrade") {
496
+ console.error(
497
+ "[bkit] `--to=<version>` / `--latest` are only valid for `bkit upgrade` (they atomically bump @cbartens/bkit, then re-render).",
498
+ );
499
+ process.exit(1);
500
+ }
501
+ if (upgradeFlags.toVersion !== null && upgradeFlags.latest) {
502
+ console.error(
503
+ "[bkit] `--to=<version>` and `--latest` are mutually exclusive — pin a version or resolve the latest, not both.",
504
+ );
505
+ process.exit(1);
506
+ }
507
+ if (upgradeFlags.toVersion !== null && upgradeFlags.toVersion.trim() === "") {
508
+ console.error("[bkit] `--to=` requires a version value, e.g. `--to=4.1.5`.");
509
+ process.exit(1);
510
+ }
511
+
512
+ // resolveModules is verb-aware: a bare uninstall expands to all modules + opt-ins +
513
+ // core (zero footprint); every other verb keeps core implicit + the named modules.
514
+ const modules = resolveModules(moduleFlags, verb);
515
+
516
+ return {
517
+ verb,
518
+ modules,
519
+ moduleFlags,
520
+ uninstallFlags,
521
+ upgradeFlags,
522
+ tracker,
523
+ cloudVariant,
524
+ opencodeProvider,
525
+ complyPhase,
526
+ telemetrySubverb,
527
+ };
528
+ }
529
+
530
+ export function printUsage(): void {
531
+ console.log(
532
+ `bkit — agent-stack consolidation CLI
533
+
534
+ Usage:
535
+ bkit install <module-flags> Install (or re-sync) the named modules + the implicit
536
+ core foundation. At least one module flag is REQUIRED —
537
+ a bare \`bkit install\` errors (name the modules below).
538
+ Hosts compose: --claude --cursor --codex --opencode=<provider>.
539
+ bkit check Dry-run — drift-check everything already installed (no
540
+ module flags). Exits 1 when a managed file needs
541
+ re-rendering. Copies under .bkit/templates/ are refreshed by
542
+ install/upgrade and checked for staleness — adopt one by
543
+ copying it elsewhere; that copy is yours. The CI gate.
544
+ bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
545
+ Upgrade everything installed (no module flags). Diffs old
546
+ vs new templates; conflict list emitted to stderr. Use
547
+ --auto-apply for CI (apply non-conflicting; exit non-zero
548
+ on any conflict).
549
+ --to=<version> / --latest atomically BUMP @cbartens/bkit
550
+ (pnpm add), then re-render + re-pin in one step — so a
551
+ version bump can never drift from its rendered mirrors.
552
+ This is the supported way to move bkit versions; a bare
553
+ \`pnpm add @cbartens/bkit\` alone leaves mirrors stale.
554
+ bkit uninstall [module-flags] Remove bkit-managed files + strip managed blocks.
555
+ No flags = full removal — ALL modules incl. opt-in add-ons
556
+ (cloud/opencode) + core. Consumer-owned updater configs
557
+ (renovate.json5, dependabot.yml, bkit-renovate.yml) are left in place. Consumer-modified
558
+ files, your own files under docs/, and generated artefacts
559
+ (.bkit/advisories.md, .bkit/friction.jsonl) are preserved (use
560
+ --nuke to force-remove manifest-listed files). Target with the
561
+ same module flags as install (e.g. uninstall --claude); a
562
+ targeted uninstall leaves core untouched.
563
+ bkit doctor Read-only preflight + post-install advisory replay.
564
+ Diagnose token surfaces and config drift. Exits 0.
565
+ bkit status Read-only host/provider status. Reports current host+provider
566
+ (sampled from .opencode/opencode.json, .claude/, .cursor/).
567
+ Writes nothing. Exits 0.
568
+ bkit cursor Launch Cursor with .bkit/.env loaded into its environment.
569
+ macOS GUI apps launched from the Dock/Finder do not inherit
570
+ the login shell env (direnv stays shell-only), so MCP token
571
+ placeholders resolve empty. This verb execs the app binary
572
+ directly with the per-repo .bkit/.env merged in. Quit Cursor
573
+ before running — a running instance ignores the new env.
574
+ Override binary path via BKIT_CURSOR_BIN=<path>.
575
+ bkit opencode Same as \`bkit cursor\` but for the opencode desktop app.
576
+ Override binary path via BKIT_OPENCODE_BIN=<path>.
577
+ bkit comply --phase=<phase> Run the compliance grader advisory step.
578
+ Checks the diff since parentSha for violations
579
+ (no-mirror-edit, skip-ci-not-head). Advisory only —
580
+ never gates a workflow. Appends kind:"compliance"
581
+ rows to .bkit/stats.jsonl. Fail-open: always exits 0.
582
+ Valid phases: design, plan, build, debug, ship.
583
+ bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
584
+ and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
585
+ for docs/deferrals.jsonl and docs/failures.jsonl).
586
+ Reads consumer paths from docs/consumers.md.
587
+ DESTRUCTIVE: harvested friction rows are REMOVED from
588
+ the consumer, but only after they are fsync'd and read
589
+ back from harvest/. stats.jsonl is never modified.
590
+ harvest/ accumulates and is never cleared — commit it,
591
+ as it is the only record of pruned rows. Never commits
592
+ in any repo. Deduplicates by per-kind composite
593
+ identity. Advisory + fail-open: exits 0.
594
+ bkit telemetry summary [--phase=<workflow>]
595
+ Per-workflow telemetry report: THIS run's metrics
596
+ (duration, size, friction/deferrals/failures added,
597
+ compliance) against med·5 — the median of the previous 5
598
+ same-workflow runs. The close step of every /bkit-*
599
+ workflow calls this and posts it to the tracker comment.
600
+ --phase=<workflow>: the workflow to report
601
+ (design|plan|build|debug|ship). Without it, prints the
602
+ ledger-health line only. Read-only: exits 0.
603
+ bkit analysis Cross-repo analysis — reports counts/rates/elapsed-time,
604
+ #183 size↔outcome regression, dispatch-size threshold,
605
+ counterSource trust labelling, per-rule compliance
606
+ rate over kind:"compliance" rows, and the
607
+ unjustified-deferral rate per (subagent, model)
608
+ over kind:"deferral" rows. Reads from harvest/,
609
+ .bkit/stats.jsonl and docs/deferrals.jsonl.
610
+ Advisory + inform-only: exits 0.
611
+ bkit help Print this message.
612
+
613
+ Core (implicit — no flag; installed/upgraded on every install):
614
+ AGENTS.md (cross-host dispatch router), .agents/rules.md + .agents/context.md +
615
+ .agents/docs.md + .agents/skills.md managed blocks, .gitignore + .gitattributes managed
616
+ blocks, docs/, .bkit/*.md, .bkit/version, the template copies in .bkit/templates/, and
617
+ the bkit:gate:* / bkit:deps:* package.json scripts every workflow runs (added when
618
+ missing, never overwritten, left by uninstall). The tool scripts those gates chain
619
+ (typecheck, lint, format:check, lint:prose, slop:delta) and their devDeps are yours
620
+ to add: see .bkit/templates.md.
621
+
622
+ Module flags (composable; symmetric install ↔ uninstall):
623
+ --claude .claude/agents/ + .claude/commands/ (byte-identical mirror) + CLAUDE.md
624
+ (root redirect to .agents/rules.md) + .claude settings/hooks + the
625
+ tracker entry in .mcp.json + .bkit/.env.example.
626
+ --cursor .cursor/agents/ + .cursor/commands/ (T1/T2/T3 transforms) +
627
+ .cursor/rules/bkit-rules.mdc + .cursor settings.
628
+ --opencode=<provider>
629
+ Additive opencode host. Each install ADDS a provider block to
630
+ opencode.json; agent defaults track the last-installed (active) provider.
631
+ Provider value is REQUIRED. Supported: openrouter, ollama,
632
+ opencode-zen, opencode-go (opencode-native gateways;
633
+ auth via BKIT_OPENCODE_API_KEY).
634
+ Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js).
635
+ Configure your provider key; verify with \`bkit doctor\`. All installed
636
+ providers tracked in bkit.opencodeProviders.
637
+ --codex Codex CLI host. BARE flag — takes no value: Codex runs on one gateway
638
+ (openai), so only --opencode is provider-pluggable. Ships .codex/agents/*.toml
639
+ + .codex/hooks.json + .codex/hooks/bkit-gateguard.cjs, plus the workflow skills
640
+ (.agents/skills/bkit-*/). Codex loads project-local hooks ONLY once the
641
+ .codex/ layer is trusted — until then GateGuard is installed and never fires.
642
+
643
+ Dependency updaters (copy an example and own it):
644
+ .bkit/templates/.github/renovate.json5
645
+ .bkit/templates/.github/workflows/bkit-renovate.yml (self-hosted runner, optional)
646
+ .bkit/templates/.github/dependabot.yml
647
+ All templates and install steps: .bkit/templates.md
648
+
649
+ --auto=<claude|cursor|opencode>
650
+ Cloud-agent (auto-dispatch) integration (opt-in). --auto=claude needs
651
+ tracker=github + the ANTHROPIC_API_KEY repo secret + the Claude GitHub App; --auto=cursor
652
+ needs tracker=linear; --auto=opencode needs tracker=github + a remote
653
+ opencode provider (OPENCODE_PROVIDER_KEY). Bare --auto is accepted on
654
+ uninstall only.
655
+
656
+ Cross-cutting / modifiers:
657
+ --tracker=<name> Wire issue tracker integration. Values: github, linear, none
658
+ (default). Records bkit.issueTracker in package.json and substitutes
659
+ tracker snippets into command mirrors. Switching is free (re-run with
660
+ a new value). Does NOT own AGENTS.md (which is tracker-agnostic).
661
+
662
+ Install flags:
663
+ --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
664
+
665
+ Upgrade flags:
666
+ --auto-apply Apply non-conflicting changes; emit conflict list to stderr; exit
667
+ non-zero when any conflict is detected (CI-safe).
668
+ --dry-run Show what would change without writing.
669
+
670
+ Uninstall flags:
671
+ --dry-run Print decision table (FILE / DECISION / REASON) without writing.
672
+ --opencode=<provider>
673
+ Surgical provider removal: removes that provider's block from
674
+ opencode.json + drops it from bkit.opencodeProviders. Does NOT remove
675
+ agents/commands/gateguard. If the removed provider was active, re-render
676
+ agents by running bkit install --opencode=<remaining> or bkit upgrade.
677
+ Bare --opencode (no value) tears down the entire opencode host.
678
+ --force Delete owned whole-file files even if consumer modified them.
679
+ --nuke Delete ALL bkit-managed files regardless of tier/hash (requires confirm).
680
+ --yes Skip interactive confirm for --nuke.
681
+
682
+ Examples:
683
+ bkit install --claude .claude/** + CLAUDE.md + core.
684
+ bkit install --claude --cursor Both hosts + core.
685
+ bkit install --opencode=opencode-zen opencode host (Zen built-in gateway, additive).
686
+ bkit install --opencode=opencode-go opencode host (Go built-in gateway, additive).
687
+ bkit install --opencode=openrouter add openrouter alongside an opencode gateway.
688
+ bkit install --opencode=ollama Ollama cloud endpoint (BKIT_OLLAMA_API_KEY).
689
+ bkit uninstall --opencode=openrouter remove openrouter block only; keep the gateway.
690
+ bkit install --tracker=github --auto=claude Claude cloud integration (GitHub tracker).
691
+ bkit check Drift-check everything installed (CI gate).
692
+ bkit upgrade --auto-apply Upgrade installed files; CI-safe.
693
+ bkit uninstall Full uninstall (all modules; artefacts kept, --nuke to purge).
694
+ bkit uninstall --claude Remove the claude host only (core kept).
695
+ bkit cursor Launch Cursor with .bkit/.env (MCP tokens).
696
+ bkit opencode Launch opencode with .bkit/.env (API key).
697
+
698
+ macOS GUI-isolation note (launchctl fallback):
699
+ If you prefer launching via the Dock/Spotlight instead of \`bkit cursor\` / \`bkit opencode\`,
700
+ make the tokens visible to launchd-launched GUI apps with a one-shot setenv (does NOT
701
+ survive reboot — must re-run after each restart):
702
+ launchctl setenv BKIT_GH_TOKEN "$BKIT_GH_TOKEN"
703
+ launchctl setenv BKIT_OPENCODE_API_KEY "$BKIT_OPENCODE_API_KEY" # etc.
704
+ For a persistent approach that re-reads the tokens file on every change, copy the
705
+ launchd template set (see \`.bkit/templates.md\` § Launchd GUI environment). Rotation
706
+ then needs no re-bootstrap — prefer \`bkit cursor\` / \`bkit opencode\` for the dynamic model.
707
+
708
+ Docs: https://github.com/cbartens/bkit/blob/main/README.md` + commandsUsage(),
709
+ );
710
+ }
711
+
712
+ /** The `bkit <noun> <verb>` section of the usage text; empty while no command is registered. */
713
+ function commandsUsage(): string {
714
+ if (COMMANDS.length === 0) return "";
715
+ const width = Math.max(...COMMANDS.map((c) => c.noun.length));
716
+ return [
717
+ "",
718
+ "",
719
+ "Workflow commands (bkit <noun> <verb> --flags; JSON on stdout; bkit <noun> --help):",
720
+ ...COMMANDS.map((c) => ` bkit ${c.noun.padEnd(width)} ${c.summary}`),
721
+ ].join("\n");
722
+ }
723
+
724
+ /**
725
+ * Validate the verb/module-flag combination before any dispatch
726
+ * work runs. `install` requires >=1 module flag (bare install errors);
727
+ * `check` / `upgrade` take NO module flags — they
728
+ * operate on everything already installed, so a stray flag is a hard error
729
+ * pointing at the no-flag form. Returns the error message to print, or `null`
730
+ * when the combination is valid.
731
+ */
732
+ export function validateModuleFlagsForVerb(
733
+ verb: Verb,
734
+ moduleFlags: Set<ModuleFlag>,
735
+ ): string | null {
736
+ if (verb === "install" && moduleFlags.size === 0) {
737
+ return (
738
+ "[bkit] `bkit install` requires at least one module flag. Name what to install: " +
739
+ "--claude, --cursor, --codex, --opencode=<provider> (plus opt-in " +
740
+ "--auto=<claude|cursor>). Run `bkit help` for usage."
741
+ );
742
+ }
743
+ if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
744
+ return (
745
+ `[bkit] \`bkit ${verb}\` takes no module flags — it operates on everything already ` +
746
+ `installed. Re-run as \`bkit ${verb}\` (no module flags). Run \`bkit help\` for usage.`
747
+ );
748
+ }
749
+ return null;
750
+ }
751
+
752
+ // The CLI entrypoint, run only when this file is executed and driven by real
753
+ // argv/fs/process.exit side effects; install.integration.test.ts exercises it through
754
+ // spawned processes. Pure decision logic lives in exported functions
755
+ // (validateModuleFlagsForVerb above, validateCloudTrackerMatch in commands/install/install.ts)
756
+ // for unit coverage.
757
+ export async function main() {
758
+ const commandExit = await runCommand(process.argv.slice(2), COMMANDS, {
759
+ classicVerbs: CLASSIC_VERBS,
760
+ });
761
+ if (commandExit !== null) {
762
+ process.exitCode = commandExit;
763
+ return;
764
+ }
765
+
766
+ const {
767
+ verb,
768
+ modules,
769
+ moduleFlags,
770
+ uninstallFlags,
771
+ upgradeFlags,
772
+ tracker,
773
+ cloudVariant,
774
+ opencodeProvider,
775
+ complyPhase,
776
+ telemetrySubverb,
777
+ } = parseArgs(process.argv.slice(2));
778
+
779
+ // A bare `bkit` (no arguments) means no command was given: print usage and exit non-zero
780
+ // (2 = usage error), distinct from an explicit `bkit help` / `--help` (verb "help"), which
781
+ // prints the same usage and exits 0. parseArgs still defaults no-args to the "help" verb.
782
+ if (process.argv.slice(2).length === 0) {
783
+ printUsage();
784
+ process.exit(2);
785
+ }
786
+
787
+ if (verb === "help") {
788
+ printUsage();
789
+ return;
790
+ }
791
+
792
+ if (verb === "comply") {
793
+ runComplyCommand(complyPhase);
794
+ return;
795
+ }
796
+
797
+ if (verb === "harvest") {
798
+ runHarvestCommand();
799
+ return;
800
+ }
801
+
802
+ if (verb === "analysis") {
803
+ runAnalysisCommand();
804
+ return;
805
+ }
806
+
807
+ if (verb === "telemetry") {
808
+ runTelemetryCommand(telemetrySubverb, complyPhase);
809
+ return;
810
+ }
811
+
812
+ // Launcher verbs — exec the GUI app binary with .bkit/.env merged into the env
813
+ // so that MCP token placeholders (BKIT_GH_TOKEN, BKIT_OPENCODE_API_KEY, …) resolve correctly
814
+ // even when launched from the Dock/Finder (macOS GUI-isolation).
815
+ if (verb === "cursor" || verb === "opencode") {
816
+ await launchApp(verb, process.cwd());
817
+ return;
818
+ }
819
+
820
+ // install requires >=1 module flag; check/upgrade take NONE (validateModuleFlagsForVerb).
821
+ const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags);
822
+ if (moduleFlagsError) {
823
+ console.error(moduleFlagsError);
824
+ process.exit(1);
825
+ }
826
+
827
+ if (verb === "doctor") {
828
+ await runDoctor(modules, opencodeProvider);
829
+ return;
830
+ }
831
+
832
+ if (verb === "status") {
833
+ setLogPrefix("[bkit-status]");
834
+ runStatus(process.cwd(), LOG_PREFIX);
835
+ return;
836
+ }
837
+
838
+ if (verb === "upgrade") {
839
+ await runUpgradeCommand(upgradeFlags);
840
+ return;
841
+ }
842
+
843
+ if (verb === "uninstall") {
844
+ await runUninstallCommand(modules, opencodeProvider, uninstallFlags);
845
+ return;
846
+ }
847
+
848
+ await runInstall({ verb, modules, tracker, cloudVariant, opencodeProvider, uninstallFlags });
849
+ }
850
+
851
+ function isMainScript(): boolean {
852
+ if (!process.argv[1]) return false;
853
+ try {
854
+ const argvReal = fs.realpathSync(process.argv[1]);
855
+ const metaReal = fs.realpathSync(fileURLToPath(import.meta.url));
856
+ return argvReal === metaReal;
857
+ } catch {
858
+ return false;
859
+ }
860
+ }
861
+
862
+ if (isMainScript()) {
863
+ main().catch((err: unknown) => {
864
+ console.error(`${LOG_PREFIX} Unhandled error: ${(err as Error).message}`);
865
+ process.exit(1);
866
+ });
867
+ }