@agent-watch-ai/edge 0.2.5 → 0.3.1

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 (346) hide show
  1. package/CHANGELOG.md +512 -0
  2. package/README.md +217 -96
  3. package/SECURITY.md +69 -0
  4. package/dist/billing/session-billing.d.ts +19 -0
  5. package/dist/billing/session-billing.js +52 -0
  6. package/dist/cli/args.d.ts +10 -0
  7. package/dist/cli/args.js +20 -0
  8. package/dist/cli/constants/cli.constants.d.ts +50 -4
  9. package/dist/cli/constants/cli.constants.js +54 -5
  10. package/dist/cli/context.d.ts +33 -2
  11. package/dist/cli/context.js +84 -14
  12. package/dist/cli/doctor.js +309 -32
  13. package/dist/cli/hook-check.d.ts +23 -0
  14. package/dist/cli/hook-check.js +114 -0
  15. package/dist/cli/hook.js +118 -7
  16. package/dist/cli/index.d.ts +3 -1
  17. package/dist/cli/index.js +3 -1
  18. package/dist/cli/misc.d.ts +11 -0
  19. package/dist/cli/misc.js +80 -4
  20. package/dist/cli/npx-install.d.ts +37 -0
  21. package/dist/cli/npx-install.js +79 -0
  22. package/dist/cli/open-browser.d.ts +39 -0
  23. package/dist/cli/open-browser.js +62 -0
  24. package/dist/cli/setup.d.ts +17 -8
  25. package/dist/cli/setup.js +439 -98
  26. package/dist/cli/status.js +82 -13
  27. package/dist/cli/toggle.d.ts +9 -0
  28. package/dist/cli/toggle.js +113 -0
  29. package/dist/cli/types/cli.types.d.ts +37 -3
  30. package/dist/cli/ui.d.ts +7 -0
  31. package/dist/cli/ui.js +10 -1
  32. package/dist/cli/uninstall.js +39 -2
  33. package/dist/cli/update.d.ts +17 -0
  34. package/dist/cli/update.js +76 -0
  35. package/dist/cli.js +100 -13
  36. package/dist/config/config-store.d.ts +57 -0
  37. package/dist/config/config-store.js +250 -12
  38. package/dist/config/config.d.ts +53 -6
  39. package/dist/config/config.js +66 -6
  40. package/dist/config/constants/config.constants.d.ts +113 -6
  41. package/dist/config/constants/config.constants.js +126 -8
  42. package/dist/config/destination.d.ts +24 -0
  43. package/dist/config/destination.js +33 -0
  44. package/dist/config/index.d.ts +7 -4
  45. package/dist/config/index.js +5 -3
  46. package/dist/config/repo-config.d.ts +11 -7
  47. package/dist/config/repo-config.js +64 -15
  48. package/dist/config/root-config.d.ts +72 -0
  49. package/dist/config/root-config.js +170 -0
  50. package/dist/config/schemas/config.schema.d.ts +721 -84
  51. package/dist/config/schemas/config.schema.js +388 -15
  52. package/dist/config/types/config.types.d.ts +15 -1
  53. package/dist/config/types/destination.types.d.ts +8 -0
  54. package/dist/core/async.d.ts +36 -0
  55. package/dist/core/async.js +68 -0
  56. package/dist/core/index.d.ts +1 -1
  57. package/dist/core/index.js +1 -1
  58. package/dist/core/object.d.ts +5 -0
  59. package/dist/core/object.js +9 -4
  60. package/dist/core/pipe.d.ts +0 -13
  61. package/dist/core/pipe.js +1 -9
  62. package/dist/core/types/core.types.d.ts +9 -0
  63. package/dist/core/types/core.types.js +0 -3
  64. package/dist/core/which.d.ts +14 -0
  65. package/dist/core/which.js +43 -3
  66. package/dist/credentials/budget.d.ts +9 -0
  67. package/dist/credentials/budget.js +16 -0
  68. package/dist/credentials/command-runner.d.ts +16 -0
  69. package/dist/credentials/command-runner.js +37 -0
  70. package/dist/credentials/constants/credentials.constants.d.ts +111 -0
  71. package/dist/credentials/constants/credentials.constants.js +112 -0
  72. package/dist/credentials/credential-status.d.ts +14 -0
  73. package/dist/credentials/credential-status.js +34 -0
  74. package/dist/credentials/credentials.d.ts +72 -0
  75. package/dist/credentials/credentials.js +253 -0
  76. package/dist/credentials/device-api.d.ts +64 -0
  77. package/dist/credentials/device-api.js +150 -0
  78. package/dist/credentials/device-state.d.ts +31 -0
  79. package/dist/credentials/device-state.js +51 -0
  80. package/dist/credentials/identity.d.ts +62 -0
  81. package/dist/credentials/identity.js +90 -0
  82. package/dist/credentials/index.d.ts +7 -0
  83. package/dist/credentials/index.js +5 -0
  84. package/dist/credentials/migration.d.ts +46 -0
  85. package/dist/credentials/migration.js +164 -0
  86. package/dist/credentials/schemas/device-api.schema.d.ts +77 -0
  87. package/dist/credentials/schemas/device-api.schema.js +33 -0
  88. package/dist/credentials/schemas/device-state.schema.d.ts +51 -0
  89. package/dist/credentials/schemas/device-state.schema.js +20 -0
  90. package/dist/credentials/secret-store.d.ts +54 -0
  91. package/dist/credentials/secret-store.js +217 -0
  92. package/dist/credentials/sign-in.d.ts +18 -0
  93. package/dist/credentials/sign-in.js +86 -0
  94. package/dist/credentials/token-refresher.d.ts +39 -0
  95. package/dist/credentials/token-refresher.js +185 -0
  96. package/dist/credentials/types/credentials.types.d.ts +195 -0
  97. package/dist/credentials/types/credentials.types.js +1 -0
  98. package/dist/enforcement/constants/enforcement.constants.d.ts +47 -1
  99. package/dist/enforcement/constants/enforcement.constants.js +56 -0
  100. package/dist/enforcement/decision-cache.d.ts +20 -1
  101. package/dist/enforcement/decision-cache.js +65 -2
  102. package/dist/enforcement/decision-client.d.ts +9 -8
  103. package/dist/enforcement/decision-client.js +62 -16
  104. package/dist/enforcement/enforcement.d.ts +23 -2
  105. package/dist/enforcement/enforcement.js +103 -15
  106. package/dist/enforcement/index.d.ts +4 -3
  107. package/dist/enforcement/index.js +3 -2
  108. package/dist/enforcement/types/enforcement.types.d.ts +64 -0
  109. package/dist/enrollment/constants/enrollment.constants.d.ts +2 -6
  110. package/dist/enrollment/constants/enrollment.constants.js +2 -6
  111. package/dist/enrollment/enrollment.d.ts +16 -0
  112. package/dist/enrollment/enrollment.js +54 -0
  113. package/dist/enrollment/index.d.ts +3 -7
  114. package/dist/enrollment/index.js +1 -1
  115. package/dist/enrollment/types/enrollment.types.d.ts +9 -13
  116. package/dist/events/constants/enrich.constants.d.ts +15 -0
  117. package/dist/events/constants/enrich.constants.js +15 -0
  118. package/dist/events/constants/events.constants.d.ts +6 -2
  119. package/dist/events/constants/events.constants.js +5 -1
  120. package/dist/events/enrich.js +92 -10
  121. package/dist/events/event-id.d.ts +0 -8
  122. package/dist/events/event-id.js +0 -10
  123. package/dist/events/index.d.ts +2 -2
  124. package/dist/events/index.js +1 -1
  125. package/dist/events/product-event.d.ts +9 -6
  126. package/dist/events/types/repo-snapshot.types.d.ts +7 -0
  127. package/dist/events/types/session-billing.types.d.ts +16 -0
  128. package/dist/events/types/session-billing.types.js +1 -0
  129. package/dist/feature/constants/feature.constants.d.ts +7 -0
  130. package/dist/feature/constants/feature.constants.js +7 -0
  131. package/dist/feature/index.d.ts +1 -1
  132. package/dist/feature/index.js +1 -1
  133. package/dist/feature/ticket-candidates.d.ts +14 -0
  134. package/dist/feature/ticket-candidates.js +26 -8
  135. package/dist/git/blob-hash.d.ts +21 -0
  136. package/dist/git/blob-hash.js +69 -0
  137. package/dist/git/checkout-root.d.ts +27 -0
  138. package/dist/git/checkout-root.js +75 -0
  139. package/dist/git/constants/git.constants.d.ts +160 -0
  140. package/dist/git/constants/git.constants.js +181 -0
  141. package/dist/git/fingerprint.d.ts +74 -0
  142. package/dist/git/fingerprint.js +219 -0
  143. package/dist/git/gate-checkout.d.ts +44 -0
  144. package/dist/git/gate-checkout.js +201 -0
  145. package/dist/git/git-context.d.ts +45 -0
  146. package/dist/git/git-context.js +61 -3
  147. package/dist/git/index.d.ts +4 -2
  148. package/dist/git/index.js +2 -1
  149. package/dist/git/manifest-repository.d.ts +13 -0
  150. package/dist/git/manifest-repository.js +92 -0
  151. package/dist/git/repo-snapshot.d.ts +29 -3
  152. package/dist/git/repo-snapshot.js +110 -7
  153. package/dist/git/repository-root.d.ts +39 -0
  154. package/dist/git/repository-root.js +131 -0
  155. package/dist/git/types/git.types.d.ts +55 -0
  156. package/dist/git/types/repository-root.types.d.ts +11 -0
  157. package/dist/git/types/repository-root.types.js +1 -0
  158. package/dist/git/types/snapshot.types.d.ts +9 -0
  159. package/dist/pipeline/constants/pipeline.constants.d.ts +7 -0
  160. package/dist/pipeline/constants/pipeline.constants.js +7 -0
  161. package/dist/pipeline/hook-pipeline.js +360 -32
  162. package/dist/pipeline/types/pipeline.types.d.ts +39 -4
  163. package/dist/privacy/constants/privacy.constants.js +15 -1
  164. package/dist/privacy/index.d.ts +1 -0
  165. package/dist/privacy/index.js +1 -0
  166. package/dist/privacy/product-capture.d.ts +12 -0
  167. package/dist/privacy/product-capture.js +73 -0
  168. package/dist/privacy/sanitizer.d.ts +21 -3
  169. package/dist/privacy/sanitizer.js +52 -8
  170. package/dist/process/ancestors.d.ts +39 -0
  171. package/dist/process/ancestors.js +121 -0
  172. package/dist/process/constants/process.constants.d.ts +34 -0
  173. package/dist/process/constants/process.constants.js +34 -0
  174. package/dist/process/index.d.ts +7 -0
  175. package/dist/process/index.js +2 -0
  176. package/dist/process/types/process.types.d.ts +23 -0
  177. package/dist/process/types/process.types.js +1 -0
  178. package/dist/providers/antigravity/antigravity.adapter.d.ts +12 -1
  179. package/dist/providers/antigravity/antigravity.adapter.js +21 -3
  180. package/dist/providers/antigravity/antigravity.detect.d.ts +0 -9
  181. package/dist/providers/antigravity/antigravity.detect.js +1 -1
  182. package/dist/providers/antigravity/antigravity.provider.js +3 -2
  183. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +2 -0
  184. package/dist/providers/antigravity/constants/antigravity.constants.js +2 -0
  185. package/dist/providers/claude/claude.adapter.d.ts +11 -1
  186. package/dist/providers/claude/claude.adapter.js +26 -5
  187. package/dist/providers/claude/claude.otel.d.ts +32 -18
  188. package/dist/providers/claude/claude.otel.js +81 -6
  189. package/dist/providers/claude/claude.provider.js +5 -2
  190. package/dist/providers/claude/constants/claude.constants.d.ts +2 -0
  191. package/dist/providers/claude/constants/claude.constants.js +2 -0
  192. package/dist/providers/claude/constants/claude.otel.constants.d.ts +4 -0
  193. package/dist/providers/claude/constants/claude.otel.constants.js +8 -0
  194. package/dist/providers/codex/codex.adapter.d.ts +15 -1
  195. package/dist/providers/codex/codex.adapter.js +29 -5
  196. package/dist/providers/codex/codex.otel.d.ts +24 -2
  197. package/dist/providers/codex/codex.otel.js +147 -30
  198. package/dist/providers/codex/codex.provider.js +5 -2
  199. package/dist/providers/codex/constants/codex.constants.d.ts +2 -0
  200. package/dist/providers/codex/constants/codex.constants.js +16 -0
  201. package/dist/providers/codex/constants/codex.otel.constants.d.ts +5 -0
  202. package/dist/providers/codex/constants/codex.otel.constants.js +5 -0
  203. package/dist/providers/constants/provider.constants.d.ts +0 -3
  204. package/dist/providers/constants/provider.constants.js +0 -3
  205. package/dist/providers/cursor/constants/cursor.constants.d.ts +7 -0
  206. package/dist/providers/cursor/constants/cursor.constants.js +7 -0
  207. package/dist/providers/cursor/cursor.adapter.d.ts +33 -1
  208. package/dist/providers/cursor/cursor.adapter.js +52 -3
  209. package/dist/providers/cursor/cursor.detect.d.ts +0 -7
  210. package/dist/providers/cursor/cursor.detect.js +1 -1
  211. package/dist/providers/cursor/cursor.provider.js +5 -2
  212. package/dist/providers/gemini/constants/gemini.constants.d.ts +9 -0
  213. package/dist/providers/gemini/constants/gemini.constants.js +9 -0
  214. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +3 -1
  215. package/dist/providers/gemini/constants/gemini.otel.constants.js +3 -0
  216. package/dist/providers/gemini/gemini.adapter.d.ts +14 -1
  217. package/dist/providers/gemini/gemini.adapter.js +25 -5
  218. package/dist/providers/gemini/gemini.detect.d.ts +0 -7
  219. package/dist/providers/gemini/gemini.detect.js +1 -1
  220. package/dist/providers/gemini/gemini.otel.d.ts +19 -20
  221. package/dist/providers/gemini/gemini.otel.js +121 -17
  222. package/dist/providers/gemini/gemini.provider.js +2 -1
  223. package/dist/providers/index.d.ts +1 -1
  224. package/dist/providers/index.js +1 -1
  225. package/dist/providers/loaders.d.ts +10 -0
  226. package/dist/providers/loaders.js +40 -0
  227. package/dist/providers/provider.d.ts +11 -0
  228. package/dist/providers/provider.js +1 -1
  229. package/dist/providers/registry.d.ts +11 -8
  230. package/dist/providers/registry.js +11 -15
  231. package/dist/providers/shared/constants/hook-refusal.constants.d.ts +7 -0
  232. package/dist/providers/shared/constants/hook-refusal.constants.js +7 -0
  233. package/dist/providers/shared/constants/shell-directories.constants.d.ts +30 -0
  234. package/dist/providers/shared/constants/shell-directories.constants.js +39 -0
  235. package/dist/providers/shared/constants/tooling.constants.d.ts +18 -2
  236. package/dist/providers/shared/constants/tooling.constants.js +19 -3
  237. package/dist/providers/shared/event-builder.d.ts +12 -14
  238. package/dist/providers/shared/event-builder.js +20 -14
  239. package/dist/providers/shared/exporter-allowlist.d.ts +20 -0
  240. package/dist/providers/shared/exporter-allowlist.js +49 -0
  241. package/dist/providers/shared/hook-config.d.ts +2 -21
  242. package/dist/providers/shared/hook-config.js +5 -4
  243. package/dist/providers/shared/hook-refusal.d.ts +12 -0
  244. package/dist/providers/shared/hook-refusal.js +17 -1
  245. package/dist/providers/shared/install-record.d.ts +12 -2
  246. package/dist/providers/shared/install-record.js +5 -2
  247. package/dist/providers/shared/shell-directories.d.ts +24 -0
  248. package/dist/providers/shared/shell-directories.js +90 -0
  249. package/dist/providers/shared/tooling.d.ts +12 -1
  250. package/dist/providers/shared/tooling.js +18 -0
  251. package/dist/providers/shared/types/adapter.types.d.ts +1 -2
  252. package/dist/providers/types/provider.types.d.ts +57 -1
  253. package/dist/snapshot/constants/snapshot.constants.d.ts +32 -0
  254. package/dist/snapshot/constants/snapshot.constants.js +33 -0
  255. package/dist/snapshot/snapshot-event.js +52 -11
  256. package/dist/snapshot/snapshot-pipeline.js +1 -1
  257. package/dist/snapshot/types/snapshot.types.d.ts +2 -0
  258. package/dist/storage/atomic-file.d.ts +7 -0
  259. package/dist/storage/atomic-file.js +1 -1
  260. package/dist/storage/constants/storage.constants.d.ts +17 -0
  261. package/dist/storage/constants/storage.constants.js +17 -0
  262. package/dist/storage/disabled.d.ts +13 -0
  263. package/dist/storage/disabled.js +24 -0
  264. package/dist/storage/index.d.ts +2 -0
  265. package/dist/storage/index.js +2 -0
  266. package/dist/storage/paths.js +3 -2
  267. package/dist/storage/schemas/storage.schema.d.ts +72 -0
  268. package/dist/storage/schemas/storage.schema.js +6 -0
  269. package/dist/storage/sweep-marker.d.ts +19 -0
  270. package/dist/storage/sweep-marker.js +55 -0
  271. package/dist/storage/types/storage.types.d.ts +2 -0
  272. package/dist/storage/uninstalled.d.ts +58 -0
  273. package/dist/storage/uninstalled.js +107 -0
  274. package/dist/transport/auth-block.d.ts +66 -0
  275. package/dist/transport/auth-block.js +129 -0
  276. package/dist/transport/constants/transport.constants.d.ts +82 -3
  277. package/dist/transport/constants/transport.constants.js +83 -4
  278. package/dist/transport/cooldown.js +8 -1
  279. package/dist/transport/delivery.d.ts +14 -6
  280. package/dist/transport/delivery.js +80 -55
  281. package/dist/transport/http-transport.d.ts +1 -0
  282. package/dist/transport/http-transport.js +52 -10
  283. package/dist/transport/index.d.ts +6 -3
  284. package/dist/transport/index.js +3 -0
  285. package/dist/transport/queue-partition.d.ts +91 -0
  286. package/dist/transport/queue-partition.js +143 -0
  287. package/dist/transport/queue.d.ts +99 -20
  288. package/dist/transport/queue.js +210 -69
  289. package/dist/transport/response-body.d.ts +25 -0
  290. package/dist/transport/response-body.js +64 -0
  291. package/dist/transport/send.d.ts +11 -0
  292. package/dist/transport/send.js +17 -0
  293. package/dist/transport/types/delivery-flow.types.d.ts +19 -0
  294. package/dist/transport/types/delivery-flow.types.js +1 -0
  295. package/dist/transport/types/transport.types.d.ts +45 -0
  296. package/dist/turns/claude-transcript.d.ts +19 -1
  297. package/dist/turns/claude-transcript.js +46 -1
  298. package/dist/turns/codex-originator.d.ts +11 -0
  299. package/dist/turns/codex-originator.js +31 -0
  300. package/dist/turns/codex-transcript.d.ts +30 -0
  301. package/dist/turns/codex-transcript.js +88 -0
  302. package/dist/turns/constants/turns.constants.d.ts +141 -5
  303. package/dist/turns/constants/turns.constants.js +155 -5
  304. package/dist/turns/file-identity.d.ts +27 -0
  305. package/dist/turns/file-identity.js +48 -0
  306. package/dist/turns/gemini-transcript.d.ts +30 -0
  307. package/dist/turns/gemini-transcript.js +96 -0
  308. package/dist/turns/index.d.ts +3 -3
  309. package/dist/turns/index.js +1 -1
  310. package/dist/turns/inherited-checkout.d.ts +54 -0
  311. package/dist/turns/inherited-checkout.js +155 -0
  312. package/dist/turns/native-session-titles.d.ts +26 -0
  313. package/dist/turns/native-session-titles.js +102 -0
  314. package/dist/turns/transcript.d.ts +3 -2
  315. package/dist/turns/transcript.js +5 -1
  316. package/dist/turns/turn-state.d.ts +224 -3
  317. package/dist/turns/turn-state.js +456 -21
  318. package/dist/turns/turn-summary.d.ts +1 -14
  319. package/dist/turns/turn-summary.js +87 -51
  320. package/dist/turns/turn-tracker.d.ts +21 -2
  321. package/dist/turns/turn-tracker.js +379 -56
  322. package/dist/turns/types/transcript.types.d.ts +5 -0
  323. package/dist/turns/types/turn-state.types.d.ts +116 -5
  324. package/dist/turns/types/turn-summary.types.d.ts +64 -14
  325. package/dist/turns/types/turn-tracker.types.d.ts +27 -1
  326. package/dist/turns/work-checkout.d.ts +65 -0
  327. package/dist/turns/work-checkout.js +666 -0
  328. package/dist/untraced/constants/untraced.constants.d.ts +31 -0
  329. package/dist/untraced/constants/untraced.constants.js +63 -0
  330. package/dist/untraced/untraced.d.ts +35 -0
  331. package/dist/untraced/untraced.js +105 -0
  332. package/dist/update/constants/update.constants.d.ts +18 -0
  333. package/dist/update/constants/update.constants.js +20 -0
  334. package/dist/update/update-check.d.ts +52 -0
  335. package/dist/update/update-check.js +113 -0
  336. package/docs/AUDIT_PROMPT.md +129 -0
  337. package/docs/DATA_HANDLING.md +648 -0
  338. package/docs/ENTERPRISE_DEPLOYMENT.md +179 -0
  339. package/docs/PERFORMANCE.md +81 -0
  340. package/package.json +14 -4
  341. package/dist/enrollment/enrollment-provider.d.ts +0 -5
  342. package/dist/enrollment/manual-enrollment.d.ts +0 -32
  343. package/dist/enrollment/manual-enrollment.js +0 -72
  344. package/example/README.md +0 -43
  345. package/example/server.mjs +0 -240
  346. /package/dist/{enrollment/enrollment-provider.js → config/types/destination.types.js} +0 -0
@@ -0,0 +1,219 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { asRecord } from '../core/object.js';
4
+ import { GIT_COMMONDIR_FILE, GIT_FINGERPRINT_ARGS, GIT_TIMEOUT_MS, PORCELAIN_V2_DETACHED, PORCELAIN_V2_HEAD_HEADER, PORCELAIN_V2_NO_OID, PORCELAIN_V2_OID_HEADER, PORCELAIN_V2_PATH_FIELD, PORCELAIN_V2_RENAME_KIND, PORCELAIN_V2_UNTRACKED_XY, RE_OBJECT_ID, gitNotAncestorArgs, gitOwnCommitFilesArgs } from './constants/git.constants.js';
5
+ import { findGitDir } from './gate-checkout.js';
6
+ import { runGit } from './git-context.js';
7
+ /**
8
+ * What a checkout looks like right now: HEAD, branch, and every dirty entry
9
+ * with its size and mtime.
10
+ *
11
+ * Two of these, one when a turn first names the checkout and one at its Stop,
12
+ * are how the edge tells which checkout a turn changed without watching any of
13
+ * them: a moved HEAD is a commit, a new or re-stamped dirty entry is an edit,
14
+ * whoever made it — a file tool or a shell command.
15
+ *
16
+ * One git process, taken without optional locks; the sizes are `lstat`s. Any
17
+ * failure is no fingerprint, which costs the checkout its evidence and nothing
18
+ * else.
19
+ *
20
+ * @param root - Checkout root.
21
+ * @param run - Git runner; injectable for tests.
22
+ * @param timeoutMs - Kill budget for the git process.
23
+ * @returns The fingerprint, or undefined when git could not give one.
24
+ */
25
+ export async function fingerprint(root, run = runGit, timeoutMs = GIT_TIMEOUT_MS) {
26
+ const [status, commonDir] = await Promise.all([run(GIT_FINGERPRINT_ARGS, root, timeoutMs), readCommonDir(root)]);
27
+ if (status === undefined)
28
+ return undefined;
29
+ const parsed = parsePorcelainV2(status);
30
+ const stamped = await Promise.all(parsed.entries.map(async ([file, xy]) => [file, await stampEntry(root, file, xy)]));
31
+ return { oid: parsed.oid, unborn: parsed.unborn || undefined, branch: parsed.branch, commonDir, dirty: Object.fromEntries(stamped) };
32
+ }
33
+ /**
34
+ * `git status --porcelain=v2 --branch -z`, read.
35
+ *
36
+ * Renames carry their original path as the next NUL record, which is skipped:
37
+ * the new path is the one that changed. Ignored entries never appear without
38
+ * `--ignored`.
39
+ *
40
+ * @param output - Raw NUL-separated output.
41
+ * @returns HEAD (and whether it is unborn), branch and the dirty entries as `[path, xy]`, in git's order.
42
+ */
43
+ export function parsePorcelainV2(output) {
44
+ const records = output.split('\0');
45
+ const entries = [];
46
+ let oid;
47
+ let unborn = false;
48
+ let branch;
49
+ for (let index = 0; index < records.length; index++) {
50
+ const record = records[index];
51
+ if (record.startsWith(PORCELAIN_V2_OID_HEADER)) {
52
+ const value = record.slice(PORCELAIN_V2_OID_HEADER.length);
53
+ unborn = value === PORCELAIN_V2_NO_OID;
54
+ oid = unborn ? undefined : value;
55
+ continue;
56
+ }
57
+ if (record.startsWith(PORCELAIN_V2_HEAD_HEADER)) {
58
+ const value = record.slice(PORCELAIN_V2_HEAD_HEADER.length);
59
+ branch = value === PORCELAIN_V2_DETACHED ? undefined : value;
60
+ continue;
61
+ }
62
+ const kind = record.slice(0, 1);
63
+ const file = pathField(record, PORCELAIN_V2_PATH_FIELD[kind]);
64
+ if (kind === PORCELAIN_V2_RENAME_KIND)
65
+ index += 1;
66
+ if (!file)
67
+ continue;
68
+ entries.push([file, kind === '?' ? PORCELAIN_V2_UNTRACKED_XY : record.slice(2, 4)]);
69
+ }
70
+ return { oid, unborn, branch, entries };
71
+ }
72
+ /**
73
+ * The paths a turn changed in a checkout's working tree: every dirty entry
74
+ * that is new, re-stamped or gone since the baseline.
75
+ *
76
+ * A file that was already dirty and stayed untouched is not this turn's work,
77
+ * which is the whole difference from reporting `git status`.
78
+ *
79
+ * @param baseline - The checkout when the turn first named it.
80
+ * @param closing - The checkout at the Stop.
81
+ * @returns Repository-relative paths, in the closing fingerprint's order.
82
+ */
83
+ export function dirtyDelta(baseline, closing) {
84
+ const before = new Map(Object.entries(baseline.dirty));
85
+ const changed = [];
86
+ for (const [file, entry] of Object.entries(closing.dirty)) {
87
+ const old = before.get(file);
88
+ before.delete(file);
89
+ if (old && old.xy === entry.xy && old.size === entry.size && old.mtimeMs === entry.mtimeMs && old.ctimeMs === entry.ctimeMs && old.ino === entry.ino)
90
+ continue;
91
+ changed.push(file);
92
+ }
93
+ // Dirty at the start and clean at the end: reverted, or committed (and then
94
+ // also in the commit diff, which the caller unions with this).
95
+ return [...changed, ...before.keys()];
96
+ }
97
+ /**
98
+ * The files of the commits a turn made between two points of one branch.
99
+ *
100
+ * Only commits no remote-tracking ref reaches count, so a pull, a fast-forward
101
+ * or a merge of pushed work brings in none of its files. A `from` that is not an
102
+ * ancestor of `to` (a reset, a rebase) names no commits of the turn's own.
103
+ *
104
+ * @param cwd - Checkout root, or the common git dir of one that vanished.
105
+ * @param from - Where the turn started; undefined when the branch was unborn.
106
+ * @param to - Where it ended: an oid, or a branch ref.
107
+ * @param gitDir - Ask this git dir rather than the one `cwd` would find.
108
+ * @param run - Git runner; injectable for tests.
109
+ * @returns Repository-relative paths; empty when git could not say.
110
+ */
111
+ export async function commitFiles(cwd, from, to, gitDir, run = runGit) {
112
+ const asked = (args) => (gitDir ? ['--git-dir', gitDir, ...args] : args);
113
+ const [diverged, output] = await Promise.all([
114
+ from === undefined ? '' : run(asked(gitNotAncestorArgs(from, to)), cwd, GIT_TIMEOUT_MS),
115
+ run(asked(gitOwnCommitFilesArgs(from, to)), cwd, GIT_TIMEOUT_MS)
116
+ ]);
117
+ // `diverged` is undefined when git failed, which is no proof either way.
118
+ return diverged === '' && output ? [...new Set(output.split('\0').filter(Boolean))] : [];
119
+ }
120
+ /**
121
+ * A fingerprint out of turn state, type-checked field by field.
122
+ *
123
+ * Turn state is a file on disk between hooks; a value that is not the shape
124
+ * this code writes is no baseline, never a throw.
125
+ *
126
+ * @param value - Decoded record field.
127
+ * @returns The fingerprint, or undefined.
128
+ */
129
+ export function asFingerprint(value) {
130
+ const record = asRecord(value);
131
+ const dirty = asRecord(record?.['dirty']);
132
+ if (!record || !dirty)
133
+ return undefined;
134
+ const entries = [];
135
+ for (const [file, raw] of Object.entries(dirty)) {
136
+ const entry = asRecord(raw);
137
+ if (typeof entry?.['xy'] !== 'string')
138
+ continue;
139
+ entries.push([
140
+ file,
141
+ { xy: entry['xy'], size: numberOr(entry['size']), mtimeMs: numberOr(entry['mtimeMs']), ctimeMs: numberOr(entry['ctimeMs']), ino: numberOr(entry['ino']) }
142
+ ]);
143
+ }
144
+ const oid = stringOr(record['oid']);
145
+ const commonDir = stringOr(record['commonDir']);
146
+ return {
147
+ // Both reach a git command line: an oid that is not one could be read as
148
+ // an option, and a relative git dir resolves against nobody knows what.
149
+ oid: oid !== undefined && RE_OBJECT_ID.test(oid) ? oid : undefined,
150
+ unborn: record['unborn'] === true || undefined,
151
+ branch: stringOr(record['branch']),
152
+ commonDir: commonDir !== undefined && path.isAbsolute(commonDir) ? commonDir : undefined,
153
+ dirty: Object.fromEntries(entries)
154
+ };
155
+ }
156
+ /**
157
+ * The git dir every worktree of this checkout's repository shares.
158
+ *
159
+ * Read from disk, no git: a worktree's `.git` file names its own git dir, and
160
+ * that dir's `commondir` file names the shared one. Kept so a turn that removes
161
+ * its worktree can still read what the branch committed.
162
+ *
163
+ * @param root - Checkout root.
164
+ * @returns The common git dir, or undefined when it cannot be read.
165
+ */
166
+ async function readCommonDir(root) {
167
+ try {
168
+ const location = await findGitDir(root);
169
+ if (!location)
170
+ return undefined;
171
+ const pointer = await fs.readFile(path.join(location.gitDir, GIT_COMMONDIR_FILE), 'utf8').catch(() => undefined);
172
+ return pointer === undefined ? location.gitDir : path.resolve(location.gitDir, pointer.trim());
173
+ }
174
+ catch {
175
+ return undefined;
176
+ }
177
+ }
178
+ /**
179
+ * One dirty entry with its size and mtime, when it is still on disk.
180
+ *
181
+ * @param root - Checkout root.
182
+ * @param file - Repository-relative path.
183
+ * @param xy - Its status letters.
184
+ * @returns The entry.
185
+ */
186
+ async function stampEntry(root, file, xy) {
187
+ try {
188
+ const stat = await fs.lstat(path.join(root, file));
189
+ return { xy, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ino: stat.ino };
190
+ }
191
+ catch {
192
+ // Deleted: its status letters are all there is to compare.
193
+ return { xy };
194
+ }
195
+ }
196
+ /**
197
+ * The path of one porcelain v2 entry, which may itself contain spaces.
198
+ *
199
+ * @param record - One NUL-separated record.
200
+ * @param fieldsBefore - How many space-separated fields precede the path.
201
+ * @returns The path, or undefined for a record of a kind this does not read.
202
+ */
203
+ function pathField(record, fieldsBefore) {
204
+ if (fieldsBefore === undefined)
205
+ return undefined;
206
+ let at = -1;
207
+ for (let field = 0; field < fieldsBefore; field++) {
208
+ at = record.indexOf(' ', at + 1);
209
+ if (at === -1)
210
+ return undefined;
211
+ }
212
+ return record.slice(at + 1) || undefined;
213
+ }
214
+ function stringOr(value) {
215
+ return typeof value === 'string' && value !== '' ? value : undefined;
216
+ }
217
+ function numberOr(value) {
218
+ return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
219
+ }
@@ -0,0 +1,44 @@
1
+ import type { GateCheckout, GateCheckoutOptions } from './types/git.types.js';
2
+ export type { GateCheckout } from './types/git.types.js';
3
+ /**
4
+ * Where a gated prompt is happening, as much of it as can be had cheaply.
5
+ *
6
+ * The platform needs a repository and a branch to judge a feature cap, and the
7
+ * gate is the one place in this package measured in milliseconds: it runs before
8
+ * any git context has been collected, between a developer pressing enter and
9
+ * their agent starting. So this reads the working copy instead of asking git —
10
+ * an upward walk for `.git`, then one small file — and pays for a subprocess
11
+ * once per checkout rather than once per prompt.
12
+ *
13
+ * Both fields or neither. A branch alone identifies nothing, because every
14
+ * repository has a `main`, and the platform drops a half-stated pair anyway.
15
+ *
16
+ * Never throws, and answers `undefined` for everything it cannot establish:
17
+ * outside a repository, on a detached HEAD (which names no branch to charge), in
18
+ * a repository with no usable remote, or on any read that fails. The turn is
19
+ * then judged on the developer alone, exactly as it is today.
20
+ *
21
+ * @param options - Working directory, where remembered remotes live, and
22
+ * overrides for the timeout and the git runner.
23
+ * @returns The checkout, or undefined.
24
+ */
25
+ export declare function readGateCheckout(options: GateCheckoutOptions): Promise<GateCheckout | undefined>;
26
+ /** A repository root and the git directory that serves it. */
27
+ export interface GitLocation {
28
+ readonly root: string;
29
+ readonly gitDir: string;
30
+ }
31
+ /**
32
+ * The nearest `.git` at or above a directory.
33
+ *
34
+ * A `.git` *file* rather than a directory is a linked worktree, and it names the
35
+ * real git directory on its one line. Agents work in worktrees often enough that
36
+ * not following it would silently drop the whole case.
37
+ *
38
+ * Exported for the turn tracker, which asks it of every checkout a turn names:
39
+ * the walk is `stat` calls only, so no hook pays a git process for it.
40
+ *
41
+ * @param startDir - Directory the payload happened in.
42
+ * @returns The location, or undefined outside a repository.
43
+ */
44
+ export declare function findGitDir(startDir: string): Promise<GitLocation | undefined>;
@@ -0,0 +1,201 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { debugLog } from '../core/logger.js';
4
+ import { writeFileAtomic } from '../storage/atomic-file.js';
5
+ import { readJsonFile } from '../storage/json-file.js';
6
+ import { sha256Hex } from '../events/event-id.js';
7
+ import { GATE_BRANCH_REF_PREFIX, GATE_GITDIR_PREFIX, GATE_MAX_WALK_DEPTH, GATE_REMOTE_ABSENT_TTL_MS, GATE_REMOTE_MEMO_TTL_MS, GIT_REMOTE_ARGS, GIT_TIMEOUT_MS } from './constants/git.constants.js';
8
+ import { runGit } from './git-context.js';
9
+ import { normalizeRemote } from './remote-sanitize.js';
10
+ /**
11
+ * Where a gated prompt is happening, as much of it as can be had cheaply.
12
+ *
13
+ * The platform needs a repository and a branch to judge a feature cap, and the
14
+ * gate is the one place in this package measured in milliseconds: it runs before
15
+ * any git context has been collected, between a developer pressing enter and
16
+ * their agent starting. So this reads the working copy instead of asking git —
17
+ * an upward walk for `.git`, then one small file — and pays for a subprocess
18
+ * once per checkout rather than once per prompt.
19
+ *
20
+ * Both fields or neither. A branch alone identifies nothing, because every
21
+ * repository has a `main`, and the platform drops a half-stated pair anyway.
22
+ *
23
+ * Never throws, and answers `undefined` for everything it cannot establish:
24
+ * outside a repository, on a detached HEAD (which names no branch to charge), in
25
+ * a repository with no usable remote, or on any read that fails. The turn is
26
+ * then judged on the developer alone, exactly as it is today.
27
+ *
28
+ * @param options - Working directory, where remembered remotes live, and
29
+ * overrides for the timeout and the git runner.
30
+ * @returns The checkout, or undefined.
31
+ */
32
+ export async function readGateCheckout(options) {
33
+ try {
34
+ const gitDir = await findGitDir(options.cwd);
35
+ if (!gitDir)
36
+ return undefined;
37
+ // A remembered checkout that is gone must not lend its name to whatever
38
+ // repository encloses the folder it left.
39
+ if (options.repository !== undefined && gitDir.root !== path.resolve(options.cwd))
40
+ return undefined;
41
+ const branch = await readBranch(gitDir.gitDir);
42
+ if (!branch)
43
+ return undefined;
44
+ const repository = options.repository ?? await resolveRepository(gitDir.root, options);
45
+ if (!repository)
46
+ return undefined;
47
+ return { repository, branch };
48
+ }
49
+ catch (error) {
50
+ debugLog('gate checkout unavailable:', error);
51
+ return undefined;
52
+ }
53
+ }
54
+ /**
55
+ * The nearest `.git` at or above a directory.
56
+ *
57
+ * A `.git` *file* rather than a directory is a linked worktree, and it names the
58
+ * real git directory on its one line. Agents work in worktrees often enough that
59
+ * not following it would silently drop the whole case.
60
+ *
61
+ * Exported for the turn tracker, which asks it of every checkout a turn names:
62
+ * the walk is `stat` calls only, so no hook pays a git process for it.
63
+ *
64
+ * @param startDir - Directory the payload happened in.
65
+ * @returns The location, or undefined outside a repository.
66
+ */
67
+ export async function findGitDir(startDir) {
68
+ let dir = path.resolve(startDir);
69
+ for (let depth = 0; depth < GATE_MAX_WALK_DEPTH; depth++) {
70
+ const candidate = path.join(dir, '.git');
71
+ const found = await readGitEntry(dir, candidate);
72
+ if (found)
73
+ return found;
74
+ const parent = path.dirname(dir);
75
+ if (parent === dir)
76
+ return undefined;
77
+ dir = parent;
78
+ }
79
+ return undefined;
80
+ }
81
+ /**
82
+ * One candidate `.git`, as a directory or as a worktree's pointer file.
83
+ *
84
+ * @param root - The directory holding the candidate.
85
+ * @param candidate - Path of the candidate itself.
86
+ * @returns The location, or undefined when there is nothing usable here.
87
+ */
88
+ async function readGitEntry(root, candidate) {
89
+ let stat;
90
+ try {
91
+ stat = await fs.stat(candidate);
92
+ }
93
+ catch {
94
+ // Not here, or not readable; keep walking.
95
+ return undefined;
96
+ }
97
+ if (stat.isDirectory())
98
+ return { root, gitDir: candidate };
99
+ if (!stat.isFile())
100
+ return undefined;
101
+ const pointer = (await fs.readFile(candidate, 'utf8')).trim();
102
+ if (!pointer.startsWith(GATE_GITDIR_PREFIX))
103
+ return undefined;
104
+ const target = pointer.slice(GATE_GITDIR_PREFIX.length).trim();
105
+ return { root, gitDir: path.resolve(root, target) };
106
+ }
107
+ /**
108
+ * The checked-out branch, from `HEAD`.
109
+ *
110
+ * A symbolic ref names a branch; a bare object id is a detached HEAD, which is
111
+ * work belonging to no branch and therefore to no feature.
112
+ *
113
+ * @param gitDir - The git directory serving this working copy.
114
+ * @returns The branch, or undefined when HEAD names none.
115
+ */
116
+ async function readBranch(gitDir) {
117
+ const head = (await fs.readFile(path.join(gitDir, 'HEAD'), 'utf8')).trim();
118
+ if (!head.startsWith(GATE_BRANCH_REF_PREFIX))
119
+ return undefined;
120
+ return head.slice(GATE_BRANCH_REF_PREFIX.length).trim() || undefined;
121
+ }
122
+ /**
123
+ * The repository's canonical name, memoised per checkout.
124
+ *
125
+ * The one subprocess here, and the reason it is bounded rather than permanent:
126
+ * a remote changes approximately never, but `git remote set-url` does happen,
127
+ * and a memo with no expiry would pin a checkout to its old repository for good.
128
+ *
129
+ * A memo that cannot be read or written costs a subprocess, never an answer.
130
+ *
131
+ * @param root - Repository root.
132
+ * @param options - Data directory, timeout and runner overrides.
133
+ * @returns The normalized remote, or undefined when there is none.
134
+ */
135
+ async function resolveRepository(root, options) {
136
+ const now = options.now?.().getTime() ?? Date.now();
137
+ const file = memoFile(options.checkoutsDir, root);
138
+ const remembered = await readMemo(file, now);
139
+ if (remembered)
140
+ return remembered.repository ?? undefined;
141
+ const run = options.run ?? runGit;
142
+ const raw = await run(GIT_REMOTE_ARGS, root, options.timeoutMs ?? GIT_TIMEOUT_MS);
143
+ const repository = raw ? normalizeRemote(raw) : undefined;
144
+ // The absence is remembered too — it is the case that needed it most, since a
145
+ // checkout that answers nothing would otherwise pay a subprocess for that
146
+ // nothing on every prompt. For much less time, though: from here a missing
147
+ // remote and a git that timed out look the same, so remembering the second for
148
+ // an hour would silence a repository's feature caps for an hour on one slow
149
+ // call.
150
+ await writeMemo(file, repository ?? null, now);
151
+ return repository;
152
+ }
153
+ /**
154
+ * Where one checkout's remote is remembered.
155
+ *
156
+ * Hashed: a root is an absolute path and would otherwise put the developer's
157
+ * directory layout in a filename.
158
+ *
159
+ * @param checkoutsDir - Where remembered remotes live.
160
+ * @param root - Repository root.
161
+ * @returns Absolute file path.
162
+ */
163
+ function memoFile(checkoutsDir, root) {
164
+ return path.join(checkoutsDir, `${sha256Hex(root)}.json`);
165
+ }
166
+ /**
167
+ * The remembered remote, when it is still young enough to use.
168
+ *
169
+ * @param file - Memo file.
170
+ * @param now - Epoch milliseconds.
171
+ * @returns The remote, or undefined on a miss.
172
+ */
173
+ async function readMemo(file, now) {
174
+ const read = await readJsonFile(file);
175
+ if (read.state !== 'ok' || typeof read.value !== 'object' || read.value === null)
176
+ return undefined;
177
+ const entry = read.value;
178
+ const known = typeof entry.repository === 'string' || entry.repository === null;
179
+ if (!known || typeof entry.at !== 'number')
180
+ return undefined;
181
+ const ttlMs = entry.repository === null ? GATE_REMOTE_ABSENT_TTL_MS : GATE_REMOTE_MEMO_TTL_MS;
182
+ if (now - entry.at > ttlMs)
183
+ return undefined;
184
+ return { repository: entry.repository };
185
+ }
186
+ /**
187
+ * Remember one checkout's remote.
188
+ *
189
+ * @param file - Memo file.
190
+ * @param repository - The normalized remote, or null when there is none.
191
+ * @param now - Epoch milliseconds.
192
+ */
193
+ async function writeMemo(file, repository, now) {
194
+ try {
195
+ await writeFileAtomic(file, JSON.stringify({ repository, at: now }));
196
+ }
197
+ catch (error) {
198
+ // A remote that cannot be remembered is still a remote.
199
+ debugLog('could not remember the checkout remote:', error);
200
+ }
201
+ }
@@ -24,6 +24,39 @@ export declare function collectGitContext(options: GitContextOptions, run?: GitR
24
24
  * @returns The configured email, or undefined outside git / when unset.
25
25
  */
26
26
  export declare function gitUserEmail(cwd: string, options?: GitUserEmailOptions): Promise<string | undefined>;
27
+ /**
28
+ * What to call this developer, as opposed to how to key them.
29
+ *
30
+ * The identity above is an address, and an address is not a name. A developer
31
+ * the platform only ever meets through this collector authors no commit, so the
32
+ * one thing that would otherwise name them on the backend never happens and
33
+ * every view prints their address at people instead.
34
+ *
35
+ * Deliberately not part of `developerIdentity`: that value is matched against
36
+ * stored policy, and a display name must never be able to change what a turn is
37
+ * keyed on. This is carried beside it and nothing keys on it.
38
+ *
39
+ * @param cwd - Directory to resolve the config from.
40
+ * @param options - Timeout, injected HOME and runner override.
41
+ * @returns The configured name, or undefined outside git / when unset.
42
+ */
43
+ export declare function gitUserName(cwd: string, options?: GitUserEmailOptions): Promise<string | undefined>;
44
+ /**
45
+ * The name to show for this developer, when one is known.
46
+ *
47
+ * Same shape as {@link developerIdentity} and for the same reason: two callers
48
+ * must not disagree. Undefined is a real answer — the backend keeps whatever
49
+ * name it already had rather than being told there is none.
50
+ *
51
+ * Truncated to {@link MAX_DEVELOPER_NAME_LENGTH}: the backend refuses a longer
52
+ * name, and it refuses the turn summary carrying it along with it.
53
+ *
54
+ * @param configuredName - `developerName` from the effective config, if set.
55
+ * @param cwd - Directory to fall back to `git config user.name` in.
56
+ * @param options - Timeout, injected HOME and runner override.
57
+ * @returns The name, or undefined when neither source has one.
58
+ */
59
+ export declare function developerDisplayName(configuredName: string | undefined, cwd: string, options?: GitUserEmailOptions): Promise<string | undefined>;
27
60
  /**
28
61
  * The developer identity attached to a turn — and asked about by the pre-turn
29
62
  * budget check.
@@ -39,6 +72,18 @@ export declare function gitUserEmail(cwd: string, options?: GitUserEmailOptions)
39
72
  * @returns The identity, or undefined when neither source has one.
40
73
  */
41
74
  export declare function developerIdentity(configuredEmail: string | undefined, cwd: string, options?: GitUserEmailOptions): Promise<string | undefined>;
75
+ /**
76
+ * How this repository is named, preferring its remote identity.
77
+ *
78
+ * Only the credential-free normalized remote is ever reported, alongside its
79
+ * hash for backends that want to group without knowing the name. A repository
80
+ * with no usable remote falls back to its directory name.
81
+ *
82
+ * @param root - Repository root path.
83
+ * @param remoteRaw - Raw `remote.origin.url`, when git reported one.
84
+ * @returns The repository/remote/hash fields of the context.
85
+ */
86
+ export declare function repositoryIdentity(root: string, remoteRaw: string | undefined): Pick<GitContext, 'repository' | 'remote' | 'repositoryHash'>;
42
87
  /**
43
88
  * Run one git command, resolving to undefined on any failure.
44
89
  *
@@ -3,7 +3,7 @@ import path from 'node:path';
3
3
  import process from 'node:process';
4
4
  import { debugLog } from '../core/logger.js';
5
5
  import { normalizeRemote, remoteHash } from './remote-sanitize.js';
6
- import { GIT_BRANCH_ARGS, GIT_COMMIT_ARGS, GIT_MAX_BUFFER_BYTES, GIT_REMOTE_ARGS, GIT_REPO_ROOT_ARGS, GIT_STATUS_ARGS, GIT_TIMEOUT_MS, GIT_USER_EMAIL_ARGS, MAX_CHANGED_FILES, PORCELAIN_ESCAPES, PORCELAIN_PREFIX_LENGTH, PORCELAIN_RENAME_SEPARATOR, RE_TRAILING_WHITESPACE, STDOUT_MAXBUFFER_CODE } from './constants/git.constants.js';
6
+ import { GIT_BRANCH_ARGS, GIT_COMMIT_ARGS, GIT_MAX_BUFFER_BYTES, GIT_NO_OPTIONAL_LOCKS, GIT_REMOTE_ARGS, GIT_REPO_ROOT_ARGS, GIT_STATUS_ARGS, GIT_TIMEOUT_MS, GIT_USER_EMAIL_ARGS, GIT_USER_NAME_ARGS, MAX_CHANGED_FILES, MAX_DEVELOPER_NAME_LENGTH, PORCELAIN_ESCAPES, PORCELAIN_PREFIX_LENGTH, PORCELAIN_RENAME_SEPARATOR, RE_TRAILING_WHITESPACE, STDOUT_MAXBUFFER_CODE } from './constants/git.constants.js';
7
7
  /**
8
8
  * Collect repository context for event enrichment.
9
9
  *
@@ -55,6 +55,62 @@ export async function gitUserEmail(cwd, options = {}) {
55
55
  const email = await run(GIT_USER_EMAIL_ARGS, cwd, options.timeoutMs ?? GIT_TIMEOUT_MS, options.home);
56
56
  return email?.trim() || undefined;
57
57
  }
58
+ /**
59
+ * What to call this developer, as opposed to how to key them.
60
+ *
61
+ * The identity above is an address, and an address is not a name. A developer
62
+ * the platform only ever meets through this collector authors no commit, so the
63
+ * one thing that would otherwise name them on the backend never happens and
64
+ * every view prints their address at people instead.
65
+ *
66
+ * Deliberately not part of `developerIdentity`: that value is matched against
67
+ * stored policy, and a display name must never be able to change what a turn is
68
+ * keyed on. This is carried beside it and nothing keys on it.
69
+ *
70
+ * @param cwd - Directory to resolve the config from.
71
+ * @param options - Timeout, injected HOME and runner override.
72
+ * @returns The configured name, or undefined outside git / when unset.
73
+ */
74
+ export async function gitUserName(cwd, options = {}) {
75
+ const run = options.run ?? runGit;
76
+ const name = await run(GIT_USER_NAME_ARGS, cwd, options.timeoutMs ?? GIT_TIMEOUT_MS, options.home);
77
+ return name?.trim() || undefined;
78
+ }
79
+ /**
80
+ * The name to show for this developer, when one is known.
81
+ *
82
+ * Same shape as {@link developerIdentity} and for the same reason: two callers
83
+ * must not disagree. Undefined is a real answer — the backend keeps whatever
84
+ * name it already had rather than being told there is none.
85
+ *
86
+ * Truncated to {@link MAX_DEVELOPER_NAME_LENGTH}: the backend refuses a longer
87
+ * name, and it refuses the turn summary carrying it along with it.
88
+ *
89
+ * @param configuredName - `developerName` from the effective config, if set.
90
+ * @param cwd - Directory to fall back to `git config user.name` in.
91
+ * @param options - Timeout, injected HOME and runner override.
92
+ * @returns The name, or undefined when neither source has one.
93
+ */
94
+ export async function developerDisplayName(configuredName, cwd, options = {}) {
95
+ const configured = configuredName?.trim();
96
+ if (configured)
97
+ return capDeveloperName(configured);
98
+ const name = await gitUserName(cwd, options);
99
+ return name === undefined ? undefined : capDeveloperName(name);
100
+ }
101
+ /**
102
+ * The name at the length the backend will accept.
103
+ *
104
+ * Never returns an empty string: both callers pass a value that already
105
+ * survived a `trim() || undefined`, and slicing a non-empty string cannot
106
+ * empty it.
107
+ *
108
+ * @param name - A trimmed, non-empty name.
109
+ * @returns The name, truncated when it exceeds the contract's limit.
110
+ */
111
+ function capDeveloperName(name) {
112
+ return name.length > MAX_DEVELOPER_NAME_LENGTH ? name.slice(0, MAX_DEVELOPER_NAME_LENGTH) : name;
113
+ }
58
114
  /**
59
115
  * The developer identity attached to a turn — and asked about by the pre-turn
60
116
  * budget check.
@@ -86,7 +142,7 @@ export async function developerIdentity(configuredEmail, cwd, options = {}) {
86
142
  * @param remoteRaw - Raw `remote.origin.url`, when git reported one.
87
143
  * @returns The repository/remote/hash fields of the context.
88
144
  */
89
- function repositoryIdentity(root, remoteRaw) {
145
+ export function repositoryIdentity(root, remoteRaw) {
90
146
  const remote = remoteRaw ? normalizeRemote(remoteRaw) : undefined;
91
147
  if (!remote)
92
148
  return { repository: path.basename(root) };
@@ -195,7 +251,9 @@ function readOctalEscape(inner, start) {
195
251
  */
196
252
  export const runGit = (args, cwd, timeoutMs, home) => new Promise((resolve) => {
197
253
  const env = home ? { ...process.env, HOME: home, XDG_CONFIG_HOME: path.join(home, '.config') } : undefined;
198
- execFile('git', [...args], { cwd, timeout: timeoutMs, maxBuffer: GIT_MAX_BUFFER_BYTES, windowsHide: true, env }, (error, stdout) => {
254
+ // `--no-optional-locks`, on every call the edge makes: a hook must never
255
+ // take `index.lock` from under the agent's own `git commit` in that checkout.
256
+ execFile('git', [GIT_NO_OPTIONAL_LOCKS, ...args], { cwd, timeout: timeoutMs, maxBuffer: GIT_MAX_BUFFER_BYTES, windowsHide: true, env }, (error, stdout) => {
199
257
  // Trailing-only trim: `status --porcelain` lines carry a significant
200
258
  // leading space (" M file"); a full trim() would eat the first character
201
259
  // of the first filename.
@@ -3,7 +3,9 @@
3
3
  * remote credentials stripped before anything is stored or sent.
4
4
  */
5
5
  export type { GitContext, GitContextOptions, GitRunner, GitUserEmailOptions, RemoteParts } from './types/git.types.js';
6
- export type { BranchCommit, BranchRef, SnapshotBranch } from './types/snapshot.types.js';
6
+ export type { BranchCommit, BranchRef, CommitFile, SnapshotBranch } from './types/snapshot.types.js';
7
+ export type { RepositoryRootFinder } from './types/repository-root.types.js';
7
8
  export { collectGitContext, developerIdentity, gitUserEmail, runGit } from './git-context.js';
8
- export { collectBranchCommits, collectBranchRefs, resolveDefaultBranch } from './repo-snapshot.js';
9
+ export { collectBranchCommits, collectBranchRefs, parseCommitFiles, resolveDefaultBranch } from './repo-snapshot.js';
9
10
  export { normalizeRemote, remoteHash, stripRemoteCredentials } from './remote-sanitize.js';
11
+ export { isBeneath, repositoryRootFinder } from './repository-root.js';
package/dist/git/index.js CHANGED
@@ -1,3 +1,4 @@
1
1
  export { collectGitContext, developerIdentity, gitUserEmail, runGit } from './git-context.js';
2
- export { collectBranchCommits, collectBranchRefs, resolveDefaultBranch } from './repo-snapshot.js';
2
+ export { collectBranchCommits, collectBranchRefs, parseCommitFiles, resolveDefaultBranch } from './repo-snapshot.js';
3
3
  export { normalizeRemote, remoteHash, stripRemoteCredentials } from './remote-sanitize.js';
4
+ export { isBeneath, repositoryRootFinder } from './repository-root.js';
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The repository address named by the nearest project manifest at or above a folder.
3
+ *
4
+ * Reads only the address field of each manifest; nothing else from it is kept.
5
+ * ponytail: the TOML files are scanned line by line, not parsed: enough for the
6
+ * one `key = "string"` we want, wrong for multi-line or inline-table forms,
7
+ * which yield nothing rather than a guess. Upgrade path: a TOML parser.
8
+ *
9
+ * @param start - Folder to start from.
10
+ * @param home - The user's home; the walk stops before it (or at the filesystem root).
11
+ * @returns The address as `host/owner/repo`, or undefined.
12
+ */
13
+ export declare function manifestRepository(start: string, home?: string): Promise<string | undefined>;