@workerstack/clients 1.0.0-rc.26 → 1.0.0-rc.27
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 +43 -43
- package/bin/{honey-clients.js → clients.js} +12 -12
- package/dist/cli.d.ts +3 -3
- package/dist/cli.js +14 -14
- package/dist/emit/cli/discovery.js +1 -1
- package/dist/emit/cli/install.js +2 -2
- package/dist/emit/cli/layout.js +1 -1
- package/dist/emit/cli/module.js +1 -1
- package/dist/emit/cli/release.js +1 -1
- package/dist/emit/csharp/errors.js +1 -1
- package/dist/emit/csharp/sdk-client.js +1 -1
- package/dist/emit/csharp/sdk-csproj.d.ts +1 -1
- package/dist/emit/csharp/sdk-csproj.js +2 -2
- package/dist/emit/csharp/sdk.d.ts +1 -1
- package/dist/emit/csharp/sdk.js +2 -2
- package/dist/emit/csharp/transport.js +2 -2
- package/dist/emit/csharp/types-record.d.ts +1 -1
- package/dist/emit/go/sdk-client.js +1 -1
- package/dist/emit/go/sdk.js +1 -1
- package/dist/emit/java/sdk-errors.js +5 -5
- package/dist/emit/java/sdk-op.d.ts +1 -1
- package/dist/emit/java/sdk.js +3 -3
- package/dist/emit/mcp/files.d.ts +1 -1
- package/dist/emit/mcp/mounted.js +2 -2
- package/dist/emit/mcp/runtime.js +1 -1
- package/dist/emit/mcp/server.js +1 -1
- package/dist/emit/python/errors.js +1 -1
- package/dist/emit/python/sdk-client.js +2 -2
- package/dist/emit/python/sdk-pyproject.js +4 -4
- package/dist/emit/python/sdk.d.ts +1 -1
- package/dist/emit/python/sdk.js +11 -11
- package/dist/emit/python/transport.js +1 -1
- package/dist/emit/rust/errors.js +2 -2
- package/dist/emit/rust/sdk-cargo.js +3 -3
- package/dist/emit/rust/sdk.d.ts +1 -1
- package/dist/emit/rust/sdk.js +2 -2
- package/dist/emit/shared/format.d.ts +1 -1
- package/dist/emit/shared/metadata.d.ts +1 -1
- package/dist/emit/shared/status-keys.d.ts +1 -1
- package/dist/emit/shared/status-keys.js +1 -1
- package/dist/emit/ts/app-client.js +2 -2
- package/dist/emit/ts/route-tree.js +1 -1
- package/dist/emit/ts/sdk-types-preamble.js +16 -16
- package/dist/emit/ts/sdk-types.js +6 -6
- package/dist/emit/ts/tanstack-query.js +5 -5
- package/dist/emit/ts/type-gen.d.ts +2 -2
- package/dist/emit/ts/type-gen.js +16 -16
- package/dist/extract/extract.js +3 -3
- package/dist/extract/serialize.js +1 -1
- package/dist/gen/args.js +3 -3
- package/dist/gen/formatters.d.ts +6 -6
- package/dist/gen/formatters.js +7 -7
- package/dist/gen/process.d.ts +3 -3
- package/dist/gen/process.js +7 -7
- package/dist/gen/targets.d.ts +3 -3
- package/dist/gen/targets.js +3 -3
- package/dist/gen/write.d.ts +1 -1
- package/dist/gen/write.js +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/ir/load.js +10 -10
- package/dist/ir/model.d.ts +4 -4
- package/dist/ir/sdk-model.d.ts +1 -1
- package/dist/ir/sdk-model.js +1 -1
- package/dist/ir/slots.d.ts +3 -3
- package/dist/ir/slots.js +10 -10
- package/dist/release/bootstrap.js +1 -1
- package/dist/release/bump-command.js +1 -1
- package/dist/release/cli.d.ts +4 -4
- package/dist/release/cli.js +6 -6
- package/dist/release/context.d.ts +1 -1
- package/dist/release/context.js +1 -1
- package/dist/release/digest.d.ts +1 -1
- package/dist/release/digest.js +2 -2
- package/dist/release/index.d.ts +1 -1
- package/dist/release/load.js +1 -1
- package/dist/release/manifest.js +1 -1
- package/dist/release/registries.js +3 -3
- package/dist/release/release-workflow.js +1 -1
- package/dist/release/spec-gate.d.ts +2 -2
- package/dist/release/spec-gate.js +2 -2
- package/dist/release/sync-command.d.ts +1 -1
- package/dist/release/sync-command.js +1 -1
- package/dist/release/sync-tree.js +1 -1
- package/dist/release/types.d.ts +6 -6
- package/dist/runtime/cli/body.go +1 -1
- package/dist/runtime/cli/config.go +3 -3
- package/dist/runtime/cli/discovery.go +1 -1
- package/dist/runtime/cli/format.go +1 -1
- package/dist/runtime/cli/log.go +1 -1
- package/dist/runtime/cli/output.go +1 -1
- package/dist/runtime/cli/params.go +1 -1
- package/dist/runtime/cli/run.go +1 -1
- package/dist/runtime/cli/socket.go +1 -1
- package/dist/runtime/cli/stream.go +1 -1
- package/dist/runtime/cli/target.go +1 -1
- package/dist/runtime/csharp/Adapters.cs +2 -2
- package/dist/runtime/csharp/Auth.cs +2 -2
- package/dist/runtime/csharp/Body.cs +3 -3
- package/dist/runtime/csharp/Config.cs +2 -2
- package/dist/runtime/csharp/Envelope.cs +3 -3
- package/dist/runtime/csharp/Errors.cs +10 -10
- package/dist/runtime/csharp/Events.cs +2 -2
- package/dist/runtime/csharp/Exchange.cs +4 -4
- package/dist/runtime/csharp/Handler.cs +3 -3
- package/dist/runtime/csharp/Hooks.cs +3 -3
- package/dist/runtime/csharp/Invalidation.cs +2 -2
- package/dist/runtime/csharp/Json.cs +2 -2
- package/dist/runtime/csharp/Log.cs +2 -2
- package/dist/runtime/csharp/Operation.cs +2 -2
- package/dist/runtime/csharp/Path.cs +2 -2
- package/dist/runtime/csharp/Query.cs +2 -2
- package/dist/runtime/csharp/Realtime.cs +2 -2
- package/dist/runtime/csharp/RealtimeLoop.cs +3 -3
- package/dist/runtime/csharp/Redirect.cs +2 -2
- package/dist/runtime/csharp/Result.cs +2 -2
- package/dist/runtime/csharp/Sse.cs +2 -2
- package/dist/runtime/csharp/Stale.cs +2 -2
- package/dist/runtime/csharp/Transport.cs +2 -2
- package/dist/runtime/csharp/TransportLongPoll.cs +2 -2
- package/dist/runtime/csharp/TransportSse.cs +2 -2
- package/dist/runtime/csharp/TransportWs.cs +2 -2
- package/dist/runtime/csharp/Wire.cs +2 -2
- package/dist/runtime/csharp/Ws.cs +2 -2
- package/dist/runtime/csharp/WsDial.cs +2 -2
- package/dist/runtime/go/auth.go +1 -1
- package/dist/runtime/go/body.go +2 -2
- package/dist/runtime/go/config.go +1 -1
- package/dist/runtime/go/errors.go +5 -5
- package/dist/runtime/go/export.go +10 -10
- package/dist/runtime/go/hooks.go +2 -2
- package/dist/runtime/go/invalidation.go +2 -2
- package/dist/runtime/go/log.go +1 -1
- package/dist/runtime/go/nullable.go +1 -1
- package/dist/runtime/go/options.go +1 -1
- package/dist/runtime/go/path.go +1 -1
- package/dist/runtime/go/query.go +2 -2
- package/dist/runtime/go/realtime.go +4 -4
- package/dist/runtime/go/realtime_loop.go +1 -1
- package/dist/runtime/go/redirect.go +2 -2
- package/dist/runtime/go/request.go +9 -9
- package/dist/runtime/go/result.go +2 -2
- package/dist/runtime/go/sse.go +3 -3
- package/dist/runtime/go/stale.go +1 -1
- package/dist/runtime/go/stream.go +2 -2
- package/dist/runtime/go/transport.go +2 -2
- package/dist/runtime/go/transport_longpoll.go +1 -1
- package/dist/runtime/go/transport_sse.go +2 -2
- package/dist/runtime/go/ws.go +1 -1
- package/dist/runtime/java/Answer.java +2 -2
- package/dist/runtime/java/ApiException.java +2 -2
- package/dist/runtime/java/BinaryBody.java +2 -2
- package/dist/runtime/java/Body.java +4 -4
- package/dist/runtime/java/Call.java +2 -2
- package/dist/runtime/java/CallLog.java +2 -2
- package/dist/runtime/java/ClientConfig.java +2 -2
- package/dist/runtime/java/ConnectionState.java +2 -2
- package/dist/runtime/java/Credential.java +2 -2
- package/dist/runtime/java/Deadline.java +2 -2
- package/dist/runtime/java/Decode.java +2 -2
- package/dist/runtime/java/Envelope.java +2 -2
- package/dist/runtime/java/ErrorEnvelope.java +3 -3
- package/dist/runtime/java/EventStream.java +2 -2
- package/dist/runtime/java/Exchange.java +2 -2
- package/dist/runtime/java/FilePart.java +2 -2
- package/dist/runtime/java/Flight.java +3 -3
- package/dist/runtime/java/Hooks.java +3 -3
- package/dist/runtime/java/Hops.java +2 -2
- package/dist/runtime/java/{HoneyException.java → HttpException.java} +4 -4
- package/dist/runtime/java/InvalidationConfig.java +2 -2
- package/dist/runtime/java/Json.java +3 -3
- package/dist/runtime/java/Keepalive.java +2 -2
- package/dist/runtime/java/LogEntry.java +2 -2
- package/dist/runtime/java/LongPollAdapter.java +2 -2
- package/dist/runtime/java/Operation.java +2 -2
- package/dist/runtime/java/Opt.java +2 -2
- package/dist/runtime/java/Pump.java +2 -2
- package/dist/runtime/java/RawResponse.java +2 -2
- package/dist/runtime/java/Realtime.java +2 -2
- package/dist/runtime/java/RealtimeLoop.java +4 -4
- package/dist/runtime/java/RedirectPolicy.java +2 -2
- package/dist/runtime/java/Redirects.java +2 -2
- package/dist/runtime/java/RequestContext.java +2 -2
- package/dist/runtime/java/RequestHook.java +2 -2
- package/dist/runtime/java/RequestOptions.java +2 -2
- package/dist/runtime/java/ResponseContext.java +2 -2
- package/dist/runtime/java/ResponseHook.java +2 -2
- package/dist/runtime/java/Result.java +2 -2
- package/dist/runtime/java/ResumableConnection.java +2 -2
- package/dist/runtime/java/SdkException.java +3 -3
- package/dist/runtime/java/Socket.java +2 -2
- package/dist/runtime/java/Sse.java +2 -2
- package/dist/runtime/java/SseAdapter.java +2 -2
- package/dist/runtime/java/SseEvent.java +2 -2
- package/dist/runtime/java/StaleMeta.java +2 -2
- package/dist/runtime/java/StaleTracker.java +2 -2
- package/dist/runtime/java/Transport.java +2 -2
- package/dist/runtime/java/TransportAdapter.java +2 -2
- package/dist/runtime/java/TransportConnection.java +2 -2
- package/dist/runtime/java/TransportKind.java +2 -2
- package/dist/runtime/java/TransportMessage.java +2 -2
- package/dist/runtime/java/TransportOptions.java +2 -2
- package/dist/runtime/java/TypedWebSocket.java +2 -2
- package/dist/runtime/java/UrlPath.java +2 -2
- package/dist/runtime/java/UrlQuery.java +2 -2
- package/dist/runtime/java/WsAdapter.java +2 -2
- package/dist/runtime/java/WsClose.java +2 -2
- package/dist/runtime/java/WsDial.java +2 -2
- package/dist/runtime/java/WsMessage.java +2 -2
- package/dist/runtime/mcp/call.ts +3 -3
- package/dist/runtime/mcp/result.ts +2 -2
- package/dist/runtime/python/__init__.py +1 -1
- package/dist/runtime/python/auth.py +1 -1
- package/dist/runtime/python/body.py +1 -1
- package/dist/runtime/python/config.py +1 -1
- package/dist/runtime/python/errors.py +11 -11
- package/dist/runtime/python/events.py +4 -4
- package/dist/runtime/python/exchange.py +1 -1
- package/dist/runtime/python/hooks.py +4 -4
- package/dist/runtime/python/invalidation.py +1 -1
- package/dist/runtime/python/log.py +1 -1
- package/dist/runtime/python/operation.py +1 -1
- package/dist/runtime/python/path.py +1 -1
- package/dist/runtime/python/query.py +1 -1
- package/dist/runtime/python/realtime.py +5 -5
- package/dist/runtime/python/redirect.py +1 -1
- package/dist/runtime/python/result.py +1 -1
- package/dist/runtime/python/send_async.py +4 -4
- package/dist/runtime/python/send_sync.py +3 -3
- package/dist/runtime/python/sse.py +1 -1
- package/dist/runtime/python/stale.py +1 -1
- package/dist/runtime/python/transport.py +1 -1
- package/dist/runtime/python/transport_longpoll.py +1 -1
- package/dist/runtime/python/transport_sse.py +1 -1
- package/dist/runtime/python/transport_ws.py +1 -1
- package/dist/runtime/python/ws.py +3 -3
- package/dist/runtime/rust/Cargo.lock +1 -1
- package/dist/runtime/rust/answer.rs +1 -1
- package/dist/runtime/rust/auth.rs +1 -1
- package/dist/runtime/rust/body.rs +2 -2
- package/dist/runtime/rust/call.rs +1 -1
- package/dist/runtime/rust/config.rs +1 -1
- package/dist/runtime/rust/envelope.rs +3 -3
- package/dist/runtime/rust/errors.rs +3 -3
- package/dist/runtime/rust/events.rs +1 -1
- package/dist/runtime/rust/exchange.rs +1 -1
- package/dist/runtime/rust/hooks.rs +1 -1
- package/dist/runtime/rust/invalidation.rs +1 -1
- package/dist/runtime/rust/log.rs +1 -1
- package/dist/runtime/rust/nullable.rs +1 -1
- package/dist/runtime/rust/path.rs +1 -1
- package/dist/runtime/rust/query.rs +1 -1
- package/dist/runtime/rust/realtime.rs +1 -1
- package/dist/runtime/rust/realtime_loop.rs +1 -1
- package/dist/runtime/rust/redirect.rs +1 -1
- package/dist/runtime/rust/request.rs +1 -1
- package/dist/runtime/rust/result.rs +1 -1
- package/dist/runtime/rust/sse.rs +1 -1
- package/dist/runtime/rust/stale.rs +1 -1
- package/dist/runtime/rust/transport.rs +1 -1
- package/dist/runtime/rust/transport_longpoll.rs +1 -1
- package/dist/runtime/rust/transport_sse.rs +1 -1
- package/dist/runtime/rust/transport_ws.rs +1 -1
- package/dist/runtime/rust/ws.rs +1 -1
- package/dist/runtime/ts/app-types.ts +5 -5
- package/dist/runtime/ts/app.ts +5 -5
- package/dist/runtime/ts/http.ts +3 -3
- package/dist/runtime/ts/path.ts +1 -1
- package/dist/runtime/ts/request.ts +1 -1
- package/dist/runtime/ts/sdk.ts +1 -1
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -5,14 +5,14 @@ server from an OpenAPI 3.x document, or straight from a
|
|
|
5
5
|
[`@workerstack/backend`](https://www.npmjs.com/package/@workerstack/backend) app.
|
|
6
6
|
|
|
7
7
|
Every target reads one intermediate representation and vendors its own small runtime, so a generated SDK has no
|
|
8
|
-
dependency on
|
|
8
|
+
dependency on backend, and a spec from another framework generates just as well. The output is formatted and
|
|
9
9
|
deterministic: regenerating an unchanged spec changes nothing on disk.
|
|
10
10
|
|
|
11
11
|
This page is the whole generator — every target, every flag, and what each client looks like to call.
|
|
12
12
|
|
|
13
13
|
- [Install](#install)
|
|
14
14
|
- [Start](#start)
|
|
15
|
-
- [
|
|
15
|
+
- [clients generate](#clients-generate)
|
|
16
16
|
- [Every flag](#every-flag)
|
|
17
17
|
- [The six SDKs](#the-six-sdks)
|
|
18
18
|
- [The TypeScript SDK](#the-typescript-sdk)
|
|
@@ -33,7 +33,7 @@ This page is the whole generator — every target, every flag, and what each cli
|
|
|
33
33
|
|
|
34
34
|
## Install
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
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)
|
|
37
37
|
maps each old package name to its new one. 1.0 is out as a release candidate, published under npm's `next` tag, so
|
|
38
38
|
an install without a tag gets a deprecated placeholder.
|
|
39
39
|
Add `@next` until the final release:
|
|
@@ -51,53 +51,53 @@ Each target formats what it writes with that language's own formatter, when it c
|
|
|
51
51
|
| `go`, `cli` | gofmt | `$GOFMT`, `$GOROOT/bin/gofmt`, `gofmt` on `PATH`, beside the `go` on `PATH` |
|
|
52
52
|
| `python` | ruff | `$RUFF`, then `ruff` on `PATH` |
|
|
53
53
|
| `rust` | rustfmt | `$RUSTFMT`, the active toolchain's own binary beside `rustc`, `PATH` |
|
|
54
|
-
| `ts` | oxfmt | the `oxfmt` optional peer, installed beside
|
|
54
|
+
| `ts` | oxfmt | the `oxfmt` optional peer, installed beside clients |
|
|
55
55
|
|
|
56
56
|
A formatter it cannot find is named on standard error and skipped: the files go out as the emitter wrote them,
|
|
57
57
|
which is valid source either way, so generating a Python SDK never requires you to install ruff. Set
|
|
58
|
-
`
|
|
58
|
+
`CLIENTS_REQUIRE_FORMATTERS=1` to make a missing formatter fail the run instead, for a pipeline that would
|
|
59
59
|
rather stop than ship unformatted code. An override that points at nothing is refused by name.
|
|
60
60
|
|
|
61
|
-
oxfmt is the exception and says nothing when absent: it is
|
|
62
|
-
declared optional peer, so not having it is the documented normal rather than news. `
|
|
61
|
+
oxfmt is the exception and says nothing when absent: it is clients' own choice of TypeScript formatter and a
|
|
62
|
+
declared optional peer, so not having it is the documented normal rather than news. `CLIENTS_REQUIRE_FORMATTERS`
|
|
63
63
|
still stops for it.
|
|
64
64
|
|
|
65
65
|
The `csharp` and `java` targets are not formatted today: `dotnet format` and google-java-format work over a
|
|
66
|
-
project rather than a stream, which
|
|
66
|
+
project rather than a stream, which clients' post-pass does not yet do.
|
|
67
67
|
|
|
68
68
|
## Start
|
|
69
69
|
|
|
70
70
|
From a document:
|
|
71
71
|
|
|
72
72
|
```sh
|
|
73
|
-
npx
|
|
73
|
+
npx clients generate --spec openapi.json --target ts --target python --out generated
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
-
From a
|
|
76
|
+
From a backend app module, with no document written first:
|
|
77
77
|
|
|
78
78
|
```sh
|
|
79
|
-
npx
|
|
79
|
+
npx clients generate --app src/app.ts --target ts --target go --go-module-path github.com/acme/shop/sdk \
|
|
80
80
|
--out generated
|
|
81
81
|
```
|
|
82
82
|
|
|
83
83
|
The targets are `ts`, `go`, `rust`, `python`, `csharp`, `java`, `cli` and `mcp`. Each target's files go under
|
|
84
84
|
`<out>/<target>`.
|
|
85
85
|
|
|
86
|
-
##
|
|
86
|
+
## clients generate
|
|
87
87
|
|
|
88
88
|
```sh
|
|
89
|
-
|
|
89
|
+
clients generate --spec openapi.json --target ts --target cli --out generated \
|
|
90
90
|
--cli-binary-name shop --cli-module-path github.com/acme/shop --cli-repo acme/shop
|
|
91
91
|
```
|
|
92
92
|
|
|
93
93
|
- `--spec <file>`: the OpenAPI document, as JSON.
|
|
94
|
-
- `--app <module>[#export]`: a
|
|
95
|
-
`app`, else `default`, is the app; its document is made by the app's own `@workerstack/backend/openapi`, resolved from
|
|
94
|
+
- `--app <module>[#export]`: a backend app module instead of `--spec` (give one, never both). Its named export, else
|
|
95
|
+
`app`, else `default`, is the app; its document is made by the app's own `@workerstack/backend/http/openapi`, resolved from
|
|
96
96
|
the app as at run time, and the module's `openApi` export, if any, is that document's options (`info`,
|
|
97
97
|
`securitySchemes`, `invalidate`, …, as `generateOpenApi` takes them). Started by `bun run`, the bin hands the load to
|
|
98
98
|
that Bun, so a module needing Bun's loaders works; a run ends once it has written, whatever the module left open.
|
|
99
99
|
The module exports the app and serves nothing: one that calls `serve()` as it loads is outside `--app`'s contract,
|
|
100
|
-
since
|
|
100
|
+
since backend never serves implicitly and has no switch to stop it.
|
|
101
101
|
- `--target <name>`: `ts`, `go`, `rust`, `python`, `csharp`, `java`, `cli` or `mcp`; repeat it for more than one.
|
|
102
102
|
- `--out <dir>`: each target's files go under `<dir>/<target>`.
|
|
103
103
|
- `--<target>-<option>`: a target's options are its generator's, passed through as given. Each takes a value.
|
|
@@ -115,7 +115,7 @@ One table, since a flag that is not written down is a flag nobody finds:
|
|
|
115
115
|
| Flag | Target | What it sets |
|
|
116
116
|
| -------------------------- | ------ | --------------------------------------------------------------------------------- |
|
|
117
117
|
| `--spec <file>` | — | the OpenAPI document to generate from |
|
|
118
|
-
| `--app <module>[#export]` | — | a
|
|
118
|
+
| `--app <module>[#export]` | — | a backend app module instead of a document |
|
|
119
119
|
| `--target <name>` | — | which target to emit; repeat for more than one |
|
|
120
120
|
| `--out <dir>` | — | the output root; each target writes under `<dir>/<target>` |
|
|
121
121
|
| `--watch` | — | regenerate on each change, in a fresh process |
|
|
@@ -199,7 +199,7 @@ a place for the field, so a description or license is given once, not once per t
|
|
|
199
199
|
same meaning wins: `--java-description` over `--metadata-description`. Each field is checked before anything
|
|
200
200
|
generates: URLs must be https, the license an SPDX expression, text one line.
|
|
201
201
|
|
|
202
|
-
`--metadata-readme` and `--metadata-license-file` name files on disk, read once relative to where
|
|
202
|
+
`--metadata-readme` and `--metadata-license-file` name files on disk, read once relative to where clients runs. Every
|
|
203
203
|
target writes them into its package root as `README.md` and `LICENSE`, and each manifest points at the ones it has:
|
|
204
204
|
pyproject's `readme` and `license-files`, Cargo's `readme` and `include`, the `.csproj`'s `PackageReadmeFile` and packed
|
|
205
205
|
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
|
|
@@ -218,7 +218,7 @@ language's client in a slice of a compiled example; the
|
|
|
218
218
|
### The TypeScript SDK
|
|
219
219
|
|
|
220
220
|
```sh
|
|
221
|
-
|
|
221
|
+
clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen
|
|
222
222
|
```
|
|
223
223
|
|
|
224
224
|
```ts sdk
|
|
@@ -261,7 +261,7 @@ also gets a `jsr.json` that publishes the sources themselves, its `.js` imports
|
|
|
261
261
|
`--metadata-*` fills description, keywords, homepage, bugs, license, author and repository.
|
|
262
262
|
|
|
263
263
|
```sh
|
|
264
|
-
|
|
264
|
+
clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen \
|
|
265
265
|
--ts-package-name @acme/kitchen --ts-version 1.4.0 --metadata-license MIT
|
|
266
266
|
```
|
|
267
267
|
|
|
@@ -270,7 +270,7 @@ honey-clients generate --spec openapi.json --target ts --out generated --ts-name
|
|
|
270
270
|
`--ts-tanstack-query` writes one more file beside the SDK, `<stem>.tanstack-query.gen.ts`. It takes no value:
|
|
271
271
|
|
|
272
272
|
```sh
|
|
273
|
-
|
|
273
|
+
clients generate --spec openapi.json --target ts --out generated --ts-name Kitchen --ts-tanstack-query
|
|
274
274
|
```
|
|
275
275
|
|
|
276
276
|
Its `createQueryHelpers(sdk, { getQueryClient })` gives five surfaces — `query`, `mutation`, `infiniteQuery`,
|
|
@@ -296,11 +296,11 @@ filter's own positions, so that reaches every search of that read, the paged ent
|
|
|
296
296
|
params are not all known the filter stays the bare prefix, which reaches everything under it — made stale
|
|
297
297
|
rather than missed.
|
|
298
298
|
|
|
299
|
-
Two notes. `@tanstack/query-core` is your dependency, not
|
|
299
|
+
Two notes. `@tanstack/query-core` is your dependency, not backend's — install it yourself; the file imports it for
|
|
300
300
|
types only. And a read's options carry `initialData: undefined`, which is what solid-query needs to keep the
|
|
301
301
|
unseeded overload; it is harmless under react-query.
|
|
302
302
|
|
|
303
|
-
Drop the flag and the next run deletes the file, the way `.
|
|
303
|
+
Drop the flag and the next run deletes the file, the way `.clients-generated.json` deletes anything the previous
|
|
304
304
|
run wrote and this one did not. The index file never re-exports the adapter, so an SDK generated without the
|
|
305
305
|
flag names no TanStack type anywhere.
|
|
306
306
|
|
|
@@ -310,7 +310,7 @@ Idiomatic Go: a `Config`, `context.Context` on every call, errors read with `err
|
|
|
310
310
|
`range` over a function.
|
|
311
311
|
|
|
312
312
|
```sh
|
|
313
|
-
|
|
313
|
+
clients generate --spec openapi.json --target go --out generated --go-module-path github.com/acme/shop/sdk
|
|
314
314
|
```
|
|
315
315
|
|
|
316
316
|
Go wants a v2-or-later module's major version at the end of its path, so pass the base path and the version:
|
|
@@ -343,7 +343,7 @@ func listing(ctx context.Context, client *sdk.Client) string {
|
|
|
343
343
|
Async over `reqwest`, each call taking its options struct, with the safe mirror as a second client style.
|
|
344
344
|
|
|
345
345
|
```sh
|
|
346
|
-
|
|
346
|
+
clients generate --spec openapi.json --target rust --out generated --rust-crate-name shop-sdk
|
|
347
347
|
```
|
|
348
348
|
|
|
349
349
|
```rust
|
|
@@ -369,13 +369,13 @@ A sync `SDK` and an async `AsyncSDK`, both context managers, typed for `mypy --s
|
|
|
369
369
|
dataclasses to narrow with `match`.
|
|
370
370
|
|
|
371
371
|
```sh
|
|
372
|
-
|
|
372
|
+
clients generate --spec openapi.json --target python --out generated --python-package-name shop_sdk
|
|
373
373
|
```
|
|
374
374
|
|
|
375
375
|
`pyproject.toml` builds with hatchling and carries what PyPI shows: `--metadata-*` gives the description, the SPDX
|
|
376
376
|
`license` (PEP 639, so no `License ::` classifier), authors, keywords, and `[project.urls]` (Homepage, Source,
|
|
377
|
-
Issues, Documentation, Changelog). The classifiers name the Python versions
|
|
378
|
-
|
|
377
|
+
Issues, Documentation, Changelog). The classifiers name the Python versions clients tests and `Typing :: Typed`, and
|
|
378
|
+
clients' own manifest stays out of the sdist.
|
|
379
379
|
|
|
380
380
|
```python
|
|
381
381
|
async def health(client: AsyncSDK) -> str:
|
|
@@ -394,7 +394,7 @@ A .NET project with its own `HttpClient` pipeline, `IAsyncDisposable` streams, a
|
|
|
394
394
|
`Result<T>`.
|
|
395
395
|
|
|
396
396
|
```sh
|
|
397
|
-
|
|
397
|
+
clients generate --spec openapi.json --target csharp --out generated --csharp-package-id Acme.Shop
|
|
398
398
|
```
|
|
399
399
|
|
|
400
400
|
nuget.org shows a package's description, authors, license and links: give them with `--csharp-description`,
|
|
@@ -402,7 +402,7 @@ nuget.org shows a package's description, authors, license and links: give them w
|
|
|
402
402
|
into `dotnet pack`.
|
|
403
403
|
|
|
404
404
|
```csharp
|
|
405
|
-
public static async Task<string> Listing(
|
|
405
|
+
public static async Task<string> Listing(HttpSdkClient client, string id)
|
|
406
406
|
{
|
|
407
407
|
var result = await client.Safe.GetApiAsync(id); // no answer (never sent, refused, timed out, canceled) still throws
|
|
408
408
|
return result.Match(
|
|
@@ -422,7 +422,7 @@ A Java 17 library on Jackson 3, with builders, `try`-with-resources streams, `cl
|
|
|
422
422
|
`Result<T>`, and a Gradle publication.
|
|
423
423
|
|
|
424
424
|
```sh
|
|
425
|
-
|
|
425
|
+
clients generate --spec openapi.json --target java --out generated --java-group-id com.acme
|
|
426
426
|
```
|
|
427
427
|
|
|
428
428
|
Maven Central refuses a POM without a URL, a license, a developer and scm: give them with `--java-homepage`,
|
|
@@ -471,7 +471,7 @@ release workflow, which can publish to Homebrew, Scoop, winget, AUR and deb/rpm/
|
|
|
471
471
|
install scripts that verify what they install.
|
|
472
472
|
|
|
473
473
|
```sh
|
|
474
|
-
|
|
474
|
+
clients generate --spec openapi.json --target cli --out ./cli --cli-repo acme/shop-cli
|
|
475
475
|
shop orders list --status open --output json
|
|
476
476
|
```
|
|
477
477
|
|
|
@@ -517,7 +517,7 @@ Full reference: [installgen](https://github.com/workerstack/clients/blob/main/sr
|
|
|
517
517
|
|
|
518
518
|
## Release tooling
|
|
519
519
|
|
|
520
|
-
`
|
|
520
|
+
`clients release` cuts versions for a product's public packages and mirrors each one to its own GitHub repo.
|
|
521
521
|
A product describes its packages once, in a `release.config.ts` typed by the `@workerstack/clients/release`
|
|
522
522
|
library; each package's dir sits beside the config, and the repo root is the config's git toplevel:
|
|
523
523
|
|
|
@@ -536,9 +536,9 @@ export default defineRelease({
|
|
|
536
536
|
```
|
|
537
537
|
|
|
538
538
|
```sh
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
539
|
+
clients release bump --config acme-release/release.config.ts [--major]
|
|
540
|
+
clients release sync --config acme-release/release.config.ts [--only sdk] [--dry-run] [--validate-only]
|
|
541
|
+
clients release bootstrap --config acme-release/release.config.ts (--all | --only sdk) [--force-bootstrap]
|
|
542
542
|
```
|
|
543
543
|
|
|
544
544
|
`bump` writes each changed package's version files, `CHANGELOG.md` and `.release-state.json` (an API change is a
|
|
@@ -554,7 +554,7 @@ status and key, never as a successful result. Read-only operations are annotated
|
|
|
554
554
|
default, and Streamable HTTP with `--http`.
|
|
555
555
|
|
|
556
556
|
```sh
|
|
557
|
-
|
|
557
|
+
clients generate --spec openapi.json --target mcp --out ./mcp --mcp-name acme
|
|
558
558
|
```
|
|
559
559
|
|
|
560
560
|
Its package publishes to npm as written. `--mcp-package-name @acme/shop-mcp` names it (its bin keeps the server's
|
|
@@ -596,13 +596,13 @@ Full reference: [the generated MCP server](https://github.com/workerstack/backen
|
|
|
596
596
|
|
|
597
597
|
## Configuring generation
|
|
598
598
|
|
|
599
|
-
In a
|
|
599
|
+
In a backend project the generation is configured once, in the Vite plugin, and `clients generate --app` reads
|
|
600
600
|
the same app. `codegen.mcp` writes the handler `mcp()` mounts, and `codegen.openApi` the document the SDKs are
|
|
601
601
|
generated from:
|
|
602
602
|
|
|
603
603
|
```sh
|
|
604
604
|
# the whole set, from the app module, in one run
|
|
605
|
-
npx
|
|
605
|
+
npx clients generate --app src/app.ts \
|
|
606
606
|
--target ts --target go --target python --target cli --target mcp \
|
|
607
607
|
--go-module-path github.com/acme/shop/sdk --cli-repo acme/shop-cli --out generated
|
|
608
608
|
```
|
|
@@ -610,7 +610,7 @@ npx honey-clients generate --app src/app.ts \
|
|
|
610
610
|
```json
|
|
611
611
|
{
|
|
612
612
|
"scripts": {
|
|
613
|
-
"generate": "
|
|
613
|
+
"generate": "backend generate && clients generate --app src/app.ts --target ts --out generated"
|
|
614
614
|
}
|
|
615
615
|
}
|
|
616
616
|
```
|
|
@@ -621,7 +621,7 @@ from a developer's.
|
|
|
621
621
|
|
|
622
622
|
## What a run writes
|
|
623
623
|
|
|
624
|
-
**Stale files are deleted, edited ones kept.** Each `<out>/<target>` keeps `.
|
|
624
|
+
**Stale files are deleted, edited ones kept.** Each `<out>/<target>` keeps `.clients-generated.json`: every file the
|
|
625
625
|
run wrote, with its sha256. A file is rewritten only when its bytes change, through a temp file renamed over it. A
|
|
626
626
|
regeneration deletes a file the last run wrote and this one does not (a `cli` target's old `<name>_cmds.go`, say),
|
|
627
627
|
unless it was edited since: that one is kept and named on stderr. A file the manifest never listed is never deleted,
|
|
@@ -637,7 +637,7 @@ the package on each registry it publishes to, as `{ registry, name, version }` (
|
|
|
637
637
|
`npm` and `mcp-registry` for an MCP server with an `mcpName`, `pypi`, `crates.io`, `nuget`, `maven-central` as
|
|
638
638
|
`group:artifact`, and `go` by the module path, its `/vN` included and no version when none is given).
|
|
639
639
|
`writeTarget(dir, files, packages)` writes one target's into a directory you pick under the same rules, keeping
|
|
640
|
-
`MANIFEST` (`.
|
|
640
|
+
`MANIFEST` (`.clients-generated.json`) there with the packages recorded beside the files, so a release reads each name
|
|
641
641
|
and version from it. A file the last call wrote that you leave out of `files` is stale: deleted if unedited, kept and
|
|
642
642
|
named in the result's `kept` if you changed it, and dropped from the manifest either way, so a file you take over by
|
|
643
643
|
editing is never touched again.
|
|
@@ -656,7 +656,7 @@ const result = targetOptionSchemas.go["~standard"].validate({ modulePath: "githu
|
|
|
656
656
|
export const ok = result.issues === undefined && TARGETS.includes("go")
|
|
657
657
|
```
|
|
658
658
|
|
|
659
|
-
This package also exports the app-side generators the
|
|
659
|
+
This package also exports the app-side generators the backend CLI and Vite plugin use: `generateRouteTree`,
|
|
660
660
|
`generateTypes` and `extractTypes` from `@workerstack/clients`, and the command's own entry at
|
|
661
661
|
`@workerstack/clients/cli`.
|
|
662
662
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// The
|
|
3
|
-
// runs the TypeScript source, natively on Bun (under the
|
|
2
|
+
// The clients bin (bit 17 phase h). A repository checkout (marked by tsconfig.json, which is not published)
|
|
3
|
+
// runs the TypeScript source, natively on Bun (under the backend-source condition) and through jiti on Node, so a stale
|
|
4
4
|
// dist/ never runs; an installed package runs the compiled JavaScript on any runtime (the tarball ships dist/, not src/).
|
|
5
5
|
import { spawn } from "node:child_process"
|
|
6
6
|
import { existsSync } from "node:fs"
|
|
@@ -13,7 +13,7 @@ const checkout = existsSync(new URL("../tsconfig.json", import.meta.url))
|
|
|
13
13
|
// `bun run` and `bunx` start this file through its node shebang, while what they run is meant for Bun: hand over to
|
|
14
14
|
// the Bun that started us, which they name in npm_execpath. Once, never again in the child.
|
|
15
15
|
function invokingBun() {
|
|
16
|
-
if (isBun || process.env.
|
|
16
|
+
if (isBun || process.env.CLIENTS_NO_BUN_HANDOFF === "1") return null
|
|
17
17
|
if (!process.env.npm_config_user_agent?.startsWith("bun/")) return null
|
|
18
18
|
const bun = process.env.npm_execpath
|
|
19
19
|
if (!bun || !/^bunx?(\.exe)?$/.test(basename(bun)) || !existsSync(bun)) return null
|
|
@@ -29,11 +29,11 @@ function handOff(bun, env) {
|
|
|
29
29
|
const forward = (signal) => child.kill(signal)
|
|
30
30
|
for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, forward)
|
|
31
31
|
child = spawn(bun, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
|
|
32
|
-
env: { ...process.env, ...env,
|
|
32
|
+
env: { ...process.env, ...env, CLIENTS_NO_BUN_HANDOFF: "1" },
|
|
33
33
|
stdio: "inherit",
|
|
34
34
|
})
|
|
35
35
|
child.on("error", (error) => {
|
|
36
|
-
console.error(`
|
|
36
|
+
console.error(`clients: could not start ${bun}: ${error.message}`)
|
|
37
37
|
process.exit(1)
|
|
38
38
|
})
|
|
39
39
|
child.on("exit", (code, signal) => {
|
|
@@ -46,19 +46,19 @@ function handOff(bun, env) {
|
|
|
46
46
|
})
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
-
// A checkout on Bun runs under the
|
|
49
|
+
// A checkout on Bun runs under the backend-source condition: an --app module's checkout core then resolves to its
|
|
50
50
|
// source, never to an unbuilt or stale dist/ (bit 20). Set through BUN_OPTIONS when the caller did not, in the one
|
|
51
51
|
// handoff, so a watch's generation children inherit it; Bun reports BUN_OPTIONS' flags in execArgv, so a Bun started
|
|
52
52
|
// with it never hands off again.
|
|
53
|
-
const SOURCE_CONDITION = "--conditions=
|
|
53
|
+
const SOURCE_CONDITION = "--conditions=backend-source"
|
|
54
54
|
const unconditioned = isBun && checkout && !process.execArgv.includes(SOURCE_CONDITION)
|
|
55
|
-
// The hand-off's backstop: its child carries
|
|
55
|
+
// The hand-off's backstop: its child carries CLIENTS_BUN_HANDOFF, the depth of hand-offs before it. A child that would
|
|
56
56
|
// hand off again (the condition set but not in its execArgv) refuses instead of re-running itself without end.
|
|
57
|
-
const handOffDepth = Number(process.env.
|
|
57
|
+
const handOffDepth = Number(process.env.CLIENTS_BUN_HANDOFF ?? 0)
|
|
58
58
|
const sourceEnv = checkout
|
|
59
59
|
? {
|
|
60
60
|
BUN_OPTIONS: `${process.env.BUN_OPTIONS ?? ""} ${SOURCE_CONDITION}`.trim(),
|
|
61
|
-
|
|
61
|
+
CLIENTS_BUN_HANDOFF: String(handOffDepth + 1),
|
|
62
62
|
}
|
|
63
63
|
: {}
|
|
64
64
|
|
|
@@ -72,7 +72,7 @@ async function entry() {
|
|
|
72
72
|
return await import("../dist/cli.js")
|
|
73
73
|
} catch (error) {
|
|
74
74
|
if (error?.code === "ERR_MODULE_NOT_FOUND" && String(error.url).endsWith("/dist/cli.js")) {
|
|
75
|
-
console.error("
|
|
75
|
+
console.error("clients: dist/ is missing from this install. Reinstall it, or run it with Bun.")
|
|
76
76
|
process.exit(1)
|
|
77
77
|
}
|
|
78
78
|
throw error
|
|
@@ -82,7 +82,7 @@ async function entry() {
|
|
|
82
82
|
const bun = invokingBun()
|
|
83
83
|
if (bun) handOff(bun, sourceEnv)
|
|
84
84
|
else if (unconditioned && handOffDepth >= 1) {
|
|
85
|
-
console.error("
|
|
85
|
+
console.error("clients: Bun hand-off loop: --conditions=backend-source not visible after re-exec")
|
|
86
86
|
process.exit(1)
|
|
87
87
|
} else if (unconditioned) handOff(process.execPath, sourceEnv)
|
|
88
88
|
else {
|
package/dist/cli.d.ts
CHANGED
|
@@ -25,7 +25,7 @@ export type GenerateRun = {
|
|
|
25
25
|
/** What a generation reads beside its run: the environment, where skips are reported, the oxfmt module to load. */
|
|
26
26
|
export type GenerateContext = {
|
|
27
27
|
/**
|
|
28
|
-
* Where formatters are looked up (`PATH`, `GOROOT`, `GOFMT`, `RUFF`, `RUSTFMT`); `
|
|
28
|
+
* Where formatters are looked up (`PATH`, `GOROOT`, `GOFMT`, `RUFF`, `RUSTFMT`); `CLIENTS_REQUIRE_FORMATTERS=1` makes
|
|
29
29
|
* a missing one throw.
|
|
30
30
|
*/
|
|
31
31
|
readonly env: NodeJS.ProcessEnv;
|
|
@@ -62,7 +62,7 @@ export type Generated = {
|
|
|
62
62
|
/**
|
|
63
63
|
* Every file a run writes, by target and its path under the target's directory. Go goes through gofmt, Python through
|
|
64
64
|
* ruff, Rust through rustfmt and TS through oxfmt; C# and Java go out as emitted, as does a target whose formatter is
|
|
65
|
-
* missing, unless `
|
|
65
|
+
* missing, unless `CLIENTS_REQUIRE_FORMATTERS=1` makes that throw. The README and license file the metadata block names
|
|
66
66
|
* go into every target's root as they are, its icon into the C# package's alone.
|
|
67
67
|
*/
|
|
68
68
|
export declare function generated(run: GenerateRun, document: Record<string, unknown>, { env, oxfmt, read, report }: GenerateContext): Promise<Generated>;
|
|
@@ -98,5 +98,5 @@ export type RunOptions = {
|
|
|
98
98
|
*/
|
|
99
99
|
readonly signal?: AbortSignal;
|
|
100
100
|
};
|
|
101
|
-
/** Runs `
|
|
101
|
+
/** Runs `clients <argv>`: the exit code it ends with (a watch ends only by `options.signal`). */
|
|
102
102
|
export declare function main(argv: readonly string[], io?: Io, options?: RunOptions): Promise<number>;
|
package/dist/cli.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The
|
|
2
|
+
* The clients generate CLI (bit 17 phase h): `clients generate --spec <openapi.json> --target <name>...
|
|
3
3
|
* --out <dir>` writes each target's generated files under `<out>/<target>`. A target's options are its generate
|
|
4
4
|
* function's, spelled `--<target>-<option>` and passed through untouched: each generator validates its own. The go and
|
|
5
5
|
* cli targets' whole trees go through gofmt (the post-pass), so a missing gofmt is a refusal, never unformatted Go; the
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* `--watch` regenerates in a fresh child on each change of the spec. Parsing is strict: an unknown flag, a missing
|
|
8
8
|
* value, a stray argument or an option for a target not asked for is a usage error. Each target is written through
|
|
9
9
|
* write.ts: only changed files, a hashed manifest, a removed operation's unedited files deleted (bit 19 h1). `--app`
|
|
10
|
-
* generates from a
|
|
10
|
+
* generates from a backend app module instead of a spec, its document made by the app's own core (ir/load.ts, bit 19 h2).
|
|
11
11
|
*/
|
|
12
12
|
import { readFileSync, watch } from "node:fs";
|
|
13
13
|
import { basename, dirname, join, resolve } from "node:path";
|
|
@@ -65,18 +65,18 @@ function packageOf(target, document, { metadata, options }, report) {
|
|
|
65
65
|
if (target === "mcp") {
|
|
66
66
|
const server = generateMcpServer(document, options, metadata);
|
|
67
67
|
for (const op of server.skipped)
|
|
68
|
-
report(`
|
|
68
|
+
report(`clients: mcp: no tool serves ${op} yet: skipped\n`);
|
|
69
69
|
return server;
|
|
70
70
|
}
|
|
71
71
|
const sdk = sdkOf(target, document, options, metadata);
|
|
72
72
|
for (const notice of sdk.notices)
|
|
73
|
-
report(`
|
|
73
|
+
report(`clients: ${notice}\n`);
|
|
74
74
|
return sdk;
|
|
75
75
|
}
|
|
76
76
|
/**
|
|
77
77
|
* Every file a run writes, by target and its path under the target's directory. Go goes through gofmt, Python through
|
|
78
78
|
* ruff, Rust through rustfmt and TS through oxfmt; C# and Java go out as emitted, as does a target whose formatter is
|
|
79
|
-
* missing, unless `
|
|
79
|
+
* missing, unless `CLIENTS_REQUIRE_FORMATTERS=1` makes that throw. The README and license file the metadata block names
|
|
80
80
|
* go into every target's root as they are, its icon into the C# package's alone.
|
|
81
81
|
*/
|
|
82
82
|
export async function generated(run, document, { env, oxfmt, read = readFileSync, report }) {
|
|
@@ -125,10 +125,10 @@ export async function writeGenerated(run, document, io, env) {
|
|
|
125
125
|
let count = 0;
|
|
126
126
|
for (const [target, { files, packages }] of Object.entries(await generated(run, document, { env, report: io.err }))) {
|
|
127
127
|
for (const rel of writeTarget(join(run.out, target), files, packages).kept)
|
|
128
|
-
io.err(`
|
|
128
|
+
io.err(`clients: ${join(target, rel)} is stale but edited since it was generated, or not its to delete: kept\n`);
|
|
129
129
|
count += Object.keys(files).length;
|
|
130
130
|
}
|
|
131
|
-
io.out(`
|
|
131
|
+
io.out(`clients: generated ${count} files into ${run.out}\n`);
|
|
132
132
|
return 0;
|
|
133
133
|
}
|
|
134
134
|
/** One generation: the spec read, or the app's document made (the module resolved from `cwd`), then written. */
|
|
@@ -139,16 +139,16 @@ async function generateOnce(run, io, env, cwd) {
|
|
|
139
139
|
/**
|
|
140
140
|
* Generates now and on each change of the spec, each run a fresh child after the one before it (a change during a run
|
|
141
141
|
* is one more run, never two at once); `signal` stops the watch, which then ends 0 once the last run is done. A
|
|
142
|
-
* generation child (
|
|
142
|
+
* generation child (CLIENTS_CODEGEN_CHILD) never watches: were `--watch` ever passed down, each child would start another.
|
|
143
143
|
*/
|
|
144
144
|
function watchSpec(run, argv, io, options) {
|
|
145
|
-
if (options.env.
|
|
145
|
+
if (options.env.CLIENTS_CODEGEN_CHILD === "1")
|
|
146
146
|
throw new Error("--watch is not allowed in a generation child");
|
|
147
147
|
const args = ["generate", ...argv.filter((arg) => arg !== "--watch" && !arg.startsWith("--watch="))];
|
|
148
148
|
const spec = resolve(options.cwd, run.app === "" ? run.spec : appRef(run.app).module);
|
|
149
149
|
let queue = Promise.resolve();
|
|
150
150
|
const generate = () => {
|
|
151
|
-
queue = queue.then(() => runCli(args, { cwd: options.cwd, env: options.env }).catch((error) => io.err(`
|
|
151
|
+
queue = queue.then(() => runCli(args, { cwd: options.cwd, env: options.env }).catch((error) => io.err(`clients: ${error.message}\n`)));
|
|
152
152
|
};
|
|
153
153
|
let timer;
|
|
154
154
|
const watcher = watch(dirname(spec), (_event, name) => {
|
|
@@ -157,7 +157,7 @@ function watchSpec(run, argv, io, options) {
|
|
|
157
157
|
clearTimeout(timer);
|
|
158
158
|
timer = setTimeout(generate, 100);
|
|
159
159
|
});
|
|
160
|
-
io.out(`
|
|
160
|
+
io.out(`clients: watching ${spec}\n`);
|
|
161
161
|
generate();
|
|
162
162
|
return new Promise((settle) => options.signal?.addEventListener("abort", () => {
|
|
163
163
|
watcher.close();
|
|
@@ -165,7 +165,7 @@ function watchSpec(run, argv, io, options) {
|
|
|
165
165
|
void queue.then(() => settle(0));
|
|
166
166
|
}, { once: true }));
|
|
167
167
|
}
|
|
168
|
-
/** Runs `
|
|
168
|
+
/** Runs `clients <argv>`: the exit code it ends with (a watch ends only by `options.signal`). */
|
|
169
169
|
export async function main(argv, io = PROCESS_IO, options = {}) {
|
|
170
170
|
try {
|
|
171
171
|
/* release has subcommands of its own, each with its own --help */
|
|
@@ -185,10 +185,10 @@ export async function main(argv, io = PROCESS_IO, options = {}) {
|
|
|
185
185
|
}
|
|
186
186
|
catch (error) {
|
|
187
187
|
if (error instanceof UsageError) {
|
|
188
|
-
io.err(`
|
|
188
|
+
io.err(`clients: ${error.message}\n\n${usage()}\n`);
|
|
189
189
|
return 1;
|
|
190
190
|
}
|
|
191
|
-
io.err(`
|
|
191
|
+
io.err(`clients: ${error.message}\n`);
|
|
192
192
|
return 1;
|
|
193
193
|
}
|
|
194
194
|
}
|
|
@@ -89,7 +89,7 @@ const SKETCHES = {
|
|
|
89
89
|
const shown = (schema, at) => SKETCHES[schema.kind](schema, at);
|
|
90
90
|
/** `schema` as a type sketch: refs inlined, one already open by its name, objects past SKETCH_DEPTH as `{…}`. */
|
|
91
91
|
export const sketch = (schema, model) => shown(schema, { depth: 0, model, open: [] });
|
|
92
|
-
/** Each declared error status, with the keys its
|
|
92
|
+
/** Each declared error status, with the keys its backend error envelope names: `[status, keys]`. */
|
|
93
93
|
function errorsOf(op, model) {
|
|
94
94
|
return op.errorStatuses.map((status) => {
|
|
95
95
|
/* an error status is one of the operation's declared responses */
|
package/dist/emit/cli/install.js
CHANGED
|
@@ -64,8 +64,8 @@ export function installgenConfigFile(app) {
|
|
|
64
64
|
const installgen = installgenCommand();
|
|
65
65
|
const { asset, checksums, identity, plain } = layout(app, `https://github.com/${app.repo}/releases`);
|
|
66
66
|
const value = (key) => `\t${key}: ${JSON.stringify(plain[key])},\n`;
|
|
67
|
-
return `// Code generated by
|
|
68
|
-
// installgen's config for ${app.bin}'s install scripts, as
|
|
67
|
+
return `// Code generated by clients. DO NOT EDIT.
|
|
68
|
+
// installgen's config for ${app.bin}'s install scripts, as clients wrote them: the release workflow runs
|
|
69
69
|
// \`${installgen} check\` with it to prove a release serves every file they fetch.
|
|
70
70
|
import type { InstallgenConfig } from "@workerstack/clients/installers"
|
|
71
71
|
|
package/dist/emit/cli/layout.js
CHANGED
|
@@ -5,7 +5,7 @@ import { groupFuncs } from "./commands.js";
|
|
|
5
5
|
import { discoveryBody } from "./discovery.js";
|
|
6
6
|
import { helpText } from "./flags.js";
|
|
7
7
|
/* the marker gopls and linters read, apart from the package doc by a blank line */
|
|
8
|
-
const MARKER = "// Code generated by
|
|
8
|
+
const MARKER = "// Code generated by clients. DO NOT EDIT.";
|
|
9
9
|
/** What a cmd file imports, by the packages its code names: the runtime always. */
|
|
10
10
|
const importsOf = (text) => {
|
|
11
11
|
const code = text.replace(NOT_CODE, "");
|
package/dist/emit/cli/module.js
CHANGED
|
@@ -22,7 +22,7 @@ import { cmdFiles } from "./layout.js";
|
|
|
22
22
|
import { goreleaserFile, releaseWorkflow, REPO, resolvedRelease } from "./release.js";
|
|
23
23
|
import { skillFile, skillPath } from "./skills.js";
|
|
24
24
|
/* the marker gopls and linters read, apart from the package doc by a blank line */
|
|
25
|
-
const MARKER = "// Code generated by
|
|
25
|
+
const MARKER = "// Code generated by clients. DO NOT EDIT.";
|
|
26
26
|
/** The runtime files a CLI ships, read from `runtime/cli/` and nowhere else; SOCKET only beside the WebSocket library. */
|
|
27
27
|
export const CLI_RUNTIME = [
|
|
28
28
|
"body.go",
|
package/dist/emit/cli/release.js
CHANGED
|
@@ -20,7 +20,7 @@ import { channelBlock, SECRETS } from "./channels.js";
|
|
|
20
20
|
import { installgenCommand } from "./install.js";
|
|
21
21
|
export { REPO, resolvedRelease } from "./channels.js";
|
|
22
22
|
/* the marker generated YAML carries on its first line */
|
|
23
|
-
const MARKER = "# Code generated by
|
|
23
|
+
const MARKER = "# Code generated by clients. DO NOT EDIT.";
|
|
24
24
|
/** The tools release.yml runs, each pinned by commit (its release in the comment beside it). */
|
|
25
25
|
export const RELEASE_ACTIONS = {
|
|
26
26
|
attest: "actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2",
|
|
@@ -16,7 +16,7 @@ function envelopeKeys(model) {
|
|
|
16
16
|
}));
|
|
17
17
|
}
|
|
18
18
|
/**
|
|
19
|
-
* Every declared key in code-unit order with its schema: `x-
|
|
19
|
+
* Every declared key in code-unit order with its schema: `x-backend-errors`' (the first operation by id to declare
|
|
20
20
|
* the key, so the document's path order never changes it), over an envelope's keys, which carry none.
|
|
21
21
|
*/
|
|
22
22
|
function declaredKeys(model) {
|
|
@@ -130,7 +130,7 @@ function clientClass(ir, root, env, render) {
|
|
|
130
130
|
` public ${mirror} ${SAFE} { get; }`,
|
|
131
131
|
];
|
|
132
132
|
return [
|
|
133
|
-
...docLines("summary", `${title}, generated by
|
|
133
|
+
...docLines("summary", `${title}, generated by clients.`),
|
|
134
134
|
...docLines("remarks", ir.info.description),
|
|
135
135
|
`public sealed class ${env.client} : IDisposable`,
|
|
136
136
|
"{",
|
|
@@ -33,4 +33,4 @@ export declare function validateVersion(value: string): string;
|
|
|
33
33
|
/** The `.csproj`: the package id as the assembly name, the metadata given, no package reference (H11). */
|
|
34
34
|
export declare const csproj: ({ metadata, packageId, rootNamespace, shipped, version, }: CSharpPackage) => string;
|
|
35
35
|
/** The root `.editorconfig` the emitted layout is written to and the format gate holds it to (Fb8). */
|
|
36
|
-
export declare const EDITORCONFIG = "# @generated by
|
|
36
|
+
export declare const EDITORCONFIG = "# @generated by clients. DO NOT EDIT.\nroot = true\n\n[*.cs]\ncharset = utf-8\nend_of_line = lf\nindent_size = 4\nindent_style = space\ninsert_final_newline = true\n";
|
|
@@ -104,7 +104,7 @@ function shippedLines(shipped) {
|
|
|
104
104
|
};
|
|
105
105
|
}
|
|
106
106
|
/** The `.csproj`: the package id as the assembly name, the metadata given, no package reference (H11). */
|
|
107
|
-
export const csproj = ({ metadata, packageId, rootNamespace, shipped, version, }) => `<!-- @generated by
|
|
107
|
+
export const csproj = ({ metadata, packageId, rootNamespace, shipped, version, }) => `<!-- @generated by clients. DO NOT EDIT. -->
|
|
108
108
|
<Project Sdk="Microsoft.NET.Sdk">
|
|
109
109
|
<PropertyGroup>
|
|
110
110
|
<TargetFramework>${TARGET_FRAMEWORK}</TargetFramework>
|
|
@@ -124,7 +124,7 @@ ${metadataLines(metadata)}${shippedLines(shipped).property} <Nullable>enable<
|
|
|
124
124
|
${shippedLines(shipped).items}</Project>
|
|
125
125
|
`;
|
|
126
126
|
/** The root `.editorconfig` the emitted layout is written to and the format gate holds it to (Fb8). */
|
|
127
|
-
export const EDITORCONFIG = `# @generated by
|
|
127
|
+
export const EDITORCONFIG = `# @generated by clients. DO NOT EDIT.
|
|
128
128
|
root = true
|
|
129
129
|
|
|
130
130
|
[*.cs]
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type PackageIdentity, type Shipped } from "../shared/metadata.ts";
|
|
2
2
|
import type { CSharpCallPlan } from "./sdk-plan.ts";
|
|
3
3
|
export type CSharpSdkOptions = {
|
|
4
|
-
/** the NuGet package id and assembly name; `
|
|
4
|
+
/** the NuGet package id and assembly name; `HttpSdk` by default */
|
|
5
5
|
readonly packageId?: string;
|
|
6
6
|
/** the namespace of every type; the package id by default */
|
|
7
7
|
readonly rootNamespace?: string;
|
package/dist/emit/csharp/sdk.js
CHANGED
|
@@ -23,10 +23,10 @@ import { runtimeFiles } from "./transport.js";
|
|
|
23
23
|
import { usings } from "./types-names.js";
|
|
24
24
|
import { csTopLevel, csTypeContext, declares } from "./types.js";
|
|
25
25
|
/* the marker every .cs file opens with; never `<auto-generated`, which the format gate and the analyzers skip (Q4) */
|
|
26
|
-
const MARKER = "// @generated by
|
|
26
|
+
const MARKER = "// @generated by clients. DO NOT EDIT.";
|
|
27
27
|
/** The options validated, each default filled in, and the client's and its context's class names. */
|
|
28
28
|
function identity(options) {
|
|
29
|
-
const packageId = validatePackageId(options.packageId ?? "
|
|
29
|
+
const packageId = validatePackageId(options.packageId ?? "HttpSdk");
|
|
30
30
|
const rootNamespace = validateRootNamespace(options.rootNamespace ?? packageId);
|
|
31
31
|
const client = validateClientName(options.clientName ?? `${csTypeName(rootNamespace.split(".").at(-1))}Client`);
|
|
32
32
|
const version = validateVersion(options.version ?? "0.1.0");
|