argsbarg 6.1.2 → 6.1.3

package/examples/full-example/docs/http.md

@@ -1,14 +1,14 @@
 # HTTP API (full-example)
 
-full-example exposes the same callable tools over HTTP as MCP.
+full-example exposes user commands over HTTP REST routes derived from the CLI tree.
 
 ## Running
 
 ```bash
-full-example api
+full-example http
 ```
 
-Listens on **http://127.0.0.1:3000** by default (`apiServer.host` / `apiServer.port`).
+Listens on **http://127.0.0.1:3000** by default (`httpServer.host` / `httpServer.port`).
 
 Bind is localhost-only in v0 — use a reverse proxy for remote access.
 
@@ -16,59 +16,58 @@ Bind is localhost-only in v0 — use a reverse proxy for remote access.
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/health` | Liveness check |
-| `GET` | `/openapi.json` | OpenAPI 3.1 document (tool paths and request shapes) |
+| `GET` | `/health` or `/health/live` | Liveness check |
+| `GET` | `/health/ready` | Readiness (config + `program.readiness`) |
+| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
 | `GET` | `/openapi-browser` | Interactive Scalar API reference |
-| `POST` | `/tools/:name` | Invoke with flat JSON args object in the body |
+| `*` | `/api/...` | Invoke user commands (method per route) |
 | `OPTIONS` | `*` | CORS preflight |
 
-Replace `{tool-key}` below with a path segment from `openapi.json` (`paths` keys are `/tools/{tool-key}`). Match body keys to that tool's `requestBody` schema in the spec.
+Discover paths from `openapi.json` (`/api/...`). Query binds options; POST/PUT/PATCH body binds options and `inputSchema` fields.
 
 ## Examples
 
 ```bash
 curl -s http://127.0.0.1:3000/health
+curl -s http://127.0.0.1:3000/health/ready
 curl -s http://127.0.0.1:3000/openapi.json
-curl -s -X POST http://127.0.0.1:3000/tools/{tool-key} \
+curl -s http://127.0.0.1:3000/api/workspaces
+curl -s -X POST http://127.0.0.1:3000/api/workspaces \
   -H "content-type: application/json" \
-  -d '{...}'
+  -d '{"name":"qa2"}'
 ```
 
 ## Responses
 
-Success (`200`): raw response body (JSON object, string, or binary). No `{ ok, stdout }` envelope.
+Success: status from handler → `http.successStatus` → method default (GET 200, POST 201, DELETE 204).
 
 Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.
 
 Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.
 
-## Configuration
+## REST routes
 
-Configure before first use: `full-example configure`.
+- `POST /api/echo` (CLI: `full-example echo`) — Echo a message (MCP-friendly leaf).
+- `POST /api/render-json` (CLI: `full-example render-json`) — Echo a JSON message (schema-first JSON leaf demo).
+- `POST /api/status` (CLI: `full-example status`) — Show app version. (flags: --json)
+- `GET /api/workspaces` (CLI: `full-example workspaces get`) — List workspaces.
+- `POST /api/workspaces` (CLI: `full-example workspaces post`) — Create a workspace.
+- `GET /api/workspaces/{id}` (CLI: `full-example workspaces :id get`) — Get one workspace.
+- `PUT /api/workspaces/{id}` (CLI: `full-example workspaces :id put`) — Replace a workspace.
+- `PATCH /api/workspaces/{id}` (CLI: `full-example workspaces :id patch`) — Patch a workspace name.
+- `DELETE /api/workspaces/{id}` (CLI: `full-example workspaces :id delete`) — Delete a workspace.
 
-Default config file: `~/.local/lib/full_example/config.json`.
+## Request bodies
 
-- **apiToken** (`apiToken`, required → env `FULL_EXAMPLE_API_TOKEN`) — Create at https://example.com/settings/tokens
-- **defaultRegion** (`defaultRegion`, optional) — AWS region for API calls.
-- **maxRetries** (`maxRetries`, optional) — HTTP retry count (0–10).
-- **prefs** (`prefs`, optional) — Local cache preferences (not exported to env).
+POST/PUT/PATCH bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).
 
-## Exposed tools
-
-- `echo` (MCP: `echo`, CLI: `full-example echo`) — echo — Echo a message (MCP-friendly leaf).
-- `status` (MCP: `status`, CLI: `full-example status`) — status — Show resolved config and app version. (flags: --json)
-
-## Tool arguments
-
-POST bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).
-
-For HTTP clients, use **`GET /openapi.json`** (or **`GET /openapi-browser`**) for per-tool request shapes — each `POST /tools/{name}` path has a `requestBody` schema.
+For HTTP clients, use **`GET /openapi.json`** (or **`GET /openapi-browser`**) for per-route request shapes.
 
 Varargs positionals accept a JSON array of strings (not a comma-separated string).
 Options with `format: comma-list` accept a comma-separated string or JSON array.
 Options with a schema `default` are applied when omitted.
 
-Shell invocation reference: `full-example docs api`. Full CLI tree JSON: `full-example docs cli-schema`.
+Shell invocation reference: `full-example docs cli`. Full CLI tree JSON: `full-example docs cli-schema`.
 
 ## OpenAPI
 
@@ -78,4 +77,4 @@ The HTTP API is described in OpenAPI 3.1.
 - **Fetch** — `curl -s http://127.0.0.1:3000/openapi.json`
 - **Save offline** — `full-example docs openapi --save` → `./docs/openapi.json` (or `just docgen` in app repos)
 
-Use the spec to discover tool names (`paths`) and request/response shapes before calling `POST /tools/:name`.
+Use the spec to discover REST paths and request/response shapes before calling `/api/...`.

package/examples/full-example/docs/mcp.md

@@ -109,27 +109,6 @@ full-example mcp
 
 - **`shellEnv`** — on by default; captures login-shell environment at MCP startup (PATH, toolchain shims, exports). Opt out with `shellEnv: false`.
 
-## Configuration
-
-Configure before first use in Cursor or Claude Desktop (MCP hosts are non-interactive): `full-example configure`.
-
-Default config file: `~/.local/lib/full_example/config.json` (flat JSON keys).
-
-- **apiToken** (`apiToken`, required → env `FULL_EXAMPLE_API_TOKEN`) — Create at https://example.com/settings/tokens
-- **defaultRegion** (`defaultRegion`, optional) — AWS region for API calls.
-- **maxRetries** (`maxRetries`, optional) — HTTP retry count (0–10).
-- **prefs** (`prefs`, optional) — Local cache preferences (not exported to env).
-
-Example:
-
-```typescript
-config: {
-  schema: {
-    apiToken: { description: "…", env: "API_TOKEN", sensitive: true },
-  },
-},
-```
-
 ## What agents get
 
 | Mechanism | Purpose |
@@ -142,7 +121,14 @@ config: {
 ## Exposed tools
 
 - `full-example echo` — echo — Echo a message (MCP-friendly leaf).
-- `full-example status` — status — Show resolved config and app version. (flags: --json)
+- `full-example render-json` — render-json — Echo a JSON message (schema-first JSON leaf demo).
+- `full-example status` — status — Show app version. (flags: --json)
+- `full-example workspaces get` — workspaces get — List workspaces.
+- `full-example workspaces post` — workspaces post — Create a workspace.
+- `full-example workspaces :id get` — workspaces :id get — Get one workspace.
+- `full-example workspaces :id put` — workspaces :id put — Replace a workspace.
+- `full-example workspaces :id patch` — workspaces :id patch — Patch a workspace name.
+- `full-example workspaces :id delete` — workspaces :id delete — Delete a workspace.
 
 ## Tool arguments