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