argsbarg 7.0.8 → 7.0.10

package/CHANGELOG.md

@@ -7,7 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [7.0.8] - 2026-09-15
+## [7.0.10] - 2026-09-16
+
+### Added
+
+- **Canonical wire input schema generation (`buildLeafInputSchema`)** — unified wire input schema generation across MCP tools, OpenAPI request bodies, and CLI schema export into a single canonical helper. Synthesizes a complete JSON Schema (types, formats, enums, required properties, and positionals) from leaf-local options when `inputSchema` is not explicitly defined.
+- **Leaf `inputSchema` in `docs cli-schema`** — `cliSchemaExport` now includes `inputSchema` for every leaf command in the machine-readable command tree (and `<app>://schema` MCP resource), giving programmatic and agent callers a unified JSON Schema input specification for both flag-based and document-based commands.
+- **`buildLeafInputSchema` and `leafWireOptions` exports** — exported from framework root, CLI runtime export, and MCP tools module.
+
+## [7.0.9] - 2026-09-16
+
+### Added
+
+- **`kind: "document"` leaf commands with YAML and JSON support** — introduced `kind: "document"` as the primary naming for structured payload leaves, while retaining `kind: "json"` and `isJsonLeaf` as fully backward-compatible aliases. Both `"document"` and `"json"` leaves now accept YAML input in addition to JSON via command positional arguments and piped stdin.
+- **YAML request body support in HTTP server** — the HTTP API server now accepts YAML request bodies in addition to JSON for structured document endpoints.
+- **`isDocumentLeaf` and `parseDocumentText` exports** — exported `isDocumentLeaf` type guard and `parseDocumentText` utility from framework root and CLI exports.
+
+### Changed
+
+- **Help rendering for document leaves** — usage lines for `kind: "document"` leaves render `[DOCUMENT]` (retaining `[JSON]` for legacy `kind: "json"` leaves) and describe inputs as `"Pass a JSON or YAML document as an argument or pipe to stdin."`
 
 ### Added
 
@@ -992,8 +1010,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - 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`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.8...HEAD
-[7.0.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.8
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.10...HEAD
+[7.0.10]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.10
+[7.0.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.9
 [7.0.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.7
 [7.0.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.6
 [7.0.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.5

package/docs/cli-program.md

@@ -108,7 +108,7 @@ Use root **`notes`** for cross-cutting hints shown in help (install commands, do
 Descriptions and schemas are copied into MCP tools and HTTP OpenAPI — optimize for smaller, clearer agent payloads:
 
 - **Declare options on the leaf command** that uses them — routing groups cannot declare options (program root may). Wire schemas (MCP, OpenAPI) expose leaf-local options only.
-- Prefer **`kind: "json"`** leaves with schemagen `inputSchema` for complex tool bodies (one nested object beats many flat flags).
+- Prefer **`kind: "document"`** (or legacy `kind: "json"`) leaves with schemagen `inputSchema` for complex tool bodies (one nested object beats many flat flags).
 - Keep **`description`** strings short and action-oriented; put examples in **`notes`**, not duplicated in every option.
 - Use **`hidden: true`** or **`mcpTool.enabled: false`** for debug/internal commands.
 - For shape discovery: HTTP agents load **`docs openapi`** or `GET /openapi.json`; MCP agents use **`docs cli-schema`**; load full **`docs cli`** only when prose is needed.
@@ -300,15 +300,15 @@ Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>(
 
 At most one `pipable` Json option per leaf. Json option names must appear in `inputSchema.properties` when a custom `inputSchema` is set.
 
-### Pure JSON leaves (`kind: "json"`)
+### Structured document leaves (`kind: "document"`)
 
-When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the leaf with **`inputSchema`** and **no `options` or `positionals`**:
+When the entire tool body is a structured document (JSON or YAML, no CLI flags), set **`kind: "document"`** (or legacy `"json"`) on the leaf with **`inputSchema`** and **no `options` or `positionals`**:
 
 ```typescript
 {
   key: "render-invoice",
   description: "Render an invoice from template data",
-  kind: "json",
+  kind: "document",
   inputSchema,
   handler: (ctx) => {
     const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
@@ -319,10 +319,25 @@ When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the
 
 | Surface | How input is supplied |
 | --- | --- |
-| CLI | One JSON positional **or** pipe a JSON document to stdin |
-| MCP / HTTP | Full tool args object (`ctx.toolArgs` / POST body) |
+| CLI | One JSON or YAML positional **or** pipe a JSON/YAML document to stdin |
+| MCP / HTTP | Full tool args object (`ctx.toolArgs` / JSON or YAML request body) |
 
-Example CLI: `jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice`
+Example CLI:
+```bash
+# JSON positional or pipe
+jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice
+myapp render-invoice '{"format":"pdf","invoice":{"id":"INV-1"}}'
+
+# YAML positional or pipe
+myapp render-invoice 'format: pdf
+invoice:
+  id: INV-1'
+cat << 'EOF' | myapp render-invoice
+format: pdf
+invoice:
+  id: INV-1
+EOF
+```
 
 See [output-schema.md](output-schema.md) for schemagen `inputType`, [http-server.md](http-server.md) for HTTP tool bodies, and [json-schema-subset.md](json-schema-subset.md) for validation drafts, Zod interop, and keyword notes.
 

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

@@ -13,6 +13,19 @@
           "required": true
         }
       ],
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Text to print."
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "message"
+        ]
+      },
       "commands": [
         {
           "key": "version",
@@ -20,7 +33,7 @@
         },
         {
           "key": "configure",
-          "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
+          "description": "Set up MCP 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 installs the binary and shell completions only. Agent artifacts live under ~/.agents and are not written during brew install.\n\nAfter install or upgrade:\n  full-example configure install\n\nUpgrade:\n  brew upgrade full-example\n  full-example configure install\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  full-example configure uninstall\n  brew uninstall <tap>/full-example\n\nUse `configure status --json` for machine-readable output.",
           "commands": [
             {
@@ -129,17 +142,6 @@
                   "kind": "presence"
                 }
               ]
-            },
-            {
-              "key": "skill",
-              "description": "Print a reference agent SKILL; run `configure install` to install an optimized copy.",
-              "options": [
-                {
-                  "name": "save",
-                  "description": "Write documentation to ./docs/.",
-                  "kind": "presence"
-                }
-              ]
             }
           ]
         },
@@ -247,6 +249,11 @@
           "kind": "presence"
         }
       ],
+      "inputSchema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
       "commands": [
         {
           "key": "version",
@@ -254,7 +261,7 @@
         },
         {
           "key": "configure",
-          "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
+          "description": "Set up MCP 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 installs the binary and shell completions only. Agent artifacts live under ~/.agents and are not written during brew install.\n\nAfter install or upgrade:\n  full-example configure install\n\nUpgrade:\n  brew upgrade full-example\n  full-example configure install\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  full-example configure uninstall\n  brew uninstall <tap>/full-example\n\nUse `configure status --json` for machine-readable output.",
           "commands": [
             {
@@ -363,17 +370,6 @@
                   "kind": "presence"
                 }
               ]
-            },
-            {
-              "key": "skill",
-              "description": "Print a reference agent SKILL; run `configure install` to install an optimized copy.",
-              "options": [
-                {
-                  "name": "save",
-                  "description": "Write documentation to ./docs/.",
-                  "kind": "presence"
-                }
-              ]
             }
           ]
         },

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

@@ -28,7 +28,7 @@ Echo a message (MCP-friendly leaf).
 #### Subcommands
 
 - `version` — Print the program version.
-- `configure` — Set up agent skills and MCP config for this app (binary via Homebrew).
+- `configure` — Set up MCP config for this app (binary via Homebrew).
 - `docs` — Print bundled CLI documentation.
 - `mcp` — MCP server and bundle tools.
 - `http` — HTTP API server for tools.
@@ -39,7 +39,7 @@ Print the program version.
 
 #### `full-example echo configure`
 
-Set up agent skills and MCP config for this app (binary via Homebrew).
+Set up MCP config for this app (binary via Homebrew).
 
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
@@ -114,7 +114,6 @@ Print bundled CLI documentation.
 - `openapi` — Print the HTTP OpenAPI 3.1 document as JSON.
 - `cli-schema` — Print the full CLI command tree as JSON.
 - `cli` — Print the full command reference as markdown.
-- `skill` — Print a reference agent SKILL; run `configure install` to install an optimized copy.
 
 ##### `full-example echo docs readme`
 
@@ -176,16 +175,6 @@ Print the full command reference as markdown.
 | --- | --- | --- | --- | --- |
 | `--save` | flag | optional | — | Write documentation to ./docs/. |
 
-##### `full-example echo docs skill`
-
-Print a reference agent SKILL; run `configure install` 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.
@@ -262,7 +251,7 @@ Show app version.
 #### Subcommands
 
 - `version` — Print the program version.
-- `configure` — Set up agent skills and MCP config for this app (binary via Homebrew).
+- `configure` — Set up MCP config for this app (binary via Homebrew).
 - `docs` — Print bundled CLI documentation.
 - `mcp` — MCP server and bundle tools.
 - `http` — HTTP API server for tools.
@@ -273,7 +262,7 @@ Print the program version.
 
 #### `full-example status configure`
 
-Set up agent skills and MCP config for this app (binary via Homebrew).
+Set up MCP config for this app (binary via Homebrew).
 
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
@@ -348,7 +337,6 @@ Print bundled CLI documentation.
 - `openapi` — Print the HTTP OpenAPI 3.1 document as JSON.
 - `cli-schema` — Print the full CLI command tree as JSON.
 - `cli` — Print the full command reference as markdown.
-- `skill` — Print a reference agent SKILL; run `configure install` to install an optimized copy.
 
 ##### `full-example status docs readme`
 
@@ -410,16 +398,6 @@ Print the full command reference as markdown.
 | --- | --- | --- | --- | --- |
 | `--save` | flag | optional | — | Write documentation to ./docs/. |
 
-##### `full-example status docs skill`
-
-Print a reference agent SKILL; run `configure install` 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.

package/examples/full-example/docs/openapi.json

@@ -344,6 +344,7 @@
                     "description": "Text to print."
                   }
                 },
+                "additionalProperties": false,
                 "required": [
                   "message"
                 ]
@@ -450,7 +451,8 @@
             "application/json; charset=utf-8": {
               "schema": {
                 "type": "object",
-                "properties": {}
+                "properties": {},
+                "additionalProperties": false
               }
             }
           }