@smoothbricks/nx-plugin 0.4.26 → 0.4.28

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 (343) hide show
  1. package/README.md +994 -117
  2. package/dist/bin/smoo-nx-bound-failures.d.ts +3 -0
  3. package/dist/bin/smoo-nx-bound-failures.d.ts.map +1 -0
  4. package/dist/bin/smoo-nx-bound-failures.js +31 -0
  5. package/dist/bin/smoo-nx-cargo-hash.js +28 -3
  6. package/dist/bin/smoo-nx-exec.js +15 -73
  7. package/dist/bin/smoo-nx-failures.d.ts +3 -0
  8. package/dist/bin/smoo-nx-failures.d.ts.map +1 -0
  9. package/dist/bin/smoo-nx-failures.js +3 -0
  10. package/dist/bin/smoo-nx-nextest-extract.js +3 -2
  11. package/dist/bin/smoo-nx-test-walks.d.ts +3 -0
  12. package/dist/bin/smoo-nx-test-walks.d.ts.map +1 -0
  13. package/dist/bin/smoo-nx-test-walks.js +34 -0
  14. package/dist/bounded-test-policy.d.ts +7 -1
  15. package/dist/bounded-test-policy.d.ts.map +1 -1
  16. package/dist/bounded-test-policy.js +101 -40
  17. package/dist/build-state-output-policy.d.ts +25 -0
  18. package/dist/build-state-output-policy.d.ts.map +1 -0
  19. package/dist/build-state-output-policy.js +64 -0
  20. package/dist/cargo-closure-input.d.ts +3 -2
  21. package/dist/cargo-closure-input.d.ts.map +1 -1
  22. package/dist/cargo-closure-input.js +16 -15
  23. package/dist/cargo-dev-profile.d.ts +37 -0
  24. package/dist/cargo-dev-profile.d.ts.map +1 -0
  25. package/dist/cargo-dev-profile.js +108 -0
  26. package/dist/cargo-source-hash.d.ts +43 -6
  27. package/dist/cargo-source-hash.d.ts.map +1 -1
  28. package/dist/cargo-source-hash.js +309 -73
  29. package/dist/cargo-toolchain-policy.d.ts +4 -0
  30. package/dist/cargo-toolchain-policy.d.ts.map +1 -1
  31. package/dist/cargo-toolchain-policy.js +5 -0
  32. package/dist/cargo-workspace.d.ts +101 -5
  33. package/dist/cargo-workspace.d.ts.map +1 -1
  34. package/dist/cargo-workspace.js +291 -10
  35. package/dist/cross-check-policy.d.ts +21 -3
  36. package/dist/cross-check-policy.d.ts.map +1 -1
  37. package/dist/cross-check-policy.js +24 -6
  38. package/dist/disk-command-policy.d.ts +7 -0
  39. package/dist/disk-command-policy.d.ts.map +1 -0
  40. package/dist/disk-command-policy.js +98 -0
  41. package/dist/ensure-built-receipt.d.ts +25 -0
  42. package/dist/ensure-built-receipt.d.ts.map +1 -0
  43. package/dist/ensure-built-receipt.js +261 -0
  44. package/dist/ensure-built-witness.d.ts +57 -0
  45. package/dist/ensure-built-witness.d.ts.map +1 -0
  46. package/dist/ensure-built-witness.js +412 -0
  47. package/dist/ensure-built.d.ts +207 -12
  48. package/dist/ensure-built.d.ts.map +1 -1
  49. package/dist/ensure-built.js +576 -202
  50. package/dist/eslint-file-set.d.ts +7 -0
  51. package/dist/eslint-file-set.d.ts.map +1 -0
  52. package/dist/eslint-file-set.js +12 -0
  53. package/dist/executors/bounded-exec/cpu-pool.d.ts +63 -0
  54. package/dist/executors/bounded-exec/cpu-pool.d.ts.map +1 -0
  55. package/dist/executors/bounded-exec/cpu-pool.js +379 -0
  56. package/dist/executors/bounded-exec/cpu-tokens.d.ts +82 -0
  57. package/dist/executors/bounded-exec/cpu-tokens.d.ts.map +1 -0
  58. package/dist/executors/bounded-exec/cpu-tokens.js +114 -0
  59. package/dist/executors/bounded-exec/disk-lease.d.ts +61 -0
  60. package/dist/executors/bounded-exec/disk-lease.d.ts.map +1 -0
  61. package/dist/executors/bounded-exec/disk-lease.js +91 -0
  62. package/dist/executors/bounded-exec/executor.d.ts +45 -2
  63. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  64. package/dist/executors/bounded-exec/executor.js +447 -52
  65. package/dist/executors/bounded-exec/gateway-lease.d.ts +52 -0
  66. package/dist/executors/bounded-exec/gateway-lease.d.ts.map +1 -0
  67. package/dist/executors/bounded-exec/gateway-lease.js +143 -0
  68. package/dist/executors/bounded-exec/hang-diagnostics.d.ts +35 -0
  69. package/dist/executors/bounded-exec/hang-diagnostics.d.ts.map +1 -0
  70. package/dist/executors/bounded-exec/hang-diagnostics.js +231 -0
  71. package/dist/executors/bounded-exec/progress.d.ts +35 -0
  72. package/dist/executors/bounded-exec/progress.d.ts.map +1 -0
  73. package/dist/executors/bounded-exec/progress.js +79 -0
  74. package/dist/executors/bounded-exec/ram-temp-fixtures.d.ts +3 -0
  75. package/dist/executors/bounded-exec/ram-temp-fixtures.d.ts.map +1 -0
  76. package/dist/executors/bounded-exec/ram-temp-fixtures.js +12 -0
  77. package/dist/executors/bounded-exec/ram-temp-held.d.ts +91 -0
  78. package/dist/executors/bounded-exec/ram-temp-held.d.ts.map +1 -0
  79. package/dist/executors/bounded-exec/ram-temp-held.js +152 -0
  80. package/dist/executors/bounded-exec/ram-temp.d.ts +223 -0
  81. package/dist/executors/bounded-exec/ram-temp.d.ts.map +1 -0
  82. package/dist/executors/bounded-exec/ram-temp.js +1528 -0
  83. package/dist/executors/bounded-exec/schema.d.ts +29 -11
  84. package/dist/executors/bounded-exec/schema.d.ts.map +1 -1
  85. package/dist/executors/bounded-exec/verdict.d.ts +162 -0
  86. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -0
  87. package/dist/executors/bounded-exec/verdict.js +318 -0
  88. package/dist/executors/shard-timings/executor.d.ts +14 -0
  89. package/dist/executors/shard-timings/executor.d.ts.map +1 -0
  90. package/dist/executors/shard-timings/executor.js +25 -0
  91. package/dist/executors/shard-timings/schema.d.ts +4 -0
  92. package/dist/executors/shard-timings/schema.d.ts.map +1 -0
  93. package/dist/executors/shard-timings/schema.js +1 -0
  94. package/dist/failure-summary.d.ts +5 -0
  95. package/dist/failure-summary.d.ts.map +1 -0
  96. package/dist/failure-summary.js +118 -0
  97. package/dist/generators/create-package/generator.d.ts.map +1 -1
  98. package/dist/generators/create-package/generator.js +6 -2
  99. package/dist/index.d.ts +14 -2
  100. package/dist/index.d.ts.map +1 -1
  101. package/dist/index.js +370 -138
  102. package/dist/managed-files/ci-workflow.d.ts +13 -0
  103. package/dist/managed-files/ci-workflow.d.ts.map +1 -1
  104. package/dist/managed-files/ci-workflow.js +44 -13
  105. package/dist/managed-files/files.d.ts +7 -1
  106. package/dist/managed-files/files.d.ts.map +1 -1
  107. package/dist/managed-files/files.js +62 -8
  108. package/dist/managed-files/json-edit.d.ts +21 -0
  109. package/dist/managed-files/json-edit.d.ts.map +1 -0
  110. package/dist/managed-files/json-edit.js +295 -0
  111. package/dist/managed-files/managed-format.d.ts +33 -1
  112. package/dist/managed-files/managed-format.d.ts.map +1 -1
  113. package/dist/managed-files/managed-format.js +82 -2
  114. package/dist/managed-files/pr-preview-cleanup-workflow.d.ts +7 -0
  115. package/dist/managed-files/pr-preview-cleanup-workflow.d.ts.map +1 -1
  116. package/dist/managed-files/pr-preview-cleanup-workflow.js +68 -4
  117. package/dist/managed-files/publish-workflow.d.ts.map +1 -1
  118. package/dist/managed-files/publish-workflow.js +231 -48
  119. package/dist/managed-files/tree.d.ts +5 -0
  120. package/dist/managed-files/tree.d.ts.map +1 -1
  121. package/dist/managed-files/tree.js +5 -3
  122. package/dist/manifest-hash.d.ts.map +1 -1
  123. package/dist/manifest-hash.js +2 -5
  124. package/dist/nextest-code-bound.d.ts +62 -0
  125. package/dist/nextest-code-bound.d.ts.map +1 -0
  126. package/dist/nextest-code-bound.js +154 -0
  127. package/dist/nextest-extraction.d.ts +24 -8
  128. package/dist/nextest-extraction.d.ts.map +1 -1
  129. package/dist/nextest-extraction.js +42 -7
  130. package/dist/package-target-policy.d.ts.map +1 -1
  131. package/dist/package-target-policy.js +3 -5
  132. package/dist/release-config-policy.d.ts.map +1 -1
  133. package/dist/release-config-policy.js +3 -5
  134. package/dist/runtime-input.d.ts +14 -0
  135. package/dist/runtime-input.d.ts.map +1 -0
  136. package/dist/runtime-input.js +15 -0
  137. package/dist/rust-tokens.d.ts +11 -0
  138. package/dist/rust-tokens.d.ts.map +1 -0
  139. package/dist/rust-tokens.js +81 -0
  140. package/dist/task-results.d.ts +6 -0
  141. package/dist/task-results.d.ts.map +1 -0
  142. package/dist/task-results.js +61 -0
  143. package/dist/test-program.d.ts +54 -0
  144. package/dist/test-program.d.ts.map +1 -0
  145. package/dist/test-program.js +292 -0
  146. package/dist/test-timings.d.ts +71 -0
  147. package/dist/test-timings.d.ts.map +1 -0
  148. package/dist/test-timings.js +393 -0
  149. package/dist/test-walk-policy.d.ts +103 -0
  150. package/dist/test-walk-policy.d.ts.map +1 -0
  151. package/dist/test-walk-policy.js +657 -0
  152. package/dist/testing.d.ts +177 -0
  153. package/dist/testing.d.ts.map +1 -0
  154. package/dist/testing.js +824 -0
  155. package/dist/type-guards.d.ts +3 -0
  156. package/dist/type-guards.d.ts.map +1 -0
  157. package/dist/type-guards.js +4 -0
  158. package/dist/typecheck-test-policy.d.ts +8 -5
  159. package/dist/typecheck-test-policy.d.ts.map +1 -1
  160. package/dist/typecheck-test-policy.js +113 -100
  161. package/dist/workspace-config-policy.d.ts +8 -0
  162. package/dist/workspace-config-policy.d.ts.map +1 -1
  163. package/dist/workspace-config-policy.js +175 -63
  164. package/dist/workspace-index.d.ts +12 -0
  165. package/dist/workspace-index.d.ts.map +1 -0
  166. package/dist/workspace-index.js +17 -0
  167. package/dist/workspace-manifest.d.ts +37 -0
  168. package/dist/workspace-manifest.d.ts.map +1 -1
  169. package/executors.json +5 -0
  170. package/loader.js +13 -11
  171. package/managed/raw/envrc +33 -67
  172. package/managed/raw/git-format-staged.yml +30 -35
  173. package/managed/raw/patches/nx@23.2.1.patch +3484 -0
  174. package/managed/raw/tooling/direnv/apple-developer.sh +83 -0
  175. package/managed/raw/tooling/direnv/developer-links.ts +569 -11
  176. package/managed/raw/tooling/direnv/devenv.smoo.nix +314 -93
  177. package/managed/raw/tooling/direnv/github-actions-bootstrap.sh +20 -11
  178. package/managed/raw/tooling/direnv/linked-snapshots.ts +845 -0
  179. package/managed/raw/tooling/direnv/nx-socket-dir.sh +82 -0
  180. package/managed/raw/tooling/direnv/repo-path +14 -2
  181. package/managed/raw/tooling/direnv/setup-environment.ts +1146 -159
  182. package/managed/raw/tooling/direnv/toolchain-stamp.ts +45 -3
  183. package/managed/raw/tooling/direnv/ttsc-env.sh +39 -0
  184. package/managed/raw/tooling/git-hooks/commit-msg.sh +5 -6
  185. package/managed/raw/tooling/git-hooks/pre-commit.sh +7 -6
  186. package/managed/raw/tooling/git-hooks/pre-push.sh +20 -15
  187. package/managed/templates/github/actions/cache-nix-devenv/action.yml +6 -6
  188. package/managed/templates/github/actions/cache-node-modules/action.yml +6 -4
  189. package/managed/templates/github/actions/cache-nx/action.yml +1 -1
  190. package/managed/templates/github/actions/cache-ttsc-plugins/action.yml +1 -1
  191. package/managed/templates/github/actions/forgejo-artifact.cjs +99 -0
  192. package/managed/templates/github/actions/forgejo-download-artifact/action.yml +49 -0
  193. package/managed/templates/github/actions/forgejo-download-artifact/index.cjs +7 -0
  194. package/managed/templates/github/actions/forgejo-upload-artifact/action.yml +65 -0
  195. package/managed/templates/github/actions/forgejo-upload-artifact/index.cjs +7 -0
  196. package/managed/templates/github/actions/setup-devenv/action.yml +21 -3
  197. package/managed/templates/github/workflows/managed-files.yml +1 -2
  198. package/nextest.toml +8 -41
  199. package/package.json +74 -12
  200. package/runtime-input.sh +81 -0
  201. package/src/__tests__/counted-cargo.ts +33 -14
  202. package/src/__tests__/fixture-nx-env.ts +111 -46
  203. package/src/__tests__/progress-clock.ts +43 -0
  204. package/src/__tests__/runtime-input.ts +23 -0
  205. package/src/bin/smoo-nx-bound-failures.test.ts +127 -0
  206. package/src/bin/smoo-nx-bound-failures.ts +33 -0
  207. package/src/bin/smoo-nx-cargo-hash.ts +28 -3
  208. package/src/bin/smoo-nx-exec.ts +16 -74
  209. package/src/bin/smoo-nx-failures.ts +4 -0
  210. package/src/bin/smoo-nx-nextest-extract.ts +3 -2
  211. package/src/bin/smoo-nx-test-walks.ts +42 -0
  212. package/src/bounded-test-policy.test.ts +268 -21
  213. package/src/bounded-test-policy.ts +114 -42
  214. package/src/build-state-output-policy.test.ts +115 -0
  215. package/src/build-state-output-policy.ts +90 -0
  216. package/src/bun-bootstrap.test.ts +57 -3
  217. package/src/bun-file-packages.test.ts +47 -0
  218. package/src/cargo-closure-input.test.ts +138 -66
  219. package/src/cargo-closure-input.ts +17 -15
  220. package/src/cargo-dev-profile.ts +137 -0
  221. package/src/cargo-resolve-cache.test.ts +70 -1
  222. package/src/cargo-source-hash.test.ts +193 -97
  223. package/src/cargo-source-hash.ts +345 -68
  224. package/src/cargo-toolchain-policy.ts +6 -0
  225. package/src/cargo-workspace.test.ts +320 -0
  226. package/src/cargo-workspace.ts +336 -10
  227. package/src/cross-check-policy.test.ts +59 -1
  228. package/src/cross-check-policy.ts +25 -6
  229. package/src/disk-command-policy.test.ts +61 -0
  230. package/src/disk-command-policy.ts +107 -0
  231. package/src/ensure-built-receipt.test.ts +184 -0
  232. package/src/ensure-built-receipt.ts +263 -0
  233. package/src/ensure-built-witness.test.ts +344 -0
  234. package/src/ensure-built-witness.ts +252 -0
  235. package/src/ensure-built.test.ts +1036 -578
  236. package/src/ensure-built.ts +820 -224
  237. package/src/eslint-file-set.ts +9 -0
  238. package/src/executors/bounded-exec/cpu-pool.test.ts +454 -0
  239. package/src/executors/bounded-exec/cpu-pool.ts +417 -0
  240. package/src/executors/bounded-exec/cpu-tokens.test.ts +269 -0
  241. package/src/executors/bounded-exec/cpu-tokens.ts +177 -0
  242. package/src/executors/bounded-exec/disk-lease.test.ts +185 -0
  243. package/src/executors/bounded-exec/disk-lease.ts +139 -0
  244. package/src/executors/bounded-exec/executor-host.test.ts +778 -0
  245. package/src/executors/bounded-exec/executor.test.ts +1116 -63
  246. package/src/executors/bounded-exec/executor.ts +565 -67
  247. package/src/executors/bounded-exec/gateway-lease.ts +176 -0
  248. package/src/executors/bounded-exec/hang-diagnostics.test.ts +285 -0
  249. package/src/executors/bounded-exec/hang-diagnostics.ts +283 -0
  250. package/src/executors/bounded-exec/progress.test.ts +79 -0
  251. package/src/executors/bounded-exec/progress.ts +118 -0
  252. package/src/executors/bounded-exec/ram-temp-fixtures.ts +12 -0
  253. package/src/executors/bounded-exec/ram-temp-held.test.ts +264 -0
  254. package/src/executors/bounded-exec/ram-temp-held.ts +242 -0
  255. package/src/executors/bounded-exec/ram-temp-host.test.ts +605 -0
  256. package/src/executors/bounded-exec/ram-temp.test.ts +674 -0
  257. package/src/executors/bounded-exec/ram-temp.ts +1918 -0
  258. package/src/executors/bounded-exec/schema.json +11 -5
  259. package/src/executors/bounded-exec/schema.ts +27 -11
  260. package/src/executors/bounded-exec/verdict.test.ts +440 -0
  261. package/src/executors/bounded-exec/verdict.ts +433 -0
  262. package/src/executors/shard-timings/executor.ts +36 -0
  263. package/src/executors/shard-timings/schema.json +21 -0
  264. package/src/executors/shard-timings/schema.ts +4 -0
  265. package/src/failure-summary.ts +119 -0
  266. package/src/generators/bounded-test-targets/generator.test.ts +4 -4
  267. package/src/generators/bun-test-tracing/generator.test.ts +2 -2
  268. package/src/generators/create-package/generator.test.ts +6 -0
  269. package/src/generators/create-package/generator.ts +6 -2
  270. package/src/host-controller-wiring.test.ts +31 -0
  271. package/src/index.test.ts +909 -295
  272. package/src/index.ts +441 -143
  273. package/src/linked-snapshots.nx.test.ts +172 -0
  274. package/src/managed-files/ci-workflow.ts +54 -13
  275. package/src/managed-files/files.ts +65 -9
  276. package/src/managed-files/forgejo-artifact.test.ts +395 -0
  277. package/src/managed-files/generator.test.ts +60 -1
  278. package/src/managed-files/json-edit.test.ts +216 -0
  279. package/src/managed-files/json-edit.ts +290 -0
  280. package/src/managed-files/managed-format-json.test.ts +308 -0
  281. package/src/managed-files/managed-format.ts +90 -2
  282. package/src/managed-files/pr-preview-cleanup-workflow.ts +69 -3
  283. package/src/managed-files/publish-workflow.ts +285 -67
  284. package/src/managed-files/repo-path.test.ts +129 -0
  285. package/src/managed-files/trace-db-artifact.test.ts +7 -0
  286. package/src/managed-files/tree.ts +11 -3
  287. package/src/manifest-hash.ts +2 -6
  288. package/src/nextest-code-bound.test.ts +155 -0
  289. package/src/nextest-code-bound.ts +195 -0
  290. package/src/nextest-extraction.test.ts +37 -5
  291. package/src/nextest-extraction.ts +51 -9
  292. package/src/nextest-partitions.test.ts +427 -82
  293. package/src/nx-cache-bound.test.ts +5 -10
  294. package/src/nx-cache-restore-mtime.test.ts +170 -0
  295. package/src/nx-daemon-claim.test.ts +277 -0
  296. package/src/nx-daemon-idle-cpu.test.ts +81 -0
  297. package/src/nx-daemon-idle-policy.test.ts +51 -0
  298. package/src/nx-daemon-ignore-files.test.ts +210 -0
  299. package/src/nx-daemon-root-normalization.test.ts +105 -0
  300. package/src/nx-daemon-validity.test.ts +925 -0
  301. package/src/nx-dot-input-policy.test.ts +353 -0
  302. package/src/nx-failure-life-cycles.test.ts +207 -0
  303. package/src/nx-files-archive-racy.test.ts +97 -0
  304. package/src/nx-foreign-workspace-env.test.ts +329 -0
  305. package/src/nx-incomplete-run-summary.test.ts +70 -0
  306. package/src/nx-plugin-load-errors.test.ts +120 -0
  307. package/src/nx-project-resolution-cache.test.ts +176 -0
  308. package/src/nx-raw-inputs.test.ts +166 -0
  309. package/src/nx-resident-graph-workers.test.ts +7 -16
  310. package/src/nx-run-information.test.ts +118 -0
  311. package/src/nx-skipped-task-exit.test.ts +180 -0
  312. package/src/nx-state-location.test.ts +63 -0
  313. package/src/nx-store-resolution.test.ts +26 -25
  314. package/src/nx-task-graph-cycles.test.ts +148 -0
  315. package/src/nx-task-output-lease.test.ts +414 -0
  316. package/src/nx-use-local.test.ts +103 -0
  317. package/src/package-target-policy.ts +3 -6
  318. package/src/release-config-policy.ts +3 -6
  319. package/src/runtime-input.test.ts +215 -0
  320. package/src/runtime-input.ts +17 -0
  321. package/src/rust-tokens.ts +78 -0
  322. package/src/serial-group-wiring.test.ts +326 -0
  323. package/src/task-history-namespace.test.ts +87 -89
  324. package/src/task-results.test.ts +226 -0
  325. package/src/task-results.ts +75 -0
  326. package/src/test-program.test.ts +303 -0
  327. package/src/test-program.ts +341 -0
  328. package/src/test-timings.test.ts +240 -0
  329. package/src/test-timings.ts +311 -0
  330. package/src/test-walk-policy.test.ts +585 -0
  331. package/src/test-walk-policy.ts +731 -0
  332. package/src/testing.test.ts +509 -0
  333. package/src/testing.ts +922 -0
  334. package/src/type-guards.ts +4 -0
  335. package/src/typecheck-test-policy.test.ts +496 -11
  336. package/src/typecheck-test-policy.ts +137 -103
  337. package/src/workspace-config-policy.test.ts +212 -13
  338. package/src/workspace-config-policy.ts +101 -73
  339. package/src/workspace-index.ts +18 -0
  340. package/src/workspace-manifest.ts +41 -0
  341. package/test-timings.json +85 -30
  342. package/managed/raw/tooling/direnv/inherited-devenv.ts +0 -665
  343. package/managed/raw/tooling/direnv/shared-caches.sh +0 -53
@@ -0,0 +1,176 @@
1
+ import { connect } from 'node:net';
2
+
3
+ /**
4
+ * The client half of a lease held on the cowshed gateway's control socket: the host
5
+ * disk-lifecycle lease (`disk-lease.ts`) and the host CPU budget (`cpu-tokens.ts`) speak the same
6
+ * protocol (specs/cowshed/05_gateway.md, "Disk-lifecycle lease" and "Host CPU budget").
7
+ *
8
+ * The client writes one request line and keeps the connection open without half-closing it. The
9
+ * gateway answers `queued` at once and `granted` when the lease is the client's, and the lease
10
+ * lasts until the client closes the connection, so a client that dies holding one releases it with
11
+ * its socket. A lease never decides whether a command runs: without a grant, it runs without one
12
+ * and the caller says why.
13
+ */
14
+
15
+ /** The cowshed gateway's control socket, at the store root every peer agrees on. */
16
+ export const GATEWAY_SOCKET = '/private/cowshed/store/gateway.sock';
17
+
18
+ export interface LeaseBounds {
19
+ /** For the `queued` answer a lease-scheduling gateway sends at once. */
20
+ ackMs: number;
21
+ /** For any answer once the request is half-closed. */
22
+ afterCloseMs: number;
23
+ /** For the grant, once queued; `null` waits for as long as the gateway keeps it queued. */
24
+ grantMs: number | null;
25
+ }
26
+
27
+ /**
28
+ * Why a command runs without a lease: no gateway listens, the gateway predates this kind of lease,
29
+ * the gateway knows the lease but predates a field the request names (it refuses the field at
30
+ * once), or any other refusal, silence or breakage.
31
+ */
32
+ export type UnleasedCause = 'absent' | 'predates' | 'predates-field' | 'other';
33
+
34
+ /**
35
+ * A granted lease with its `granted` answer, held until released, or why there is none. `closed`
36
+ * resolves when the connection really closes: after `release`, when the gateway ends it, or when
37
+ * the client process dies.
38
+ */
39
+ export type HeldLease =
40
+ | { granted: true; answer: Readonly<Record<string, unknown>>; release: () => void; closed: Promise<void> }
41
+ | { granted: false; cause: UnleasedCause; reason: string; code?: string };
42
+
43
+ /**
44
+ * Ask the gateway at `socket` for the lease `request` names, `what` in its messages ("disk
45
+ * leases", "the CPU budget"). A gateway from before one-line requests says nothing until it reads
46
+ * EOF, so a request not queued within `ackMs` is half-closed and that gateway's refusal read; a
47
+ * gateway that reads the line but does not know the operation refuses it at once. Both predate the
48
+ * lease.
49
+ */
50
+ export function holdLease(
51
+ socket: string,
52
+ request: Readonly<Record<string, unknown>>,
53
+ what: string,
54
+ bounds: LeaseBounds,
55
+ onQueued?: () => void,
56
+ ): Promise<HeldLease> {
57
+ // `Promise.withResolvers` would read better but needs lib es2024; this package inherits lib
58
+ // es2022 from tsconfig.base.json.
59
+ let resolve!: (outcome: HeldLease) => void;
60
+ const promise = new Promise<HeldLease>((settled) => {
61
+ resolve = settled;
62
+ });
63
+ const connection = connect(socket);
64
+ // `closed` is made when a consumer reads it, so a lease nobody watches allocates no promise. The
65
+ // flag, not `connection.destroyed`, says the socket really closed: `destroy()` sets that flag before
66
+ // the `close` event fires.
67
+ let socketClosed = false;
68
+ let closed: Promise<void> | undefined;
69
+ let state: 'connecting' | 'asked' | 'half-closed' | 'queued' | 'settled' = 'connecting';
70
+ let buffered = '';
71
+ let timer: NodeJS.Timeout | undefined;
72
+ const settle = (outcome: HeldLease) => {
73
+ if (state === 'settled') {
74
+ return;
75
+ }
76
+ state = 'settled';
77
+ clearTimeout(timer);
78
+ if (!outcome.granted) {
79
+ connection.destroy();
80
+ }
81
+ resolve(outcome);
82
+ };
83
+ const unleased = (reason: string, cause: UnleasedCause = 'other', code?: string) =>
84
+ settle({ granted: false, cause, reason, ...(code === undefined ? {} : { code }) });
85
+ const wait = (ms: number, onExpiry: () => void) => {
86
+ clearTimeout(timer);
87
+ timer = setTimeout(onExpiry, ms);
88
+ };
89
+ const answer = (line: string) => {
90
+ let parsed: unknown;
91
+ try {
92
+ parsed = JSON.parse(line);
93
+ } catch {
94
+ unleased(`the gateway answered something that is not an answer: ${line}`);
95
+ return;
96
+ }
97
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
98
+ unleased(`the gateway answered something that is not an answer: ${line}`);
99
+ return;
100
+ }
101
+ const fields: Readonly<Record<string, unknown>> = Object.fromEntries(Object.entries(parsed));
102
+ const lease = fields.lease;
103
+ if (fields.ok !== true) {
104
+ const error = String(fields.error ?? '');
105
+ const why = `${String(fields.code ?? 'refused')}: ${error}`;
106
+ if (state === 'half-closed' || error.endsWith('unknown gateway control operation')) {
107
+ unleased(`the gateway predates ${what} (${why}); restart it with \`cowshed setup\``, 'predates');
108
+ } else if (error.endsWith('contains an unknown field')) {
109
+ unleased(
110
+ `the gateway predates a field of ${what} (${why}); restart it with \`cowshed setup\``,
111
+ 'predates-field',
112
+ );
113
+ } else {
114
+ unleased(
115
+ `the gateway refused the lease (${why})`,
116
+ 'other',
117
+ typeof fields.code === 'string' ? fields.code : undefined,
118
+ );
119
+ }
120
+ } else if (state === 'half-closed') {
121
+ unleased('the gateway did not queue the request in time; it is alive but overloaded');
122
+ } else if (state === 'asked' && lease === 'queued') {
123
+ state = 'queued';
124
+ onQueued?.();
125
+ const grantMs = bounds.grantMs;
126
+ if (grantMs === null) {
127
+ clearTimeout(timer);
128
+ } else {
129
+ wait(grantMs, () => unleased(`the gateway granted nothing within ${grantMs} ms`));
130
+ }
131
+ } else if (state === 'queued' && lease === 'granted') {
132
+ settle({
133
+ granted: true,
134
+ answer: fields,
135
+ release: () => connection.destroy(),
136
+ get closed() {
137
+ closed ??= socketClosed
138
+ ? Promise.resolve()
139
+ : new Promise<void>((done) => connection.once('close', () => done()));
140
+ return closed;
141
+ },
142
+ });
143
+ } else {
144
+ unleased(`the gateway answered out of turn: ${line}`);
145
+ }
146
+ };
147
+ connection.on('connect', () => {
148
+ state = 'asked';
149
+ connection.write(`${JSON.stringify(request)}\n`);
150
+ wait(bounds.ackMs, () => {
151
+ state = 'half-closed';
152
+ connection.end();
153
+ wait(bounds.afterCloseMs, () => unleased('the gateway answered nothing'));
154
+ });
155
+ });
156
+ connection.on('data', (chunk: Buffer) => {
157
+ buffered += chunk.toString('utf8');
158
+ for (let newline = buffered.indexOf('\n'); newline !== -1; newline = buffered.indexOf('\n')) {
159
+ const line = buffered.slice(0, newline);
160
+ buffered = buffered.slice(newline + 1);
161
+ answer(line);
162
+ }
163
+ });
164
+ connection.on('error', (error) => {
165
+ if (state === 'connecting') {
166
+ unleased(`the gateway's control socket ${socket} does not answer (${error.message})`, 'absent');
167
+ } else {
168
+ unleased(error.message);
169
+ }
170
+ });
171
+ connection.on('close', () => {
172
+ socketClosed = true;
173
+ unleased('the gateway closed the lease connection');
174
+ });
175
+ return promise;
176
+ }
@@ -0,0 +1,285 @@
1
+ import { describe, expect, it } from 'bun:test';
2
+ import { mkdtemp, rm, writeFile } from 'node:fs/promises';
3
+ import { tmpdir } from 'node:os';
4
+ import { join } from 'node:path';
5
+ import {
6
+ captureHangDiagnostics,
7
+ type HangCaptureRequest,
8
+ type HangDiagnosticHost,
9
+ type HangProbeResult,
10
+ } from './hang-diagnostics.js';
11
+
12
+ const ROOT = 101;
13
+ const STARTED = 'Thu Oct 15 12:34:56 2026';
14
+ const rootRow = `${ROOT} 1 ${ROOT} S 0.0 03:01 ${STARTED} runner --test selected`;
15
+ const childRow = `202 ${ROOT} ${ROOT} S 0.0 03:00 ${STARTED} child waiting`;
16
+ const grandchildRow = `303 202 ${ROOT} S 0.0 02:59 ${STARTED} grandchild holding pipe`;
17
+ const reparentedRow = `404 1 ${ROOT} S 0.0 02:58 ${STARTED} reparented group member`;
18
+ const unrelatedRow = `505 1 505 S 0.0 02:58 ${STARTED} unrelated process`;
19
+ const census = [rootRow, childRow, grandchildRow, reparentedRow, unrelatedRow].join('\n');
20
+ const fileObservation =
21
+ 'COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME\nchild 303 tester 7r REG 1,2 4 123 /fixture/held-file\n';
22
+ const exited = (stdout: string, code = 0, stderr = ''): HangProbeResult => ({ status: 'exited', code, stdout, stderr });
23
+ const request = (): HangCaptureRequest => ({
24
+ pid: ROOT,
25
+ pgid: ROOT,
26
+ expiresAtMs: Date.now() + 5_000,
27
+ deadlineMs: 5_000,
28
+ });
29
+
30
+ function scriptedHost(results: readonly HangProbeResult[]) {
31
+ const calls: { file: string; args: readonly string[]; timeoutMs: number }[] = [];
32
+ let index = 0;
33
+ const host: HangDiagnosticHost = {
34
+ platform: 'darwin',
35
+ async probe(file, args, timeoutMs) {
36
+ calls.push({ file, args, timeoutMs });
37
+ const result = results[index++];
38
+ if (result === undefined) throw new Error(`unexpected probe ${file}`);
39
+ return result;
40
+ },
41
+ };
42
+ return { host, calls };
43
+ }
44
+
45
+ describe('pre-expiry hang diagnostics', () => {
46
+ it('keeps grandchildren and reparented group members, but not unrelated host rows', async () => {
47
+ const { host, calls } = scriptedHost([exited(census), exited(fileObservation), exited(census)]);
48
+ const capture = await captureHangDiagnostics(request(), host);
49
+ expect(capture.outcome).toBe('holders');
50
+ for (const row of [rootRow, childRow, grandchildRow, reparentedRow]) expect(capture.text).toContain(row);
51
+ expect(capture.text).not.toContain(unrelatedRow);
52
+ expect(capture.text).toContain('/fixture/held-file');
53
+ expect(capture.text).toContain('not proof of a contested lock');
54
+ expect(capture.text).toContain('pid=101 pgid=101');
55
+ expect(calls.map((call) => call.file)).toEqual(['ps', 'sudo', 'ps']);
56
+ expect(calls[1]?.args).toEqual(['-n', 'lsof', '-nP', '-p', '101,202,303,404']);
57
+ expect(capture.offsetFromExpiryMs).toBeGreaterThan(0);
58
+ expect(capture.capturedAtMs).toBeGreaterThanOrEqual(capture.startedAtMs);
59
+ });
60
+
61
+ it('reports no matches only after successful resource inspection and stable identities', async () => {
62
+ const { host } = scriptedHost([exited(rootRow), exited('', 1), exited(rootRow)]);
63
+ const capture = await captureHangDiagnostics(request(), host);
64
+ expect(capture.outcome).toBe('none');
65
+ expect(capture.text).toContain('no open-file matches within its stated visibility');
66
+ });
67
+
68
+ it('names denied privileged access and limits fallback claims to ordinary-user visibility', async () => {
69
+ const denied: HangProbeResult = {
70
+ status: 'unavailable',
71
+ detail: 'sudo: permission denied',
72
+ stdout: '',
73
+ stderr: '',
74
+ };
75
+ const { host, calls } = scriptedHost([exited(rootRow), denied, exited(fileObservation), exited(rootRow)]);
76
+ const capture = await captureHangDiagnostics(request(), host);
77
+ expect(capture.outcome).toBe('incomplete');
78
+ expect(capture.text).toContain('sudo: permission denied');
79
+ expect(capture.text).toContain('ordinary-user visibility only');
80
+ expect(capture.text).toContain('/fixture/held-file');
81
+ expect(calls[2]?.file).toBe('lsof');
82
+ });
83
+
84
+ it('retains partial failed output instead of replacing it with an empty fallback', async () => {
85
+ const partial: HangProbeResult = {
86
+ status: 'failed',
87
+ detail: 'probe output exceeded bound; output is incomplete',
88
+ stdout: fileObservation,
89
+ stderr: 'read failed',
90
+ };
91
+ const { host } = scriptedHost([exited(rootRow), partial, exited('', 1), exited(rootRow)]);
92
+ const capture = await captureHangDiagnostics(request(), host);
93
+ expect(capture.outcome).toBe('incomplete');
94
+ expect(capture.text).toContain('Partial privileged lsof output');
95
+ expect(capture.text).toContain('/fixture/held-file');
96
+ expect(capture.text).toContain('read failed');
97
+ });
98
+
99
+ it('does not turn an exited root, reused pid, or changed descendant membership into no holders', async () => {
100
+ const absent = scriptedHost([exited(unrelatedRow)]);
101
+ expect((await captureHangDiagnostics(request(), absent.host)).outcome).toBe('incomplete');
102
+ expect(absent.calls).toHaveLength(1);
103
+ for (const after of [rootRow.replace(STARTED, 'Thu Oct 15 12:35:00 2026'), `${rootRow}\n${childRow}`]) {
104
+ const { host } = scriptedHost([exited(rootRow), exited('', 1), exited(after)]);
105
+ const capture = await captureHangDiagnostics(request(), host);
106
+ expect(capture.outcome).toBe('incomplete');
107
+ expect(capture.text).toContain('identities or membership changed');
108
+ }
109
+ });
110
+
111
+ it('names process probe failures and malformed census output without throwing', async () => {
112
+ for (const result of [
113
+ exited('', 1, 'ps: denied'),
114
+ exited('not a ps row'),
115
+ { status: 'timed-out', detail: 'ps deadline', stdout: '', stderr: '' } satisfies HangProbeResult,
116
+ ]) {
117
+ const { host } = scriptedHost([result]);
118
+ const capture = await captureHangDiagnostics(request(), host);
119
+ expect(capture.outcome).toBe('incomplete');
120
+ expect(capture.text).toContain('ps before');
121
+ }
122
+ const throwing: HangDiagnosticHost = {
123
+ platform: 'darwin',
124
+ async probe() {
125
+ throw new Error('probe rejected');
126
+ },
127
+ };
128
+ expect((await captureHangDiagnostics(request(), throwing)).text).toContain('probe rejected');
129
+ });
130
+
131
+ it('returns at its own deadline even when the probe never answers, and starts no later probe', async () => {
132
+ let calls = 0;
133
+ let signal: AbortSignal | undefined;
134
+ const unresponsive: HangDiagnosticHost = {
135
+ platform: 'darwin',
136
+ probe(_file, _args, _timeoutMs, captureSignal) {
137
+ calls += 1;
138
+ signal = captureSignal;
139
+ // An unanswered process boundary; the capture must not rely on its cooperation.
140
+ return new Promise<HangProbeResult>(() => {});
141
+ },
142
+ };
143
+ const capture = await captureHangDiagnostics({ ...request(), deadlineMs: 1 }, unresponsive);
144
+ expect(capture.outcome).toBe('incomplete');
145
+ expect(capture.text).toContain('1ms deadline reached during ps before');
146
+ expect(signal?.aborted).toBe(true);
147
+ expect(calls).toBe(1);
148
+ });
149
+
150
+ it('cancels a pending probe when its progress generation ends without starting another', async () => {
151
+ const controller = new AbortController();
152
+ let calls = 0;
153
+ let seen: AbortSignal | undefined;
154
+ const pending: HangDiagnosticHost = {
155
+ platform: 'darwin',
156
+ probe(_file, _args, _timeoutMs, signal) {
157
+ calls += 1;
158
+ seen = signal;
159
+ return new Promise<HangProbeResult>(() => {});
160
+ },
161
+ };
162
+ const collecting = captureHangDiagnostics({ ...request(), signal: controller.signal }, pending);
163
+ expect(calls).toBe(1);
164
+ controller.abort();
165
+ const capture = await collecting;
166
+ expect(capture.outcome).toBe('incomplete');
167
+ expect(capture.text).toContain('Capture cancelled during ps before');
168
+ expect(seen?.aborted).toBe(true);
169
+ expect(calls).toBe(1);
170
+ });
171
+
172
+ it('starts no probe for a generation already cancelled', async () => {
173
+ const controller = new AbortController();
174
+ controller.abort();
175
+ const { host, calls } = scriptedHost([]);
176
+ const capture = await captureHangDiagnostics({ ...request(), signal: controller.signal }, host);
177
+ expect(capture.outcome).toBe('incomplete');
178
+ expect(capture.text).toContain('Capture cancelled');
179
+ expect(calls).toHaveLength(0);
180
+ });
181
+
182
+ it('starts no process probe after the pre-expiry window or with no remaining budget', async () => {
183
+ for (const bounds of [{ expiresAtMs: Date.now() - 1 }, { deadlineMs: 0 }]) {
184
+ const { host, calls } = scriptedHost([]);
185
+ const capture = await captureHangDiagnostics({ ...request(), ...bounds }, host);
186
+ expect(capture.outcome).toBe('incomplete');
187
+ expect(capture.text).toContain('no probe started');
188
+ expect(calls).toEqual([]);
189
+ }
190
+ });
191
+
192
+ it('keeps process-only visibility explicit on platforms without the Darwin open-file probe', async () => {
193
+ const { host, calls } = scriptedHost([exited(rootRow), exited(rootRow)]);
194
+ const capture = await captureHangDiagnostics(request(), { ...host, platform: 'linux' });
195
+ expect(capture.outcome).toBe('holders');
196
+ expect(capture.text).toContain('observations below name processes only');
197
+ expect(calls.map((call) => call.file)).toEqual(['ps', 'ps']);
198
+ });
199
+
200
+ it('captures a real child, its grandchild, and an actually open file before either is stopped', async () => {
201
+ const directory = await mkdtemp(join(tmpdir(), 'hang-snapshot-'));
202
+ const held = join(directory, 'held');
203
+ await writeFile(held, 'owned file\n');
204
+ const child = Bun.spawn(
205
+ [
206
+ process.execPath,
207
+ '-e',
208
+ `
209
+ const fs = require('node:fs');
210
+ fs.openSync(process.env.HANG_SNAPSHOT_FILE, 'r');
211
+ const descendant = Bun.spawn([process.execPath, '-e', "console.log('ready'); process.stdin.resume()"], {
212
+ stdin: 'pipe', stdout: 'pipe', stderr: 'ignore',
213
+ });
214
+ const ready = descendant.stdout.getReader();
215
+ await ready.read();
216
+ ready.releaseLock();
217
+ console.log('PID=' + descendant.pid);
218
+ process.stdin.resume();
219
+ `,
220
+ ],
221
+ {
222
+ env: { ...process.env, HANG_SNAPSHOT_FILE: held },
223
+ stdin: 'pipe',
224
+ stdout: 'pipe',
225
+ stderr: 'pipe',
226
+ },
227
+ );
228
+ let descendant: number | undefined;
229
+ const failures: unknown[] = [];
230
+ try {
231
+ const reader = child.stdout
232
+ .pipeThrough(new TextDecoderStream(), { signal: AbortSignal.timeout(10_000) })
233
+ .getReader();
234
+ let text = '';
235
+ try {
236
+ // Real OS-pipe readiness cannot advance a fake test clock; abort only bounds a missing line.
237
+ for (;;) {
238
+ const chunk = await reader.read();
239
+ if (chunk.done) throw new Error('child stdout ended before a complete PID line');
240
+ text += chunk.value;
241
+ if (text.includes('\n')) break;
242
+ }
243
+ } catch (cause) {
244
+ throw new Error(`PID readiness failed; observed ${JSON.stringify(text)}`, { cause });
245
+ } finally {
246
+ reader.releaseLock();
247
+ }
248
+ const line = text.slice(0, text.indexOf('\n'));
249
+ const match = /^PID=(\d+)$/.exec(line);
250
+ descendant = match === null ? Number.NaN : Number(match[1]);
251
+ expect(
252
+ Number.isSafeInteger(descendant) && descendant > 0,
253
+ `expected a tagged PID line, observed ${JSON.stringify(line)}`,
254
+ ).toBe(true);
255
+ const capture = await captureHangDiagnostics({ ...request(), pid: child.pid, pgid: null });
256
+ expect(capture.outcome).toBe('holders');
257
+ expect(capture.text).toContain(String(child.pid));
258
+ expect(capture.text).toContain(String(descendant));
259
+ if (process.platform === 'darwin') expect(capture.text).toContain(held);
260
+ } catch (error) {
261
+ failures.push(error);
262
+ }
263
+ if (descendant !== undefined && Number.isSafeInteger(descendant) && descendant > 0) {
264
+ try {
265
+ process.kill(descendant, 'SIGKILL');
266
+ } catch (error) {
267
+ if (!(error instanceof Error && 'code' in error && error.code === 'ESRCH')) failures.push(error);
268
+ }
269
+ }
270
+ try {
271
+ child.kill('SIGKILL');
272
+ await child.exited;
273
+ } catch (error) {
274
+ failures.push(error);
275
+ }
276
+ try {
277
+ await rm(directory, { recursive: true, force: true });
278
+ } catch (error) {
279
+ failures.push(error);
280
+ }
281
+ if (failures.length > 0) {
282
+ throw new AggregateError(failures, `hang snapshot fixture ${directory} failed`);
283
+ }
284
+ });
285
+ });