@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.
- package/README.md +548 -35
- package/assets/installers/examples/github.config.ts +17 -19
- package/assets/installers/examples/goreleaser.config.ts +16 -18
- package/assets/installers/examples/raw.config.ts +13 -15
- package/bin/clients.js +88 -68
- package/bin/installgen.js +18 -13
- package/dist/cli.d.ts +4 -4
- package/dist/cli.js +20 -12
- package/dist/emit/cli/channels.d.ts +2 -2
- package/dist/emit/cli/channels.js +18 -13
- package/dist/emit/cli/commands.d.ts +1 -1
- package/dist/emit/cli/commands.js +14 -8
- package/dist/emit/cli/discovery.d.ts +0 -6
- package/dist/emit/cli/discovery.js +9 -7
- package/dist/emit/cli/flags.d.ts +1 -3
- package/dist/emit/cli/flags.js +11 -5
- package/dist/emit/cli/install.d.ts +0 -8
- package/dist/emit/cli/install.js +3 -3
- package/dist/emit/cli/layout.d.ts +1 -1
- package/dist/emit/cli/layout.js +13 -10
- package/dist/emit/cli/module.d.ts +6 -6
- package/dist/emit/cli/module.js +10 -10
- package/dist/emit/cli/release.d.ts +0 -11
- package/dist/emit/cli/release.js +4 -4
- package/dist/emit/cli/skills.js +3 -3
- package/dist/emit/csharp/errors.js +4 -4
- package/dist/emit/csharp/json.js +8 -8
- package/dist/emit/csharp/realtime.js +3 -3
- package/dist/emit/csharp/sdk-answer.js +4 -4
- package/dist/emit/csharp/sdk-body.js +8 -6
- package/dist/emit/csharp/sdk-client.d.ts +3 -3
- package/dist/emit/csharp/sdk-client.js +2 -2
- package/dist/emit/csharp/sdk-csproj.d.ts +7 -9
- package/dist/emit/csharp/sdk-csproj.js +10 -10
- package/dist/emit/csharp/sdk-doc.js +1 -1
- package/dist/emit/csharp/sdk-method.d.ts +18 -2
- package/dist/emit/csharp/sdk-method.js +24 -9
- package/dist/emit/csharp/sdk-plan.js +0 -1
- package/dist/emit/csharp/sdk.js +7 -4
- package/dist/emit/csharp/sse.d.ts +0 -2
- package/dist/emit/csharp/sse.js +7 -7
- package/dist/emit/csharp/transport.js +7 -7
- package/dist/emit/csharp/types-enum.js +3 -1
- package/dist/emit/csharp/types-messages.js +3 -3
- package/dist/emit/csharp/types-names.js +10 -12
- package/dist/emit/csharp/types-record.js +3 -3
- package/dist/emit/csharp/types-union.d.ts +1 -1
- package/dist/emit/csharp/types.d.ts +0 -1
- package/dist/emit/csharp/types.js +3 -3
- package/dist/emit/csharp/ws.js +2 -2
- package/dist/emit/go/errors.js +1 -1
- package/dist/emit/go/http.js +2 -2
- package/dist/emit/go/module-path.js +2 -2
- package/dist/emit/go/sdk-answer.js +1 -1
- package/dist/emit/go/sdk-body.js +11 -7
- package/dist/emit/go/sdk-client.js +1 -1
- package/dist/emit/go/sdk-method.d.ts +9 -0
- package/dist/emit/go/sdk-method.js +12 -3
- package/dist/emit/go/sdk-mirror.js +2 -2
- package/dist/emit/go/sdk-opts.d.ts +0 -2
- package/dist/emit/go/sdk-opts.js +3 -3
- package/dist/emit/go/sdk.d.ts +1 -1
- package/dist/emit/go/sdk.js +12 -11
- package/dist/emit/go/sse.js +1 -1
- package/dist/emit/go/types-names.js +5 -0
- package/dist/emit/go/types-struct.d.ts +2 -1
- package/dist/emit/go/types-struct.js +1 -1
- package/dist/emit/go/types.js +9 -9
- package/dist/emit/go/ws.js +6 -6
- package/dist/emit/java/gradle.d.ts +7 -9
- package/dist/emit/java/gradle.js +8 -8
- package/dist/emit/java/json.js +1 -1
- package/dist/emit/java/layout-ast.js +1 -1
- package/dist/emit/java/layout-decl.js +5 -4
- package/dist/emit/java/layout-doc.js +13 -7
- package/dist/emit/java/layout-dot.js +1 -1
- package/dist/emit/java/layout-strings.js +4 -5
- package/dist/emit/java/layout-types.js +7 -5
- package/dist/emit/java/layout-visitor.js +4 -3
- package/dist/emit/java/layout.js +5 -4
- package/dist/emit/java/models-names.js +5 -4
- package/dist/emit/java/models-record.d.ts +0 -1
- package/dist/emit/java/models-record.js +3 -3
- package/dist/emit/java/models-union.d.ts +1 -1
- package/dist/emit/java/models-union.js +1 -1
- package/dist/emit/java/models.d.ts +1 -2
- package/dist/emit/java/models.js +25 -16
- package/dist/emit/java/realtime.d.ts +5 -17
- package/dist/emit/java/realtime.js +1 -1
- package/dist/emit/java/sdk-client.d.ts +6 -6
- package/dist/emit/java/sdk-client.js +2 -1
- package/dist/emit/java/sdk-decl.js +2 -2
- package/dist/emit/java/sdk-errors.js +1 -1
- package/dist/emit/java/sdk-headers.js +2 -2
- package/dist/emit/java/sdk-mirror.js +2 -2
- package/dist/emit/java/sdk-models.d.ts +1 -1
- package/dist/emit/java/sdk-models.js +7 -7
- package/dist/emit/java/sdk-op.d.ts +7 -11
- package/dist/emit/java/sdk-op.js +22 -10
- package/dist/emit/java/sdk-params.d.ts +5 -5
- package/dist/emit/java/sdk-params.js +3 -2
- package/dist/emit/java/sdk-plan.js +0 -1
- package/dist/emit/java/sdk.d.ts +1 -1
- package/dist/emit/java/sdk.js +21 -14
- package/dist/emit/java/sse.d.ts +2 -4
- package/dist/emit/java/sse.js +6 -6
- package/dist/emit/java/ws.d.ts +2 -2
- package/dist/emit/java/ws.js +3 -4
- package/dist/emit/mcp/annotations.js +8 -4
- package/dist/emit/mcp/files.js +9 -9
- package/dist/emit/mcp/mounted.js +2 -2
- package/dist/emit/mcp/output-schema.js +3 -3
- package/dist/emit/mcp/registry.d.ts +0 -2
- package/dist/emit/mcp/registry.js +5 -4
- package/dist/emit/mcp/runtime.js +2 -2
- package/dist/emit/mcp/schema.js +22 -11
- package/dist/emit/mcp/server.d.ts +7 -7
- package/dist/emit/mcp/server.js +7 -6
- package/dist/emit/mcp/tools.js +7 -6
- package/dist/emit/python/errors.js +3 -3
- package/dist/emit/python/realtime.js +2 -2
- package/dist/emit/python/sdk-answer.d.ts +3 -7
- package/dist/emit/python/sdk-answer.js +2 -2
- package/dist/emit/python/sdk-body.js +4 -5
- package/dist/emit/python/sdk-client.js +5 -5
- package/dist/emit/python/sdk-doc.js +2 -2
- package/dist/emit/python/sdk-method.d.ts +11 -0
- package/dist/emit/python/sdk-method.js +20 -5
- package/dist/emit/python/sdk-plan.js +0 -1
- package/dist/emit/python/sdk-pyproject.d.ts +0 -2
- package/dist/emit/python/sdk-pyproject.js +8 -8
- package/dist/emit/python/sdk.d.ts +1 -1
- package/dist/emit/python/sdk.js +12 -8
- package/dist/emit/python/sse.d.ts +0 -2
- package/dist/emit/python/sse.js +2 -2
- package/dist/emit/python/transport.js +4 -4
- package/dist/emit/python/types-dict.d.ts +2 -2
- package/dist/emit/python/types-dict.js +1 -1
- package/dist/emit/python/types-names.js +2 -2
- package/dist/emit/python/types-union.js +1 -1
- package/dist/emit/python/types.js +3 -3
- package/dist/emit/python/ws.d.ts +2 -5
- package/dist/emit/python/ws.js +4 -4
- package/dist/emit/rust/errors.js +3 -3
- package/dist/emit/rust/http.js +4 -4
- package/dist/emit/rust/realtime.js +2 -2
- package/dist/emit/rust/sdk-body.js +8 -5
- package/dist/emit/rust/sdk-cargo.d.ts +16 -18
- package/dist/emit/rust/sdk-cargo.js +12 -12
- package/dist/emit/rust/sdk-client.d.ts +1 -1
- package/dist/emit/rust/sdk-client.js +3 -3
- package/dist/emit/rust/sdk-method.d.ts +12 -1
- package/dist/emit/rust/sdk-method.js +12 -4
- package/dist/emit/rust/sdk-opts.d.ts +2 -1
- package/dist/emit/rust/sdk-opts.js +2 -2
- package/dist/emit/rust/sdk-plan.js +0 -1
- package/dist/emit/rust/sdk.d.ts +1 -1
- package/dist/emit/rust/sdk.js +9 -6
- package/dist/emit/rust/sse.d.ts +0 -5
- package/dist/emit/rust/sse.js +2 -2
- package/dist/emit/rust/types-names.js +3 -3
- package/dist/emit/rust/types-struct.js +1 -1
- package/dist/emit/rust/types-union.d.ts +1 -1
- package/dist/emit/rust/types.js +7 -5
- package/dist/emit/rust/ws.d.ts +0 -11
- package/dist/emit/rust/ws.js +5 -5
- package/dist/emit/shared/escape.js +17 -17
- package/dist/emit/shared/format.js +1 -1
- package/dist/emit/shared/gofmt.js +1 -1
- package/dist/emit/shared/lang.js +10 -10
- package/dist/emit/shared/literals.d.ts +5 -0
- package/dist/emit/shared/literals.js +8 -0
- package/dist/emit/shared/metadata.d.ts +0 -6
- package/dist/emit/shared/metadata.js +8 -7
- package/dist/emit/shared/ruff.js +1 -1
- package/dist/emit/shared/rustfmt.js +1 -1
- package/dist/emit/shared/type-emitter.js +37 -20
- package/dist/emit/shared/unknown-type.constants.d.ts +2 -0
- package/dist/emit/shared/unknown-type.constants.js +2 -0
- package/dist/emit/ts/http.d.ts +8 -2
- package/dist/emit/ts/http.js +51 -6
- package/dist/emit/ts/package.d.ts +14 -12
- package/dist/emit/ts/package.js +10 -8
- package/dist/emit/ts/route-tree.js +2 -2
- package/dist/emit/ts/sdk-types-preamble.d.ts +1 -1
- package/dist/emit/ts/sdk-types-preamble.js +12 -4
- package/dist/emit/ts/sdk-types.d.ts +0 -5
- package/dist/emit/ts/sdk-types.js +63 -19
- package/dist/emit/ts/sdk.d.ts +3 -1
- package/dist/emit/ts/sdk.js +44 -12
- package/dist/emit/ts/service-map.d.ts +7 -1
- package/dist/emit/ts/service-map.js +10 -1
- package/dist/emit/ts/single-flight-text.d.ts +3 -0
- package/dist/emit/ts/single-flight-text.js +38 -0
- package/dist/emit/ts/tanstack-query.d.ts +3 -2
- package/dist/emit/ts/tanstack-query.js +60 -35
- package/dist/emit/ts/type-gen.js +31 -18
- package/dist/emit/ts/webhooks.d.ts +0 -2
- package/dist/emit/ts/webhooks.js +3 -3
- package/dist/extract/chain.js +5 -4
- package/dist/extract/extract.js +5 -5
- package/dist/extract/serialize.d.ts +0 -2
- package/dist/extract/serialize.js +14 -15
- package/dist/extract/walk.js +15 -12
- package/dist/gen/args.js +9 -5
- package/dist/gen/formatters.js +5 -3
- package/dist/gen/process.js +2 -1
- package/dist/gen/shipped.js +2 -2
- package/dist/gen/switch-on.constants.d.ts +2 -0
- package/dist/gen/switch-on.constants.js +2 -0
- package/dist/gen/targets.d.ts +6 -7
- package/dist/gen/targets.js +11 -6
- package/dist/gen/write.js +4 -2
- package/dist/index.js +2 -2
- package/dist/installers/cli.d.ts +4 -4
- package/dist/installers/cli.js +24 -24
- package/dist/installers/commands/build.d.ts +4 -4
- package/dist/installers/commands/build.js +2 -3
- package/dist/installers/commands/check.d.ts +2 -2
- package/dist/installers/commands/check.js +11 -10
- package/dist/installers/commands/init.d.ts +2 -2
- package/dist/installers/commands/init.js +1 -2
- package/dist/installers/config/define-config.d.ts +16 -16
- package/dist/installers/config/define-config.js +1 -1
- package/dist/installers/config/hooks/bun.d.ts +6 -6
- package/dist/installers/config/hooks/node.js +1 -1
- package/dist/installers/config/load.d.ts +6 -8
- package/dist/installers/config/load.js +7 -8
- package/dist/installers/config/resolve.d.ts +1 -2
- package/dist/installers/config/resolve.js +28 -33
- package/dist/installers/config/types.d.ts +6 -6
- package/dist/installers/config/types.js +0 -1
- package/dist/installers/render/quote.js +3 -5
- package/dist/installers/render/render.d.ts +6 -6
- package/dist/installers/render/render.js +26 -26
- package/dist/installers/ui.d.ts +4 -4
- package/dist/installers/ui.js +3 -3
- package/dist/ir/build.d.ts +3 -3
- package/dist/ir/build.js +8 -5
- package/dist/ir/invalidate-reads.d.ts +17 -0
- package/dist/ir/invalidate-reads.js +104 -0
- package/dist/ir/load.d.ts +10 -0
- package/dist/ir/load.js +65 -18
- package/dist/ir/model.d.ts +2 -1
- package/dist/ir/model.js +0 -1
- package/dist/ir/read-method.constants.d.ts +2 -0
- package/dist/ir/read-method.constants.js +2 -0
- package/dist/ir/resolve-refs.js +2 -2
- package/dist/ir/resource-tree.js +2 -1
- package/dist/ir/route-tree-intern.js +1 -1
- package/dist/ir/schema.js +3 -3
- package/dist/ir/sdk-model.js +3 -3
- package/dist/ir/slots.js +13 -8
- package/dist/ir/streams.js +1 -1
- package/dist/release/bootstrap.d.ts +3 -3
- package/dist/release/bootstrap.js +7 -7
- package/dist/release/bump-args.js +4 -4
- package/dist/release/bump-command.d.ts +1 -1
- package/dist/release/bump-command.js +9 -10
- package/dist/release/bump.d.ts +5 -4
- package/dist/release/bump.js +2 -2
- package/dist/release/cli.d.ts +4 -4
- package/dist/release/cli.js +4 -4
- package/dist/release/codegen.js +1 -1
- package/dist/release/digest.js +5 -7
- package/dist/release/git.js +5 -8
- package/dist/release/load.js +4 -4
- package/dist/release/manifest.js +9 -10
- package/dist/release/oasdiff.d.ts +10 -15
- package/dist/release/oasdiff.js +5 -6
- package/dist/release/registries.d.ts +0 -11
- package/dist/release/registries.js +17 -17
- package/dist/release/release-state.d.ts +16 -13
- package/dist/release/release-workflow.js +5 -7
- package/dist/release/repo-settings.d.ts +2 -1
- package/dist/release/spec-gate.d.ts +0 -2
- package/dist/release/spec-gate.js +6 -10
- package/dist/release/sync-command.d.ts +2 -2
- package/dist/release/sync-command.js +1 -1
- package/dist/release/sync-tree.js +9 -13
- package/dist/release/sync.d.ts +6 -6
- package/dist/release/sync.js +12 -13
- package/dist/release/types.d.ts +22 -22
- package/dist/release/types.js +0 -1
- package/dist/release/version-files.d.ts +3 -4
- package/dist/release/version-files.js +4 -5
- package/dist/runtime/.oxfmtrc.jsonc +8 -0
- package/dist/runtime/csharp/Config.cs +9 -1
- package/dist/runtime/csharp/Exchange.cs +56 -4
- package/dist/runtime/csharp/Hooks.cs +9 -0
- package/dist/runtime/csharp/Operation.cs +6 -1
- package/dist/runtime/csharp/WsDial.cs +3 -1
- package/dist/runtime/go/config.go +5 -0
- package/dist/runtime/go/hooks.go +70 -0
- package/dist/runtime/go/request.go +6 -2
- package/dist/runtime/go/stream.go +4 -1
- package/dist/runtime/go/ws.go +3 -1
- package/dist/runtime/java/ClientConfig.java +11 -0
- package/dist/runtime/java/Flight.java +2 -12
- package/dist/runtime/java/Hooks.java +45 -0
- package/dist/runtime/java/InvalidateEvent.java +10 -0
- package/dist/runtime/java/InvalidateHook.java +12 -0
- package/dist/runtime/java/InvalidateTarget.java +7 -0
- package/dist/runtime/java/Operation.java +23 -3
- package/dist/runtime/java/Realtime.java +3 -1
- package/dist/runtime/java/WsDial.java +3 -0
- package/dist/runtime/mcp/files.ts +1 -1
- package/dist/runtime/mcp/http.ts +6 -2
- package/dist/runtime/mcp/listen.ts +1 -1
- package/dist/runtime/mcp/mount.ts +2 -2
- package/dist/runtime/mcp/protocol.ts +1 -1
- package/dist/runtime/python/config.py +8 -2
- package/dist/runtime/python/exchange.py +3 -1
- package/dist/runtime/python/hooks.py +110 -5
- package/dist/runtime/python/operation.py +2 -0
- package/dist/runtime/python/send_async.py +14 -2
- package/dist/runtime/python/send_sync.py +4 -2
- package/dist/runtime/python/ws.py +5 -1
- package/dist/runtime/rust/config.rs +6 -1
- package/dist/runtime/rust/exchange.rs +15 -3
- package/dist/runtime/rust/hooks.rs +127 -2
- package/dist/runtime/rust/log.rs +11 -3
- package/dist/runtime/rust/request.rs +17 -0
- package/dist/runtime/rust/ws.rs +9 -1
- package/dist/runtime/ts/config.ts +69 -0
- package/dist/runtime/ts/http.ts +12 -10
- package/dist/runtime/ts/request.ts +2 -0
- package/dist/runtime/ts/response.ts +7 -0
- package/dist/runtime/ts/sdk-invalidate.ts +82 -0
- package/dist/runtime/ts/sdk-single-flight.constants.ts +25 -0
- package/dist/runtime/ts/sdk-single-flight.ts +203 -0
- package/dist/runtime/ts/sdk-sse.ts +5 -1
- package/dist/runtime/ts/sdk-ws.ts +9 -3
- package/dist/runtime/ts/sdk.ts +55 -31
- package/dist/runtime/ts/single-flight-batch.ts +184 -0
- package/dist/runtime/ts/single-flight-body.ts +59 -0
- package/dist/runtime/ts/single-flight-run.ts +160 -0
- package/dist/runtime/ts/single-flight.constants.ts +31 -0
- package/dist/runtime/ts/single-flight.ts +158 -0
- package/dist/runtime/ts-tanstack-query/invalidate.ts +96 -92
- package/dist/runtime/ts-tanstack-query/query.ts +140 -170
- package/package.json +12 -17
- package/references/INDEX.md +31 -0
- package/references/cli.md +33 -0
- package/references/configuring.md +29 -0
- package/references/documentation.md +15 -0
- package/references/errors.md +23 -0
- package/references/flags.md +104 -0
- package/references/gates.md +46 -0
- package/references/generate.md +29 -0
- package/references/install-scripts.md +28 -0
- package/references/install.md +38 -0
- package/references/license.md +8 -0
- package/references/mcp.md +76 -0
- package/references/output.md +45 -0
- package/references/overview.md +14 -0
- package/references/release-tooling.md +34 -0
- package/references/release.md +305 -0
- package/references/sdks.md +393 -0
- package/references/start.md +22 -0
- package/references/tdd.md +16 -0
- package/dist/emit/cli/index.d.ts +0 -1
- package/dist/emit/cli/index.js +0 -1
- package/dist/emit/csharp/index.d.ts +0 -1
- package/dist/emit/csharp/index.js +0 -1
- package/dist/emit/go/index.d.ts +0 -1
- package/dist/emit/go/index.js +0 -1
- package/dist/emit/java/index.d.ts +0 -2
- package/dist/emit/java/index.js +0 -2
- package/dist/emit/mcp/index.d.ts +0 -3
- package/dist/emit/mcp/index.js +0 -3
- package/dist/emit/python/index.d.ts +0 -1
- package/dist/emit/python/index.js +0 -1
- package/dist/emit/rust/index.d.ts +0 -1
- package/dist/emit/rust/index.js +0 -1
package/README.md
CHANGED
|
@@ -1,26 +1,17 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- @generated by @workerstack/repo -->
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
277
|
-
`
|
|
278
|
-
|
|
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
|
-
**
|
|
285
|
-
|
|
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.
|
|
288
|
-
no request keys as `[<SDK name>, ...the member path]`. `queryKey.<…>(req)` returns exactly the key
|
|
289
|
-
`query.<…>(
|
|
290
|
-
cached shape is `InfiniteData` and it must not
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
the
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
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
|