@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
package/src/testing.ts ADDED
@@ -0,0 +1,922 @@
1
+ /**
2
+ * Ownership and retirement of the temp workspaces a test suite runs real Nx
3
+ * in, shared by every package whose tests do.
4
+ *
5
+ * A fixture that runs Nx with its daemon on leaves a daemon whose working
6
+ * directory is the fixture: it idles, watches files and burns CPU until
7
+ * someone stops it. A test that throws stops it in its `finally`; a test
8
+ * process that is killed runs no `finally`. So every fixture root lives in a
9
+ * run directory named for the test process that owns it,
10
+ * `<parent>/smoothbricks-fixtures/<suite>/run-<pid>`, where the caller names
11
+ * the parent: the temp directory, or the directory of a volume the fixture has
12
+ * to lie on. A process that gets SIGTERM, SIGINT or SIGHUP (a bounded test
13
+ * leg's timeout sends SIGTERM, and SIGKILL 10 s later) first stops whatever
14
+ * still works in every run it holds, then dies of that signal. One killed
15
+ * outright cannot, so the first fixture a process creates for a suite under a
16
+ * parent reclaims every run of that suite there whose owner is gone: each
17
+ * process working in it is stopped, then the run is deleted. A run whose owner
18
+ * still exists is never touched by another process, so nothing outside a dead
19
+ * or dying run of the same suite is ever signalled.
20
+ *
21
+ * The module also says where a fixture's sockets and loopback listeners may
22
+ * live, because a Cowshed sandbox admits only its own: a Unix socket under its
23
+ * own tree or short runtime link, a TCP connect to a port of its own block. A
24
+ * literal `/tmp/x.sock` or a port-0 listener still binds there, and then no
25
+ * process of the workspace can reach it (specs/cowshed/04_sandbox.md).
26
+ *
27
+ * Node APIs and the library's public workspace-root finder only: this module
28
+ * is built with the library and imported by Bun tests in other packages.
29
+ */
30
+ import { execFile } from 'node:child_process';
31
+ import { createHash } from 'node:crypto';
32
+ import { lstatSync, readlinkSync, realpathSync, statSync } from 'node:fs';
33
+ import { lstat, mkdir, mkdtemp, readdir, readFile, readlink, realpath, rm, symlink, writeFile } from 'node:fs/promises';
34
+ import { tmpdir, userInfo } from 'node:os';
35
+ import { dirname, isAbsolute, join, sep } from 'node:path';
36
+ import { setTimeout as sleep } from 'node:timers/promises';
37
+ import { promisify } from 'node:util';
38
+ import { findNxWorkspaceRoot } from './ensure-built.js';
39
+
40
+ const run = promisify(execFile);
41
+ const EXIT_TIMEOUT_MS = 10_000;
42
+ /** Under half of the SIGTERM-to-SIGKILL grace a bounded test leg gives, per round of signals. */
43
+ const SIGNALLED_GRACE_MS = 3_000;
44
+ const FIXTURE_HOME = 'smoothbricks-fixtures';
45
+ const RUN_NAME = /^run-(\d+)$/;
46
+ const SWEEP_LOCK = 'sweep.lock';
47
+
48
+ /** One process as `ps` lists it. */
49
+ export interface ProcessEntry {
50
+ readonly pid: number;
51
+ readonly ppid: number;
52
+ /** `ps` state; a leading `Z` is a zombie, which has exited. */
53
+ readonly stat: string;
54
+ readonly command: string;
55
+ }
56
+
57
+ /** Every process on the host, as `ps` lists it on macOS and Linux alike. */
58
+ export async function processTable(): Promise<ProcessEntry[]> {
59
+ const { stdout } = await run('ps', ['-A', '-o', 'pid=', '-o', 'ppid=', '-o', 'stat=', '-o', 'command='], {
60
+ maxBuffer: 64 * 1024 * 1024,
61
+ });
62
+ return stdout
63
+ .split('\n')
64
+ .filter((line) => line.trim() !== '')
65
+ .map((line) => {
66
+ const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s?(.*)$/.exec(line);
67
+ if (match === null) {
68
+ throw new Error(`Unable to parse ps line: ${line}`);
69
+ }
70
+ const [, pid, ppid, stat, command] = match;
71
+ return { pid: Number(pid), ppid: Number(ppid), stat: stat ?? '', command: command ?? '' };
72
+ });
73
+ }
74
+
75
+ /**
76
+ * The listed processes among `pids`, and every process descending from one, each once: a pid that
77
+ * descends from another in `pids` is not listed twice.
78
+ */
79
+ export function withDescendants(table: readonly ProcessEntry[], pids: readonly number[]): ProcessEntry[] {
80
+ const found = new Map<number, ProcessEntry>();
81
+ const pending = table.filter((entry) => pids.includes(entry.pid));
82
+ for (let entry = pending.pop(); entry !== undefined; entry = pending.pop()) {
83
+ if (found.has(entry.pid)) {
84
+ continue;
85
+ }
86
+ found.set(entry.pid, entry);
87
+ const parent = entry.pid;
88
+ pending.push(...table.filter((child) => child.ppid === parent));
89
+ }
90
+ return [...found.values()];
91
+ }
92
+
93
+ function errorCode(error: unknown): unknown {
94
+ return error instanceof Error && 'code' in error ? error.code : undefined;
95
+ }
96
+
97
+ /** Whether `pid` names a process, this user's or not. A zombie still answers. */
98
+ export function isRunning(pid: number): boolean {
99
+ try {
100
+ process.kill(pid, 0);
101
+ return true;
102
+ } catch (error) {
103
+ switch (errorCode(error)) {
104
+ case 'ESRCH':
105
+ return false;
106
+ case 'EPERM':
107
+ return true;
108
+ default:
109
+ throw error;
110
+ }
111
+ }
112
+ }
113
+
114
+ /** Signal `pid`; one that has already exited is not an error. */
115
+ export function terminate(pid: number, signal: NodeJS.Signals = 'SIGTERM'): void {
116
+ try {
117
+ process.kill(pid, signal);
118
+ } catch (error) {
119
+ if (errorCode(error) !== 'ESRCH') {
120
+ throw error;
121
+ }
122
+ }
123
+ }
124
+
125
+ /**
126
+ * Wait until every one of `processes` has exited. One still running
127
+ * `timeoutMs` later is an error naming it and `owner`.
128
+ */
129
+ export async function awaitExit(
130
+ processes: readonly ProcessEntry[],
131
+ owner: string,
132
+ timeoutMs = EXIT_TIMEOUT_MS,
133
+ ): Promise<void> {
134
+ const deadline = Date.now() + timeoutMs;
135
+ for (let waiting = processes.filter((entry) => isRunning(entry.pid)); waiting.length > 0; ) {
136
+ if (Date.now() > deadline) {
137
+ // A signal probe also answers for a zombie, which has already exited.
138
+ const live = new Set(
139
+ (await processTable()).filter((entry) => !entry.stat.startsWith('Z')).map((entry) => entry.pid),
140
+ );
141
+ const survivors = waiting.filter((entry) => live.has(entry.pid));
142
+ if (survivors.length === 0) {
143
+ return;
144
+ }
145
+ throw new Error(
146
+ `${owner}: ${survivors.map((entry) => `${entry.pid} (${entry.command})`).join(', ')} still running ${timeoutMs}ms after it was stopped`,
147
+ );
148
+ }
149
+ await sleep(50);
150
+ waiting = waiting.filter((entry) => isRunning(entry.pid));
151
+ }
152
+ }
153
+
154
+ /** Every process of this user whose working directory is `root` or lies beneath it, deleted or not. */
155
+ export async function pidsWorkingIn(root: string): Promise<number[]> {
156
+ const under = (cwd: string) => cwd === root || cwd.startsWith(`${root}/`);
157
+ switch (process.platform) {
158
+ case 'linux': {
159
+ const found: number[] = [];
160
+ for (const pid of (await readdir('/proc')).filter((name) => /^\d+$/.test(name))) {
161
+ const cwd = await readlink(`/proc/${pid}/cwd`).catch((error: unknown) => {
162
+ // Another user's process, or one that exited since the listing.
163
+ if (errorCode(error) === 'EACCES' || errorCode(error) === 'ENOENT') {
164
+ return null;
165
+ }
166
+ throw error;
167
+ });
168
+ if (cwd !== null && under(cwd.replace(/ \(deleted\)$/, ''))) {
169
+ found.push(Number(pid));
170
+ }
171
+ }
172
+ return found;
173
+ }
174
+ case 'darwin': {
175
+ // lsof keeps naming a working directory after it has been deleted. It
176
+ // exits 1 when a listed process vanished before it was read; what it
177
+ // printed for the rest is still the answer.
178
+ const fields = await run('/usr/sbin/lsof', ['-nP', '-a', '-d', 'cwd', '-u', String(userInfo().uid), '-Fpn'], {
179
+ maxBuffer: 64 * 1024 * 1024,
180
+ }).then(
181
+ ({ stdout }) => stdout,
182
+ (error: unknown) => {
183
+ if (error instanceof Error && 'code' in error && error.code === 1 && 'stdout' in error) {
184
+ return String(error.stdout);
185
+ }
186
+ throw error;
187
+ },
188
+ );
189
+ const found: number[] = [];
190
+ let pid = 0;
191
+ for (const line of fields.split('\n')) {
192
+ if (line.startsWith('p')) {
193
+ pid = Number(line.slice(1));
194
+ } else if (line.startsWith('n') && under(line.slice(1))) {
195
+ found.push(pid);
196
+ }
197
+ }
198
+ return found;
199
+ }
200
+ default:
201
+ throw new Error(`No working-directory scan for ${process.platform}`);
202
+ }
203
+ }
204
+
205
+ /**
206
+ * The Nx daemon `workspace` runs, the daemon first, then every process it
207
+ * started. Empty when the workspace records no daemon or the recorded one is
208
+ * gone. The record is `d/server-process.json` under the workspace's own
209
+ * `.nx/workspace-data`, where every fixture keeps its Nx state.
210
+ */
211
+ export async function nxDaemonProcesses(workspace: string): Promise<ProcessEntry[]> {
212
+ const record = join(workspace, '.nx', 'workspace-data', 'd', 'server-process.json');
213
+ const text = await readFile(record, 'utf8').catch((error: unknown) => {
214
+ if (errorCode(error) === 'ENOENT') {
215
+ return null;
216
+ }
217
+ throw error;
218
+ });
219
+ if (text === null) {
220
+ return [];
221
+ }
222
+ const parsed: unknown = JSON.parse(text);
223
+ if (
224
+ typeof parsed !== 'object' ||
225
+ parsed === null ||
226
+ !('processId' in parsed) ||
227
+ typeof parsed.processId !== 'number' ||
228
+ !Number.isSafeInteger(parsed.processId)
229
+ ) {
230
+ throw new Error(`Nx daemon record ${record} names no process id`);
231
+ }
232
+ return withDescendants(await processTable(), [parsed.processId]);
233
+ }
234
+
235
+ /**
236
+ * Release the Nx daemon `workspace` started and wait until the daemon and
237
+ * every process it ran have exited. `stop` runs `nx daemon --stop` against
238
+ * the workspace, in the environment that started it. Nx deletes the daemon's
239
+ * record before the daemon exits, so the record cannot say when the workspace
240
+ * is free to delete; the processes can. The daemon also leaves what it
241
+ * spawned to end on its own: plugin workers once they see it gone, the editor
242
+ * extension probe it starts at launch never. Those get SIGTERM with it, the
243
+ * ones it started while it was stopping included. A child that outlives the
244
+ * daemon is reparented to init and leaves the daemon's process tree, but it
245
+ * still works in the workspace, so the workspace census ends what is left.
246
+ * A missing record can mean startup has not published it yet: skip the
247
+ * daemon-stop command, but never skip the working-directory census.
248
+ */
249
+ export async function stopNxDaemon(workspace: string, stop: () => Promise<void>): Promise<void> {
250
+ const [daemon, ...before] = await nxDaemonProcesses(workspace);
251
+ if (daemon !== undefined) {
252
+ await stop();
253
+ const known = new Set([daemon.pid, ...before.map((entry) => entry.pid)]);
254
+ const after = withDescendants(await processTable(), [daemon.pid]).filter((entry) => !known.has(entry.pid));
255
+ const spawned = [...before, ...after];
256
+ for (const entry of spawned) {
257
+ terminate(entry.pid);
258
+ }
259
+ await awaitExit([daemon, ...spawned], `Nx daemon of ${workspace}`);
260
+ }
261
+ await endWorkspaceProcesses(workspace, `Nx processes of ${workspace}`);
262
+ }
263
+
264
+ /**
265
+ * End every process still working in `workspace`, round after round, until a
266
+ * census finds none. The daemon has exited by now, so a process can start
267
+ * another under the workspace only while it is alive, and a child started
268
+ * just before its parent was ended is in the next census. A zombie has
269
+ * exited already, and this process never ends itself.
270
+ */
271
+ async function endWorkspaceProcesses(workspace: string, owner: string): Promise<void> {
272
+ for (;;) {
273
+ const working = new Set(await pidsWorkingIn(workspace));
274
+ const leftovers = (await processTable()).filter(
275
+ (entry) => working.has(entry.pid) && entry.pid !== process.pid && !entry.stat.startsWith('Z'),
276
+ );
277
+ if (leftovers.length === 0) {
278
+ return;
279
+ }
280
+ for (const entry of leftovers) {
281
+ terminate(entry.pid);
282
+ }
283
+ await awaitExit(leftovers, owner);
284
+ }
285
+ }
286
+
287
+ /**
288
+ * The run this process holds in each suite directory, opened or still opening,
289
+ * by that directory's canonical path: one for each parent and suite, however
290
+ * the parent is spelled. Entries are kept for the life of the process, an open
291
+ * that failed included.
292
+ */
293
+ const runDirectories = new Map<string, Promise<string>>();
294
+
295
+ const RUN_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'] as const;
296
+
297
+ /** The handlers this process made for {@link RUN_SIGNALS}, by signal: none until it opens its first run. */
298
+ const runSignalHandlers = new Map<NodeJS.Signals, () => void>();
299
+
300
+ /** Reclaiming every run this process holds, begun by the first of {@link RUN_SIGNALS} it received. */
301
+ let retirement: Promise<void> | undefined;
302
+
303
+ /**
304
+ * A fresh fixture root for `suite`, owned by this process: a `prefix`-named
305
+ * directory (mode 0700) in this process's run directory under
306
+ * `parentDirectory`, `<parent>/smoothbricks-fixtures/<suite>/run-<pid>`. The
307
+ * caller always names the parent: the temp directory, or the directory of the
308
+ * volume the fixture has to lie on. The parent is resolved through every link,
309
+ * so the root is canonical (macOS puts the temp directory behind a /private
310
+ * symlink, and a daemon never sees an edit made under a root named through
311
+ * one) and a parent spelled two ways is one run. A process holds one run for
312
+ * each parent and suite, and the first root of a suite under a parent reclaims
313
+ * that suite's dead runs there first. Once a signal has this process
314
+ * reclaiming its runs, no root is made.
315
+ */
316
+ export async function ownedFixtureRoot(parentDirectory: string, suite: string, prefix: string): Promise<string> {
317
+ const suiteDirectory = join(await realpath(parentDirectory), FIXTURE_HOME, suite);
318
+ refuseWhileRetiring();
319
+ let opened = runDirectories.get(suiteDirectory);
320
+ if (opened === undefined) {
321
+ opened = openRun(suiteDirectory);
322
+ runDirectories.set(suiteDirectory, opened);
323
+ }
324
+ const directory = await opened;
325
+ refuseWhileRetiring();
326
+ return mkdtemp(join(directory, prefix));
327
+ }
328
+
329
+ async function openRun(suiteDirectory: string): Promise<string> {
330
+ await sweepSuite(suiteDirectory);
331
+ const directory = join(suiteDirectory, `run-${process.pid}`);
332
+ await mkdir(directory, { recursive: true });
333
+ ownRunSignals();
334
+ return directory;
335
+ }
336
+
337
+ /**
338
+ * Own the signals that end this process, once however many runs it holds. The
339
+ * first of them reclaims every run (`retireRuns`) before it takes its course. A
340
+ * handler for each run would let the first to finish re-raise the signal over
341
+ * the reclaim of the rest, and a signal repeated meanwhile would meet no handler
342
+ * and kill the process before any reclaim ended.
343
+ */
344
+ function ownRunSignals(): void {
345
+ if (runSignalHandlers.size > 0) {
346
+ return;
347
+ }
348
+ for (const signal of RUN_SIGNALS) {
349
+ const handler = (): void => {
350
+ retirement ??= retireRuns(signal);
351
+ };
352
+ runSignalHandlers.set(signal, handler);
353
+ process.on(signal, handler);
354
+ }
355
+ }
356
+
357
+ /**
358
+ * Reclaim every run this process holds at once, then let `signal`, the first it
359
+ * received, take its course: the handlers go and the process dies of it, as it
360
+ * would have without them. Every run is awaited, one still opening or one whose
361
+ * open failed included, and one failing cuts no other short; each failure is
362
+ * written to stderr with the suite directory of its run. A repeated signal
363
+ * meets a handler, not the default, so it waits for this and neither starts a
364
+ * second reclaim nor kills the first. That wait is the reclaim's own: for each
365
+ * run, after any sweep it was still opening with, the scans, two rounds of
366
+ * `SIGNALLED_GRACE_MS` (SIGTERM, then SIGKILL) for its processes, and the
367
+ * delete. A bounded test leg's SIGKILL ends it whatever it is.
368
+ */
369
+ async function retireRuns(signal: NodeJS.Signals): Promise<void> {
370
+ const runs = [...runDirectories];
371
+ // Inside the 10 s a bounded leg grants between SIGTERM and SIGKILL.
372
+ const outcomes = await Promise.allSettled(
373
+ runs.map(async ([, opened]) => reclaimRun(await opened, 'signalled fixture run', SIGNALLED_GRACE_MS)),
374
+ );
375
+ for (const [index, outcome] of outcomes.entries()) {
376
+ if (outcome.status === 'rejected') {
377
+ const reason = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
378
+ process.stderr.write(`could not reclaim this process's run in ${runs[index][0]}: ${reason}\n`);
379
+ }
380
+ }
381
+ for (const [name, handler] of runSignalHandlers) {
382
+ process.removeListener(name, handler);
383
+ }
384
+ process.kill(process.pid, signal);
385
+ }
386
+
387
+ function refuseWhileRetiring(): void {
388
+ if (retirement !== undefined) {
389
+ throw new Error('no fixture root is made: a signal has this process reclaiming the fixture runs it owns');
390
+ }
391
+ }
392
+
393
+ /**
394
+ * Stop every process working in a run of `suite` under `parentDirectory` whose
395
+ * owner is gone, then delete the run, and return the suite's directory there.
396
+ * The first fixture root of a suite under a parent in a process does this; a
397
+ * test that just watched a fixture-owning process die may too. An owner's pid
398
+ * reused by an unrelated process makes its run look alive; it is reclaimed once
399
+ * that process is gone too, never early.
400
+ */
401
+ export async function reclaimDeadFixtureRuns(parentDirectory: string, suite: string): Promise<string> {
402
+ const suiteDirectory = join(await realpath(parentDirectory), FIXTURE_HOME, suite);
403
+ await sweepSuite(suiteDirectory);
404
+ return suiteDirectory;
405
+ }
406
+
407
+ async function sweepSuite(suiteDirectory: string): Promise<void> {
408
+ await mkdir(suiteDirectory, { recursive: true });
409
+ await reclaimDeadRuns(suiteDirectory);
410
+ }
411
+
412
+ async function reclaimDeadRuns(suiteDirectory: string): Promise<void> {
413
+ const dead = (await readdir(suiteDirectory)).flatMap((name) => {
414
+ const owner = RUN_NAME.exec(name)?.[1];
415
+ if (owner === undefined) {
416
+ return [];
417
+ }
418
+ const pid = Number(owner);
419
+ return pid !== process.pid && !isRunning(pid) ? [join(suiteDirectory, name)] : [];
420
+ });
421
+ if (dead.length === 0) {
422
+ return;
423
+ }
424
+ const lock = await takeSweepLock(suiteDirectory);
425
+ if (lock === null) {
426
+ // Another process of the suite is reclaiming them right now.
427
+ return;
428
+ }
429
+ try {
430
+ for (const directory of dead) {
431
+ await reclaimRun(directory, 'dead fixture run');
432
+ }
433
+ } finally {
434
+ await rm(lock, { force: true });
435
+ }
436
+ }
437
+
438
+ async function reclaimRun(directory: string, owner: string, graceMs = EXIT_TIMEOUT_MS): Promise<void> {
439
+ const roots = await readdir(directory).catch((error: unknown) => {
440
+ if (errorCode(error) === 'ENOENT') {
441
+ return null;
442
+ }
443
+ throw error;
444
+ });
445
+ if (roots === null) {
446
+ return;
447
+ }
448
+ // A fixture deletes its root only once nothing runs in it, so an emptied
449
+ // run holds no process and needs no scan.
450
+ if (roots.length > 0) {
451
+ const working = await pidsWorkingIn(directory);
452
+ const processes = (await processTable()).filter((entry) => working.includes(entry.pid));
453
+ if (processes.length > 0) {
454
+ process.stderr.write(
455
+ `reclaiming ${owner} ${directory}: ${processes.map((entry) => `${entry.pid} (${entry.command})`).join(', ')}\n`,
456
+ );
457
+ for (const entry of processes) {
458
+ terminate(entry.pid);
459
+ }
460
+ try {
461
+ await awaitExit(processes, `processes of ${owner} ${directory}`, graceMs);
462
+ } catch (error) {
463
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}; sending SIGKILL\n`);
464
+ for (const entry of processes) {
465
+ terminate(entry.pid, 'SIGKILL');
466
+ }
467
+ await awaitExit(processes, `processes of ${owner} ${directory} after SIGKILL`, graceMs);
468
+ }
469
+ }
470
+ }
471
+ // A killed fixture may never have reached its own alias retirement, and its
472
+ // workspace may be gone. The alias is its own record: one whose target is the
473
+ // socket state of a workspace in this reclaimed run, and whose name is that
474
+ // workspace's, is this sweep's to retire. Every other entry is left alone.
475
+ const { directory: namespace } = socketNamespace();
476
+ for (const entry of await readdir(namespace, { withFileTypes: true })) {
477
+ if (!entry.isSymbolicLink()) continue;
478
+ const target = await readlink(join(namespace, entry.name)).catch((error: unknown) => {
479
+ if (errorCode(error) === 'ENOENT') return undefined;
480
+ throw error;
481
+ });
482
+ if (target === undefined) continue;
483
+ const workspace = dirname(dirname(target));
484
+ if (
485
+ workspace.startsWith(`${directory}${sep}`) &&
486
+ target === fixtureSocketTarget(workspace) &&
487
+ entry.name === fixtureSocketAliasName(workspace)
488
+ ) {
489
+ await retireFixtureSocketDirectory(workspace);
490
+ }
491
+ }
492
+ await rm(directory, { recursive: true, force: true });
493
+ }
494
+
495
+ /**
496
+ * The suite's sweep lock, or null while a live process holds it. A lock left
497
+ * by a process that died mid-sweep is taken over. Reclaiming is idempotent, so
498
+ * the lock only keeps concurrent test processes from scanning the same runs.
499
+ */
500
+ async function takeSweepLock(suiteDirectory: string): Promise<string | null> {
501
+ const lock = join(suiteDirectory, SWEEP_LOCK);
502
+ for (let attempt = 0; attempt < 2; attempt += 1) {
503
+ try {
504
+ await writeFile(lock, `${process.pid}\n`, { flag: 'wx' });
505
+ return lock;
506
+ } catch (error) {
507
+ if (errorCode(error) !== 'EEXIST') {
508
+ throw error;
509
+ }
510
+ }
511
+ const holder = Number(
512
+ (
513
+ await readFile(lock, 'utf8').catch((error: unknown) => {
514
+ if (errorCode(error) === 'ENOENT') {
515
+ return '';
516
+ }
517
+ throw error;
518
+ })
519
+ ).trim(),
520
+ );
521
+ if (Number.isSafeInteger(holder) && holder > 0 && isRunning(holder)) {
522
+ return null;
523
+ }
524
+ await rm(lock, { force: true });
525
+ }
526
+ return null;
527
+ }
528
+
529
+ /**
530
+ * The longest path a fixture binds a Unix socket at: the stricter of Nx's own
531
+ * limit (`assertValidSocketPath` refuses over 95 characters) and the kernel's
532
+ * (macOS's `sun_path` holds 104 bytes, the terminating NUL included), counted
533
+ * in UTF-8 bytes, which is what the kernel limits.
534
+ */
535
+ const SOCKET_PATH_BYTES = 95;
536
+
537
+ /**
538
+ * The longest socket Nx binds in a configured socket directory: an isolated
539
+ * plugin worker's `p<pid>-<counter>-<8 hex>.sock` (`getPluginSocketFileName`;
540
+ * with a configured directory `getPluginSocketDir` is the daemon's own), which
541
+ * outgrows the daemon's `d.sock` and a forked task's `fp<pid>-<n>.sock`. macOS
542
+ * pids stop at 99999, Linux's have seven digits; two base-36 digits count 1295
543
+ * workers.
544
+ */
545
+ export const NX_LONGEST_SOCKET_NAME = `p${'9'.repeat(process.platform === 'darwin' ? 5 : 7)}-zz-ffffffff.sock`;
546
+
547
+ const RUNTIME_LINK_ENV = 'COWSHED_RUNTIME_LINK';
548
+ const PORT_BASE_ENV = 'COWSHED_PORT_BASE';
549
+ const PORT_BLOCK_SIZE_ENV = 'COWSHED_PORT_BLOCK_SIZE';
550
+ const MAX_PORT = 65_535;
551
+ const DECIMAL = /^[0-9]+$/;
552
+
553
+ /** Where a fixture's sockets are made, and the candidates passed over on the way there. */
554
+ export interface SocketNamespace {
555
+ readonly directory: string;
556
+ /** Each environment root not used, and why: carried into every refusal made in this namespace. */
557
+ readonly passedOver: readonly string[];
558
+ }
559
+
560
+ /**
561
+ * The directory a fixture's sockets are made in: a short root this process's
562
+ * own environment supplies for the checkout it runs in. In order: the parent
563
+ * of `NX_SOCKET_DIR`, which for a Cowshed job is the workspace's short runtime
564
+ * link (its Nx socket directory is `nx` below it); `COWSHED_RUNTIME_LINK`,
565
+ * that link; else the temp directory. Never `NX_SOCKET_DIR` itself: Nx deletes
566
+ * that directory, recursively and whatever else is in it, whenever its daemon
567
+ * stops, so a fixture's sockets live beside it. The sandbox admits Unix sockets
568
+ * under the link by its literal path, and under the temp directory only for a
569
+ * job's own `TMPDIR`. Spelled as the environment gives it and never resolved,
570
+ * since the physical path is too long for a socket.
571
+ *
572
+ * As `nx-socket-dir.sh` does, a shell's variable is trusted only when it is
573
+ * this checkout's. The public finder names the checkout from the working
574
+ * directory; an `NX_SOCKET_DIR` also needs a matching `NX_WORKSPACE_ROOT_PATH`.
575
+ * The link must resolve to that checkout's `.cowshed/run`, even when a test
576
+ * preload has removed the inherited Nx variables. Unproven candidates are
577
+ * passed over with their resolution or permission failure, so the fallback
578
+ * directory, or the length refusal it leads to, names what it fell from. One
579
+ * that is this checkout's but is not an existing directory of this user is an
580
+ * error naming it.
581
+ */
582
+ export function socketNamespace(): SocketNamespace {
583
+ const passedOver: string[] = [];
584
+ const socketDirectory = environmentValue('NX_SOCKET_DIR');
585
+ const link = environmentValue(RUNTIME_LINK_ENV);
586
+ if (socketDirectory !== undefined || link !== undefined) {
587
+ const checkout = checkoutRoot();
588
+ if (checkout.kind === 'unresolved') {
589
+ passedOver.push(`NX_SOCKET_DIR and ${RUNTIME_LINK_ENV} cannot be tied to a checkout: ${checkout.why}`);
590
+ } else {
591
+ if (socketDirectory !== undefined) {
592
+ const named = environmentValue('NX_WORKSPACE_ROOT_PATH');
593
+ const binding: Resolution =
594
+ named === undefined ? { kind: 'unresolved', why: 'NX_WORKSPACE_ROOT_PATH is not set' } : resolution(named);
595
+ if (binding.kind === 'resolved' && binding.path === checkout.path) {
596
+ const leaf = resolution(socketDirectory);
597
+ if (leaf.kind === 'resolved' && isWithin(leaf.path, checkout.path)) {
598
+ const source = `the parent of NX_SOCKET_DIR=${socketDirectory}`;
599
+ return { directory: ownedDirectory(source, dirname(socketDirectory), passedOver, 'private'), passedOver };
600
+ }
601
+ passedOver.push(
602
+ `NX_SOCKET_DIR=${socketDirectory} ${describeResolution(leaf)}, not inside the checkout ${checkout.path}`,
603
+ );
604
+ } else {
605
+ passedOver.push(
606
+ `NX_SOCKET_DIR=${socketDirectory} has no current checkout binding: ${describeResolution(binding)}`,
607
+ );
608
+ }
609
+ }
610
+ if (link !== undefined) {
611
+ const run = join(checkout.path, '.cowshed', 'run');
612
+ const runResolved = resolution(run);
613
+ const linked = resolution(link);
614
+ if (runResolved.kind === 'resolved' && linked.kind === 'resolved' && linked.path === runResolved.path) {
615
+ return { directory: ownedDirectory(RUNTIME_LINK_ENV, link, passedOver, 'private'), passedOver };
616
+ }
617
+ passedOver.push(
618
+ `${RUNTIME_LINK_ENV}=${link} ${describeResolution(linked)}, and the checkout's ${run} ${describeResolution(runResolved)}`,
619
+ );
620
+ }
621
+ }
622
+ }
623
+ return { directory: ownedDirectory('the temp directory', tmpdir(), passedOver, 'process-temp'), passedOver };
624
+ }
625
+
626
+ /** The variable's value, or undefined when it is unset or empty. */
627
+ function environmentValue(name: string): string | undefined {
628
+ const value = process.env[name];
629
+ return value === undefined || value === '' ? undefined : value;
630
+ }
631
+
632
+ type Resolution =
633
+ | { readonly kind: 'resolved'; readonly path: string }
634
+ | { readonly kind: 'unresolved'; readonly why: string };
635
+
636
+ function describeResolution(resolved: Resolution): string {
637
+ return resolved.kind === 'resolved' ? `resolves to ${resolved.path}` : `cannot be resolved (${resolved.why})`;
638
+ }
639
+
640
+ /** The current checkout, read from its marker rather than an inherited Nx override. */
641
+ function checkoutRoot(): Resolution {
642
+ const here = resolution(process.cwd());
643
+ if (here.kind === 'unresolved') {
644
+ return { kind: 'unresolved', why: `the working directory cannot be resolved (${here.why})` };
645
+ }
646
+ const root = findNxWorkspaceRoot(here.path);
647
+ return root === null
648
+ ? { kind: 'unresolved', why: `no nx.json at or above the working directory ${here.path}` }
649
+ : resolution(root);
650
+ }
651
+
652
+ /** `path` resolved through every link, or the errno of a path that does not exist or may not be looked at. */
653
+ function resolution(path: string): Resolution {
654
+ try {
655
+ return { kind: 'resolved', path: realpathSync(path) };
656
+ } catch (error) {
657
+ const code = errorCode(error);
658
+ if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EACCES' || code === 'EPERM') {
659
+ return { kind: 'unresolved', why: `${code} on ${path}` };
660
+ }
661
+ throw error;
662
+ }
663
+ }
664
+
665
+ /** Whether the resolved `path` is `root` or lies beneath it. */
666
+ function isWithin(path: string, root: string): boolean {
667
+ return path === root || path.startsWith(`${root}${sep}`);
668
+ }
669
+
670
+ function ownedDirectory(
671
+ source: string,
672
+ directory: string,
673
+ passedOver: readonly string[],
674
+ ownership: 'private' | 'process-temp',
675
+ ): string {
676
+ const stat = statSync(directory, { throwIfNoEntry: false });
677
+ const user = process.getuid?.();
678
+ const owned = user === undefined || stat?.uid === user;
679
+ const publicTemp = ownership === 'process-temp' && stat?.uid === 0 && (stat.mode & 0o7777) === 0o1777;
680
+ if (!isAbsolute(directory) || stat === undefined || !stat.isDirectory() || (!owned && !publicTemp)) {
681
+ throw new Error(
682
+ `${source} (${directory}, uid=${stat?.uid}, mode=${stat?.mode.toString(8)}) is not an existing absolute ` +
683
+ 'user-owned directory or an admitted sticky public temp directory, so no fixture socket can be ' +
684
+ `made under it${passedOver.length === 0 ? '' : `; passed over: ${passedOver.join('; ')}`}`,
685
+ );
686
+ }
687
+ return directory;
688
+ }
689
+
690
+ /**
691
+ * `path`, or an error naming it, its length and the namespace it was made in
692
+ * (with what that namespace passed over) when Nx and the kernel would refuse
693
+ * to bind a socket there.
694
+ */
695
+ export function assertSocketPath(path: string, namespace: SocketNamespace): string {
696
+ const bytes = Buffer.byteLength(path, 'utf8');
697
+ if (bytes > SOCKET_PATH_BYTES) {
698
+ const { directory, passedOver } = namespace;
699
+ throw new Error(
700
+ `the socket path ${path} is ${bytes} UTF-8 bytes, over the ${SOCKET_PATH_BYTES} a Unix socket may have; ` +
701
+ `the socket namespace ${directory} leaves too little room` +
702
+ `${passedOver.length === 0 ? '' : `; passed over: ${passedOver.join('; ')}`}`,
703
+ );
704
+ }
705
+ return path;
706
+ }
707
+
708
+ /**
709
+ * A fresh directory, mode 0700 and named `prefix` plus six random characters,
710
+ * in {@link socketNamespace}: the one owner of the sockets a fixture makes
711
+ * there, so the fixture removes the directory and nothing else. `longestSocketName`
712
+ * is the longest socket it will hold, and the call fails before creating
713
+ * anything when that socket's path would be too long to bind.
714
+ */
715
+ export async function ownedSocketDirectory(prefix: string, longestSocketName: string): Promise<string> {
716
+ const namespace = socketNamespace();
717
+ assertSocketPath(join(namespace.directory, `${prefix}XXXXXX`, longestSocketName), namespace);
718
+ return mkdtemp(join(namespace.directory, prefix));
719
+ }
720
+
721
+ /** The alias's name: a digest of the workspace's physical path, which is the whole of its identity. */
722
+ function fixtureSocketAliasName(workspace: string): string {
723
+ return `nx-${createHash('sha256').update(workspace).digest('hex').slice(0, 16)}`;
724
+ }
725
+
726
+ /** The real directory below the workspace that its alias names. */
727
+ function fixtureSocketTarget(workspace: string): string {
728
+ return join(workspace, '.nx', 'sockets');
729
+ }
730
+
731
+ /** A colliding or retargeted alias is not this fixture's and must not be used or removed. */
732
+ function assertFixtureSocketAlias(alias: string, target: string): void {
733
+ const entry = lstatSync(alias);
734
+ if (!entry.isSymbolicLink() || readlinkSync(alias) !== target) {
735
+ throw new Error(`fixture socket alias ${alias} does not name its owned target ${target}`);
736
+ }
737
+ }
738
+
739
+ /**
740
+ * The fixture's `NX_SOCKET_DIR`, named and nothing more: the real `nx` leaf
741
+ * below the short parent alias {@link publishFixtureSocketDirectory} makes in
742
+ * the job's admitted namespace. `workspace` is the physical path that
743
+ * publication was given; the alias is named for a hash of it, so every client,
744
+ * daemon stop and retirement of the workspace names the same leaf, and no two
745
+ * fixtures share one. A long private `TMPDIR` affects neither the bind path nor
746
+ * workspace ownership. A namespace too small for Nx's longest socket name is
747
+ * refused here, so before any publication.
748
+ */
749
+ export function fixtureSocketDirectory(workspace: string): string {
750
+ const namespace = socketNamespace();
751
+ const directory = join(namespace.directory, fixtureSocketAliasName(workspace), 'nx');
752
+ assertSocketPath(join(directory, NX_LONGEST_SOCKET_NAME), namespace);
753
+ return directory;
754
+ }
755
+
756
+ /**
757
+ * Publish the fixture's short socket alias and return its
758
+ * {@link fixtureSocketDirectory}. The workspace must be a physical directory in
759
+ * a fixture run this process holds ({@link ownedFixtureRoot}): then the run's
760
+ * sweep reclaims the alias even if this process dies before its
761
+ * {@link retireFixtureSocketDirectory}. The alias points at the workspace's own
762
+ * `.nx/sockets`, made mode 0700; a symlinked `.nx` or `.nx/sockets` is refused
763
+ * before anything is written through it. Nx makes the `nx` leaf itself.
764
+ */
765
+ export async function publishFixtureSocketDirectory(workspace: string): Promise<string> {
766
+ refuseWhileRetiring();
767
+ const runs = await Promise.allSettled(runDirectories.values());
768
+ const owned = runs.some((run) => run.status === 'fulfilled' && workspace.startsWith(`${run.value}${sep}`));
769
+ if (!owned || (await realpath(workspace)) !== workspace) {
770
+ throw new Error(
771
+ `no socket alias is published for ${workspace}: it is not a physical workspace in a fixture run this ` +
772
+ 'process owns, so no sweep could reclaim its alias',
773
+ );
774
+ }
775
+ const directory = fixtureSocketDirectory(workspace);
776
+ const alias = dirname(directory);
777
+ const target = fixtureSocketTarget(workspace);
778
+ for (const state of [dirname(target), target]) {
779
+ try {
780
+ await mkdir(state, { mode: 0o700 });
781
+ } catch (error) {
782
+ if (errorCode(error) !== 'EEXIST') throw error;
783
+ }
784
+ if (!(await lstat(state)).isDirectory()) {
785
+ throw new Error(`fixture socket target ${state} is not a real directory in its physical workspace`);
786
+ }
787
+ }
788
+ try {
789
+ await symlink(target, alias, 'dir');
790
+ } catch (error) {
791
+ if (errorCode(error) !== 'EEXIST') throw error;
792
+ }
793
+ assertFixtureSocketAlias(alias, target);
794
+ return directory;
795
+ }
796
+
797
+ /**
798
+ * A second real leaf, `slot`, beside the `nx` one below the workspace's
799
+ * published alias, for tests whose subject is two daemon socket directories.
800
+ * A slot name is shorter than `nx`, so it fits wherever the published leaf
801
+ * does. An existing slot is an error. Its caller stops the daemon bound in it
802
+ * before removing it.
803
+ */
804
+ export async function ownedWorkspaceSocketDirectory(workspace: string, slot: 'a' | 'b'): Promise<string> {
805
+ const alias = dirname(fixtureSocketDirectory(workspace));
806
+ assertFixtureSocketAlias(alias, fixtureSocketTarget(workspace));
807
+ const directory = join(alias, slot);
808
+ await mkdir(directory, { mode: 0o700 });
809
+ return directory;
810
+ }
811
+
812
+ /**
813
+ * After the daemon exits, unlink only this workspace's verified parent alias,
814
+ * not its target. Named from the workspace's path alone, so a workspace already
815
+ * deleted retires too. No alias is not an error; any other entry under its name
816
+ * is refused and left in place.
817
+ */
818
+ export async function retireFixtureSocketDirectory(workspace: string): Promise<void> {
819
+ const alias = join(socketNamespace().directory, fixtureSocketAliasName(workspace));
820
+ try {
821
+ assertFixtureSocketAlias(alias, fixtureSocketTarget(workspace));
822
+ } catch (error) {
823
+ if (errorCode(error) === 'ENOENT') return;
824
+ throw error;
825
+ }
826
+ await rm(alias);
827
+ }
828
+
829
+ /** The port block a Cowshed job's environment names, or why it names none a listener can use. */
830
+ type PortBlockEnvironment =
831
+ /** Outside Cowshed, or on Linux: no block, so a listener binds port 0 as usual. */
832
+ | { readonly kind: 'none' }
833
+ /** The gateway listens on `base`; service ports are `base+1 … base+size-1`. */
834
+ | { readonly kind: 'block'; readonly base: number; readonly size: number }
835
+ | { readonly kind: 'broken'; readonly reason: string };
836
+
837
+ /**
838
+ * The block `env` (`COWSHED_PORT_BASE`, `COWSHED_PORT_BLOCK_SIZE`) names. A
839
+ * size without a base, a base without a size (never assumed), a value that is
840
+ * not a decimal number, a size that is not a power of two of at least two, a
841
+ * base not aligned to it, or a block outside the TCP ports 1–65535 is a broken
842
+ * environment, refused rather than guessed around (04_sandbox.md).
843
+ */
844
+ function portBlockEnvironment(env: NodeJS.ProcessEnv): PortBlockEnvironment {
845
+ const baseText = env[PORT_BASE_ENV];
846
+ const sizeText = env[PORT_BLOCK_SIZE_ENV];
847
+ if (baseText === undefined && sizeText === undefined) {
848
+ return { kind: 'none' };
849
+ }
850
+ if (baseText === undefined) {
851
+ return { kind: 'broken', reason: `${PORT_BLOCK_SIZE_ENV}=${sizeText} is set without ${PORT_BASE_ENV}` };
852
+ }
853
+ if (sizeText === undefined) {
854
+ return { kind: 'broken', reason: `${PORT_BASE_ENV}=${baseText} is set without ${PORT_BLOCK_SIZE_ENV}` };
855
+ }
856
+ if (!DECIMAL.test(baseText) || !DECIMAL.test(sizeText)) {
857
+ return {
858
+ kind: 'broken',
859
+ reason: `${PORT_BASE_ENV}=${JSON.stringify(baseText)} and ${PORT_BLOCK_SIZE_ENV}=${JSON.stringify(sizeText)} are not both decimal numbers`,
860
+ };
861
+ }
862
+ const base = Number(baseText);
863
+ const size = Number(sizeText);
864
+ if (!Number.isSafeInteger(size) || size < 2 || (size & (size - 1)) !== 0) {
865
+ return {
866
+ kind: 'broken',
867
+ reason: `${PORT_BLOCK_SIZE_ENV}=${sizeText} is not a power of two of at least 2`,
868
+ };
869
+ }
870
+ if (!Number.isSafeInteger(base) || base < 1 || base % size !== 0) {
871
+ return {
872
+ kind: 'broken',
873
+ reason: `${PORT_BASE_ENV}=${baseText} is not a positive multiple of ${PORT_BLOCK_SIZE_ENV}=${sizeText}`,
874
+ };
875
+ }
876
+ if (base + size - 1 > MAX_PORT) {
877
+ return {
878
+ kind: 'broken',
879
+ reason: `the block ${base}+${size} (${PORT_BASE_ENV}, ${PORT_BLOCK_SIZE_ENV}) runs past TCP port ${MAX_PORT}`,
880
+ };
881
+ }
882
+ return { kind: 'block', base, size };
883
+ }
884
+
885
+ /**
886
+ * Bind a real listener where a Cowshed job's other processes can connect to
887
+ * it. In a block, `bind` is called with each candidate `base+1 … base+size-1`,
888
+ * lowest first (a long-lived test listener scans from the bottom), and the
889
+ * first that binds is kept: only a real bind claims a port, so nothing probes
890
+ * and closes. Only `EADDRINUSE` (by `code`) moves on to the next candidate;
891
+ * any other failure is that bind's own and surfaces as is, and so does the
892
+ * last candidate's, so an exhausted block reports `EADDRINUSE`, never a silent
893
+ * port 0. Outside a block `bind` is called with 0, and the kernel picks.
894
+ *
895
+ * `bind` creates and binds one listener per call and returns it, and a failed
896
+ * bind leaves nothing behind. It may throw (`Bun.serve` does) or reject (a
897
+ * Node `net` server reports a failed `listen` as an `error` event, which the
898
+ * caller turns into a rejection). The listener the winning call returns is the
899
+ * caller's to keep and close.
900
+ */
901
+ export async function bindListener<T>(bind: (port: number) => T | Promise<T>): Promise<T> {
902
+ const block = portBlockEnvironment(process.env);
903
+ switch (block.kind) {
904
+ case 'none':
905
+ return bind(0);
906
+ case 'broken':
907
+ throw new Error(`a listener cannot bind in a broken Cowshed port-block environment: ${block.reason}`);
908
+ case 'block': {
909
+ const last = block.base + block.size - 1;
910
+ for (let port = block.base + 1; port < last; port += 1) {
911
+ try {
912
+ return await bind(port);
913
+ } catch (error) {
914
+ if (errorCode(error) !== 'EADDRINUSE') {
915
+ throw error;
916
+ }
917
+ }
918
+ }
919
+ return bind(last);
920
+ }
921
+ }
922
+ }