@cbartens/bkit 0.0.0-stage → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (373) hide show
  1. package/.bkit/README.md +421 -0
  2. package/.bkit/core/.agents/context.md +95 -0
  3. package/.bkit/core/.agents/docs.md +62 -0
  4. package/.bkit/core/.agents/rules.md +147 -0
  5. package/.bkit/core/.agents/skills.md +43 -0
  6. package/.bkit/core/.bkit/LICENSE.md +151 -0
  7. package/.bkit/core/.bkit/README.md +421 -0
  8. package/.bkit/core/.bkit/cloud.md +502 -0
  9. package/.bkit/core/.bkit/comparison.md +318 -0
  10. package/.bkit/core/.bkit/install.md +496 -0
  11. package/.bkit/core/.bkit/jsonl.md +497 -0
  12. package/.bkit/core/.bkit/prompts.md +474 -0
  13. package/.bkit/core/.bkit/providers.md +598 -0
  14. package/.bkit/core/.bkit/templates.md +471 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1546 -0
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
  22. package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
  24. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
  26. package/.bkit/core/AGENTS.md +77 -0
  27. package/.bkit/core/LICENSE.md +149 -0
  28. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
  29. package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
  30. package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
  31. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
  32. package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
  33. package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
  34. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
  35. package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
  36. package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
  37. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
  38. package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
  39. package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
  40. package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
  41. package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
  42. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
  43. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
  44. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
  45. package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
  46. package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
  47. package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
  48. package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
  49. package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
  50. package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
  51. package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
  52. package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
  53. package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
  54. package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
  55. package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
  56. package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
  57. package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
  58. package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
  59. package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
  60. package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
  61. package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
  62. package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
  63. package/.bkit/core/docs/templates/bkit-plan.md +476 -0
  64. package/.bkit/core/engine/checks/after/auth.ts +247 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +739 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +556 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  70. package/.bkit/core/engine/checks/after/vercel.ts +101 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +201 -0
  73. package/.bkit/core/engine/checks/before/files.ts +202 -0
  74. package/.bkit/core/engine/checks/before/index.ts +206 -0
  75. package/.bkit/core/engine/checks/before/mcp.ts +127 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +77 -0
  77. package/.bkit/core/engine/checks/before/version.ts +67 -0
  78. package/.bkit/core/engine/checks/status-holes.ts +479 -0
  79. package/.bkit/core/engine/cli.ts +871 -0
  80. package/.bkit/core/engine/commands/analysis.ts +550 -0
  81. package/.bkit/core/engine/commands/ci/ci.ts +483 -0
  82. package/.bkit/core/engine/commands/comply.ts +415 -0
  83. package/.bkit/core/engine/commands/harvest.ts +459 -0
  84. package/.bkit/core/engine/commands/install/check.ts +70 -0
  85. package/.bkit/core/engine/commands/install/doctor.ts +247 -0
  86. package/.bkit/core/engine/commands/install/install.ts +528 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +972 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1026 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +494 -0
  91. package/.bkit/core/engine/commands/registry.ts +53 -0
  92. package/.bkit/core/engine/commands/setup/setup.ts +184 -0
  93. package/.bkit/core/engine/commands/telemetry.ts +32 -0
  94. package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
  95. package/.bkit/core/engine/commands/workflow/context.ts +961 -0
  96. package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
  97. package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
  98. package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
  99. package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
  100. package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
  101. package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
  102. package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
  103. package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
  104. package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
  105. package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
  106. package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
  107. package/.bkit/core/engine/commands/workflow/status.ts +455 -0
  108. package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
  109. package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
  110. package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
  111. package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
  112. package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
  113. package/.bkit/core/engine/install/cloud-env.ts +925 -0
  114. package/.bkit/core/engine/install/managed-block.ts +212 -0
  115. package/.bkit/core/engine/install/manifest.ts +448 -0
  116. package/.bkit/core/engine/install/modules/claude.ts +362 -0
  117. package/.bkit/core/engine/install/modules/cloud.ts +174 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +600 -0
  120. package/.bkit/core/engine/install/modules/cursor.ts +231 -0
  121. package/.bkit/core/engine/install/modules/index.ts +242 -0
  122. package/.bkit/core/engine/install/modules/opencode.ts +573 -0
  123. package/.bkit/core/engine/install/placeholders.ts +108 -0
  124. package/.bkit/core/engine/install/template-copies.ts +119 -0
  125. package/.bkit/core/engine/install/version-file.ts +284 -0
  126. package/.bkit/core/engine/install/write.ts +467 -0
  127. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  128. package/.bkit/core/engine/ledgers/status.ts +213 -0
  129. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  130. package/.bkit/core/engine/render/hosts.ts +372 -0
  131. package/.bkit/core/engine/render/models.ts +323 -0
  132. package/.bkit/core/engine/render/parts.ts +38 -0
  133. package/.bkit/core/engine/render/trackers.ts +170 -0
  134. package/.bkit/core/engine/shared/egress.ts +345 -0
  135. package/.bkit/core/engine/shared/json.ts +16 -0
  136. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  137. package/.bkit/core/engine/shared/package-json.ts +29 -0
  138. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  139. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  140. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  141. package/.bkit/core/engine/shared/settings.ts +72 -0
  142. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  143. package/.bkit/core/engine/tools/wording.ts +748 -0
  144. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  145. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  146. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  147. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  148. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  149. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  150. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  155. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  156. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  157. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  158. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  159. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  160. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  161. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  162. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  165. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  166. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  169. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  170. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  171. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  172. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  173. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  174. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  175. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  176. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  178. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  179. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  180. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  181. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  182. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  185. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  186. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  187. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  188. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  189. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  190. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  191. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  192. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  193. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  194. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  195. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  196. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  197. package/.bkit/core/workflows/bkit-auto.md +121 -0
  198. package/.bkit/core/workflows/bkit-build.md +802 -0
  199. package/.bkit/core/workflows/bkit-debug.md +642 -0
  200. package/.bkit/core/workflows/bkit-design.md +495 -0
  201. package/.bkit/core/workflows/bkit-plan.md +510 -0
  202. package/.bkit/core/workflows/bkit-ship.md +650 -0
  203. package/.bkit/shared/.bkit/.env.example +108 -0
  204. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  205. package/.bkit/shared/.claude/settings.json +88 -0
  206. package/.bkit/shared/.codex/hooks.json +26 -0
  207. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  208. package/.bkit/shared/.cursor/hooks.json +26 -0
  209. package/.bkit/shared/.cursor/mcp.json +15 -0
  210. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  211. package/.bkit/shared/.gitattributes +37 -0
  212. package/.bkit/shared/.mcp.json +16 -0
  213. package/.bkit/shared/.opencode/opencode.json +62 -0
  214. package/.bkit/shared/CLAUDE.md +11 -0
  215. package/.bkit/shared/LICENSE.md +22 -0
  216. package/.bkit/shared/docs/architecture.md +19 -0
  217. package/.bkit/shared/docs/data-schema.md +19 -0
  218. package/.bkit/shared/docs/deployments.md +438 -0
  219. package/.bkit/shared/docs/design.md +39 -0
  220. package/.bkit/shared/docs/noise.md +19 -0
  221. package/.bkit/shared/docs/observability.md +25 -0
  222. package/.bkit/shared/docs/security.md +42 -0
  223. package/.bkit/shared/docs/setup.md +30 -0
  224. package/.bkit/shared/docs/technology.md +18 -0
  225. package/.bkit/shared/docs/testing.md +413 -0
  226. package/.bkit/shared/gitignore +92 -0
  227. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +192 -0
  228. package/.bkit/templates/.cursor/Dockerfile +68 -0
  229. package/.bkit/templates/.cursor/environment.json +6 -0
  230. package/.bkit/templates/.cursor/settings.json +11 -0
  231. package/.bkit/templates/.envrc +7 -0
  232. package/.bkit/templates/.github/dependabot.yml +52 -0
  233. package/.bkit/templates/.github/renovate.json5 +239 -0
  234. package/.bkit/templates/.github/workflows/bkit-ci.yml +1082 -0
  235. package/.bkit/templates/.github/workflows/bkit-cloud.yml +566 -0
  236. package/.bkit/templates/.github/workflows/bkit-renovate.yml +107 -0
  237. package/.bkit/templates/.graphifyignore +108 -0
  238. package/.bkit/templates/.husky/pre-commit +16 -0
  239. package/.bkit/templates/.husky/pre-push +91 -0
  240. package/.bkit/templates/.lintstagedrc.json +3 -0
  241. package/.bkit/templates/.prettierignore +41 -0
  242. package/.bkit/templates/.serena/project.yml +243 -0
  243. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  244. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  245. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  246. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  247. package/.bkit/templates/.vale.ini +67 -0
  248. package/.bkit/templates/LICENSE.md +22 -0
  249. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  250. package/.bkit/templates/context/bkit-expo.md +186 -0
  251. package/.bkit/templates/context/bkit-github.md +79 -0
  252. package/.bkit/templates/context/bkit-inngest.md +45 -0
  253. package/.bkit/templates/context/bkit-maestro.md +76 -0
  254. package/.bkit/templates/context/bkit-playwright.md +62 -0
  255. package/.bkit/templates/context/bkit-resend.md +36 -0
  256. package/.bkit/templates/context/bkit-sentry.md +65 -0
  257. package/.bkit/templates/context/bkit-serena.md +33 -0
  258. package/.bkit/templates/context/bkit-stripe.md +36 -0
  259. package/.bkit/templates/context/bkit-supabase.md +59 -0
  260. package/.bkit/templates/context/bkit-tavily.md +49 -0
  261. package/.bkit/templates/context/bkit-vercel.md +64 -0
  262. package/.bkit/templates/docs/capabilities.md +72 -0
  263. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  264. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  266. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  268. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  280. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  281. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  282. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  283. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  284. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  286. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  288. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  289. package/.bkit/templates/slop-scan.config.json +120 -0
  290. package/CHANGELOG.md +1486 -0
  291. package/LICENSE.md +161 -0
  292. package/README.md +185 -2
  293. package/dist/checks/after/auth.js +232 -0
  294. package/dist/checks/after/ci-yml.js +718 -0
  295. package/dist/checks/after/github.js +400 -0
  296. package/dist/checks/after/index.js +447 -0
  297. package/dist/checks/after/managed.js +187 -0
  298. package/dist/checks/after/tools.js +351 -0
  299. package/dist/checks/after/vercel.js +102 -0
  300. package/dist/checks/before/context-fetch.js +426 -0
  301. package/dist/checks/before/env.js +173 -0
  302. package/dist/checks/before/files.js +185 -0
  303. package/dist/checks/before/index.js +162 -0
  304. package/dist/checks/before/mcp.js +111 -0
  305. package/dist/checks/before/repo.js +71 -0
  306. package/dist/checks/before/version.js +60 -0
  307. package/dist/checks/status-holes.js +393 -0
  308. package/dist/cli.js +692 -0
  309. package/dist/commands/analysis.js +325 -0
  310. package/dist/commands/ci/ci.js +438 -0
  311. package/dist/commands/comply.js +310 -0
  312. package/dist/commands/harvest.js +354 -0
  313. package/dist/commands/install/check.js +61 -0
  314. package/dist/commands/install/doctor.js +207 -0
  315. package/dist/commands/install/install.js +461 -0
  316. package/dist/commands/install/uninstall.js +815 -0
  317. package/dist/commands/install/upgrade.js +771 -0
  318. package/dist/commands/launch.js +118 -0
  319. package/dist/commands/lib.js +362 -0
  320. package/dist/commands/registry.js +50 -0
  321. package/dist/commands/setup/setup.js +158 -0
  322. package/dist/commands/telemetry.js +29 -0
  323. package/dist/commands/workflow/branches.js +1265 -0
  324. package/dist/commands/workflow/context.js +846 -0
  325. package/dist/commands/workflow/counters.js +227 -0
  326. package/dist/commands/workflow/fids.js +224 -0
  327. package/dist/commands/workflow/issues.js +585 -0
  328. package/dist/commands/workflow/ledgers.js +472 -0
  329. package/dist/commands/workflow/locks.js +364 -0
  330. package/dist/commands/workflow/prs.js +904 -0
  331. package/dist/commands/workflow/repo.js +199 -0
  332. package/dist/commands/workflow/roadmap.js +495 -0
  333. package/dist/commands/workflow/runs.js +1717 -0
  334. package/dist/commands/workflow/runtime.js +257 -0
  335. package/dist/commands/workflow/skills.js +110 -0
  336. package/dist/commands/workflow/status.js +392 -0
  337. package/dist/commands/workflow/steps.js +1093 -0
  338. package/dist/commands/workflow/tests.js +144 -0
  339. package/dist/commands/workflow/workflows.js +1342 -0
  340. package/dist/commands/workflow/workstreams.js +141 -0
  341. package/dist/commands/workflow/worktrees.js +473 -0
  342. package/dist/install/cloud-env.js +819 -0
  343. package/dist/install/managed-block.js +182 -0
  344. package/dist/install/manifest.js +376 -0
  345. package/dist/install/modules/claude.js +288 -0
  346. package/dist/install/modules/cloud.js +152 -0
  347. package/dist/install/modules/codex.js +193 -0
  348. package/dist/install/modules/core.js +511 -0
  349. package/dist/install/modules/cursor.js +186 -0
  350. package/dist/install/modules/index.js +152 -0
  351. package/dist/install/modules/opencode.js +504 -0
  352. package/dist/install/placeholders.js +87 -0
  353. package/dist/install/template-copies.js +106 -0
  354. package/dist/install/version-file.js +204 -0
  355. package/dist/install/write.js +342 -0
  356. package/dist/ledgers/clamp-log.js +27 -0
  357. package/dist/ledgers/status.js +156 -0
  358. package/dist/ledgers/telemetry.js +637 -0
  359. package/dist/render/hosts.js +339 -0
  360. package/dist/render/models.js +288 -0
  361. package/dist/render/parts.js +33 -0
  362. package/dist/render/trackers.js +135 -0
  363. package/dist/shared/egress.js +299 -0
  364. package/dist/shared/json.js +16 -0
  365. package/dist/shared/log-prefix.js +7 -0
  366. package/dist/shared/package-json.js +22 -0
  367. package/dist/shared/package-manager.js +32 -0
  368. package/dist/shared/package-roots.js +145 -0
  369. package/dist/shared/protected-paths.js +153 -0
  370. package/dist/shared/settings.js +44 -0
  371. package/dist/shared/timeouts.js +19 -0
  372. package/dist/tools/wording.js +680 -0
  373. package/package.json +101 -4
@@ -0,0 +1,904 @@
1
+ // bkit prs open|probe|merge|update-branch|checks|verbose-ci|scan-body|cross-check|transport-row —
2
+ // the pull-request side of a phase close, and the close audit trail.
3
+ //
4
+ // `gh` is the only transport `open` and `probe` drive. When it is missing or not
5
+ // logged in (`gh` exits 4) they exit 80 instead, and `open` still prints the title
6
+ // and body, so the workflow makes the same call through the GitHub MCP tool. Every
7
+ // PR `open` creates carries the `bkit:issue` / `bkit:fid` marker: `/bkit-auto`
8
+ // reads it first and only guesses from the branch name when it is missing.
9
+ import * as fs from "node:fs";
10
+ import * as path from "node:path";
11
+ import { readBkitConfig } from "../../shared/settings.js";
12
+ import { appendLine, statusTimestamp } from "../../ledgers/status.js";
13
+ import { bodySkipToken, CommandError, EXIT, ghUnavailable, git, parseJson, repoRoot, runGh, runGit, SKIP_CI_TOKEN, } from "../lib.js";
14
+ import { AUTO_LABEL, AUTO_ROUTE_SUFFIX } from "./issues.js";
15
+ import { EXIT_NO_STATUS, FILE_FLAG, readStatusRows, statusFile, str } from "./status.js";
16
+ // ---------------------------------------------------------------------------
17
+ // gh
18
+ // ---------------------------------------------------------------------------
19
+ const PR_FIELDS = "number,url,state,baseRefName,headRefName,headRefOid,title,mergeCommit";
20
+ function ghFailure(res, what) {
21
+ const detail = res.stderr.split("\n").at(-1) || `exit ${String(res.status)}`;
22
+ return ghUnavailable(res)
23
+ ? { kind: "unavailable", message: `gh unavailable for ${what}: ${detail}` }
24
+ : { kind: "failed", message: `${what} failed: ${detail}` };
25
+ }
26
+ /**
27
+ * The PR for a head branch, or one PR by number. With `state: "all"` an OPEN PR
28
+ * wins over a MERGED one and a CLOSED one is never picked — ship resumes from a
29
+ * merged PR but must not adopt an abandoned one.
30
+ */
31
+ export function probePr(cwd, opts) {
32
+ if (opts.number !== undefined) {
33
+ const res = runGh(cwd, ["pr", "view", opts.number, "--json", `${PR_FIELDS},mergeable`]);
34
+ if (!res.ok)
35
+ return ghFailure(res, `gh pr view ${opts.number}`);
36
+ const parsed = parseJson(res.stdout);
37
+ if (!parsed.ok)
38
+ return { kind: "failed", message: "gh pr view printed no JSON" };
39
+ return { kind: "ok", pr: parsed.value };
40
+ }
41
+ const args = ["pr", "list", "--head", opts.head, "--state", opts.state, "--json", PR_FIELDS];
42
+ if (opts.base !== undefined)
43
+ args.push("--base", opts.base);
44
+ const res = runGh(cwd, args);
45
+ if (!res.ok)
46
+ return ghFailure(res, `gh pr list --head ${opts.head}`);
47
+ const parsed = parseJson(res.stdout);
48
+ if (!parsed.ok || !Array.isArray(parsed.value)) {
49
+ return { kind: "failed", message: "gh pr list printed no JSON array" };
50
+ }
51
+ const prs = parsed.value;
52
+ const pr = opts.state === "open"
53
+ ? prs[0]
54
+ : (prs.find((p) => p.state === "OPEN") ?? prs.find((p) => p.state === "MERGED"));
55
+ return { kind: "ok", pr };
56
+ }
57
+ export function prOutput(pr) {
58
+ return {
59
+ found: pr !== undefined,
60
+ number: pr?.number ?? null,
61
+ url: pr?.url ?? null,
62
+ state: pr?.state ?? null,
63
+ baseRefName: pr?.baseRefName ?? null,
64
+ headRefName: pr?.headRefName ?? null,
65
+ headRefOid: pr?.headRefOid ?? null,
66
+ title: pr?.title ?? null,
67
+ titleSkipToken: (pr?.title !== undefined && SKIP_CI_TOKEN.exec(pr.title)?.[0]) || null,
68
+ mergeCommitOid: pr?.mergeCommit?.oid ?? null,
69
+ mergeable: pr?.mergeable ?? null,
70
+ };
71
+ }
72
+ const PR_OUTPUT_KEYS = {
73
+ found: "whether a PR was found",
74
+ number: "PR number, or null",
75
+ url: "PR URL, or null",
76
+ state: "OPEN | MERGED | CLOSED, or null",
77
+ baseRefName: "base branch, or null",
78
+ headRefName: "head branch, or null",
79
+ headRefOid: "head commit, or null",
80
+ title: "PR title, or null",
81
+ titleSkipToken: "the CI-suppressing token in the title, or null (a merge of this title would skip CI on dev)",
82
+ mergeCommitOid: "squash/merge commit once merged, or null",
83
+ mergeable: "MERGEABLE | CONFLICTING | UNKNOWN (with --number only), or null",
84
+ };
85
+ function currentBranch(cwd) {
86
+ const branch = git(cwd, ["branch", "--show-current"]) ?? "";
87
+ if (branch === "")
88
+ throw new CommandError(EXIT.USAGE, "detached HEAD — pass --head explicitly");
89
+ return branch;
90
+ }
91
+ /** A git ref given on the command line; a leading `-` would be read as an option. */
92
+ function refFlag(value, flag) {
93
+ const s = String(value ?? "");
94
+ if (s === "" || s.startsWith("-")) {
95
+ throw new CommandError(EXIT.USAGE, `--${flag} must be a non-empty ref not starting with "-"`);
96
+ }
97
+ return s;
98
+ }
99
+ // ---------------------------------------------------------------------------
100
+ // open
101
+ // ---------------------------------------------------------------------------
102
+ /** FID allowlists per tracker — the same ones `/bkit-auto` asserts when it reads the marker back. */
103
+ const FID_FORMAT = {
104
+ github: /^[0-9]+-[a-z0-9-]+$/,
105
+ linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
106
+ none: /^[a-z0-9][a-z0-9-]*$/,
107
+ };
108
+ const ISSUE_FORMAT = {
109
+ github: /^[0-9]+$/,
110
+ linear: /^[A-Z]+-[0-9]+$/,
111
+ };
112
+ /** The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). */
113
+ export function prMarker(tracker, fid, issue) {
114
+ if (!FID_FORMAT[tracker].test(fid)) {
115
+ throw new CommandError(EXIT.USAGE, `--fid "${fid}" is not a ${tracker} FID slug`);
116
+ }
117
+ if (tracker === "none")
118
+ return `<!-- bkit:fid=${fid} -->`;
119
+ const id = (issue ?? "").replace(/^#/, "");
120
+ if (!ISSUE_FORMAT[tracker].test(id)) {
121
+ throw new CommandError(EXIT.USAGE, `--issue "${issue ?? ""}" is not a ${tracker} issue id`);
122
+ }
123
+ return tracker === "github"
124
+ ? `<!-- bkit:issue=#${id} bkit:fid=${fid} -->`
125
+ : `<!-- bkit:issue=${id} bkit:fid=${fid} -->`;
126
+ }
127
+ /** Marker line, then a `bkit:start` / `bkit:end` block with the notes and the plan path. */
128
+ export function prBody(marker, notes, plan) {
129
+ const block = [...notes, ...(plan === undefined ? [] : [plan])];
130
+ return [marker, ...(block.length ? ["<!-- bkit:start -->", ...block, "<!-- bkit:end -->"] : [])]
131
+ .join("\n")
132
+ .concat("\n");
133
+ }
134
+ export const EXIT_PR_EXISTS = 3;
135
+ export const EXIT_SKIP_CI_TITLE = 4;
136
+ export const EXIT_GH_FAILED = 5;
137
+ export const EXIT_WRONG_BASE = 6;
138
+ /** Open (or, with `existing: "reuse"`, reuse) the PR for `head`; `code` is the verb's exit code. */
139
+ export function openPrFor(cwd, o, log) {
140
+ const tracker = readBkitConfig(repoRoot(cwd)).issueTracker;
141
+ if (tracker === "none" && o.issue !== undefined)
142
+ log("--issue ignored: no tracker wired");
143
+ const marker = prMarker(tracker, o.fid, o.issue);
144
+ const title = o.title;
145
+ if (title.trim() === "")
146
+ throw new CommandError(EXIT.USAGE, "--title must be non-empty");
147
+ const token = SKIP_CI_TOKEN.exec(title);
148
+ if (token) {
149
+ log(`refusing: PR title carries the CI-suppressing token ${token[0]} — CI would never run`);
150
+ return { code: EXIT_SKIP_CI_TITLE, out: null };
151
+ }
152
+ const base = refFlag(o.base ?? "dev", "base");
153
+ const head = o.head === undefined ? currentBranch(cwd) : refFlag(o.head, "head");
154
+ if (head === base || head === "dev" || head === "main") {
155
+ throw new CommandError(EXIT.USAGE, `refusing to open a PR from "${head}" into "${base}"`);
156
+ }
157
+ let plan = o.plan;
158
+ if (plan !== undefined && !fs.existsSync(path.resolve(cwd, plan))) {
159
+ log(`plan ${plan} not present — PR body names no plan`);
160
+ plan = undefined;
161
+ }
162
+ const body = prBody(marker, o.notes ?? [], plan);
163
+ const viaMcp = (why) => {
164
+ log(`${why} — create the PR through the GitHub MCP tool with this title and body`);
165
+ return {
166
+ code: EXIT.USE_MCP,
167
+ out: { created: false, useMcp: true, number: null, url: null, base, head, title, body },
168
+ };
169
+ };
170
+ const existing = probePr(cwd, { head, base, state: "open" });
171
+ if (existing.kind === "unavailable")
172
+ return viaMcp(existing.message);
173
+ if (existing.kind === "failed") {
174
+ log(existing.message);
175
+ return { code: EXIT_GH_FAILED, out: null };
176
+ }
177
+ if (existing.pr) {
178
+ const out = {
179
+ created: false,
180
+ useMcp: false,
181
+ number: existing.pr.number,
182
+ url: existing.pr.url,
183
+ base,
184
+ head,
185
+ title: existing.pr.title,
186
+ body,
187
+ };
188
+ if (o.existing === "reuse") {
189
+ log(`reusing open PR #${existing.pr.number} on ${head}`);
190
+ return { code: EXIT.OK, out };
191
+ }
192
+ log(`${head} already has open PR #${existing.pr.number} to ${base} — refusing to blind-create (resume via /bkit-debug or close the stale PR)`);
193
+ return { code: EXIT_PR_EXISTS, out };
194
+ }
195
+ const createArgs = [
196
+ "pr",
197
+ "create",
198
+ "--base",
199
+ base,
200
+ "--head",
201
+ head,
202
+ "--title",
203
+ title,
204
+ "--body",
205
+ body,
206
+ ];
207
+ let created = runGh(cwd, createArgs);
208
+ if (!created.ok && !ghUnavailable(created)) {
209
+ log(`gh pr create failed (${created.stderr || `exit ${String(created.status)}`}) — retrying once`);
210
+ created = runGh(cwd, createArgs);
211
+ }
212
+ if (ghUnavailable(created))
213
+ return viaMcp("gh unavailable for gh pr create");
214
+ if (!created.ok) {
215
+ log(`gh pr create failed twice: ${created.stderr || `exit ${String(created.status)}`}`);
216
+ return { code: EXIT_GH_FAILED, out: null };
217
+ }
218
+ // gh prints the new PR's URL; reading the PR back is what proves its base.
219
+ const url = created.stdout.split("\n").at(-1) ?? "";
220
+ const back = probePr(cwd, { number: url, state: "open" });
221
+ if (back.kind !== "ok" || !back.pr) {
222
+ log(`created ${url} but could not read it back: ${back.kind === "ok" ? "empty" : back.message}`);
223
+ return { code: EXIT_GH_FAILED, out: null };
224
+ }
225
+ const out = {
226
+ created: true,
227
+ useMcp: false,
228
+ number: back.pr.number,
229
+ url: back.pr.url,
230
+ base: back.pr.baseRefName,
231
+ head,
232
+ title: back.pr.title,
233
+ body,
234
+ };
235
+ if (back.pr.baseRefName !== base) {
236
+ log(`PR #${back.pr.number} targets ${back.pr.baseRefName}, not ${base}`);
237
+ return { code: EXIT_WRONG_BASE, out };
238
+ }
239
+ return { code: EXIT.OK, out };
240
+ }
241
+ function openPr(ctx) {
242
+ const r = openPrFor(ctx.cwd, {
243
+ fid: String(ctx.flags.fid),
244
+ title: String(ctx.flags.title),
245
+ issue: str(ctx.flags.issue),
246
+ base: str(ctx.flags.base),
247
+ head: str(ctx.flags.head),
248
+ plan: str(ctx.flags.plan),
249
+ notes: ctx.flags.note ?? [],
250
+ existing: str(ctx.flags.existing),
251
+ }, ctx.log);
252
+ if (r.out)
253
+ ctx.emit(r.out);
254
+ return r.code;
255
+ }
256
+ // ---------------------------------------------------------------------------
257
+ // merge
258
+ // ---------------------------------------------------------------------------
259
+ /** Exit code (merge --expect-merged): the PR did not reach MERGED. */
260
+ export const EXIT_NOT_MERGED = 7;
261
+ /**
262
+ * Squash-merge a PR with an explicit empty body (never the default concatenated
263
+ * subjects), unless it is already MERGED, then read the state back. gh missing →
264
+ * EXIT.USE_MCP (merge through `merge_pull_request` with `subject`).
265
+ */
266
+ export function mergePr(cwd, o, log) {
267
+ const read = () => probePr(cwd, { number: o.number, state: "open" });
268
+ const result = (code, pr, already) => {
269
+ const merged = pr?.state === "MERGED";
270
+ return {
271
+ code,
272
+ out: {
273
+ merged,
274
+ alreadyMerged: already,
275
+ state: pr?.state ?? null,
276
+ mergeCommitOid: pr?.mergeCommit?.oid ?? null,
277
+ subject: o.subject,
278
+ verdict: merged ? "PASS" : "FAIL",
279
+ failures: merged ? 0 : 1,
280
+ },
281
+ };
282
+ };
283
+ const before = read();
284
+ if (before.kind === "unavailable") {
285
+ log(`${before.message} — merge through merge_pull_request with this subject and an empty body`);
286
+ return result(EXIT.USE_MCP, undefined, false);
287
+ }
288
+ if (before.kind === "failed") {
289
+ log(before.message);
290
+ return result(EXIT_GH_FAILED, undefined, false);
291
+ }
292
+ if (before.pr?.state === "MERGED")
293
+ return result(EXIT.OK, before.pr, true);
294
+ const args = ["pr", "merge", o.number, "--squash", "--subject", o.subject, "--body", ""];
295
+ if (o.deleteBranch === true)
296
+ args.push("--delete-branch");
297
+ if (o.matchHead !== undefined)
298
+ args.push("--match-head-commit", o.matchHead);
299
+ const merged = runGh(cwd, args);
300
+ if (ghUnavailable(merged)) {
301
+ log("gh unavailable for gh pr merge — merge through merge_pull_request with this subject and an empty body");
302
+ return result(EXIT.USE_MCP, before.pr, false);
303
+ }
304
+ if (!merged.ok)
305
+ log(`gh pr merge ${o.number} failed: ${merged.stderr || `exit ${String(merged.status)}`}`);
306
+ const after = read();
307
+ if (after.kind !== "ok") {
308
+ log(after.message);
309
+ return result(EXIT_GH_FAILED, undefined, false);
310
+ }
311
+ return result(EXIT.OK, after.pr, false);
312
+ }
313
+ /**
314
+ * Request a server-side base-into-head refresh (ship Step 4 B1). GitHub authors
315
+ * the merge commit, so bkit cannot set its message and there is no local head to
316
+ * read back — ship's Step 9 poll observes the new head. gh missing →
317
+ * EXIT.USE_MCP (route through `update_pull_request_branch`).
318
+ */
319
+ export function updateBranch(cwd, number, log) {
320
+ const res = runGh(cwd, ["pr", "update-branch", number]);
321
+ if (ghUnavailable(res)) {
322
+ log("gh unavailable for gh pr update-branch — update the branch through update_pull_request_branch");
323
+ return { code: EXIT.USE_MCP, out: null };
324
+ }
325
+ if (!res.ok) {
326
+ const detail = res.stderr.split("\n").at(-1) || `exit ${String(res.status)}`;
327
+ log(`gh pr update-branch ${number} failed: ${detail} (403 = actions:write scope, network, branch protection) — PR head NOT integrated`);
328
+ return { code: EXIT_GH_FAILED, out: null };
329
+ }
330
+ return { code: EXIT.OK, out: { number, updated: true } };
331
+ }
332
+ // ---------------------------------------------------------------------------
333
+ // checks
334
+ // ---------------------------------------------------------------------------
335
+ /** Exit code (checks): the PR's check rollup could not be read. */
336
+ export const EXIT_CHECKS_UNREADABLE = 4;
337
+ /** Conclusions / states a finished check may carry and still count as passing. */
338
+ const PASS_STATES = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
339
+ /**
340
+ * The PR's check rollup, classified (ship Step 2's post-open assert). `green` only
341
+ * when at least one check exists and none is failed or pending. A check run is
342
+ * open until `status` = `COMPLETED`; a commit status is open while its `state` is
343
+ * `PENDING` / `EXPECTED`. gh missing → EXIT.USE_MCP (read the rollup through
344
+ * `pull_request_read` `get_status`).
345
+ */
346
+ export function checksFor(cwd, number, log) {
347
+ const res = runGh(cwd, ["pr", "view", number, "--json", "statusCheckRollup"]);
348
+ if (ghUnavailable(res)) {
349
+ log("gh unavailable for gh pr view --json statusCheckRollup — read the rollup through pull_request_read (get_status)");
350
+ return { code: EXIT.USE_MCP, out: null };
351
+ }
352
+ if (!res.ok) {
353
+ log(`gh pr view ${number} failed: ${res.stderr.split("\n").at(-1) || `exit ${String(res.status)}`}`);
354
+ return { code: EXIT_CHECKS_UNREADABLE, out: null };
355
+ }
356
+ const parsed = parseJson(res.stdout);
357
+ if (!parsed.ok) {
358
+ log("gh pr view printed no JSON");
359
+ return { code: EXIT_CHECKS_UNREADABLE, out: null };
360
+ }
361
+ const rawRollup = parsed.value.statusCheckRollup;
362
+ const checks = (Array.isArray(rawRollup) ? rawRollup : []);
363
+ let passing = 0;
364
+ let failed = 0;
365
+ let pending = 0;
366
+ const failing = [];
367
+ for (const c of checks) {
368
+ const name = String(c.name ?? c.context ?? "").trim();
369
+ const status = String(c.status ?? "").toUpperCase();
370
+ const state = String(c.state ?? "").toUpperCase();
371
+ const conclusion = String(c.conclusion ?? "").toUpperCase();
372
+ // A check run carries `status`; a commit status carries `state`.
373
+ const open = status !== "" ? status !== "COMPLETED" : state === "PENDING" || state === "EXPECTED";
374
+ if (open) {
375
+ pending++;
376
+ }
377
+ else if (PASS_STATES.has(conclusion || state)) {
378
+ passing++;
379
+ }
380
+ else {
381
+ failed++;
382
+ if (name)
383
+ failing.push(name);
384
+ }
385
+ }
386
+ const green = checks.length > 0 && failed === 0 && pending === 0;
387
+ const out = {
388
+ number,
389
+ total: checks.length,
390
+ passing,
391
+ failed,
392
+ pending,
393
+ green,
394
+ failing,
395
+ };
396
+ if (!green)
397
+ log(`PR ${number} is not green: ${String(failed)} failed, ${String(pending)} pending, ${String(checks.length)} total`);
398
+ return { code: green ? EXIT.OK : EXIT.NO, out };
399
+ }
400
+ /** The latest row of `type` in the log, or undefined. */
401
+ const lastRow = (rows, type) => rows.filter((r) => r.type === type).at(-1);
402
+ /** A capability value as the shell compared it: by its string form. */
403
+ function capability(v) {
404
+ const s = String(v);
405
+ return s === "true" ? true : s === "false" ? false : null;
406
+ }
407
+ export const EXIT_UNREADABLE_COMMIT = 3;
408
+ /** Exit code (transport-row --scan): the landed commit's message could not be read. */
409
+ export const EXIT_SCAN_UNREADABLE = 8;
410
+ /**
411
+ * Scan a landed commit's BODY for a CI-suppressing token. The subject is skipped on
412
+ * purpose: a docs-only close carries `bkit [skip ci]` there by convention. The
413
+ * defect is a squash body that concatenates branch commit subjects and so inherits
414
+ * a token nobody meant to put on the shared branch.
415
+ */
416
+ function scanBody(ctx) {
417
+ const sha = refFlag(ctx.flags.sha, "sha");
418
+ const remote = str(ctx.flags.remoteRef);
419
+ if (remote !== undefined) {
420
+ const fetched = runGit(ctx.cwd, ["fetch", "origin", refFlag(remote, "remote-ref")]);
421
+ if (!fetched.ok)
422
+ ctx.log(`git fetch origin ${remote} failed — scanning what is local`);
423
+ }
424
+ const token = bodySkipToken(ctx.cwd, sha);
425
+ if (token === undefined) {
426
+ ctx.log(`could not read the commit message for ${sha}`);
427
+ return EXIT_UNREADABLE_COMMIT;
428
+ }
429
+ if (token)
430
+ ctx.log(`landed commit ${sha} body inherited a CI-suppression token ${token}`);
431
+ ctx.emit({ sha, scanResult: token ? "skip-token-found" : "clean", token });
432
+ return token ? EXIT.NO : EXIT.OK;
433
+ }
434
+ const TRANSPORTS = ["git", "gh", "mcp"];
435
+ /**
436
+ * A close that went through a mapped MCP tool while Step 1 recorded `gh` as
437
+ * unavailable must have written a `transport-fallback` row. Only `mcp` is checked:
438
+ * a `git` close needs no `gh`, so a laptop that never ran `gh auth login` closes fine.
439
+ */
440
+ export function crossCheckFile(file, transport, log) {
441
+ if (!TRANSPORTS.includes(transport)) {
442
+ throw new CommandError(EXIT.USAGE, `--transport must be ${TRANSPORTS.join(", ")}`);
443
+ }
444
+ const rows = readStatusRows(file);
445
+ const runtimeGithubCli = capability(lastRow(rows, "runtime-resolved")?.runtimeGithubCli);
446
+ const fallbackRows = rows.filter((r) => r.type === "transport-fallback").length;
447
+ const violated = runtimeGithubCli === false && transport === "mcp" && fallbackRows === 0;
448
+ if (violated) {
449
+ log(`runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${file}`);
450
+ }
451
+ return { ok: !violated, runtimeGithubCli, transport, fallbackRows };
452
+ }
453
+ function crossCheck(ctx) {
454
+ const r = crossCheckFile(statusFile(ctx), String(ctx.flags.transport), ctx.log);
455
+ ctx.emit({ ...r });
456
+ return r.ok ? EXIT.OK : EXIT.NO;
457
+ }
458
+ /** Append a `close-transport` row: which close shape landed which commit, and its body scan. */
459
+ export function closeTransportRow(file, o) {
460
+ if (!SHAPES.includes(o.shape))
461
+ throw new CommandError(EXIT.USAGE, `--shape must be ${SHAPES.join(", ")}`);
462
+ if (!SCAN_RESULTS.includes(o.scanResult))
463
+ throw new CommandError(EXIT.USAGE, `--scan-result must be ${SCAN_RESULTS.join(", ")}`);
464
+ if (o.sha === "")
465
+ throw new CommandError(EXIT.USAGE, "--kind=close needs a non-empty --sha");
466
+ if (!fs.existsSync(file))
467
+ throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
468
+ const row = {
469
+ type: "close-transport",
470
+ shape: o.shape,
471
+ sha: o.sha,
472
+ scanResult: o.scanResult,
473
+ at: statusTimestamp(),
474
+ };
475
+ fs.appendFileSync(file, appendLine(row));
476
+ return row;
477
+ }
478
+ const SHAPES = ["local", "pr", "push"];
479
+ const SCAN_RESULTS = ["clean", "skip-token-found"];
480
+ function nonEmpty(ctx, flag, key, allowed) {
481
+ const v = str(ctx.flags[key]);
482
+ if (v === undefined || v === "") {
483
+ throw new CommandError(EXIT.USAGE, `--kind=${String(ctx.flags.kind)} needs a non-empty --${flag}`);
484
+ }
485
+ if (allowed && !allowed.includes(v)) {
486
+ throw new CommandError(EXIT.USAGE, `--${flag} must be ${allowed.join(", ")}`);
487
+ }
488
+ return v;
489
+ }
490
+ function transportRow(ctx) {
491
+ const kind = String(ctx.flags.kind);
492
+ const file = statusFile(ctx);
493
+ if (kind === "close" && (ctx.flags.scan === true || ctx.flags.crossCheck !== undefined)) {
494
+ return auditedClose(ctx, file);
495
+ }
496
+ let row;
497
+ if (kind === "fallback") {
498
+ row = {
499
+ type: "transport-fallback",
500
+ from: nonEmpty(ctx, "from", "from"),
501
+ to: nonEmpty(ctx, "to", "to"),
502
+ reason: nonEmpty(ctx, "reason", "reason"),
503
+ assertedBy: nonEmpty(ctx, "asserted-by", "assertedBy"),
504
+ at: statusTimestamp(),
505
+ };
506
+ }
507
+ else if (kind === "close") {
508
+ row = {
509
+ type: "close-transport",
510
+ shape: nonEmpty(ctx, "shape", "shape", SHAPES),
511
+ sha: nonEmpty(ctx, "sha", "sha"),
512
+ scanResult: nonEmpty(ctx, "scan-result", "scanResult", SCAN_RESULTS),
513
+ at: statusTimestamp(),
514
+ };
515
+ }
516
+ else {
517
+ throw new CommandError(EXIT.USAGE, "--kind must be fallback or close");
518
+ }
519
+ if (!fs.existsSync(file))
520
+ throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
521
+ fs.appendFileSync(file, appendLine(row));
522
+ ctx.emit({ row });
523
+ return EXIT.OK;
524
+ }
525
+ /**
526
+ * The whole close audit in one call: scan the landed commit's body (`--scan`),
527
+ * cross-check the transport (`--cross-check`), write the close-transport row, and
528
+ * refuse (exit 1) a landed body carrying a skip token — after recording it.
529
+ */
530
+ function auditedClose(ctx, file) {
531
+ const sha = refFlag(ctx.flags.sha, "sha");
532
+ const shape = nonEmpty(ctx, "shape", "shape", SHAPES);
533
+ let scanResult = str(ctx.flags.scanResult);
534
+ if (ctx.flags.scan === true) {
535
+ const remote = str(ctx.flags.remoteRef);
536
+ if (remote !== undefined &&
537
+ !runGit(ctx.cwd, ["fetch", "origin", refFlag(remote, "remote-ref")]).ok)
538
+ ctx.log(`git fetch origin ${remote} failed — scanning what is local`);
539
+ const token = bodySkipToken(ctx.cwd, sha);
540
+ if (token === undefined) {
541
+ ctx.log(`post-close body scan could not read ${sha}`);
542
+ return EXIT_SCAN_UNREADABLE;
543
+ }
544
+ scanResult = token ? "skip-token-found" : "clean";
545
+ }
546
+ if (scanResult === undefined)
547
+ throw new CommandError(EXIT.USAGE, "give --scan or --scan-result");
548
+ const transport = str(ctx.flags.crossCheck);
549
+ if (transport !== undefined) {
550
+ const check = crossCheckFile(file, transport, ctx.log);
551
+ if (!check.ok) {
552
+ ctx.log("close transport cross-check failed");
553
+ return EXIT.NO;
554
+ }
555
+ }
556
+ const row = closeTransportRow(file, { shape, sha, scanResult });
557
+ ctx.emit({ row });
558
+ if (scanResult !== "clean") {
559
+ ctx.log(`landed commit ${sha} inherited a CI-suppression token in its body`);
560
+ return EXIT.NO;
561
+ }
562
+ return EXIT.OK;
563
+ }
564
+ // ---------------------------------------------------------------------------
565
+ // Command
566
+ // ---------------------------------------------------------------------------
567
+ const HEAD_FLAG = {
568
+ name: "head",
569
+ type: "string",
570
+ help: "head branch (default: the current branch)",
571
+ };
572
+ const BASE_FLAG = { name: "base", type: "string", help: "base branch (default dev)" };
573
+ export const prsCommand = {
574
+ noun: "prs",
575
+ summary: "Open and probe pull requests, and audit the close transport.",
576
+ verbs: {
577
+ open: {
578
+ summary: "Open a PR whose body carries the bkit:issue / bkit:fid marker (exit 80: use MCP).",
579
+ flags: [
580
+ { name: "fid", type: "string", required: true, help: "feature id" },
581
+ { name: "title", type: "string", required: true, help: "PR title (no skip-CI token)" },
582
+ {
583
+ name: "issue",
584
+ type: "string",
585
+ help: "issue id for the marker (github: 123 or #123; linear: ABC-123)",
586
+ },
587
+ BASE_FLAG,
588
+ HEAD_FLAG,
589
+ { name: "plan", type: "string", help: "plan path named in the body, when the file exists" },
590
+ {
591
+ name: "note",
592
+ type: "string",
593
+ repeatable: true,
594
+ help: "line placed above the plan path in the bkit block",
595
+ },
596
+ {
597
+ name: "existing",
598
+ type: "string",
599
+ help: "an open PR already on --head: fail (default, exit 3) | reuse",
600
+ },
601
+ ],
602
+ output: {
603
+ created: "true when this run created the PR",
604
+ useMcp: "true when gh is unavailable: create it through MCP with title/body/base/head",
605
+ number: "PR number, or null",
606
+ url: "PR URL, or null",
607
+ base: "base branch (read back from the PR when created)",
608
+ head: "head branch",
609
+ title: "PR title",
610
+ body: "PR body, marker first",
611
+ },
612
+ exitCodes: {
613
+ [EXIT_PR_EXISTS]: "--head already has an open PR (with --existing=fail)",
614
+ [EXIT_SKIP_CI_TITLE]: "the title carries a CI-suppressing token",
615
+ [EXIT_GH_FAILED]: "gh errored (probe, create after one retry, or read-back)",
616
+ [EXIT_WRONG_BASE]: "the created PR's base is not --base",
617
+ },
618
+ run: (ctx) => {
619
+ const existing = str(ctx.flags.existing);
620
+ if (existing !== undefined && !["fail", "reuse"].includes(existing)) {
621
+ throw new CommandError(EXIT.USAGE, "--existing must be fail or reuse");
622
+ }
623
+ return openPr(ctx);
624
+ },
625
+ },
626
+ probe: {
627
+ summary: "The open (or open-then-merged) PR for a branch, or one PR by number.",
628
+ flags: [
629
+ HEAD_FLAG,
630
+ { name: "base", type: "string", help: "only PRs into this base (default: any base)" },
631
+ { name: "state", type: "string", help: "open (default) | all: OPEN wins, then MERGED" },
632
+ { name: "number", type: "string", help: "read this PR instead of listing by --head" },
633
+ ],
634
+ output: PR_OUTPUT_KEYS,
635
+ exitCodes: { 4: "gh errored — the probe could not answer" },
636
+ run: (ctx) => {
637
+ const state = str(ctx.flags.state) ?? "open";
638
+ if (state !== "open" && state !== "all") {
639
+ throw new CommandError(EXIT.USAGE, "--state must be open or all");
640
+ }
641
+ const number = str(ctx.flags.number);
642
+ if (number !== undefined && !/^[1-9][0-9]*$/.test(number)) {
643
+ throw new CommandError(EXIT.USAGE, "--number must be a PR number");
644
+ }
645
+ const res = probePr(ctx.cwd, {
646
+ number,
647
+ state,
648
+ head: number !== undefined
649
+ ? undefined
650
+ : ctx.flags.head === undefined
651
+ ? currentBranch(ctx.cwd)
652
+ : refFlag(ctx.flags.head, "head"),
653
+ base: ctx.flags.base === undefined ? undefined : refFlag(ctx.flags.base, "base"),
654
+ });
655
+ if (res.kind !== "ok") {
656
+ ctx.log(res.message);
657
+ return res.kind === "unavailable" ? EXIT.USE_MCP : 4;
658
+ }
659
+ ctx.emit(prOutput(res.pr));
660
+ return res.pr ? EXIT.OK : EXIT.NO;
661
+ },
662
+ },
663
+ merge: {
664
+ summary: "Squash-merge a PR with an empty body (skipped when already MERGED) and read its state back.",
665
+ flags: [
666
+ { name: "number", type: "string", required: true, help: "the PR number" },
667
+ {
668
+ name: "subject",
669
+ type: "string",
670
+ help: "squash subject (default: the PR title + ` (#N)`)",
671
+ },
672
+ {
673
+ name: "match-head",
674
+ type: "string",
675
+ help: "--match-head-commit SHA: GitHub refuses the merge when the head moved",
676
+ },
677
+ { name: "delete-branch", type: "boolean", help: "delete the head branch after the merge" },
678
+ {
679
+ name: "label",
680
+ type: "string",
681
+ repeatable: true,
682
+ help: "a label the issue carries now: bkit:auto appends ` bkit [auto route]` to the subject",
683
+ },
684
+ {
685
+ name: "expect-merged",
686
+ type: "boolean",
687
+ help: "exit 7 when the PR did not reach MERGED (default: report it, exit 0)",
688
+ },
689
+ ],
690
+ output: {
691
+ merged: "the PR is MERGED",
692
+ alreadyMerged: "it was MERGED before this call (no merge ran)",
693
+ state: "OPEN | MERGED | CLOSED, or null when unread",
694
+ mergeCommitOid: "the squash commit, or null",
695
+ subject: "the squash subject used",
696
+ verdict: "PASS when merged, else FAIL",
697
+ failures: "0 when merged, else 1",
698
+ },
699
+ exitCodes: {
700
+ [EXIT_GH_FAILED]: "gh could not read the PR",
701
+ [EXIT_NOT_MERGED]: "--expect-merged and the PR did not reach MERGED",
702
+ },
703
+ run: (ctx) => {
704
+ const number = String(ctx.flags.number);
705
+ if (!/^[1-9][0-9]*$/.test(number))
706
+ throw new CommandError(EXIT.USAGE, "--number must be a PR number");
707
+ let subject = str(ctx.flags.subject);
708
+ if (subject === undefined) {
709
+ const pr = probePr(ctx.cwd, { number, state: "open" });
710
+ if (pr.kind === "unavailable") {
711
+ ctx.log(`${pr.message} — merge through merge_pull_request`);
712
+ return EXIT.USE_MCP;
713
+ }
714
+ if (pr.kind === "failed" || !pr.pr) {
715
+ ctx.log(pr.kind === "failed" ? pr.message : `PR #${number} not found`);
716
+ return EXIT_GH_FAILED;
717
+ }
718
+ subject = `${pr.pr.title} (#${number})`;
719
+ }
720
+ if ((ctx.flags.label ?? []).includes(AUTO_LABEL))
721
+ subject += AUTO_ROUTE_SUFFIX;
722
+ const r = mergePr(ctx.cwd, {
723
+ number,
724
+ subject,
725
+ matchHead: str(ctx.flags.matchHead),
726
+ deleteBranch: ctx.flags.deleteBranch === true,
727
+ }, ctx.log);
728
+ ctx.emit(r.out);
729
+ if (r.code !== EXIT.OK)
730
+ return r.code;
731
+ return ctx.flags.expectMerged === true && !r.out.merged ? EXIT_NOT_MERGED : EXIT.OK;
732
+ },
733
+ },
734
+ "update-branch": {
735
+ summary: "Refresh a PR's head from its base server-side (exit 80: use update_pull_request_branch).",
736
+ flags: [{ name: "number", type: "string", required: true, help: "the PR number" }],
737
+ output: {
738
+ number: "the PR number",
739
+ updated: "the update request succeeded (true even when already up to date)",
740
+ },
741
+ exitCodes: {
742
+ [EXIT_GH_FAILED]: "gh could not update the branch (403 = actions:write scope)",
743
+ },
744
+ run: (ctx) => {
745
+ const number = String(ctx.flags.number);
746
+ if (!/^[1-9][0-9]*$/.test(number))
747
+ throw new CommandError(EXIT.USAGE, "--number must be a PR number");
748
+ const r = updateBranch(ctx.cwd, number, ctx.log);
749
+ if (r.out)
750
+ ctx.emit(r.out);
751
+ return r.code;
752
+ },
753
+ },
754
+ checks: {
755
+ summary: "A PR's check rollup, classified: green when present and none failed or pending (exit 80: use MCP).",
756
+ flags: [{ name: "number", type: "string", required: true, help: "the PR number" }],
757
+ output: {
758
+ number: "the PR number",
759
+ total: "checks in the rollup",
760
+ passing: "checks that finished successfully (SUCCESS | NEUTRAL | SKIPPED)",
761
+ failed: "checks that finished unsuccessfully",
762
+ pending: "checks not yet finished",
763
+ green: "total > 0 and no check failed or pending",
764
+ failing: "names of the failed checks",
765
+ },
766
+ exitCodes: {
767
+ [EXIT_CHECKS_UNREADABLE]: "gh could not read the PR's check rollup",
768
+ },
769
+ run: (ctx) => {
770
+ const number = String(ctx.flags.number);
771
+ if (!/^[1-9][0-9]*$/.test(number))
772
+ throw new CommandError(EXIT.USAGE, "--number must be a PR number");
773
+ const r = checksFor(ctx.cwd, number, ctx.log);
774
+ if (r.out)
775
+ ctx.emit({ ...r.out });
776
+ return r.code;
777
+ },
778
+ },
779
+ "verbose-ci": {
780
+ summary: "Add ` bkit [verbose ci]` to a PR title, or strip it (with an optional `bkit ` prefix); a no-op when already so.",
781
+ flags: [
782
+ { name: "number", type: "string", required: true, help: "the PR number" },
783
+ { name: "state", type: "string", required: true, help: "on | off" },
784
+ ],
785
+ output: {
786
+ title: "the PR title now",
787
+ changed: "the title was edited",
788
+ },
789
+ exitCodes: { [EXIT_GH_FAILED]: "gh could not read or edit the PR" },
790
+ run: (ctx) => {
791
+ const number = String(ctx.flags.number);
792
+ if (!/^[1-9][0-9]*$/.test(number))
793
+ throw new CommandError(EXIT.USAGE, "--number must be a PR number");
794
+ const state = String(ctx.flags.state);
795
+ if (!["on", "off"].includes(state))
796
+ throw new CommandError(EXIT.USAGE, "--state must be on or off");
797
+ const pr = probePr(ctx.cwd, { number, state: "open" });
798
+ if (pr.kind === "unavailable") {
799
+ ctx.log(`${pr.message} — edit the title through update_pull_request`);
800
+ return EXIT.USE_MCP;
801
+ }
802
+ if (pr.kind === "failed" || !pr.pr) {
803
+ ctx.log(pr.kind === "failed" ? pr.message : `PR #${number} not found`);
804
+ return EXIT_GH_FAILED;
805
+ }
806
+ const title = pr.pr.title;
807
+ const has = title.includes("[verbose ci]");
808
+ const next = state === "on"
809
+ ? has
810
+ ? title
811
+ : `${title} bkit [verbose ci]`
812
+ : title.replace(/ ?(bkit )?\[verbose ci\]/, "");
813
+ if (next === title) {
814
+ ctx.emit({ title, changed: false });
815
+ return EXIT.OK;
816
+ }
817
+ const edit = runGh(ctx.cwd, ["pr", "edit", number, "--title", next]);
818
+ if (ghUnavailable(edit)) {
819
+ ctx.log("gh unavailable for gh pr edit — edit the title through update_pull_request");
820
+ return EXIT.USE_MCP;
821
+ }
822
+ if (!edit.ok) {
823
+ ctx.log(`gh pr edit ${number} failed: ${edit.stderr}`);
824
+ return EXIT_GH_FAILED;
825
+ }
826
+ ctx.emit({ title: next, changed: true });
827
+ return EXIT.OK;
828
+ },
829
+ },
830
+ "scan-body": {
831
+ summary: "Check a landed commit's body (not its subject) for a CI-suppressing token.",
832
+ flags: [
833
+ { name: "sha", type: "string", required: true, help: "the landed commit" },
834
+ {
835
+ name: "remote-ref",
836
+ type: "string",
837
+ help: "fetch origin <ref> first (the close merged server-side), e.g. dev",
838
+ },
839
+ ],
840
+ output: {
841
+ sha: "the commit scanned",
842
+ scanResult: "clean | skip-token-found",
843
+ token: "the token found, or null",
844
+ },
845
+ exitCodes: { [EXIT_UNREADABLE_COMMIT]: "the commit message could not be read" },
846
+ run: scanBody,
847
+ },
848
+ "cross-check": {
849
+ summary: "An mcp close with gh recorded unavailable must have a transport-fallback row.",
850
+ flags: [
851
+ FILE_FLAG,
852
+ {
853
+ name: "transport",
854
+ type: "string",
855
+ required: true,
856
+ help: "how the close landed: git | gh | mcp",
857
+ },
858
+ ],
859
+ output: {
860
+ ok: "false when the fallback row is missing",
861
+ runtimeGithubCli: "runtimeGithubCli of the latest runtime-resolved row, or null",
862
+ transport: "the transport checked",
863
+ fallbackRows: "transport-fallback rows in the log",
864
+ },
865
+ exitCodes: { [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON" },
866
+ run: crossCheck,
867
+ },
868
+ "transport-row": {
869
+ summary: "Append a transport-fallback or close-transport audit row to status.jsonl.",
870
+ flags: [
871
+ FILE_FLAG,
872
+ { name: "kind", type: "string", required: true, help: "fallback | close" },
873
+ { name: "from", type: "string", help: "fallback: the gh command that was unavailable" },
874
+ { name: "to", type: "string", help: "fallback: the MCP tool used instead" },
875
+ { name: "reason", type: "string", help: "fallback: why, e.g. runtimeGithubCli=false" },
876
+ {
877
+ name: "asserted-by",
878
+ type: "string",
879
+ help: "fallback: how the fallback's effect was re-read",
880
+ },
881
+ { name: "shape", type: "string", help: "close: local | pr | push" },
882
+ { name: "sha", type: "string", help: "close: the landed commit" },
883
+ { name: "scan-result", type: "string", help: "close: clean | skip-token-found" },
884
+ {
885
+ name: "scan",
886
+ type: "boolean",
887
+ help: "close: scan --sha's body for a skip token instead of --scan-result; a token found is recorded, then exit 1",
888
+ },
889
+ { name: "remote-ref", type: "string", help: "close --scan: fetch origin <ref> first" },
890
+ {
891
+ name: "cross-check",
892
+ type: "string",
893
+ help: "close: first cross-check this transport (git | gh | mcp) against the runtime row; failing it exits 1 unrecorded",
894
+ },
895
+ ],
896
+ output: { row: "the appended row" },
897
+ exitCodes: {
898
+ [EXIT_NO_STATUS]: "status.jsonl does not exist",
899
+ [EXIT_SCAN_UNREADABLE]: "--scan: the commit message could not be read",
900
+ },
901
+ run: transportRow,
902
+ },
903
+ },
904
+ };