argsbarg 6.1.1 → 6.1.3

package/docs/config-schema.md

@@ -48,7 +48,7 @@ await cli.run();
 
 **`_bindings`** — reserved top-level metadata: `{ "_bindings": { "apiToken": "env" } }`. Set via wizard (Enter to use env), `configure set --from-env`, or `ctx.appConfig.set` (marks `file`). Optional keys can be bound to `skip`.
 
-**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema. Partial writes (bindings only, single-key updates) skip required-property checks.
+**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema ([supported subset](json-schema-subset.md)). Partial writes (bindings only, single-key updates) skip required-property checks.
 
 See [cli-program.md — Configuration](cli-program.md#configuration-programappconfig) for resolution order, bootstrap timing, and `configure get`/`set`.
 
@@ -142,44 +142,43 @@ Mirror the [output-schema.md](output-schema.md) pattern for config:
 
 ```mermaid
 flowchart LR
-  subgraph types [types.ts]
-    Marker["export type configType = AppConfig"]
+  subgraph src [src/config/types.ts]
+    Marker["/** @sg */ export interface AppConfig"]
   end
   subgraph gen [argsbarg schemagen]
     Script["argsbarg schemagen"]
     Gen["ts-json-schema-generator"]
   end
   subgraph artifacts [Gitignored __generated__]
-    Json["configSchema.json"]
+    Json["AppConfigSchema.json"]
     Index["index.ts"]
   end
   subgraph runtime [Runtime]
     Program["program.appConfig.jsonSchema"]
     Validate["argsbarg runtime subset validator"]
   end
-  types --> Script --> Gen --> Json
+  src --> Script --> Gen --> Json
   Gen --> Index --> Program --> Validate
 ```
 
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled with argsbarg) |
-| Discovery | `export type configType = …` in `src/config/types.ts` |
-| Artifacts | `src/config/__generated__/` — gitignored; run `just schemagen` after clone |
+| Discovery | `/** @sg */` on `AppConfig` in `src/config/types.ts` (or any scanned `src/**/*.ts`) |
+| Artifacts | `src/config/__generated__/AppConfigSchema.json` — gitignored; run `just schemagen` after clone |
 | Consumer CI | Optional: `ajv` + `ajv-formats` against the same committed JSON (not an argsbarg runtime dep) |
 
 Example:
 
 ```typescript
 // src/config/types.ts
+/** @sg */
 export interface AppConfig {
   apiToken: string;
 }
-
-export type configType = AppConfig;
 ```
 
-Wire on the program root: `import { configSchema } from "./config/__generated__/index.ts"`.
+Wire on the program root: `import { AppConfigSchema } from "./config/__generated__"`.
 
 ### Supported AppConfig shapes (argsbarg runtime validator)
 
@@ -222,7 +221,7 @@ Object/array/`$ref` properties require `--json` on `configure set` when comma-se
 
 | Example | Role |
 | --- | --- |
-| [`examples/full-example/`](../examples/full-example/) | **Copy template** — `argsbarg schemagen`, `program.appConfig`, built-in `configure get`/`set` |
+| [`examples/full-example/`](../examples/full-example/) | **Copy template** — `@sg` schemagen, builtins; optional `program.appConfig` |
 
 ```bash
 cd examples/full-example && just setup && just schemagen

package/docs/configure.md

@@ -1,5 +1,7 @@
 # Configure command
 
+> This feature is experimental.
+
 The `configure` built-in manages **agent artifacts** (skills, MCP config, app config). The **binary and shell completions** ship via Homebrew — see [distribution-homebrew.md](distribution-homebrew.md).
 
 Opt out with `configure: { enabled: false }` on the program root.

package/docs/decisions.md

@@ -0,0 +1,40 @@
+# Decisions
+
+This doc tracks big architectural decisions so that we can avoid re-hashing the same decisions over and over.
+
+## HTTP REST vs flat `/tools/:name`
+
+Decision: **nested `/api/...` REST** (7.0)
+
+### Context
+
+- v6 exposed tools as `POST /tools/:flat-name` with hyphen-joined paths
+- Nested resources (e.g. `workspaces/{id}`) and verb-specific methods need a route model aligned with the CLI tree
+
+### Rationale
+
+1. Command tree already encodes hierarchy — REST paths mirror `http.segment ?? key` plus `:param` routers
+2. Verb leaves (`get`, `post`, …) map to HTTP methods without duplicating path segments
+3. OpenAPI paths match real URLs clients call; query/body binding matches MCP flat args
+4. Hard break on `/tools/*` is acceptable pre-7.0-ship
+
+## Validation: JSON-SCHEMA vs Zod, etc
+
+Decision: JSON-SCHEMA
+
+### Context
+- JSON-SCHEMA is an open standard to capture a schema in json
+- Zod is the leading Typescript schema management library
+- Others are similar or less good than Zod
+
+### Rational
+Zod may actually cause more complexity and little/no gain for consumers. 
+
+Yes Zod implements some features we do custom for JSON-SCHEMA, but is opinionated, less flexible, and would actually explode complexity in some situations. Zod could be a win for consumers if they require substantial, complex validation -- but then that may not convert well to json-schema anyways and json-schema generation is a big win.
+
+1. Argsbarg does a lot of schema patching/manipulation to create different schemas per target (cli-schema.json, MCP contract, openapi.json). This would be harder with Zod
+2. Consumers can already use zod if they want by using Zod's to-json-schema features to convert when passing to Argsbarg. So we aren't actually alienating / thwarting consumers from using Zod anyways.
+3. For uses like API pass-through, proxy, dynamic schemas, Zod may actually explode complexity for consumers.
+4. Our TS->json-schema approach is actually easier and better in many cases
+  - Just write plain typescript, done.
+  - Better intellisense -- substantially less abstraction/inference, much better control

package/docs/developing.md

@@ -32,14 +32,28 @@ Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_
 
 | Recipe | When | Effect |
 | --- | --- | --- |
-| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` from template (keeps app-specific suffix) |
-| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **argsbarg Cursor rule**, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
+| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` and `code.mdc` from template (keeps app-specific suffix) |
+| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **cli-program** + **code** Cursor rules, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
+| `just consumers-schemagen` | After `@sg` type changes in consumers | Runs `argsbarg schemagen` in each `consumer_apps` path (fails if missing) |
 
 `consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.
 
-**Argsbarg authoring rule** — `scripts/merge-cli-program-rule.ts` copies `examples/full-example/.cursor/rules/cli-program.mdc` into each consumer’s `.cursor/rules/cli-program.mdc`, preserving any existing `**… conventions:**` footer block.
+**Argsbarg authoring rules** — `scripts/merge-cli-program-rule.ts` and `scripts/merge-code-rule.ts` copy templates from `examples/full-example/.cursor/rules/` into each consumer, preserving any existing `**… conventions:**` footer block.
 
-**Recommended in each consumer:** replace the template placeholder with `**<app> conventions:**` bullets (paths to `read*Flags`, shared flags, Ink vs JSON-only). Commit that file; merges refresh the shared top, not your footer.
+**Recommended in each consumer:** replace template placeholders with `**<app> conventions:**` bullets. Commit those files; merges refresh the shared top, not your footer.
+
+## Upgrading consumer apps to 7.0
+
+Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unreleased]`.
+
+1. **Schemagen:** replace `export type configType|inputType|outputType` with `/** @sg */` immediately above `export interface` / `export type` (no blank line).
+2. **Imports:** `configSchema` → `{AppConfig}Schema` (type name + `Schema`); same for leaf `inputSchema` / `outputSchema` imports (`StatusJsonOutputSchema`, etc.).
+3. **Run** `argsbarg schemagen` (or `just schemagen`) after every type change.
+4. **HTTP:** use `/api/...` REST routes only (`POST /tools/*` removed).
+5. **Hooks:** remove manual `ctx.locals.requestId` in `beforeInvoke` — framework seeds it.
+6. **Exports:** stop importing `loadLeafInputs` / `CliHttpResponseConfig` from `argsbarg` (use `ctx.inputs`, leaf `http.successContentType`).
+7. **Cursor rules:** `just consumers-dev` merges `cli-program.mdc` + `code.mdc` (includes **Abstractions** needless-extraction rule).
+8. **Verify:** `just test` and `just docgen` in each consumer repo.
 
 **Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure --sync --yes`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
 
@@ -60,7 +74,31 @@ just full-example-schemagen
 just test
 ```
 
-See [`.cursor/rules/examples.mdc`](../.cursor/rules/examples.mdc) for maintainer guidance.
+See [docs/README.md](README.md) for the full documentation map.
+
+## Advanced imports
+
+Subpath exports (root barrel still re-exports everything):
+
+```typescript
+import { Cli, type CliProgram } from "argsbarg/cli";
+import { generateOpenApi, httpServeHttp } from "argsbarg/http";
+import { packMcpBundle } from "argsbarg/mcp"; // @experimental
+import { shouldRunHeadless } from "argsbarg/headless";
+import { runSchemagen } from "argsbarg/schemagen";
+```
+
+## Module boundaries
+
+| Layer | Role |
+| --- | --- |
+| `schema.ts`, `parse.ts`, `context.ts` | Transport-agnostic CLI core |
+| `http/` | HTTP tool server (`httpServer` capability) |
+| `mcp/` | MCP stdio server and bundle (`mcpServer` capability) |
+| `configure/artifacts/` | Agent artifact sync (`configure` capability) |
+| `docs/` | Built-in documentation generators |
+
+Capabilities are declared on `CliProgram`; builtins wire them in [`src/builtins/`](../src/builtins/).
 
 ## Docs
 

package/docs/http-server.md

@@ -0,0 +1,171 @@
+# HTTP API server
+
+ArgsBarg can expose your CLI as an HTTP REST server. Each **leaf command** becomes a route under `/api/...` — nested command paths, HTTP verbs, and `:param` routers are reflected in the URL. The server uses Bun's built-in HTTP stack and binds to **localhost by default**.
+
+The HTTP API is **opt-in**. Apps that do not set `httpServer` on the program root behave exactly as before.
+
+## Quick start
+
+1. Add `httpServer` to your program root:
+
+```typescript
+import pkg from "../package.json" with { type: "json" };
+
+const cli = {
+  key: "myapp",
+  version: pkg.version,
+  description: "My app.",
+  httpServer: { enabled: true },
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
+
+`httpServer: { enabled: true }` opts in. Omit `httpServer` entirely to disable HTTP. Empty `httpServer: {}` is rejected at validation.
+
+2. Run the HTTP server:
+
+```bash
+myapp http
+```
+
+The process listens until interrupted. Startup prints the listen URL to stderr.
+
+Optional flags on `myapp http` (and `myapp http serve`): `--host`, `--port`, `--trust-proxy`, `--obscure-errors`, `--log-format`, `--log-file`, `--no-access-log`, `--dev`.
+
+## Configuration
+
+Set `httpServer` on the **program root only**. Validation rejects `httpServer` on nested nodes.
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `enabled` | *(required)* | Must be `true` when `httpServer` is set |
+| `host` | `127.0.0.1` | Listen address |
+| `port` | `3000` | Listen port |
+| `trustProxy` | `false` | Honor `X-Forwarded-For` in hooks and access logs |
+| `errors.errorSchema` | `{ error: string }` | OpenAPI + default error body shape |
+| `errors.obscureUnexpected` | `false` | Client sees generic message on 500; ECS logs real stack |
+| `hooks` | — | Observe-only wire hooks (`onRequest`, `onResponse`, `onError`) |
+
+`httpServer` and `mcpServer` are independent — enable either or both.
+
+Program-level `program.log` controls ECS JSON vs human text on stderr (and optional file tee). See [docs/decisions.md](decisions.md).
+
+## REST routes
+
+Routes are derived from the command tree:
+
+| CLI path | HTTP | Notes |
+| --- | --- | --- |
+| `workspaces get` | `GET /api/workspaces` | Verb leaf (`get`) omitted from URL |
+| `workspaces post` | `POST /api/workspaces` | Default POST success **201** |
+| `workspaces :id get` | `GET /api/workspaces/{id}` | `:id` param router |
+| `stat owner lookup` | `POST /api/stat/owner/lookup` | Default method POST when key is not a verb |
+
+Method precedence: `leaf.http.method` → verb key (`get`/`post`/…) → **POST**.
+
+Query string binds to options (values starting with `{` or `[` are JSON-parsed). Body on POST/PUT/PATCH binds to options, positionals, and `inputSchema` fields.
+
+Per-surface exposure: `http.enabled: false` removes a leaf from the route table; `http.hidden: true` keeps it callable but omits it from OpenAPI.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health` or `/health/live` | Liveness — 200 when server is listening |
+| `GET` | `/health/ready` | Readiness — config + optional `program.readiness` |
+| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
+| `GET` | `/openapi-browser` | Interactive Scalar API reference (CDN) |
+| `*` | `/api/...` | Invoke user commands (method per route) |
+| `OPTIONS` | `*` | CORS preflight (`GET, POST, PUT, PATCH, DELETE`) |
+
+`POST /tools/*` was removed in 7.0 — use `/api/*` only.
+
+## Examples
+
+```bash
+curl -s http://127.0.0.1:3000/health
+curl -s http://127.0.0.1:3000/health/ready
+curl -s http://127.0.0.1:3000/openapi.json
+open http://127.0.0.1:3000/openapi-browser
+curl -s http://127.0.0.1:3000/api/workspaces
+curl -s -X POST http://127.0.0.1:3000/api/workspaces \
+  -H 'content-type: application/json' \
+  -d '{"name":"qa2"}'
+curl -s http://127.0.0.1:3000/api/workspaces/{id}
+```
+
+Discover paths and request shapes from `openapi.json` or `myapp docs openapi`.
+
+## Handler responses (`ctx.respond()`)
+
+API and MCP tool handlers must return machine-readable output via **`ctx.respond()`** or by **returning a value** (implicit JSON). `console.log` is not included in HTTP/MCP success payloads.
+
+```typescript
+handler: (ctx) => {
+  if (ctx.hasFlag("json")) {
+    return { user: "alice", path: "/tmp" };
+  }
+  ctx.respond({
+    body: pdfBytes,
+    contentType: "application/pdf",
+    headers: { "Content-Disposition": 'inline; filename="invoice.pdf"' },
+  });
+},
+```
+
+**CLI mode:** `ctx.respond()` prints to stdout. Handlers may still use `console.log` for human-only CLI output.
+
+### Leaf HTTP metadata
+
+```typescript
+http?: {
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  segment?: string;              // URL segment override
+  successStatus?: number;
+  successContentType?: string;   // OpenAPI + default Content-Type
+  contentDisposition?: string;
+};
+```
+
+## Responses
+
+**Success:** status from `ctx.respond({ status })` → `http.successStatus` → method default (GET 200, POST 201, DELETE 204 without body).
+
+| Body type | HTTP `Content-Type` |
+| --- | --- |
+| object / array | `application/json` |
+| string | handler `contentType` or `text/plain` |
+| `Uint8Array` | e.g. `application/pdf` (set explicitly) |
+
+**Errors:** JSON `{ "error": "..." }` by default (override with `httpServer.errors.errorSchema`).
+
+| Situation | Status |
+| --- | --- |
+| Validation / help | 400 |
+| Unknown route | 404 |
+| Thrown handler / missing `ctx.respond()` | 500 |
+| Missing required config | 503 |
+
+Tool invocations are **not** gated on `/health/ready`; readiness is for orchestrators only.
+
+## Hooks and runtime
+
+`program.hooks` (`beforeInvoke`, `afterInvoke`, `formatError`, `onError`) run for user commands on CLI, HTTP, and MCP — **not** for builtins.
+
+- `ctx.locals` — per-request bag (fresh each invoke); framework sets `requestId` before `beforeInvoke` (HTTP/MCP wire id when present, else a new UUID)
+- `ctx.runtime` — shared `ServerRuntime.state` on HTTP/MCP server sessions
+- `ctx.pathParams` — values from `:param` routers
+
+Error order: `formatError` → `onError` → ECS log → client response.
+
+## CORS
+
+All responses include wide-open CORS headers (`Access-Control-Allow-Origin: *`). Not configurable in v1.
+
+## OpenAPI
+
+Call `generateOpenApi(program)` from `argsbarg/http`, fetch `GET /openapi.json`, or run `myapp docs openapi --save`. Nested `$ref` in input/output schemas are dereferenced in the spec.
+
+## Complex tool inputs
+
+Set `inputSchema` on the leaf and read coerced values with `ctx.inputs` / `ctx.inputsAs<T>()`. HTTP query, body, and path params merge into inputs before validation.

package/docs/json-schema-subset.md

@@ -0,0 +1,51 @@
+# JSON Schema subset
+
+Argsbarg validates `program.appConfig`, leaf `inputSchema`, and related documents with a **custom Draft-07 subset** in [`src/config/validate.ts`](../src/config/validate.ts). There is no runtime dependency on a full JSON Schema validator.
+
+Use this page when authoring schemas for config files, `inputSchema` on leaves, or `@sg` schemagen output.
+
+## Supported constructs
+
+| Feature | Notes |
+| --- | --- |
+| `type` | `object`, `array`, `string`, `integer`, `number`, `boolean`, `null` |
+| `properties` / `required` | Object keys; `additionalProperties: false` enforced when set |
+| `items` | Homogeneous arrays; comma-separated CLI strings coerced when `items` is a primitive |
+| `enum` / `const` | Exact value checks |
+| `anyOf` / `oneOf` | First matching branch wins; errors surface when none match |
+| `$ref` | **Local only** — `#/definitions/Name` resolved within the same root document |
+| `definitions` | Companion to local `$ref` |
+| `format` | `date`, `date-time`, `duration`, `comma-list` (and related string coercions) |
+| `minimum` / `maximum` | Numbers and integers |
+| `minLength` / `maxLength` | Strings |
+| `pattern` | String regex (ECMAScript) |
+
+## Partial validation
+
+`validateConfigDocumentPartial` validates **present keys only** — root `required` is skipped. Used for `configure set` partial writes and bootstrap flows.
+
+Leaf `inputSchema` validation uses full validation (including `required`) before the handler runs.
+
+## Not supported (today)
+
+- Remote `$ref` (`http://…`, other files)
+- `allOf`, conditional (`if`/`then`/`else`), `not`
+- Unevaluated / dynamic references
+- `default` application at validation time (defaults come from CLI option `default` or config bindings)
+
+If schemagen emits an unsupported keyword, simplify the TypeScript type or post-process the generated JSON Schema.
+
+## Where validation runs
+
+| Surface | Validator | When |
+| --- | --- | --- |
+| App config file | `validateConfigDocument` / `Partial` | `configure set`, config load |
+| Leaf `inputSchema` | Same engine via leaf-inputs | Before handler (MCP/HTTP/CLI merged inputs) |
+| `outputSchema` | Structural checks at program validate time | Startup / `cliValidateProgram` |
+
+## Related docs
+
+- [cli-program.md](cli-program.md) — `inputSchema`, JSON leaves, `ctx.inputs` / `ctx.inputsAs`
+- [config-schema.md](config-schema.md) — `program.appConfig` and schemagen pipeline
+
+Implementation: [`src/config/validate.ts`](../src/config/validate.ts), [`src/core/leaf-inputs.ts`](../src/core/leaf-inputs.ts).

package/docs/mcp.md

@@ -1,5 +1,7 @@
 # MCP server
 
+> This feature is experimental.
+
 ArgsBarg can expose your CLI to AI agents through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Each **leaf command** becomes an MCP tool; the full command tree is available as a schema resource. The server speaks JSON-RPC over stdio — one JSON object per line on stdin and stdout.
 
 MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave exactly as before.
@@ -246,7 +248,7 @@ The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nest
 
 ### Auto docs topic resources
 
-When both **`docs.enabled`** and **`mcpServer.enabled`** are true, each user key in **`docs.topics`** is also exposed as an MCP resource:
+When docs is enabled (default) and **`mcpServer.enabled`** is true, each user key in **`docs.topics`** is also exposed as an MCP resource:
 
 | Property | Value |
 | --- | --- |
@@ -419,7 +421,7 @@ Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `configure`
 
 ## Hidden commands and options
 
-Set **`hidden: true`** on a command or option to omit it from help listings, `docs cli-schema` / `docs api`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
+Set **`hidden: true`** on a command or option to omit it from help listings, `docs cli-schema` / `docs cli`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
 
 ## Reserved names