@cbartens/bkit 6.1.0 → 6.2.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 (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -2,11 +2,302 @@
2
2
  import assert from "node:assert/strict";
3
3
  import { spawn, spawnSync } from "node:child_process";
4
4
  import { once } from "node:events";
5
- import { existsSync, readFileSync } from "node:fs";
5
+ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
6
+ import { join, resolve } from "node:path";
6
7
  import { test } from "node:test";
7
8
  import { fileURLToPath } from "node:url";
8
9
 
9
10
  const script = fileURLToPath(new URL("./bkit-test-awake.mjs", import.meta.url));
11
+ const lockScript = fileURLToPath(new URL("./bkit-machine-lock.sh", import.meta.url));
12
+ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
13
+ const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
14
+
15
+ async function until(check, description) {
16
+ for (let attempt = 0; attempt < 150; attempt++) {
17
+ if (check()) return;
18
+ await delay(20);
19
+ }
20
+ assert.fail(`timed out waiting for ${description}`);
21
+ }
22
+
23
+ function cancellationFixture(t, command) {
24
+ const base = resolve("tmp");
25
+ mkdirSync(base, { recursive: true });
26
+ const dir = mkdtempSync(join(base, "awake-cancel-"));
27
+ const worker = join(dir, "worker.cjs");
28
+ writeFileSync(
29
+ worker,
30
+ `
31
+ const fs = require("node:fs");
32
+ const path = require("node:path");
33
+ const file = (name) => path.join(__dirname, name);
34
+ for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
35
+ process.on(signal, () => {
36
+ fs.writeFileSync(file("cancelled.tmp"), signal);
37
+ fs.renameSync(file("cancelled.tmp"), file("cancelled"));
38
+ });
39
+ fs.writeFileSync(file("ready.tmp"), JSON.stringify({
40
+ pid: process.pid,
41
+ owner: Number(process.env.LOCAL_STACK_LOCK_OWNER_awake || 0),
42
+ }));
43
+ fs.renameSync(file("ready.tmp"), file("ready"));
44
+ setInterval(() => {
45
+ if (fs.existsSync(file("release"))) {
46
+ fs.writeFileSync(file("finished"), "done");
47
+ process.exit(0);
48
+ }
49
+ }, 20);
50
+ `,
51
+ );
52
+ const env = { ...process.env, CI: "", XDG_CACHE_HOME: dir, TMPDIR: dir, FORCE_COLOR: "1" };
53
+ for (const key of Object.keys(env)) {
54
+ if (/^LOCAL_STACK_LOCK_(OWNER|PID|NAME)/.test(key)) delete env[key];
55
+ }
56
+ const child = spawn(process.execPath, [script, ...command(worker, dir)], {
57
+ detached: true,
58
+ stdio: ["ignore", "pipe", "pipe"],
59
+ env,
60
+ });
61
+ child.stdout.resume();
62
+ child.stderr.resume();
63
+ const closed = once(child, "close");
64
+ let groupKilled = false;
65
+ const killGroup = (signal) => {
66
+ if (groupKilled) return;
67
+ try {
68
+ process.kill(-child.pid, signal);
69
+ if (signal === "SIGKILL") groupKilled = true;
70
+ } catch (error) {
71
+ if (error.code !== "ESRCH") throw error;
72
+ }
73
+ };
74
+ const deadline = setTimeout(() => killGroup("SIGKILL"), 8000);
75
+ t.after(async () => {
76
+ killGroup("SIGKILL");
77
+ await closed;
78
+ clearTimeout(deadline);
79
+ rmSync(dir, { recursive: true, force: true });
80
+ });
81
+ return { child, closed, dir, env, killGroup, file: (name) => join(dir, name) };
82
+ }
83
+
84
+ function assertionPid(owner) {
85
+ if (process.platform !== "darwin") return null;
86
+ const result = spawnSync("pgrep", ["-P", String(owner), "caffeinate"], { encoding: "utf8" });
87
+ assert.equal(result.status, 0, "the wrapper must own a sleep assertion");
88
+ return Number(result.stdout.trim());
89
+ }
90
+
91
+ for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
92
+ for (const shell of [false, true]) {
93
+ test(
94
+ `${shell ? "shell" : "direct"} cancellation waits for ${signal} cleanup`,
95
+ {
96
+ skip: process.platform === "win32",
97
+ timeout: 12000,
98
+ },
99
+ async (t) => {
100
+ const fixture = cancellationFixture(t, (worker, dir) =>
101
+ shell
102
+ ? [
103
+ "--shell",
104
+ `${quote(process.execPath)} ${quote(worker)}; echo later > ${quote(join(dir, "later"))}`,
105
+ ]
106
+ : [process.execPath, worker],
107
+ );
108
+ await until(() => existsSync(fixture.file("ready")), "worker readiness");
109
+ const { pid } = JSON.parse(readFileSync(fixture.file("ready"), "utf8"));
110
+ const assertion = assertionPid(fixture.child.pid);
111
+ fixture.child.kill(signal);
112
+ await until(() => existsSync(fixture.file("cancelled")), "worker cancellation");
113
+ assert.equal(readFileSync(fixture.file("cancelled"), "utf8"), signal);
114
+ assert.equal(isRunning(fixture.child.pid), true, "wrapper must wait for cleanup");
115
+ if (assertion) assert.equal(isRunning(assertion), true, "assertion must survive cleanup");
116
+ writeFileSync(fixture.file("release"), "finish cleanup");
117
+ const [code] = await fixture.closed;
118
+ assert.equal(code, shell ? { SIGTERM: 143, SIGINT: 130, SIGHUP: 129 }[signal] : 0);
119
+ assert.equal(existsSync(fixture.file("finished")), true);
120
+ assert.equal(existsSync(fixture.file("later")), false);
121
+ assert.equal(isRunning(pid), false);
122
+ if (assertion) assert.equal(isRunning(assertion), false);
123
+ },
124
+ );
125
+ }
126
+ }
127
+
128
+ test(
129
+ "shell cancellation reads complete readiness JSON when publication is interrupted",
130
+ { skip: process.platform === "win32", timeout: 12000 },
131
+ (t) => {
132
+ const base = resolve("tmp");
133
+ mkdirSync(base, { recursive: true });
134
+ const dir = mkdtempSync(join(base, "awake-publish-"));
135
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
136
+ const preload = join(dir, "pause-publication.cjs");
137
+ const receipt = join(dir, "publication-observed");
138
+ writeFileSync(
139
+ preload,
140
+ `
141
+ if (process.argv[1]?.endsWith("worker.cjs")) {
142
+ const fs = require("node:fs");
143
+ const writeFileSync = fs.writeFileSync;
144
+ fs.writeFileSync = function (file, data, ...options) {
145
+ if (typeof data !== "string" || !data.startsWith('{"pid":'))
146
+ return writeFileSync.call(this, file, data, ...options);
147
+ const fd = fs.openSync(file, "w");
148
+ try {
149
+ writeFileSync(${JSON.stringify(receipt)}, "paused");
150
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 150);
151
+ writeFileSync(fd, data, ...options);
152
+ } finally {
153
+ fs.closeSync(fd);
154
+ }
155
+ };
156
+ }
157
+ `,
158
+ );
159
+ const result = spawnSync(
160
+ process.execPath,
161
+ [
162
+ "--test",
163
+ "--test-name-pattern=^shell cancellation waits for SIGTERM cleanup$",
164
+ fileURLToPath(import.meta.url),
165
+ ],
166
+ {
167
+ encoding: "utf8",
168
+ env: {
169
+ ...process.env,
170
+ NODE_TEST_CONTEXT: undefined,
171
+ NODE_OPTIONS: `${process.env.NODE_OPTIONS || ""} --require=${JSON.stringify(preload)}`,
172
+ },
173
+ },
174
+ );
175
+ assert.equal(
176
+ existsSync(receipt),
177
+ true,
178
+ `the worker must pause after opening its JSON file\n${result.stdout}${result.stderr}`,
179
+ );
180
+ assert.equal(result.status, 0, result.stdout + result.stderr);
181
+ },
182
+ );
183
+
184
+ test(
185
+ "shell cancellation follows a worker orphaned by a nested shell",
186
+ {
187
+ skip: process.platform === "win32",
188
+ timeout: 12000,
189
+ },
190
+ async (t) => {
191
+ const fixture = cancellationFixture(t, (worker, dir) => {
192
+ const nested = `${quote(process.execPath)} ${quote(worker)}; :`;
193
+ return ["--shell", `/bin/sh -c ${quote(nested)}; echo later > ${quote(join(dir, "later"))}`];
194
+ });
195
+ await until(() => existsSync(fixture.file("ready")), "nested worker readiness");
196
+ const { pid } = JSON.parse(readFileSync(fixture.file("ready"), "utf8"));
197
+ const assertion = assertionPid(fixture.child.pid);
198
+ fixture.child.kill("SIGTERM");
199
+ await until(() => existsSync(fixture.file("cancelled")), "orphaned worker cancellation");
200
+ assert.equal(isRunning(fixture.child.pid), true, "wrapper must await orphaned worker cleanup");
201
+ if (assertion) assert.equal(isRunning(assertion), true);
202
+ writeFileSync(fixture.file("release"), "finish cleanup");
203
+ const [code] = await fixture.closed;
204
+ assert.equal(code, 143);
205
+ assert.equal(existsSync(fixture.file("finished")), true);
206
+ assert.equal(existsSync(fixture.file("later")), false);
207
+ assert.equal(isRunning(pid), false);
208
+ if (assertion) assert.equal(isRunning(assertion), false);
209
+ },
210
+ );
211
+
212
+ for (const mode of ["direct", "shell", "nested shell"]) {
213
+ test(
214
+ `${mode} cancellation preserves a nested machine-lock owner`,
215
+ {
216
+ skip: process.platform === "win32",
217
+ timeout: 12000,
218
+ },
219
+ async (t) => {
220
+ const fixture = cancellationFixture(t, (worker, dir) => {
221
+ const args = [
222
+ "bash",
223
+ lockScript,
224
+ "run",
225
+ "awake cleanup",
226
+ "--lock",
227
+ "awake",
228
+ "--",
229
+ process.execPath,
230
+ worker,
231
+ ];
232
+ if (mode === "direct") return args;
233
+ const command = args.map(quote).join(" ");
234
+ const wrapped = mode === "nested shell" ? `/bin/sh -c ${quote(`${command}; :`)}` : command;
235
+ return ["--shell", `${wrapped}; echo later > ${quote(join(dir, "later"))}`];
236
+ });
237
+ await until(() => existsSync(fixture.file("ready")), "locked worker readiness");
238
+ const { pid, owner } = JSON.parse(readFileSync(fixture.file("ready"), "utf8"));
239
+ assert.ok(owner > 0);
240
+ const assertion = assertionPid(fixture.child.pid);
241
+ fixture.child.kill("SIGTERM");
242
+ await delay(150);
243
+ assert.equal(isRunning(fixture.child.pid), true);
244
+ assert.equal(isRunning(owner), true);
245
+ assert.equal(isRunning(pid), true);
246
+ assert.equal(
247
+ existsSync(fixture.file("cancelled")),
248
+ false,
249
+ "lock command completes naturally",
250
+ );
251
+ if (assertion) assert.equal(isRunning(assertion), true);
252
+ const contender = () =>
253
+ spawnSync(
254
+ "bash",
255
+ [
256
+ "-c",
257
+ 'source "$1"; try_local_stack_lock contender awake; result=$?; release_local_stack_lock awake; exit "$result"',
258
+ "bash",
259
+ lockScript,
260
+ ],
261
+ {
262
+ env: fixture.env,
263
+ encoding: "utf8",
264
+ timeout: 3000,
265
+ },
266
+ );
267
+ assert.equal(contender().status, 1, "the lock must remain held while its command runs");
268
+ writeFileSync(fixture.file("release"), "finish command");
269
+ const [code] = await fixture.closed;
270
+ assert.equal(code, 143);
271
+ assert.equal(existsSync(fixture.file("finished")), true);
272
+ assert.equal(existsSync(fixture.file("later")), false);
273
+ assert.equal(isRunning(pid), false);
274
+ assert.equal(isRunning(owner), false);
275
+ if (assertion) assert.equal(isRunning(assertion), false);
276
+ assert.equal(contender().status, 0, "the completed command must release its lock");
277
+ },
278
+ );
279
+ }
280
+
281
+ test(
282
+ "a hard process-group timeout reaches a shell command during cleanup",
283
+ {
284
+ skip: process.platform === "win32",
285
+ timeout: 12000,
286
+ },
287
+ async (t) => {
288
+ const fixture = cancellationFixture(t, (worker) => [
289
+ "--shell",
290
+ `${quote(process.execPath)} ${quote(worker)}; echo later`,
291
+ ]);
292
+ await until(() => existsSync(fixture.file("ready")), "worker readiness");
293
+ const { pid } = JSON.parse(readFileSync(fixture.file("ready"), "utf8"));
294
+ fixture.killGroup("SIGTERM");
295
+ await until(() => existsSync(fixture.file("cancelled")), "worker cancellation");
296
+ fixture.killGroup("SIGKILL");
297
+ await fixture.closed;
298
+ await until(() => !isRunning(pid), "hard timeout cleanup");
299
+ },
300
+ );
10
301
 
11
302
  function isRunning(pid) {
12
303
  try {
@@ -70,6 +361,214 @@ test("requires a command", () => {
70
361
  assert.match(result.stderr, /command/);
71
362
  });
72
363
 
364
+ test(
365
+ "--hold-s stops a command that outlives the limit, with the processes under it, and exits 124",
366
+ { skip: process.platform === "win32", timeout: 15000 },
367
+ (t) => {
368
+ const base = resolve("tmp");
369
+ mkdirSync(base, { recursive: true });
370
+ const dir = mkdtempSync(join(base, "awake-hold-"));
371
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
372
+ const root = join(dir, "root.pid");
373
+ const grandchild = join(dir, "grandchild.pid");
374
+ const started = Date.now();
375
+ const result = spawnSync(
376
+ process.execPath,
377
+ [
378
+ script,
379
+ "--hold-s",
380
+ "1",
381
+ "--grace-s",
382
+ "1",
383
+ "--",
384
+ "/bin/sh",
385
+ "-c",
386
+ `echo $$ > ${quote(root)}; sleep 300 & echo $! > ${quote(grandchild)}; wait`,
387
+ ],
388
+ { encoding: "utf8", timeout: 12000 },
389
+ );
390
+ assert.equal(result.status, 124, result.stderr);
391
+ assert.ok(Date.now() - started >= 1000, "the command must run until the limit");
392
+ assert.equal(isRunning(Number(readFileSync(root, "utf8"))), false);
393
+ assert.equal(isRunning(Number(readFileSync(grandchild, "utf8"))), false);
394
+ },
395
+ );
396
+
397
+ test("--hold-s passes on the exit status and output of a command that finishes first", () => {
398
+ const failing = spawnSync(
399
+ process.execPath,
400
+ [script, "--hold-s", "30", "--", "/bin/sh", "-c", "exit 7"],
401
+ { encoding: "utf8", timeout: 12000 },
402
+ );
403
+ assert.equal(failing.status, 7, failing.stderr);
404
+ const passing = spawnSync(process.execPath, [script, "--hold-s", "30", "--", "echo", "fine"], {
405
+ encoding: "utf8",
406
+ timeout: 12000,
407
+ });
408
+ assert.equal(passing.status, 0, passing.stderr);
409
+ assert.equal(passing.stdout, "fine\n");
410
+ assert.equal(passing.stderr, "");
411
+ });
412
+
413
+ test(
414
+ "--pass-fds hands the command the listed descriptors beyond stdio",
415
+ { skip: process.platform === "win32" },
416
+ () => {
417
+ const result = spawnSync(
418
+ process.execPath,
419
+ [script, "--hold-s", "30", "--pass-fds", "3", "--", "/bin/sh", "-c", "echo through-3 >&3"],
420
+ { stdio: ["ignore", "pipe", "pipe", "pipe"], encoding: "utf8", timeout: 12000 },
421
+ );
422
+ assert.equal(result.status, 0, result.stderr);
423
+ assert.equal(result.output[3], "through-3\n");
424
+ },
425
+ );
426
+
427
+ test(
428
+ "--stopped-file is created when the hold limit stops the command, and not when the command finishes first",
429
+ { skip: process.platform === "win32", timeout: 15000 },
430
+ (t) => {
431
+ const base = resolve("tmp");
432
+ mkdirSync(base, { recursive: true });
433
+ const dir = mkdtempSync(join(base, "awake-stopped-"));
434
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
435
+ const stopped = join(dir, "stopped");
436
+ const held = spawnSync(
437
+ process.execPath,
438
+ [script, "--hold-s", "1", "--grace-s", "1", "--stopped-file", stopped, "--", "sleep", "300"],
439
+ { encoding: "utf8", timeout: 12000 },
440
+ );
441
+ assert.equal(held.status, 124, held.stderr);
442
+ assert.equal(existsSync(stopped), true, "the stop must create the file");
443
+ rmSync(stopped);
444
+ const own = spawnSync(
445
+ process.execPath,
446
+ [script, "--hold-s", "30", "--stopped-file", stopped, "--", "/bin/sh", "-c", "exit 124"],
447
+ { encoding: "utf8", timeout: 12000 },
448
+ );
449
+ assert.equal(own.status, 124, own.stderr);
450
+ assert.equal(existsSync(stopped), false, "a command's own 124 must not create the file");
451
+ },
452
+ );
453
+
454
+ test(
455
+ "--stopped-file that cannot be written still stops the command at the hold limit",
456
+ { skip: process.platform === "win32", timeout: 15000 },
457
+ () => {
458
+ const stopped = join(resolve("tmp"), "awake-no-such-folder", "stopped");
459
+ const held = spawnSync(
460
+ process.execPath,
461
+ [script, "--hold-s", "1", "--grace-s", "1", "--stopped-file", stopped, "--", "sleep", "300"],
462
+ { encoding: "utf8", timeout: 12000 },
463
+ );
464
+ assert.equal(held.status, 124, held.stderr);
465
+ assert.match(held.stderr, /could not write .*stopped/);
466
+ assert.doesNotMatch(held.stderr, /\n\s+at /);
467
+ },
468
+ );
469
+
470
+ test(
471
+ "--pass-fds naming a descriptor that is not open fails with the usage error",
472
+ { skip: process.platform === "win32" },
473
+ () => {
474
+ const result = spawnSync(
475
+ process.execPath,
476
+ [script, "--hold-s", "30", "--pass-fds", "250", "--", "echo", "should-not-run"],
477
+ { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 12000 },
478
+ );
479
+ assert.equal(result.status, 2, result.stderr);
480
+ assert.equal(result.stdout, "");
481
+ assert.match(result.stderr, /--pass-fds/);
482
+ assert.doesNotMatch(result.stderr, /EBADF|\n\s+at /);
483
+ },
484
+ );
485
+
486
+ test(
487
+ "a Ctrl-C from the terminal is not sent again, but a --shell chain still waits for its descendants",
488
+ { skip: process.platform === "win32", timeout: 12000 },
489
+ async (t) => {
490
+ const { runAwake } = await import("./bkit-test-awake.mjs");
491
+ const base = resolve("tmp");
492
+ mkdirSync(base, { recursive: true });
493
+ const dir = mkdtempSync(join(base, "awake-foreground-"));
494
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
495
+ const file = (name) => join(dir, name);
496
+ const worker = file("worker.cjs");
497
+ writeFileSync(
498
+ worker,
499
+ `
500
+ const fs = require("node:fs");
501
+ let interrupts = 0;
502
+ process.on("SIGINT", () => {
503
+ interrupts++;
504
+ fs.writeFileSync(${JSON.stringify(file("cancelled"))}, String(interrupts));
505
+ });
506
+ fs.writeFileSync(${JSON.stringify(file("ready"))}, String(process.pid));
507
+ setInterval(() => {
508
+ if (fs.existsSync(${JSON.stringify(file("release"))})) {
509
+ fs.writeFileSync(${JSON.stringify(file("finished"))}, String(interrupts));
510
+ process.exit(0);
511
+ }
512
+ }, 20);
513
+ `,
514
+ );
515
+ // The runner exits 300 ms after its Ctrl-C and leaves its worker cleaning up.
516
+ const runner = file("runner.cjs");
517
+ writeFileSync(
518
+ runner,
519
+ `
520
+ const { spawn } = require("node:child_process");
521
+ spawn(process.execPath, [${JSON.stringify(worker)}], { stdio: "inherit" });
522
+ process.on("SIGINT", () => setTimeout(() => process.exit(130), 300));
523
+ setInterval(() => {}, 1000);
524
+ `,
525
+ );
526
+ const done = runAwake(
527
+ "--shell",
528
+ [`${quote(process.execPath)} ${quote(runner)}`],
529
+ "linux",
530
+ null,
531
+ () => true,
532
+ );
533
+ let settled = false;
534
+ done.then(() => (settled = true));
535
+ await until(() => existsSync(file("ready")), "worker readiness");
536
+ const pid = Number(readFileSync(file("ready"), "utf8"));
537
+ t.after(() => {
538
+ if (isRunning(pid)) process.kill(pid, "SIGKILL");
539
+ });
540
+ const group = spawnSync("ps", ["-o", "pid=", "-o", "ppid=", "-A"], { encoding: "utf8" })
541
+ .stdout.split("\n")
542
+ .map((row) => row.trim().split(/\s+/).map(Number));
543
+ const parentOf = (child) => group.find(([p]) => p === child)?.[1];
544
+ const runnerPid = parentOf(pid);
545
+ const shellPid = parentOf(runnerPid);
546
+ // The terminal delivers Ctrl-C to the whole foreground group, then the wrapper sees it too.
547
+ for (const target of [shellPid, runnerPid, pid]) process.kill(target, "SIGINT");
548
+ process.emit("SIGINT", "SIGINT");
549
+ await until(() => existsSync(file("cancelled")), "worker cancellation");
550
+ await until(() => !isRunning(runnerPid), "runner exit");
551
+ await delay(300);
552
+ assert.equal(settled, false, "the wrapper must wait for the worker's cleanup");
553
+ writeFileSync(file("release"), "finish cleanup");
554
+ assert.equal(await done, 130);
555
+ assert.equal(readFileSync(file("finished"), "utf8"), "1", "INT must reach the worker once");
556
+ },
557
+ );
558
+
559
+ test("--hold-s and --grace-s need whole numbers", () => {
560
+ for (const args of [
561
+ ["--hold-s", "abc", "--", "true"],
562
+ ["--hold-s", "0", "--", "true"],
563
+ ["--hold-s", "5", "--grace-s", "-1", "--", "true"],
564
+ ["--hold-s", "5", "--pass-fds", "1", "--", "true"],
565
+ ]) {
566
+ const result = spawnSync(process.execPath, [script, ...args], { encoding: "utf8" });
567
+ assert.equal(result.status, 2, args.join(" "));
568
+ assert.match(result.stderr, /--hold-s/);
569
+ }
570
+ });
571
+
73
572
  test("non-macOS platform selection runs commands without sleep prevention", async () => {
74
573
  const { runAwake } = await import("./bkit-test-awake.mjs");
75
574
  for (const platform of ["linux", "win32"]) {
@@ -11,7 +11,7 @@ OWN interpreter — it imports graphify itself.
11
11
  bkit-graphify-graphml.py <graph.json> <out.graphml>
12
12
 
13
13
  The graphify CLI has no --graphml flag (only the /graphify skill has one, which
14
- this repo does not install; see docs/setup.md § Code Graph, "Never run"), so this
14
+ this repo does not install; see .bkit/templates.md § graphify — map), so this
15
15
  calls to_graphml() directly. Community IDs are carried through so Gephi can
16
16
  partition on them.
17
17
  """