@workerstack/clients 1.0.0-rc.29 → 1.0.0-rc.31

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 (375) hide show
  1. package/README.md +548 -35
  2. package/assets/installers/examples/github.config.ts +17 -19
  3. package/assets/installers/examples/goreleaser.config.ts +16 -18
  4. package/assets/installers/examples/raw.config.ts +13 -15
  5. package/bin/clients.js +88 -68
  6. package/bin/installgen.js +18 -13
  7. package/dist/cli.d.ts +4 -4
  8. package/dist/cli.js +20 -12
  9. package/dist/emit/cli/channels.d.ts +2 -2
  10. package/dist/emit/cli/channels.js +18 -13
  11. package/dist/emit/cli/commands.d.ts +1 -1
  12. package/dist/emit/cli/commands.js +14 -8
  13. package/dist/emit/cli/discovery.d.ts +0 -6
  14. package/dist/emit/cli/discovery.js +9 -7
  15. package/dist/emit/cli/flags.d.ts +1 -3
  16. package/dist/emit/cli/flags.js +11 -5
  17. package/dist/emit/cli/install.d.ts +0 -8
  18. package/dist/emit/cli/install.js +3 -3
  19. package/dist/emit/cli/layout.d.ts +1 -1
  20. package/dist/emit/cli/layout.js +13 -10
  21. package/dist/emit/cli/module.d.ts +6 -6
  22. package/dist/emit/cli/module.js +10 -10
  23. package/dist/emit/cli/release.d.ts +0 -11
  24. package/dist/emit/cli/release.js +4 -4
  25. package/dist/emit/cli/skills.js +3 -3
  26. package/dist/emit/csharp/errors.js +4 -4
  27. package/dist/emit/csharp/json.js +8 -8
  28. package/dist/emit/csharp/realtime.js +3 -3
  29. package/dist/emit/csharp/sdk-answer.js +4 -4
  30. package/dist/emit/csharp/sdk-body.js +8 -6
  31. package/dist/emit/csharp/sdk-client.d.ts +3 -3
  32. package/dist/emit/csharp/sdk-client.js +2 -2
  33. package/dist/emit/csharp/sdk-csproj.d.ts +7 -9
  34. package/dist/emit/csharp/sdk-csproj.js +10 -10
  35. package/dist/emit/csharp/sdk-doc.js +1 -1
  36. package/dist/emit/csharp/sdk-method.d.ts +18 -2
  37. package/dist/emit/csharp/sdk-method.js +24 -9
  38. package/dist/emit/csharp/sdk-plan.js +0 -1
  39. package/dist/emit/csharp/sdk.js +7 -4
  40. package/dist/emit/csharp/sse.d.ts +0 -2
  41. package/dist/emit/csharp/sse.js +7 -7
  42. package/dist/emit/csharp/transport.js +7 -7
  43. package/dist/emit/csharp/types-enum.js +3 -1
  44. package/dist/emit/csharp/types-messages.js +3 -3
  45. package/dist/emit/csharp/types-names.js +10 -12
  46. package/dist/emit/csharp/types-record.js +3 -3
  47. package/dist/emit/csharp/types-union.d.ts +1 -1
  48. package/dist/emit/csharp/types.d.ts +0 -1
  49. package/dist/emit/csharp/types.js +3 -3
  50. package/dist/emit/csharp/ws.js +2 -2
  51. package/dist/emit/go/errors.js +1 -1
  52. package/dist/emit/go/http.js +2 -2
  53. package/dist/emit/go/module-path.js +2 -2
  54. package/dist/emit/go/sdk-answer.js +1 -1
  55. package/dist/emit/go/sdk-body.js +11 -7
  56. package/dist/emit/go/sdk-client.js +1 -1
  57. package/dist/emit/go/sdk-method.d.ts +9 -0
  58. package/dist/emit/go/sdk-method.js +12 -3
  59. package/dist/emit/go/sdk-mirror.js +2 -2
  60. package/dist/emit/go/sdk-opts.d.ts +0 -2
  61. package/dist/emit/go/sdk-opts.js +3 -3
  62. package/dist/emit/go/sdk.d.ts +1 -1
  63. package/dist/emit/go/sdk.js +12 -11
  64. package/dist/emit/go/sse.js +1 -1
  65. package/dist/emit/go/types-names.js +5 -0
  66. package/dist/emit/go/types-struct.d.ts +2 -1
  67. package/dist/emit/go/types-struct.js +1 -1
  68. package/dist/emit/go/types.js +9 -9
  69. package/dist/emit/go/ws.js +6 -6
  70. package/dist/emit/java/gradle.d.ts +7 -9
  71. package/dist/emit/java/gradle.js +8 -8
  72. package/dist/emit/java/json.js +1 -1
  73. package/dist/emit/java/layout-ast.js +1 -1
  74. package/dist/emit/java/layout-decl.js +5 -4
  75. package/dist/emit/java/layout-doc.js +13 -7
  76. package/dist/emit/java/layout-dot.js +1 -1
  77. package/dist/emit/java/layout-strings.js +4 -5
  78. package/dist/emit/java/layout-types.js +7 -5
  79. package/dist/emit/java/layout-visitor.js +4 -3
  80. package/dist/emit/java/layout.js +5 -4
  81. package/dist/emit/java/models-names.js +5 -4
  82. package/dist/emit/java/models-record.d.ts +0 -1
  83. package/dist/emit/java/models-record.js +3 -3
  84. package/dist/emit/java/models-union.d.ts +1 -1
  85. package/dist/emit/java/models-union.js +1 -1
  86. package/dist/emit/java/models.d.ts +1 -2
  87. package/dist/emit/java/models.js +25 -16
  88. package/dist/emit/java/realtime.d.ts +5 -17
  89. package/dist/emit/java/realtime.js +1 -1
  90. package/dist/emit/java/sdk-client.d.ts +6 -6
  91. package/dist/emit/java/sdk-client.js +2 -1
  92. package/dist/emit/java/sdk-decl.js +2 -2
  93. package/dist/emit/java/sdk-errors.js +1 -1
  94. package/dist/emit/java/sdk-headers.js +2 -2
  95. package/dist/emit/java/sdk-mirror.js +2 -2
  96. package/dist/emit/java/sdk-models.d.ts +1 -1
  97. package/dist/emit/java/sdk-models.js +7 -7
  98. package/dist/emit/java/sdk-op.d.ts +7 -11
  99. package/dist/emit/java/sdk-op.js +22 -10
  100. package/dist/emit/java/sdk-params.d.ts +5 -5
  101. package/dist/emit/java/sdk-params.js +3 -2
  102. package/dist/emit/java/sdk-plan.js +0 -1
  103. package/dist/emit/java/sdk.d.ts +1 -1
  104. package/dist/emit/java/sdk.js +21 -14
  105. package/dist/emit/java/sse.d.ts +2 -4
  106. package/dist/emit/java/sse.js +6 -6
  107. package/dist/emit/java/ws.d.ts +2 -2
  108. package/dist/emit/java/ws.js +3 -4
  109. package/dist/emit/mcp/annotations.js +8 -4
  110. package/dist/emit/mcp/files.js +9 -9
  111. package/dist/emit/mcp/mounted.js +2 -2
  112. package/dist/emit/mcp/output-schema.js +3 -3
  113. package/dist/emit/mcp/registry.d.ts +0 -2
  114. package/dist/emit/mcp/registry.js +5 -4
  115. package/dist/emit/mcp/runtime.js +2 -2
  116. package/dist/emit/mcp/schema.js +22 -11
  117. package/dist/emit/mcp/server.d.ts +7 -7
  118. package/dist/emit/mcp/server.js +7 -6
  119. package/dist/emit/mcp/tools.js +7 -6
  120. package/dist/emit/python/errors.js +3 -3
  121. package/dist/emit/python/realtime.js +2 -2
  122. package/dist/emit/python/sdk-answer.d.ts +3 -7
  123. package/dist/emit/python/sdk-answer.js +2 -2
  124. package/dist/emit/python/sdk-body.js +4 -5
  125. package/dist/emit/python/sdk-client.js +5 -5
  126. package/dist/emit/python/sdk-doc.js +2 -2
  127. package/dist/emit/python/sdk-method.d.ts +11 -0
  128. package/dist/emit/python/sdk-method.js +20 -5
  129. package/dist/emit/python/sdk-plan.js +0 -1
  130. package/dist/emit/python/sdk-pyproject.d.ts +0 -2
  131. package/dist/emit/python/sdk-pyproject.js +8 -8
  132. package/dist/emit/python/sdk.d.ts +1 -1
  133. package/dist/emit/python/sdk.js +12 -8
  134. package/dist/emit/python/sse.d.ts +0 -2
  135. package/dist/emit/python/sse.js +2 -2
  136. package/dist/emit/python/transport.js +4 -4
  137. package/dist/emit/python/types-dict.d.ts +2 -2
  138. package/dist/emit/python/types-dict.js +1 -1
  139. package/dist/emit/python/types-names.js +2 -2
  140. package/dist/emit/python/types-union.js +1 -1
  141. package/dist/emit/python/types.js +3 -3
  142. package/dist/emit/python/ws.d.ts +2 -5
  143. package/dist/emit/python/ws.js +4 -4
  144. package/dist/emit/rust/errors.js +3 -3
  145. package/dist/emit/rust/http.js +4 -4
  146. package/dist/emit/rust/realtime.js +2 -2
  147. package/dist/emit/rust/sdk-body.js +8 -5
  148. package/dist/emit/rust/sdk-cargo.d.ts +16 -18
  149. package/dist/emit/rust/sdk-cargo.js +12 -12
  150. package/dist/emit/rust/sdk-client.d.ts +1 -1
  151. package/dist/emit/rust/sdk-client.js +3 -3
  152. package/dist/emit/rust/sdk-method.d.ts +12 -1
  153. package/dist/emit/rust/sdk-method.js +12 -4
  154. package/dist/emit/rust/sdk-opts.d.ts +2 -1
  155. package/dist/emit/rust/sdk-opts.js +2 -2
  156. package/dist/emit/rust/sdk-plan.js +0 -1
  157. package/dist/emit/rust/sdk.d.ts +1 -1
  158. package/dist/emit/rust/sdk.js +9 -6
  159. package/dist/emit/rust/sse.d.ts +0 -5
  160. package/dist/emit/rust/sse.js +2 -2
  161. package/dist/emit/rust/types-names.js +3 -3
  162. package/dist/emit/rust/types-struct.js +1 -1
  163. package/dist/emit/rust/types-union.d.ts +1 -1
  164. package/dist/emit/rust/types.js +7 -5
  165. package/dist/emit/rust/ws.d.ts +0 -11
  166. package/dist/emit/rust/ws.js +5 -5
  167. package/dist/emit/shared/escape.js +17 -17
  168. package/dist/emit/shared/format.js +1 -1
  169. package/dist/emit/shared/gofmt.js +1 -1
  170. package/dist/emit/shared/lang.js +10 -10
  171. package/dist/emit/shared/literals.d.ts +5 -0
  172. package/dist/emit/shared/literals.js +8 -0
  173. package/dist/emit/shared/metadata.d.ts +0 -6
  174. package/dist/emit/shared/metadata.js +8 -7
  175. package/dist/emit/shared/ruff.js +1 -1
  176. package/dist/emit/shared/rustfmt.js +1 -1
  177. package/dist/emit/shared/type-emitter.js +37 -20
  178. package/dist/emit/shared/unknown-type.constants.d.ts +2 -0
  179. package/dist/emit/shared/unknown-type.constants.js +2 -0
  180. package/dist/emit/ts/http.d.ts +8 -2
  181. package/dist/emit/ts/http.js +51 -6
  182. package/dist/emit/ts/package.d.ts +14 -12
  183. package/dist/emit/ts/package.js +10 -8
  184. package/dist/emit/ts/route-tree.js +2 -2
  185. package/dist/emit/ts/sdk-types-preamble.d.ts +1 -1
  186. package/dist/emit/ts/sdk-types-preamble.js +12 -4
  187. package/dist/emit/ts/sdk-types.d.ts +0 -5
  188. package/dist/emit/ts/sdk-types.js +63 -19
  189. package/dist/emit/ts/sdk.d.ts +3 -1
  190. package/dist/emit/ts/sdk.js +44 -12
  191. package/dist/emit/ts/service-map.d.ts +7 -1
  192. package/dist/emit/ts/service-map.js +10 -1
  193. package/dist/emit/ts/single-flight-text.d.ts +3 -0
  194. package/dist/emit/ts/single-flight-text.js +38 -0
  195. package/dist/emit/ts/tanstack-query.d.ts +3 -2
  196. package/dist/emit/ts/tanstack-query.js +60 -35
  197. package/dist/emit/ts/type-gen.js +31 -18
  198. package/dist/emit/ts/webhooks.d.ts +0 -2
  199. package/dist/emit/ts/webhooks.js +3 -3
  200. package/dist/extract/chain.js +5 -4
  201. package/dist/extract/extract.js +5 -5
  202. package/dist/extract/serialize.d.ts +0 -2
  203. package/dist/extract/serialize.js +14 -15
  204. package/dist/extract/walk.js +15 -12
  205. package/dist/gen/args.js +9 -5
  206. package/dist/gen/formatters.js +5 -3
  207. package/dist/gen/process.js +2 -1
  208. package/dist/gen/shipped.js +2 -2
  209. package/dist/gen/switch-on.constants.d.ts +2 -0
  210. package/dist/gen/switch-on.constants.js +2 -0
  211. package/dist/gen/targets.d.ts +6 -7
  212. package/dist/gen/targets.js +11 -6
  213. package/dist/gen/write.js +4 -2
  214. package/dist/index.js +2 -2
  215. package/dist/installers/cli.d.ts +4 -4
  216. package/dist/installers/cli.js +24 -24
  217. package/dist/installers/commands/build.d.ts +4 -4
  218. package/dist/installers/commands/build.js +2 -3
  219. package/dist/installers/commands/check.d.ts +2 -2
  220. package/dist/installers/commands/check.js +11 -10
  221. package/dist/installers/commands/init.d.ts +2 -2
  222. package/dist/installers/commands/init.js +1 -2
  223. package/dist/installers/config/define-config.d.ts +16 -16
  224. package/dist/installers/config/define-config.js +1 -1
  225. package/dist/installers/config/hooks/bun.d.ts +6 -6
  226. package/dist/installers/config/hooks/node.js +1 -1
  227. package/dist/installers/config/load.d.ts +6 -8
  228. package/dist/installers/config/load.js +7 -8
  229. package/dist/installers/config/resolve.d.ts +1 -2
  230. package/dist/installers/config/resolve.js +28 -33
  231. package/dist/installers/config/types.d.ts +6 -6
  232. package/dist/installers/config/types.js +0 -1
  233. package/dist/installers/render/quote.js +3 -5
  234. package/dist/installers/render/render.d.ts +6 -6
  235. package/dist/installers/render/render.js +26 -26
  236. package/dist/installers/ui.d.ts +4 -4
  237. package/dist/installers/ui.js +3 -3
  238. package/dist/ir/build.d.ts +3 -3
  239. package/dist/ir/build.js +8 -5
  240. package/dist/ir/invalidate-reads.d.ts +17 -0
  241. package/dist/ir/invalidate-reads.js +104 -0
  242. package/dist/ir/load.d.ts +10 -0
  243. package/dist/ir/load.js +65 -18
  244. package/dist/ir/model.d.ts +2 -1
  245. package/dist/ir/model.js +0 -1
  246. package/dist/ir/read-method.constants.d.ts +2 -0
  247. package/dist/ir/read-method.constants.js +2 -0
  248. package/dist/ir/resolve-refs.js +2 -2
  249. package/dist/ir/resource-tree.js +2 -1
  250. package/dist/ir/route-tree-intern.js +1 -1
  251. package/dist/ir/schema.js +3 -3
  252. package/dist/ir/sdk-model.js +3 -3
  253. package/dist/ir/slots.js +13 -8
  254. package/dist/ir/streams.js +1 -1
  255. package/dist/release/bootstrap.d.ts +3 -3
  256. package/dist/release/bootstrap.js +7 -7
  257. package/dist/release/bump-args.js +4 -4
  258. package/dist/release/bump-command.d.ts +1 -1
  259. package/dist/release/bump-command.js +9 -10
  260. package/dist/release/bump.d.ts +5 -4
  261. package/dist/release/bump.js +2 -2
  262. package/dist/release/cli.d.ts +4 -4
  263. package/dist/release/cli.js +4 -4
  264. package/dist/release/codegen.js +1 -1
  265. package/dist/release/digest.js +5 -7
  266. package/dist/release/git.js +5 -8
  267. package/dist/release/load.js +4 -4
  268. package/dist/release/manifest.js +9 -10
  269. package/dist/release/oasdiff.d.ts +10 -15
  270. package/dist/release/oasdiff.js +5 -6
  271. package/dist/release/registries.d.ts +0 -11
  272. package/dist/release/registries.js +17 -17
  273. package/dist/release/release-state.d.ts +16 -13
  274. package/dist/release/release-workflow.js +5 -7
  275. package/dist/release/repo-settings.d.ts +2 -1
  276. package/dist/release/spec-gate.d.ts +0 -2
  277. package/dist/release/spec-gate.js +6 -10
  278. package/dist/release/sync-command.d.ts +2 -2
  279. package/dist/release/sync-command.js +1 -1
  280. package/dist/release/sync-tree.js +9 -13
  281. package/dist/release/sync.d.ts +6 -6
  282. package/dist/release/sync.js +12 -13
  283. package/dist/release/types.d.ts +22 -22
  284. package/dist/release/types.js +0 -1
  285. package/dist/release/version-files.d.ts +3 -4
  286. package/dist/release/version-files.js +4 -5
  287. package/dist/runtime/.oxfmtrc.jsonc +8 -0
  288. package/dist/runtime/csharp/Config.cs +9 -1
  289. package/dist/runtime/csharp/Exchange.cs +56 -4
  290. package/dist/runtime/csharp/Hooks.cs +9 -0
  291. package/dist/runtime/csharp/Operation.cs +6 -1
  292. package/dist/runtime/csharp/WsDial.cs +3 -1
  293. package/dist/runtime/go/config.go +5 -0
  294. package/dist/runtime/go/hooks.go +70 -0
  295. package/dist/runtime/go/request.go +6 -2
  296. package/dist/runtime/go/stream.go +4 -1
  297. package/dist/runtime/go/ws.go +3 -1
  298. package/dist/runtime/java/ClientConfig.java +11 -0
  299. package/dist/runtime/java/Flight.java +2 -12
  300. package/dist/runtime/java/Hooks.java +45 -0
  301. package/dist/runtime/java/InvalidateEvent.java +10 -0
  302. package/dist/runtime/java/InvalidateHook.java +12 -0
  303. package/dist/runtime/java/InvalidateTarget.java +7 -0
  304. package/dist/runtime/java/Operation.java +23 -3
  305. package/dist/runtime/java/Realtime.java +3 -1
  306. package/dist/runtime/java/WsDial.java +3 -0
  307. package/dist/runtime/mcp/files.ts +1 -1
  308. package/dist/runtime/mcp/http.ts +6 -2
  309. package/dist/runtime/mcp/listen.ts +1 -1
  310. package/dist/runtime/mcp/mount.ts +2 -2
  311. package/dist/runtime/mcp/protocol.ts +1 -1
  312. package/dist/runtime/python/config.py +8 -2
  313. package/dist/runtime/python/exchange.py +3 -1
  314. package/dist/runtime/python/hooks.py +110 -5
  315. package/dist/runtime/python/operation.py +2 -0
  316. package/dist/runtime/python/send_async.py +14 -2
  317. package/dist/runtime/python/send_sync.py +4 -2
  318. package/dist/runtime/python/ws.py +5 -1
  319. package/dist/runtime/rust/config.rs +6 -1
  320. package/dist/runtime/rust/exchange.rs +15 -3
  321. package/dist/runtime/rust/hooks.rs +127 -2
  322. package/dist/runtime/rust/log.rs +11 -3
  323. package/dist/runtime/rust/request.rs +17 -0
  324. package/dist/runtime/rust/ws.rs +9 -1
  325. package/dist/runtime/ts/config.ts +69 -0
  326. package/dist/runtime/ts/http.ts +12 -10
  327. package/dist/runtime/ts/request.ts +2 -0
  328. package/dist/runtime/ts/response.ts +7 -0
  329. package/dist/runtime/ts/sdk-invalidate.ts +82 -0
  330. package/dist/runtime/ts/sdk-single-flight.constants.ts +25 -0
  331. package/dist/runtime/ts/sdk-single-flight.ts +203 -0
  332. package/dist/runtime/ts/sdk-sse.ts +5 -1
  333. package/dist/runtime/ts/sdk-ws.ts +9 -3
  334. package/dist/runtime/ts/sdk.ts +55 -31
  335. package/dist/runtime/ts/single-flight-batch.ts +184 -0
  336. package/dist/runtime/ts/single-flight-body.ts +59 -0
  337. package/dist/runtime/ts/single-flight-run.ts +160 -0
  338. package/dist/runtime/ts/single-flight.constants.ts +31 -0
  339. package/dist/runtime/ts/single-flight.ts +158 -0
  340. package/dist/runtime/ts-tanstack-query/invalidate.ts +96 -92
  341. package/dist/runtime/ts-tanstack-query/query.ts +140 -170
  342. package/package.json +12 -17
  343. package/references/INDEX.md +31 -0
  344. package/references/cli.md +33 -0
  345. package/references/configuring.md +29 -0
  346. package/references/documentation.md +15 -0
  347. package/references/errors.md +23 -0
  348. package/references/flags.md +104 -0
  349. package/references/gates.md +46 -0
  350. package/references/generate.md +29 -0
  351. package/references/install-scripts.md +28 -0
  352. package/references/install.md +38 -0
  353. package/references/license.md +8 -0
  354. package/references/mcp.md +76 -0
  355. package/references/output.md +45 -0
  356. package/references/overview.md +14 -0
  357. package/references/release-tooling.md +34 -0
  358. package/references/release.md +305 -0
  359. package/references/sdks.md +393 -0
  360. package/references/start.md +22 -0
  361. package/references/tdd.md +16 -0
  362. package/dist/emit/cli/index.d.ts +0 -1
  363. package/dist/emit/cli/index.js +0 -1
  364. package/dist/emit/csharp/index.d.ts +0 -1
  365. package/dist/emit/csharp/index.js +0 -1
  366. package/dist/emit/go/index.d.ts +0 -1
  367. package/dist/emit/go/index.js +0 -1
  368. package/dist/emit/java/index.d.ts +0 -2
  369. package/dist/emit/java/index.js +0 -2
  370. package/dist/emit/mcp/index.d.ts +0 -3
  371. package/dist/emit/mcp/index.js +0 -3
  372. package/dist/emit/python/index.d.ts +0 -1
  373. package/dist/emit/python/index.js +0 -1
  374. package/dist/emit/rust/index.d.ts +0 -1
  375. package/dist/emit/rust/index.js +0 -1
package/README.md CHANGED
@@ -1,26 +1,17 @@
1
- # @workerstack/clients
1
+ <!-- @generated by @workerstack/repo -->
2
2
 
3
- Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a Go command-line client and a Model Context Protocol
4
- server from an OpenAPI 3.x document, or straight from a
5
- [`@workerstack/backend`](https://www.npmjs.com/package/@workerstack/backend) app.
3
+ # @workerstack/clients
6
4
 
7
- Every target reads one intermediate representation and vendors its own small runtime, so a generated SDK has no
8
- dependency on backend, and a spec from another framework generates just as well. The output is formatted and
9
- deterministic: regenerating an unchanged spec changes nothing on disk.
5
+ Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a CLI and an MCP server from any OpenAPI 3.x document.
10
6
 
11
- This page is the whole generator — every target, every flag, and what each client looks like to call.
7
+ ## Contents
12
8
 
9
+ - [What it generates](#what-it-generates)
13
10
  - [Install](#install)
14
11
  - [Start](#start)
15
12
  - [clients generate](#clients-generate)
16
13
  - [Every flag](#every-flag)
17
14
  - [The six SDKs](#the-six-sdks)
18
- - [The TypeScript SDK](#the-typescript-sdk)
19
- - [The Go SDK](#the-go-sdk)
20
- - [The Rust SDK](#the-rust-sdk)
21
- - [The Python SDK](#the-python-sdk)
22
- - [The C# SDK](#the-c-sdk)
23
- - [The Java SDK](#the-java-sdk)
24
15
  - [Errors and the safe mirror](#errors-and-the-safe-mirror)
25
16
  - [The command-line client](#the-command-line-client)
26
17
  - [Install scripts](#install-scripts)
@@ -29,8 +20,21 @@ This page is the whole generator — every target, every flag, and what each cli
29
20
  - [Configuring generation](#configuring-generation)
30
21
  - [What a run writes](#what-a-run-writes)
31
22
  - [Documentation](#documentation)
23
+ - [Releasing a product's public packages](#releasing-a-products-public-packages)
24
+ - [Gates](#gates)
25
+ - [Red, fix, green](#red-fix-green)
32
26
  - [License](#license)
33
27
 
28
+ ## What it generates
29
+
30
+ Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a Go command-line client and a Model Context Protocol
31
+ server from an OpenAPI 3.x document, or straight from a
32
+ [`@workerstack/backend`](https://www.npmjs.com/package/@workerstack/backend) app.
33
+
34
+ Every target reads one intermediate representation and vendors its own small runtime, so a generated SDK has no
35
+ dependency on backend, and a spec from another framework generates just as well. The output is formatted and
36
+ deterministic: regenerating an unchanged spec changes nothing on disk.
37
+
34
38
  ## Install
35
39
 
36
40
  backend moved to the workerstack org in 1.0.0-rc.23, and [the migration note](https://github.com/workerstack/backend/blob/main/docs/migrating-from-honey.md)
@@ -124,6 +128,7 @@ One table, since a flag that is not written down is a flag nobody finds:
124
128
  | `--ts-stem` | ts | the file stem the generated modules share |
125
129
  | `--ts-package-name` | ts | the npm name, and the JSR name when scoped; the stem by default |
126
130
  | `--ts-version` | ts | the version both registries carry; the document's by default |
131
+ | `--ts-single-flight` | ts | also write the single-flight handler; takes no value |
127
132
  | `--ts-tanstack-query` | ts | also write the TanStack Query adapter; takes no value |
128
133
  | `--go-module-path` | go | the Go module path the SDK is imported by |
129
134
  | `--go-version` | go | its semver; from v2 on, the major suffix (`/v2`) it puts on the module path |
@@ -221,7 +226,7 @@ language's client in a slice of a compiled example; the
221
226
  clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen
222
227
  ```
223
228
 
224
- ```ts sdk
229
+ ```sdk ts
225
230
  import { DecodeError, Kitchen, NotFoundError } from "./kitchen"
226
231
 
227
232
  export function newClient(): Kitchen {
@@ -273,37 +278,190 @@ clients generate --spec openapi.json --target ts --out generated --ts-name Kitch
273
278
  clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen --ts-tanstack-query
274
279
  ```
275
280
 
276
- Its `createQueryHelpers(sdk, { getQueryClient })` gives five surfaces — `query`, `mutation`, `infiniteQuery`,
277
- `queryKey` and `mutationKey` — each nested exactly as the client is, so `query.org.member.list(…)` sits where
278
- `client.org.member.list(…)` does. `sdk` may be a client or a thunk for one, which an isomorphic app needs.
281
+ Build the QueryClient first, then the SDK with the file's `invalidateQueries` hook, then the helpers. The
282
+ `QueryClient` is the one your framework's adapter exports (`@tanstack/solid-query`, `@tanstack/react-query`), or
283
+ query-core's own, as here:
284
+
285
+ ```sdk ts tanstack
286
+ import { QueryClient } from "@tanstack/query-core"
287
+ import { Kitchen } from "./kitchen"
288
+ import { createQueryHelpers, invalidateQueries } from "./kitchen.tanstack-query.gen"
289
+
290
+ export const queryClient = new QueryClient()
291
+ const sdk = new Kitchen({ baseURL: "https://api.example.com", onInvalidate: [invalidateQueries(queryClient)] })
292
+ export const { query, mutation, infiniteQuery, queryKey, mutationKey } = createQueryHelpers(() => sdk)
293
+ ```
294
+
295
+ The five surfaces are nested exactly as the client is, so `query.organizations.retrieve(…)` sits where
296
+ `client.organizations.retrieve(…)` does. `createQueryHelpers` takes a function that returns the client, and it calls it
297
+ on every request, so an isomorphic app can return a different client for each request.
279
298
 
280
299
  The document decides what goes where. A `GET` is on `query`, every other method is on `mutation`, and an event
281
300
  stream, a WebSocket or an `x-realtime` operation is on neither, because a stream is not a cache entry. Nothing
282
301
  is keyed off a method's name.
283
302
 
284
- **Keys.** A read's key is `[<SDK name>, ...the member path, the request]` — the request object whole, so
285
- `params`, `search` and anything else the SDK sends are all in it. That is what TanStack requires: every input
303
+ **Call shapes.** Each factory returns only its key and its function. Spread the result into TanStack's own
304
+ options and put everything else after it, so every other option is typed by TanStack. These use query-core's
305
+ observers; `useQuery(() => ({ ... }))` in solid-query, or `useQuery({ ... })` in react-query, takes the same
306
+ object:
307
+
308
+ ```sdk ts tanstack
309
+ import { InfiniteQueryObserver, MutationObserver, QueryClient, QueryObserver } from "@tanstack/query-core"
310
+ import { Kitchen } from "./kitchen"
311
+ import { createQueryHelpers, invalidateQueries } from "./kitchen.tanstack-query.gen"
312
+
313
+ const queryClient = new QueryClient()
314
+ const sdk = new Kitchen({ baseURL: "https://api.example.com", onInvalidate: [invalidateQueries(queryClient)] })
315
+ const { query, mutation, infiniteQuery, queryKey } = createQueryHelpers(() => sdk)
316
+
317
+ export function organization(orgId: string) {
318
+ return new QueryObserver(queryClient, { ...query.organizations.retrieve({ params: { orgId } }), staleTime: 0 })
319
+ }
320
+
321
+ // the second argument is the SDK's own call options; they reach the call, not the key
322
+ export const timed = query.organizations.retrieve({ params: { orgId: "org_1" } }, { timeout: 5_000 })
323
+
324
+ export const greet = new MutationObserver(queryClient, {
325
+ ...mutation.hello.create(),
326
+ onMutate: (input) => console.log(`greeting ${input.json.name}`),
327
+ })
328
+
329
+ export const greetings = new InfiniteQueryObserver(queryClient, {
330
+ ...infiniteQuery.hello.list((q: string | undefined) => ({ search: { q: q ?? "" } })),
331
+ initialPageParam: undefined,
332
+ getNextPageParam: () => undefined, // read the next page param off the last page, when your API pages
333
+ })
334
+
335
+ export const cached = queryClient.getQueryData(queryKey.hello.list({ search: { q: "Ada" } }))
336
+ ```
337
+
338
+ A read takes the SDK method's request, then optionally its call options (`timeout`, `headers`, `signal`, and
339
+ the other per-call options). `mutate` takes exactly what the SDK method takes. A paged read takes a function
340
+ from the page param to the request. The adapter calls that function once with `undefined` to build the key, so
341
+ it must accept `undefined`. Annotate its parameter and TanStack infers the page param type from it. Every call
342
+ gets TanStack's abort signal merged with yours, so a cancel, or the last observer unmounting, aborts the
343
+ request.
344
+
345
+ **Keys.** A read's key is `[<SDK name>, ...the member path, the request]`. The request object goes in whole,
346
+ so `params`, `search` and anything else the SDK sends are all in it. That is what TanStack requires: every input
286
347
  the `queryFn` depends on belongs in the key, so two reads of one route that differ only by `search` are two
287
- cache entries. `init` is not in the key, since a signal and a timeout say nothing about the answer. A read with
288
- no request keys as `[<SDK name>, ...the member path]`. `queryKey.<…>(req)` returns exactly the key
289
- `query.<…>({ reqOptions: { req } })` writes. A paged read carries a trailing `"infinite"` marker, because its
290
- cached shape is `InfiniteData` and it must not share the plain read's entry.
291
-
292
- **Invalidation** works by prefix, which is why the two are not the same shape. A successful write makes stale
293
- the reads its `x-invalidate` selectors name, with the mutation's own path params filled in:
294
- `[<SDK name>, ...the member path, { params }]`. TanStack matches objects partially and compares only the
295
- filter's own positions, so that reaches every search of that read, the paged entry included. When a selector's
296
- params are not all known the filter stays the bare prefix, which reaches everything under it — made stale
297
- rather than missed.
298
-
299
- Two notes. `@tanstack/query-core` is your dependency, not backend's — install it yourself; the file imports it for
300
- types only. And a read's options carry `initialData: undefined`, which is what solid-query needs to keep the
301
- unseeded overload; it is harmless under react-query.
348
+ cache entries. The call options are not in the key, since a signal and a timeout say nothing about the answer.
349
+ A read with no request keys as `[<SDK name>, ...the member path]`. `queryKey.<…>(req)` returns exactly the key
350
+ `query.<…>(req)` uses, typed so `getQueryData` infers the answer. A paged read's key is the key of its request
351
+ for `undefined` plus a trailing `"infinite"` marker, because its cached shape is `InfiniteData` and it must not
352
+ share the plain read's entry.
353
+
354
+ **Invalidation** happens in the SDK, not the helpers. A successful write fires the SDK's `onInvalidate` with the
355
+ reads its `x-invalidate` selectors name, and `invalidateQueries(queryClient)` makes each of them stale as
356
+ `[<SDK name>, ...the member path, { params }]`, or as the bare prefix when the target has no params. TanStack
357
+ matches objects partially and compares only the filter's own positions, so that reaches every search of that
358
+ read, the paged entry included. Because the SDK fires the hook, a plain `sdk.hello.create(…)` refreshes the
359
+ cache just as `mutation.hello.create()` does. The SDK awaits the hook, so a write resolves only after the
360
+ active reads it made stale have refetched. A failing refetch holds the write through its retries but never
361
+ rejects it, and an infinite query refetches every page it holds.
362
+
363
+ **Server rendering.** On the server, build the QueryClient and the SDK per request, in that order. Both are
364
+ dropped when the request ends, and the hook holds no state of its own. If a route preload prefetches, skip the
365
+ browser's hydration run, or it refetches what the server already sent:
366
+
367
+ ```sdk ts tanstack
368
+ import { QueryClient } from "@tanstack/query-core"
369
+ import { Kitchen } from "./kitchen"
370
+ import { createQueryHelpers, invalidateQueries } from "./kitchen.tanstack-query.gen"
371
+
372
+ const queryClient = new QueryClient()
373
+ const sdk = new Kitchen({ baseURL: "https://api.example.com", onInvalidate: [invalidateQueries(queryClient)] })
374
+ const { query } = createQueryHelpers(() => sdk)
375
+
376
+ // a route preload: `isServer` from your framework (`@solidjs/web` in Solid), `intent` from the router
377
+ export function preloadOrganization(isServer: boolean, intent: string, orgId: string): void {
378
+ if (!isServer && intent === "initial") return
379
+ void queryClient.prefetchQuery(query.organizations.retrieve({ params: { orgId } }))
380
+ }
381
+ ```
382
+
383
+ `@tanstack/query-core` is your dependency, not backend's. Install it yourself; the file imports it for types
384
+ only.
302
385
 
303
386
  Drop the flag and the next run deletes the file, the way `.clients-generated.json` deletes anything the previous
304
387
  run wrote and this one did not. The index file never re-exports the adapter, so an SDK generated without the
305
388
  flag names no TanStack type anywhere.
306
389
 
390
+ #### Single-flight, a write and its reads in one request
391
+
392
+ `--ts-single-flight` writes `<stem>.single-flight.gen.ts`, a server's file: `singleFlightHandler(getSdk, options)`
393
+ is a fetch handler, and `runSingleFlight(sdk, body)` runs the same batch with no Request or Response. It takes no
394
+ value, and the run refuses it for a document with no write whose `x-invalidate` names a read.
395
+
396
+ ```sh
397
+ clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen --ts-single-flight
398
+ ```
399
+
400
+ A batch is `{ v: 1, op, input, reads: [{ id, operationId, input }] }` and its answer is
401
+ `{ v: 1, write: { status, headers, body }, reads: [{ id, data } | { id, error: { status, body? } }] }`. Everything
402
+ is checked against the service map before anything runs: one REST write, at most `maxReads` (10) REST JSON reads,
403
+ and input of only `params`, `search`, `json` (the write's) and `idempotencyKey` (an idempotent write's). The
404
+ handler takes only a JSON POST of at most `maxBodyBytes` (64 KiB), refuses a browser on another site or an origin
405
+ outside `allowedOrigins` (its own by default), and answers a refusal as a 400 `application/problem+json`.
406
+
407
+ The write runs once on `getSdk(request)`, which you make per request, forwarding only the auth you choose; the
408
+ handler adds no retry, though the SDK's own hooks may. Only after a 2xx do the reads run, in parallel and past any
409
+ cache, within `readBudgetMs` (2000) and `maxReadBytes` (1 MiB) in all; a read past either ends as its own error
410
+ entry (504 or 502) and never fails the batch. The write's `Set-Cookie` headers are copied onto the 200, and a
411
+ cookie only sticks when the API shares the handler's site.
412
+
413
+ The index never re-exports the file, so no browser bundle carries the handler; the package exports it at
414
+ `./single-flight`.
415
+
416
+ The client sends its writes there once you give it `singleFlight`. A write goes in a batch only when it can: a
417
+ REST write with a JSON answer whose `x-invalidate` names reads, called with nothing a batch cannot carry
418
+ (`headers`, `cookies`, `body`, `form`, `baseURL`, `raw`), its operationId not in `exclude`, and `select` picking at
419
+ least one read. `select` gets the write's targets and returns the reads to bring back, at most `maxReads` (10).
420
+ Every other call goes direct, as does one called with `singleFlight: false`. The batch is a POST to `path`
421
+ (`_mutate`) under the base URL, so the client's hooks, timeout and signal apply to it. An idempotent write's key
422
+ is made before the batch, so a resend carries the same one. With TanStack Query, `activeReads(queryClient)` picks
423
+ the active reads, and `invalidateQueries` puts each one in the cache before it marks the rest stale:
424
+
425
+ ```sdk ts tanstack
426
+ import { QueryClient } from "@tanstack/query-core"
427
+ import { Kitchen } from "./kitchen"
428
+ import { activeReads, invalidateQueries } from "./kitchen.tanstack-query.gen"
429
+
430
+ const queryClient = new QueryClient()
431
+ const sdk = new Kitchen({
432
+ baseURL: "https://app.example.com/api",
433
+ onInvalidate: [invalidateQueries(queryClient)],
434
+ singleFlight: { select: activeReads(queryClient) },
435
+ })
436
+ ```
437
+
438
+ The write resolves with the answer a direct call would have, and throws the same error. Its reads reach the
439
+ `onInvalidate` hooks first, as `event.fresh`: each answered read's data by the id `select` gave it, and in
440
+ `failed` the ids that did not come back. A query opts out with `meta: { singleFlight: false }`, and a mutation with
441
+ the same meta sends its write direct. A 401 on the write refreshes the token once through `onAuthExpired` and sends
442
+ the batch again. When the handler refuses the batch, the client sends the write direct; any other failure throws
443
+ and the write is never sent twice. A batch answer that is no envelope throws `DecodeError`, the hooks still
444
+ called, since the write may have run.
445
+
446
+ `send` replaces the POST, for an app that calls its server another way, such as a server function that returns
447
+ `runSingleFlight(sdk, batch)`. It gets the batch and resolves the envelope. The client cannot tell a refusal
448
+ through `send` from a failure, so it throws one and never resends the write:
449
+
450
+ ```sdk ts
451
+ import { Kitchen, type SingleFlightBatch } from "./kitchen"
452
+
453
+ declare function mutate(batch: SingleFlightBatch): Promise<object>
454
+
455
+ export const sdk = new Kitchen({
456
+ baseURL: "https://app.example.com/api",
457
+ singleFlight: {
458
+ select: (targets) =>
459
+ targets.map((target, at) => ({ id: `r${at}`, input: { params: target.params }, operationId: target.operationId })),
460
+ send: mutate,
461
+ },
462
+ })
463
+ ```
464
+
307
465
  ### The Go SDK
308
466
 
309
467
  Idiomatic Go: a `Config`, `context.Context` on every call, errors read with `errors.As`, and an event stream as a
@@ -694,6 +852,361 @@ This package also exports the app-side generators the backend CLI and Vite plugi
694
852
  - [SDK conformance](https://github.com/workerstack/clients/blob/main/docs/conformance.md) and
695
853
  [the framework itself](https://github.com/workerstack/backend#readme).
696
854
 
855
+ ## Releasing a product's public packages
856
+
857
+ `@workerstack/clients` releases a product's public packages from the private repo that generates them. One
858
+ `release.config.ts` lists the packages. `clients release bump` cuts each package's next version from what
859
+ changed. `clients release sync` mirrors each package into its own public repo and pushes the `v<version>` tag.
860
+ Each public repo's `release.yml` then publishes on that tag through OIDC, with no registry token stored anywhere.
861
+ Three reusable workflows in `workerstack/clients` run these steps in CI, so a consumer repo only writes short callers.
862
+
863
+ ### Contents
864
+
865
+ - [Consumer prerequisites](#consumer-prerequisites)
866
+ - [release.config.ts](#releaseconfigts)
867
+ - [New product checklist](#new-product-checklist)
868
+ - [The reusable workflows](#the-reusable-workflows)
869
+ - [CLI](#cli)
870
+ - [Versioning](#versioning)
871
+ - [Tags](#tags)
872
+ - [Deployed spec gate](#deployed-spec-gate)
873
+ - [Channels](#channels)
874
+ - [Secrets](#secrets)
875
+
876
+ ### Consumer prerequisites
877
+
878
+ - `@workerstack/clients` in the repo's dependencies. The `workflows-v1` workflows need 1.0.0-rc.25 or later, the first
879
+ version with `release codegen` and `release toolchains`. The workflows run the consumer's own installed copy and pin
880
+ none.
881
+ - `@workerstack/system` in the repo's dependencies, and a `system.config.ts` at the repo root that declares every name
882
+ the release config lists in `toolchains`, each at the version codegen needs:
883
+
884
+ ```ts
885
+ import { defineConfig } from "@workerstack/system"
886
+
887
+ export default defineConfig({ deps: { go: "1.27.2", rust: "1.99.1", uv: "0.13.1", ruff: "0.17.1" } })
888
+ ```
889
+
890
+ - `packageManager: "bun@<version>"` in the root `package.json` (the workflows read Bun's version from it) and a
891
+ committed `bun.lock` (they run `bun install --frozen-lockfile`, with the repo's scripts on).
892
+
893
+ ### release.config.ts
894
+
895
+ A product's config sits in its own directory. Each package's source dir is a sibling named after the package, and
896
+ every other non-hidden directory there is an error. A package's public repo is `github.com/<repo>`.
897
+
898
+ ```ts
899
+ import { defineRelease } from "@workerstack/clients/release"
900
+
901
+ export default defineRelease({
902
+ project: "<product>",
903
+ /* regenerates every package from the repo root; bump runs it, and it must honor RELEASE_VERSIONS */
904
+ codegen: ["bun", "scripts/codegen.ts"],
905
+ /* the system.config.ts deps codegen needs, installed in this order before it runs */
906
+ toolchains: ["go", "rust", "uv", "ruff"],
907
+ homepage: "https://<domain>",
908
+ metadata: { license: "MIT", authors: ["<Name> <oss@<domain>>"] },
909
+ packages: [
910
+ {
911
+ name: "cli",
912
+ repo: "<org>/cli",
913
+ description: "<one line: the repo's, every registry's, and the first CHANGELOG entry>",
914
+ topics: ["<product>", "cli"],
915
+ commitMessage: "chore: generate from openapi spec",
916
+ clients: {
917
+ target: "cli",
918
+ options: { binaryName: "<bin>", modulePath: "github.com/<org>/cli", repo: "<org>/cli" },
919
+ },
920
+ },
921
+ {
922
+ name: "sdk-typescript",
923
+ repo: "<org>/sdk-typescript",
924
+ description: "<one line>",
925
+ topics: ["<product>", "sdk"],
926
+ commitMessage: "chore: generate from openapi spec",
927
+ clients: { target: "ts" },
928
+ registries: [{ kind: "npm" }, { kind: "jsr" }],
929
+ },
930
+ ],
931
+ spec: {
932
+ committedPath: "api/openapi.public.json",
933
+ deployedUrl: "https://api.<domain>/openapi.json",
934
+ },
935
+ })
936
+ ```
937
+
938
+ | Field | Meaning |
939
+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
940
+ | `project` | The product's slug: each package's `<project>/<name>` key, and what codegen filters on |
941
+ | `codegen` | The argv that regenerates every package, run from the repo root. Bump runs it again with `RELEASE_VERSIONS` (JSON, package name to version) set |
942
+ | `toolchains` | Optional, none by default. The `system.config.ts` dep names codegen needs; the workflows install them in this order |
943
+ | `committer` | Optional. The identity sync commits as (`public-sync[bot]` by default); a GitHub App's bot address works |
944
+ | `homepage` | https. Every public repo's website and every registry's homepage |
945
+ | `metadata` | Optional. Package metadata every generated package carries (authors, license, keywords and the rest); a package's own `metadata` wins over it |
946
+ | `packages[].clients` | How clients generates the package: its target and that target's options. Absent for a hand-kept package (one that publishes the spec itself) |
947
+ | `packages[].registries` | Where the public repo's rendered `release.yml` publishes: `npm`, `jsr`, `pypi`, `crates`, `go`, `nuget`, `maven`, or `github` with `assets` |
948
+ | `packages[].branch` | The public repo's branch sync pushes to, `main` by default |
949
+ | `packages[].bootstrapExclude` | Globs the first push leaves out, so the next sync adds them as their own commit |
950
+ | `spec` | The committed spec codegen builds from (repo-relative), and the URL prod serves it at (the deployed spec gate) |
951
+
952
+ ### New product checklist
953
+
954
+ 1. Create or pick the GitHub org for the public repos, and an empty public repo `<org>/<package>` for each package.
955
+ Sync pushes their content; nobody commits there by hand.
956
+ 2. Register the account-backed channels the packages need. Every registry that supports it publishes through a
957
+ trusted publisher for repo `<org>/<package>`, workflow `release.yml`:
958
+ - JSR: create `@<scope>` and link the package to its repo.
959
+ - npm: npm adds a trusted publisher only to a package that exists, so publish it once by hand with a short-lived
960
+ granular token, add the trusted publisher, then revoke the token.
961
+ - PyPI: add a pending trusted publisher (it works before the first upload).
962
+ - crates.io: publish once with `cargo publish` and a short-lived token, then add the trusted publisher.
963
+ - NuGet: add a trusted-publishing policy for the repo and workflow, and set the repo variable `NUGET_USER` to the
964
+ nuget.org user that owns it.
965
+ - Maven Central has no OIDC: verify the namespace, generate a Portal user token, create a GPG key whose public half
966
+ is on `keys.openpgp.org`, and add the four `MAVEN_*` secrets to the SDK's repo (see [Secrets](#secrets)).
967
+ - Go: nothing to register; the workflow's `proxy.golang.org` fetch indexes the tag.
968
+ - A CLI's channels are clients `cli` options, each optional: a Homebrew tap repo, a Scoop bucket repo, a
969
+ `microsoft/winget-pkgs` fork, an AUR account with an SSH key. Each one's token goes in the CLI's repo.
970
+ 3. Create a GitHub App with `contents: write`, `workflows: write` (sync pushes each repo's `release.yml`) and
971
+ `administration: write` (sync sets each repo's description, homepage and topics), install it on the org's public repos, and store its ID and private key as two Actions secrets in the private repo.
972
+ 4. Write `release.config.ts` with a dir per package, add the prerequisites above, and check the config:
973
+ `clients release sync --config <path> --validate-only`. A CLI also needs a hand `README.md` and `LICENSE`;
974
+ clients writes its `.goreleaser.yaml` and `.github/workflows/release.yml`.
975
+ 5. Publishing needs no workflow edits: every public tree carries a `release.yml` (the CLI's from clients, the rest
976
+ rendered from `registries`). Before the first real tag, run a repo's `release.yml` by hand with `workflow_dispatch`
977
+ to see each registry accept it. A repo whose version is already live must get that tag pushed by hand before its
978
+ first `release.yml` lands, or sync tags and republishes it.
979
+ 6. First release: commit the spec (bump records the commit a release is cut from), run the bump caller (or
980
+ `clients release bump --config <path>` locally), and merge the release PR. Each package releases 1.0.0 with
981
+ its `description` as the entry. The next sync tags each package.
982
+ 7. Verify: each public repo's `release` run is green (`gh run list -R <org>/<package> -w release`), its GitHub release
983
+ has its assets, each registry serves the new version, and a CLI's tap, bucket, winget PR and AUR package show it.
984
+
985
+ ### The reusable workflows
986
+
987
+ A consumer calls each one from its own workflow, pinned to the `workflows-v1` tag. The caller owns the triggers,
988
+ the `concurrency` group and the permissions it grants. A reusable workflow's job never gets more than its caller
989
+ grants, and secrets pass only through the declared `secrets:`, never `secrets: inherit` across owners. Every job runs
990
+ the same set-up: checkout, Node 24 (the release config loads as TypeScript), Bun from `packageManager`,
991
+ `bun install --frozen-lockfile`, each `toolchains` name through `system install <name> --upgrade` at its
992
+ `system.config.ts` pin with those tools first on PATH, then `release codegen`.
993
+
994
+ Each workflow also takes `cli`, the command that runs clients, split on spaces. It defaults to
995
+ `bun x --no-install clients`, the bin a consumer's `@workerstack/clients` install links. A consumer leaves it
996
+ unset. This repo's own release fixture passes `node bin/clients.js`, because bun never links a root package's
997
+ own bin.
998
+
999
+ ```yaml
1000
+ # .github/workflows/release-sync.yml
1001
+ on:
1002
+ push:
1003
+ branches: [main]
1004
+ paths: ["<product>-release/**", "api/**"]
1005
+ schedule: [{ cron: "0 3 * * *" }]
1006
+ workflow_dispatch:
1007
+ inputs:
1008
+ dry-run: { type: boolean, default: false }
1009
+ only: { type: string, required: false }
1010
+ concurrency: { group: release-sync, cancel-in-progress: false }
1011
+ permissions: { contents: read }
1012
+ jobs:
1013
+ sync:
1014
+ uses: workerstack/clients/.github/workflows/release-sync.yml@workflows-v1
1015
+ with:
1016
+ config: <product>-release/release.config.ts
1017
+ app-owner: <org>
1018
+ dry-run: ${{ inputs.dry-run == true }}
1019
+ only: ${{ inputs.only }}
1020
+ secrets:
1021
+ app-id: ${{ secrets.RELEASE_APP_ID }}
1022
+ app-private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
1023
+ ```
1024
+
1025
+ | `release-sync.yml` | Meaning |
1026
+ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
1027
+ | `config` | Required. The release config, repo-relative |
1028
+ | `app-owner` | The App installation's owner (the public repos' org); blank means the caller repo's owner |
1029
+ | `dry-run` | Stage each tree and report what would be pushed and tagged, pushing nothing |
1030
+ | `only` | Comma-separated package names (`name` or `project/name`); blank means every package |
1031
+ | `app-id`, `app-private-key` | Secrets, optional. Without both, the token step is skipped and only a dry run works (sync says `GH_TOKEN env is required`) |
1032
+
1033
+ ```yaml
1034
+ # .github/workflows/release-bump.yml
1035
+ on:
1036
+ workflow_dispatch:
1037
+ inputs:
1038
+ major: { type: boolean, default: false }
1039
+ permissions: { contents: write, pull-requests: write }
1040
+ jobs:
1041
+ bump:
1042
+ uses: workerstack/clients/.github/workflows/release-bump.yml@workflows-v1
1043
+ with:
1044
+ config: <product>-release/release.config.ts
1045
+ major: ${{ inputs.major == true }}
1046
+ ```
1047
+
1048
+ `release-bump.yml` takes `config` (required) and `major` (release every changed package as a major). It also installs
1049
+ `go` when `toolchains` does not list it, because bump runs oasdiff through `go run`. When a package changed, it opens
1050
+ or updates the release PR on branch `auto/release-bump` with exactly the paths bump printed as `wrote:`. That PR is
1051
+ opened with the caller's `GITHUB_TOKEN`, so it starts no workflows of its own: run the validate caller by hand, or
1052
+ review the PR's diff.
1053
+
1054
+ ```yaml
1055
+ # .github/workflows/release-validate.yml
1056
+ on:
1057
+ pull_request:
1058
+ paths: ["<product>-release/**"]
1059
+ permissions: { contents: read }
1060
+ jobs:
1061
+ validate:
1062
+ uses: workerstack/clients/.github/workflows/release-validate.yml@workflows-v1
1063
+ with:
1064
+ config: <product>-release/release.config.ts
1065
+ ```
1066
+
1067
+ `release-validate.yml` takes `config` and runs the set-up, codegen, then `release sync --validate-only`.
1068
+
1069
+ A dry run proves the whole path short of the push: the toolchains install, codegen runs, every package's tree is
1070
+ staged against its public repo's current tip, its `release.yml` is rendered, and the report says which packages would
1071
+ be pushed and which `v<version>` tags would be created. It leaves out the push, the tag and the repo settings step.
1072
+
1073
+ ### CLI
1074
+
1075
+ ```
1076
+ clients release bump --config <path> [--major]
1077
+ clients release sync --config <path> [--only <names>] [--dry-run] [--validate-only]
1078
+ clients release bootstrap --config <path> (--all | --only <names>) [--force-bootstrap]
1079
+ clients release codegen --config <path>
1080
+ clients release toolchains --config <path>
1081
+ ```
1082
+
1083
+ - `bump` regenerates, decides each package's release, gates generated output on prod, writes versions, regenerates at
1084
+ them, and records the release. It prints one `bumped: <name> <version> <kind>` line per release and one
1085
+ `wrote: <path>` line per file it touched.
1086
+ - `sync` mirrors each package and pushes its tag. It needs `GH_TOKEN` unless `--dry-run` or `--validate-only` is set.
1087
+ - `bootstrap` makes the first push to an empty public repo, or over the stub a new repo starts with.
1088
+ - `codegen` runs the config's codegen from the repo root, as bump runs it.
1089
+ - `toolchains` prints the config's `toolchains`, one per line.
1090
+
1091
+ ### Versioning
1092
+
1093
+ `bump` runs the product's codegen, then compares each package with what its `.release-state.json` recorded at the last
1094
+ release. It compares the generated output (backend's `.clients-generated.json` map, or the spec itself for a hand-kept
1095
+ package) and the tracked hand files (version lines normalized, the CHANGELOG and the state file left out). Nothing
1096
+ moved means no release, even when the spec moved.
1097
+
1098
+ When the output changed on a moved spec, oasdiff compares the spec with the one the last release was cut from (read
1099
+ back with `git show <commit>:<path>`). Any API change, breaking or not, is a minor. Output that changed with no API change,
1100
+ and any hand-file change, is a patch. A package stays on its major line: a major comes only from `--major`, which makes each
1101
+ package that releases a major.
1102
+
1103
+ A release writes the new version into every version file the package has (`package.json`, `jsr.json`,
1104
+ `pyproject.toml`). It reruns codegen with `RELEASE_VERSIONS`, so version-baked output is regenerated at that version.
1105
+ Only then does it record the digests, the spec's commit and the version in `.release-state.json`, so the merged release
1106
+ PR finds nothing left to release. The spec must be committed first, because the state records HEAD. A refusal writes
1107
+ nothing, so a rerun decides the same. Each public repo's `release.yml` checks the tag against its version files, so a
1108
+ tag whose files disagree fails before anything publishes.
1109
+
1110
+ ### Tags
1111
+
1112
+ Sync tags; the private repo never does. After sync pushes a package, or finds the bot's tip already equal to the
1113
+ source, it pushes `v<version>` from the package's `.release-state.json` unless that tag exists. It never moves a tag,
1114
+ so a rerun, or a run after one that stopped between its commit and its tag, converges. A merged release PR therefore
1115
+ releases every bumped package on the next sync. Never delete or move a pushed tag.
1116
+
1117
+ ### Deployed spec gate
1118
+
1119
+ Generated code may only describe operations prod serves. The gate fetches `spec.deployedUrl` and compares it with the
1120
+ committed spec by canonical sha. Sync refuses a package whose changed paths include a file clients generated. Bump
1121
+ refuses the whole run, hand-kept packages included, when a generated package whose output changed would release. On
1122
+ drift both print both shas and the operations on either side. Deploy, then rerun the bump caller; sync reruns on its
1123
+ schedule.
1124
+
1125
+ ### Channels
1126
+
1127
+ | Package kind | Channel | Published by |
1128
+ | -------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- |
1129
+ | CLI | GitHub Release: archives, `checksums.txt` signed by cosign, build attestations, `version.txt` | backend's `release.yml` in the CLI's repo |
1130
+ | CLI | Homebrew cask, Scoop manifest, winget PR, AUR `<bin>-bin`, deb/rpm/apk assets (each optional) | the same, with its channel's secret |
1131
+ | TypeScript SDK, MCP server | npm (provenance), JSR | the rendered `release.yml` |
1132
+ | Go SDK | the Go proxy (`proxy.golang.org` fetch of the tag) | the rendered `release.yml` |
1133
+ | Python SDK | PyPI (attestations) | the rendered `release.yml` |
1134
+ | Rust SDK | crates.io | the rendered `release.yml` |
1135
+ | C# SDK | NuGet | the rendered `release.yml` |
1136
+ | Java SDK | Maven Central (GPG-signed bundle through the Central Portal) | the rendered `release.yml` |
1137
+ | OpenAPI spec | GitHub Release with `openapi.json` | the rendered `release.yml` |
1138
+
1139
+ A rendered `release.yml` checks the tag against the version each registry publishes from, publishes, and retries until
1140
+ the registry serves the version. A rejected or repeated upload fails the run; a rerun is `workflow_dispatch` with the
1141
+ tag. Go modules at 2.0.0 and up carry `/v<major>` in their path, which codegen adds for the go and cli targets.
1142
+
1143
+ ### Secrets
1144
+
1145
+ | Secret | Where | Read by |
1146
+ | -------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
1147
+ | the App's ID and private key | the private repo | the sync caller, passed as `app-id` and `app-private-key` |
1148
+ | `HOMEBREW_TAP_TOKEN` | `<org>/cli` | goreleaser's cask push to the tap |
1149
+ | `SCOOP_BUCKET_TOKEN` | `<org>/cli` | goreleaser's manifest push to the bucket |
1150
+ | `WINGET_TOKEN` | `<org>/cli` | goreleaser's push to the winget-pkgs fork and its PR to `microsoft/winget-pkgs` |
1151
+ | `AUR_SSH_KEY` | `<org>/cli` | goreleaser's push to `aur.archlinux.org/<bin>-bin.git` |
1152
+ | none for npm, JSR, PyPI, crates.io, NuGet | | trusted publishers; NuGet's login also reads the repo variable `NUGET_USER` |
1153
+ | `MAVEN_CENTRAL_USERNAME`, `MAVEN_CENTRAL_PASSWORD` | `<org>/sdk-java` | the Central Portal user token: uploads the bundle and polls until it is published |
1154
+ | `MAVEN_GPG_PRIVATE_KEY`, `MAVEN_GPG_PASSPHRASE` | `<org>/sdk-java` | signs every bundle file; the public key must be on a keyserver Central reads |
1155
+
1156
+ ## Gates
1157
+
1158
+ ### Script contract
1159
+
1160
+ This repo has these `package.json` scripts. Hooks and CI call only these names, so a tool change is one line in `package.json`.
1161
+
1162
+ | script | runs |
1163
+ | ---------------------------- | ----------------------------------------------------------------------------------------- |
1164
+ | `fmt` / `fmt:check` | `repo fmt`: oxfmt with the standards pack's generated `.oxfmtrc.jsonc` |
1165
+ | `lint` / `lint:fix` | `repo lint`: oxlint with the generated `.oxlintrc.jsonc`, the repo's own plugin in `lint/` |
1166
+ | `typecheck` | `tsc -p tsconfig.json`: src, tests and scripts |
1167
+ | `typecheck:src` | `tsc -p tsconfig.src.json`: the source under the strict preset |
1168
+ | `test` | the repo's suite |
1169
+
1170
+ The lint and format configs, `knip.jsonc` and the git hooks are written by `bun repo sync` from `repo.config.ts`. The
1171
+ repo's own lint rules are `lint.plugins` and `lint.rules` there; a rule that does not fit a file is a `lint.skip` entry
1172
+ with its reason, and a use knip cannot see is a `knip.ignore` entry with its reason.
1173
+
1174
+ ### Where each gate runs
1175
+
1176
+ | when | what | blocks |
1177
+ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------- |
1178
+ | pre-commit | `repo precommit`: fmt and `lint --fix` on the staged files (restaged), lint held to the baseline, typecheck, sync, the related tests, `repo check` | the commit |
1179
+ | commit-msg | `repo commit-msg`: Conventional Commits and the change-size rule | the commit |
1180
+ | pre-push | `repo link --pre-push`, then `repo commit-msg --pre-push` on each pushed commit | the push |
1181
+ | CI | on every push to `main`: the `commits` job (`repo commit-msg --range`), `fmt:check`, `repo check`, `typecheck`, `typecheck:src`, `test`, `test:harness` | new work, until fixed |
1182
+
1183
+ `bun repo sync` points `core.hooksPath` at `.githooks/`, so the hooks come with `bun install`.
1184
+
1185
+ ### Push and CI
1186
+
1187
+ No full suite runs locally. Each commit runs the tests its change reaches: the touched test files and the tests of the code it changed. Then push, and run `bun repo ci wait` in the background. It waits for CI's run on the pushed commit and names any failed job and its log. A push cancels the run before it, so batch the commits and push once.
1188
+
1189
+ ### Release
1190
+
1191
+ The version bump rides in the final push. Only a commit CI passed on `main` gets the `v*` tag. The release workflow runs no tests: it waits for that commit's `ci.yml` push run and publishes on its success, so a bump made after the green push is a new commit and costs another CI run. The tag's notes are the `## [Unreleased]` entry of `CHANGELOG.md` for a prerelease and the dated `## [x.y.z] - YYYY-MM-DD` entry for a final release; `scripts/changelog.ts` refuses a tag without them.
1192
+
1193
+ ### Browsers
1194
+
1195
+ - Chrome: `offscreen --hypr` adds a hidden virtual monitor to the running Hyprland; tests drive Chrome on it over CDP. It never takes focus. `exec` and `run` are refused in that mode.
1196
+ - Safari: the MacBook Air M3 over Tailscale (`ssh mac`, `safaridriver -p 4799`), one run at a time.
1197
+
1198
+ ## Red, fix, green
1199
+
1200
+ 1. Red: write the test that shows the bug or the missing behavior. Run it. It must fail, for the reason the test names. Record the failing output (BUGS.md for a bug, where the repo has one).
1201
+ 2. Fix: the smallest change that makes it pass.
1202
+ 3. Green: run it again and record the passing output. Then run the tests the change reaches, and leave the full gates to CI on the push.
1203
+
1204
+ A test that cannot fail proves nothing. Check it: revert or break the fix, and the test must go red.
1205
+
1206
+ Commits: the test and the fix may share a commit or come as `test(...)` then `fix(...)`. A `fix` or `feat` commit always contains a test change.
1207
+
1208
+ Lint rules follow the same loop. A mistake that a rule could catch mechanically ships with a rule: a RuleTester case that fails first, then the rule, in the repo's `lint/` plugin.
1209
+
697
1210
  ## License
698
1211
 
699
1212
  MIT