@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
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Every generate flag
|
|
3
|
+
order: 50
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Every flag
|
|
7
|
+
|
|
8
|
+
One table, since a flag that is not written down is a flag nobody finds:
|
|
9
|
+
|
|
10
|
+
| Flag | Target | What it sets |
|
|
11
|
+
| -------------------------- | ------ | --------------------------------------------------------------------------------- |
|
|
12
|
+
| `--spec <file>` | — | the OpenAPI document to generate from |
|
|
13
|
+
| `--app <module>[#export]` | — | a backend app module instead of a document |
|
|
14
|
+
| `--target <name>` | — | which target to emit; repeat for more than one |
|
|
15
|
+
| `--out <dir>` | — | the output root; each target writes under `<dir>/<target>` |
|
|
16
|
+
| `--watch` | — | regenerate on each change, in a fresh process |
|
|
17
|
+
| `-h`, `--help` | — | the usage text |
|
|
18
|
+
| `--ts-name` | ts | the client class's name (default `SDK`) |
|
|
19
|
+
| `--ts-stem` | ts | the file stem the generated modules share |
|
|
20
|
+
| `--ts-package-name` | ts | the npm name, and the JSR name when scoped; the stem by default |
|
|
21
|
+
| `--ts-version` | ts | the version both registries carry; the document's by default |
|
|
22
|
+
| `--ts-single-flight` | ts | also write the single-flight handler; takes no value |
|
|
23
|
+
| `--ts-tanstack-query` | ts | also write the TanStack Query adapter; takes no value |
|
|
24
|
+
| `--go-module-path` | go | the Go module path the SDK is imported by |
|
|
25
|
+
| `--go-version` | go | its semver; from v2 on, the major suffix (`/v2`) it puts on the module path |
|
|
26
|
+
| `--rust-crate-name` | rust | the crate's name |
|
|
27
|
+
| `--rust-version` | rust | the crate's version |
|
|
28
|
+
| `--rust-description` | rust | what crates.io shows; `cargo publish` needs one |
|
|
29
|
+
| `--rust-license` | rust | its SPDX license; `cargo publish` needs one |
|
|
30
|
+
| `--rust-repository` | rust | the repository crates.io links |
|
|
31
|
+
| `--rust-homepage` | rust | the home page crates.io links |
|
|
32
|
+
| `--rust-keywords` | rust | its crates.io keywords, comma separated: five at most, each 20 ASCII characters |
|
|
33
|
+
| `--rust-categories` | rust | its crates.io category slugs, comma separated: five at most |
|
|
34
|
+
| `--rust-documentation` | rust | the https documentation crates.io links; docs.rs by default |
|
|
35
|
+
| `--python-package-name` | python | the Python package's name |
|
|
36
|
+
| `--python-version` | python | the package's version |
|
|
37
|
+
| `--csharp-client-name` | csharp | the client class's name |
|
|
38
|
+
| `--csharp-package-id` | csharp | the NuGet package id |
|
|
39
|
+
| `--csharp-root-namespace` | csharp | the root namespace |
|
|
40
|
+
| `--csharp-version` | csharp | the package's version |
|
|
41
|
+
| `--csharp-description` | csharp | what nuget.org shows |
|
|
42
|
+
| `--csharp-authors` | csharp | its authors, comma separated |
|
|
43
|
+
| `--csharp-license` | csharp | its SPDX license expression |
|
|
44
|
+
| `--csharp-homepage` | csharp | the https home page nuget.org links |
|
|
45
|
+
| `--csharp-repository` | csharp | the https URL of its git repository |
|
|
46
|
+
| `--csharp-copyright` | csharp | the copyright notice nuget.org shows |
|
|
47
|
+
| `--csharp-tags` | csharp | its NuGet tags, comma separated |
|
|
48
|
+
| `--java-artifact-id` | java | the Maven artifact id; `sdk` by default |
|
|
49
|
+
| `--java-group-id` | java | the Maven group id; `com.example` by default, yours to publish |
|
|
50
|
+
| `--java-package-name` | java | the Java package name |
|
|
51
|
+
| `--java-client-name` | java | the client class's name |
|
|
52
|
+
| `--java-version` | java | the publication's version |
|
|
53
|
+
| `--java-description` | java | the POM's description; the document's by default |
|
|
54
|
+
| `--java-homepage` | java | the POM's https project URL |
|
|
55
|
+
| `--java-license` | java | its SPDX license id, linked to spdx.org |
|
|
56
|
+
| `--java-repository` | java | the https URL of its git repository, the POM's scm |
|
|
57
|
+
| `--java-developers` | java | the POM's developers, comma separated: each a name or `Name <email>` |
|
|
58
|
+
| `--cli-binary-name` | cli | the command's own name (`shop`) |
|
|
59
|
+
| `--cli-base-url` | cli | the base URL it calls by default; the document's server by default |
|
|
60
|
+
| `--cli-module-path` | cli | the Go module path the CLI is built from |
|
|
61
|
+
| `--cli-version` | cli | its semver; from v2 on, the major suffix (`/v2`) it puts on the module path |
|
|
62
|
+
| `--cli-repo` | cli | the GitHub repository its release workflow and install scripts use |
|
|
63
|
+
| `--cli-env-prefix` | cli | the prefix of the environment variables it reads |
|
|
64
|
+
| `--cli-install-url` | cli | the https directory its install scripts are served from; the release's by default |
|
|
65
|
+
| `--cli-description` | cli | what the package managers show; every channel needs one |
|
|
66
|
+
| `--cli-homepage` | cli | the home page the package managers link; every channel needs one |
|
|
67
|
+
| `--cli-license` | cli | its SPDX license; every channel needs one |
|
|
68
|
+
| `--cli-maintainer` | cli | `Name <email>`, which AUR and the Linux packages name |
|
|
69
|
+
| `--cli-homebrew-tap` | cli | the Homebrew tap (`owner/name`) its cask is pushed to |
|
|
70
|
+
| `--cli-scoop-bucket` | cli | the Scoop bucket (`owner/name`) its manifest is pushed to |
|
|
71
|
+
| `--cli-winget-fork` | cli | the winget-pkgs fork (`owner/name`) its manifests are proposed from |
|
|
72
|
+
| `--cli-winget-publisher` | cli | the publisher winget files it under |
|
|
73
|
+
| `--cli-aur` | cli | a switch: publish the `<bin>-bin` AUR package |
|
|
74
|
+
| `--cli-packages` | cli | Linux packages beside the archives: `deb`, `rpm`, `apk`, comma separated |
|
|
75
|
+
| `--mcp-name` | mcp | the server's name, and the stem of its bin |
|
|
76
|
+
| `--mcp-env-prefix` | mcp | the prefix of the environment variables it reads |
|
|
77
|
+
| `--mcp-version` | mcp | its server info and package version; the document's by default |
|
|
78
|
+
| `--mcp-package-name` | mcp | the npm name it publishes under; `<name>-mcp` by default |
|
|
79
|
+
| `--mcp-mcp-name` | mcp | its MCP registry name (`io.github.acme/shop`), package.json's `mcpName` |
|
|
80
|
+
| `--metadata-description` | all | what every registry shows |
|
|
81
|
+
| `--metadata-homepage` | all | the https home page the registries link |
|
|
82
|
+
| `--metadata-repository` | all | the https URL of its git repository |
|
|
83
|
+
| `--metadata-license` | all | its SPDX license expression |
|
|
84
|
+
| `--metadata-authors` | all | each `Name <email>` or a name, comma separated |
|
|
85
|
+
| `--metadata-keywords` | all | registry keywords, comma separated |
|
|
86
|
+
| `--metadata-copyright` | all | the copyright line |
|
|
87
|
+
| `--metadata-documentation` | all | the https URL of its documentation |
|
|
88
|
+
| `--metadata-changelog` | all | the https URL of its changelog |
|
|
89
|
+
| `--metadata-license-file` | all | the license file to ship in each package |
|
|
90
|
+
| `--metadata-readme` | all | the README to ship in each package |
|
|
91
|
+
| `--metadata-icon` | all | the package icon to ship where the registry shows one |
|
|
92
|
+
|
|
93
|
+
The `--metadata-<field>` flags fill one package block that every target which publishes reads where its registry has
|
|
94
|
+
a place for the field, so a description or license is given once, not once per target. A target's own option of the
|
|
95
|
+
same meaning wins: `--java-description` over `--metadata-description`. Each field is checked before anything
|
|
96
|
+
generates: URLs must be https, the license an SPDX expression, text one line.
|
|
97
|
+
|
|
98
|
+
`--metadata-readme` and `--metadata-license-file` name files on disk, read once relative to where clients runs. Every
|
|
99
|
+
target writes them into its package root as `README.md` and `LICENSE`, and each manifest points at the ones it has:
|
|
100
|
+
pyproject's `readme` and `license-files`, Cargo's `readme` and `include`, the `.csproj`'s `PackageReadmeFile` and packed
|
|
101
|
+
items, and jsr.json's publish list; npm packs both on its own. The README must be a `.md` file, and both must be UTF-8
|
|
102
|
+
text. `--metadata-icon` ships only into the C# package, as `icon` with its own extension in lower case (`icon.png`,
|
|
103
|
+
`icon.jpeg`) under `PackageIcon`, since nuget.org is the one registry that shows an icon: a PNG or JPEG whose bytes are
|
|
104
|
+
that image, at most 1 MB.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Gates, push, CI and release
|
|
3
|
+
order: 800
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Gates
|
|
7
|
+
|
|
8
|
+
## Script contract
|
|
9
|
+
|
|
10
|
+
This repo has these `package.json` scripts. Hooks and CI call only these names, so a tool change is one line in `package.json`.
|
|
11
|
+
|
|
12
|
+
| script | runs |
|
|
13
|
+
| ---------------------------- | ----------------------------------------------------------------------------------------- |
|
|
14
|
+
| `fmt` / `fmt:check` | `repo fmt`: oxfmt with the standards pack's generated `.oxfmtrc.jsonc` |
|
|
15
|
+
| `lint` / `lint:fix` | `repo lint`: oxlint with the generated `.oxlintrc.jsonc`, the repo's own plugin in `lint/` |
|
|
16
|
+
| `typecheck` | `tsc -p tsconfig.json`: src, tests and scripts |
|
|
17
|
+
| `typecheck:src` | `tsc -p tsconfig.src.json`: the source under the strict preset |
|
|
18
|
+
| `test` | the repo's suite |
|
|
19
|
+
|
|
20
|
+
The lint and format configs, `knip.jsonc` and the git hooks are written by `bun repo sync` from `repo.config.ts`. The
|
|
21
|
+
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
|
|
22
|
+
with its reason, and a use knip cannot see is a `knip.ignore` entry with its reason.
|
|
23
|
+
|
|
24
|
+
## Where each gate runs
|
|
25
|
+
|
|
26
|
+
| when | what | blocks |
|
|
27
|
+
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
|
28
|
+
| 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 |
|
|
29
|
+
| commit-msg | `repo commit-msg`: Conventional Commits and the change-size rule | the commit |
|
|
30
|
+
| pre-push | `repo link --pre-push`, then `repo commit-msg --pre-push` on each pushed commit | the push |
|
|
31
|
+
| 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 |
|
|
32
|
+
|
|
33
|
+
`bun repo sync` points `core.hooksPath` at `.githooks/`, so the hooks come with `bun install`.
|
|
34
|
+
|
|
35
|
+
## Push and CI
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
## Release
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
## Browsers
|
|
44
|
+
|
|
45
|
+
- 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.
|
|
46
|
+
- Safari: the MacBook Air M3 over Tailscale (`ssh mac`, `safaridriver -p 4799`), one run at a time.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: The generate command
|
|
3
|
+
order: 40
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# clients generate
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
clients generate --spec openapi.json --target ts --target cli --out generated \
|
|
10
|
+
--cli-binary-name shop --cli-module-path github.com/acme/shop --cli-repo acme/shop
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
- `--spec <file>`: the OpenAPI document, as JSON.
|
|
14
|
+
- `--app <module>[#export]`: a backend app module instead of `--spec` (give one, never both). Its named export, else
|
|
15
|
+
`app`, else `default`, is the app; its document is made by the app's own `@workerstack/backend/http/openapi`, resolved from
|
|
16
|
+
the app as at run time, and the module's `openApi` export, if any, is that document's options (`info`,
|
|
17
|
+
`securitySchemes`, `invalidate`, …, as `generateOpenApi` takes them). Started by `bun run`, the bin hands the load to
|
|
18
|
+
that Bun, so a module needing Bun's loaders works; a run ends once it has written, whatever the module left open.
|
|
19
|
+
The module exports the app and serves nothing: one that calls `serve()` as it loads is outside `--app`'s contract,
|
|
20
|
+
since backend never serves implicitly and has no switch to stop it.
|
|
21
|
+
- `--target <name>`: `ts`, `go`, `rust`, `python`, `csharp`, `java`, `cli` or `mcp`; repeat it for more than one.
|
|
22
|
+
- `--out <dir>`: each target's files go under `<dir>/<target>`.
|
|
23
|
+
- `--<target>-<option>`: a target's options are its generator's, passed through as given. Each takes a value.
|
|
24
|
+
- `--watch`: generate again on each change of the spec (or the `--app` module), each run in a fresh process.
|
|
25
|
+
- `-h`, `--help`: the usage text, with every target's options.
|
|
26
|
+
|
|
27
|
+
Parsing is strict, because a typo that generates the wrong thing silently is worse than a refusal: an unknown flag, a
|
|
28
|
+
missing value, a stray argument, an unknown target, or an option for a target no `--target` names is a usage error.
|
|
29
|
+
`--k v` and `--k=v` both work, and a value is never the next flag.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Install scripts for a CLI
|
|
3
|
+
order: 90
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Install scripts
|
|
7
|
+
|
|
8
|
+
The CLI's `install.sh` and `install.ps1` are written by installgen, which ships in this package as the `installgen`
|
|
9
|
+
bin and the `@workerstack/clients/installers` library (it was `@lovrozagar/installgen`). The generated release
|
|
10
|
+
workflow checks every release with the installgen of the clients release that generated the module:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npx --yes --package @workerstack/clients@<version> installgen check --default-version v1.2.3
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
installgen also writes installers for any prebuilt binary, outside a generated CLI:
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { defineConfig } from "@workerstack/clients/installers"
|
|
20
|
+
|
|
21
|
+
export default defineConfig({
|
|
22
|
+
name: "my-cli",
|
|
23
|
+
baseUrl: "https://dl.example.com/my-cli",
|
|
24
|
+
assetPath: ({ version, os, arch }) => `${version}/my-cli-${os}-${arch}.tar.gz`,
|
|
25
|
+
})
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Full reference: [installgen](https://github.com/workerstack/clients/blob/main/src/installers/README.md).
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Install the package
|
|
3
|
+
order: 20
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Install
|
|
7
|
+
|
|
8
|
+
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)
|
|
9
|
+
maps each old package name to its new one. 1.0 is out as a release candidate, published under npm's `next` tag, so
|
|
10
|
+
an install without a tag gets a deprecated placeholder.
|
|
11
|
+
Add `@next` until the final release:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install --save-dev @workerstack/clients@next
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Node 22.12 or later, or Bun 1.3 or later.
|
|
18
|
+
|
|
19
|
+
Each target formats what it writes with that language's own formatter, when it can find it:
|
|
20
|
+
|
|
21
|
+
| target | formatter | found by |
|
|
22
|
+
| ----------- | --------- | --------------------------------------------------------------------------- |
|
|
23
|
+
| `go`, `cli` | gofmt | `$GOFMT`, `$GOROOT/bin/gofmt`, `gofmt` on `PATH`, beside the `go` on `PATH` |
|
|
24
|
+
| `python` | ruff | `$RUFF`, then `ruff` on `PATH` |
|
|
25
|
+
| `rust` | rustfmt | `$RUSTFMT`, the active toolchain's own binary beside `rustc`, `PATH` |
|
|
26
|
+
| `ts` | oxfmt | the `oxfmt` optional peer, installed beside clients |
|
|
27
|
+
|
|
28
|
+
A formatter it cannot find is named on standard error and skipped: the files go out as the emitter wrote them,
|
|
29
|
+
which is valid source either way, so generating a Python SDK never requires you to install ruff. Set
|
|
30
|
+
`CLIENTS_REQUIRE_FORMATTERS=1` to make a missing formatter fail the run instead, for a pipeline that would
|
|
31
|
+
rather stop than ship unformatted code. An override that points at nothing is refused by name.
|
|
32
|
+
|
|
33
|
+
oxfmt is the exception and says nothing when absent: it is clients' own choice of TypeScript formatter and a
|
|
34
|
+
declared optional peer, so not having it is the documented normal rather than news. `CLIENTS_REQUIRE_FORMATTERS`
|
|
35
|
+
still stops for it.
|
|
36
|
+
|
|
37
|
+
The `csharp` and `java` targets are not formatted today: `dotnet format` and google-java-format work over a
|
|
38
|
+
project rather than a stream, which clients' post-pass does not yet do.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: The generated MCP server
|
|
3
|
+
order: 110
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# The MCP server
|
|
7
|
+
|
|
8
|
+
`--target mcp` writes a standalone Model Context Protocol server: one tool per operation marked for MCP, its
|
|
9
|
+
`inputSchema` from the operation's parameters and body, an `outputSchema` from its success response, and
|
|
10
|
+
`structuredContent` an agent reads as data beside a text rendering. A failure comes back as a tool error with its
|
|
11
|
+
status and key, never as a successful result. Read-only operations are annotated as such. It speaks stdio by
|
|
12
|
+
default, and Streamable HTTP with `--http`.
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
clients generate --spec openapi.json --target mcp --out ./mcp --mcp-name acme
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Its package publishes to npm as written. `--mcp-package-name @acme/shop-mcp` names it (its bin keeps the server's
|
|
19
|
+
name), the metadata block fills its description, license, repository and the rest as it does the TS SDK's, and
|
|
20
|
+
`--mcp-mcp-name io.github.acme/shop` writes the `mcpName` the MCP registry checks the npm package by. With it the
|
|
21
|
+
server also gets the `server.json` that `mcp-publisher publish` reads from the package's root, on the registry's
|
|
22
|
+
2025-12-11 schema: that name, the description (100 characters at most, else refused), the version npm publishes, the
|
|
23
|
+
npm package over stdio with every environment variable the server reads, the home page as `websiteUrl`, and a GitHub
|
|
24
|
+
or GitLab repository. Where a hosted server runs is yours, so it lists no `remotes`.
|
|
25
|
+
|
|
26
|
+
```json
|
|
27
|
+
{
|
|
28
|
+
"name": "orders_get",
|
|
29
|
+
"inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] },
|
|
30
|
+
"outputSchema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } }
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
An event stream is one bounded collect: `max_events` (1 to 100, 20 by default) and `last_event_id` in, and
|
|
35
|
+
`{ events, last_event_id, ended }` out. When the stream names its events, each event's `event` is required and the
|
|
36
|
+
declared names are its `examples`. Each JSON event's `data` is typed by its name in an `anyOf` member, and any other
|
|
37
|
+
event, declared or not, has its `data` as a string. A stream of `tick` JSON events and `heartbeat` text events lists
|
|
38
|
+
its events as:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"type": "object",
|
|
43
|
+
"properties": { "event": { "type": "string", "examples": ["tick", "heartbeat"] }, "id": { "type": "string" } },
|
|
44
|
+
"required": ["data", "event"],
|
|
45
|
+
"anyOf": [
|
|
46
|
+
{
|
|
47
|
+
"properties": {
|
|
48
|
+
"event": { "const": "tick" },
|
|
49
|
+
"data": { "type": "object", "properties": { "n": { "type": "number" } } }
|
|
50
|
+
}
|
|
51
|
+
},
|
|
52
|
+
{ "properties": { "data": { "type": "string" } } }
|
|
53
|
+
]
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The server reads its configuration from the environment, under the `--mcp-env-prefix` (or the document's title,
|
|
58
|
+
upper-cased):
|
|
59
|
+
|
|
60
|
+
| Variable | Default | What it does |
|
|
61
|
+
| ---------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| `$<PREFIX>_BASE_URL` | the document's first server | the API every call goes to |
|
|
63
|
+
| `$<PREFIX>_API_KEY` | none | the credential, sent as the document's scheme says; scrubbed from every result |
|
|
64
|
+
| `$<PREFIX>_HEADERS` | none | a JSON object of headers sent on every call, each scrubbed from results |
|
|
65
|
+
| `$<PREFIX>_REDIRECT` | `same-origin` | `same-origin`, or `follow` to follow a redirect off the API's origin with its credentials dropped |
|
|
66
|
+
| `$<PREFIX>_TIMEOUT_MS` | `30000` | each call's bound, an event stream's collect included |
|
|
67
|
+
| `$<PREFIX>_FILE_ROOT` | the client's working dir | the only directory a `{ path }` file argument is read from |
|
|
68
|
+
| `$<PREFIX>_MAX_FILE_BYTES` | `52428800` | the largest file a path may name |
|
|
69
|
+
| `$<PREFIX>_MAX_INLINE_BYTES` | `1048576` | all inline files of one call together, decoded |
|
|
70
|
+
| `$<PREFIX>_MCP_TOKEN` | none | the bearer token `--http` requires; it never reaches the API |
|
|
71
|
+
|
|
72
|
+
**The standalone server needs Node**: it holds a listening socket and reads local files, so it belongs on a machine
|
|
73
|
+
or a container, never on serverless or Workers. To serve the same tools remotely, mount them in the app instead with
|
|
74
|
+
`mcp()` from `@workerstack/backend/mcp`, which runs wherever the app runs and is guarded by the app's own auth.
|
|
75
|
+
|
|
76
|
+
Full reference: [the generated MCP server](https://github.com/workerstack/backend/blob/main/docs/mcp.md).
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: What a run writes
|
|
3
|
+
order: 130
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# What a run writes
|
|
7
|
+
|
|
8
|
+
**Stale files are deleted, edited ones kept.** Each `<out>/<target>` keeps `.clients-generated.json`: every file the
|
|
9
|
+
run wrote, with its sha256. A file is rewritten only when its bytes change, through a temp file renamed over it. A
|
|
10
|
+
regeneration deletes a file the last run wrote and this one does not (a `cli` target's old `<name>_cmds.go`, say),
|
|
11
|
+
unless it was edited since: that one is kept and named on stderr. A file the manifest never listed is never deleted,
|
|
12
|
+
nothing outside `<out>/<target>` is touched, and no symlink is followed. Without a manifest, nothing is deleted.
|
|
13
|
+
|
|
14
|
+
Every target is held to the same conformance grid: one shared scenario suite runs against a live reference server
|
|
15
|
+
for all eight targets, and each decoded answer and each request on the wire must match one expected table. A feature
|
|
16
|
+
that works in one SDK and breaks in another fails the grid.
|
|
17
|
+
|
|
18
|
+
To lay the files out yourself, `generated(run, document, ctx)` from `@workerstack/clients` returns each
|
|
19
|
+
target's `files` unwritten, each as its text but for the C# package's icon, which is its bytes, and its `packages`:
|
|
20
|
+
the package on each registry it publishes to, as `{ registry, name, version }` (`npm` and `jsr` for a scoped TS SDK,
|
|
21
|
+
`npm` and `mcp-registry` for an MCP server with an `mcpName`, `pypi`, `crates.io`, `nuget`, `maven-central` as
|
|
22
|
+
`group:artifact`, and `go` by the module path, its `/vN` included and no version when none is given).
|
|
23
|
+
`writeTarget(dir, files, packages)` writes one target's into a directory you pick under the same rules, keeping
|
|
24
|
+
`MANIFEST` (`.clients-generated.json`) there with the packages recorded beside the files, so a release reads each name
|
|
25
|
+
and version from it. A file the last call wrote that you leave out of `files` is stale: deleted if unedited, kept and
|
|
26
|
+
named in the result's `kept` if you changed it, and dropped from the manifest either way, so a file you take over by
|
|
27
|
+
editing is never touched again.
|
|
28
|
+
|
|
29
|
+
A run kept as data (a release manifest, say) is checked with the same tables the command parses. `TARGETS` lists
|
|
30
|
+
every target, and `targetOptionSchemas[target]` is a Standard Schema for that target's options: its option names only,
|
|
31
|
+
each a non-empty string, a switch `"true"` or `"false"`. `generated` checks each target's options with it before
|
|
32
|
+
anything generates, and `GenerateRun` types them by target, so a misspelled option is a type error, then a refusal.
|
|
33
|
+
`GenerateRun`'s `metadata` is the `--metadata-<field>` block as a `Metadata` object, `authors` and `keywords` as
|
|
34
|
+
arrays, checked with the same rules.
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { TARGETS, targetOptionSchemas } from "@workerstack/clients"
|
|
38
|
+
|
|
39
|
+
const result = targetOptionSchemas.go["~standard"].validate({ modulePath: "github.com/acme/shop-go" })
|
|
40
|
+
export const ok = result.issues === undefined && TARGETS.includes("go")
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This package also exports the app-side generators the backend CLI and Vite plugin use: `generateRouteTree`,
|
|
44
|
+
`generateTypes` and `extractTypes` from `@workerstack/clients`, and the command's own entry at
|
|
45
|
+
`@workerstack/clients/cli`.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: What it generates
|
|
3
|
+
order: 10
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# What it generates
|
|
7
|
+
|
|
8
|
+
Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a Go command-line client and a Model Context Protocol
|
|
9
|
+
server from an OpenAPI 3.x document, or straight from a
|
|
10
|
+
[`@workerstack/backend`](https://www.npmjs.com/package/@workerstack/backend) app.
|
|
11
|
+
|
|
12
|
+
Every target reads one intermediate representation and vendors its own small runtime, so a generated SDK has no
|
|
13
|
+
dependency on backend, and a spec from another framework generates just as well. The output is formatted and
|
|
14
|
+
deterministic: regenerating an unchanged spec changes nothing on disk.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Release tooling overview
|
|
3
|
+
order: 100
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Release tooling
|
|
7
|
+
|
|
8
|
+
`clients release` cuts versions for a product's public packages and mirrors each one to its own GitHub repo.
|
|
9
|
+
A product describes its packages once, in a `release.config.ts` typed by the `@workerstack/clients/release`
|
|
10
|
+
library; each package's dir sits beside the config, and the repo root is the config's git toplevel:
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
import { defineRelease } from "@workerstack/clients/release"
|
|
14
|
+
|
|
15
|
+
export default defineRelease({
|
|
16
|
+
project: "acme",
|
|
17
|
+
codegen: ["bun", "run", "codegen"],
|
|
18
|
+
homepage: "https://example.com",
|
|
19
|
+
spec: { committedPath: "openapi.json", deployedUrl: "https://api.example.com/openapi.json" },
|
|
20
|
+
packages: [
|
|
21
|
+
{ name: "sdk", repo: "acme/sdk", description: "Acme SDK", commitMessage: "chore: sync", topics: ["acme"] },
|
|
22
|
+
],
|
|
23
|
+
})
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
clients release bump --config acme-release/release.config.ts [--major]
|
|
28
|
+
clients release sync --config acme-release/release.config.ts [--only sdk] [--dry-run] [--validate-only]
|
|
29
|
+
clients release bootstrap --config acme-release/release.config.ts (--all | --only sdk) [--force-bootstrap]
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`bump` writes each changed package's version files, `CHANGELOG.md` and `.release-state.json` (an API change is a
|
|
33
|
+
minor, measured by oasdiff through Go on PATH); `sync` and `bootstrap` push with `GH_TOKEN`, committing as
|
|
34
|
+
`committer` (default `public-sync[bot]`).
|