@agent-watch-ai/edge 0.2.5

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 (364) hide show
  1. package/CHANGELOG.md +251 -0
  2. package/LICENSE +21 -0
  3. package/README.md +168 -0
  4. package/dist/billing/billing-mode.d.ts +16 -0
  5. package/dist/billing/billing-mode.js +139 -0
  6. package/dist/billing/constants/billing.constants.d.ts +37 -0
  7. package/dist/billing/constants/billing.constants.js +38 -0
  8. package/dist/billing/index.d.ts +6 -0
  9. package/dist/billing/index.js +6 -0
  10. package/dist/cli/args.d.ts +29 -0
  11. package/dist/cli/args.js +61 -0
  12. package/dist/cli/constants/cli.constants.d.ts +60 -0
  13. package/dist/cli/constants/cli.constants.js +60 -0
  14. package/dist/cli/context.d.ts +51 -0
  15. package/dist/cli/context.js +108 -0
  16. package/dist/cli/doctor.d.ts +15 -0
  17. package/dist/cli/doctor.js +416 -0
  18. package/dist/cli/hook.d.ts +20 -0
  19. package/dist/cli/hook.js +166 -0
  20. package/dist/cli/index.d.ts +13 -0
  21. package/dist/cli/index.js +8 -0
  22. package/dist/cli/misc.d.ts +31 -0
  23. package/dist/cli/misc.js +63 -0
  24. package/dist/cli/setup.d.ts +32 -0
  25. package/dist/cli/setup.js +298 -0
  26. package/dist/cli/status.d.ts +11 -0
  27. package/dist/cli/status.js +174 -0
  28. package/dist/cli/types/cli.types.d.ts +69 -0
  29. package/dist/cli/types/cli.types.js +1 -0
  30. package/dist/cli/ui.d.ts +41 -0
  31. package/dist/cli/ui.js +78 -0
  32. package/dist/cli/uninstall.d.ts +13 -0
  33. package/dist/cli/uninstall.js +83 -0
  34. package/dist/cli.d.ts +2 -0
  35. package/dist/cli.js +124 -0
  36. package/dist/config/config-store.d.ts +29 -0
  37. package/dist/config/config-store.js +75 -0
  38. package/dist/config/config.d.ts +73 -0
  39. package/dist/config/config.js +115 -0
  40. package/dist/config/constants/config.constants.d.ts +62 -0
  41. package/dist/config/constants/config.constants.js +70 -0
  42. package/dist/config/index.d.ts +10 -0
  43. package/dist/config/index.js +5 -0
  44. package/dist/config/repo-config.d.ts +37 -0
  45. package/dist/config/repo-config.js +178 -0
  46. package/dist/config/schemas/config.schema.d.ts +409 -0
  47. package/dist/config/schemas/config.schema.js +97 -0
  48. package/dist/config/types/config.types.d.ts +33 -0
  49. package/dist/config/types/config.types.js +1 -0
  50. package/dist/core/async.d.ts +20 -0
  51. package/dist/core/async.js +32 -0
  52. package/dist/core/constants/core.constants.d.ts +18 -0
  53. package/dist/core/constants/core.constants.js +18 -0
  54. package/dist/core/env.d.ts +12 -0
  55. package/dist/core/env.js +20 -0
  56. package/dist/core/index.d.ts +13 -0
  57. package/dist/core/index.js +8 -0
  58. package/dist/core/logger.d.ts +27 -0
  59. package/dist/core/logger.js +82 -0
  60. package/dist/core/number.d.ts +33 -0
  61. package/dist/core/number.js +47 -0
  62. package/dist/core/object.d.ts +78 -0
  63. package/dist/core/object.js +127 -0
  64. package/dist/core/pipe.d.ts +55 -0
  65. package/dist/core/pipe.js +81 -0
  66. package/dist/core/types/core.types.d.ts +54 -0
  67. package/dist/core/types/core.types.js +4 -0
  68. package/dist/core/version.d.ts +19 -0
  69. package/dist/core/version.js +35 -0
  70. package/dist/core/which.d.ts +13 -0
  71. package/dist/core/which.js +57 -0
  72. package/dist/enforcement/constants/enforcement.constants.d.ts +23 -0
  73. package/dist/enforcement/constants/enforcement.constants.js +22 -0
  74. package/dist/enforcement/decision-cache.d.ts +57 -0
  75. package/dist/enforcement/decision-cache.js +138 -0
  76. package/dist/enforcement/decision-client.d.ts +14 -0
  77. package/dist/enforcement/decision-client.js +84 -0
  78. package/dist/enforcement/enforcement.d.ts +17 -0
  79. package/dist/enforcement/enforcement.js +90 -0
  80. package/dist/enforcement/index.d.ts +11 -0
  81. package/dist/enforcement/index.js +10 -0
  82. package/dist/enforcement/schemas/enforcement.schema.d.ts +30 -0
  83. package/dist/enforcement/schemas/enforcement.schema.js +36 -0
  84. package/dist/enforcement/types/enforcement.types.d.ts +59 -0
  85. package/dist/enforcement/types/enforcement.types.js +1 -0
  86. package/dist/enrollment/constants/enrollment.constants.d.ts +6 -0
  87. package/dist/enrollment/constants/enrollment.constants.js +6 -0
  88. package/dist/enrollment/enrollment-provider.d.ts +5 -0
  89. package/dist/enrollment/enrollment-provider.js +1 -0
  90. package/dist/enrollment/index.d.ts +7 -0
  91. package/dist/enrollment/index.js +1 -0
  92. package/dist/enrollment/manual-enrollment.d.ts +32 -0
  93. package/dist/enrollment/manual-enrollment.js +72 -0
  94. package/dist/enrollment/types/enrollment.types.d.ts +25 -0
  95. package/dist/enrollment/types/enrollment.types.js +1 -0
  96. package/dist/events/canonical-event.d.ts +10 -0
  97. package/dist/events/canonical-event.js +9 -0
  98. package/dist/events/constants/enrich.constants.d.ts +14 -0
  99. package/dist/events/constants/enrich.constants.js +15 -0
  100. package/dist/events/constants/events.constants.d.ts +35 -0
  101. package/dist/events/constants/events.constants.js +57 -0
  102. package/dist/events/enrich.d.ts +16 -0
  103. package/dist/events/enrich.js +226 -0
  104. package/dist/events/event-id.d.ts +32 -0
  105. package/dist/events/event-id.js +49 -0
  106. package/dist/events/index.d.ts +14 -0
  107. package/dist/events/index.js +5 -0
  108. package/dist/events/llm-call.d.ts +14 -0
  109. package/dist/events/llm-call.js +84 -0
  110. package/dist/events/product-event.d.ts +39 -0
  111. package/dist/events/product-event.js +19 -0
  112. package/dist/events/types/enrich.types.d.ts +25 -0
  113. package/dist/events/types/enrich.types.js +1 -0
  114. package/dist/events/types/events.types.d.ts +112 -0
  115. package/dist/events/types/events.types.js +1 -0
  116. package/dist/events/types/llm-call.types.d.ts +79 -0
  117. package/dist/events/types/llm-call.types.js +1 -0
  118. package/dist/events/types/repo-snapshot.types.d.ts +32 -0
  119. package/dist/events/types/repo-snapshot.types.js +1 -0
  120. package/dist/feature/constants/feature.constants.d.ts +10 -0
  121. package/dist/feature/constants/feature.constants.js +10 -0
  122. package/dist/feature/index.d.ts +6 -0
  123. package/dist/feature/index.js +6 -0
  124. package/dist/feature/ticket-candidates.d.ts +13 -0
  125. package/dist/feature/ticket-candidates.js +26 -0
  126. package/dist/git/constants/git.constants.d.ts +84 -0
  127. package/dist/git/constants/git.constants.js +113 -0
  128. package/dist/git/git-context.d.ts +52 -0
  129. package/dist/git/git-context.js +226 -0
  130. package/dist/git/index.d.ts +9 -0
  131. package/dist/git/index.js +3 -0
  132. package/dist/git/remote-sanitize.d.ts +26 -0
  133. package/dist/git/remote-sanitize.js +92 -0
  134. package/dist/git/repo-snapshot.d.ts +40 -0
  135. package/dist/git/repo-snapshot.js +95 -0
  136. package/dist/git/types/git.types.d.ts +36 -0
  137. package/dist/git/types/git.types.js +1 -0
  138. package/dist/git/types/snapshot.types.d.ts +25 -0
  139. package/dist/git/types/snapshot.types.js +1 -0
  140. package/dist/otlp/constants/otlp.constants.d.ts +84 -0
  141. package/dist/otlp/constants/otlp.constants.js +99 -0
  142. package/dist/otlp/http.d.ts +24 -0
  143. package/dist/otlp/http.js +37 -0
  144. package/dist/otlp/index.d.ts +9 -0
  145. package/dist/otlp/index.js +3 -0
  146. package/dist/otlp/normalize.d.ts +14 -0
  147. package/dist/otlp/normalize.js +404 -0
  148. package/dist/otlp/types/otlp.types.d.ts +69 -0
  149. package/dist/otlp/types/otlp.types.js +1 -0
  150. package/dist/pipeline/constants/pipeline.constants.d.ts +23 -0
  151. package/dist/pipeline/constants/pipeline.constants.js +22 -0
  152. package/dist/pipeline/hook-pipeline.d.ts +14 -0
  153. package/dist/pipeline/hook-pipeline.js +297 -0
  154. package/dist/pipeline/index.d.ts +6 -0
  155. package/dist/pipeline/index.js +1 -0
  156. package/dist/pipeline/types/pipeline.types.d.ts +48 -0
  157. package/dist/pipeline/types/pipeline.types.js +1 -0
  158. package/dist/privacy/constants/privacy.constants.d.ts +23 -0
  159. package/dist/privacy/constants/privacy.constants.js +38 -0
  160. package/dist/privacy/index.d.ts +7 -0
  161. package/dist/privacy/index.js +2 -0
  162. package/dist/privacy/sanitizer.d.ts +20 -0
  163. package/dist/privacy/sanitizer.js +52 -0
  164. package/dist/privacy/types/privacy.types.d.ts +13 -0
  165. package/dist/privacy/types/privacy.types.js +1 -0
  166. package/dist/providers/antigravity/antigravity.adapter.d.ts +54 -0
  167. package/dist/providers/antigravity/antigravity.adapter.js +311 -0
  168. package/dist/providers/antigravity/antigravity.detect.d.ts +25 -0
  169. package/dist/providers/antigravity/antigravity.detect.js +64 -0
  170. package/dist/providers/antigravity/antigravity.hooks.d.ts +24 -0
  171. package/dist/providers/antigravity/antigravity.hooks.js +126 -0
  172. package/dist/providers/antigravity/antigravity.provider.d.ts +2 -0
  173. package/dist/providers/antigravity/antigravity.provider.js +22 -0
  174. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +72 -0
  175. package/dist/providers/antigravity/constants/antigravity.constants.js +75 -0
  176. package/dist/providers/antigravity/schemas/antigravity.schema.d.ts +521 -0
  177. package/dist/providers/antigravity/schemas/antigravity.schema.js +64 -0
  178. package/dist/providers/antigravity/types/antigravity.types.d.ts +13 -0
  179. package/dist/providers/antigravity/types/antigravity.types.js +1 -0
  180. package/dist/providers/claude/claude.adapter.d.ts +15 -0
  181. package/dist/providers/claude/claude.adapter.js +141 -0
  182. package/dist/providers/claude/claude.detect.d.ts +20 -0
  183. package/dist/providers/claude/claude.detect.js +57 -0
  184. package/dist/providers/claude/claude.hooks.d.ts +23 -0
  185. package/dist/providers/claude/claude.hooks.js +94 -0
  186. package/dist/providers/claude/claude.otel.d.ts +95 -0
  187. package/dist/providers/claude/claude.otel.js +331 -0
  188. package/dist/providers/claude/claude.provider.d.ts +2 -0
  189. package/dist/providers/claude/claude.provider.js +26 -0
  190. package/dist/providers/claude/constants/claude.constants.d.ts +34 -0
  191. package/dist/providers/claude/constants/claude.constants.js +54 -0
  192. package/dist/providers/claude/constants/claude.otel.constants.d.ts +17 -0
  193. package/dist/providers/claude/constants/claude.otel.constants.js +17 -0
  194. package/dist/providers/claude/schemas/claude.schema.d.ts +72 -0
  195. package/dist/providers/claude/schemas/claude.schema.js +32 -0
  196. package/dist/providers/claude/types/claude.types.d.ts +3 -0
  197. package/dist/providers/claude/types/claude.types.js +1 -0
  198. package/dist/providers/codex/codex.adapter.d.ts +11 -0
  199. package/dist/providers/codex/codex.adapter.js +106 -0
  200. package/dist/providers/codex/codex.detect.d.ts +30 -0
  201. package/dist/providers/codex/codex.detect.js +58 -0
  202. package/dist/providers/codex/codex.hooks.d.ts +27 -0
  203. package/dist/providers/codex/codex.hooks.js +129 -0
  204. package/dist/providers/codex/codex.otel.d.ts +51 -0
  205. package/dist/providers/codex/codex.otel.js +325 -0
  206. package/dist/providers/codex/codex.provider.d.ts +2 -0
  207. package/dist/providers/codex/codex.provider.js +25 -0
  208. package/dist/providers/codex/constants/codex.constants.d.ts +41 -0
  209. package/dist/providers/codex/constants/codex.constants.js +62 -0
  210. package/dist/providers/codex/constants/codex.otel.constants.d.ts +22 -0
  211. package/dist/providers/codex/constants/codex.otel.constants.js +22 -0
  212. package/dist/providers/codex/schemas/codex.schema.d.ts +70 -0
  213. package/dist/providers/codex/schemas/codex.schema.js +32 -0
  214. package/dist/providers/codex/types/codex.types.d.ts +3 -0
  215. package/dist/providers/codex/types/codex.types.js +1 -0
  216. package/dist/providers/constants/provider.constants.d.ts +33 -0
  217. package/dist/providers/constants/provider.constants.js +33 -0
  218. package/dist/providers/cursor/constants/cursor.constants.d.ts +58 -0
  219. package/dist/providers/cursor/constants/cursor.constants.js +95 -0
  220. package/dist/providers/cursor/cursor.adapter.d.ts +11 -0
  221. package/dist/providers/cursor/cursor.adapter.js +331 -0
  222. package/dist/providers/cursor/cursor.detect.d.ts +23 -0
  223. package/dist/providers/cursor/cursor.detect.js +66 -0
  224. package/dist/providers/cursor/cursor.hooks.d.ts +25 -0
  225. package/dist/providers/cursor/cursor.hooks.js +95 -0
  226. package/dist/providers/cursor/cursor.provider.d.ts +2 -0
  227. package/dist/providers/cursor/cursor.provider.js +27 -0
  228. package/dist/providers/cursor/schemas/cursor.schema.d.ts +130 -0
  229. package/dist/providers/cursor/schemas/cursor.schema.js +62 -0
  230. package/dist/providers/cursor/types/cursor.types.d.ts +3 -0
  231. package/dist/providers/cursor/types/cursor.types.js +1 -0
  232. package/dist/providers/gemini/constants/gemini.constants.d.ts +36 -0
  233. package/dist/providers/gemini/constants/gemini.constants.js +58 -0
  234. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +34 -0
  235. package/dist/providers/gemini/constants/gemini.otel.constants.js +48 -0
  236. package/dist/providers/gemini/gemini.adapter.d.ts +15 -0
  237. package/dist/providers/gemini/gemini.adapter.js +146 -0
  238. package/dist/providers/gemini/gemini.detect.d.ts +23 -0
  239. package/dist/providers/gemini/gemini.detect.js +78 -0
  240. package/dist/providers/gemini/gemini.hooks.d.ts +22 -0
  241. package/dist/providers/gemini/gemini.hooks.js +93 -0
  242. package/dist/providers/gemini/gemini.otel.d.ts +62 -0
  243. package/dist/providers/gemini/gemini.otel.js +274 -0
  244. package/dist/providers/gemini/gemini.provider.d.ts +2 -0
  245. package/dist/providers/gemini/gemini.provider.js +22 -0
  246. package/dist/providers/gemini/schemas/gemini.schema.d.ts +81 -0
  247. package/dist/providers/gemini/schemas/gemini.schema.js +35 -0
  248. package/dist/providers/gemini/types/gemini.types.d.ts +3 -0
  249. package/dist/providers/gemini/types/gemini.types.js +1 -0
  250. package/dist/providers/index.d.ts +14 -0
  251. package/dist/providers/index.js +8 -0
  252. package/dist/providers/provider.d.ts +16 -0
  253. package/dist/providers/provider.js +149 -0
  254. package/dist/providers/registry.d.ts +12 -0
  255. package/dist/providers/registry.js +23 -0
  256. package/dist/providers/shared/constants/hook-refusal.constants.d.ts +6 -0
  257. package/dist/providers/shared/constants/hook-refusal.constants.js +6 -0
  258. package/dist/providers/shared/constants/tooling.constants.d.ts +25 -0
  259. package/dist/providers/shared/constants/tooling.constants.js +25 -0
  260. package/dist/providers/shared/event-builder.d.ts +85 -0
  261. package/dist/providers/shared/event-builder.js +166 -0
  262. package/dist/providers/shared/hook-config.d.ts +80 -0
  263. package/dist/providers/shared/hook-config.js +164 -0
  264. package/dist/providers/shared/hook-refusal.d.ts +16 -0
  265. package/dist/providers/shared/hook-refusal.js +33 -0
  266. package/dist/providers/shared/install-record.d.ts +75 -0
  267. package/dist/providers/shared/install-record.js +113 -0
  268. package/dist/providers/shared/tooling.d.ts +58 -0
  269. package/dist/providers/shared/tooling.js +103 -0
  270. package/dist/providers/shared/types/adapter.types.d.ts +54 -0
  271. package/dist/providers/shared/types/adapter.types.js +1 -0
  272. package/dist/providers/shared/types/hook-config.types.d.ts +32 -0
  273. package/dist/providers/shared/types/hook-config.types.js +1 -0
  274. package/dist/providers/types/provider.types.d.ts +98 -0
  275. package/dist/providers/types/provider.types.js +1 -0
  276. package/dist/snapshot/branch-selection.d.ts +37 -0
  277. package/dist/snapshot/branch-selection.js +69 -0
  278. package/dist/snapshot/budget.d.ts +41 -0
  279. package/dist/snapshot/budget.js +67 -0
  280. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +11 -0
  281. package/dist/snapshot/constants/snapshot-stages.constants.js +11 -0
  282. package/dist/snapshot/constants/snapshot.constants.d.ts +56 -0
  283. package/dist/snapshot/constants/snapshot.constants.js +56 -0
  284. package/dist/snapshot/index.d.ts +16 -0
  285. package/dist/snapshot/index.js +6 -0
  286. package/dist/snapshot/snapshot-event.d.ts +17 -0
  287. package/dist/snapshot/snapshot-event.js +66 -0
  288. package/dist/snapshot/snapshot-pipeline.d.ts +14 -0
  289. package/dist/snapshot/snapshot-pipeline.js +163 -0
  290. package/dist/snapshot/snapshot-state.d.ts +55 -0
  291. package/dist/snapshot/snapshot-state.js +100 -0
  292. package/dist/snapshot/types/snapshot.types.d.ts +86 -0
  293. package/dist/snapshot/types/snapshot.types.js +1 -0
  294. package/dist/storage/atomic-file.d.ts +25 -0
  295. package/dist/storage/atomic-file.js +76 -0
  296. package/dist/storage/constants/storage.constants.d.ts +34 -0
  297. package/dist/storage/constants/storage.constants.js +35 -0
  298. package/dist/storage/index.d.ts +10 -0
  299. package/dist/storage/index.js +5 -0
  300. package/dist/storage/install-state.d.ts +20 -0
  301. package/dist/storage/install-state.js +40 -0
  302. package/dist/storage/json-file.d.ts +13 -0
  303. package/dist/storage/json-file.js +31 -0
  304. package/dist/storage/lock.d.ts +15 -0
  305. package/dist/storage/lock.js +70 -0
  306. package/dist/storage/paths.d.ts +14 -0
  307. package/dist/storage/paths.js +42 -0
  308. package/dist/storage/schemas/storage.schema.d.ts +128 -0
  309. package/dist/storage/schemas/storage.schema.js +27 -0
  310. package/dist/storage/types/storage.types.d.ts +36 -0
  311. package/dist/storage/types/storage.types.js +1 -0
  312. package/dist/transport/constants/transport.constants.d.ts +47 -0
  313. package/dist/transport/constants/transport.constants.js +47 -0
  314. package/dist/transport/cooldown.d.ts +35 -0
  315. package/dist/transport/cooldown.js +62 -0
  316. package/dist/transport/delivery-stats.d.ts +65 -0
  317. package/dist/transport/delivery-stats.js +186 -0
  318. package/dist/transport/delivery.d.ts +26 -0
  319. package/dist/transport/delivery.js +80 -0
  320. package/dist/transport/headers.d.ts +12 -0
  321. package/dist/transport/headers.js +19 -0
  322. package/dist/transport/http-transport.d.ts +39 -0
  323. package/dist/transport/http-transport.js +106 -0
  324. package/dist/transport/index.d.ts +13 -0
  325. package/dist/transport/index.js +7 -0
  326. package/dist/transport/queue.d.ts +177 -0
  327. package/dist/transport/queue.js +474 -0
  328. package/dist/transport/schemas/queue.schema.d.ts +30 -0
  329. package/dist/transport/schemas/queue.schema.js +18 -0
  330. package/dist/transport/transport.d.ts +6 -0
  331. package/dist/transport/transport.js +1 -0
  332. package/dist/transport/types/transport.types.d.ts +102 -0
  333. package/dist/transport/types/transport.types.js +1 -0
  334. package/dist/turns/aggregate-usage.d.ts +20 -0
  335. package/dist/turns/aggregate-usage.js +269 -0
  336. package/dist/turns/claude-transcript.d.ts +18 -0
  337. package/dist/turns/claude-transcript.js +80 -0
  338. package/dist/turns/constants/turns.constants.d.ts +69 -0
  339. package/dist/turns/constants/turns.constants.js +86 -0
  340. package/dist/turns/cursor-transcript.d.ts +21 -0
  341. package/dist/turns/cursor-transcript.js +66 -0
  342. package/dist/turns/index.d.ts +17 -0
  343. package/dist/turns/index.js +7 -0
  344. package/dist/turns/transcript.d.ts +74 -0
  345. package/dist/turns/transcript.js +188 -0
  346. package/dist/turns/turn-state.d.ts +94 -0
  347. package/dist/turns/turn-state.js +234 -0
  348. package/dist/turns/turn-summary.d.ts +27 -0
  349. package/dist/turns/turn-summary.js +164 -0
  350. package/dist/turns/turn-tracker.d.ts +14 -0
  351. package/dist/turns/turn-tracker.js +521 -0
  352. package/dist/turns/types/aggregate-usage.types.d.ts +26 -0
  353. package/dist/turns/types/aggregate-usage.types.js +1 -0
  354. package/dist/turns/types/transcript.types.d.ts +41 -0
  355. package/dist/turns/types/transcript.types.js +1 -0
  356. package/dist/turns/types/turn-state.types.d.ts +37 -0
  357. package/dist/turns/types/turn-state.types.js +1 -0
  358. package/dist/turns/types/turn-summary.types.d.ts +106 -0
  359. package/dist/turns/types/turn-summary.types.js +1 -0
  360. package/dist/turns/types/turn-tracker.types.d.ts +27 -0
  361. package/dist/turns/types/turn-tracker.types.js +1 -0
  362. package/example/README.md +43 -0
  363. package/example/server.mjs +240 -0
  364. package/package.json +89 -0
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Runtime-agnostic primitives: the ambient environment, diagnostics, and the
3
+ * pure helpers every other module composes from.
4
+ */
5
+ export type { Env, FlowObserver, FlowResult, FlowTrace, Step, StepOutcome, UnknownRecord } from './types/core.types.js';
6
+ export { realEnv } from './env.js';
7
+ export { debugEnabled, debugLog, setVerbose, warnLog } from './logger.js';
8
+ export { meetsMinVersion, parseVersion } from './version.js';
9
+ export { findExecutable } from './which.js';
10
+ export { asArray, asRecord, compact, firstNumber, firstString, firstStringOf, isRecord, omitKeys } from './object.js';
11
+ export { add, finiteOrZero, sumPresent } from './number.js';
12
+ export { pollUntil, sleep } from './async.js';
13
+ export { next, pipe, runFlow, step, stop } from './pipe.js';
@@ -0,0 +1,8 @@
1
+ export { realEnv } from './env.js';
2
+ export { debugEnabled, debugLog, setVerbose, warnLog } from './logger.js';
3
+ export { meetsMinVersion, parseVersion } from './version.js';
4
+ export { findExecutable } from './which.js';
5
+ export { asArray, asRecord, compact, firstNumber, firstString, firstStringOf, isRecord, omitKeys } from './object.js';
6
+ export { add, finiteOrZero, sumPresent } from './number.js';
7
+ export { pollUntil, sleep } from './async.js';
8
+ export { next, pipe, runFlow, step, stop } from './pipe.js';
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Turn on verbose diagnostics for the rest of the process.
3
+ *
4
+ * @param on - Whether `--verbose` was passed.
5
+ */
6
+ export declare function setVerbose(on: boolean): void;
7
+ /**
8
+ * Whether debug diagnostics should be written.
9
+ *
10
+ * @param vars - Environment to read; defaults to the real process env.
11
+ * @returns True when `--verbose`, AGENTWATCH_DEBUG or DEBUG asked for them.
12
+ */
13
+ export declare function debugEnabled(vars?: Readonly<Record<string, string | undefined>>): boolean;
14
+ /**
15
+ * Write a diagnostic line to stderr when debugging is on.
16
+ *
17
+ * @param parts - Message fragments; objects are JSON-encoded, Errors reduced
18
+ * to their message.
19
+ */
20
+ export declare function debugLog(...parts: readonly unknown[]): void;
21
+ /**
22
+ * Write a warning to stderr. Always shown: a warning the user cannot see is
23
+ * not a warning.
24
+ *
25
+ * @param parts - Message fragments, formatted like {@link debugLog}.
26
+ */
27
+ export declare function warnLog(...parts: readonly unknown[]): void;
@@ -0,0 +1,82 @@
1
+ import process from 'node:process';
2
+ import { DEBUG_NAMESPACE, DEBUG_NAMESPACE_VAR, DEBUG_VAR, LOG_PREFIX, TRUTHY_DEBUG_VALUES } from './constants/core.constants.js';
3
+ /**
4
+ * All diagnostics go to stderr. Hook stdout belongs to the agent's hook
5
+ * protocol and must never receive log output.
6
+ *
7
+ * The `--verbose` flag is process-wide state, so it lives here as the module's
8
+ * one deliberate mutable cell rather than being threaded through every call.
9
+ */
10
+ let verbose = false;
11
+ /**
12
+ * Turn on verbose diagnostics for the rest of the process.
13
+ *
14
+ * @param on - Whether `--verbose` was passed.
15
+ */
16
+ export function setVerbose(on) {
17
+ verbose = on;
18
+ }
19
+ /**
20
+ * Whether debug diagnostics should be written.
21
+ *
22
+ * @param vars - Environment to read; defaults to the real process env.
23
+ * @returns True when `--verbose`, AGENTWATCH_DEBUG or DEBUG asked for them.
24
+ */
25
+ export function debugEnabled(vars = process.env) {
26
+ if (verbose)
27
+ return true;
28
+ const flag = (vars[DEBUG_VAR] ?? '').toLowerCase();
29
+ if (TRUTHY_DEBUG_VALUES.has(flag))
30
+ return true;
31
+ return (vars[DEBUG_NAMESPACE_VAR] ?? '').includes(DEBUG_NAMESPACE);
32
+ }
33
+ /**
34
+ * Write a diagnostic line to stderr when debugging is on.
35
+ *
36
+ * @param parts - Message fragments; objects are JSON-encoded, Errors reduced
37
+ * to their message.
38
+ */
39
+ export function debugLog(...parts) {
40
+ if (!debugEnabled())
41
+ return;
42
+ process.stderr.write(`${LOG_PREFIX} ${formatParts(parts)}\n`);
43
+ }
44
+ /**
45
+ * Write a warning to stderr. Always shown: a warning the user cannot see is
46
+ * not a warning.
47
+ *
48
+ * @param parts - Message fragments, formatted like {@link debugLog}.
49
+ */
50
+ export function warnLog(...parts) {
51
+ process.stderr.write(`${LOG_PREFIX} warning: ${formatParts(parts)}\n`);
52
+ }
53
+ /**
54
+ * Render message fragments as one space-separated line.
55
+ *
56
+ * @param parts - Fragments of any shape.
57
+ * @returns The joined text.
58
+ */
59
+ function formatParts(parts) {
60
+ const rendered = [];
61
+ for (const part of parts)
62
+ rendered.push(formatPart(part));
63
+ return rendered.join(' ');
64
+ }
65
+ /**
66
+ * Render one fragment, never throwing on a cyclic or exotic value.
67
+ *
68
+ * @param part - Fragment of any shape.
69
+ * @returns Its text form.
70
+ */
71
+ function formatPart(part) {
72
+ if (typeof part === 'string')
73
+ return part;
74
+ if (part instanceof Error)
75
+ return part.message;
76
+ try {
77
+ return JSON.stringify(part) ?? String(part);
78
+ }
79
+ catch {
80
+ return String(part);
81
+ }
82
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Add an untrusted value to a running total, ignoring anything unusable.
3
+ *
4
+ * Token counts come from transcripts and OTLP attributes, where a field may be
5
+ * missing, null, or a string. `undefined + 1` would poison the whole sum with
6
+ * NaN, so a value that is not a finite number leaves the total as it was —
7
+ * including its "not reported at all" undefined state.
8
+ *
9
+ * @param current - Total so far; undefined when nothing has been added yet.
10
+ * @param value - Candidate addend of unknown shape.
11
+ * @returns The new total, or `current` when the value was unusable.
12
+ */
13
+ export declare function add(current: number | undefined, value: unknown): number | undefined;
14
+ /**
15
+ * An untrusted value as a number, treating anything unusable as zero.
16
+ *
17
+ * For weights and ratios, where "missing" and "zero" are the same thing.
18
+ *
19
+ * @param value - Candidate of unknown shape.
20
+ * @returns The finite number, or 0.
21
+ */
22
+ export declare function finiteOrZero(value: unknown): number;
23
+ /**
24
+ * Sum the values that are actually present.
25
+ *
26
+ * Returns undefined for an all-empty input rather than 0: "no agent reported
27
+ * this token class" and "the agent reported zero" are different facts, and
28
+ * collapsing them would invent usage data downstream.
29
+ *
30
+ * @param values - Values to sum; undefined entries are skipped.
31
+ * @returns The sum, or undefined when no value was present.
32
+ */
33
+ export declare function sumPresent(values: readonly (number | undefined)[]): number | undefined;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Add an untrusted value to a running total, ignoring anything unusable.
3
+ *
4
+ * Token counts come from transcripts and OTLP attributes, where a field may be
5
+ * missing, null, or a string. `undefined + 1` would poison the whole sum with
6
+ * NaN, so a value that is not a finite number leaves the total as it was —
7
+ * including its "not reported at all" undefined state.
8
+ *
9
+ * @param current - Total so far; undefined when nothing has been added yet.
10
+ * @param value - Candidate addend of unknown shape.
11
+ * @returns The new total, or `current` when the value was unusable.
12
+ */
13
+ export function add(current, value) {
14
+ if (typeof value !== 'number' || !Number.isFinite(value))
15
+ return current;
16
+ return (current ?? 0) + value;
17
+ }
18
+ /**
19
+ * An untrusted value as a number, treating anything unusable as zero.
20
+ *
21
+ * For weights and ratios, where "missing" and "zero" are the same thing.
22
+ *
23
+ * @param value - Candidate of unknown shape.
24
+ * @returns The finite number, or 0.
25
+ */
26
+ export function finiteOrZero(value) {
27
+ return typeof value === 'number' && Number.isFinite(value) ? value : 0;
28
+ }
29
+ /**
30
+ * Sum the values that are actually present.
31
+ *
32
+ * Returns undefined for an all-empty input rather than 0: "no agent reported
33
+ * this token class" and "the agent reported zero" are different facts, and
34
+ * collapsing them would invent usage data downstream.
35
+ *
36
+ * @param values - Values to sum; undefined entries are skipped.
37
+ * @returns The sum, or undefined when no value was present.
38
+ */
39
+ export function sumPresent(values) {
40
+ let total;
41
+ for (const value of values) {
42
+ if (value === undefined)
43
+ continue;
44
+ total = (total ?? 0) + value;
45
+ }
46
+ return total;
47
+ }
@@ -0,0 +1,78 @@
1
+ import type { UnknownRecord } from './types/core.types.js';
2
+ export type { UnknownRecord } from './types/core.types.js';
3
+ /**
4
+ * Drop every key whose value is `undefined`, returning a new object.
5
+ *
6
+ * Canonical events are serialized straight to JSON, and an explicit
7
+ * `"field": undefined` is not representable there — the property has to be
8
+ * absent instead. Building a fresh object (rather than deleting keys) also
9
+ * keeps the result monomorphic for V8 (STYLEGUIDE 3.4).
10
+ *
11
+ * @param value - Object to compact; left untouched.
12
+ * @returns A copy holding only the defined entries.
13
+ */
14
+ export declare function compact<T extends object>(value: T): T;
15
+ /**
16
+ * Copy an object without the given keys.
17
+ *
18
+ * The replacement for `delete obj.key`: same result, no hidden-class
19
+ * transition on the original object (STYLEGUIDE 3.4).
20
+ *
21
+ * @param value - Source object; left untouched.
22
+ * @param keys - Keys to leave out. A Set, so the filter is O(1) per entry.
23
+ * @returns A copy without those keys.
24
+ */
25
+ export declare function omitKeys<T extends UnknownRecord>(value: T, keys: ReadonlySet<string>): T;
26
+ /**
27
+ * Narrow an untrusted value to a plain JSON object.
28
+ *
29
+ * Arrays are rejected on purpose: every caller wants a keyed record, and
30
+ * `typeof [] === 'object'` would otherwise let one through.
31
+ *
32
+ * @param value - Value of unknown shape.
33
+ * @returns The value as a record, or undefined when it is not one.
34
+ */
35
+ export declare function asRecord(value: unknown): UnknownRecord | undefined;
36
+ /**
37
+ * Type guard form of {@link asRecord}, for use in conditions.
38
+ *
39
+ * @param value - Value of unknown shape.
40
+ * @returns True when the value is a plain JSON object.
41
+ */
42
+ export declare function isRecord(value: unknown): value is UnknownRecord;
43
+ /**
44
+ * An array, or an empty one for anything else.
45
+ *
46
+ * @param value - Value of unknown shape.
47
+ * @returns The value when it is an array, otherwise an empty array.
48
+ */
49
+ export declare function asArray(value: unknown): unknown[];
50
+ /**
51
+ * First key that holds a usable string, checked in the given order.
52
+ *
53
+ * Numbers are stringified: agents report the same attribute (a sequence
54
+ * number, an id) as either type depending on version and exporter.
55
+ *
56
+ * @param record - Attribute bag to read.
57
+ * @param keys - Candidate keys, most specific first.
58
+ * @returns The first non-empty value, or undefined when none matches.
59
+ */
60
+ export declare function firstString(record: UnknownRecord, keys: readonly string[]): string | undefined;
61
+ /**
62
+ * First key that holds a finite number, checked in the given order.
63
+ *
64
+ * Numeric strings are accepted: OTLP/JSON encodes 64-bit integers as strings,
65
+ * so token counts arrive either way.
66
+ *
67
+ * @param record - Attribute bag to read.
68
+ * @param keys - Candidate keys, most specific first.
69
+ * @returns The first finite value, or undefined when none matches.
70
+ */
71
+ export declare function firstNumber(record: UnknownRecord, keys: readonly string[]): number | undefined;
72
+ /**
73
+ * First argument that is a non-empty string.
74
+ *
75
+ * @param values - Candidates in priority order.
76
+ * @returns The first usable string, or undefined when there is none.
77
+ */
78
+ export declare function firstStringOf(...values: readonly unknown[]): string | undefined;
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Drop every key whose value is `undefined`, returning a new object.
3
+ *
4
+ * Canonical events are serialized straight to JSON, and an explicit
5
+ * `"field": undefined` is not representable there — the property has to be
6
+ * absent instead. Building a fresh object (rather than deleting keys) also
7
+ * keeps the result monomorphic for V8 (STYLEGUIDE 3.4).
8
+ *
9
+ * @param value - Object to compact; left untouched.
10
+ * @returns A copy holding only the defined entries.
11
+ */
12
+ export function compact(value) {
13
+ const out = {};
14
+ for (const [key, entry] of Object.entries(value)) {
15
+ if (entry === undefined)
16
+ continue;
17
+ out[key] = entry;
18
+ }
19
+ return out;
20
+ }
21
+ /**
22
+ * Copy an object without the given keys.
23
+ *
24
+ * The replacement for `delete obj.key`: same result, no hidden-class
25
+ * transition on the original object (STYLEGUIDE 3.4).
26
+ *
27
+ * @param value - Source object; left untouched.
28
+ * @param keys - Keys to leave out. A Set, so the filter is O(1) per entry.
29
+ * @returns A copy without those keys.
30
+ */
31
+ export function omitKeys(value, keys) {
32
+ const out = {};
33
+ for (const [key, entry] of Object.entries(value)) {
34
+ if (keys.has(key))
35
+ continue;
36
+ out[key] = entry;
37
+ }
38
+ return out;
39
+ }
40
+ /**
41
+ * Narrow an untrusted value to a plain JSON object.
42
+ *
43
+ * Arrays are rejected on purpose: every caller wants a keyed record, and
44
+ * `typeof [] === 'object'` would otherwise let one through.
45
+ *
46
+ * @param value - Value of unknown shape.
47
+ * @returns The value as a record, or undefined when it is not one.
48
+ */
49
+ export function asRecord(value) {
50
+ if (typeof value !== 'object' || value === null || Array.isArray(value))
51
+ return undefined;
52
+ return value;
53
+ }
54
+ /**
55
+ * Type guard form of {@link asRecord}, for use in conditions.
56
+ *
57
+ * @param value - Value of unknown shape.
58
+ * @returns True when the value is a plain JSON object.
59
+ */
60
+ export function isRecord(value) {
61
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
62
+ }
63
+ /**
64
+ * An array, or an empty one for anything else.
65
+ *
66
+ * @param value - Value of unknown shape.
67
+ * @returns The value when it is an array, otherwise an empty array.
68
+ */
69
+ export function asArray(value) {
70
+ return Array.isArray(value) ? value : [];
71
+ }
72
+ /**
73
+ * First key that holds a usable string, checked in the given order.
74
+ *
75
+ * Numbers are stringified: agents report the same attribute (a sequence
76
+ * number, an id) as either type depending on version and exporter.
77
+ *
78
+ * @param record - Attribute bag to read.
79
+ * @param keys - Candidate keys, most specific first.
80
+ * @returns The first non-empty value, or undefined when none matches.
81
+ */
82
+ export function firstString(record, keys) {
83
+ for (const key of keys) {
84
+ const value = record[key];
85
+ if (typeof value === 'string' && value.length > 0)
86
+ return value;
87
+ if (typeof value === 'number')
88
+ return String(value);
89
+ }
90
+ return undefined;
91
+ }
92
+ /**
93
+ * First key that holds a finite number, checked in the given order.
94
+ *
95
+ * Numeric strings are accepted: OTLP/JSON encodes 64-bit integers as strings,
96
+ * so token counts arrive either way.
97
+ *
98
+ * @param record - Attribute bag to read.
99
+ * @param keys - Candidate keys, most specific first.
100
+ * @returns The first finite value, or undefined when none matches.
101
+ */
102
+ export function firstNumber(record, keys) {
103
+ for (const key of keys) {
104
+ const value = record[key];
105
+ if (typeof value === 'number' && Number.isFinite(value))
106
+ return value;
107
+ if (typeof value === 'string' && value.trim() !== '') {
108
+ const parsed = Number(value);
109
+ if (Number.isFinite(parsed))
110
+ return parsed;
111
+ }
112
+ }
113
+ return undefined;
114
+ }
115
+ /**
116
+ * First argument that is a non-empty string.
117
+ *
118
+ * @param values - Candidates in priority order.
119
+ * @returns The first usable string, or undefined when there is none.
120
+ */
121
+ export function firstStringOf(...values) {
122
+ for (const value of values) {
123
+ if (typeof value === 'string' && value.length > 0)
124
+ return value;
125
+ }
126
+ return undefined;
127
+ }
@@ -0,0 +1,55 @@
1
+ import type { FlowObserver, FlowResult, Step, StepOutcome } from './types/core.types.js';
2
+ export type { FlowObserver, FlowResult, FlowTrace, Step, StepOutcome } from './types/core.types.js';
3
+ /**
4
+ * Wrap a state as "keep going": the next stage receives it verbatim.
5
+ *
6
+ * @param state - State the next stage should run on.
7
+ * @returns A continue outcome carrying that state.
8
+ */
9
+ export declare function next<TState>(state: TState): StepOutcome<TState>;
10
+ /**
11
+ * Wrap a state as "flow is done": remaining stages are skipped.
12
+ *
13
+ * @param state - Final state, returned to the caller as-is.
14
+ * @param reason - Why the flow ended here; surfaces in diagnostics.
15
+ * @returns A terminal outcome carrying that state.
16
+ */
17
+ export declare function stop<TState>(state: TState, reason: string): StepOutcome<TState>;
18
+ /**
19
+ * Declare one stage of a flow. A stage is a pure function of the whole state:
20
+ * it reads what it needs, returns the next state, and never mutates its input.
21
+ *
22
+ * @param name - Stage label used in traces and diagnostics.
23
+ * @param run - The transformation; returns `next(...)` or `stop(...)`.
24
+ * @returns The stage, ready to be listed in a flow.
25
+ */
26
+ export declare function step<TState>(name: string, run: Step<TState>['run']): Step<TState>;
27
+ /**
28
+ * Run stages left to right, threading one immutable state through them, and
29
+ * stop at the first stage that says so.
30
+ *
31
+ * This is the shape every entry point in the package is expressed in: the flow
32
+ * is a list of named stages you can read top to bottom, not a call graph you
33
+ * have to trace. A stage that throws ends the flow the same way an explicit
34
+ * stop does — the state stays whatever the last successful stage returned, so
35
+ * a failure degrades the result instead of losing it.
36
+ *
37
+ * @param steps - Stages in execution order.
38
+ * @param initial - State the first stage receives.
39
+ * @param observe - Optional per-stage trace sink; the flow itself does no I/O.
40
+ * @returns The final state, whether every stage ran, and where it stopped.
41
+ */
42
+ export declare function runFlow<TState>(steps: readonly Step<TState>[], initial: TState, observe?: FlowObserver): Promise<FlowResult<TState>>;
43
+ /**
44
+ * Left-to-right function composition for plain value transformations, so a
45
+ * derivation reads in the order it happens instead of inside-out.
46
+ *
47
+ * Takes the unary transformations to apply, in order.
48
+ *
49
+ * @returns One function that threads its argument through all of them.
50
+ */
51
+ export declare function pipe<A, B>(ab: (a: A) => B): (a: A) => B;
52
+ export declare function pipe<A, B, C>(ab: (a: A) => B, bc: (b: B) => C): (a: A) => C;
53
+ export declare function pipe<A, B, C, D>(ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): (a: A) => D;
54
+ export declare function pipe<A, B, C, D, E>(ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E): (a: A) => E;
55
+ export declare function pipe<A, B, C, D, E, F>(ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F): (a: A) => F;
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Wrap a state as "keep going": the next stage receives it verbatim.
3
+ *
4
+ * @param state - State the next stage should run on.
5
+ * @returns A continue outcome carrying that state.
6
+ */
7
+ export function next(state) {
8
+ return { kind: 'next', state };
9
+ }
10
+ /**
11
+ * Wrap a state as "flow is done": remaining stages are skipped.
12
+ *
13
+ * @param state - Final state, returned to the caller as-is.
14
+ * @param reason - Why the flow ended here; surfaces in diagnostics.
15
+ * @returns A terminal outcome carrying that state.
16
+ */
17
+ export function stop(state, reason) {
18
+ return { kind: 'stop', state, reason };
19
+ }
20
+ /**
21
+ * Declare one stage of a flow. A stage is a pure function of the whole state:
22
+ * it reads what it needs, returns the next state, and never mutates its input.
23
+ *
24
+ * @param name - Stage label used in traces and diagnostics.
25
+ * @param run - The transformation; returns `next(...)` or `stop(...)`.
26
+ * @returns The stage, ready to be listed in a flow.
27
+ */
28
+ export function step(name, run) {
29
+ return { name, run };
30
+ }
31
+ /**
32
+ * Run stages left to right, threading one immutable state through them, and
33
+ * stop at the first stage that says so.
34
+ *
35
+ * This is the shape every entry point in the package is expressed in: the flow
36
+ * is a list of named stages you can read top to bottom, not a call graph you
37
+ * have to trace. A stage that throws ends the flow the same way an explicit
38
+ * stop does — the state stays whatever the last successful stage returned, so
39
+ * a failure degrades the result instead of losing it.
40
+ *
41
+ * @param steps - Stages in execution order.
42
+ * @param initial - State the first stage receives.
43
+ * @param observe - Optional per-stage trace sink; the flow itself does no I/O.
44
+ * @returns The final state, whether every stage ran, and where it stopped.
45
+ */
46
+ export async function runFlow(steps, initial, observe) {
47
+ let state = initial;
48
+ for (const current of steps) {
49
+ let outcome;
50
+ try {
51
+ outcome = await current.run(state);
52
+ }
53
+ catch (error) {
54
+ observe?.({ step: current.name, outcome: 'threw', reason: errorMessage(error) });
55
+ return { state, completed: false, stoppedAt: current.name, reason: errorMessage(error) };
56
+ }
57
+ observe?.({ step: current.name, outcome: outcome.kind, reason: outcome.kind === 'stop' ? outcome.reason : undefined });
58
+ if (outcome.kind === 'stop') {
59
+ return { state: outcome.state, completed: false, stoppedAt: current.name, reason: outcome.reason };
60
+ }
61
+ state = outcome.state;
62
+ }
63
+ return { state, completed: true };
64
+ }
65
+ export function pipe(...fns) {
66
+ return (value) => {
67
+ let current = value;
68
+ for (const fn of fns)
69
+ current = fn(current);
70
+ return current;
71
+ };
72
+ }
73
+ /**
74
+ * Human-readable text for anything that reached a catch block.
75
+ *
76
+ * @param error - The thrown value, of any shape.
77
+ * @returns Its message, or its string form when it is not an Error.
78
+ */
79
+ function errorMessage(error) {
80
+ return error instanceof Error ? error.message : String(error);
81
+ }
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Ambient runtime contracts shared by every module.
3
+ */
4
+ /**
5
+ * Ambient environment for every command. All filesystem locations, environment
6
+ * variables and PATH lookups flow through this object so tests can run against
7
+ * a temporary HOME without ever touching the developer's real agent configs.
8
+ */
9
+ export interface Env {
10
+ readonly home: string;
11
+ readonly platform: NodeJS.Platform;
12
+ readonly cwd: string;
13
+ /** Mirrors `process.env`, which is mutable ambient state by nature. */
14
+ readonly vars: Record<string, string | undefined>;
15
+ now(): Date;
16
+ }
17
+ /** Any JSON object decoded from an untrusted source. */
18
+ export type UnknownRecord = Record<string, unknown>;
19
+ /**
20
+ * One named stage of a flow. Receives the whole state and returns the next
21
+ * state, or stops the flow. Never mutates its input.
22
+ */
23
+ export interface Step<TState> {
24
+ readonly name: string;
25
+ run(state: TState): Promise<StepOutcome<TState>> | StepOutcome<TState>;
26
+ }
27
+ /**
28
+ * What a stage hands back: the state to feed the next stage, or a terminal
29
+ * state with the reason the flow ended early. Making "stop" an explicit value
30
+ * — instead of a thrown error or a nullable return — is what keeps the flow
31
+ * linear and every stage independently testable.
32
+ */
33
+ export type StepOutcome<TState> = {
34
+ readonly kind: 'next';
35
+ readonly state: TState;
36
+ } | {
37
+ readonly kind: 'stop';
38
+ readonly state: TState;
39
+ readonly reason: string;
40
+ };
41
+ /** Where a flow ended and why; `stoppedAt` is empty when every stage ran. */
42
+ export interface FlowResult<TState> {
43
+ readonly state: TState;
44
+ readonly completed: boolean;
45
+ readonly stoppedAt?: string;
46
+ readonly reason?: string;
47
+ }
48
+ /** Per-stage trace hook. The flow itself stays pure; I/O lives in the observer. */
49
+ export type FlowObserver = (trace: FlowTrace) => void;
50
+ export interface FlowTrace {
51
+ readonly step: string;
52
+ readonly outcome: 'next' | 'stop' | 'threw';
53
+ readonly reason?: string;
54
+ }
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Ambient runtime contracts shared by every module.
3
+ */
4
+ export {};
@@ -0,0 +1,19 @@
1
+ /**
2
+ * First dotted version (x.y.z) found in CLI output.
3
+ *
4
+ * @param output - Raw stdout of a `--version` call.
5
+ * @returns The version, or undefined when the output holds none.
6
+ */
7
+ export declare function parseVersion(output: string): string | undefined;
8
+ /**
9
+ * Whether `version` is at least `min`.
10
+ *
11
+ * Segment-wise numeric comparison; a missing segment counts as 0, so "2.1"
12
+ * satisfies "2.1.0". A non-numeric segment fails closed: an unparseable
13
+ * version must not be reported as new enough.
14
+ *
15
+ * @param version - Version found on the machine.
16
+ * @param min - Minimum this feature needs.
17
+ * @returns True when version >= min.
18
+ */
19
+ export declare function meetsMinVersion(version: string, min: string): boolean;
@@ -0,0 +1,35 @@
1
+ import { RE_SEMVER } from './constants/core.constants.js';
2
+ /**
3
+ * First dotted version (x.y.z) found in CLI output.
4
+ *
5
+ * @param output - Raw stdout of a `--version` call.
6
+ * @returns The version, or undefined when the output holds none.
7
+ */
8
+ export function parseVersion(output) {
9
+ return RE_SEMVER.exec(output)?.[0];
10
+ }
11
+ /**
12
+ * Whether `version` is at least `min`.
13
+ *
14
+ * Segment-wise numeric comparison; a missing segment counts as 0, so "2.1"
15
+ * satisfies "2.1.0". A non-numeric segment fails closed: an unparseable
16
+ * version must not be reported as new enough.
17
+ *
18
+ * @param version - Version found on the machine.
19
+ * @param min - Minimum this feature needs.
20
+ * @returns True when version >= min.
21
+ */
22
+ export function meetsMinVersion(version, min) {
23
+ const actual = version.split('.');
24
+ const required = min.split('.');
25
+ const length = Math.max(actual.length, required.length);
26
+ for (let index = 0; index < length; index++) {
27
+ const left = Number(actual[index] ?? 0);
28
+ const right = Number(required[index] ?? 0);
29
+ if (Number.isNaN(left) || Number.isNaN(right))
30
+ return false;
31
+ if (left !== right)
32
+ return left > right;
33
+ }
34
+ return true;
35
+ }