@cbartens/bkit 6.1.1 → 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 (313) 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 +42 -32
  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 +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  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 +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -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 +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -2,17 +2,29 @@
2
2
  // Example. Copy into scripts/ci/ and own it. bkit install does not write this file.
3
3
  // Usage: node scripts/ci/bkit-test-awake.mjs command [args...]
4
4
  // Chains: node scripts/ci/bkit-test-awake.mjs --shell 'first && second'
5
+ // Hold limit: node scripts/ci/bkit-test-awake.mjs --hold-s N [--grace-s G] [--stopped-file P] [--pass-fds 3,4] -- command [args...]
5
6
 
6
7
  import { spawn, spawnSync } from "node:child_process";
7
- import spawnCommand from "cross-spawn";
8
8
  import { once } from "node:events";
9
+ import { existsSync, statSync, writeFile } from "node:fs";
9
10
  import { constants } from "node:os";
11
+ import { join } from "node:path";
10
12
  import { setTimeout as delay } from "node:timers/promises";
11
13
  import { pathToFileURL } from "node:url";
12
14
 
15
+ /** The first executable `ps` on PATH, else /bin/ps. */
16
+ function psBinary() {
17
+ for (const dir of (process.env.PATH ?? "").split(":")) {
18
+ const candidate = join(dir || ".", "ps");
19
+ const stat = statSync(candidate, { throwIfNoEntry: false });
20
+ if (stat?.isFile() && (stat.mode & 0o111) !== 0) return candidate;
21
+ }
22
+ return "/bin/ps";
23
+ }
24
+
13
25
  function processTable() {
14
26
  const result = spawnSync(
15
- "/bin/ps",
27
+ psBinary(),
16
28
  ["-A", "-o", "pid=", "-o", "ppid=", "-o", "stat=", "-o", "lstart="],
17
29
  {
18
30
  encoding: "utf8",
@@ -35,7 +47,7 @@ function collectDescendants(processes, tracked) {
35
47
  do {
36
48
  added = false;
37
49
  for (const [pid, entry] of processes) {
38
- if (!tracked.has(pid) && tracked.has(entry.parent)) {
50
+ if (!tracked.has(pid) && tracked.has(entry.parent) && pid !== process.pid) {
39
51
  tracked.set(pid, entry);
40
52
  added = true;
41
53
  }
@@ -43,13 +55,47 @@ function collectDescendants(processes, tracked) {
43
55
  } while (added);
44
56
  }
45
57
 
58
+ /** Whether `pid` still runs; a signal it cannot receive from us counts as running. */
59
+ function alive(pid) {
60
+ try {
61
+ process.kill(pid, 0);
62
+ return true;
63
+ } catch (error) {
64
+ return error.code !== "ESRCH";
65
+ }
66
+ }
67
+
68
+ /** Signal `pid`; a process that already exited is not an error. */
69
+ function signalPid(pid, signal) {
70
+ try {
71
+ process.kill(pid, signal);
72
+ } catch (error) {
73
+ if (error.code !== "ESRCH")
74
+ console.error(`bkit-test-awake: could not signal command ${pid}: ${error.message}`);
75
+ }
76
+ }
77
+
78
+ /**
79
+ * True when this process is in its terminal's foreground group: a Ctrl-C there already reached
80
+ * the command, so passing INT on would deliver it twice.
81
+ */
82
+ function inTerminalForeground() {
83
+ const result = spawnSync(psBinary(), ["-o", "tpgid=", "-o", "pgid=", "-p", String(process.pid)], {
84
+ encoding: "utf8",
85
+ timeout: 1000,
86
+ });
87
+ const [tpgid, pgid] = (result.stdout ?? "").trim().split(/\s+/).map(Number);
88
+ return result.status === 0 && tpgid > 0 && tpgid === pgid;
89
+ }
90
+
91
+ /** Send `signal` through a shell chain and wait for its descendants; a null signal only waits. */
46
92
  async function cancelShell(child, signal) {
47
93
  let processes = processTable();
48
94
  const root = processes?.get(child.pid);
49
95
  if (!root) {
50
96
  if (!processes)
51
97
  console.error("bkit-test-awake: could not inspect shell commands; waiting for completion");
52
- child.kill(signal);
98
+ if (signal) child.kill(signal);
53
99
  return;
54
100
  }
55
101
  const tracked = new Map([[child.pid, root]]);
@@ -59,12 +105,7 @@ async function cancelShell(child, signal) {
59
105
  const identity = `${pid}:${entry.started}`;
60
106
  if (signalled.has(identity)) return;
61
107
  signalled.add(identity);
62
- try {
63
- process.kill(pid, signal);
64
- } catch (error) {
65
- if (error.code !== "ESRCH")
66
- console.error(`bkit-test-awake: could not signal command ${pid}: ${error.message}`);
67
- }
108
+ if (signal) signalPid(pid, signal);
68
109
  };
69
110
  // Live command owners retain responsibility for their descendants and locks.
70
111
  for (const [pid, entry] of tracked) {
@@ -95,8 +136,92 @@ async function cancelShell(child, signal) {
95
136
  }
96
137
  }
97
138
 
98
- /** Run a command with a macOS sleep assertion owned by this process. */
99
- export async function runAwake(command, args, platform = process.platform) {
139
+ /**
140
+ * Stop `child` and every process started under it once `holdS` seconds pass: one TERM to each,
141
+ * then KILL to those left after `graceS`. The tree is recorded every second, so a process whose
142
+ * parent exited is still stopped; each is recorded with its start time, so a reused pid is never
143
+ * signalled. Without a ps that lists start times, only the command itself can be stopped.
144
+ * `stoppedFile`, when set, is created as the stop starts. Resolves true when it stopped the
145
+ * command, false when the command finished first.
146
+ */
147
+ async function holdLimit(child, closing, { holdS, graceS, stoppedFile }, state) {
148
+ let closed = false;
149
+ closing.then(() => (closed = true));
150
+ const pause = (ms) => Promise.race([delay(ms, undefined, { ref: false }), closing]);
151
+ const first = processTable();
152
+ const tree = first !== null;
153
+ if (!tree)
154
+ console.error(
155
+ "bkit-test-awake: ps with lstart is not available (procps on Linux), so the --hold-s limit can stop only the command itself, not the processes started under it",
156
+ );
157
+ // The command's start time is null when it was already gone from the first table.
158
+ const tracked = new Map([[child.pid, first?.get(child.pid) ?? null]]);
159
+ const refresh = () => {
160
+ if (!tree) {
161
+ for (const pid of tracked.keys()) if (!alive(pid)) tracked.delete(pid);
162
+ return;
163
+ }
164
+ const processes = processTable();
165
+ if (!processes) return;
166
+ for (const [pid, entry] of tracked) {
167
+ const current = processes.get(pid);
168
+ if (!current || (entry && current.started !== entry.started)) tracked.delete(pid);
169
+ else tracked.set(pid, current);
170
+ }
171
+ collectDescendants(processes, tracked);
172
+ };
173
+ const end = Date.now() + holdS * 1000;
174
+ while (!closed && Date.now() < end) {
175
+ refresh();
176
+ await pause(Math.min(1000, Math.max(0, end - Date.now())));
177
+ }
178
+ if (closed) return false;
179
+ refresh();
180
+ if (!tracked.has(child.pid) || !alive(child.pid)) return false;
181
+ state.stopping = true;
182
+ // The stop goes ahead without the file; the caller then reads the 124 as the command's own.
183
+ if (stoppedFile)
184
+ writeFile(stoppedFile, "", (error) => {
185
+ if (error) console.error(`bkit-test-awake: could not write ${stoppedFile}: ${error.message}`);
186
+ });
187
+ // Each process gets one TERM, so a second one never cuts short its own shutdown.
188
+ const termed = new Set();
189
+ const term = () => {
190
+ for (const [pid, entry] of tracked) {
191
+ const identity = `${pid}:${entry?.started}`;
192
+ if (termed.has(identity)) continue;
193
+ termed.add(identity);
194
+ signalPid(pid, "SIGTERM");
195
+ }
196
+ };
197
+ term();
198
+ const killAt = Date.now() + graceS * 1000;
199
+ while (tracked.size > 0 && Date.now() < killAt) {
200
+ await delay(100);
201
+ refresh();
202
+ term();
203
+ }
204
+ for (let round = 0; round < 20 && tracked.size > 0; round++) {
205
+ for (const pid of tracked.keys()) signalPid(pid, "SIGKILL");
206
+ await delay(100);
207
+ refresh();
208
+ }
209
+ return true;
210
+ }
211
+
212
+ /**
213
+ * Run a command with a macOS sleep assertion owned by this process. With `hold`, the command is
214
+ * stopped once `hold.holdS` seconds pass (see `holdLimit`) and the result is 124, and the
215
+ * descriptors in `hold.fds` are handed to the command too. `foreground` says whether this process
216
+ * is in its terminal's foreground group.
217
+ */
218
+ export async function runAwake(
219
+ command,
220
+ args,
221
+ platform = process.platform,
222
+ hold = null,
223
+ foreground = inTerminalForeground,
224
+ ) {
100
225
  const shell = command === "--shell" && platform !== "win32";
101
226
  if (command === "--shell") {
102
227
  command = shell ? "/bin/sh" : process.env.ComSpec || "cmd.exe";
@@ -118,30 +243,51 @@ export async function runAwake(command, args, platform = process.platform) {
118
243
  }
119
244
  }
120
245
 
121
- const child = spawnCommand(command, args, {
122
- stdio: "inherit",
123
- });
124
- let cleanup;
125
- const forward = (signal) => {
126
- if (!child.pid) return;
127
- if (shell) {
128
- cleanup ??= cancelShell(child, signal);
129
- return;
130
- }
131
- try {
132
- child.kill(signal);
133
- } catch (error) {
134
- if (error.code !== "ESRCH") throw error;
135
- }
136
- };
137
- const handlers = ["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => {
138
- const handler = () => forward(signal);
139
- process.on(signal, handler);
140
- return [signal, handler];
141
- });
246
+ // cross-spawn handles Windows command shims and argument escaping; elsewhere it is spawn.
247
+ const spawnCommand = platform === "win32" ? (await import("cross-spawn")).default : spawn;
248
+ // Descriptors above 2 reach the command only when listed in `hold.fds`, each at its own number.
249
+ const fds = hold?.fds ?? [];
250
+ const extra = Array.from({ length: Math.max(2, ...fds) - 2 }, (_, i) =>
251
+ fds.includes(i + 3) ? i + 3 : "ignore",
252
+ );
253
+ let handlers = [];
142
254
  try {
255
+ let child;
256
+ const state = { stopping: false };
257
+ let cleanup;
258
+ const forward = (signal) => {
259
+ if (!child?.pid || state.stopping) return;
260
+ // A Ctrl-C at the terminal already reached the command, so it is not sent again; a shell
261
+ // chain is still waited for.
262
+ const resend = !(signal === "SIGINT" && platform !== "win32" && foreground());
263
+ if (shell) {
264
+ cleanup ??= cancelShell(child, resend ? signal : null);
265
+ return;
266
+ }
267
+ if (!resend) return;
268
+ try {
269
+ child.kill(signal);
270
+ } catch (error) {
271
+ if (error.code !== "ESRCH") throw error;
272
+ }
273
+ };
274
+ // The handlers go in before the command starts: a signal without one ends this process and
275
+ // leaves the command running. A handler runs only once the command has started.
276
+ handlers = ["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => {
277
+ const handler = () => forward(signal);
278
+ process.on(signal, handler);
279
+ return [signal, handler];
280
+ });
281
+ child = spawnCommand(command, args, {
282
+ stdio: ["inherit", "inherit", "inherit", ...extra],
283
+ });
284
+ const held =
285
+ hold && child.pid
286
+ ? holdLimit(child, new Promise((resolve) => child.on("close", resolve)), hold, state)
287
+ : Promise.resolve(false);
143
288
  const [code, signal] = await once(child, "close");
144
289
  await cleanup;
290
+ if (await held) return 124;
145
291
  return code ?? 128 + (constants.signals[signal] ?? 1);
146
292
  } catch (error) {
147
293
  const reason = error.code === "ENOENT" ? "not found on PATH" : "could not run";
@@ -157,12 +303,59 @@ export async function runAwake(command, args, platform = process.platform) {
157
303
  }
158
304
  }
159
305
 
306
+ /**
307
+ * `--hold-s N [--grace-s G] [--stopped-file P] [--pass-fds A,B] [--]` off the front of argv: the
308
+ * limits, the file to create when the limit stops the command, the open descriptors above 2 to
309
+ * hand the command, and the rest; null when a value is invalid.
310
+ */
311
+ function holdOptions(argv) {
312
+ const whole = (value, min) =>
313
+ /^\d+$/.test(value ?? "") && Number(value) >= min ? Number(value) : null;
314
+ const holdS = whole(argv[1], 1);
315
+ let rest = argv.slice(2);
316
+ let graceS = 10;
317
+ if (rest[0] === "--grace-s") {
318
+ graceS = whole(rest[1], 0);
319
+ rest = rest.slice(2);
320
+ }
321
+ let stoppedFile = null;
322
+ if (rest[0] === "--stopped-file") {
323
+ stoppedFile = rest[1] || null;
324
+ if (!stoppedFile) return null;
325
+ rest = rest.slice(2);
326
+ }
327
+ let fds = [];
328
+ if (rest[0] === "--pass-fds") {
329
+ fds = (rest[1] ?? "")
330
+ .split(",")
331
+ .filter(Boolean)
332
+ .map((fd) => whole(fd, 3));
333
+ rest = rest.slice(2);
334
+ }
335
+ if (rest[0] === "--") rest = rest.slice(1);
336
+ if (holdS === null || graceS === null) return null;
337
+ if (fds.some((fd) => fd === null || !existsSync(`/dev/fd/${fd}`))) return null;
338
+ return { hold: { holdS, graceS, stoppedFile, fds }, rest };
339
+ }
340
+
160
341
  if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
161
- const [command, ...args] = process.argv.slice(2);
342
+ let argv = process.argv.slice(2);
343
+ let hold = null;
344
+ if (argv[0] === "--hold-s") {
345
+ const options = holdOptions(argv);
346
+ if (!options) {
347
+ console.error(
348
+ "bkit-test-awake: --hold-s needs a whole number of seconds of at least 1, --grace-s one of at least 0, --stopped-file a path, and --pass-fds open descriptor numbers of at least 3",
349
+ );
350
+ process.exit(2);
351
+ }
352
+ ({ hold, rest: argv } = options);
353
+ }
354
+ const [command, ...args] = argv;
162
355
  if (!command || (command === "--shell" && args.length !== 1)) {
163
356
  console.error("bkit-test-awake: name a command, or --shell followed by one command string");
164
357
  process.exitCode = 2;
165
358
  } else {
166
- process.exitCode = await runAwake(command, args);
359
+ process.exitCode = await runAwake(command, args, process.platform, hold);
167
360
  }
168
361
  }
@@ -32,11 +32,15 @@ function cancellationFixture(t, command) {
32
32
  const path = require("node:path");
33
33
  const file = (name) => path.join(__dirname, name);
34
34
  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
35
- process.on(signal, () => fs.writeFileSync(file("cancelled"), signal));
36
- fs.writeFileSync(file("ready"), JSON.stringify({
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({
37
40
  pid: process.pid,
38
41
  owner: Number(process.env.LOCAL_STACK_LOCK_OWNER_awake || 0),
39
42
  }));
43
+ fs.renameSync(file("ready.tmp"), file("ready"));
40
44
  setInterval(() => {
41
45
  if (fs.existsSync(file("release"))) {
42
46
  fs.writeFileSync(file("finished"), "done");
@@ -121,6 +125,62 @@ for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
121
125
  }
122
126
  }
123
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
+
124
184
  test(
125
185
  "shell cancellation follows a worker orphaned by a nested shell",
126
186
  {
@@ -301,6 +361,214 @@ test("requires a command", () => {
301
361
  assert.match(result.stderr, /command/);
302
362
  });
303
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
+
304
572
  test("non-macOS platform selection runs commands without sleep prevention", async () => {
305
573
  const { runAwake } = await import("./bkit-test-awake.mjs");
306
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
  """