@cbartens/bkit 5.5.1 → 6.1.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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -7,16 +7,21 @@
7
7
  // folder). Each exports a list of steps; `max` also runs every `min` step. No file → nothing
8
8
  // runs, and worktree setup checks nothing.
9
9
  //
10
- // `--auto` is the hooks' entry: a mode runs at most once a day per machine, and `max` at
11
- // most once an hour while free disk is under `bkit.disk.minFreeGb`; the sweep then runs
12
- // detached and logs to the bkit cache folder, so the hook does not wait. `bkit worktrees
13
- // setup` calls `ensureDiskSpace` before it mints. A lock in the cache folder keeps one sweep
14
- // at a time across every repo. CI and cloud sessions run nothing.
10
+ // `--auto` is the hooks' entry: a mode runs at most once a day, and `max` at most once an
11
+ // hour while free disk is under `bkit.workflows.minFreeGb`. The machine file's steps keep one
12
+ // limit for the whole machine; each checkout's repo steps keep their own, so a sweep another
13
+ // repo started never uses up this checkout's day. The sweep then runs detached, only for the
14
+ // files that are due, and logs to the bkit cache folder, so the hook does not wait. `bkit
15
+ // worktrees setup` calls `ensureDiskSpace` before it mints. A lock in the cache folder keeps
16
+ // one sweep at a time across every repo; the detached sweep and the worktree check wait for
17
+ // their turn, so a day already counted is never lost to a running sweep. A hand run stops
18
+ // unless it passes `--wait`. CI and cloud sessions run nothing.
15
19
  //
16
20
  // A step calls `note()` for what it found but would not delete on its own (a worktree with
17
21
  // uncommitted files, say). Each sweep replaces its checkout's notes in the cache folder;
18
22
  // `bkit tips` lists them first, so the workflow that prints its tips surfaces them.
19
23
  import { spawn, spawnSync } from "node:child_process";
24
+ import { createHash } from "node:crypto";
20
25
  import * as fs from "node:fs";
21
26
  import * as os from "node:os";
22
27
  import * as path from "node:path";
@@ -24,37 +29,52 @@ import { pathToFileURL } from "node:url";
24
29
  import { isCloudOrCi } from "../../checks/before/env.js";
25
30
  import { readJsonFile } from "../../shared/json.js";
26
31
  import { readBkitConfig } from "../../shared/settings.js";
32
+ import { TIMEOUTS } from "../../shared/timeouts.js";
27
33
  import { CommandError, EXIT, git } from "../lib.js";
28
34
  import { tryCreate } from "./locks.js";
29
35
  const MODES = ["min", "max"];
30
36
  export const REPO_STEPS = "scripts/cleanup/bkit-disk-prune.mjs";
31
37
  const TEMPLATES = ".bkit/templates/scripts/cleanup/";
32
- const SETTING = "bkit.disk.minFreeGb";
38
+ const SETTING = "bkit.workflows.minFreeGb";
33
39
  const HOUR_MS = 60 * 60 * 1000;
34
40
  const DAY_MS = 24 * HOUR_MS;
35
41
  /** A lock this old, or whose process is gone, belongs to a sweep that died. */
36
42
  const LOCK_STALE_MS = HOUR_MS;
43
+ /** How often a running sweep renews its lock, so a long sweep is never taken for a dead one. */
44
+ const LOCK_RENEW_MS = 10 * 60 * 1000;
45
+ /** How often a waiting sweep tries the lock again. */
46
+ const LOCK_POLL_MS = 5_000;
37
47
  const GB = 1e9;
38
48
  const configDir = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "bkit");
39
49
  const cacheDir = () => path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "bkit");
40
50
  export const machineStepsPath = () => path.join(configDir(), "disk-prune.mjs");
41
51
  export const sweepLogPath = () => path.join(cacheDir(), "disk-prune.log");
42
52
  const lockPath = () => path.join(cacheDir(), "disk-prune.lock");
43
- const stampPath = (name) => path.join(cacheDir(), `disk-prune-${name}.stamp`);
53
+ /** One stamp per limit: the machine file's under `machine`, a checkout's repo file's under its top. */
54
+ const stampPath = (key, name) => path.join(cacheDir(), key === MACHINE
55
+ ? `disk-prune-${name}.stamp`
56
+ : `disk-prune-${name}-${createHash("sha256").update(key).digest("hex").slice(0, 12)}.stamp`);
57
+ /** A checkout's stamps this old belong to a checkout no hook has run in since (a removed worktree). */
58
+ const STAMP_STALE_MS = 7 * DAY_MS;
59
+ const REPO_STAMP = /^disk-prune-[a-z]+-[0-9a-f]{12}\.stamp$/;
44
60
  const notesPath = () => path.join(cacheDir(), "disk-prune-notes.json");
45
61
  /** Notes older than this are dropped: no sweep has run there since. */
46
62
  const NOTES_STALE_MS = 7 * DAY_MS;
63
+ const MACHINE = "machine";
47
64
  const gb = (bytes) => (bytes === null ? "?" : `${(bytes / GB).toFixed(1)} GB`);
48
65
  const errorText = (err) => (err instanceof Error ? err.message : String(err));
66
+ const SCOPES = ["repo", "machine"];
49
67
  const checkoutTop = (cwd) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
50
- /** The step files that exist for `cwd`, repo first. */
51
- function stepFilePaths(cwd) {
68
+ /** The step files that exist for `cwd`, repo first; only `scopes`' files when given. */
69
+ function stepFilePaths(cwd, scopes) {
52
70
  const top = checkoutTop(cwd);
53
71
  return [
54
72
  { scope: "repo", file: path.join(top, REPO_STEPS), cwd: top },
55
73
  { scope: "machine", file: machineStepsPath(), cwd: os.homedir() },
56
- ].filter((f) => fs.existsSync(f.file));
74
+ ].filter((f) => (scopes === undefined || scopes.includes(f.scope)) && fs.existsSync(f.file));
57
75
  }
76
+ /** Whose limits a step file counts against: the machine's, or its checkout's. */
77
+ const stampKey = (f) => (f.scope === "machine" ? MACHINE : f.cwd);
58
78
  const isAction = (v) => typeof v === "string" || typeof v === "function";
59
79
  function stepProblem(step) {
60
80
  if (step === null || typeof step !== "object")
@@ -121,14 +141,23 @@ function sizeOf(patterns, cwd) {
121
141
  .split("\n")
122
142
  .reduce((sum, line) => sum + Number(line.split(/\s/)[0] ?? 0) * 1024, 0);
123
143
  }
124
- function due(name, everyMs, now) {
125
- const st = fs.statSync(stampPath(name), { throwIfNoEntry: false });
144
+ function due(key, name, everyMs, now) {
145
+ const st = fs.statSync(stampPath(key, name), { throwIfNoEntry: false });
126
146
  return st === undefined || now - st.mtimeMs >= everyMs;
127
147
  }
128
- function touch(...names) {
148
+ /** Stamp `names` for `key`, and drop checkout stamps no hook has renewed in 7 days. */
149
+ function touch(key, ...names) {
129
150
  fs.mkdirSync(cacheDir(), { recursive: true });
130
151
  for (const name of names)
131
- fs.writeFileSync(stampPath(name), `${new Date().toISOString()}\n`);
152
+ fs.writeFileSync(stampPath(key, name), `${new Date().toISOString()}\n`);
153
+ for (const entry of fs.readdirSync(cacheDir())) {
154
+ if (!REPO_STAMP.test(entry))
155
+ continue;
156
+ const file = path.join(cacheDir(), entry);
157
+ const st = fs.statSync(file, { throwIfNoEntry: false });
158
+ if (st !== undefined && Date.now() - st.mtimeMs >= STAMP_STALE_MS)
159
+ fs.rmSync(file, { force: true });
160
+ }
132
161
  }
133
162
  function pidAlive(pid) {
134
163
  try {
@@ -139,40 +168,117 @@ function pidAlive(pid) {
139
168
  return err.code === "EPERM";
140
169
  }
141
170
  }
142
- /** Take the sweep lock; a dead or hour-old holder's lock is replaced. False when held. */
171
+ /**
172
+ * Take the sweep lock; a lock whose holder is gone, or that no holder renewed for an hour, is
173
+ * replaced. False when held. The stale lock is renamed aside before it is removed, so a lock
174
+ * another sweep took after this one's check is put back, never deleted.
175
+ */
143
176
  function takeLock() {
144
177
  const file = lockPath();
145
178
  const line = `${new Date().toISOString()} ${process.pid}`;
146
179
  if (tryCreate(file, line))
147
180
  return true;
148
181
  const st = fs.statSync(file, { throwIfNoEntry: false });
149
- const holder = st === undefined ? "" : fs.readFileSync(file, "utf-8");
182
+ if (st === undefined)
183
+ return tryCreate(file, line);
184
+ const holder = fs.readFileSync(file, "utf-8");
150
185
  const pid = Number(holder.split(/\s+/)[1]);
151
- const live = st !== undefined && Date.now() - st.mtimeMs < LOCK_STALE_MS;
186
+ const live = Date.now() - st.mtimeMs < LOCK_STALE_MS;
152
187
  if (live && Number.isInteger(pid) && pid > 0 && pidAlive(pid))
153
188
  return false;
154
- fs.rmSync(file, { force: true });
189
+ const aside = `${file}.${process.pid}.${Date.now()}.stale`;
190
+ try {
191
+ fs.renameSync(file, aside);
192
+ }
193
+ catch (err) {
194
+ if (err.code !== "ENOENT")
195
+ throw err;
196
+ return tryCreate(file, line);
197
+ }
198
+ const taken = fs.readFileSync(aside, "utf-8");
199
+ if (taken !== holder) {
200
+ restoreLock(aside, file);
201
+ return false;
202
+ }
203
+ fs.rmSync(aside, { force: true });
155
204
  return tryCreate(file, line);
156
205
  }
206
+ /** Put a lock renamed aside back at `file`, unless a third sweep has taken `file` since. */
207
+ function restoreLock(aside, file) {
208
+ try {
209
+ fs.linkSync(aside, file);
210
+ }
211
+ catch (err) {
212
+ if (err.code !== "EEXIST")
213
+ throw err;
214
+ }
215
+ fs.rmSync(aside, { force: true });
216
+ }
217
+ /**
218
+ * Take the sweep lock, waiting while another sweep holds it. False only when it is still held
219
+ * after `maxWaitMs` (default `LOCK_STALE_MS`): a sweep that long renews its lock, so `takeLock`
220
+ * never replaces it.
221
+ */
222
+ async function waitForLock(pollMs, log, maxWaitMs = LOCK_STALE_MS + pollMs) {
223
+ if (takeLock())
224
+ return true;
225
+ log(`another sweep is running (${lockPath()}) — waiting for it to end`);
226
+ const deadline = Date.now() + maxWaitMs;
227
+ while (Date.now() < deadline) {
228
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
229
+ if (takeLock())
230
+ return true;
231
+ }
232
+ return false;
233
+ }
234
+ const holdsLock = (file) => fs.existsSync(file) && fs.readFileSync(file, "utf-8").split(/\s+/)[1] === String(process.pid);
235
+ /** Mark this sweep's lock as live; another process's lock is left alone. */
236
+ function renewLock() {
237
+ const file = lockPath();
238
+ const now = new Date();
239
+ if (holdsLock(file))
240
+ fs.utimesSync(file, now, now);
241
+ }
157
242
  function releaseLock() {
158
243
  const file = lockPath();
159
- const pid = fs.existsSync(file) ? fs.readFileSync(file, "utf-8").split(/\s+/)[1] : undefined;
160
- if (pid === String(process.pid))
244
+ if (holdsLock(file))
161
245
  fs.rmSync(file, { force: true });
162
246
  }
247
+ /**
248
+ * Run a step's shell command and log its last 20 output lines. Spawned, not run in step: the
249
+ * lock renewal timer has to fire while a long command runs.
250
+ */
163
251
  function shell(command, cwd, log) {
164
- const r = spawnSync("sh", ["-c", command], { cwd, encoding: "utf-8", maxBuffer: 1 << 26 });
165
- const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
166
- if (out !== "")
167
- for (const line of out.split("\n").slice(-20))
168
- log(` ${line}`);
169
- return r.error ? 127 : (r.status ?? 1);
252
+ return new Promise((resolve) => {
253
+ const child = spawn("sh", ["-c", command], { cwd, stdio: ["ignore", "pipe", "pipe"] });
254
+ let out = "";
255
+ const keep = (chunk) => {
256
+ out = `${out}${chunk.toString()}`.slice(-(1 << 16));
257
+ };
258
+ child.stdout.on("data", keep);
259
+ child.stderr.on("data", keep);
260
+ let settled = false;
261
+ const finish = (status) => {
262
+ if (settled)
263
+ return;
264
+ settled = true;
265
+ const text = out.trim();
266
+ if (text !== "")
267
+ for (const line of text.split("\n").slice(-20))
268
+ log(` ${line}`);
269
+ resolve(status);
270
+ };
271
+ child.on("error", () => finish(127));
272
+ child.on("close", (status) => finish(status ?? 1));
273
+ });
170
274
  }
171
275
  async function skipReason(step, ctx) {
172
276
  if (step.skip === undefined)
173
277
  return null;
174
278
  if (typeof step.skip === "string") {
175
- return shell(step.skip, ctx.cwd, ctx.log) === 0 ? `skip check passed: ${step.skip}` : null;
279
+ return (await shell(step.skip, ctx.cwd, ctx.log)) === 0
280
+ ? `skip check passed: ${step.skip}`
281
+ : null;
176
282
  }
177
283
  const answer = await step.skip(ctx);
178
284
  if (!answer)
@@ -185,7 +291,7 @@ async function runStep(step, ctx) {
185
291
  if (reason !== null)
186
292
  return { outcome: "skipped", detail: reason };
187
293
  if (typeof step.run === "string") {
188
- const status = shell(step.run, ctx.cwd, ctx.log);
294
+ const status = await shell(step.run, ctx.cwd, ctx.log);
189
295
  if (status !== 0)
190
296
  return { outcome: "failed", detail: `exit ${status}` };
191
297
  }
@@ -199,8 +305,9 @@ async function runStep(step, ctx) {
199
305
  }
200
306
  }
201
307
  /**
202
- * Run the `mode` steps from every step file for `cwd`, one at a time, repo file first.
203
- * `dryRun` runs nothing and sizes each step's paths instead.
308
+ * Run the `mode` steps from every step file for `cwd` (only `scopes`' files when given), one
309
+ * at a time, repo file first. `dryRun` runs nothing and sizes each step's paths instead.
310
+ * While another sweep runs, `wait` waits for it to end; without it the sweep stops.
204
311
  */
205
312
  export async function sweep(opts) {
206
313
  const result = {
@@ -213,7 +320,7 @@ export async function sweep(opts) {
213
320
  };
214
321
  if (isCloudOrCi())
215
322
  return { ...result, reason: "ci" };
216
- const files = await Promise.all(stepFilePaths(opts.cwd).map(loadStepFile));
323
+ const files = await Promise.all(stepFilePaths(opts.cwd, opts.scopes).map(loadStepFile));
217
324
  result.files = files.map((f) => ({
218
325
  scope: f.scope,
219
326
  file: f.file,
@@ -243,10 +350,15 @@ export async function sweep(opts) {
243
350
  }
244
351
  return result;
245
352
  }
246
- if (!takeLock()) {
353
+ const locked = opts.wait
354
+ ? !(await waitForLock(opts.pollMs ?? LOCK_POLL_MS, opts.log, opts.maxWaitMs))
355
+ : !takeLock();
356
+ if (locked) {
247
357
  opts.log(`another sweep is running (${lockPath()})`);
248
358
  return { ...result, reason: "locked" };
249
359
  }
360
+ const renewal = setInterval(renewLock, opts.renewMs ?? LOCK_RENEW_MS);
361
+ renewal.unref();
250
362
  try {
251
363
  result.freeBefore = freeBytes(opts.cwd);
252
364
  opts.log(`${new Date().toISOString()} ${opts.mode} sweep, ${gb(result.freeBefore)} free`);
@@ -264,6 +376,7 @@ export async function sweep(opts) {
264
376
  saveNotes(checkoutTop(opts.cwd), result.notes);
265
377
  }
266
378
  finally {
379
+ clearInterval(renewal);
267
380
  releaseLock();
268
381
  }
269
382
  return result;
@@ -324,59 +437,78 @@ export function formatNotes(notes) {
324
437
  // ---------------------------------------------------------------------------
325
438
  // Scheduling (hooks) and the worktree check
326
439
  // ---------------------------------------------------------------------------
327
- /** Start `bkit disk prune --mode=<mode>` detached, its output appended to the sweep log. */
328
- function spawnDetached(mode, cwd) {
440
+ /**
441
+ * The `bkit` arguments of the sweep `--auto` starts: the due `scopes` only, and waiting for
442
+ * a running sweep to end, so a hook that fires mid-sweep still gets its turn.
443
+ */
444
+ export function detachedArgs(mode, scopes) {
445
+ const only = scopes.length === 1 ? [`--scope=${scopes[0]}`] : [];
446
+ return ["disk", "prune", `--mode=${mode}`, ...only, "--wait"];
447
+ }
448
+ /** Start the `--auto` sweep detached, its output appended to the sweep log. */
449
+ function spawnDetached(mode, cwd, scopes) {
329
450
  fs.mkdirSync(cacheDir(), { recursive: true });
330
451
  const fd = fs.openSync(sweepLogPath(), "a");
331
- const child = spawn(process.execPath, [...process.execArgv, process.argv[1], "disk", "prune", `--mode=${mode}`], { cwd, detached: true, stdio: ["ignore", fd, fd] });
452
+ const child = spawn(process.execPath, [...process.execArgv, process.argv[1], ...detachedArgs(mode, scopes)], { cwd, detached: true, stdio: ["ignore", fd, fd] });
332
453
  child.unref();
333
454
  fs.closeSync(fd);
334
455
  }
335
456
  /**
336
- * `--auto`: start a detached sweep when one is due. Under `minFreeGb` free → `max`, at
337
- * most hourly; else `mode`, at most daily. A `max` run also counts as that day's `min`.
457
+ * `--auto`: start a detached sweep of the step files that are due. Under `minFreeGb` free →
458
+ * `max`, at most hourly; else `mode`, at most daily. A `max` run also counts as that day's
459
+ * `min`. The machine file is due by the machine's stamps, the repo file by its checkout's.
338
460
  */
339
461
  export function schedule(opts) {
340
462
  if (isCloudOrCi())
341
463
  return { started: null, reason: "ci" };
342
- if (stepFilePaths(opts.cwd).length === 0)
464
+ const files = stepFilePaths(opts.cwd);
465
+ if (files.length === 0)
343
466
  return { started: null, reason: "no-steps" };
344
467
  const now = opts.now ?? Date.now();
345
468
  const start = opts.start ?? spawnDetached;
346
469
  const free = freeBytes(opts.cwd);
347
- if (free !== null && free < opts.minFreeGb * GB) {
348
- if (!due("low", HOUR_MS, now))
349
- return { started: null, reason: "not-due" };
350
- touch("low", "max", "min");
351
- start("max", opts.cwd);
352
- return { started: "max", reason: "low-disk" };
353
- }
354
- if (!due(opts.mode, DAY_MS, now))
470
+ const low = free !== null && free < opts.minFreeGb * GB;
471
+ const mode = low ? "max" : opts.mode;
472
+ const dueFiles = files.filter((f) => low ? due(stampKey(f), "low", HOUR_MS, now) : due(stampKey(f), mode, DAY_MS, now));
473
+ if (dueFiles.length === 0)
355
474
  return { started: null, reason: "not-due" };
356
- touch(...(opts.mode === "max" ? ["max", "min"] : ["min"]));
357
- start(opts.mode, opts.cwd);
358
- return { started: opts.mode, reason: "due" };
475
+ const names = low ? ["low", "max", "min"] : mode === "max" ? ["max", "min"] : ["min"];
476
+ for (const f of dueFiles)
477
+ touch(stampKey(f), ...names);
478
+ start(mode, opts.cwd, dueFiles.map((f) => f.scope));
479
+ return { started: mode, reason: low ? "low-disk" : "due" };
359
480
  }
360
481
  /**
361
482
  * Before worktree setup mints: under `minFreeGb` free with step files present, run the
362
- * `max` steps and check again. Null = carry on; else why the worktree must not be made.
483
+ * `max` steps (waiting for a running sweep to end first) and check again. Null = carry on;
484
+ * else why the worktree must not be made.
363
485
  */
364
486
  export async function ensureDiskSpace(opts) {
365
- if (isCloudOrCi() || stepFilePaths(opts.cwd).length === 0)
487
+ const files = isCloudOrCi() ? [] : stepFilePaths(opts.cwd);
488
+ if (files.length === 0)
366
489
  return null;
367
490
  const min = opts.minFreeGb * GB;
368
491
  const before = freeBytes(opts.cwd);
369
492
  if (before === null || before >= min)
370
493
  return null;
371
494
  opts.log(`${gb(before)} free, under ${SETTING} (${opts.minFreeGb} GB) — running your max cleanup steps`);
372
- touch("low", "max", "min");
373
- const ran = await sweep({ cwd: opts.cwd, mode: "max", dryRun: false, log: opts.log });
495
+ for (const f of files)
496
+ touch(stampKey(f), "low", "max", "min");
497
+ const ran = await sweep({
498
+ cwd: opts.cwd,
499
+ mode: "max",
500
+ dryRun: false,
501
+ wait: true,
502
+ pollMs: opts.pollMs,
503
+ maxWaitMs: opts.maxWaitMs ?? TIMEOUTS.DISK_SETUP_SWEEP_WAIT_S * 1000,
504
+ log: opts.log,
505
+ });
374
506
  const after = freeBytes(opts.cwd);
375
507
  if (after === null || after >= min)
376
508
  return null;
377
509
  opts.log("what your max steps still cover:");
378
510
  await sweep({ cwd: opts.cwd, mode: "max", dryRun: true, log: opts.log });
379
- const locked = ran.reason === "locked" ? " (another sweep was running — re-run once it ends)" : "";
511
+ const locked = ran.reason === "locked" ? " (another sweep still holds the lock — re-run once it ends)" : "";
380
512
  return `${gb(after)} free after your max cleanup steps, still under ${SETTING} (${opts.minFreeGb} GB)${locked} — free space by hand or add steps (.bkit/templates.md § Disk prune), then re-run`;
381
513
  }
382
514
  // ---------------------------------------------------------------------------
@@ -388,6 +520,7 @@ export const diskCommand = {
388
520
  verbs: {
389
521
  prune: {
390
522
  summary: `Run the min or max steps from ${REPO_STEPS} and ~/.config/bkit/disk-prune.mjs.`,
523
+ use: "by-hand",
391
524
  flags: [
392
525
  {
393
526
  name: "mode",
@@ -400,10 +533,20 @@ export const diskCommand = {
400
533
  type: "boolean",
401
534
  help: "run nothing; list each step with the size of its paths",
402
535
  },
536
+ {
537
+ name: "scope",
538
+ type: "string",
539
+ help: "repo or machine: run only that file's steps (default: both)",
540
+ },
541
+ {
542
+ name: "wait",
543
+ type: "boolean",
544
+ help: "while another sweep runs, wait for it to end instead of stopping (the sweep --auto starts always waits)",
545
+ },
403
546
  {
404
547
  name: "auto",
405
548
  type: "boolean",
406
- help: `for hooks: run detached, at most once a day per mode; max at most hourly while free disk is under ${SETTING}`,
549
+ help: `for hooks: run detached, at most once a day per mode (machine steps once per machine, repo steps once per checkout); max at most hourly while free disk is under ${SETTING}`,
407
550
  },
408
551
  ],
409
552
  output: {
@@ -421,9 +564,17 @@ export const diskCommand = {
421
564
  if (!MODES.includes(mode))
422
565
  throw new CommandError(EXIT.USAGE, "--mode must be min or max");
423
566
  const dryRun = ctx.flags.dryRun === true;
567
+ const scope = ctx.flags.scope === undefined ? undefined : String(ctx.flags.scope);
568
+ if (scope !== undefined && !SCOPES.includes(scope))
569
+ throw new CommandError(EXIT.USAGE, "--scope must be repo or machine");
570
+ const scopes = scope === undefined ? undefined : [scope];
424
571
  if (ctx.flags.auto === true) {
425
572
  if (dryRun)
426
573
  throw new CommandError(EXIT.USAGE, "give --auto or --dry-run, not both");
574
+ if (scopes)
575
+ throw new CommandError(EXIT.USAGE, "give --auto or --scope, not both");
576
+ if (ctx.flags.wait === true)
577
+ throw new CommandError(EXIT.USAGE, "give --auto or --wait, not both");
427
578
  const plan = schedule({
428
579
  cwd: ctx.cwd,
429
580
  mode: mode,
@@ -442,7 +593,14 @@ export const diskCommand = {
442
593
  });
443
594
  return EXIT.OK;
444
595
  }
445
- const r = await sweep({ cwd: ctx.cwd, mode: mode, dryRun, log: ctx.log });
596
+ const r = await sweep({
597
+ cwd: ctx.cwd,
598
+ mode: mode,
599
+ dryRun,
600
+ scopes,
601
+ wait: ctx.flags.wait === true,
602
+ log: ctx.log,
603
+ });
446
604
  ctx.emit({ mode, started: null, ...r });
447
605
  const failed = r.files.some((f) => f.error !== null) || r.steps.some((s) => s.outcome === "failed");
448
606
  return failed ? EXIT.NO : EXIT.OK;