argsbarg 7.1.1 → 7.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +38 -1
- package/README.md +7 -7
- package/docs/README.md +1 -1
- package/docs/cli-program.md +1 -1
- package/docs/configure.md +2 -2
- package/docs/mcp.md +53 -4
- package/docs/output-schema.md +6 -0
- package/examples/full-example/AGENTS.md +1 -1
- package/examples/full-example/bun.lock +83 -1
- package/examples/full-example/justfile +5 -3
- package/examples/full-example-json/AGENTS.md +1 -1
- package/examples/full-example-json/README.md +1 -0
- package/examples/full-example-json/bun.lock +83 -1
- package/examples/full-example-json/docs/cli-schema.json +284 -9
- package/examples/full-example-json/docs/cli.md +236 -18
- package/examples/full-example-json/docs/http.md +1 -0
- package/examples/full-example-json/docs/mcp.md +18 -0
- package/examples/full-example-json/docs/openapi.json +155 -0
- package/examples/full-example-json/justfile +5 -3
- package/examples/full-example-json/src/commands/shape-area/__generated__/ShapeAreaInputSchema.json +59 -0
- package/examples/full-example-json/src/commands/shape-area/__generated__/index.ts +5 -0
- package/examples/full-example-json/src/commands/shape-area/command.test.ts +34 -0
- package/examples/full-example-json/src/commands/shape-area/command.ts +31 -0
- package/examples/full-example-json/src/commands/shape-area/types.ts +28 -0
- package/examples/full-example-json/src/program.ts +2 -1
- package/examples/mcp-plugin/.claude-plugin/plugin.json +7 -1
- package/examples/mcp-plugin/.cursor-plugin/plugin.json +7 -1
- package/examples/mcp-plugin/AGENTS.md +14 -1
- package/examples/mcp-plugin/README.md +19 -10
- package/examples/mcp-plugin/bun.lock +83 -1
- package/examples/mcp-plugin/bunfig.toml +4 -0
- package/examples/mcp-plugin/docs/node-distro.md +97 -0
- package/examples/mcp-plugin/justfile +12 -11
- package/examples/mcp-plugin/package.json +2 -1
- package/examples/mcp-plugin/scripts/release.ts +10 -11
- package/index.d.ts +62 -0
- package/package.json +1 -1
- package/src/cli-tool/create.test.ts +14 -0
- package/src/cli-tool/create.ts +9 -0
- package/src/cli-tool/main.ts +1 -1
- package/src/cli-tool/schemagen/run.ts +41 -2
- package/src/cli-tool/schemagen/schemagen.test.ts +87 -2
- package/src/config/validate.test.ts +157 -0
- package/src/config/validate.ts +353 -26
- package/src/core/document-leaf.test.ts +53 -0
- package/src/core/json-pointer.ts +46 -0
- package/src/core/types.ts +33 -0
- package/src/core/validate.ts +68 -1
- package/src/docs/docs.test.ts +7 -0
- package/src/docs/mcp-guide.ts +43 -1
- package/src/headless/tool-call.test.ts +74 -2
- package/src/headless/tool-call.ts +44 -22
- package/src/http/schema-deref.ts +1 -23
- package/src/index.ts +3 -0
- package/src/mcp/server.ts +28 -4
- package/src/mcp/tools.test.ts +292 -0
- package/src/mcp/tools.ts +144 -6
- package/src/runtime/cli.ts +6 -1
- package/src/server/context.ts +6 -0
- package/src/test/integration/mcp.test.ts +73 -0
- package/src/test/mcp-integration-fixture.ts +1 -0
- package/src/test/mcp-size-fixture.ts +31 -0
- package/examples/mcp-plugin/.mcp.json +0 -6
- package/examples/mcp-plugin/mcp.json +0 -8
- package/examples/mcp-plugin/scripts/mcp.mjs +0 -11106
- package/examples/mcp-plugin/src/commands/render-json/__generated__/RenderJsonInputSchema.json +0 -15
- package/examples/mcp-plugin/src/commands/render-json/__generated__/index.ts +0 -5
- package/examples/mcp-plugin/src/commands/status/__generated__/StatusJsonOutputSchema.json +0 -15
- package/examples/mcp-plugin/src/commands/status/__generated__/index.ts +0 -5
- package/examples/mcp-plugin/src/commands/workspaces/__generated__/WorkspaceNameInputSchema.json +0 -15
- package/examples/mcp-plugin/src/commands/workspaces/__generated__/index.ts +0 -5
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [7.1.3] - 2026-09-29
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- MCP tools whose `inputSchema` or `outputSchema` root is not `type: "object"` (e.g. a discriminated-union `anyOf` from `export type Input = A | B`) are now wrapped for MCP as `{ input: <schema> }` / `{ result: <schema> }`, with `definitions` moved to the new root. MCP requires an object root, and the TypeScript SDK rejects anything else; previously these tools shipped schemas clients refused or showed no fields for. `tools/call` unwraps `input` before invoke (handlers and `inputSchema` validation still see the exact union) and wraps `structuredContent` under `result` to match. CLI and HTTP are unchanged. See `docs/mcp.md`.
|
|
15
|
+
- Startup validation (MCP enabled only): every exposed MCP tool's served schemas must have resolvable local `$ref`s, and wrapped schemas must not use `$ref: "#"`.
|
|
16
|
+
- `full-example-json` gains a `shape-area` union-input leaf demonstrating the MCP wrap.
|
|
17
|
+
- `argsbarg create` drops template lines marked `# argsbarg-dev-only` from new projects. The in-repo examples use it for the `just setup` step that repairs `node_modules/.bin/argsbarg` for `file:../..` installs (now in all three templates); scaffolded projects never see it.
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- Docs now use `bun x` instead of `bunx`, and `create` examples use `bun x argsbarg@latest create` so scaffolding never runs a stale cached argsbarg (old templates, old `^` version in `package.json`). `create --check` examples keep `bun x argsbarg` so they check against the project's installed version.
|
|
22
|
+
- The MCP plugin example now defaults to source-only Bun startup with inline Claude and Cursor MCP configuration, updated plugin recipes, unit/integration/agent-E2E guidance, and an optional Node distribution guide.
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- schemagen now hoists a root `$ref` (from `export type Input = Inner`, generic aliases like `Box<string>`, or alias chains) to the object definition it names. Previously these roots had no `type: "object"` or `properties`, so MCP rejected the tool schema, `--help` showed no input rows, and Json-option/`properties` checks were skipped.
|
|
27
|
+
- schemagen no longer adds `additionalProperties: false` to non-object roots. On a union root it rejected every property, so union-typed inputs never validated.
|
|
28
|
+
- JSON Pointer `$ref` resolution (discriminated-union error reporting, OpenAPI dereferencing) now decodes percent-escaped segments such as `#/definitions/Box%3Cstring%3E`.
|
|
29
|
+
- The `full-example` and `full-example-json` justfiles derive `tap_parent`/`tap_path` from a literal `tap := "org/repo"` instead of raw `{tapOrg}`/`{tapRepo}` placeholders, which only `create` filled in. Run in-repo, the Homebrew recipes targeted `Taps/{tapOrg}/homebrew-{tapRepo}`, and `create --check` reported drift. A new test runs `create --check` on every in-repo template as part of `just test`.
|
|
30
|
+
- The MCP plugin example's release `--dry-run` now prints the planned actions without running checks, changing files, or publishing.
|
|
31
|
+
|
|
32
|
+
## [7.1.2] - 2026-09-25
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
|
|
36
|
+
- `mcpServer.instructions` — an optional string returned as `initialize.result.instructions`. Claude Code adds it to the system prompt of every session; Cursor writes it to `mcps/<server>/INSTRUCTIONS.md`.
|
|
37
|
+
- MCP protocol version negotiation: `initialize` now echoes a client's `2025-06-18` or `2024-11-05` `protocolVersion`, and answers `2025-06-18` (the newest) when the request omits it or asks for an unsupported version. Previously the server always claimed `2024-11-05` regardless of what the client sent or what fields it actually returned. `tools/list`'s `outputSchema` and `tools/call`'s `structuredContent` — both defined starting in `2025-06-18` — are now only sent for sessions that negotiated that version or later; a `2024-11-05` session no longer receives fields from a spec revision it never agreed to.
|
|
38
|
+
- `mcpSizeReport(root)` and `mcpServer.sizeLimits` — measures every MCP tool's `description` length and pretty-printed definition (bytes and lines) against configurable limits approximating two real client behaviors (Claude Code truncates long tool descriptions; Cursor reads each tool's synced definition file in bounded chunks), and returns warnings for anything over. `serveMcp` runs this at startup and writes warnings to stderr before the "MCP ready" line; `docs mcp` now includes a `## Tool sizes` table. Set any limit to `false` to disable that check.
|
|
39
|
+
- `mcpTool.notes` (`string | false`) — overrides a leaf's `notes` in the MCP tool description only; CLI `--help` continues to show the leaf's own `notes` unchanged. Useful for a note that only makes sense with `--help` in front of it, or to keep a tool's definition under a size limit.
|
|
40
|
+
|
|
41
|
+
### Changed
|
|
42
|
+
|
|
43
|
+
- Discriminated `anyOf`/`oneOf` unions (every branch has a `properties` key with a string `const` or all-string `enum`, and the value sets are disjoint) now report only the branch matching the instance's discriminator value, instead of every branch's unrelated errors at once. A missing, non-string, or unmapped discriminator value collapses to one synthetic message naming the valid choices. Non-discriminated unions are unaffected. Along the way, two cfworker `@cfworker/json-schema` quirks are also cleaned up for every validated schema (not just discriminated unions): a spurious `additionalProperties` + `"False boolean schema."` pair it emits even for a property that's genuinely declared in `properties`, and dropping now-redundant wrapper errors (`$ref`, `properties`, `items`, `anyOf`, `oneOf`, …) once a more specific error survives underneath them. Discriminator detection also resolves each branch through `$ref` before inspecting its `properties` — schema generators such as `ts-json-schema-generator` write every `anyOf` branch as a bare `{ $ref }` into `definitions` rather than inlining it, which previously made every branch look property-less and silently fell back to the noisy full-error listing.
|
|
44
|
+
|
|
10
45
|
## [7.1.1] - 2026-09-25
|
|
11
46
|
|
|
12
47
|
### Added
|
|
@@ -1048,7 +1083,9 @@ const cli = { ... } satisfies CliProgram; // or : CliProgram
|
|
|
1048
1083
|
- 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`).
|
|
1049
1084
|
- Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
|
|
1050
1085
|
|
|
1051
|
-
[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.1.
|
|
1086
|
+
[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.1.3...HEAD
|
|
1087
|
+
[7.1.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.1.3
|
|
1088
|
+
[7.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.1.2
|
|
1052
1089
|
[7.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.1.1
|
|
1053
1090
|
[7.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.1.0
|
|
1054
1091
|
[7.0.11]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.11
|
package/README.md
CHANGED
|
@@ -112,10 +112,10 @@ ArgsBarg provides an interactive project generator to scaffold a new repository
|
|
|
112
112
|
|
|
113
113
|
```bash
|
|
114
114
|
# Interactive setup (prompts for naming and git configurations)
|
|
115
|
-
|
|
115
|
+
bun x argsbarg@latest create my-app
|
|
116
116
|
|
|
117
117
|
# Non-interactive / Headless setup
|
|
118
|
-
|
|
118
|
+
bun x argsbarg@latest create my-app \
|
|
119
119
|
--key my-cli --release-repo org/my-cli --yes
|
|
120
120
|
```
|
|
121
121
|
|
|
@@ -136,7 +136,7 @@ Edit `scripts/create-identity.ts` in the new repository to set your description.
|
|
|
136
136
|
| Dev tooling | Biome (`just format` / `just lint`), TypeScript, colocated tests |
|
|
137
137
|
| Agent instructions | `AGENTS.md`, `CLAUDE.md` (`@AGENTS.md`) |
|
|
138
138
|
|
|
139
|
-
*Tip: Verify an existing tree or template setup with `
|
|
139
|
+
*Tip: Verify an existing tree or template setup with `bun x argsbarg create --check .`*
|
|
140
140
|
|
|
141
141
|
### Option B: Manual Installation (For Existing Projects)
|
|
142
142
|
|
|
@@ -301,13 +301,13 @@ Copy a shipped template into a new directory (`cli` default, or `json` for schem
|
|
|
301
301
|
Interactive (TTY) — pick template A/B, then key and release repo:
|
|
302
302
|
|
|
303
303
|
```bash
|
|
304
|
-
|
|
304
|
+
bun x argsbarg@latest create my-cli
|
|
305
305
|
```
|
|
306
306
|
|
|
307
307
|
Non-interactive:
|
|
308
308
|
|
|
309
309
|
```bash
|
|
310
|
-
|
|
310
|
+
bun x argsbarg@latest create my-cli \
|
|
311
311
|
--template cli \
|
|
312
312
|
--key my-cli --release-repo org/my-cli --yes
|
|
313
313
|
```
|
|
@@ -315,7 +315,7 @@ bunx argsbarg create my-cli \
|
|
|
315
315
|
Schema-first (`@sg`, JSON schemas, REST CRUD demo):
|
|
316
316
|
|
|
317
317
|
```bash
|
|
318
|
-
|
|
318
|
+
bun x argsbarg@latest create my-api \
|
|
319
319
|
--template json \
|
|
320
320
|
--key my-api --release-repo org/my-api --yes
|
|
321
321
|
```
|
|
@@ -326,7 +326,7 @@ Edit `scripts/create-identity.ts` in the new repo to set `desc` (used by `progra
|
|
|
326
326
|
|
|
327
327
|
**Git bootstrap:** skipped when the target already has a `.git` directory, or when the target sits inside an existing git work tree (monorepo subfolder). Standalone new directories get an `Initial commit`.
|
|
328
328
|
|
|
329
|
-
Verify an existing tree: `
|
|
329
|
+
Verify an existing tree: `bun x argsbarg create --check .`
|
|
330
330
|
|
|
331
331
|
To refresh agent instructions in an existing consumer: `bun scripts/merge-agents-md.ts .` from an argsbarg checkout (or pass the npm package path to the template).
|
|
332
332
|
|
package/docs/README.md
CHANGED
|
@@ -17,7 +17,7 @@ Start here to pick the right guide.
|
|
|
17
17
|
| **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |
|
|
18
18
|
| **Agent skills** | [ai-skills.md](ai-skills.md) — repository skills (`skills/<app>/SKILL.md`) |
|
|
19
19
|
| **Maintaining the argsbarg repo** | [developing.md](developing.md) — release, consumers, npm `files` |
|
|
20
|
-
| **IDE agents in a consumer app** | `
|
|
20
|
+
| **IDE agents in a consumer app** | `bun x argsbarg@latest create` (includes `AGENTS.md`) or `bun scripts/merge-agents-md.ts .` from argsbarg checkout |
|
|
21
21
|
| **Runnable examples** (shipped in npm) | [examples/](examples/) — see table below |
|
|
22
22
|
|
|
23
23
|
## Examples (agents: read these)
|
package/docs/cli-program.md
CHANGED
|
@@ -582,7 +582,7 @@ Agents do **not** discover package docs automatically. Wire them in after `bun a
|
|
|
582
582
|
bun scripts/merge-agents-md.ts .
|
|
583
583
|
```
|
|
584
584
|
|
|
585
|
-
`
|
|
585
|
+
`bun x argsbarg@latest create` copies `AGENTS.md` and `CLAUDE.md` (`@AGENTS.md`) into new projects automatically.
|
|
586
586
|
|
|
587
587
|
2. **Add app-specific sections below the managed block** (recommended). The framework baseline lives between `<!-- argsbarg:managed -->` and `<!-- /argsbarg:managed -->` at the top of the file. All application-specific sections (`## Tooling`, `## Documentation`, `## App conventions`, custom rules) live below the closing marker where they take precedence over framework defaults. Example:
|
|
588
588
|
|
package/docs/configure.md
CHANGED
|
@@ -177,8 +177,8 @@ Do **not** use `post_install` or `def uninstall` for agent artifacts — Homebre
|
|
|
177
177
|
## Bootstrapping a new CLI
|
|
178
178
|
|
|
179
179
|
```bash
|
|
180
|
-
|
|
181
|
-
|
|
180
|
+
bun x argsbarg@latest create my-cli --key my-cli --class-name MyCli --tap org/repo --yes
|
|
181
|
+
bun x argsbarg create --check .
|
|
182
182
|
```
|
|
183
183
|
|
|
184
184
|
See [distribution-homebrew.md](distribution-homebrew.md) and [../examples/full-example/README.md](../examples/full-example/README.md).
|
package/docs/mcp.md
CHANGED
|
@@ -96,9 +96,11 @@ Set `mcpServer` on the **program root only** (the `CliProgram` passed to `new Cl
|
|
|
96
96
|
| Field | Default | Purpose |
|
|
97
97
|
| --- | --- | --- |
|
|
98
98
|
| `enabled` | *(required)* | Must be `true` when `mcpServer` is set |
|
|
99
|
+
| `instructions` | *(none)* | Returned as `initialize.result.instructions` for every negotiated protocol version. Claude Code adds it to the system prompt of every session; Cursor writes it to `mcps/<server>/INSTRUCTIONS.md`. Both cases cost context whether or not the agent ends up using this server, so keep it to a one- or two-line pointer (when to reach for this tool, and to read the accompanying skill first), not usage docs. Must be non-empty when set. |
|
|
99
100
|
| `schemaResourceUri` | `<sanitized root key>://schema` | URI for the built-in schema resource |
|
|
100
101
|
| `shellEnv` | on (opt-out with `false`) | Capture login-shell `env` at startup (`true` uses `$SHELL`, or pass a shell path) |
|
|
101
102
|
| `resources` | `[]` | Custom `CliMcpResource` entries (additive; schema resource is always included) |
|
|
103
|
+
| `sizeLimits` | see [Tool sizes](#tool-sizes) | Overrides the default startup size warnings for tool descriptions, definitions, and `instructions` |
|
|
102
104
|
|
|
103
105
|
MCP `serverInfo.name` and the default schema URI use the sanitized program `key` (non-alphanumeric characters become `_`). Program `version` comes from `CliProgram.version` (also used by the `version` built-in).
|
|
104
106
|
|
|
@@ -158,12 +160,14 @@ Omitted or `enabled: true` exposes the command (default). `mcpTool` is only vali
|
|
|
158
160
|
mcpTool: {
|
|
159
161
|
enabled: true,
|
|
160
162
|
description: "Custom tools/list text (overrides auto-generated path + help).",
|
|
163
|
+
notes: false, // omit this leaf's `notes` from the MCP description; a string replaces them
|
|
161
164
|
}
|
|
162
165
|
```
|
|
163
166
|
|
|
164
167
|
Set **`outputSchema` on the leaf** (not under `mcpTool`) — see [cli-program.md — Structured stdout](cli-program.md#structured-stdout).
|
|
165
168
|
|
|
166
169
|
- **`description`** — when set, replaces the auto-generated `path — help` description entirely.
|
|
170
|
+
- **`notes`** — overrides the leaf's `notes` in the MCP description only; CLI `--help` always shows the leaf's own `notes` unchanged. `false` omits notes from the MCP description entirely; a string replaces them; omit `notes` to use the leaf's `notes` as given. Useful when a note only makes sense with `--help` in front of it, or to keep a tool's definition under a size limit (see [Tool sizes](#tool-sizes)).
|
|
167
171
|
|
|
168
172
|
### Tool arguments
|
|
169
173
|
|
|
@@ -188,18 +192,63 @@ This maps to argv: `stat owner lookup --json --user-name alice /path/to/file`.
|
|
|
188
192
|
|
|
189
193
|
Tool arguments use **long option names** only (`user-name`, not `-u`). Short aliases from your schema are not accepted in MCP tool calls.
|
|
190
194
|
|
|
195
|
+
#### Object-rooted schemas and wrapping
|
|
196
|
+
|
|
197
|
+
MCP requires `type: "object"` at the root of every tool `inputSchema` and `outputSchema`. Object-rooted leaf schemas (every schemagen `interface`, every synthesized options/positionals schema) are served as-is. Any other root — typically a discriminated union (`anyOf`/`oneOf`) from `export type Input = A | B` — is **wrapped** under a single required property, and `$schema`, `$id`, `definitions`, and `$defs` move up to the new root so `#/definitions/…` references still resolve:
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"type": "object",
|
|
202
|
+
"properties": { "input": { "anyOf": [{ "$ref": "#/definitions/Circle" }, { "$ref": "#/definitions/Rect" }] } },
|
|
203
|
+
"required": ["input"],
|
|
204
|
+
"additionalProperties": false,
|
|
205
|
+
"definitions": { "Circle": { "…": "…" }, "Rect": { "…": "…" } }
|
|
206
|
+
}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
- **Arguments** — clients send `{ "input": { "kind": "circle", "radius": 1 } }`. argsbarg unwraps `input` before invoke, so handlers, `ctx.inputs`, and `inputSchema` validation see the bare object (the exact union, unchanged). Extra top-level keys or a non-object `input` fail with a validation error.
|
|
210
|
+
- **Results** — a wrapped `outputSchema` nests under `result`, and `structuredContent` is wrapped to match (`{ "result": [ … ] }`).
|
|
211
|
+
- **CLI and HTTP are unaffected** — only MCP `tools/list` and `tools/call` see the wrapper.
|
|
212
|
+
|
|
213
|
+
When MCP is enabled, startup validation checks every exposed tool's served schemas: each local `$ref` must resolve, and a wrapped schema must not use `$ref: "#"` (after wrapping it would point at the wrapper — reference a named definition instead). See `examples/full-example-json` `shape-area` for a union-input leaf.
|
|
214
|
+
|
|
191
215
|
### Tool results
|
|
192
216
|
|
|
193
217
|
On success (`isError: false`):
|
|
194
218
|
|
|
195
219
|
- **stdout** — first `content` text block with the handler’s captured stdout (raw, unchanged).
|
|
196
220
|
- **stderr** — when non-empty, a second `content` text block with trimmed stderr (no prefix). The block’s position signals stderr; hosts may label it themselves.
|
|
197
|
-
- **structuredContent** — when trimmed stdout is valid JSON, the parsed value is also returned per the [MCP tools spec](https://modelcontextprotocol.io/specification/draft/server/tools). Objects and arrays from flags like `--json` are the common case. JSON **primitives** (`true`, `42`, `"hello"`) are parsed too — a handler that prints the literal string `true` as human text would get `structuredContent: true`. Prefer objects for machine-readable output.
|
|
221
|
+
- **structuredContent** — when trimmed stdout is valid JSON, the parsed value is also returned per the [MCP tools spec](https://modelcontextprotocol.io/specification/draft/server/tools) — only for `2025-06-18` sessions (see [Protocol](#protocol)); `2024-11-05` sessions get `content` only. Objects and arrays from flags like `--json` are the common case. JSON **primitives** (`true`, `42`, `"hello"`) are parsed too — a handler that prints the literal string `true` as human text would get `structuredContent: true`. Prefer objects for machine-readable output.
|
|
198
222
|
|
|
199
223
|
On failure (parse error, validation error, non-zero exit, thrown error), the **full** error message is returned as text content with `isError: true` (ANSI stripped, newlines preserved). HTTP JSON `{ "error": "…" }` uses the same full text. Do not collapse headless errors to the first line.
|
|
200
224
|
|
|
201
225
|
Help and `docs cli-schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
|
|
202
226
|
|
|
227
|
+
## Tool sizes
|
|
228
|
+
|
|
229
|
+
Some hosts have their own limits on how much of a tool's `description` or full definition they'll read, independent of anything the MCP spec itself defines. `mcpSizeReport(root)` (exported from `argsbarg`) measures every tool's `description` length and pretty-printed `{name, description, inputSchema, outputSchema}` definition (bytes and lines) against configurable limits, and returns human-readable warnings for anything over. `serveMcp` runs this at startup and writes any warnings to stderr (`action: "mcp.size"`) before the "MCP ready" line; `docs mcp` includes a `## Tool sizes` table with a per-tool `ok` / `over: …` status.
|
|
230
|
+
|
|
231
|
+
Default limits — observed client behaviors, not MCP spec requirements, so they may need retuning as those clients change:
|
|
232
|
+
|
|
233
|
+
| Limit | Default | Approximates |
|
|
234
|
+
| --- | --- | --- |
|
|
235
|
+
| `descriptionChars` | `2,048` | Claude Code truncates a tool's `description` past this |
|
|
236
|
+
| `definitionBytes` | `51,200` | Cursor syncs each tool's full definition to a file and reads it in chunks of at most this many bytes |
|
|
237
|
+
| `definitionLines` | `2,000` | Same file, read in chunks of at most this many lines (whichever limit hits first) |
|
|
238
|
+
| `instructionsChars` | `2,048` | No specific client behavior modeled yet; a general "keep it short" budget |
|
|
239
|
+
|
|
240
|
+
Override with `mcpServer.sizeLimits`; set any field to `false` to disable that check entirely:
|
|
241
|
+
|
|
242
|
+
```typescript
|
|
243
|
+
mcpServer: {
|
|
244
|
+
enabled: true,
|
|
245
|
+
sizeLimits: {
|
|
246
|
+
definitionBytes: 100_000, // this app's tools are legitimately large
|
|
247
|
+
instructionsChars: false, // don't warn on instructions length
|
|
248
|
+
},
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
203
252
|
## Schema and custom resources
|
|
204
253
|
|
|
205
254
|
The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nested.ts` → `nested_ts://schema`) exposes your full CLI tree as JSON — the same output as `myapp docs cli-schema`. Override with `schemaResourceUri` if needed.
|
|
@@ -312,16 +361,16 @@ mcpServer: {
|
|
|
312
361
|
|
|
313
362
|
- **Transport:** stdio, newline-delimited JSON (NDJSON).
|
|
314
363
|
- **JSON-RPC:** version `2.0`.
|
|
315
|
-
- **MCP protocol version:** `2024-11-05` (
|
|
364
|
+
- **MCP protocol version negotiation:** the server supports `2025-06-18` and `2024-11-05`. `initialize` echoes `params.protocolVersion` when it's one of those; otherwise (unsupported, or omitted) it answers `2025-06-18`, the newest. The negotiated version is fixed for the lifetime of the stdio session (one `initialize` per connection) and gates `outputSchema` (`tools/list`) and `structuredContent` (`tools/call`): both are present only for `2025-06-18` sessions, since those fields are defined starting there. `2025-03-26` is not supported (it mandates JSON-RPC batching, which this server doesn't implement).
|
|
316
365
|
|
|
317
366
|
### Supported methods
|
|
318
367
|
|
|
319
368
|
| Method | Description |
|
|
320
369
|
| --- | --- |
|
|
321
|
-
| `initialize` |
|
|
370
|
+
| `initialize` | Negotiates protocol version, returns capabilities (`tools`, `resources`), `serverInfo`, and optional `instructions`. |
|
|
322
371
|
| `notifications/initialized` | Acknowledged; no response (notification). |
|
|
323
372
|
| `ping` | Returns `{}`. |
|
|
324
|
-
| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`, and
|
|
373
|
+
| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`, and `outputSchema` (`2025-06-18` sessions only). |
|
|
325
374
|
| `tools/call` | Runs a leaf handler; params: `name`, `arguments` (object). |
|
|
326
375
|
| `resources/list` | Lists schema + custom resources. |
|
|
327
376
|
| `resources/read` | Returns resource body; params: `uri`. |
|
package/docs/output-schema.md
CHANGED
|
@@ -92,6 +92,12 @@ export interface StatusJsonOutput {
|
|
|
92
92
|
}
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
+
Root shapes:
|
|
96
|
+
|
|
97
|
+
- **`interface`** or object type literal → object root (`type: "object"`, `additionalProperties: false`).
|
|
98
|
+
- **Alias of a named type** (`export type Input = Inner`, `= Box<string>`, or an alias chain) → schemagen hoists the root `$ref` so the generated root is the object definition itself; `definitions` are kept so recursive references still resolve.
|
|
99
|
+
- **Union** (`export type Input = A | B`) → `anyOf` root; no root `additionalProperties` (it would reject every property). As an MCP `inputSchema`/`outputSchema` it is wrapped as `{ input }` / `{ result }` — see [mcp.md — Object-rooted schemas and wrapping](mcp.md#object-rooted-schemas-and-wrapping).
|
|
100
|
+
|
|
95
101
|
Handlers import types from the same module; leaves import schemas from `./__generated__`:
|
|
96
102
|
|
|
97
103
|
```typescript
|
|
@@ -33,16 +33,98 @@
|
|
|
33
33
|
|
|
34
34
|
"@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.1", "", { "os": "win32", "cpu": "x64" }, "sha512-6uxpR9hvaglANkZemeSiN/FhYgkGasrEGn267eXIWvjrjJ2LhDlk251IhjVJq6MXzkV2/bcXwLwSroLyPtqRZg=="],
|
|
35
35
|
|
|
36
|
+
"@cfworker/json-schema": ["@cfworker/json-schema@4.1.1", "", {}, "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og=="],
|
|
37
|
+
|
|
36
38
|
"@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
|
|
37
39
|
|
|
40
|
+
"@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
|
|
41
|
+
|
|
38
42
|
"@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
|
|
39
43
|
|
|
40
|
-
"
|
|
44
|
+
"ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
|
|
45
|
+
|
|
46
|
+
"ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
|
|
47
|
+
|
|
48
|
+
"argsbarg": ["argsbarg@file:../..", { "dependencies": { "@cfworker/json-schema": "^4", "ts-json-schema-generator": "^2.3.0" }, "devDependencies": { "@biomejs/biome": "^2.5.5", "@types/bun": "^1.3.12", "dts-bundle-generator": "^9.5.1", "typescript": "^5.9.3" }, "bin": { "argsbarg": "bin/argsbarg" } }],
|
|
49
|
+
|
|
50
|
+
"balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
|
|
51
|
+
|
|
52
|
+
"brace-expansion": ["brace-expansion@5.0.12", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ=="],
|
|
41
53
|
|
|
42
54
|
"bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
|
|
43
55
|
|
|
56
|
+
"cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
|
|
57
|
+
|
|
58
|
+
"color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
|
|
59
|
+
|
|
60
|
+
"color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
|
|
61
|
+
|
|
62
|
+
"commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
|
|
63
|
+
|
|
64
|
+
"dts-bundle-generator": ["dts-bundle-generator@9.5.1", "", { "dependencies": { "typescript": ">=5.0.2", "yargs": "^17.6.0" }, "bin": { "dts-bundle-generator": "dist/bin/dts-bundle-generator.js" } }, "sha512-DxpJOb2FNnEyOzMkG11sxO2dmxPjthoVWxfKqWYJ/bI/rT1rvTMktF5EKjAYrRZu6Z6t3NhOUZ0sZ5ZXevOfbA=="],
|
|
65
|
+
|
|
66
|
+
"emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
|
|
67
|
+
|
|
68
|
+
"escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
|
|
69
|
+
|
|
70
|
+
"get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
|
|
71
|
+
|
|
72
|
+
"glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
|
|
73
|
+
|
|
74
|
+
"is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
|
|
75
|
+
|
|
76
|
+
"json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
|
|
77
|
+
|
|
78
|
+
"lru-cache": ["lru-cache@11.5.3", "", {}, "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg=="],
|
|
79
|
+
|
|
80
|
+
"minimatch": ["minimatch@10.2.6", "", { "dependencies": { "brace-expansion": "^5.0.8" } }, "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A=="],
|
|
81
|
+
|
|
82
|
+
"minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
|
|
83
|
+
|
|
84
|
+
"normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
|
|
85
|
+
|
|
86
|
+
"path-scurry": ["path-scurry@2.0.2", "", { "dependencies": { "lru-cache": "^11.0.0", "minipass": "^7.1.2" } }, "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg=="],
|
|
87
|
+
|
|
88
|
+
"require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
|
|
89
|
+
|
|
90
|
+
"safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
|
|
91
|
+
|
|
92
|
+
"string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
|
|
93
|
+
|
|
94
|
+
"strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
|
|
95
|
+
|
|
96
|
+
"ts-json-schema-generator": ["ts-json-schema-generator@2.9.0", "", { "dependencies": { "@types/json-schema": "^7.0.15", "commander": "^14.0.3", "glob": "^13.0.6", "json5": "^2.2.3", "normalize-path": "^3.0.0", "safe-stable-stringify": "^2.5.0", "tslib": "^2.8.1", "typescript": "^5.9.3" }, "bin": { "ts-json-schema-generator": "bin/ts-json-schema-generator.js" } }, "sha512-NR5ZE108uiPtBHBJNGnhwoUaUx5vWTDJzDFG9YlRoqxPU76n+5FClRh92dcGgysbe1smRmYalM9Saj97GW1J4Q=="],
|
|
97
|
+
|
|
98
|
+
"tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
|
|
99
|
+
|
|
44
100
|
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
|
|
45
101
|
|
|
46
102
|
"undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
|
|
103
|
+
|
|
104
|
+
"wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
|
|
105
|
+
|
|
106
|
+
"y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
|
|
107
|
+
|
|
108
|
+
"yargs": ["yargs@17.7.3", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g=="],
|
|
109
|
+
|
|
110
|
+
"yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
|
|
111
|
+
|
|
112
|
+
"argsbarg/@biomejs/biome": ["@biomejs/biome@2.5.14", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.14", "@biomejs/cli-darwin-x64": "2.5.14", "@biomejs/cli-linux-arm64": "2.5.14", "@biomejs/cli-linux-arm64-musl": "2.5.14", "@biomejs/cli-linux-x64": "2.5.14", "@biomejs/cli-linux-x64-musl": "2.5.14", "@biomejs/cli-win32-arm64": "2.5.14", "@biomejs/cli-win32-x64": "2.5.14" }, "bin": { "biome": "bin/biome" } }, "sha512-0FabLIjd4M/dm8VFI86RMaLLdgepzbdfiAL2R8cr7V81OYYrP1w7Z73KfAwPK5h9SrEBXTzNG2y+mBwPo9xRnw=="],
|
|
113
|
+
|
|
114
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.14", "", { "os": "darwin", "cpu": "arm64" }, "sha512-UnzaXO65L4tsZimFITFP2M121GyhDcWFrT3pL5ZJ5U4XcS/0L5VHYytVohdCf/gnDUFHgl2I9xnt5bV/J1kxHQ=="],
|
|
115
|
+
|
|
116
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.14", "", { "os": "darwin", "cpu": "x64" }, "sha512-kiy8qA16K93J7uvFfWi4LgjqDpnRKyePAna6A0Y4jxyUga35SYpIZ2cNWlhy0lsfgqRenCpfymnJWEZ6mgpRgA=="],
|
|
117
|
+
|
|
118
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.14", "", { "os": "linux", "cpu": "arm64" }, "sha512-vO/9BaU1n30CiFNLx49gMTMtbCAAqlo/EqFoG0BU3deQInTbJrmXSmTQ9e3FoDZIKQnvSLDVNL4lx1ci7y1T1Q=="],
|
|
119
|
+
|
|
120
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.14", "", { "os": "linux", "cpu": "arm64" }, "sha512-SJ9PrZkBnnH9dHJDnxk34vKs0GB2dbsioaft6/hPhWJ7AHpwYH83Isnhj0FSRpFkGgpVfJ1lds23ApB2czUDLQ=="],
|
|
121
|
+
|
|
122
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.14", "", { "os": "linux", "cpu": "x64" }, "sha512-VHZRa7CCQBUWKxNwUvHJeuW03WFRgN5NWO//SDGOitc9QIeNyfA42V9zlKm+x82xFSG9Bzi5fi+hbhm9anO8yA=="],
|
|
123
|
+
|
|
124
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.14", "", { "os": "linux", "cpu": "x64" }, "sha512-2kI5PrMgW5dcEZYrstLPmUmCwkUwZY39rP4BN93Vxbwcs2O57LDQOktUZZYPvvspN5i0mhGr3TJtF5sU26NUWg=="],
|
|
125
|
+
|
|
126
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.14", "", { "os": "win32", "cpu": "arm64" }, "sha512-pHgAFffmZtaYoxavEsWEYNvcA7NwOIjLyqw2HXyLbt16xYryX0L4fMV2u0G9ag6LNYPIoqWaWqzUcnc6rLGGXg=="],
|
|
127
|
+
|
|
128
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.14", "", { "os": "win32", "cpu": "x64" }, "sha512-oJWmBhoHsnhUKIke+0gXDX0mltJrWHA1UyHsrTlXwX0TL64ilVZAo+TYZm97baecV0esBdpzy3k96q+09JaZUQ=="],
|
|
47
129
|
}
|
|
48
130
|
}
|
|
@@ -4,8 +4,10 @@ set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
|
|
|
4
4
|
export PATH := justfile_directory() + "/node_modules/.bin:" + env_var("PATH")
|
|
5
5
|
|
|
6
6
|
brew_prefix := `brew --prefix`
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
# Homebrew tap (org/repo); `argsbarg create` rewrites this literal to the new project's tap
|
|
8
|
+
tap := "bdombro/bun-argsbarg"
|
|
9
|
+
tap_parent := brew_prefix + "/Library/Taps/" + replace_regex(tap, "/.*", "")
|
|
10
|
+
tap_path := tap_parent + "/homebrew-" + replace_regex(tap, ".*/", "")
|
|
9
11
|
|
|
10
12
|
# List available recipes (default)
|
|
11
13
|
_:
|
|
@@ -101,7 +103,7 @@ schemagen:
|
|
|
101
103
|
# Install bun/npm dependencies
|
|
102
104
|
setup:
|
|
103
105
|
bun install
|
|
104
|
-
test -f node_modules/argsbarg/bin/argsbarg && ln -sf ../argsbarg/bin/argsbarg node_modules/.bin/argsbarg
|
|
106
|
+
test -f node_modules/argsbarg/bin/argsbarg && ln -sf ../argsbarg/bin/argsbarg node_modules/.bin/argsbarg # argsbarg-dev-only: fix link for file:../.. installs
|
|
105
107
|
|
|
106
108
|
# Run unit tests (after check)
|
|
107
109
|
test: check
|
|
@@ -18,6 +18,7 @@ full-example-json configure install
|
|
|
18
18
|
|
|
19
19
|
- `full-example-json echo` — Echo text back to stdout or inspect flags.
|
|
20
20
|
- `full-example-json render-json` — Process structured JSON payloads with schema validation.
|
|
21
|
+
- `full-example-json shape-area` — Discriminated-union JSON input (MCP clients see it wrapped as `{ input }`).
|
|
21
22
|
- `full-example-json status` — Show application version with schemagen output schema (`--json`).
|
|
22
23
|
- `full-example-json workspaces` — Manage workspace resources (REST CRUD with in-memory SQLite).
|
|
23
24
|
|
|
@@ -33,16 +33,98 @@
|
|
|
33
33
|
|
|
34
34
|
"@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.1", "", { "os": "win32", "cpu": "x64" }, "sha512-6uxpR9hvaglANkZemeSiN/FhYgkGasrEGn267eXIWvjrjJ2LhDlk251IhjVJq6MXzkV2/bcXwLwSroLyPtqRZg=="],
|
|
35
35
|
|
|
36
|
+
"@cfworker/json-schema": ["@cfworker/json-schema@4.1.1", "", {}, "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og=="],
|
|
37
|
+
|
|
36
38
|
"@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
|
|
37
39
|
|
|
40
|
+
"@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
|
|
41
|
+
|
|
38
42
|
"@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
|
|
39
43
|
|
|
40
|
-
"
|
|
44
|
+
"ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
|
|
45
|
+
|
|
46
|
+
"ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
|
|
47
|
+
|
|
48
|
+
"argsbarg": ["argsbarg@file:../..", { "dependencies": { "@cfworker/json-schema": "^4", "ts-json-schema-generator": "^2.3.0" }, "devDependencies": { "@biomejs/biome": "^2.5.5", "@types/bun": "^1.3.12", "dts-bundle-generator": "^9.5.1", "typescript": "^5.9.3" }, "bin": { "argsbarg": "bin/argsbarg" } }],
|
|
49
|
+
|
|
50
|
+
"balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
|
|
51
|
+
|
|
52
|
+
"brace-expansion": ["brace-expansion@5.0.12", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ=="],
|
|
41
53
|
|
|
42
54
|
"bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
|
|
43
55
|
|
|
56
|
+
"cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
|
|
57
|
+
|
|
58
|
+
"color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
|
|
59
|
+
|
|
60
|
+
"color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
|
|
61
|
+
|
|
62
|
+
"commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
|
|
63
|
+
|
|
64
|
+
"dts-bundle-generator": ["dts-bundle-generator@9.5.1", "", { "dependencies": { "typescript": ">=5.0.2", "yargs": "^17.6.0" }, "bin": { "dts-bundle-generator": "dist/bin/dts-bundle-generator.js" } }, "sha512-DxpJOb2FNnEyOzMkG11sxO2dmxPjthoVWxfKqWYJ/bI/rT1rvTMktF5EKjAYrRZu6Z6t3NhOUZ0sZ5ZXevOfbA=="],
|
|
65
|
+
|
|
66
|
+
"emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
|
|
67
|
+
|
|
68
|
+
"escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
|
|
69
|
+
|
|
70
|
+
"get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
|
|
71
|
+
|
|
72
|
+
"glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
|
|
73
|
+
|
|
74
|
+
"is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
|
|
75
|
+
|
|
76
|
+
"json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
|
|
77
|
+
|
|
78
|
+
"lru-cache": ["lru-cache@11.5.3", "", {}, "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg=="],
|
|
79
|
+
|
|
80
|
+
"minimatch": ["minimatch@10.2.6", "", { "dependencies": { "brace-expansion": "^5.0.8" } }, "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A=="],
|
|
81
|
+
|
|
82
|
+
"minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
|
|
83
|
+
|
|
84
|
+
"normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
|
|
85
|
+
|
|
86
|
+
"path-scurry": ["path-scurry@2.0.2", "", { "dependencies": { "lru-cache": "^11.0.0", "minipass": "^7.1.2" } }, "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg=="],
|
|
87
|
+
|
|
88
|
+
"require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
|
|
89
|
+
|
|
90
|
+
"safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
|
|
91
|
+
|
|
92
|
+
"string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
|
|
93
|
+
|
|
94
|
+
"strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
|
|
95
|
+
|
|
96
|
+
"ts-json-schema-generator": ["ts-json-schema-generator@2.9.0", "", { "dependencies": { "@types/json-schema": "^7.0.15", "commander": "^14.0.3", "glob": "^13.0.6", "json5": "^2.2.3", "normalize-path": "^3.0.0", "safe-stable-stringify": "^2.5.0", "tslib": "^2.8.1", "typescript": "^5.9.3" }, "bin": { "ts-json-schema-generator": "bin/ts-json-schema-generator.js" } }, "sha512-NR5ZE108uiPtBHBJNGnhwoUaUx5vWTDJzDFG9YlRoqxPU76n+5FClRh92dcGgysbe1smRmYalM9Saj97GW1J4Q=="],
|
|
97
|
+
|
|
98
|
+
"tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
|
|
99
|
+
|
|
44
100
|
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
|
|
45
101
|
|
|
46
102
|
"undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
|
|
103
|
+
|
|
104
|
+
"wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
|
|
105
|
+
|
|
106
|
+
"y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
|
|
107
|
+
|
|
108
|
+
"yargs": ["yargs@17.7.3", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g=="],
|
|
109
|
+
|
|
110
|
+
"yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
|
|
111
|
+
|
|
112
|
+
"argsbarg/@biomejs/biome": ["@biomejs/biome@2.5.14", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.14", "@biomejs/cli-darwin-x64": "2.5.14", "@biomejs/cli-linux-arm64": "2.5.14", "@biomejs/cli-linux-arm64-musl": "2.5.14", "@biomejs/cli-linux-x64": "2.5.14", "@biomejs/cli-linux-x64-musl": "2.5.14", "@biomejs/cli-win32-arm64": "2.5.14", "@biomejs/cli-win32-x64": "2.5.14" }, "bin": { "biome": "bin/biome" } }, "sha512-0FabLIjd4M/dm8VFI86RMaLLdgepzbdfiAL2R8cr7V81OYYrP1w7Z73KfAwPK5h9SrEBXTzNG2y+mBwPo9xRnw=="],
|
|
113
|
+
|
|
114
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.14", "", { "os": "darwin", "cpu": "arm64" }, "sha512-UnzaXO65L4tsZimFITFP2M121GyhDcWFrT3pL5ZJ5U4XcS/0L5VHYytVohdCf/gnDUFHgl2I9xnt5bV/J1kxHQ=="],
|
|
115
|
+
|
|
116
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.14", "", { "os": "darwin", "cpu": "x64" }, "sha512-kiy8qA16K93J7uvFfWi4LgjqDpnRKyePAna6A0Y4jxyUga35SYpIZ2cNWlhy0lsfgqRenCpfymnJWEZ6mgpRgA=="],
|
|
117
|
+
|
|
118
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.14", "", { "os": "linux", "cpu": "arm64" }, "sha512-vO/9BaU1n30CiFNLx49gMTMtbCAAqlo/EqFoG0BU3deQInTbJrmXSmTQ9e3FoDZIKQnvSLDVNL4lx1ci7y1T1Q=="],
|
|
119
|
+
|
|
120
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.14", "", { "os": "linux", "cpu": "arm64" }, "sha512-SJ9PrZkBnnH9dHJDnxk34vKs0GB2dbsioaft6/hPhWJ7AHpwYH83Isnhj0FSRpFkGgpVfJ1lds23ApB2czUDLQ=="],
|
|
121
|
+
|
|
122
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.14", "", { "os": "linux", "cpu": "x64" }, "sha512-VHZRa7CCQBUWKxNwUvHJeuW03WFRgN5NWO//SDGOitc9QIeNyfA42V9zlKm+x82xFSG9Bzi5fi+hbhm9anO8yA=="],
|
|
123
|
+
|
|
124
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.14", "", { "os": "linux", "cpu": "x64" }, "sha512-2kI5PrMgW5dcEZYrstLPmUmCwkUwZY39rP4BN93Vxbwcs2O57LDQOktUZZYPvvspN5i0mhGr3TJtF5sU26NUWg=="],
|
|
125
|
+
|
|
126
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.14", "", { "os": "win32", "cpu": "arm64" }, "sha512-pHgAFffmZtaYoxavEsWEYNvcA7NwOIjLyqw2HXyLbt16xYryX0L4fMV2u0G9ag6LNYPIoqWaWqzUcnc6rLGGXg=="],
|
|
127
|
+
|
|
128
|
+
"argsbarg/@biomejs/biome/@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.14", "", { "os": "win32", "cpu": "x64" }, "sha512-oJWmBhoHsnhUKIke+0gXDX0mltJrWHA1UyHsrTlXwX0TL64ilVZAo+TYZm97baecV0esBdpzy3k96q+09JaZUQ=="],
|
|
47
129
|
}
|
|
48
130
|
}
|