argsbarg 5.1.16 → 6.0.0

package/examples/full-example/docs/cli-schema.json

@@ -0,0 +1,453 @@
+{
+  "key": "full-example",
+  "description": "Argsbarg full example reference app",
+  "commands": [
+    {
+      "key": "echo",
+      "description": "Echo a message (MCP-friendly leaf).",
+      "options": [
+        {
+          "name": "message",
+          "description": "Text to print.",
+          "kind": "string",
+          "required": true
+        }
+      ],
+      "commands": [
+        {
+          "key": "version",
+          "description": "Print the program version."
+        },
+        {
+          "key": "configure",
+          "description": "Set up agent skills, MCP config, and app config for this app (binary via Homebrew).",
+          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example configure --sync --yes\n\nInteractive setup (per target):\n  full-example configure\n\nUpgrade:\n  brew upgrade full-example\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nRemove app config only:\n  full-example configure --remove-config --yes\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+          "options": [
+            {
+              "name": "sync",
+              "description": "Refresh installed skills, MCP, and config. Used by Homebrew post_install.",
+              "kind": "presence"
+            },
+            {
+              "name": "remove-all",
+              "description": "Remove all detected agent artifacts (skills and MCP).",
+              "kind": "presence"
+            },
+            {
+              "name": "remove-config",
+              "description": "Remove the app config file only.",
+              "kind": "presence"
+            },
+            {
+              "name": "status",
+              "description": "Print what is currently installed (read-only).",
+              "kind": "presence"
+            },
+            {
+              "name": "yes",
+              "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+              "kind": "presence",
+              "shortName": "y"
+            },
+            {
+              "name": "dry",
+              "description": "Show what would change without writing files.",
+              "kind": "presence"
+            },
+            {
+              "name": "json",
+              "description": "Print changed paths or status JSON on stdout.",
+              "kind": "presence"
+            }
+          ],
+          "fallbackCommand": "run",
+          "fallbackMode": "missingOnly",
+          "commands": [
+            {
+              "key": "get",
+              "description": "Print resolved configuration value(s).",
+              "options": [
+                {
+                  "name": "json",
+                  "description": "Emit JSON (compact).",
+                  "kind": "presence"
+                },
+                {
+                  "name": "pretty",
+                  "description": "Pretty-print JSON (requires --json).",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "set",
+              "description": "Write one configuration key to the config file.",
+              "options": [
+                {
+                  "name": "json",
+                  "description": "Emit JSON (compact).",
+                  "kind": "presence"
+                },
+                {
+                  "name": "from-env",
+                  "description": "Bind this key to its mapped environment variable (no literal value stored).",
+                  "kind": "presence"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "key": "docs",
+          "description": "Print bundled CLI documentation.",
+          "notes": "Topics print to stdout. Add --save to write files under ./docs/.",
+          "options": [
+            {
+              "name": "save",
+              "description": "Write documentation to ./docs/.",
+              "kind": "presence"
+            }
+          ],
+          "fallbackCommand": "readme",
+          "fallbackMode": "missingOnly",
+          "commands": [
+            {
+              "key": "readme",
+              "description": "Print README (user guide).",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "mcp",
+              "description": "Print MCP server setup and tool guidance.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "http",
+              "description": "Print HTTP API setup and tool guidance.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "openapi",
+              "description": "Print the HTTP OpenAPI 3.1 document as JSON.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "cli-schema",
+              "description": "Print the full CLI command tree as JSON.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "api",
+              "description": "Print the full command reference as markdown.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "skill",
+              "description": "Print a reference agent SKILL; run `configure` to install an optimized copy.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "key": "mcp",
+          "description": "MCP server and bundle tools.",
+          "notes": "Stdio MCP server. Add to Cursor, Claude Code, or Claude Desktop:\n\n  command: full-example\n  args: mcp\n\nOr:\n\n  full-example configure\n\nFull setup guide: full-example docs mcp",
+          "fallbackCommand": "serve",
+          "fallbackMode": "missingOnly",
+          "commands": [
+            {
+              "key": "bundle",
+              "description": "Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>."
+            }
+          ]
+        },
+        {
+          "key": "api",
+          "description": "HTTP API server for tools.",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /openapi.json, GET /openapi-browser, POST /tools/:name\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "fallbackCommand": "serve",
+          "fallbackMode": "missingOnly"
+        }
+      ]
+    },
+    {
+      "key": "status",
+      "description": "Show resolved config and app version.",
+      "options": [
+        {
+          "name": "json",
+          "description": "Emit JSON.",
+          "kind": "presence"
+        }
+      ],
+      "outputSchema": {
+        "$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": {}
+      },
+      "commands": [
+        {
+          "key": "version",
+          "description": "Print the program version."
+        },
+        {
+          "key": "configure",
+          "description": "Set up agent skills, MCP config, and app config for this app (binary via Homebrew).",
+          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example configure --sync --yes\n\nInteractive setup (per target):\n  full-example configure\n\nUpgrade:\n  brew upgrade full-example\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nRemove app config only:\n  full-example configure --remove-config --yes\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+          "options": [
+            {
+              "name": "sync",
+              "description": "Refresh installed skills, MCP, and config. Used by Homebrew post_install.",
+              "kind": "presence"
+            },
+            {
+              "name": "remove-all",
+              "description": "Remove all detected agent artifacts (skills and MCP).",
+              "kind": "presence"
+            },
+            {
+              "name": "remove-config",
+              "description": "Remove the app config file only.",
+              "kind": "presence"
+            },
+            {
+              "name": "status",
+              "description": "Print what is currently installed (read-only).",
+              "kind": "presence"
+            },
+            {
+              "name": "yes",
+              "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+              "kind": "presence",
+              "shortName": "y"
+            },
+            {
+              "name": "dry",
+              "description": "Show what would change without writing files.",
+              "kind": "presence"
+            },
+            {
+              "name": "json",
+              "description": "Print changed paths or status JSON on stdout.",
+              "kind": "presence"
+            }
+          ],
+          "fallbackCommand": "run",
+          "fallbackMode": "missingOnly",
+          "commands": [
+            {
+              "key": "get",
+              "description": "Print resolved configuration value(s).",
+              "options": [
+                {
+                  "name": "json",
+                  "description": "Emit JSON (compact).",
+                  "kind": "presence"
+                },
+                {
+                  "name": "pretty",
+                  "description": "Pretty-print JSON (requires --json).",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "set",
+              "description": "Write one configuration key to the config file.",
+              "options": [
+                {
+                  "name": "json",
+                  "description": "Emit JSON (compact).",
+                  "kind": "presence"
+                },
+                {
+                  "name": "from-env",
+                  "description": "Bind this key to its mapped environment variable (no literal value stored).",
+                  "kind": "presence"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "key": "docs",
+          "description": "Print bundled CLI documentation.",
+          "notes": "Topics print to stdout. Add --save to write files under ./docs/.",
+          "options": [
+            {
+              "name": "save",
+              "description": "Write documentation to ./docs/.",
+              "kind": "presence"
+            }
+          ],
+          "fallbackCommand": "readme",
+          "fallbackMode": "missingOnly",
+          "commands": [
+            {
+              "key": "readme",
+              "description": "Print README (user guide).",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "mcp",
+              "description": "Print MCP server setup and tool guidance.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "http",
+              "description": "Print HTTP API setup and tool guidance.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "openapi",
+              "description": "Print the HTTP OpenAPI 3.1 document as JSON.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "cli-schema",
+              "description": "Print the full CLI command tree as JSON.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "api",
+              "description": "Print the full command reference as markdown.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            },
+            {
+              "key": "skill",
+              "description": "Print a reference agent SKILL; run `configure` to install an optimized copy.",
+              "options": [
+                {
+                  "name": "save",
+                  "description": "Write documentation to ./docs/.",
+                  "kind": "presence"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "key": "mcp",
+          "description": "MCP server and bundle tools.",
+          "notes": "Stdio MCP server. Add to Cursor, Claude Code, or Claude Desktop:\n\n  command: full-example\n  args: mcp\n\nOr:\n\n  full-example configure\n\nFull setup guide: full-example docs mcp",
+          "fallbackCommand": "serve",
+          "fallbackMode": "missingOnly",
+          "commands": [
+            {
+              "key": "bundle",
+              "description": "Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>."
+            }
+          ]
+        },
+        {
+          "key": "api",
+          "description": "HTTP API server for tools.",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /openapi.json, GET /openapi-browser, POST /tools/:name\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "fallbackCommand": "serve",
+          "fallbackMode": "missingOnly"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,81 @@
+# HTTP API (full-example)
+
+full-example exposes the same callable tools over HTTP as MCP.
+
+## Running
+
+```bash
+full-example api
+```
+
+Listens on **http://127.0.0.1:3000** by default (`apiServer.host` / `apiServer.port`).
+
+Bind is localhost-only in v0 — use a reverse proxy for remote access.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health` | Liveness check |
+| `GET` | `/openapi.json` | OpenAPI 3.1 document (tool paths and request shapes) |
+| `GET` | `/openapi-browser` | Interactive Scalar API reference |
+| `POST` | `/tools/:name` | Invoke with flat JSON args object in the body |
+| `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.
+
+## Examples
+
+```bash
+curl -s http://127.0.0.1:3000/health
+curl -s http://127.0.0.1:3000/openapi.json
+curl -s -X POST http://127.0.0.1:3000/tools/{tool-key} \
+  -H "content-type: application/json" \
+  -d '{...}'
+```
+
+## Responses
+
+Success (`200`): raw response body (JSON object, string, or binary). No `{ ok, stdout }` envelope.
+
+Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.
+
+Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.
+
+## Configuration
+
+Configure before first use: `full-example configure`.
+
+Default config file: `~/.local/lib/full_example/config.json`.
+
+- **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).
+
+## 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.
+
+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`.
+
+## OpenAPI
+
+The HTTP API is described in OpenAPI 3.1.
+
+- **Browse** — [http://127.0.0.1:3000/openapi-browser](http://127.0.0.1:3000/openapi-browser) (Scalar UI; loads `/openapi.json`)
+- **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`.

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

@@ -0,0 +1,159 @@
+<!-- Generated by full-example docs mcp --save; do not edit. -->
+
+# MCP server (full-example)
+
+full-example exposes an MCP server with features similar to the CLI.
+
+## Installation
+
+### `configure`
+
+Install the CLI first so `full-example` is on your PATH (e.g. `brew install full-example`). Host configs reference the app by name.
+
+```bash
+full-example configure --sync --yes
+```
+
+Merges the server entry below into host config when each host is present:
+
+| Host | Config file |
+| --- | --- |
+| Cursor | `~/.cursor/mcp.json` (when `~/.cursor` exists) |
+| Claude Code | `~/.claude.json` |
+| Claude Desktop | `claude_desktop_config.json` (when Claude Desktop app data exists) |
+| OpenCode | `~/.config/opencode/*` (when `~/.config/opencode` exists) |
+| OpenAI Codex | `~/.codex/config.toml` via `codex mcp add` (when `codex` is on PATH) |
+| ChatGPT desktop | `chatgpt_mcp_config.json` (when ChatGPT app data exists) |
+
+Claude Desktop paths by platform:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+ChatGPT desktop JSON (when auto-installed):
+
+- **macOS:** `~/Library/Application Support/ChatGPT/chatgpt_mcp_config.json`
+- **Windows:** `%APPDATA%\OpenAI\ChatGPT\chatgpt_mcp_config.json`
+
+Restart Claude Desktop and ChatGPT desktop after changing their config files.
+
+### Manual fallbacks
+
+**OpenCode** (no `~/.config/opencode` yet):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "full_example": {
+      "type": "local",
+      "command": [
+        "full-example",
+        "mcp"
+      ],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Codex** (`codex` not on PATH):
+
+```toml
+[mcp_servers.full_example]
+command = "full-example"
+args = ["mcp"]
+```
+
+Or after installing Codex CLI: `codex mcp add full_example -- full-example mcp`.
+
+### ChatGPT web (Connectors)
+
+OpenAI's documented path for **ChatGPT web/desktop** is **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL** — not local stdio. ChatGPT does not spawn `full-example mcp` directly.
+
+For local stdio, bridge and tunnel, then register the HTTPS URL in Connectors:
+
+1. Expose `full-example mcp` over HTTP (e.g. `mcp-remote`).
+2. Tunnel if needed (ngrok, Cloudflare Tunnel).
+3. Add the public URL as a custom connector.
+
+Desktop `chatgpt_mcp_config.json` is merged when the ChatGPT app is installed; support varies by build. Use Connectors when local JSON is absent or tools do not appear.
+
+### Manual `mcpServers` entry
+
+For Cursor, Claude, and ChatGPT desktop JSON configs, add under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "full_example": {
+      "command": "full-example",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+## Running directly
+
+Start the stdio MCP server without editing host config:
+
+```bash
+full-example mcp
+```
+
+## Environment
+
+- **`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 |
+|-----------|---------|
+| `tools/list` | Callable tools for exposed leaf commands |
+| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |
+| Schema resource | `full_example://schema` — same JSON as `full-example docs cli-schema` |
+| Docs topic `readme` | `full_example://docs/readme` — same markdown as `full-example docs readme` |
+
+## Exposed tools
+
+- `full-example echo` — echo — Echo a message (MCP-friendly leaf).
+- `full-example status` — status — Show resolved config and app version. (flags: --json)
+
+## Tool arguments
+
+Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).
+See `full-example 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 docs` for bundled user documentation.