argsbarg 6.1.3 → 6.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/CHANGELOG.md +19 -1
  2. package/README.md +1 -1
  3. package/docs/http-server.md +22 -17
  4. package/examples/full-example/docs/cli-schema.json +9 -9
  5. package/examples/full-example/docs/cli.md +9 -9
  6. package/examples/full-example/docs/http.md +20 -20
  7. package/examples/full-example/docs/openapi.json +334 -14
  8. package/examples/servers.ts +2 -2
  9. package/index.d.ts +6 -1
  10. package/package.json +1 -1
  11. package/src/builtins/http.ts +3 -1
  12. package/src/core/types.ts +6 -1
  13. package/src/core/validate.ts +43 -0
  14. package/src/docs/http-guide.ts +15 -11
  15. package/src/http/openapi.ts +113 -5
  16. package/src/http/paths.ts +39 -0
  17. package/src/http/readiness.ts +1 -1
  18. package/src/http/result.ts +6 -6
  19. package/src/http/routes.ts +22 -9
  20. package/src/http/server.ts +8 -12
  21. package/src/test/integration/http.test.ts +165 -28
package/CHANGELOG.md CHANGED
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [6.1.5] - 2026-07-24
11
+
12
+ ### Changed
13
+
14
+ - **`httpServer.pathPrefix`** — configurable URL prefix for user routes (default `""`; routes at server root, e.g. `/workspaces`). Set `"/api"` for prefixed paths.
15
+
16
+ ## [6.1.4] - 2026-07-24
17
+
18
+ ### Changed
19
+
20
+ - **`GET /swagger`** — Swagger UI API reference (replaces `GET /openapi-browser` and Scalar).
21
+ - **`GET /openapi.json`** — documents `/health`, `/health/liveness`, and `/health/readiness` probe endpoints under a **Health** tag.
22
+ - **OpenAPI tags** — user `/api/*` routes are grouped by top-level command key (router `description` becomes the tag description).
23
+ - **Health probe paths** — `GET /health/liveness` and `GET /health/readiness` replace `/health/live` and `/health/ready` (`GET /health` remains a liveness alias).
24
+ - **`httpServer.pathPrefix`** — configurable URL prefix for user routes (default `""`; routes at server root, e.g. `/workspaces`). Set `"/api"` for prefixed paths.
25
+
10
26
  ## [6.1.3] - 2026-07-24
11
27
 
12
28
  ### Added
@@ -833,7 +849,9 @@ const cli = { ... } satisfies CliProgram; // or : CliProgram
833
849
  - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
834
850
  - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
835
851
 
836
- [Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.3...HEAD
852
+ [Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.5...HEAD
853
+ [6.1.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.5
854
+ [6.1.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.4
837
855
  [6.1.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.3
838
856
  [6.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.2
839
857
  [6.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.1
package/README.md CHANGED
@@ -112,7 +112,7 @@ See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom
112
112
 
113
113
  ### HTTP tool server
114
114
 
115
- Opt in on the program root with `httpServer: { enabled: true }`, then run `myapp http` for an HTTP REST server (default `http://127.0.0.1:3000`). Nested CLI paths map to `/api/...` with inferred HTTP verbs. Discover routes via `GET /openapi.json`.
115
+ Opt in on the program root with `httpServer: { enabled: true }`, then run `myapp http` for an HTTP REST server (default `http://127.0.0.1:3000`). Nested CLI paths map to REST routes at the server root by default (e.g. `/workspaces`); set `httpServer.pathPrefix: "/api"` to prefix all user routes. Discover routes via `GET /openapi.json`.
116
116
 
117
117
  See **[docs/http-server.md](docs/http-server.md)** for endpoints, curl examples, and response shapes.
118
118
 
package/docs/http-server.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # HTTP API server
2
2
 
3
- ArgsBarg can expose your CLI as an HTTP REST server. Each **leaf command** becomes a route under `/api/...` — nested command paths, HTTP verbs, and `:param` routers are reflected in the URL. The server uses Bun's built-in HTTP stack and binds to **localhost by default**.
3
+ ArgsBarg can expose your CLI as an HTTP REST server. Each **leaf command** becomes a route — nested command paths, HTTP verbs, and `:param` routers are reflected in the URL. By default routes sit at the server root (e.g. `GET /workspaces`). The server uses Bun's built-in HTTP stack and binds to **localhost by default**.
4
4
 
5
5
  The HTTP API is **opt-in**. Apps that do not set `httpServer` on the program root behave exactly as before.
6
6
 
@@ -41,6 +41,7 @@ Set `httpServer` on the **program root only**. Validation rejects `httpServer` o
41
41
  | `enabled` | *(required)* | Must be `true` when `httpServer` is set |
42
42
  | `host` | `127.0.0.1` | Listen address |
43
43
  | `port` | `3000` | Listen port |
44
+ | `pathPrefix` | `""` | URL prefix for user routes (e.g. `"/api"` → `/api/workspaces`; empty → `/workspaces`) |
44
45
  | `trustProxy` | `false` | Honor `X-Forwarded-For` in hooks and access logs |
45
46
  | `errors.errorSchema` | `{ error: string }` | OpenAPI + default error body shape |
46
47
  | `errors.obscureUnexpected` | `false` | Client sees generic message on 500; ECS logs real stack |
@@ -56,10 +57,14 @@ Routes are derived from the command tree:
56
57
 
57
58
  | CLI path | HTTP | Notes |
58
59
  | --- | --- | --- |
59
- | `workspaces get` | `GET /api/workspaces` | Verb leaf (`get`) omitted from URL |
60
- | `workspaces post` | `POST /api/workspaces` | Default POST success **201** |
61
- | `workspaces :id get` | `GET /api/workspaces/{id}` | `:id` param router |
62
- | `stat owner lookup` | `POST /api/stat/owner/lookup` | Default method POST when key is not a verb |
60
+ | `workspaces get` | `GET /workspaces` | Verb leaf (`get`) omitted from URL |
61
+ | `workspaces post` | `POST /workspaces` | Default POST success **201** |
62
+ | `workspaces :id get` | `GET /workspaces/{id}` | `:id` param router |
63
+ | `stat owner lookup` | `POST /stat/owner/lookup` | Default method POST when key is not a verb |
64
+
65
+ With `httpServer.pathPrefix: "/api"`, the same routes are prefixed (e.g. `GET /api/workspaces`).
66
+
67
+ When `pathPrefix` is empty, top-level command keys must not collide with framework paths (`health`, `swagger`, `openapi.json`, `tools`).
63
68
 
64
69
  Method precedence: `leaf.http.method` → verb key (`get`/`post`/…) → **POST**.
65
70
 
@@ -71,27 +76,27 @@ Per-surface exposure: `http.enabled: false` removes a leaf from the route table;
71
76
 
72
77
  | Method | Path | Purpose |
73
78
  | --- | --- | --- |
74
- | `GET` | `/health` or `/health/live` | Liveness — 200 when server is listening |
75
- | `GET` | `/health/ready` | Readiness — config + optional `program.readiness` |
76
- | `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
77
- | `GET` | `/openapi-browser` | Interactive Scalar API reference (CDN) |
78
- | `*` | `/api/...` | Invoke user commands (method per route) |
79
+ | `GET` | `/health` or `/health/liveness` | Liveness — 200 when server is listening |
80
+ | `GET` | `/health/readiness` | Readiness — config + optional `program.readiness` |
81
+ | `GET` | `/openapi.json` | OpenAPI 3.1 REST paths (includes `/health/*` and user routes) |
82
+ | `GET` | `/swagger` | Interactive Swagger UI API reference (CDN) |
83
+ | `*` | `/{command}/...` | Invoke user commands (method per route; optional `pathPrefix`) |
79
84
  | `OPTIONS` | `*` | CORS preflight (`GET, POST, PUT, PATCH, DELETE`) |
80
85
 
81
- `POST /tools/*` was removed in 7.0 — use `/api/*` only.
86
+ `POST /tools/*` was removed in 7.0.
82
87
 
83
88
  ## Examples
84
89
 
85
90
  ```bash
86
91
  curl -s http://127.0.0.1:3000/health
87
- curl -s http://127.0.0.1:3000/health/ready
92
+ curl -s http://127.0.0.1:3000/health/readiness
88
93
  curl -s http://127.0.0.1:3000/openapi.json
89
- open http://127.0.0.1:3000/openapi-browser
90
- curl -s http://127.0.0.1:3000/api/workspaces
91
- curl -s -X POST http://127.0.0.1:3000/api/workspaces \
94
+ open http://127.0.0.1:3000/swagger
95
+ curl -s http://127.0.0.1:3000/workspaces
96
+ curl -s -X POST http://127.0.0.1:3000/workspaces \
92
97
  -H 'content-type: application/json' \
93
98
  -d '{"name":"qa2"}'
94
- curl -s http://127.0.0.1:3000/api/workspaces/{id}
99
+ curl -s http://127.0.0.1:3000/workspaces/{id}
95
100
  ```
96
101
 
97
102
  Discover paths and request shapes from `openapi.json` or `myapp docs openapi`.
@@ -146,7 +151,7 @@ http?: {
146
151
  | Thrown handler / missing `ctx.respond()` | 500 |
147
152
  | Missing required config | 503 |
148
153
 
149
- Tool invocations are **not** gated on `/health/ready`; readiness is for orchestrators only.
154
+ Tool invocations are **not** gated on `/health/readiness`; readiness is for orchestrators only.
150
155
 
151
156
  ## Hooks and runtime
152
157
 
package/examples/full-example/docs/cli-schema.json CHANGED
@@ -191,7 +191,7 @@
191
191
  {
192
192
  "key": "http",
193
193
  "description": "HTTP API server for tools.",
194
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
194
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
195
195
  "options": [
196
196
  {
197
197
  "name": "host",
@@ -424,7 +424,7 @@
424
424
  {
425
425
  "key": "http",
426
426
  "description": "HTTP API server for tools.",
427
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
427
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
428
428
  "options": [
429
429
  {
430
430
  "name": "host",
@@ -679,7 +679,7 @@
679
679
  {
680
680
  "key": "http",
681
681
  "description": "HTTP API server for tools.",
682
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
682
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
683
683
  "options": [
684
684
  {
685
685
  "name": "host",
@@ -916,7 +916,7 @@
916
916
  {
917
917
  "key": "http",
918
918
  "description": "HTTP API server for tools.",
919
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
919
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
920
920
  "options": [
921
921
  {
922
922
  "name": "host",
@@ -1149,7 +1149,7 @@
1149
1149
  {
1150
1150
  "key": "http",
1151
1151
  "description": "HTTP API server for tools.",
1152
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1152
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1153
1153
  "options": [
1154
1154
  {
1155
1155
  "name": "host",
@@ -1386,7 +1386,7 @@
1386
1386
  {
1387
1387
  "key": "http",
1388
1388
  "description": "HTTP API server for tools.",
1389
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1389
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1390
1390
  "options": [
1391
1391
  {
1392
1392
  "name": "host",
@@ -1619,7 +1619,7 @@
1619
1619
  {
1620
1620
  "key": "http",
1621
1621
  "description": "HTTP API server for tools.",
1622
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1622
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1623
1623
  "options": [
1624
1624
  {
1625
1625
  "name": "host",
@@ -1852,7 +1852,7 @@
1852
1852
  {
1853
1853
  "key": "http",
1854
1854
  "description": "HTTP API server for tools.",
1855
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1855
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
1856
1856
  "options": [
1857
1857
  {
1858
1858
  "name": "host",
@@ -2085,7 +2085,7 @@
2085
2085
  {
2086
2086
  "key": "http",
2087
2087
  "description": "HTTP API server for tools.",
2088
- "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
2088
+ "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n full-example configure\n\nFull setup guide: full-example docs http",
2089
2089
  "options": [
2090
2090
  {
2091
2091
  "name": "host",
package/examples/full-example/docs/cli.md CHANGED
@@ -213,7 +213,7 @@ HTTP API server for tools.
213
213
 
214
214
  > HTTP tool server on http://127.0.0.1:3000.
215
215
  >
216
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
216
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
217
217
  >
218
218
  > Configure app settings:
219
219
  >
@@ -426,7 +426,7 @@ HTTP API server for tools.
426
426
 
427
427
  > HTTP tool server on http://127.0.0.1:3000.
428
428
  >
429
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
429
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
430
430
  >
431
431
  > Configure app settings:
432
432
  >
@@ -667,7 +667,7 @@ HTTP API server for tools.
667
667
 
668
668
  > HTTP tool server on http://127.0.0.1:3000.
669
669
  >
670
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
670
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
671
671
  >
672
672
  > Configure app settings:
673
673
  >
@@ -890,7 +890,7 @@ HTTP API server for tools.
890
890
 
891
891
  > HTTP tool server on http://127.0.0.1:3000.
892
892
  >
893
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
893
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
894
894
  >
895
895
  > Configure app settings:
896
896
  >
@@ -1103,7 +1103,7 @@ HTTP API server for tools.
1103
1103
 
1104
1104
  > HTTP tool server on http://127.0.0.1:3000.
1105
1105
  >
1106
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
1106
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
1107
1107
  >
1108
1108
  > Configure app settings:
1109
1109
  >
@@ -1327,7 +1327,7 @@ HTTP API server for tools.
1327
1327
 
1328
1328
  > HTTP tool server on http://127.0.0.1:3000.
1329
1329
  >
1330
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
1330
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
1331
1331
  >
1332
1332
  > Configure app settings:
1333
1333
  >
@@ -1540,7 +1540,7 @@ HTTP API server for tools.
1540
1540
 
1541
1541
  > HTTP tool server on http://127.0.0.1:3000.
1542
1542
  >
1543
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
1543
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
1544
1544
  >
1545
1545
  > Configure app settings:
1546
1546
  >
@@ -1753,7 +1753,7 @@ HTTP API server for tools.
1753
1753
 
1754
1754
  > HTTP tool server on http://127.0.0.1:3000.
1755
1755
  >
1756
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
1756
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
1757
1757
  >
1758
1758
  > Configure app settings:
1759
1759
  >
@@ -1966,7 +1966,7 @@ HTTP API server for tools.
1966
1966
 
1967
1967
  > HTTP tool server on http://127.0.0.1:3000.
1968
1968
  >
1969
- > Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
1969
+ > Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
1970
1970
  >
1971
1971
  > Configure app settings:
1972
1972
  >
package/examples/full-example/docs/http.md CHANGED
@@ -16,23 +16,23 @@ Bind is localhost-only in v0 — use a reverse proxy for remote access.
16
16
 
17
17
  | Method | Path | Purpose |
18
18
  | --- | --- | --- |
19
- | `GET` | `/health` or `/health/live` | Liveness check |
20
- | `GET` | `/health/ready` | Readiness (config + `program.readiness`) |
19
+ | `GET` | `/health` or `/health/liveness` | Liveness check |
20
+ | `GET` | `/health/readiness` | Readiness (config + `program.readiness`) |
21
21
  | `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
22
- | `GET` | `/openapi-browser` | Interactive Scalar API reference |
23
- | `*` | `/api/...` | Invoke user commands (method per route) |
22
+ | `GET` | `/swagger` | Interactive Swagger UI API reference |
23
+ | * | `/*` | Invoke user commands (method per route) |
24
24
  | `OPTIONS` | `*` | CORS preflight |
25
25
 
26
- Discover paths from `openapi.json` (`/api/...`). Query binds options; POST/PUT/PATCH body binds options and `inputSchema` fields.
26
+ Discover paths from `openapi.json` (`/*`). Query binds options; POST/PUT/PATCH body binds options and `inputSchema` fields.
27
27
 
28
28
  ## Examples
29
29
 
30
30
  ```bash
31
31
  curl -s http://127.0.0.1:3000/health
32
- curl -s http://127.0.0.1:3000/health/ready
32
+ curl -s http://127.0.0.1:3000/health/readiness
33
33
  curl -s http://127.0.0.1:3000/openapi.json
34
- curl -s http://127.0.0.1:3000/api/workspaces
35
- curl -s -X POST http://127.0.0.1:3000/api/workspaces \
34
+ curl -s http://127.0.0.1:3000/workspaces
35
+ curl -s -X POST http://127.0.0.1:3000/workspaces \
36
36
  -H "content-type: application/json" \
37
37
  -d '{"name":"qa2"}'
38
38
  ```
@@ -47,21 +47,21 @@ Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.
47
47
 
48
48
  ## REST routes
49
49
 
50
- - `POST /api/echo` (CLI: `full-example echo`) — Echo a message (MCP-friendly leaf).
51
- - `POST /api/render-json` (CLI: `full-example render-json`) — Echo a JSON message (schema-first JSON leaf demo).
52
- - `POST /api/status` (CLI: `full-example status`) — Show app version. (flags: --json)
53
- - `GET /api/workspaces` (CLI: `full-example workspaces get`) — List workspaces.
54
- - `POST /api/workspaces` (CLI: `full-example workspaces post`) — Create a workspace.
55
- - `GET /api/workspaces/{id}` (CLI: `full-example workspaces :id get`) — Get one workspace.
56
- - `PUT /api/workspaces/{id}` (CLI: `full-example workspaces :id put`) — Replace a workspace.
57
- - `PATCH /api/workspaces/{id}` (CLI: `full-example workspaces :id patch`) — Patch a workspace name.
58
- - `DELETE /api/workspaces/{id}` (CLI: `full-example workspaces :id delete`) — Delete a workspace.
50
+ - `POST /echo` (CLI: `full-example echo`) — Echo a message (MCP-friendly leaf).
51
+ - `POST /render-json` (CLI: `full-example render-json`) — Echo a JSON message (schema-first JSON leaf demo).
52
+ - `POST /status` (CLI: `full-example status`) — Show app version. (flags: --json)
53
+ - `GET /workspaces` (CLI: `full-example workspaces get`) — List workspaces.
54
+ - `POST /workspaces` (CLI: `full-example workspaces post`) — Create a workspace.
55
+ - `GET /workspaces/{id}` (CLI: `full-example workspaces :id get`) — Get one workspace.
56
+ - `PUT /workspaces/{id}` (CLI: `full-example workspaces :id put`) — Replace a workspace.
57
+ - `PATCH /workspaces/{id}` (CLI: `full-example workspaces :id patch`) — Patch a workspace name.
58
+ - `DELETE /workspaces/{id}` (CLI: `full-example workspaces :id delete`) — Delete a workspace.
59
59
 
60
60
  ## Request bodies
61
61
 
62
62
  POST/PUT/PATCH bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).
63
63
 
64
- For HTTP clients, use **`GET /openapi.json`** (or **`GET /openapi-browser`**) for per-route request shapes.
64
+ For HTTP clients, use **`GET /openapi.json`** (or **`GET /swagger`**) for per-route request shapes.
65
65
 
66
66
  Varargs positionals accept a JSON array of strings (not a comma-separated string).
67
67
  Options with `format: comma-list` accept a comma-separated string or JSON array.
@@ -73,8 +73,8 @@ Shell invocation reference: `full-example docs cli`. Full CLI tree JSON: `full-e
73
73
 
74
74
  The HTTP API is described in OpenAPI 3.1.
75
75
 
76
- - **Browse** — [http://127.0.0.1:3000/openapi-browser](http://127.0.0.1:3000/openapi-browser) (Scalar UI; loads `/openapi.json`)
76
+ - **Browse** — [http://127.0.0.1:3000/swagger](http://127.0.0.1:3000/swagger) (Swagger UI; loads `/openapi.json`)
77
77
  - **Fetch** — `curl -s http://127.0.0.1:3000/openapi.json`
78
78
  - **Save offline** — `full-example docs openapi --save` → `./docs/openapi.json` (or `just docgen` in app repos)
79
79
 
80
- Use the spec to discover REST paths and request/response shapes before calling `/api/...`.
80
+ Use the spec to discover REST paths and request/response shapes before calling `/*`.