@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,82 @@
1
+ #!/usr/bin/env node
2
+ // bkit-gateguard.cjs — bkit GateGuard advisory PreToolUse hook (Claude Code).
3
+ //
4
+ // Fires before Edit / Write / MultiEdit. On the FIRST touch of a given file in a
5
+ // session it injects an investigation checklist into the model's context so the
6
+ // investigation happens BEFORE the edit. A second class of paths — quality-gate
7
+ // configs — gets a stronger "fix the code, don't weaken the gate" advisory. A Write
8
+ // to a not-yet-existing path gets the reuse-over-duplicate checklist (rules.md
9
+ // "Improve over duplicate") instead of the read-this-file checklist.
10
+ //
11
+ // CONTRACT — do not regress:
12
+ // - ADVISORY BY DEFAULT: emits `additionalContext` only, never blocks. Deny mode
13
+ // is wired behind BKIT_GATEGUARD=deny (see MODES).
14
+ // - FAIL OPEN: a single top-level catch swallows every error (the process exits
15
+ // 0 with whatever was already emitted). Normal control paths use existence
16
+ // guards, never try/catch; that catch is the only error sink.
17
+ // - SUBAGENTS INCLUDED: a subagent edit is an edit. Dedup is per (session, file)
18
+ // and a subagent carries its own session id, so it gets its own checklist.
19
+ // - DEDUP: warns once per (session, file); state lives in the OS temp dir keyed
20
+ // by session_id and is GC'd after 24h. Never writes into the consumer repo.
21
+ //
22
+ // MODES (BKIT_GATEGUARD env var):
23
+ // - unset / anything else → advisory (inject context, never block) [DEFAULT]
24
+ // - "off" → disabled (no-op)
25
+ // - "deny" → deny the FIRST touch per file with the checklist as
26
+ // the reason, then allow the retry. Opt-in.
27
+ //
28
+ // BKIT_ALLOW_CONFIG_EDIT=1 → suppress the gate-config advisory (sanctioned edit).
29
+ //
30
+ // Host note: one engine, four hosts. bkit generates this hook at install from one
31
+ // shared engine (bkit's `core/hooks/gateguard-engine.js`) plus the parts that
32
+ // differ per host. `.cursor/hooks/bkit-gateguard.cjs` carries this same managed block (Cursor's
33
+ // preToolUse delivers `additional_context` on an allow); the Codex and opencode hooks
34
+ // carry the same engine behind their own payload adapters. See .bkit/providers.md
35
+ // § GateGuard.
36
+ //
37
+ // OWNERSHIP: everything between the markers below is bkit-managed and is
38
+ // overwritten on every `bkit install` / `bkit upgrade`. It is a pure advisory
39
+ // engine only — no stdin read, no stdout write, no top-level invocation. Add your
40
+ // own logic in the driver that follows the managed block: call
41
+ // `bkitGateguard(payload)`, fold in your own checks, and call `emit()` once.
42
+
43
+ "use strict";
44
+
45
+ // bkit:start
46
+
47
+ // {{BKIT_MANAGED_MARKER}}
48
+
49
+ const fs = require("node:fs");
50
+ const os = require("node:os");
51
+ const path = require("node:path");
52
+
53
+ // {{BKIT_PART gateguard-engine.js}}
54
+
55
+ // {{BKIT_PART gateguard-edit-payload.js}}
56
+
57
+ // bkit:end
58
+
59
+ function emit(payload) {
60
+ process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
61
+ }
62
+
63
+ try {
64
+ const raw = fs.readFileSync(0, "utf-8");
65
+ if (raw.trim()) {
66
+ const payload = JSON.parse(raw);
67
+ const result = bkitGateguard(payload);
68
+ if (result) {
69
+ emit(
70
+ result.mode === "deny"
71
+ ? {
72
+ hookEventName: "PreToolUse",
73
+ permissionDecision: "deny",
74
+ permissionDecisionReason: result.context,
75
+ }
76
+ : { hookEventName: "PreToolUse", additionalContext: result.context },
77
+ );
78
+ }
79
+ }
80
+ } catch {
81
+ process.exitCode = 0; // fail open — never block, never error out
82
+ }
@@ -0,0 +1,93 @@
1
+ #!/usr/bin/env node
2
+ // bkit-guardrails.cjs — bkit shell advisories (Claude Code).
3
+ //
4
+ // Twin of `.cursor/hooks/bkit-guardrails.cjs` and `.codex/hooks/bkit-guardrails.cjs`: bkit
5
+ // generates the same shell detection into all three at install (bkit's
6
+ // `core/hooks/guardrails-shell.js`). Wired from `.claude/settings.json` → PreToolUse,
7
+ // matcher `Bash`.
8
+ //
9
+ // SCOPE — the two shell checks a command-PREFIX permission table cannot express:
10
+ //
11
+ // 1. URL HOSTS. `Bash(curl:*)` matches a prefix, never a URL host. This hook flags a
12
+ // curl / wget whose URL host is off the network allowlist.
13
+ // 2. SHELL-AS-EDIT-CHANNEL. `sed -i` and redirection into a source file bypass every
14
+ // pre-edit gate (GateGuard only sees Edit/Write/MultiEdit). Detection parses the
15
+ // target path.
16
+ //
17
+ // ADVISORY ONLY — this hook NEVER denies and NEVER asks; it emits `additionalContext`.
18
+ // `deny` rows live in settings.json and are evaluated BEFORE any hook. The permission
19
+ // table and the auto-mode classifier are what stop commands.
20
+ //
21
+ // CONTRACT — do not regress:
22
+ // - FAIL OPEN: one top-level catch swallows every error and exits 0.
23
+ // - NEVER BLOCKS: no `permissionDecision` is ever emitted from the managed block.
24
+ // - PURE ENGINE: everything between the markers is a decision engine only — no stdin
25
+ // read, no stdout write. Add your own gates in the driver below the block.
26
+ //
27
+ // OWNERSHIP: everything between the markers is bkit-managed and overwritten on every
28
+ // `bkit install` / `bkit upgrade`.
29
+
30
+ "use strict";
31
+
32
+ // bkit:start
33
+
34
+ // {{BKIT_MANAGED_MARKER}}
35
+
36
+ const fs = require("node:fs");
37
+ const path = require("node:path");
38
+
39
+ // {{BKIT_PART guardrails-shell.js}}
40
+
41
+ const SHELL_TOOL_NAMES = new Set(["Bash", "bash"]);
42
+
43
+ /**
44
+ * Entry point — pure. Returns `{ context }` when bkit has something to say about this
45
+ * call, or `null` when it does not. Never returns a blocking decision: see the header.
46
+ */
47
+ function bkitGuardrails(payload) {
48
+ if (!payload || typeof payload !== "object") return null;
49
+ if (!SHELL_TOOL_NAMES.has(payload.tool_name)) return null;
50
+ const input = payload.tool_input || {};
51
+ const cmd = Array.isArray(input.command) ? input.command.join(" ") : input.command;
52
+ if (typeof cmd !== "string") return null;
53
+ const c = cmd.trim();
54
+ if (!c) return null;
55
+
56
+ const notes = [];
57
+ if (usesFetch(c) && !curlWgetHostAllowed(c)) {
58
+ notes.push(
59
+ "bkit guardrails: outbound fetch to a host that is not on this repo's network allowlist " +
60
+ "(.agents/context.md § allowed-domains, plus bkit's shipped tooling hosts). Not blocked — " +
61
+ "confirm the destination is intended before relying on the result, and add the host to " +
62
+ "allowed-domains if it is a standing dependency.",
63
+ );
64
+ }
65
+ const edits = shellEditTargets(c);
66
+ if (edits.length > 0) notes.push(shellEditAdvisory(edits));
67
+
68
+ return notes.length > 0 ? { context: notes.join("\n\n") } : null;
69
+ }
70
+
71
+ // bkit:end
72
+
73
+ // --- Driver (yours to extend) ----------------------------------------------
74
+ //
75
+ // Fold in your own checks here: call bkitGuardrails(payload), combine with your own
76
+ // result, and call emit() exactly once. Keep the single-emit rule — two writers on one
77
+ // stdout produce an unparseable blob and Claude Code ignores the whole thing.
78
+
79
+ function emit(payload) {
80
+ process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
81
+ }
82
+
83
+ try {
84
+ const raw = fs.readFileSync(0, "utf-8");
85
+ if (raw.trim()) {
86
+ const result = bkitGuardrails(JSON.parse(raw));
87
+ if (result) {
88
+ emit({ hookEventName: "PreToolUse", additionalContext: result.context });
89
+ }
90
+ }
91
+ } catch {
92
+ process.exitCode = 0; // fail open — never block, never error out
93
+ }
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env bash
2
+ # bkit-preflight.sh — Claude Code SessionStart hook
3
+ #
4
+ # Validates Linear issue state before any background/cloud session does bkit
5
+ # work. Refuses the session if the issue isn't approved for automation.
6
+ #
7
+ # Trigger: LINEAR_ISSUE_ID env var present (proxy for non-IDE session).
8
+ # Guards: `bkit:auto` label present; issue state not in {Cancelled, Done}.
9
+ # Setup: See `.bkit/README.md` § Linear setup.
10
+ #
11
+ # IMPORTANT — Claude Code SessionStart hooks CANNOT block the session: any
12
+ # non-zero exit is treated as non-blocking (docs.claude.com/docs/en/hooks.md).
13
+ # Failures are surfaced via `additionalContext` (the agent reads + obeys the
14
+ # HARD STOP instruction) AND `stderr` (visible to the user). Exit code is
15
+ # informational only.
16
+ #
17
+ # bkit generates the managed block at install: the Linear guard is shared with the
18
+ # Cursor hook (bkit's `hooks/preflight-linear.sh`); the trigger, the brew check
19
+ # and the output shape below are Claude's own.
20
+
21
+ # <!-- bkit:start -->
22
+
23
+ # {{BKIT_MANAGED_MARKER}}
24
+
25
+ set -euo pipefail
26
+
27
+ # Consume stdin so the writing process doesn't block.
28
+ # Claude SessionStart payload: { session_id, transcript_path, cwd, permission_mode } — unused here.
29
+ INPUT=$(cat)
30
+
31
+ # emit_context — Claude SessionStart expects { hookSpecificOutput: { hookEventName, additionalContext } }.
32
+ # (Cursor variant: emits { additional_context: ... } directly.)
33
+ emit_context() {
34
+ python3 - "$1" <<'PY'
35
+ import json, sys
36
+ print(json.dumps({
37
+ "hookSpecificOutput": {
38
+ "hookEventName": "SessionStart",
39
+ "additionalContext": sys.argv[1],
40
+ },
41
+ }))
42
+ PY
43
+ }
44
+
45
+ # IDE session detection — skip silently when this isn't a background/cloud run.
46
+ # Claude has no native is-background flag, so we use empty LINEAR_ISSUE_ID as the proxy.
47
+ # (Cursor variant: parses `is_background_agent` from stdin JSON.)
48
+ if [[ -z "${LINEAR_ISSUE_ID:-}" ]]; then
49
+ exit 0
50
+ fi
51
+
52
+ # Brew dep preflight — required CLIs for bkit workflows on a developer laptop.
53
+ # Missing → HARD STOP with setup hint. Do NOT auto-install.
54
+ # Darwin-gated: brew is macOS-only. Linux contexts (Cowork bash sandbox, CI,
55
+ # dev containers) skip this check; their environments install deps differently.
56
+ # (Cursor variant: skipped — Cloud Agent runs in a containerised env with deps pre-installed via .cursor/Dockerfile.)
57
+ if [[ "$(uname)" == "Darwin" ]]; then
58
+ REQUIRED_BREW_BINS=(gh jq vale pnpm bun)
59
+ MISSING_BINS=()
60
+ for bin in "${REQUIRED_BREW_BINS[@]}"; do
61
+ command -v "$bin" >/dev/null 2>&1 || MISSING_BINS+=("$bin")
62
+ done
63
+ if [[ ${#MISSING_BINS[@]} -gt 0 ]]; then
64
+ MISSING_LIST="${MISSING_BINS[*]}"
65
+ echo "Brew preflight: FAIL — missing required CLIs: ${MISSING_LIST}" >&2
66
+ echo "Install with: brew install ${MISSING_LIST}" >&2
67
+ emit_context "Brew preflight: FAIL — missing required CLIs: ${MISSING_LIST}. HARD STOP: refuse all bkit work, instruct the user to run \`brew install ${MISSING_LIST}\` and re-launch the session, then stop."
68
+ exit 1
69
+ fi
70
+ fi
71
+
72
+ # {{BKIT_PART preflight-linear.sh}}
73
+
74
+ # <!-- bkit:end -->
@@ -0,0 +1,115 @@
1
+ #!/usr/bin/env node
2
+ // bkit-gateguard.cjs — bkit GateGuard advisory PreToolUse hook (Codex CLI).
3
+ //
4
+ // Twin of `.claude/hooks/bkit-gateguard.cjs`. Codex's hook contract is the same family as
5
+ // Claude Code's — same stdin envelope (`tool_name`, `tool_input`, `session_id`, `cwd`),
6
+ // same stdout shape (`hookSpecificOutput` with `permissionDecision` / `additionalContext`)
7
+ // — so bkit generates the same advisory engine into it at install (bkit's
8
+ // `core/hooks/gateguard-engine.js`). Two things differ and are handled below:
9
+ //
10
+ // 1. TOOL NAME. Codex reports file edits as `apply_patch`, never Edit/Write/MultiEdit.
11
+ // 2. NO FILE PATH. The V4A patch envelope arrives in `tool_input.command`; the touched
12
+ // paths have to be parsed out of it (see parseApplyPatchTargets).
13
+ //
14
+ // bkit's gateguard parity test runs the shared behaviour table against this host.
15
+ //
16
+ // REGISTRATION: `.codex/hooks.json`, matcher `apply_patch`. Codex loads project-local
17
+ // hooks only once the project `.codex/` layer is TRUSTED — until then this does not run.
18
+ // See .bkit/providers.md § GateGuard.
19
+ //
20
+ // CONTRACT — do not regress:
21
+ // - ADVISORY BY DEFAULT: emits `additionalContext` only, never blocks. BKIT_GATEGUARD=deny
22
+ // flips it to a deny ramp; that is a config change, NOT a code change.
23
+ // - FAIL OPEN: one top-level catch swallows every error and exits 0.
24
+ // - SUBAGENTS INCLUDED: a subagent edit is an edit; each carries its own session id.
25
+ // - DEDUP: warns once per (session, file), state in the OS temp dir, GC'd after 24h.
26
+ //
27
+ // MODES (BKIT_GATEGUARD): unset → advisory [DEFAULT] | "off" → no-op | "deny" → block first
28
+ // touch per file, then allow the retry. BKIT_ALLOW_CONFIG_EDIT=1 suppresses the gate-config
29
+ // advisory.
30
+ //
31
+ // OWNERSHIP: everything between the markers is bkit-managed and overwritten on every
32
+ // `bkit install` / `bkit upgrade`. Add your own logic in the driver below the block.
33
+
34
+ "use strict";
35
+
36
+ // bkit:start
37
+
38
+ // {{BKIT_MANAGED_MARKER}}
39
+
40
+ const fs = require("node:fs");
41
+ const os = require("node:os");
42
+ const path = require("node:path");
43
+
44
+ // Codex reports every file edit as `apply_patch`, whatever matcher registered the hook
45
+ // (`apply_patch` / `Edit` / `Write` are all accepted as matchers, but the payload always
46
+ // says apply_patch). `Edit` / `Write` match a consumer-registered matcher.
47
+ const EDIT_TOOLS = new Set(["apply_patch", "Edit", "Write"]);
48
+
49
+ // Codex does NOT send a file path: `apply_patch` puts a V4A patch envelope in
50
+ // `tool_input.command`. Pull the touched paths out of it. Grammar (codex-rs/apply-patch):
51
+ // *** Add File: <path> | *** Update File: <path> | *** Delete File: <path>
52
+ // Paths are always repo-relative, so they are resolved against the payload cwd.
53
+ // Returns [{ file, isNew }] in patch order; [] when nothing parses.
54
+ function parseApplyPatchTargets(command, cwd) {
55
+ if (typeof command !== "string") return [];
56
+ const out = [];
57
+ for (const line of command.split("\n")) {
58
+ const m = /^\*\*\* (Add|Update|Delete) File: (.+?)\s*$/.exec(line);
59
+ if (!m) continue;
60
+ const rel = m[2];
61
+ out.push({ file: cwd ? path.resolve(cwd, rel) : rel, isNew: m[1] === "Add" });
62
+ }
63
+ return out;
64
+ }
65
+
66
+ // {{BKIT_PART gateguard-engine.js}}
67
+
68
+ // Pure: takes the already-parsed hook payload, returns the advisory to emit or
69
+ // null. Never touches process.stdin / process.stdout — the driver below owns both.
70
+ // Subagents are NOT exempt: dedup is per (session, file) and a subagent carries its
71
+ // own session id, so it gets the checklist once for a file the orchestrator already
72
+ // touched.
73
+ function bkitGateguard(payload) {
74
+ if (process.env.BKIT_GATEGUARD === "off") return null;
75
+ if (!EDIT_TOOLS.has(payload.tool_name)) return null;
76
+
77
+ const input = payload.tool_input || {};
78
+ const cwd = typeof payload.cwd === "string" ? payload.cwd : "";
79
+ const sessionId = typeof payload.session_id === "string" ? payload.session_id : "no-session";
80
+ // One patch can touch several files. Advises on the first not-yet-warned target, so a
81
+ // new file after an already-warned one still gets its advisory.
82
+ const target = parseApplyPatchTargets(input.command, cwd).find(
83
+ (t) => !alreadyWarned(sessionId, t.file),
84
+ );
85
+ if (!target) return null;
86
+ // `*** Add File:` IS the new-file signal; no existence probe.
87
+ return firstTouchAdvice(target.file, sessionId, target.isNew);
88
+ }
89
+
90
+ // bkit:end
91
+
92
+ function emit(payload) {
93
+ process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
94
+ }
95
+
96
+ try {
97
+ const raw = fs.readFileSync(0, "utf-8");
98
+ if (raw.trim()) {
99
+ const payload = JSON.parse(raw);
100
+ const result = bkitGateguard(payload);
101
+ if (result) {
102
+ emit(
103
+ result.mode === "deny"
104
+ ? {
105
+ hookEventName: "PreToolUse",
106
+ permissionDecision: "deny",
107
+ permissionDecisionReason: result.context,
108
+ }
109
+ : { hookEventName: "PreToolUse", additionalContext: result.context },
110
+ );
111
+ }
112
+ }
113
+ } catch {
114
+ process.exitCode = 0; // fail open — never block, never error out
115
+ }
@@ -0,0 +1,135 @@
1
+ #!/usr/bin/env node
2
+ // bkit-guardrails.cjs — bkit destructive-op shell gates (Codex CLI).
3
+ //
4
+ // Twin of `.cursor/hooks/bkit-guardrails.cjs`: bkit generates the same shell detection and
5
+ // deny / ask tiers into both at install (bkit's `core/hooks/`). Wired from
6
+ // `.codex/hooks.json`, matcher `Bash` — Codex's canonical tool name for shell execution.
7
+ //
8
+ // TWO THINGS DIFFER FROM THE CURSOR TWIN:
9
+ //
10
+ // 1. NO `ask`. Codex parses `permissionDecision: "ask"` but does not implement it —
11
+ // an attempt is recorded as an error and the tool call proceeds anyway. The ask
12
+ // tier is emitted as `additionalContext`: an advisory the model reads, the command
13
+ // still runs. The deny tier is a real block. Asserted in bkit's hook parity
14
+ // tests; see providers.md.
15
+ // 2. ENVELOPE. Codex is the Claude-family hook contract (stdin `tool_name` /
16
+ // `tool_input`, stdout `hookSpecificOutput`), not Cursor's `beforeShellExecution`
17
+ // + `{ permission }` shape.
18
+ //
19
+ // REGISTRATION: `.codex/hooks.json`, matcher `Bash`. Codex loads project-local hooks
20
+ // only once the project `.codex/` layer is TRUSTED — until then this does not run.
21
+ // See .bkit/providers.md § GateGuard.
22
+ //
23
+ // CONTRACT — do not regress:
24
+ // - FAIL OPEN: one top-level catch swallows every error and exits 0.
25
+ // - DENY IS REAL: the deny tier returns permissionDecision "deny" and blocks.
26
+ // - PURE ENGINE: everything between the markers is a decision engine only — no stdin
27
+ // read, no stdout write. Add your own gates in the driver below the block.
28
+ //
29
+ // OWNERSHIP: everything between the markers is bkit-managed and overwritten on every
30
+ // `bkit install` / `bkit upgrade`.
31
+
32
+ "use strict";
33
+
34
+ // bkit:start
35
+
36
+ // {{BKIT_MANAGED_MARKER}}
37
+
38
+ const fs = require("node:fs");
39
+ const path = require("node:path");
40
+
41
+ // {{BKIT_PART guardrails-shell.js}}
42
+
43
+ // {{BKIT_PART guardrails-tiers.js}}
44
+
45
+ /** Verdicts mirror the Cursor hook's tiers so the shared gate table reads identically. */
46
+ function allow() {
47
+ return { verdict: "allow" };
48
+ }
49
+
50
+ function ask(reason) {
51
+ return { verdict: "ask", reason };
52
+ }
53
+
54
+ function deny(reason) {
55
+ return { verdict: "deny", reason };
56
+ }
57
+
58
+ /** @param {string} cmd */
59
+ function decideShell(cmd) {
60
+ const c = String(cmd || "").trim();
61
+ const v = classifyShell(c);
62
+ if (!v) return allow();
63
+ switch (v.tier) {
64
+ case "deny":
65
+ return deny(`Blocked by bkit Codex guardrails: ${v.what}. ${v.fix}`);
66
+ case "ask":
67
+ // Advisory on this host (Codex cannot prompt).
68
+ return ask(
69
+ `bkit Codex guardrails: this is a destructive or privileged command and Codex cannot prompt for confirmation. It is on the PROHIBITED list in every bkit workflow. Do not run it unless the user asked for this exact command. Note that git clean and git checkout -- . destroy untracked files and uncommitted work, which no reflog can recover. Command: ${c}`,
70
+ );
71
+ case "fetch":
72
+ return ask(
73
+ `bkit Codex guardrails: outbound fetch to a host that is not on the network allowlist. Confirm the destination is intended before relying on the result. Command: ${c}`,
74
+ );
75
+ default:
76
+ // Shell-as-edit-channel: advisory on every host, never a block.
77
+ return ask(shellEditAdvisory(v.edits));
78
+ }
79
+ }
80
+
81
+ /**
82
+ * Entry point — pure. Takes the parsed hook payload, returns
83
+ * `{ verdict: "allow"|"ask"|"deny", reason? }`, or `null` when bkit has no opinion
84
+ * (the caller decides what a no-opinion result means).
85
+ *
86
+ * Codex reports shell execution as `Bash`; the aliases match a consumer-registered
87
+ * matcher.
88
+ */
89
+ const SHELL_TOOL_NAMES = new Set(["Bash", "bash", "shell", "local_shell", "exec"]);
90
+
91
+ function bkitGuardrails(payload) {
92
+ if (!payload || typeof payload !== "object") return null;
93
+ const tool = payload.tool_name;
94
+ if (!SHELL_TOOL_NAMES.has(tool)) return null;
95
+ const input = payload.tool_input || {};
96
+ // Codex passes the command as a string, or as an argv array for some shells.
97
+ const cmd = Array.isArray(input.command) ? input.command.join(" ") : input.command;
98
+ if (typeof cmd !== "string") return null;
99
+ const decision = decideShell(cmd);
100
+ return decision.verdict === "allow" ? null : decision;
101
+ }
102
+
103
+ // bkit:end
104
+
105
+ // --- Driver (yours to extend) ----------------------------------------------
106
+ //
107
+ // Fold in your own checks here: call bkitGuardrails(payload), combine with your own
108
+ // verdict, and call emit() exactly once. Keep the single-emit rule — two writers on
109
+ // one stdout produce an unparseable blob and Codex ignores the whole thing.
110
+
111
+ function emit(payload) {
112
+ process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
113
+ }
114
+
115
+ try {
116
+ const raw = fs.readFileSync(0, "utf-8");
117
+ if (raw.trim()) {
118
+ const result = bkitGuardrails(JSON.parse(raw));
119
+ if (result) {
120
+ emit(
121
+ result.verdict === "deny"
122
+ ? {
123
+ hookEventName: "PreToolUse",
124
+ permissionDecision: "deny",
125
+ permissionDecisionReason: result.reason,
126
+ }
127
+ : // `ask` is parsed-but-unimplemented on Codex; the ask tier is emitted as
128
+ // advisory context.
129
+ { hookEventName: "PreToolUse", additionalContext: result.reason },
130
+ );
131
+ }
132
+ }
133
+ } catch {
134
+ process.exitCode = 0; // fail open — never block, never error out
135
+ }
@@ -0,0 +1,111 @@
1
+ #!/usr/bin/env node
2
+ // bkit-gateguard.cjs — bkit GateGuard advisory PreToolUse hook for Cursor.
3
+ //
4
+ // On the FIRST touch of a given file in a session it injects an investigation
5
+ // checklist into the model's context so the investigation happens BEFORE the edit.
6
+ // A second class of paths — quality-gate configs — gets a stronger "fix the code,
7
+ // don't weaken the gate" advisory. A write to a not-yet-existing path gets the
8
+ // reuse-over-duplicate nudge instead of the read-this-file checklist.
9
+ //
10
+ // CONTRACT — do not regress:
11
+ // - ADVISORY BY DEFAULT: returns `permission: "allow"` with `additional_context`.
12
+ // Cursor delivers that to the model as a system_reminder on the tool result
13
+ // WITHOUT blocking the edit. Verified live on Cursor 3.17.8.
14
+ // - FAIL OPEN: top-level try/catch emits a bare allow on any error.
15
+ // - SUBAGENTS INCLUDED: a subagent edit is an edit. Cursor's payload carries no
16
+ // subagent marker.
17
+ // - DEDUP: warns once per (session, file); state lives in OS temp dir keyed by
18
+ // session_id and is GC'd after 24h. Never writes into the consumer repo.
19
+ //
20
+ // MODES (BKIT_GATEGUARD env var):
21
+ // - unset / anything else → advisory (inject context, never block) [DEFAULT]
22
+ // - "off" → disabled (no-op)
23
+ // - "deny" → deny the FIRST touch per file with the checklist as
24
+ // `agent_message`, then allow the retry. Opt-in.
25
+ //
26
+ // BKIT_ALLOW_CONFIG_EDIT=1 → suppress the gate-config advisory (sanctioned edit).
27
+ //
28
+ // Host notes (Cursor 3.17.8, spike-verified):
29
+ // - Cursor normalises its edit tools to `tool_name: "Write"` with
30
+ // `tool_input: { file_path, content }` for BOTH edits and creates.
31
+ // - `file_path` on a write is RELATIVE to the workspace root; on a read it is
32
+ // absolute. The driver resolves it against `workspace_roots[0]` before calling
33
+ // the engine; the new-file check is an fs.existsSync.
34
+ // - Deny must use `agent_message`. Cursor routes `user_message` to the human.
35
+ //
36
+ // Wired from `.cursor/hooks.json` → preToolUse (matcher "Write").
37
+ //
38
+ // OWNERSHIP: everything between the markers below is bkit-managed and is
39
+ // overwritten on every `bkit install` / `bkit upgrade`. bkit generates it from the
40
+ // same shared parts as the block in `.claude/hooks/bkit-gateguard.cjs`, so the two are
41
+ // byte-identical. It is a pure advisory engine only — no stdin read, no stdout write, no top-level
42
+ // invocation. Add your own logic in the driver that follows the managed block:
43
+ // call `bkitGateguard(payload)`, fold in your own checks, and call `emit()` once.
44
+
45
+ "use strict";
46
+
47
+ // bkit:start
48
+
49
+ // {{BKIT_MANAGED_MARKER}}
50
+
51
+ const fs = require("node:fs");
52
+ const os = require("node:os");
53
+ const path = require("node:path");
54
+
55
+ // {{BKIT_PART gateguard-engine.js}}
56
+
57
+ // {{BKIT_PART gateguard-edit-payload.js}}
58
+
59
+ // bkit:end
60
+
61
+ // --- driver (yours) ---------------------------------------------------------
62
+ // Reads stdin, adapts Cursor's payload to the engine's shape, and emits EXACTLY
63
+ // ONE JSON document. Cursor discards the whole hook's output if two emitters
64
+ // both write to stdout.
65
+
66
+ function emit(decision) {
67
+ process.stdout.write(JSON.stringify(decision));
68
+ }
69
+
70
+ /**
71
+ * Resolves a workspace-relative `file_path` (Cursor sends one on writes, an absolute
72
+ * one on reads) against the first workspace root, else the process cwd.
73
+ */
74
+ function resolveAgainstWorkspace(filePath, roots) {
75
+ if (!filePath || typeof filePath !== "string") return filePath;
76
+ if (path.isAbsolute(filePath)) return filePath;
77
+ const root = Array.isArray(roots) && typeof roots[0] === "string" ? roots[0] : process.cwd();
78
+ return path.join(root, filePath);
79
+ }
80
+
81
+ try {
82
+ const raw = fs.readFileSync(0, "utf-8");
83
+ if (raw.trim()) {
84
+ const cursorPayload = JSON.parse(raw);
85
+ const input = cursorPayload.tool_input || {};
86
+ const result = bkitGateguard({
87
+ tool_name: cursorPayload.tool_name,
88
+ tool_input: {
89
+ file_path: resolveAgainstWorkspace(
90
+ input.file_path || input.path,
91
+ cursorPayload.workspace_roots,
92
+ ),
93
+ },
94
+ session_id: cursorPayload.session_id || cursorPayload.conversation_id,
95
+ });
96
+ if (result) {
97
+ emit(
98
+ result.mode === "deny"
99
+ ? { permission: "deny", agent_message: result.context, user_message: result.context }
100
+ : { permission: "allow", additional_context: result.context },
101
+ );
102
+ } else {
103
+ emit({ permission: "allow" });
104
+ }
105
+ } else {
106
+ emit({ permission: "allow" });
107
+ }
108
+ } catch {
109
+ // Fail open — any error emits a bare allow.
110
+ emit({ permission: "allow" });
111
+ }