argsbarg 6.1.10 → 6.2.0

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

@@ -0,0 +1,92 @@
+<!-- Generated by full-example-json docs http --save; do not edit. -->
+
+# HTTP API (full-example-json)
+
+full-example-json exposes user commands over HTTP REST routes derived from the CLI tree.
+
+## Running
+
+```bash
+full-example-json http
+```
+
+Listens on **http://127.0.0.1:3000** by default (`httpServer.host` / `httpServer.port`).
+
+Bind is localhost-only by default — use a reverse proxy for remote access.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health/liveness` | Liveness — server is online and accepting requests |
+| `GET` | `/health/readiness` | Readiness — online plus config and `program.readiness` checks passed |
+| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
+| `GET` | `/swagger` | Interactive Swagger UI API reference |
+| * | `/*` | Invoke user commands (method per route) |
+| `OPTIONS` | `*` | CORS preflight |
+
+Discover paths from `openapi.json` (`/*`). Query binds options; POST/PUT/PATCH body binds options and `inputSchema` fields.
+
+## Examples
+
+```bash
+curl -s http://127.0.0.1:3000/health/liveness
+curl -s http://127.0.0.1:3000/health/readiness
+curl -s http://127.0.0.1:3000/openapi.json
+curl -s http://127.0.0.1:3000/workspaces
+curl -s -X POST http://127.0.0.1:3000/workspaces \
+  -H "content-type: application/json" \
+  -d '{"name":"qa2"}'
+```
+
+## Responses
+
+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`.
+
+## Logging
+
+Server logs go to **stderr** (one JSON object per line by default).
+
+- Configure with `program.log` on the program root
+- **`enrich`** — add custom JSON fields on top of the default line
+- **`serialize`** — replace the formatter and emit your own line shape
+
+See the argsbarg [logging guide](https://github.com/bdombro/bun-argsbarg/blob/main/docs/logging.md) for examples and the full `LogEnrichContext` shape.
+
+## REST routes
+
+- `POST /echo` (CLI: `full-example-json echo`) — Echo a message (MCP-friendly leaf).
+- `POST /render-json` (CLI: `full-example-json render-json`) — Echo a JSON message (schema-first JSON leaf demo).
+- `POST /status` (CLI: `full-example-json status`) — Show app version. (flags: --json)
+- `GET /workspaces` (CLI: `full-example-json workspaces get`) — List workspaces.
+- `POST /workspaces` (CLI: `full-example-json workspaces post`) — Create a workspace.
+- `GET /workspaces/{id}` (CLI: `full-example-json workspaces :id get`) — Get one workspace.
+- `PUT /workspaces/{id}` (CLI: `full-example-json workspaces :id put`) — Replace a workspace.
+- `PATCH /workspaces/{id}` (CLI: `full-example-json workspaces :id patch`) — Patch a workspace name.
+- `DELETE /workspaces/{id}` (CLI: `full-example-json workspaces :id delete`) — Delete a workspace.
+
+## Request bodies
+
+POST/PUT/PATCH 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 /swagger`**) 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-json docs cli`. Full CLI tree JSON: `full-example-json docs cli-schema`.
+
+## OpenAPI
+
+The HTTP API is described in OpenAPI 3.1.
+
+- **Browse** — [http://127.0.0.1:3000/swagger](http://127.0.0.1:3000/swagger) (Swagger UI; loads `/openapi.json`)
+- **Fetch** — `curl -s http://127.0.0.1:3000/openapi.json`
+- **Save offline** — `full-example-json docs openapi --save` → `./docs/openapi.json` (or `just docgen` in app repos)
+
+Use the spec to discover REST paths and request/response shapes before calling `/*`.

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

@@ -0,0 +1,116 @@
+<!-- Generated by full-example-json docs mcp --save; do not edit. -->
+
+# MCP server (full-example-json)
+
+full-example-json exposes an MCP server with features similar to the CLI.
+
+## Installation
+
+### `.agents` auto-install
+
+When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/).
+
+Install the CLI first so `full-example-json` is on your PATH (e.g. `brew install full-example-json`).
+
+```bash
+full-example-json configure --sync --yes
+```
+
+Writes or updates `~/.agents/mcp.json` with a `mcpServers` entry for this app.
+
+### Manual client setup
+
+Many clients do not read `~/.agents/mcp.json` yet. Copy the `mcpServers` entry from that file, or paste:
+
+```json
+{
+  "mcpServers": {
+    "full_example_json": {
+      "command": "full-example-json",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+| Client | Config file |
+| --- | --- |
+| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |
+| **Claude Code** | `~/.claude.json` under `mcpServers`, or project `.mcp.json` |
+| **Claude Desktop** | See platform paths below |
+
+Restart Cursor or reload MCP after editing. Restart Claude Desktop after config changes.
+
+Claude Desktop config paths:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+On this machine (macOS/Linux): `/Users/briandombrowski/Library/Application Support/Claude/claude_desktop_config.json`
+
+### Manual `mcpServers` entry
+
+Same shape as in `~/.agents/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "full_example_json": {
+      "command": "full-example-json",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+## Running directly
+
+Start the stdio MCP server without editing host config:
+
+```bash
+full-example-json mcp
+```
+
+## Environment
+
+- **`shellEnv`** — on by default; captures login-shell environment at MCP startup (PATH, toolchain shims, exports). Opt out with `shellEnv: false`.
+
+## What agents get
+
+| Mechanism | Purpose |
+|-----------|---------|
+| `tools/list` | Callable tools for exposed leaf commands |
+| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |
+| Schema resource | `full_example_json://schema` — same JSON as `full-example-json docs cli-schema` |
+| Docs topic `readme` | `full_example_json://docs/readme` — same markdown as `full-example-json docs readme` |
+
+## Exposed tools
+
+- `full-example-json echo` — echo — Echo a message (MCP-friendly leaf).
+- `full-example-json render-json` — render-json — Echo a JSON message (schema-first JSON leaf demo).
+- `full-example-json status` — status — Show app version. (flags: --json)
+- `full-example-json workspaces get` — workspaces get — List workspaces.
+- `full-example-json workspaces post` — workspaces post — Create a workspace.
+- `full-example-json workspaces :id get` — workspaces :id get — Get one workspace.
+- `full-example-json workspaces :id put` — workspaces :id put — Replace a workspace.
+- `full-example-json workspaces :id patch` — workspaces :id patch — Patch a workspace name.
+- `full-example-json workspaces :id delete` — workspaces :id delete — Delete a workspace.
+
+## Tool arguments
+
+Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).
+See `full-example-json docs cli-schema` or the schema resource for per-tool 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.
+
+## Protocol
+
+Stdio NDJSON JSON-RPC. Help and `docs cli-schema` are not available through tool calls.
+Run `full-example-json docs` for bundled user documentation.