@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,67 @@
1
+ import { GIT_TIMEOUT_MS } from '../git/constants/git.constants.js';
2
+ /**
3
+ * How long a deadline still allows, never below zero.
4
+ *
5
+ * @param deadline - Epoch milliseconds the flow must be finished by.
6
+ * @param now - Current time, injectable for tests.
7
+ * @returns Milliseconds left.
8
+ */
9
+ export function remainingMs(deadline, now = Date.now) {
10
+ return Math.max(0, deadline - now());
11
+ }
12
+ /**
13
+ * A git runner that cannot outlive the flow's budget.
14
+ *
15
+ * Without this the budget bounds nothing that matters: the listing may wait a
16
+ * second, resolving the default branch may wait three more across its
17
+ * fallbacks, and a `git log` that started inside the budget runs to its own
18
+ * timeout regardless. Four sequential seconds is not "at most one", and this
19
+ * runs on the hook's answer path.
20
+ *
21
+ * A call with no time left is not made at all — its caller reads the absent
22
+ * output the same way it reads a repository that could not be listed.
23
+ *
24
+ * @param run - The real runner.
25
+ * @param deadline - Epoch milliseconds the flow must be finished by.
26
+ * @param now - Current time, injectable for tests.
27
+ * @returns A runner whose timeout is whatever is left, capped at the git default.
28
+ */
29
+ export function budgetedRunner(run, deadline, now = Date.now) {
30
+ return async (args, cwd, timeoutMs, home) => {
31
+ const left = remainingMs(deadline, now);
32
+ if (left === 0)
33
+ return undefined;
34
+ return run(args, cwd, Math.min(timeoutMs || GIT_TIMEOUT_MS, left), home);
35
+ };
36
+ }
37
+ /**
38
+ * Give up on work that outlives the budget.
39
+ *
40
+ * Used for the two local writes at the end of the flow. Abandoning either is
41
+ * safe by construction: an enqueue that did not finish means nothing was
42
+ * recorded as sent, and a cache write that did not finish means the branches
43
+ * are simply offered again next turn.
44
+ *
45
+ * @param work - The promise to bound.
46
+ * @param deadline - Epoch milliseconds the flow must be finished by.
47
+ * @param now - Current time, injectable for tests.
48
+ * @returns True when the work finished inside the budget.
49
+ */
50
+ export async function withinBudget(work, deadline, now = Date.now) {
51
+ const left = remainingMs(deadline, now);
52
+ if (left === 0)
53
+ return false;
54
+ let timer;
55
+ const expiry = new Promise((resolve) => {
56
+ timer = setTimeout(() => resolve(false), left);
57
+ // The flow must never be the reason a hook process stays alive.
58
+ timer.unref?.();
59
+ });
60
+ try {
61
+ return await Promise.race([work.then(() => true), expiry]);
62
+ }
63
+ finally {
64
+ if (timer)
65
+ clearTimeout(timer);
66
+ }
67
+ }
@@ -0,0 +1,11 @@
1
+ /** Stage names, used in the flow definition and in its debug trace. */
2
+ export declare const STAGE_COLLECT_REFS = "collect-refs";
3
+ export declare const STAGE_SELECT_CHANGED = "select-changed";
4
+ export declare const STAGE_COLLECT_COMMITS = "collect-commits";
5
+ export declare const STAGE_SANITIZE = "sanitize";
6
+ export declare const STAGE_ENQUEUE = "enqueue";
7
+ /** Reasons a stage ends the flow early. */
8
+ export declare const STOP_NOT_A_REPOSITORY = "no branches: not a repository, or it has none";
9
+ export declare const STOP_NOTHING_CHANGED = "no branch moved and none is due a refresh";
10
+ export declare const STOP_BUDGET_SPENT = "snapshot budget spent";
11
+ export declare const STOP_NO_EVENT = "no snapshot event was built";
@@ -0,0 +1,11 @@
1
+ /** Stage names, used in the flow definition and in its debug trace. */
2
+ export const STAGE_COLLECT_REFS = 'collect-refs';
3
+ export const STAGE_SELECT_CHANGED = 'select-changed';
4
+ export const STAGE_COLLECT_COMMITS = 'collect-commits';
5
+ export const STAGE_SANITIZE = 'sanitize';
6
+ export const STAGE_ENQUEUE = 'enqueue';
7
+ /** Reasons a stage ends the flow early. */
8
+ export const STOP_NOT_A_REPOSITORY = 'no branches: not a repository, or it has none';
9
+ export const STOP_NOTHING_CHANGED = 'no branch moved and none is due a refresh';
10
+ export const STOP_BUDGET_SPENT = 'snapshot budget spent';
11
+ export const STOP_NO_EVENT = 'no snapshot event was built';
@@ -0,0 +1,56 @@
1
+ /**
2
+ * How many branches one snapshot describes.
3
+ *
4
+ * The ten most recently committed: enough to cover what anyone is actually
5
+ * working on, few enough that the listing is one cheap git process and the
6
+ * backend's per-branch transaction count stays bounded.
7
+ */
8
+ export declare const SNAPSHOT_BRANCH_COUNT = 10;
9
+ /**
10
+ * How many of a branch's own commits travel with it.
11
+ *
12
+ * They become the titles the backend's grouping agent reads, so this is a
13
+ * window on recent work rather than an archive: a branch is described by what
14
+ * has been done on it lately, and the window is what keeps a long-lived branch
15
+ * from accumulating hundreds of rows.
16
+ */
17
+ export declare const SNAPSHOT_COMMITS_PER_BRANCH = 20;
18
+ /**
19
+ * Total budget for the whole snapshot flow.
20
+ *
21
+ * It is awaited, so it delays the hook's answer — a dangling promise would be
22
+ * killed by process exit before the queue write landed, which is worse than
23
+ * being slow. One second buys the two listing processes plus a log for each
24
+ * branch that actually moved, and an overrun simply stops: the next turn
25
+ * retries, and nothing about a snapshot is urgent.
26
+ */
27
+ export declare const SNAPSHOT_BUDGET_MS = 1000;
28
+ /**
29
+ * How long a branch may go unreported before it is sent again unchanged.
30
+ *
31
+ * The heartbeat exists for one case: a tracker connected after the work on a
32
+ * branch was finished. Nothing on the developer's machine will ever change that
33
+ * branch again, so without a periodic re-send the backend would never get
34
+ * another chance to ask a tracker about it.
35
+ */
36
+ export declare const SNAPSHOT_REFRESH_MS: number;
37
+ /**
38
+ * Caps the backend states in its own schema, applied here so nothing is lost.
39
+ *
40
+ * The backend drops an entry it cannot store rather than refusing the snapshot,
41
+ * so an over-long subject sent verbatim would silently cost that commit its
42
+ * row. Truncated, it still names the work — which is all the drafting agent
43
+ * reads it for. The generic scrubber's limit is 8192 characters and says
44
+ * nothing about this contract.
45
+ */
46
+ export declare const SNAPSHOT_MAX_SUBJECT_LENGTH = 200;
47
+ /**
48
+ * The longest branch name the backend stores.
49
+ *
50
+ * A name it cannot store costs that branch its row, and a branch name this long
51
+ * is not a name anyone typed — so it is dropped rather than truncated, which
52
+ * would report work under a name that does not exist.
53
+ */
54
+ export declare const SNAPSHOT_MAX_BRANCH_NAME_LENGTH = 255;
55
+ /** Hex characters kept from the repository digest that names a state file. */
56
+ export declare const SNAPSHOT_STATE_HASH_LENGTH = 32;
@@ -0,0 +1,56 @@
1
+ /**
2
+ * How many branches one snapshot describes.
3
+ *
4
+ * The ten most recently committed: enough to cover what anyone is actually
5
+ * working on, few enough that the listing is one cheap git process and the
6
+ * backend's per-branch transaction count stays bounded.
7
+ */
8
+ export const SNAPSHOT_BRANCH_COUNT = 10;
9
+ /**
10
+ * How many of a branch's own commits travel with it.
11
+ *
12
+ * They become the titles the backend's grouping agent reads, so this is a
13
+ * window on recent work rather than an archive: a branch is described by what
14
+ * has been done on it lately, and the window is what keeps a long-lived branch
15
+ * from accumulating hundreds of rows.
16
+ */
17
+ export const SNAPSHOT_COMMITS_PER_BRANCH = 20;
18
+ /**
19
+ * Total budget for the whole snapshot flow.
20
+ *
21
+ * It is awaited, so it delays the hook's answer — a dangling promise would be
22
+ * killed by process exit before the queue write landed, which is worse than
23
+ * being slow. One second buys the two listing processes plus a log for each
24
+ * branch that actually moved, and an overrun simply stops: the next turn
25
+ * retries, and nothing about a snapshot is urgent.
26
+ */
27
+ export const SNAPSHOT_BUDGET_MS = 1000;
28
+ /**
29
+ * How long a branch may go unreported before it is sent again unchanged.
30
+ *
31
+ * The heartbeat exists for one case: a tracker connected after the work on a
32
+ * branch was finished. Nothing on the developer's machine will ever change that
33
+ * branch again, so without a periodic re-send the backend would never get
34
+ * another chance to ask a tracker about it.
35
+ */
36
+ export const SNAPSHOT_REFRESH_MS = 6 * 60 * 60 * 1000;
37
+ /**
38
+ * Caps the backend states in its own schema, applied here so nothing is lost.
39
+ *
40
+ * The backend drops an entry it cannot store rather than refusing the snapshot,
41
+ * so an over-long subject sent verbatim would silently cost that commit its
42
+ * row. Truncated, it still names the work — which is all the drafting agent
43
+ * reads it for. The generic scrubber's limit is 8192 characters and says
44
+ * nothing about this contract.
45
+ */
46
+ export const SNAPSHOT_MAX_SUBJECT_LENGTH = 200;
47
+ /**
48
+ * The longest branch name the backend stores.
49
+ *
50
+ * A name it cannot store costs that branch its row, and a branch name this long
51
+ * is not a name anyone typed — so it is dropped rather than truncated, which
52
+ * would report work under a name that does not exist.
53
+ */
54
+ export const SNAPSHOT_MAX_BRANCH_NAME_LENGTH = 255;
55
+ /** Hex characters kept from the repository digest that names a state file. */
56
+ export const SNAPSHOT_STATE_HASH_LENGTH = 32;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * What the working copy says the work is: the repository's recent branches,
3
+ * diffed against what was last reported, so a quiet repository costs nothing.
4
+ *
5
+ * The second flow the hook path runs. It exists because the backend's feature
6
+ * layer is an overlay on work items, and a team with no tracker connected has
7
+ * none — the branches on this machine are then the only evidence that a piece
8
+ * of work exists at all.
9
+ */
10
+ export type { BuildSnapshotInput, SelectionInput, SnapshotFlowInput, SnapshotFlowState, SnapshotIdentity, SnapshotPipelineInput, SnapshotQueue, SnapshotState, SnapshotStateEntry, SnapshotStateReader } from './types/snapshot.types.js';
11
+ export { SNAPSHOT_BRANCH_COUNT, SNAPSHOT_BUDGET_MS, SNAPSHOT_COMMITS_PER_BRANCH, SNAPSHOT_REFRESH_MS } from './constants/snapshot.constants.js';
12
+ export { nextSnapshotState, selectChangedBranches } from './branch-selection.js';
13
+ export { budgetedRunner, remainingMs, withinBudget } from './budget.js';
14
+ export { buildRepoSnapshot } from './snapshot-event.js';
15
+ export { runSnapshotPipeline } from './snapshot-pipeline.js';
16
+ export { SnapshotStateStore, emptyState } from './snapshot-state.js';
@@ -0,0 +1,6 @@
1
+ export { SNAPSHOT_BRANCH_COUNT, SNAPSHOT_BUDGET_MS, SNAPSHOT_COMMITS_PER_BRANCH, SNAPSHOT_REFRESH_MS } from './constants/snapshot.constants.js';
2
+ export { nextSnapshotState, selectChangedBranches } from './branch-selection.js';
3
+ export { budgetedRunner, remainingMs, withinBudget } from './budget.js';
4
+ export { buildRepoSnapshot } from './snapshot-event.js';
5
+ export { runSnapshotPipeline } from './snapshot-pipeline.js';
6
+ export { SnapshotStateStore, emptyState } from './snapshot-state.js';
@@ -0,0 +1,17 @@
1
+ import type { RepoSnapshotEvent } from '../events/types/repo-snapshot.types.js';
2
+ import type { BuildSnapshotInput } from './types/snapshot.types.js';
3
+ /**
4
+ * Build the record one repository's changed branches become.
5
+ *
6
+ * The id is derived from the repository, the branch heads, the default branch
7
+ * *and* `captured_at`. The capture time has to be in it: the queue's filename
8
+ * is the event id and the backend deduplicates on the same value, so an id
9
+ * built from heads alone would make every heartbeat of a quiet branch a
10
+ * duplicate of the send before it — and the heartbeat exists precisely to be
11
+ * received again. A retry of one queued event carries its stored capture time
12
+ * and so keeps its id; the next heartbeat captures anew and gets a new one.
13
+ *
14
+ * @param input - Identity, base branch and the branches being described.
15
+ * @returns The snapshot event.
16
+ */
17
+ export declare function buildRepoSnapshot(input: BuildSnapshotInput): RepoSnapshotEvent;
@@ -0,0 +1,66 @@
1
+ import { compact } from '../core/object.js';
2
+ import { deriveEventId, sha256Hex } from '../events/event-id.js';
3
+ import { EVENT_SCHEMA_VERSION } from '../events/constants/events.constants.js';
4
+ import { SNAPSHOT_MAX_BRANCH_NAME_LENGTH, SNAPSHOT_MAX_SUBJECT_LENGTH } from './constants/snapshot.constants.js';
5
+ /**
6
+ * Build the record one repository's changed branches become.
7
+ *
8
+ * The id is derived from the repository, the branch heads, the default branch
9
+ * *and* `captured_at`. The capture time has to be in it: the queue's filename
10
+ * is the event id and the backend deduplicates on the same value, so an id
11
+ * built from heads alone would make every heartbeat of a quiet branch a
12
+ * duplicate of the send before it — and the heartbeat exists precisely to be
13
+ * received again. A retry of one queued event carries its stored capture time
14
+ * and so keeps its id; the next heartbeat captures anew and gets a new one.
15
+ *
16
+ * @param input - Identity, base branch and the branches being described.
17
+ * @returns The snapshot event.
18
+ */
19
+ export function buildRepoSnapshot(input) {
20
+ const { identity, defaultBranch, branches } = input;
21
+ return compact({
22
+ schemaVersion: EVENT_SCHEMA_VERSION,
23
+ id: deriveEventId({
24
+ provider: identity.provider,
25
+ providerEventType: 'repo.snapshot',
26
+ sessionId: identity.sessionId,
27
+ timestamp: identity.capturedAt,
28
+ payloadFingerprint: fingerprint(input)
29
+ }),
30
+ timestamp: identity.capturedAt,
31
+ event: { type: 'repo.snapshot', providerEventType: 'repo.snapshot' },
32
+ agent: { provider: identity.provider, name: identity.agentName },
33
+ session: { id: identity.sessionId, providerId: identity.sessionId },
34
+ developer: identity.installationId ? { installationId: identity.installationId } : undefined,
35
+ provider: identity.provider,
36
+ surface: identity.surface,
37
+ repository: identity.repository,
38
+ developer_id: identity.developerId,
39
+ default_branch: defaultBranch,
40
+ captured_at: identity.capturedAt,
41
+ branches: branches
42
+ // A name the backend cannot store costs that branch its row, and a
43
+ // branch name that long is not a name anyone typed.
44
+ .filter((branch) => branch.name.length <= SNAPSHOT_MAX_BRANCH_NAME_LENGTH)
45
+ .map((branch) => compact({
46
+ name: branch.name,
47
+ head_sha: branch.headSha,
48
+ last_commit_at: branch.lastCommitAt,
49
+ commits: branch.commits.map((commit) => compact({
50
+ sha: commit.sha,
51
+ subject: commit.subject.slice(0, SNAPSHOT_MAX_SUBJECT_LENGTH),
52
+ authored_at: commit.authoredAt
53
+ }))
54
+ }))
55
+ });
56
+ }
57
+ /**
58
+ * What makes this send different from the one before it.
59
+ *
60
+ * @param input - Identity, base branch and branches.
61
+ * @returns A digest over repository, default branch, heads and capture time.
62
+ */
63
+ function fingerprint(input) {
64
+ const heads = input.branches.map((branch) => `${branch.name}@${branch.headSha}`).sort();
65
+ return sha256Hex(JSON.stringify([input.identity.repository, input.defaultBranch ?? '', heads, input.identity.capturedAt]));
66
+ }
@@ -0,0 +1,14 @@
1
+ import type { FlowResult } from '../core/types/core.types.js';
2
+ import type { SnapshotFlowState, SnapshotPipelineInput } from './types/snapshot.types.js';
3
+ export type { SnapshotFlowInput, SnapshotFlowState, SnapshotPipelineInput } from './types/snapshot.types.js';
4
+ /**
5
+ * Describe this repository's recent branches, if anything about them changed.
6
+ *
7
+ * Never throws: it runs after the hook's own delivery has finished, and a
8
+ * repository this cannot read is a repository the platform simply learns
9
+ * nothing new about.
10
+ *
11
+ * @param pipeline - Identity and clock, the state cache and the offline queue.
12
+ * @returns The final state and where the flow stopped.
13
+ */
14
+ export declare function runSnapshotPipeline(pipeline: SnapshotPipelineInput): Promise<FlowResult<SnapshotFlowState>>;
@@ -0,0 +1,163 @@
1
+ import { debugLog } from '../core/logger.js';
2
+ import { next, runFlow, step, stop } from '../core/pipe.js';
3
+ import { collectBranchCommits, collectBranchRefs, resolveDefaultBranch } from '../git/repo-snapshot.js';
4
+ import { sanitizeValue } from '../privacy/sanitizer.js';
5
+ import { nextSnapshotState, selectChangedBranches } from './branch-selection.js';
6
+ import { budgetedRunner, remainingMs, withinBudget } from './budget.js';
7
+ import { buildRepoSnapshot } from './snapshot-event.js';
8
+ import { emptyState } from './snapshot-state.js';
9
+ import { SNAPSHOT_BRANCH_COUNT, SNAPSHOT_COMMITS_PER_BRANCH } from './constants/snapshot.constants.js';
10
+ import { STAGE_COLLECT_COMMITS, STAGE_COLLECT_REFS, STAGE_ENQUEUE, STAGE_SANITIZE, STAGE_SELECT_CHANGED, STOP_BUDGET_SPENT, STOP_NOTHING_CHANGED, STOP_NO_EVENT, STOP_NOT_A_REPOSITORY } from './constants/snapshot-stages.constants.js';
11
+ /**
12
+ * The snapshot flow, as the list of stages it is.
13
+ *
14
+ * The order is the whole point of the design: the cache diff runs *before* any
15
+ * `git log`. `for-each-ref` already returns every head, so an ordinary closing
16
+ * turn — where nothing moved — costs two git processes and stops, instead of
17
+ * spending ten logs to discover there was nothing to send.
18
+ */
19
+ const SNAPSHOT_STAGES = [
20
+ step(STAGE_COLLECT_REFS, collectRefs),
21
+ step(STAGE_SELECT_CHANGED, selectChanged),
22
+ step(STAGE_COLLECT_COMMITS, collectCommits),
23
+ step(STAGE_SANITIZE, sanitize),
24
+ step(STAGE_ENQUEUE, enqueue)
25
+ ];
26
+ /**
27
+ * Describe this repository's recent branches, if anything about them changed.
28
+ *
29
+ * Never throws: it runs after the hook's own delivery has finished, and a
30
+ * repository this cannot read is a repository the platform simply learns
31
+ * nothing new about.
32
+ *
33
+ * @param pipeline - Identity and clock, the state cache and the offline queue.
34
+ * @returns The final state and where the flow stopped.
35
+ */
36
+ export function runSnapshotPipeline(pipeline) {
37
+ const initial = {
38
+ input: pipeline.input,
39
+ store: pipeline.store,
40
+ queue: pipeline.queue,
41
+ // Every git call in this flow goes through the budget, not only the logs:
42
+ // the listing and the three fallbacks that resolve a trunk are four
43
+ // sequential seconds of the hook's answer if nothing bounds them.
44
+ run: budgetedRunner(pipeline.input.run, pipeline.input.deadline),
45
+ refs: [],
46
+ selected: [],
47
+ branches: []
48
+ };
49
+ return runFlow(SNAPSHOT_STAGES, initial, (trace) => {
50
+ if (trace.outcome === 'next')
51
+ return;
52
+ debugLog(`snapshot flow ${trace.outcome} at ${trace.step}${trace.reason ? `: ${trace.reason}` : ''}`);
53
+ });
54
+ }
55
+ /**
56
+ * The recent branches and what this repository calls its trunk.
57
+ *
58
+ * @param state - Current flow state.
59
+ * @returns The state with its refs, or a stop outside a repository.
60
+ */
61
+ async function collectRefs(state) {
62
+ const { cwd } = state.input;
63
+ const refs = await collectBranchRefs({ cwd, branchCount: SNAPSHOT_BRANCH_COUNT }, state.run);
64
+ if (refs.length === 0)
65
+ return stop(state, STOP_NOT_A_REPOSITORY);
66
+ const defaultBranch = await resolveDefaultBranch(cwd, state.run);
67
+ return next({ ...state, refs, defaultBranch });
68
+ }
69
+ /**
70
+ * Compare the heads against what was last sent.
71
+ *
72
+ * @param state - Current flow state.
73
+ * @returns The state with its selection, or a stop when nothing is due.
74
+ */
75
+ async function selectChanged(state) {
76
+ const stored = await state.store.read(state.input.repository);
77
+ const selected = selectChangedBranches(selectionInput({ ...state, stored }));
78
+ if (selected.length === 0)
79
+ return stop({ ...state, stored }, STOP_NOTHING_CHANGED);
80
+ return next({ ...state, stored, selected });
81
+ }
82
+ /**
83
+ * The commits each selected branch has that the trunk does not.
84
+ *
85
+ * The budget is checked per branch rather than once: the listing is cheap and
86
+ * the logs are not, so an overrun stops here with the branches already
87
+ * described rather than discarding the work.
88
+ *
89
+ * @param state - Current flow state.
90
+ * @returns The state with its branches, or a stop when the budget ran out
91
+ * before any branch was described.
92
+ */
93
+ async function collectCommits(state) {
94
+ const { cwd, deadline } = state.input;
95
+ const branches = [];
96
+ for (const ref of state.selected) {
97
+ if (remainingMs(deadline) === 0)
98
+ break;
99
+ const commits = await collectBranchCommits(ref.name, { cwd, defaultBranch: state.defaultBranch, commitCount: SNAPSHOT_COMMITS_PER_BRANCH }, state.run);
100
+ branches.push({ ...ref, commits });
101
+ }
102
+ if (branches.length === 0)
103
+ return stop(state, STOP_BUDGET_SPENT);
104
+ return next({ ...state, branches });
105
+ }
106
+ /**
107
+ * Build the event and put it through the same scrubber prompt text gets.
108
+ *
109
+ * Branch names and commit subjects are written by people who did not expect
110
+ * them to be transmitted, and a token pasted into a commit message is exactly
111
+ * the kind of thing this catches.
112
+ *
113
+ * @param state - Current flow state.
114
+ * @returns The state carrying the event to send.
115
+ */
116
+ async function sanitize(state) {
117
+ const event = buildRepoSnapshot({
118
+ identity: state.input,
119
+ defaultBranch: state.defaultBranch,
120
+ branches: state.branches
121
+ });
122
+ return next({ ...state, event: sanitizeValue(event) });
123
+ }
124
+ /**
125
+ * Queue the event, then record what was sent.
126
+ *
127
+ * The cache is written only after the queue accepted the event. Written first,
128
+ * a failed enqueue would mark the branches as reported and nothing would ever
129
+ * offer them again.
130
+ *
131
+ * @param state - Current flow state.
132
+ * @returns The state, unchanged.
133
+ */
134
+ async function enqueue(state) {
135
+ if (!state.event)
136
+ return stop(state, STOP_NO_EVENT);
137
+ const { deadline } = state.input;
138
+ const queued = await withinBudget(state.queue.enqueue([state.event]), deadline);
139
+ // Recording a send that may not have happened is the one thing this flow must
140
+ // never do: the branches would be marked reported and never offered again.
141
+ if (!queued)
142
+ return stop(state, STOP_BUDGET_SPENT);
143
+ await withinBudget(state.store.write(state.input.repository, nextSnapshotState(selectionInput(state), state.branches)), deadline);
144
+ return next(state);
145
+ }
146
+ /**
147
+ * The selection's view of this flow.
148
+ *
149
+ * Built once so the write-back cannot disagree with the comparison that chose
150
+ * the branches — they read the same refs, the same stored state and the same
151
+ * clock, or a branch could be selected against one and recorded against another.
152
+ *
153
+ * @param state - Current flow state, with its stored state already read.
154
+ * @returns What both the selection and the write-back are decided on.
155
+ */
156
+ function selectionInput(state) {
157
+ return {
158
+ refs: state.refs,
159
+ stored: state.stored ?? emptyState(),
160
+ defaultBranch: state.defaultBranch,
161
+ now: Date.parse(state.input.capturedAt)
162
+ };
163
+ }
@@ -0,0 +1,55 @@
1
+ import type { SnapshotState } from './types/snapshot.types.js';
2
+ export type { SnapshotState, SnapshotStateEntry } from './types/snapshot.types.js';
3
+ /**
4
+ * What the last snapshot of each repository reported.
5
+ *
6
+ * The point of the whole file: a closing turn on a repository where nothing has
7
+ * moved must cost one `for-each-ref` and no event at all. Without it every turn
8
+ * would resend ten branches and the backend would spend a transaction per
9
+ * branch confirming that it already knew.
10
+ *
11
+ * One file per repository, keyed by a hash of its identity so a remote URL
12
+ * never becomes a path on disk. Read tolerantly and rewritten whole: this is a
13
+ * cache, and losing it costs one redundant snapshot, which the backend absorbs.
14
+ */
15
+ export declare class SnapshotStateStore {
16
+ readonly snapshotsDir: string;
17
+ /**
18
+ * Bind the store to its state root.
19
+ *
20
+ * @param snapshotsDir - Directory the per-repository files live in.
21
+ */
22
+ constructor(snapshotsDir: string);
23
+ /**
24
+ * What was last sent for one repository.
25
+ *
26
+ * @param repository - Sanitized repository identity.
27
+ * @returns The stored state, or an empty one when there is none or it is
28
+ * unreadable — an unreadable cache means "send everything", never a failure.
29
+ */
30
+ read(repository: string): Promise<SnapshotState>;
31
+ /**
32
+ * Record what has just been queued.
33
+ *
34
+ * Written after the event reaches the queue and never before: a state file
35
+ * updated ahead of a failed enqueue would mark a branch as sent that nobody
36
+ * ever received, and nothing would ever offer it again.
37
+ *
38
+ * @param repository - Sanitized repository identity.
39
+ * @param state - What was reported for it.
40
+ */
41
+ write(repository: string, state: SnapshotState): Promise<void>;
42
+ /**
43
+ * Path of one repository's state file.
44
+ *
45
+ * @param repository - Sanitized repository identity.
46
+ * @returns Absolute file path.
47
+ */
48
+ private file;
49
+ }
50
+ /**
51
+ * The state of a repository nothing has been sent for.
52
+ *
53
+ * @returns An empty state, which selects every branch.
54
+ */
55
+ export declare function emptyState(): SnapshotState;
@@ -0,0 +1,100 @@
1
+ import path from 'node:path';
2
+ import { asRecord } from '../core/object.js';
3
+ import { sha256Hex } from '../events/event-id.js';
4
+ import { writeFileAtomic } from '../storage/atomic-file.js';
5
+ import { readJsonFile } from '../storage/json-file.js';
6
+ import { SNAPSHOT_STATE_HASH_LENGTH } from './constants/snapshot.constants.js';
7
+ /**
8
+ * What the last snapshot of each repository reported.
9
+ *
10
+ * The point of the whole file: a closing turn on a repository where nothing has
11
+ * moved must cost one `for-each-ref` and no event at all. Without it every turn
12
+ * would resend ten branches and the backend would spend a transaction per
13
+ * branch confirming that it already knew.
14
+ *
15
+ * One file per repository, keyed by a hash of its identity so a remote URL
16
+ * never becomes a path on disk. Read tolerantly and rewritten whole: this is a
17
+ * cache, and losing it costs one redundant snapshot, which the backend absorbs.
18
+ */
19
+ export class SnapshotStateStore {
20
+ snapshotsDir;
21
+ /**
22
+ * Bind the store to its state root.
23
+ *
24
+ * @param snapshotsDir - Directory the per-repository files live in.
25
+ */
26
+ constructor(snapshotsDir) {
27
+ this.snapshotsDir = snapshotsDir;
28
+ }
29
+ /**
30
+ * What was last sent for one repository.
31
+ *
32
+ * @param repository - Sanitized repository identity.
33
+ * @returns The stored state, or an empty one when there is none or it is
34
+ * unreadable — an unreadable cache means "send everything", never a failure.
35
+ */
36
+ async read(repository) {
37
+ const result = await readJsonFile(this.file(repository));
38
+ if (result.state !== 'ok')
39
+ return emptyState();
40
+ const record = asRecord(result.value);
41
+ if (!record)
42
+ return emptyState();
43
+ return {
44
+ defaultBranch: typeof record.defaultBranch === 'string' ? record.defaultBranch : undefined,
45
+ branches: readEntries(record.branches)
46
+ };
47
+ }
48
+ /**
49
+ * Record what has just been queued.
50
+ *
51
+ * Written after the event reaches the queue and never before: a state file
52
+ * updated ahead of a failed enqueue would mark a branch as sent that nobody
53
+ * ever received, and nothing would ever offer it again.
54
+ *
55
+ * @param repository - Sanitized repository identity.
56
+ * @param state - What was reported for it.
57
+ */
58
+ async write(repository, state) {
59
+ await writeFileAtomic(this.file(repository), JSON.stringify(state));
60
+ }
61
+ /**
62
+ * Path of one repository's state file.
63
+ *
64
+ * @param repository - Sanitized repository identity.
65
+ * @returns Absolute file path.
66
+ */
67
+ file(repository) {
68
+ return path.join(this.snapshotsDir, `${sha256Hex(repository).slice(0, SNAPSHOT_STATE_HASH_LENGTH)}.json`);
69
+ }
70
+ }
71
+ /**
72
+ * Branch entries out of a stored record, ignoring anything malformed.
73
+ *
74
+ * @param value - The `branches` field as read from disk.
75
+ * @returns Entries by branch name.
76
+ */
77
+ function readEntries(value) {
78
+ const record = asRecord(value);
79
+ if (!record)
80
+ return {};
81
+ const entries = {};
82
+ for (const [name, raw] of Object.entries(record)) {
83
+ const entry = asRecord(raw);
84
+ if (!entry || typeof entry.headSha !== 'string')
85
+ continue;
86
+ entries[name] = {
87
+ headSha: entry.headSha,
88
+ lastSentAt: typeof entry.lastSentAt === 'number' ? entry.lastSentAt : 0
89
+ };
90
+ }
91
+ return entries;
92
+ }
93
+ /**
94
+ * The state of a repository nothing has been sent for.
95
+ *
96
+ * @returns An empty state, which selects every branch.
97
+ */
98
+ export function emptyState() {
99
+ return { branches: {} };
100
+ }