stitchkit 0.113.1 → 0.113.2

package/llms-full.txt

@@ -10289,13 +10289,42 @@ command name — validated against the declared schema, and kept out of every
 operation's arguments: `handoff_read` above receives `{ handoffId: 'u' }` and
 nothing else. The values reach `resolveAuth(globals)`, `context(auth, globals)`
 and a native command's `globals`. An invalid value is an argument error naming
-the flag; a name that collides with a framework option, or with a field of any
-command, is refused at startup rather than shadowing it silently. Past a bare
+the flag. An application global that collides with a framework option is refused
+at startup. Field collisions in authored commands are configuration errors;
+runtime catalogue entries are isolated as described below. Past a bare
 `--` every token is a literal, so a positional value that reads like a global
 survives intact.
 
 Both help levels list them under `Application options:`.
 
+## When one runtime command cannot be represented in argv
+
+A `runtimeTools` catalogue can change independently of the CLI application. An
+entry whose input declares a framework option such as `json`, or a field shadowed
+by an application global such as `caller`, cannot receive that field through argv.
+Only that entry becomes unavailable. Other commands still run, and top-level,
+filtered and command-specific help retain the entry and its full reason:
+
+```text
+  inspect  Inspect an operation [unavailable]
+    Unavailable: [stitchkit] CLI command "inspect" declares field(s) shadowed by application global options: caller
+```
+
+Calling it returns `CLI_COMMAND_UNAVAILABLE`, `retryable: false`, and the same
+reason in `details.message` on stderr; the default exit code is 1. `--json`
+compacts the error as usual; `exitCodes` and `errorHint` apply. The refusal precedes
+command argument parsing, stdin, context, hooks and the handler; `--dry-run` cannot
+turn it into success. A known unavailable `--wait` target returns the same refusal;
+an unknown target keeps `NOT_FOUND`.
+
+This isolates only reserved/global **field** conflicts in `runtimeTools`.
+Native commands and contract-defined `services` still fail at startup for those
+conflicts. Duplicate or reserved command names and invalid local aliases,
+positionals or passthrough policies remain configuration errors for every entry.
+`createCliInvoker` receives globals and command input separately and has no argv
+projection, so its own `caller` or `json` input stays callable without renaming.
+See [ADR 0273](../decisions/0273-a-runtime-cli-field-conflict-is-one-commands-unavailability.md).
+
 ## When the managed surface cannot resolve
 
 A CLI whose commands come from a running server declares them with a factory,
@@ -13068,7 +13097,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
@@ -23593,7 +23622,7 @@ SDK nor the `ai` peer.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `createCli` | function | build and run a CLI from contracts; a runtime catalogue field conflicting with reserved/global argv options disables only that entry, retained in help with its reason; invocation returns `CLI_COMMAND_UNAVAILABLE` before side effects — [guide](../guide/cli.md#when-one-runtime-command-cannot-be-represented-in-argv) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
 | `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |

package/llms.txt

@@ -18,7 +18,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.9 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 45.3 KB → [llms/cli.2.txt](llms/cli.2.txt) 22.3 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 47.0 KB → [llms/cli.2.txt](llms/cli.2.txt) 22.5 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.113.1",
+  "version": "0.113.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",