@leed-ai/git-gateway-contract 0.0.0-stage → 0.1.0

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 (286) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +50 -2
  3. package/dist/behaviour/assertions.d.ts +23 -0
  4. package/dist/behaviour/assertions.js +56 -0
  5. package/dist/behaviour/assertions.js.map +1 -0
  6. package/dist/behaviour/behaviour-case.d.ts +19 -0
  7. package/dist/behaviour/behaviour-case.js +12 -0
  8. package/dist/behaviour/behaviour-case.js.map +1 -0
  9. package/dist/behaviour/behaviour-suite.d.ts +30 -0
  10. package/dist/behaviour/behaviour-suite.js +50 -0
  11. package/dist/behaviour/behaviour-suite.js.map +1 -0
  12. package/dist/behaviour/commit-action-cases.d.ts +4 -0
  13. package/dist/behaviour/commit-action-cases.js +342 -0
  14. package/dist/behaviour/commit-action-cases.js.map +1 -0
  15. package/dist/behaviour/commit-write-cases.d.ts +4 -0
  16. package/dist/behaviour/commit-write-cases.js +234 -0
  17. package/dist/behaviour/commit-write-cases.js.map +1 -0
  18. package/dist/behaviour/fixtures.d.ts +29 -0
  19. package/dist/behaviour/fixtures.js +83 -0
  20. package/dist/behaviour/fixtures.js.map +1 -0
  21. package/dist/behaviour/lifecycle-cases.d.ts +4 -0
  22. package/dist/behaviour/lifecycle-cases.js +158 -0
  23. package/dist/behaviour/lifecycle-cases.js.map +1 -0
  24. package/dist/behaviour/promote-cases.d.ts +4 -0
  25. package/dist/behaviour/promote-cases.js +122 -0
  26. package/dist/behaviour/promote-cases.js.map +1 -0
  27. package/dist/behaviour/read-cases.d.ts +4 -0
  28. package/dist/behaviour/read-cases.js +248 -0
  29. package/dist/behaviour/read-cases.js.map +1 -0
  30. package/dist/behaviour/sync-cases.d.ts +4 -0
  31. package/dist/behaviour/sync-cases.js +205 -0
  32. package/dist/behaviour/sync-cases.js.map +1 -0
  33. package/dist/clock-B3MlpmVY.d.ts +10 -0
  34. package/dist/commit-BEZmeAOl.d.ts +23 -0
  35. package/dist/file-map-CxUveLWz.d.ts +18 -0
  36. package/dist/gateway-config-oVsdTEeK.d.ts +39 -0
  37. package/dist/gateway-error-body-BWzZFAQI.d.ts +214 -0
  38. package/dist/gateway-error.d.ts +30 -0
  39. package/dist/gateway-error.js +63 -0
  40. package/dist/gateway-error.js.map +1 -0
  41. package/dist/git-gateway-VA9Tc5tn.d.ts +358 -0
  42. package/dist/git-gateway.d.ts +2 -0
  43. package/dist/git-gateway.js +65 -0
  44. package/dist/git-gateway.js.map +1 -0
  45. package/dist/health.d.ts +9 -0
  46. package/dist/health.js +18 -0
  47. package/dist/health.js.map +1 -0
  48. package/dist/history-CqvHaUE-.d.ts +20 -0
  49. package/dist/package-name.d.ts +3 -0
  50. package/dist/package-name.js +6 -0
  51. package/dist/package-name.js.map +1 -0
  52. package/dist/proxy/audit-event.d.ts +61 -0
  53. package/dist/proxy/audit-event.js +97 -0
  54. package/dist/proxy/audit-event.js.map +1 -0
  55. package/dist/proxy/branch-rule.d.ts +72 -0
  56. package/dist/proxy/branch-rule.js +106 -0
  57. package/dist/proxy/branch-rule.js.map +1 -0
  58. package/dist/proxy/gateway-hooks.d.ts +58 -0
  59. package/dist/proxy/gateway-hooks.js +0 -0
  60. package/dist/proxy/git-operation.d.ts +17 -0
  61. package/dist/proxy/git-operation.js +32 -0
  62. package/dist/proxy/git-operation.js.map +1 -0
  63. package/dist/proxy/policy-result.d.ts +51 -0
  64. package/dist/proxy/policy-result.js +90 -0
  65. package/dist/proxy/policy-result.js.map +1 -0
  66. package/dist/proxy/principal.d.ts +18 -0
  67. package/dist/proxy/principal.js +32 -0
  68. package/dist/proxy/principal.js.map +1 -0
  69. package/dist/proxy/push-policy-result.d.ts +34 -0
  70. package/dist/proxy/push-policy-result.js +48 -0
  71. package/dist/proxy/push-policy-result.js.map +1 -0
  72. package/dist/proxy/push-policy.d.ts +146 -0
  73. package/dist/proxy/push-policy.js +112 -0
  74. package/dist/proxy/push-policy.js.map +1 -0
  75. package/dist/proxy/request-credential.d.ts +22 -0
  76. package/dist/proxy/request-credential.js +46 -0
  77. package/dist/proxy/request-credential.js.map +1 -0
  78. package/dist/proxy/smart-http-config.d.ts +22 -0
  79. package/dist/proxy/smart-http-config.js +40 -0
  80. package/dist/proxy/smart-http-config.js.map +1 -0
  81. package/dist/reference/apply-actions.d.ts +9 -0
  82. package/dist/reference/apply-actions.js +84 -0
  83. package/dist/reference/apply-actions.js.map +1 -0
  84. package/dist/reference/branch-methods.d.ts +7 -0
  85. package/dist/reference/branch-methods.js +105 -0
  86. package/dist/reference/branch-methods.js.map +1 -0
  87. package/dist/reference/bytes.d.ts +22 -0
  88. package/dist/reference/bytes.js +62 -0
  89. package/dist/reference/bytes.js.map +1 -0
  90. package/dist/reference/clock.d.ts +2 -0
  91. package/dist/reference/clock.js +18 -0
  92. package/dist/reference/clock.js.map +1 -0
  93. package/dist/reference/commit-method.d.ts +5 -0
  94. package/dist/reference/commit-method.js +83 -0
  95. package/dist/reference/commit-method.js.map +1 -0
  96. package/dist/reference/file-map.d.ts +2 -0
  97. package/dist/reference/file-map.js +24 -0
  98. package/dist/reference/file-map.js.map +1 -0
  99. package/dist/reference/hash.d.ts +10 -0
  100. package/dist/reference/hash.js +25 -0
  101. package/dist/reference/hash.js.map +1 -0
  102. package/dist/reference/history.d.ts +2 -0
  103. package/dist/reference/history.js +65 -0
  104. package/dist/reference/history.js.map +1 -0
  105. package/dist/reference/lifecycle-methods.d.ts +9 -0
  106. package/dist/reference/lifecycle-methods.js +48 -0
  107. package/dist/reference/lifecycle-methods.js.map +1 -0
  108. package/dist/reference/read-methods.d.ts +13 -0
  109. package/dist/reference/read-methods.js +68 -0
  110. package/dist/reference/read-methods.js.map +1 -0
  111. package/dist/reference/reference-gateway.d.ts +18 -0
  112. package/dist/reference/reference-gateway.js +35 -0
  113. package/dist/reference/reference-gateway.js.map +1 -0
  114. package/dist/reference/repo-state.d.ts +43 -0
  115. package/dist/reference/repo-state.js +45 -0
  116. package/dist/reference/repo-state.js.map +1 -0
  117. package/dist/reference/run-method.d.ts +13 -0
  118. package/dist/reference/run-method.js +15 -0
  119. package/dist/reference/run-method.js.map +1 -0
  120. package/dist/reference/three-way-merge.d.ts +16 -0
  121. package/dist/reference/three-way-merge.js +45 -0
  122. package/dist/reference/three-way-merge.js.map +1 -0
  123. package/dist/reference/trailer.d.ts +7 -0
  124. package/dist/reference/trailer.js +16 -0
  125. package/dist/reference/trailer.js.map +1 -0
  126. package/dist/reference/tree-index.d.ts +2 -0
  127. package/dist/reference/tree-index.js +66 -0
  128. package/dist/reference/tree-index.js.map +1 -0
  129. package/dist/reference/write-commit.d.ts +15 -0
  130. package/dist/reference/write-commit.js +44 -0
  131. package/dist/reference/write-commit.js.map +1 -0
  132. package/dist/rpc/commit-exists.d.ts +16 -0
  133. package/dist/rpc/commit-exists.js +30 -0
  134. package/dist/rpc/commit-exists.js.map +1 -0
  135. package/dist/rpc/commit.d.ts +172 -0
  136. package/dist/rpc/commit.js +115 -0
  137. package/dist/rpc/commit.js.map +1 -0
  138. package/dist/rpc/list-tree.d.ts +59 -0
  139. package/dist/rpc/list-tree.js +54 -0
  140. package/dist/rpc/list-tree.js.map +1 -0
  141. package/dist/rpc/log.d.ts +35 -0
  142. package/dist/rpc/log.js +41 -0
  143. package/dist/rpc/log.js.map +1 -0
  144. package/dist/rpc/mint-read-token.d.ts +17 -0
  145. package/dist/rpc/mint-read-token.js +36 -0
  146. package/dist/rpc/mint-read-token.js.map +1 -0
  147. package/dist/rpc/promote.d.ts +39 -0
  148. package/dist/rpc/promote.js +69 -0
  149. package/dist/rpc/promote.js.map +1 -0
  150. package/dist/rpc/read-file.d.ts +44 -0
  151. package/dist/rpc/read-file.js +56 -0
  152. package/dist/rpc/read-file.js.map +1 -0
  153. package/dist/rpc/repo-lifecycle.d.ts +39 -0
  154. package/dist/rpc/repo-lifecycle.js +64 -0
  155. package/dist/rpc/repo-lifecycle.js.map +1 -0
  156. package/dist/rpc/resolve-ref.d.ts +15 -0
  157. package/dist/rpc/resolve-ref.js +28 -0
  158. package/dist/rpc/resolve-ref.js.map +1 -0
  159. package/dist/rpc/sync-branch.d.ts +107 -0
  160. package/dist/rpc/sync-branch.js +114 -0
  161. package/dist/rpc/sync-branch.js.map +1 -0
  162. package/dist/schemas/commit-action.d.ts +100 -0
  163. package/dist/schemas/commit-action.js +138 -0
  164. package/dist/schemas/commit-action.js.map +1 -0
  165. package/dist/schemas/commit.d.ts +2 -0
  166. package/dist/schemas/commit.js +24 -0
  167. package/dist/schemas/commit.js.map +1 -0
  168. package/dist/schemas/content-encoding.d.ts +24 -0
  169. package/dist/schemas/content-encoding.js +41 -0
  170. package/dist/schemas/content-encoding.js.map +1 -0
  171. package/dist/schemas/examples.d.ts +38 -0
  172. package/dist/schemas/examples.js +32 -0
  173. package/dist/schemas/examples.js.map +1 -0
  174. package/dist/schemas/gateway-config.d.ts +2 -0
  175. package/dist/schemas/gateway-config.js +72 -0
  176. package/dist/schemas/gateway-config.js.map +1 -0
  177. package/dist/schemas/gateway-error-body.d.ts +2 -0
  178. package/dist/schemas/gateway-error-body.js +188 -0
  179. package/dist/schemas/gateway-error-body.js.map +1 -0
  180. package/dist/schemas/identity.d.ts +21 -0
  181. package/dist/schemas/identity.js +40 -0
  182. package/dist/schemas/identity.js.map +1 -0
  183. package/dist/schemas/names.d.ts +26 -0
  184. package/dist/schemas/names.js +58 -0
  185. package/dist/schemas/names.js.map +1 -0
  186. package/dist/schemas/ref-update.d.ts +10 -0
  187. package/dist/schemas/ref-update.js +25 -0
  188. package/dist/schemas/ref-update.js.map +1 -0
  189. package/dist/schemas/sha.d.ts +8 -0
  190. package/dist/schemas/sha.js +14 -0
  191. package/dist/schemas/sha.js.map +1 -0
  192. package/dist/schemas/tree-entry.d.ts +2 -0
  193. package/dist/schemas/tree-entry.js +62 -0
  194. package/dist/schemas/tree-entry.js.map +1 -0
  195. package/dist/storage/git-remote.d.ts +17 -0
  196. package/dist/storage/git-remote.js +31 -0
  197. package/dist/storage/git-remote.js.map +1 -0
  198. package/dist/storage/storage-backend.d.ts +61 -0
  199. package/dist/storage/storage-backend.js +0 -0
  200. package/dist/storage/storage-errors.d.ts +12 -0
  201. package/dist/storage/storage-errors.js +22 -0
  202. package/dist/storage/storage-errors.js.map +1 -0
  203. package/dist/storage/storage-input.d.ts +7 -0
  204. package/dist/storage/storage-input.js +14 -0
  205. package/dist/storage/storage-input.js.map +1 -0
  206. package/dist/storage/storage-read.d.ts +13 -0
  207. package/dist/storage/storage-read.js +30 -0
  208. package/dist/storage/storage-read.js.map +1 -0
  209. package/dist/storage/storage-repo-info.d.ts +16 -0
  210. package/dist/storage/storage-repo-info.js +30 -0
  211. package/dist/storage/storage-repo-info.js.map +1 -0
  212. package/dist/storage/storage-tree-entry.d.ts +21 -0
  213. package/dist/storage/storage-tree-entry.js +17 -0
  214. package/dist/storage/storage-tree-entry.js.map +1 -0
  215. package/dist/tree-entry-BM_1gou1.d.ts +41 -0
  216. package/dist/tree-index-Bk721Phv.d.ts +14 -0
  217. package/package.json +401 -4
  218. package/src/behaviour/assertions.ts +75 -0
  219. package/src/behaviour/behaviour-case.ts +28 -0
  220. package/src/behaviour/behaviour-suite.ts +76 -0
  221. package/src/behaviour/commit-action-cases.ts +253 -0
  222. package/src/behaviour/commit-write-cases.ts +205 -0
  223. package/src/behaviour/fixtures.ts +103 -0
  224. package/src/behaviour/lifecycle-cases.ts +104 -0
  225. package/src/behaviour/promote-cases.ts +78 -0
  226. package/src/behaviour/read-cases.ts +176 -0
  227. package/src/behaviour/sync-cases.ts +156 -0
  228. package/src/gateway-error.ts +72 -0
  229. package/src/git-gateway.ts +76 -0
  230. package/src/health.ts +26 -0
  231. package/src/package-name.ts +4 -0
  232. package/src/proxy/audit-event.ts +135 -0
  233. package/src/proxy/branch-rule.ts +190 -0
  234. package/src/proxy/gateway-hooks.ts +67 -0
  235. package/src/proxy/git-operation.ts +36 -0
  236. package/src/proxy/policy-result.ts +127 -0
  237. package/src/proxy/principal.ts +81 -0
  238. package/src/proxy/push-policy-result.ts +86 -0
  239. package/src/proxy/push-policy.ts +158 -0
  240. package/src/proxy/request-credential.ts +47 -0
  241. package/src/proxy/smart-http-config.ts +158 -0
  242. package/src/reference/apply-actions.ts +96 -0
  243. package/src/reference/branch-methods.ts +105 -0
  244. package/src/reference/bytes.ts +66 -0
  245. package/src/reference/clock.ts +19 -0
  246. package/src/reference/commit-method.ts +97 -0
  247. package/src/reference/file-map.ts +35 -0
  248. package/src/reference/hash.ts +25 -0
  249. package/src/reference/history.ts +78 -0
  250. package/src/reference/lifecycle-methods.ts +52 -0
  251. package/src/reference/read-methods.ts +87 -0
  252. package/src/reference/reference-gateway.ts +50 -0
  253. package/src/reference/repo-state.ts +83 -0
  254. package/src/reference/run-method.ts +25 -0
  255. package/src/reference/three-way-merge.ts +42 -0
  256. package/src/reference/trailer.ts +18 -0
  257. package/src/reference/tree-index.ts +65 -0
  258. package/src/reference/write-commit.ts +44 -0
  259. package/src/rpc/commit-exists.ts +46 -0
  260. package/src/rpc/commit.ts +156 -0
  261. package/src/rpc/list-tree.ts +78 -0
  262. package/src/rpc/log.ts +51 -0
  263. package/src/rpc/mint-read-token.ts +59 -0
  264. package/src/rpc/promote.ts +72 -0
  265. package/src/rpc/read-file.ts +75 -0
  266. package/src/rpc/repo-lifecycle.ts +103 -0
  267. package/src/rpc/resolve-ref.ts +41 -0
  268. package/src/rpc/sync-branch.ts +149 -0
  269. package/src/schemas/commit-action.ts +157 -0
  270. package/src/schemas/commit.ts +43 -0
  271. package/src/schemas/content-encoding.ts +58 -0
  272. package/src/schemas/examples.ts +24 -0
  273. package/src/schemas/gateway-config.ts +116 -0
  274. package/src/schemas/gateway-error-body.ts +230 -0
  275. package/src/schemas/identity.ts +57 -0
  276. package/src/schemas/names.ts +126 -0
  277. package/src/schemas/ref-update.ts +38 -0
  278. package/src/schemas/sha.ts +20 -0
  279. package/src/schemas/tree-entry.ts +72 -0
  280. package/src/storage/git-remote.ts +58 -0
  281. package/src/storage/storage-backend.ts +65 -0
  282. package/src/storage/storage-errors.ts +24 -0
  283. package/src/storage/storage-input.ts +14 -0
  284. package/src/storage/storage-read.ts +45 -0
  285. package/src/storage/storage-repo-info.ts +46 -0
  286. package/src/storage/storage-tree-entry.ts +20 -0
@@ -0,0 +1,116 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { z } from 'zod';
3
+
4
+ import { Identity } from './identity.ts';
5
+ import { BranchName } from './names.ts';
6
+
7
+ /** How far back `commit()` looks for a commit carrying the same idempotency key. */
8
+ export const IdempotencyConfig = z
9
+ .object({
10
+ maxCommits: z
11
+ .int()
12
+ .min(1)
13
+ .max(10_000)
14
+ .default(200)
15
+ .describe('Most commits of the branch history examined, newest first; 1–10000, default 200.'),
16
+ maxAgeSeconds: z
17
+ .int()
18
+ .min(60)
19
+ .max(30 * 24 * 3600)
20
+ .default(7 * 24 * 3600)
21
+ .describe(
22
+ 'Commits committed longer ago than this many seconds are not examined; 60 s–30 days, default 7 days (604800).',
23
+ ),
24
+ })
25
+ .strict()
26
+ .meta({
27
+ id: 'IdempotencyConfig',
28
+ title: 'Idempotency window',
29
+ description:
30
+ 'How far back commit() looks through the target branch for a commit carrying the same idempotency key. Both bounds apply; the lookup stops at whichever is reached first.',
31
+ examples: [{ maxCommits: 200, maxAgeSeconds: 604_800 }],
32
+ });
33
+
34
+ /** An idempotency window, inferred from {@link IdempotencyConfig}. */
35
+ export type IdempotencyConfig = z.infer<typeof IdempotencyConfig>;
36
+
37
+ /** An automatic sync run after every push to a branch. */
38
+ export const SyncRule = z
39
+ .object({
40
+ from: BranchName.describe('The branch whose pushes trigger the sync.'),
41
+ into: BranchName.describe('The branch brought up to date with `from` by syncBranch.'),
42
+ })
43
+ .strict()
44
+ .refine((rule) => rule.from !== rule.into, { message: 'from and into must differ', path: ['into'] })
45
+ .meta({
46
+ id: 'SyncRule',
47
+ title: 'Sync rule',
48
+ description:
49
+ 'An onPush rule: after any push to `from`, run syncBranch({ from, into }) as a SyncBranchWorkflow with retries.',
50
+ examples: [{ from: 'main', into: 'staging' }],
51
+ });
52
+
53
+ /** An automatic sync rule, inferred from {@link SyncRule}. */
54
+ export type SyncRule = z.infer<typeof SyncRule>;
55
+
56
+ /** Settings shared by every gateway implementation of the RPC contract. */
57
+ export const GatewayConfig = z
58
+ .object({
59
+ publicBaseUrl: z
60
+ .url({ protocol: /^https?$/ })
61
+ .default('https://git.example.com')
62
+ .describe(
63
+ 'Origin (and optional path prefix) repositories are served under, without a trailing slash; a repository is at <publicBaseUrl>/<repo>.git. Default https://git.example.com.',
64
+ ),
65
+ serviceIdentity: Identity.default({ name: 'git-gateway', email: 'git-gateway@noreply.invalid' }).describe(
66
+ 'Author and committer of commits the gateway makes on its own behalf (sync merges) when the caller names none. Default git-gateway <git-gateway@noreply.invalid>.',
67
+ ),
68
+ idempotency: IdempotencyConfig.default({ maxCommits: 200, maxAgeSeconds: 604_800 }).describe(
69
+ 'Idempotency lookback window; defaults to 200 commits or 7 days.',
70
+ ),
71
+ inlineRetries: z
72
+ .int()
73
+ .min(0)
74
+ .max(10)
75
+ .default(3)
76
+ .describe(
77
+ 'Times a write is rebuilt and retried inline after a stale-head refusal before it is handed to a Workflow; 0–10, default 3.',
78
+ ),
79
+ authCacheSeconds: z
80
+ .int()
81
+ .min(0)
82
+ .max(3600)
83
+ .default(60)
84
+ .describe(
85
+ 'Seconds an authentication and authorization decision is cached per principal and repository; 0 disables caching; at most 3600, default 60.',
86
+ ),
87
+ syncRules: z
88
+ .array(SyncRule)
89
+ .max(50)
90
+ .default([])
91
+ .describe(
92
+ "Branch syncs started after every accepted push to a rule's `from` branch, through the smart-HTTP proxy or an RPC write. The worker starts each as a SyncBranchWorkflow and refuses to start without that Workflow binding when any rule is set; the in-memory reference has no push hooks and ignores them. At most 50, default none.",
93
+ ),
94
+ })
95
+ .strict()
96
+ .meta({
97
+ id: 'GatewayConfig',
98
+ title: 'Gateway configuration',
99
+ description:
100
+ 'Settings shared by every implementation of the RPC contract, the real gateway and the in-memory reference alike. Every field has a default, so {} is a complete configuration.',
101
+ examples: [
102
+ {
103
+ publicBaseUrl: 'https://git.example.com',
104
+ serviceIdentity: { name: 'git-gateway', email: 'git-gateway@noreply.invalid' },
105
+ idempotency: { maxCommits: 200, maxAgeSeconds: 604_800 },
106
+ inlineRetries: 3,
107
+ authCacheSeconds: 60,
108
+ syncRules: [{ from: 'main', into: 'staging' }],
109
+ },
110
+ ],
111
+ });
112
+
113
+ /** A gateway configuration as written (defaults optional). */
114
+ export type GatewayConfigInput = z.input<typeof GatewayConfig>;
115
+ /** A complete gateway configuration, inferred from {@link GatewayConfig}. */
116
+ export type GatewayConfig = z.output<typeof GatewayConfig>;
@@ -0,0 +1,230 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { z } from 'zod';
3
+
4
+ import { BranchName, FilePath, RepoName, Revision } from './names.ts';
5
+ import { Sha } from './sha.ts';
6
+
7
+ const message = z.string().min(1).describe('Human-readable explanation, safe to show to an end user.');
8
+ const repo = RepoName.describe('The repository the call named.');
9
+
10
+ /** Builds one error variant: a code literal, a message and typed details. */
11
+ function variant<const Code extends string, Shape extends z.ZodRawShape>(
12
+ code: Code,
13
+ meaning: string,
14
+ details: Shape,
15
+ example: { message: string; details: z.input<z.ZodObject<Shape>> },
16
+ ) {
17
+ return z
18
+ .object({
19
+ code: z.literal(code).describe(meaning),
20
+ message,
21
+ details: z.object(details).strict().describe(`Machine-readable facts about the ${code} error.`),
22
+ })
23
+ .strict()
24
+ .meta({
25
+ id: `GatewayError.${code}`,
26
+ title: `${code} error`,
27
+ description: meaning,
28
+ examples: [{ code, ...example }],
29
+ });
30
+ }
31
+
32
+ const PATH_EXAMPLE = { path: 'content/about.md' };
33
+ const SHA_A = '1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d';
34
+ const SHA_B = '8f3c2a9e1b7d4c6f0a5e2d9b8c7a6f5e4d3c2b1a';
35
+
36
+ /** The input failed schema validation. */
37
+ export const InvalidInputError = variant(
38
+ 'invalid_input',
39
+ 'The call input failed schema validation; nothing was read or written.',
40
+ {
41
+ issues: z
42
+ .array(
43
+ z
44
+ .object({
45
+ path: z
46
+ .string()
47
+ .describe('Dot-separated location of the bad value in the input; empty for the root.'),
48
+ message: z.string().min(1).describe('What is wrong with the value.'),
49
+ })
50
+ .strict()
51
+ .describe('One validation failure.'),
52
+ )
53
+ .min(1)
54
+ .describe('Every validation failure found.'),
55
+ },
56
+ { message: 'Invalid input', details: { issues: [{ path: 'branch', message: 'Required' }] } },
57
+ );
58
+
59
+ /** The named repository does not exist. */
60
+ export const RepoNotFoundError = variant(
61
+ 'repo_not_found',
62
+ 'The named repository does not exist.',
63
+ { repo },
64
+ { message: 'Repository not found', details: { repo: 'acme' } },
65
+ );
66
+
67
+ /** A repository with that name already exists. */
68
+ export const RepoExistsError = variant(
69
+ 'repo_exists',
70
+ 'createRepo named a repository that already exists; it is left unchanged.',
71
+ { repo },
72
+ { message: 'Repository already exists', details: { repo: 'acme' } },
73
+ );
74
+
75
+ /** The named branch or commit does not exist. */
76
+ export const RefNotFoundError = variant(
77
+ 'ref_not_found',
78
+ 'A branch or commit the call named does not exist in the repository.',
79
+ { ref: Revision.describe('The branch name or commit id that was not found.') },
80
+ { message: 'Branch not found: staging', details: { ref: 'staging' } },
81
+ );
82
+
83
+ /** A create or move target already exists. */
84
+ export const PathExistsError = variant(
85
+ 'path_exists',
86
+ 'A create, upsert or move action targeted a path that is already a file or a directory.',
87
+ { path: FilePath.describe('The path that already exists.') },
88
+ { message: 'File already exists', details: PATH_EXAMPLE },
89
+ );
90
+
91
+ /** An action needed a file that does not exist. */
92
+ export const PathNotFoundError = variant(
93
+ 'path_not_found',
94
+ 'An update, delete, move or chmod action named a path that is not a file.',
95
+ { path: FilePath.describe('The path that is not a file.') },
96
+ { message: 'File not found', details: PATH_EXAMPLE },
97
+ );
98
+
99
+ /** A parent of the target path is a file. */
100
+ export const PathConflictError = variant(
101
+ 'path_conflict',
102
+ 'An action would place a file beneath a path that is itself a file.',
103
+ {
104
+ path: FilePath.describe('The path the action targeted.'),
105
+ conflictingPath: FilePath.describe('The parent of `path` that is a file.'),
106
+ },
107
+ { message: 'A parent of the path is a file', details: { path: 'a/b.md', conflictingPath: 'a' } },
108
+ );
109
+
110
+ /** The branch head is not the head the caller expected. */
111
+ export const StaleHeadError = variant(
112
+ 'stale_head',
113
+ 'The branch head is not the head the caller expected; nothing was written. Re-read and retry.',
114
+ {
115
+ branch: BranchName.describe('The branch the write targeted.'),
116
+ expectedHead: Sha.nullable().describe('The head the caller expected; null when it expected no branch.'),
117
+ actualHead: Sha.nullable().describe('The current head; null when the branch does not exist.'),
118
+ },
119
+ { message: 'Branch head moved', details: { branch: 'main', expectedHead: SHA_A, actualHead: SHA_B } },
120
+ );
121
+
122
+ /** promote named a commit that is not the head of the source branch. */
123
+ export const NotHeadOfSourceError = variant(
124
+ 'not_head_of_source',
125
+ 'promote named a commit that is not the current head of the source branch; nothing moved.',
126
+ {
127
+ from: BranchName.describe('The source branch.'),
128
+ sha: Sha.describe('The commit the caller asked to promote.'),
129
+ head: Sha.describe('The current head of the source branch.'),
130
+ },
131
+ { message: 'Commit is not the head of staging', details: { from: 'staging', sha: SHA_A, head: SHA_B } },
132
+ );
133
+
134
+ /** promote would not be a fast-forward. */
135
+ export const NotFastForwardError = variant(
136
+ 'not_fast_forward',
137
+ 'promote named a commit that does not contain the head of the target branch; nothing moved.',
138
+ {
139
+ into: BranchName.describe('The target branch.'),
140
+ sha: Sha.describe('The commit the caller asked to promote.'),
141
+ head: Sha.describe('The current head of the target branch, which `sha` does not contain.'),
142
+ },
143
+ { message: 'Not a fast-forward', details: { into: 'main', sha: SHA_A, head: SHA_B } },
144
+ );
145
+
146
+ /** syncBranch found no common ancestor. */
147
+ export const UnrelatedHistoriesError = variant(
148
+ 'unrelated_histories',
149
+ 'syncBranch found no common ancestor between the branches, so there is nothing to merge against.',
150
+ {
151
+ from: BranchName.describe('The branch being merged in.'),
152
+ into: BranchName.describe('The branch being brought up to date.'),
153
+ },
154
+ { message: 'Refusing to merge unrelated histories', details: { from: 'main', into: 'staging' } },
155
+ );
156
+
157
+ /** The storage backend failed. */
158
+ export const StorageUnavailableError = variant(
159
+ 'storage_unavailable',
160
+ 'The storage backend failed or timed out; the call may be retried with the same input.',
161
+ { retryable: z.literal(true).describe('Always true: the same call may succeed later.') },
162
+ { message: 'Storage backend unavailable', details: { retryable: true } },
163
+ );
164
+
165
+ /** Every error a gateway call can report, discriminated by `code`. */
166
+ export const GatewayErrorBody = z
167
+ .discriminatedUnion('code', [
168
+ InvalidInputError,
169
+ RepoNotFoundError,
170
+ RepoExistsError,
171
+ RefNotFoundError,
172
+ PathExistsError,
173
+ PathNotFoundError,
174
+ PathConflictError,
175
+ StaleHeadError,
176
+ NotHeadOfSourceError,
177
+ NotFastForwardError,
178
+ UnrelatedHistoriesError,
179
+ StorageUnavailableError,
180
+ ])
181
+ .meta({
182
+ id: 'GatewayErrorBody',
183
+ title: 'Gateway error',
184
+ description:
185
+ 'Every error a gateway call can report, discriminated by `code`, with a message and typed details. Thrown as a GatewayError whose `body` holds it.',
186
+ examples: [{ code: 'repo_not_found', message: 'Repository not found', details: { repo: 'acme' } }],
187
+ });
188
+
189
+ /** A gateway error body, inferred from {@link GatewayErrorBody}. */
190
+ export type GatewayErrorBody = z.infer<typeof GatewayErrorBody>;
191
+
192
+ /** The code of every gateway error; the same set as the `code` branches of {@link GatewayErrorBody}. */
193
+ export const GatewayErrorCode = z
194
+ .enum([
195
+ 'invalid_input',
196
+ 'repo_not_found',
197
+ 'repo_exists',
198
+ 'ref_not_found',
199
+ 'path_exists',
200
+ 'path_not_found',
201
+ 'path_conflict',
202
+ 'stale_head',
203
+ 'not_head_of_source',
204
+ 'not_fast_forward',
205
+ 'unrelated_histories',
206
+ 'storage_unavailable',
207
+ ])
208
+ .meta({
209
+ id: 'GatewayErrorCode',
210
+ title: 'Gateway error code',
211
+ description: 'The machine-readable code of a gateway error.',
212
+ enumDescriptions: {
213
+ invalid_input: 'The input failed schema validation.',
214
+ repo_not_found: 'The named repository does not exist.',
215
+ repo_exists: 'createRepo named an existing repository.',
216
+ ref_not_found: 'A named branch or commit does not exist.',
217
+ path_exists: 'A create, upsert or move target already exists.',
218
+ path_not_found: 'An action needed a file that does not exist.',
219
+ path_conflict: 'A parent of the target path is a file.',
220
+ stale_head: 'The branch head is not the one the caller expected.',
221
+ not_head_of_source: 'promote named a commit that is not the source head.',
222
+ not_fast_forward: 'promote would not be a fast-forward.',
223
+ unrelated_histories: 'syncBranch found no common ancestor.',
224
+ storage_unavailable: 'The storage backend failed; retry later.',
225
+ },
226
+ examples: ['stale_head'],
227
+ });
228
+
229
+ /** The code of a gateway error, inferred from {@link GatewayErrorCode}. */
230
+ export type GatewayErrorCode = z.infer<typeof GatewayErrorCode>;
@@ -0,0 +1,57 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { z } from 'zod';
3
+
4
+ /** A UTC timestamp in ISO 8601 form. */
5
+ export const Timestamp = z.iso.datetime().meta({
6
+ id: 'Timestamp',
7
+ title: 'Timestamp',
8
+ description:
9
+ 'A point in time as an ISO 8601 UTC timestamp ending in "Z", with optional fractional seconds (e.g. 2026-11-20T09:30:00.000Z).',
10
+ examples: ['2026-11-20T09:30:00.000Z'],
11
+ });
12
+
13
+ /** A UTC timestamp, inferred from {@link Timestamp}. */
14
+ export type Timestamp = z.infer<typeof Timestamp>;
15
+
16
+ /** The name and email a commit is attributed to. */
17
+ export const Identity = z
18
+ .object({
19
+ name: z
20
+ .string()
21
+ .min(1)
22
+ .max(255)
23
+ .regex(/^[^<>\n\0]+$/)
24
+ .describe('Display name, 1–255 characters, without "<", ">", newlines or NUL (git cannot store them).'),
25
+ email: z.email().max(255).describe('Email address, at most 255 characters.'),
26
+ })
27
+ .strict()
28
+ .meta({
29
+ id: 'Identity',
30
+ title: 'Identity',
31
+ description: 'The name and email a commit is attributed to, as an author or a committer.',
32
+ examples: [{ name: 'Ada Lovelace', email: 'ada@example.com' }],
33
+ });
34
+
35
+ /** A commit identity, inferred from {@link Identity}. */
36
+ export type Identity = z.infer<typeof Identity>;
37
+
38
+ /** An identity together with when it acted. */
39
+ export const Signature = z
40
+ .object({
41
+ name: Identity.shape.name,
42
+ email: Identity.shape.email,
43
+ date: Timestamp.describe(
44
+ 'When this person authored or committed the change, as an ISO 8601 UTC timestamp.',
45
+ ),
46
+ })
47
+ .strict()
48
+ .meta({
49
+ id: 'Signature',
50
+ title: 'Signature',
51
+ description:
52
+ 'An identity together with the time it authored or committed a commit, as stored in the commit.',
53
+ examples: [{ name: 'Ada Lovelace', email: 'ada@example.com', date: '2026-11-20T09:30:00.000Z' }],
54
+ });
55
+
56
+ /** An identity with a date, inferred from {@link Signature}. */
57
+ export type Signature = z.infer<typeof Signature>;
@@ -0,0 +1,126 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { z } from 'zod';
3
+
4
+ import { Sha } from './sha.ts';
5
+
6
+ /**
7
+ * One or more slash-separated ref components following `git check-ref-format`: no component starts
8
+ * with "." or ends with ".lock", no "..", "@{", "//", control characters, space, ~ ^ : ? * [ or \,
9
+ * not "@" alone, and no trailing "/" or ".".
10
+ */
11
+ const REF_COMPONENTS = String.raw`(?!@$)(?!.*\.\.)(?!.*@\{)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))(?!.*[./]$)[^\x00-\x20\x7f~^:?*[\\.\-/][^\x00-\x20\x7f~^:?*[\\]*`;
12
+
13
+ /** A repository name: one URL path segment, served as `/<name>.git`. */
14
+ export const RepoName = z
15
+ .string()
16
+ .min(1)
17
+ .max(100)
18
+ .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/)
19
+ .refine((name) => !name.toLowerCase().endsWith('.git'), { message: 'must not end with ".git"' })
20
+ .meta({
21
+ id: 'RepoName',
22
+ title: 'Repository name',
23
+ description:
24
+ 'Name of a repository behind the gateway: 1–100 characters of letters, digits, ".", "_" and "-", starting with a letter or digit and not ending in ".git". Served at /<name>.git.',
25
+ examples: ['acme-raw-content', 'site.example'],
26
+ });
27
+
28
+ /** A repository name, inferred from {@link RepoName}. */
29
+ export type RepoName = z.infer<typeof RepoName>;
30
+
31
+ /** A short branch name such as `main` or `feature/x` (never `refs/heads/…`). */
32
+ export const BranchName = z
33
+ .string()
34
+ .min(1)
35
+ .max(255)
36
+ .regex(new RegExp(`^(?!refs/)(?!HEAD$)(?![0-9a-f]{40}$)${REF_COMPONENTS}$`))
37
+ .meta({
38
+ id: 'BranchName',
39
+ title: 'Branch name',
40
+ description:
41
+ 'A short branch name, 1–255 characters, valid under git check-ref-format (no "..", "@{", "//", spaces, control characters or ~ ^ : ? * [ or backslash; no component starting with "." or ending with ".lock"; not starting with "-" or "refs/"; not "HEAD"; not 40 lowercase hex characters, which a Revision always reads as a commit id). The gateway stores it as refs/heads/<name>.',
42
+ examples: ['main', 'staging', 'feature/new-page'],
43
+ });
44
+
45
+ /** A short branch name, inferred from {@link BranchName}. */
46
+ export type BranchName = z.infer<typeof BranchName>;
47
+
48
+ /** A fully qualified ref under `refs/heads/` or `refs/tags/`. */
49
+ export const FullRefName = z
50
+ .string()
51
+ .min(11)
52
+ .max(266)
53
+ .regex(new RegExp(`^refs/(?:heads|tags)/${REF_COMPONENTS}$`))
54
+ .meta({
55
+ id: 'FullRefName',
56
+ title: 'Full ref name',
57
+ description:
58
+ 'A fully qualified ref, "refs/heads/<branch>" or "refs/tags/<tag>", where the name after the prefix follows the same rules as a branch name.',
59
+ examples: ['refs/heads/main', 'refs/tags/v1.0.0'],
60
+ });
61
+
62
+ /** A fully qualified ref, inferred from {@link FullRefName}. */
63
+ export type FullRefName = z.infer<typeof FullRefName>;
64
+
65
+ /** What a read is made against: a commit id or a branch name. */
66
+ export const Revision = z
67
+ .union([
68
+ Sha.describe(
69
+ 'A commit id. Any 40-character lowercase hex string is read as a commit id, never a branch.',
70
+ ),
71
+ BranchName.describe('A branch name, resolved to the branch head at the time of the call.'),
72
+ ])
73
+ .meta({
74
+ id: 'Revision',
75
+ title: 'Revision',
76
+ description:
77
+ 'What a read is made against: a 40-character lowercase hex commit id, or a short branch name resolved to its current head.',
78
+ examples: ['main', '8f3c2a9e1b7d4c6f0a5e2d9b8c7a6f5e4d3c2b1a'],
79
+ });
80
+
81
+ /** A commit id or branch name, inferred from {@link Revision}. */
82
+ export type Revision = z.infer<typeof Revision>;
83
+
84
+ /** A file path inside a repository. */
85
+ export const FilePath = z
86
+ .string()
87
+ .min(1)
88
+ .max(4096)
89
+ // Segments are capped at 255 characters, the limit a tree entry name has, so every committed path
90
+ // can be listed back. Control characters (newline included) are excluded outright, so every lookahead sees the whole
91
+ // string; the "s" flag keeps that true even if the character class is ever loosened. ".git" is
92
+ // matched case-insensitively by its character classes rather than an "i" flag, because JSON Schema
93
+ // "pattern" drops regex flags and the published schema must enforce the same rule.
94
+ .regex(
95
+ new RegExp(
96
+ String.raw`^(?!\/)(?!.*\/\/)(?!.*\/$)(?!(?:.*\/)?[^/]{256})(?!(?:.*\/)?\.\.?(?:\/|$))(?!(?:.*\/)?\.[gG][iI][tT](?:\/|$))[^\x00-\x1f\x7f\\]+$`,
97
+ 's',
98
+ ),
99
+ )
100
+ .meta({
101
+ id: 'FilePath',
102
+ title: 'File path',
103
+ description:
104
+ 'A path inside the repository relative to its root, 1–4096 characters, "/"-separated into segments of 1–255 characters: no leading or trailing "/", no empty, "." or ".." segment, no ".git" segment (any case), no backslash and no control character (U+0000–U+001F, U+007F). Case-sensitive; unicode allowed.',
105
+ examples: ['content/index.md', 'templates/layouts/page.hbs'],
106
+ });
107
+
108
+ /** A file path inside a repository, inferred from {@link FilePath}. */
109
+ export type FilePath = z.infer<typeof FilePath>;
110
+
111
+ /** The key that makes a write idempotent. */
112
+ export const IdempotencyKey = z
113
+ .string()
114
+ .min(1)
115
+ .max(128)
116
+ .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/)
117
+ .meta({
118
+ id: 'IdempotencyKey',
119
+ title: 'Idempotency key',
120
+ description:
121
+ 'Caller-chosen key that makes a commit idempotent: 1–128 characters of letters, digits, ".", "_", ":" and "-", starting with a letter or digit. Recorded as a "Gateway-Idempotency-Key:" trailer; a retried commit carrying a key already in the branch\'s recent history returns that commit instead of writing another.',
122
+ examples: ['cms:publish:2f9c1e', '6f1d2c3b-9a8e-4f7d-b6c5-a4e3d2c1b0a9'],
123
+ });
124
+
125
+ /** An idempotency key, inferred from {@link IdempotencyKey}. */
126
+ export type IdempotencyKey = z.infer<typeof IdempotencyKey>;
@@ -0,0 +1,38 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { z } from 'zod';
3
+
4
+ import { FullRefName } from './names.ts';
5
+ import { Sha } from './sha.ts';
6
+
7
+ /** One ref moved by a write: the command a receive-pack request carries. */
8
+ export const RefUpdate = z
9
+ .object({
10
+ ref: FullRefName.describe('The ref that moved, fully qualified (refs/heads/<branch>).'),
11
+ oldSha: Sha.describe(
12
+ 'Id the ref pointed at before the update; the all-zero id when the update created the ref.',
13
+ ),
14
+ newSha: Sha.describe(
15
+ 'Id the ref points at after the update; the all-zero id when the update deleted the ref.',
16
+ ),
17
+ })
18
+ .strict()
19
+ .refine((update) => update.oldSha !== update.newSha, {
20
+ message: 'an update must change the ref',
21
+ path: ['newSha'],
22
+ })
23
+ .meta({
24
+ id: 'RefUpdate',
25
+ title: 'Ref update',
26
+ description:
27
+ 'One ref moved by a write, in receive-pack command form: the ref, the id it named before and the id it names after. Creation and deletion use the all-zero id on the missing side.',
28
+ examples: [
29
+ {
30
+ ref: 'refs/heads/main',
31
+ oldSha: '1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d',
32
+ newSha: '8f3c2a9e1b7d4c6f0a5e2d9b8c7a6f5e4d3c2b1a',
33
+ },
34
+ ],
35
+ });
36
+
37
+ /** A ref update, inferred from {@link RefUpdate}. */
38
+ export type RefUpdate = z.infer<typeof RefUpdate>;
@@ -0,0 +1,20 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { z } from 'zod';
3
+
4
+ /** A git object id: 40-character lowercase hex SHA-1. */
5
+ export const Sha = z
6
+ .string()
7
+ .regex(/^[0-9a-f]{40}$/)
8
+ .meta({
9
+ id: 'Sha',
10
+ title: 'Object id',
11
+ description:
12
+ 'A git object id: 40-character lowercase hex SHA-1 naming a commit, tree or blob. Never abbreviated.',
13
+ examples: ['8f3c2a9e1b7d4c6f0a5e2d9b8c7a6f5e4d3c2b1a'],
14
+ });
15
+
16
+ /** A git object id, inferred from {@link Sha}. */
17
+ export type Sha = z.infer<typeof Sha>;
18
+
19
+ /** The all-zero object id git uses for "no object". */
20
+ export const ZERO_SHA = '0000000000000000000000000000000000000000';
@@ -0,0 +1,72 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { z } from 'zod';
3
+
4
+ import { FilePath } from './names.ts';
5
+ import { Sha } from './sha.ts';
6
+
7
+ /** The git file mode of a tree entry. */
8
+ export const FileMode = z.enum(['100644', '100755', '120000', '040000', '160000']).meta({
9
+ id: 'FileMode',
10
+ title: 'File mode',
11
+ description: 'The git mode of a tree entry, as the six-digit octal string git records.',
12
+ enumDescriptions: {
13
+ '100644': 'A regular file, not executable.',
14
+ '100755': 'A regular file with the executable bit set.',
15
+ '120000': 'A symbolic link; the blob holds the link target.',
16
+ '040000': 'A directory (a subtree).',
17
+ '160000': 'A submodule; the id names a commit in another repository.',
18
+ },
19
+ examples: ['100644', '040000'],
20
+ });
21
+
22
+ /** A git file mode, inferred from {@link FileMode}. */
23
+ export type FileMode = z.infer<typeof FileMode>;
24
+
25
+ /** The kind of object a tree entry names. */
26
+ export const TreeEntryType = z.enum(['blob', 'tree', 'commit']).meta({
27
+ id: 'TreeEntryType',
28
+ title: 'Tree entry type',
29
+ description: 'The kind of object a tree entry names.',
30
+ enumDescriptions: {
31
+ blob: 'A file or symbolic link (modes 100644, 100755, 120000).',
32
+ tree: 'A directory (mode 040000).',
33
+ commit: 'A submodule commit in another repository (mode 160000).',
34
+ },
35
+ examples: ['blob', 'tree'],
36
+ });
37
+
38
+ /** A tree entry type, inferred from {@link TreeEntryType}. */
39
+ export type TreeEntryType = z.infer<typeof TreeEntryType>;
40
+
41
+ /** One entry of a directory listing. */
42
+ export const TreeEntry = z
43
+ .object({
44
+ path: FilePath.describe('Full path of the entry from the repository root.'),
45
+ name: z
46
+ .string()
47
+ .min(1)
48
+ .max(255)
49
+ .regex(/^[^/\0]+$/)
50
+ .describe('Last segment of the path: 1–255 characters without "/" or NUL.'),
51
+ type: TreeEntryType,
52
+ mode: FileMode,
53
+ sha: Sha.describe('Id of the blob, tree or submodule commit the entry names.'),
54
+ })
55
+ .strict()
56
+ .meta({
57
+ id: 'TreeEntry',
58
+ title: 'Tree entry',
59
+ description: 'One entry of a directory listing: a file, directory, symbolic link or submodule.',
60
+ examples: [
61
+ {
62
+ path: 'content/about.md',
63
+ name: 'about.md',
64
+ type: 'blob',
65
+ mode: '100644',
66
+ sha: 'e69de29bb2d1d6434b8b29ae775ad8c2e48c5391',
67
+ },
68
+ ],
69
+ });
70
+
71
+ /** A tree entry, inferred from {@link TreeEntry}. */
72
+ export type TreeEntry = z.infer<typeof TreeEntry>;