argsbarg 6.1.1 → 6.1.3

package/docs/api-server.md

@@ -1,141 +0,0 @@
-# HTTP API server
-
-ArgsBarg can expose your CLI as an HTTP tool server. Each **leaf command** becomes a callable tool — the same exposure model as MCP. The server uses Bun's built-in HTTP stack and binds to **localhost by default**.
-
-The HTTP API is **opt-in**. Apps that do not set `apiServer` on the program root behave exactly as before.
-
-## Quick start
-
-1. Add `apiServer` to your program root:
-
-```typescript
-import pkg from "../package.json" with { type: "json" };
-
-const cli = {
-  key: "myapp",
-  version: pkg.version,
-  description: "My app.",
-  apiServer: { enabled: true },
-  commands: [/* ... */],
-} satisfies CliProgram;
-```
-
-`apiServer: { enabled: true }` opts in. Omit `apiServer` entirely to disable HTTP. Empty `apiServer: {}` is rejected at validation.
-
-2. Run the HTTP server:
-
-```bash
-myapp api
-```
-
-The process listens until interrupted. Startup prints the listen URL to stderr.
-
-## Configuration
-
-Set `apiServer` on the **program root only**. Validation rejects `apiServer` on nested nodes.
-
-| Field | Default | Purpose |
-| --- | --- | --- |
-| `enabled` | *(required)* | Must be `true` when `apiServer` is set |
-| `host` | `127.0.0.1` | Listen address |
-| `port` | `3000` | Listen port |
-
-`apiServer` and `mcpServer` are independent — enable either or both.
-
-## Tool names
-
-HTTP and MCP use different tool identifiers for the same leaf command:
-
-| CLI path | HTTP API (`POST /tools/:name`) | MCP (`tools/call`) |
-| --- | --- | --- |
-| `stat owner lookup` | `stat-owner-lookup` | `stat_owner_lookup` |
-| `render-invoice` | `render-invoice` | `render_invoice` |
-
-OpenAPI `paths` use the API id (`/tools/render-invoice`, etc.).
-
-## Endpoints
-
-| Method | Path | Purpose |
-| --- | --- | --- |
-| `GET` | `/health` | Liveness check |
-| `GET` | `/openapi.json` | OpenAPI 3.1 document (per-tool `POST /tools/{name}` paths) |
-| `GET` | `/openapi-browser` | Interactive Scalar API reference (CDN) |
-| `POST` | `/tools/:name` | Invoke tool; body is a flat JSON args object |
-| `OPTIONS` | `*` | CORS preflight (wide-open `Access-Control-Allow-Origin: *`) |
-
-## Examples
-
-```bash
-curl -s http://127.0.0.1:3000/health
-curl -s http://127.0.0.1:3000/openapi.json
-open http://127.0.0.1:3000/openapi-browser
-curl -s -X POST http://127.0.0.1:3000/tools/{tool-key} \
-  -H 'content-type: application/json' \
-  -d '{...}'
-```
-
-Replace `{tool-key}` with a path segment from `openapi.json` (`paths` keys are `/tools/{tool-key}`); body keys match that tool's flat JSON args (see `docs cli-schema` or `openapi.json`).
-
-## Handler responses (`ctx.respond()`)
-
-API and MCP tool handlers must return machine-readable output via **`ctx.respond()`** or by **returning a value** (implicit JSON). `console.log` is not included in HTTP/MCP success payloads.
-
-```typescript
-handler: (ctx) => {
-  if (ctx.hasFlag("json")) {
-    return { user: "alice", path: "/tmp" };
-  }
-  ctx.respond({
-    body: pdfBytes,
-    contentType: "application/pdf",
-    headers: { "Content-Disposition": 'inline; filename="invoice.pdf"' },
-  });
-},
-```
-
-**CLI mode:** `ctx.respond()` prints to stdout (JSON pretty-printed, strings as-is, `Uint8Array` as raw bytes). Handlers may still use `console.log` for human-only CLI output.
-
-### Leaf metadata
-
-```typescript
-apiResponse?: {
-  contentType?: string;           // default application/json
-  contentDisposition?: string;    // e.g. attachment; filename="invoice.pdf"
-};
-```
-
-Used by OpenAPI and as a default `Content-Type` when the handler does not set one.
-
-## Responses
-
-**Success (`200`):** raw body — no `{ ok, stdout }` envelope.
-
-| Body type | HTTP `Content-Type` |
-| --- | --- |
-| object / array | `application/json` |
-| string | handler `contentType` or `text/plain` |
-| `Uint8Array` | e.g. `application/pdf` (required on `respond()`) |
-
-**Errors:** JSON `{ "error": "...", "exitCode?": number }` with `400` (bad args), `404` (unknown tool), `503` (missing config), or `500` (handler failure).
-
-## MCP binary payloads
-
-Binary `ctx.respond()` bodies are encoded in MCP `structuredContent` as:
-
-```json
-{ "data": "<base64>", "contentType": "application/pdf", "encoding": "base64" }
-```
-
-String bodies use `{ "content": "...", "contentType": "..." }`. JSON objects are returned as-is in `structuredContent`.
-
-## CORS
-
-All responses include wide-open CORS headers (`Access-Control-Allow-Origin: *`). Not configurable in v1.
-
-## OpenAPI
-
-Call `generateOpenApi(program)` or `openApiJson(program)` from the package, fetch `GET /openapi.json` from a running server, or run `myapp docs openapi` / `myapp docs openapi --save` (writes `./docs/openapi.json` when `docs.enabled` and `apiServer.enabled`). Nested `inputSchema` / `outputSchema` `$ref` pointers are dereferenced when the OpenAPI document is built so API reference UIs can show nested request shapes.
-
-## Complex tool inputs
-
-For nested request bodies (e.g. invoice template data), set `inputSchema` on the leaf, declare a matching `kind: Json` option (optionally `pipable: true` for CLI stdin), and read inputs with `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — piped stdin is loaded before the handler runs.

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

@@ -1,511 +0,0 @@
-<!-- Generated by full-example docs api --save; do not edit. -->
-
-# full-example — CLI API reference
-
-Argsbarg full example reference app
-
-Machine-readable export: `full-example docs cli-schema`
-
-## `full-example`
-
-Argsbarg full example reference app
-
-#### Subcommands
-
-- `echo` — Echo a message (MCP-friendly leaf).
-- `status` — Show resolved config and app version.
-
-### `full-example echo`
-
-Echo a message (MCP-friendly leaf).
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--message` | string | required | — | Text to print. |
-
-#### Subcommands
-
-- `version` — Print the program version.
-- `configure` — Set up agent skills, MCP config, and app config for this app (binary via Homebrew).
-- `docs` — Print bundled CLI documentation.
-- `mcp` — MCP server and bundle tools.
-- `api` — HTTP API server for tools.
-
-#### `full-example echo version`
-
-Print the program version.
-
-#### `full-example echo configure`
-
-Set up agent skills, MCP config, and app config for this app (binary via Homebrew).
-
-> Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
-> 
-> Homebrew post_install runs:
->   full-example configure --sync --yes
-> 
-> Interactive setup (per target):
->   full-example configure
-> 
-> Upgrade:
->   brew upgrade full-example
-> 
-> Shell completions are installed by Homebrew during brew install.
-> See: https://docs.brew.sh/Shell-Completion
-> 
-> See what is installed:
->   full-example configure --status
-> 
-> Uninstall:
->   brew uninstall <tap>/full-example
-> 
-> The formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).
-> 
-> Remove app config only:
->   full-example configure --remove-config --yes
-> 
-> Use --dry to preview changes without writing files.
-> Use --json for machine-readable output.
-
-**Default subcommand:** `run` (`missingOnly`)
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills, MCP, and config. Used by Homebrew post_install. |
-| `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
-| `--remove-config` | flag | optional | — | Remove the app config file only. |
-| `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
-| `--dry` | flag | optional | — | Show what would change without writing files. |
-| `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
-
-#### Subcommands
-
-- `get` — Print resolved configuration value(s).
-- `set` — Write one configuration key to the config file.
-
-##### `full-example echo configure get`
-
-Print resolved configuration value(s).
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--json` | flag | optional | — | Emit JSON (compact). |
-| `--pretty` | flag | optional | — | Pretty-print JSON (requires --json). |
-
-##### `full-example echo configure set`
-
-Write one configuration key to the config file.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--json` | flag | optional | — | Emit JSON (compact). |
-| `--from-env` | flag | optional | — | Bind this key to its mapped environment variable (no literal value stored). |
-
-#### `full-example echo docs`
-
-Print bundled CLI documentation.
-
-> Topics print to stdout. Add --save to write files under ./docs/.
-
-**Default subcommand:** `readme` (`missingOnly`)
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-#### Subcommands
-
-- `readme` — Print README (user guide).
-- `mcp` — Print MCP server setup and tool guidance.
-- `http` — Print HTTP API setup and tool guidance.
-- `openapi` — Print the HTTP OpenAPI 3.1 document as JSON.
-- `cli-schema` — Print the full CLI command tree as JSON.
-- `api` — Print the full command reference as markdown.
-- `skill` — Print a reference agent SKILL; run `configure` to install an optimized copy.
-
-##### `full-example echo docs readme`
-
-Print README (user guide).
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example echo docs mcp`
-
-Print MCP server setup and tool guidance.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example echo docs http`
-
-Print HTTP API setup and tool guidance.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example echo docs openapi`
-
-Print the HTTP OpenAPI 3.1 document as JSON.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example echo docs cli-schema`
-
-Print the full CLI command tree as JSON.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example echo docs api`
-
-Print the full command reference as markdown.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example echo docs skill`
-
-Print a reference agent SKILL; run `configure` to install an optimized copy.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-#### `full-example echo mcp`
-
-MCP server and bundle tools.
-
-> Stdio MCP server. Add to Cursor, Claude Code, or Claude Desktop:
-> 
->   command: full-example
->   args: mcp
-> 
-> Or:
-> 
->   full-example configure
-> 
-> Full setup guide: full-example docs mcp
-
-**Default subcommand:** `serve` (`missingOnly`)
-
-#### Subcommands
-
-- `bundle` — Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>.
-
-##### `full-example echo mcp bundle`
-
-Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>.
-
-#### `full-example echo api`
-
-HTTP API server for tools.
-
-> HTTP tool server on http://127.0.0.1:3000.
-> 
-> Endpoints: GET /health, GET /openapi.json, GET /openapi-browser, POST /tools/:name
-> 
-> Configure app settings:
-> 
->   full-example configure
-> 
-> Full setup guide: full-example docs http
-
-**Default subcommand:** `serve` (`missingOnly`)
-
-### `full-example status`
-
-Show resolved config and app version.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--json` | flag | optional | — | Emit JSON. |
-
-#### Output
-
-JSON Schema for output when/if handler emits JSON
-
-```json
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "defaultRegion": {
-      "type": "string",
-      "description": "Resolved AWS region."
-    },
-    "maxRetries": {
-      "type": "number",
-      "description": "Resolved retry count."
-    },
-    "apiTokenSet": {
-      "type": "boolean",
-      "description": "Whether apiToken is set (value never included)."
-    },
-    "version": {
-      "type": "string",
-      "description": "App version from program root."
-    }
-  },
-  "required": [
-    "apiTokenSet",
-    "version"
-  ],
-  "description": "JSON payload for `full-example status --json`.",
-  "definitions": {}
-}
-```
-
-#### Subcommands
-
-- `version` — Print the program version.
-- `configure` — Set up agent skills, MCP config, and app config for this app (binary via Homebrew).
-- `docs` — Print bundled CLI documentation.
-- `mcp` — MCP server and bundle tools.
-- `api` — HTTP API server for tools.
-
-#### `full-example status version`
-
-Print the program version.
-
-#### `full-example status configure`
-
-Set up agent skills, MCP config, and app config for this app (binary via Homebrew).
-
-> Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
-> 
-> Homebrew post_install runs:
->   full-example configure --sync --yes
-> 
-> Interactive setup (per target):
->   full-example configure
-> 
-> Upgrade:
->   brew upgrade full-example
-> 
-> Shell completions are installed by Homebrew during brew install.
-> See: https://docs.brew.sh/Shell-Completion
-> 
-> See what is installed:
->   full-example configure --status
-> 
-> Uninstall:
->   brew uninstall <tap>/full-example
-> 
-> The formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).
-> 
-> Remove app config only:
->   full-example configure --remove-config --yes
-> 
-> Use --dry to preview changes without writing files.
-> Use --json for machine-readable output.
-
-**Default subcommand:** `run` (`missingOnly`)
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills, MCP, and config. Used by Homebrew post_install. |
-| `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
-| `--remove-config` | flag | optional | — | Remove the app config file only. |
-| `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
-| `--dry` | flag | optional | — | Show what would change without writing files. |
-| `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
-
-#### Subcommands
-
-- `get` — Print resolved configuration value(s).
-- `set` — Write one configuration key to the config file.
-
-##### `full-example status configure get`
-
-Print resolved configuration value(s).
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--json` | flag | optional | — | Emit JSON (compact). |
-| `--pretty` | flag | optional | — | Pretty-print JSON (requires --json). |
-
-##### `full-example status configure set`
-
-Write one configuration key to the config file.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--json` | flag | optional | — | Emit JSON (compact). |
-| `--from-env` | flag | optional | — | Bind this key to its mapped environment variable (no literal value stored). |
-
-#### `full-example status docs`
-
-Print bundled CLI documentation.
-
-> Topics print to stdout. Add --save to write files under ./docs/.
-
-**Default subcommand:** `readme` (`missingOnly`)
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-#### Subcommands
-
-- `readme` — Print README (user guide).
-- `mcp` — Print MCP server setup and tool guidance.
-- `http` — Print HTTP API setup and tool guidance.
-- `openapi` — Print the HTTP OpenAPI 3.1 document as JSON.
-- `cli-schema` — Print the full CLI command tree as JSON.
-- `api` — Print the full command reference as markdown.
-- `skill` — Print a reference agent SKILL; run `configure` to install an optimized copy.
-
-##### `full-example status docs readme`
-
-Print README (user guide).
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example status docs mcp`
-
-Print MCP server setup and tool guidance.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example status docs http`
-
-Print HTTP API setup and tool guidance.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example status docs openapi`
-
-Print the HTTP OpenAPI 3.1 document as JSON.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example status docs cli-schema`
-
-Print the full CLI command tree as JSON.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example status docs api`
-
-Print the full command reference as markdown.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-##### `full-example status docs skill`
-
-Print a reference agent SKILL; run `configure` to install an optimized copy.
-
-#### Options
-
-| Option | Type | Required | Format / default | Description |
-| --- | --- | --- | --- | --- |
-| `--save` | flag | optional | — | Write documentation to ./docs/. |
-
-#### `full-example status mcp`
-
-MCP server and bundle tools.
-
-> Stdio MCP server. Add to Cursor, Claude Code, or Claude Desktop:
-> 
->   command: full-example
->   args: mcp
-> 
-> Or:
-> 
->   full-example configure
-> 
-> Full setup guide: full-example docs mcp
-
-**Default subcommand:** `serve` (`missingOnly`)
-
-#### Subcommands
-
-- `bundle` — Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>.
-
-##### `full-example status mcp bundle`
-
-Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>.
-
-#### `full-example status api`
-
-HTTP API server for tools.
-
-> HTTP tool server on http://127.0.0.1:3000.
-> 
-> Endpoints: GET /health, GET /openapi.json, GET /openapi-browser, POST /tools/:name
-> 
-> Configure app settings:
-> 
->   full-example configure
-> 
-> Full setup guide: full-example docs http
-
-**Default subcommand:** `serve` (`missingOnly`)

package/examples/full-example/src/commands/status/__generated__/outputSchema.json

@@ -1,28 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "defaultRegion": {
-      "type": "string",
-      "description": "Resolved AWS region."
-    },
-    "maxRetries": {
-      "type": "number",
-      "description": "Resolved retry count."
-    },
-    "apiTokenSet": {
-      "type": "boolean",
-      "description": "Whether apiToken is set (value never included)."
-    },
-    "version": {
-      "type": "string",
-      "description": "App version from program root."
-    }
-  },
-  "required": [
-    "apiTokenSet",
-    "version"
-  ],
-  "description": "JSON stdout for `full-example status --json`.",
-  "definitions": {}
-}