argsbarg 5.1.15 → 6.0.0

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

@@ -0,0 +1,222 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "full-example",
+    "version": "1.0.0",
+    "description": "Argsbarg full example reference app"
+  },
+  "paths": {
+    "/tools/echo": {
+      "post": {
+        "operationId": "echo",
+        "summary": "echo — Echo a message (MCP-friendly leaf).",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json; charset=utf-8": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "message": {
+                    "type": "string",
+                    "description": "Text to print."
+                  }
+                },
+                "additionalProperties": false,
+                "required": [
+                  "message"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful tool invocation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid arguments or help requested",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "exitCode": {
+                      "type": "integer"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Unknown tool",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Handler error",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/status": {
+      "post": {
+        "operationId": "status",
+        "summary": "status — Show resolved config and app version.",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json; charset=utf-8": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "json": {
+                    "type": "boolean",
+                    "description": "Emit JSON."
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful tool invocation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$schema": "http://json-schema.org/draft-07/schema#",
+                  "type": "object",
+                  "properties": {
+                    "defaultRegion": {
+                      "type": "string",
+                      "description": "Resolved AWS region."
+                    },
+                    "maxRetries": {
+                      "type": "number",
+                      "description": "Resolved retry count."
+                    },
+                    "apiTokenSet": {
+                      "type": "boolean",
+                      "description": "Whether apiToken is set (value never included)."
+                    },
+                    "version": {
+                      "type": "string",
+                      "description": "App version from program root."
+                    }
+                  },
+                  "required": [
+                    "apiTokenSet",
+                    "version"
+                  ],
+                  "description": "JSON payload for `full-example status --json`.",
+                  "definitions": {}
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid arguments or help requested",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "exitCode": {
+                      "type": "integer"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Unknown tool",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Handler error",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,46 @@
+---
+name: full_example
+description: Operates the full-example CLI (echo, status). Use when the user mentions full-example, echo, status, or related tasks.
+---
+<!-- Generated by full-example docs skill --save; do not edit. -->
+
+
+# full-example
+
+Argsbarg full example reference app
+
+## Execution
+
+Invoke via shell:
+
+```bash
+full-example <subcommand> [options] [args]
+```
+
+## Commands
+
+- **`full-example echo`** — Echo a message (MCP-friendly leaf).
+- **`full-example status`** — Show resolved config and app version. (flags: --json)
+
+## Configuration
+
+- **apiToken** (`apiToken` (env: `FULL_EXAMPLE_API_TOKEN`)) — Create at https://example.com/settings/tokens
+- **defaultRegion** (`defaultRegion`) — AWS region for API calls.
+- **maxRetries** (`maxRetries`) — HTTP retry count (0–10).
+- **prefs** (`prefs`) — Local cache preferences (not exported to env).
+
+## Pitfalls
+
+- Pass `--` before arguments that look like flags.
+
+## Reference
+
+For full detail, open `reference.md` in this skill directory (same as `full-example docs api`).
+
+## Cursor install location
+
+- Project: `.cursor/skills/full_example/`
+- Global: `~/.cursor/skills/full_example/`
+
+Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).
+

package/examples/full-example/justfile

@@ -27,10 +27,14 @@ check: schemagen format typecheck
 dev *ARGS:
     bun --watch ./src/index.ts {{ARGS}}
 
-# Regenerate docs/schema.json and docs/skill.md
+# Regenerate consumer docs under ./docs/
 docgen: schemagen
-    @just run docs schema --save
+    @just run docs cli-schema --save
+    @just run docs api --save
     @just run docs skill --save
+    @just run docs mcp --save
+    @just run docs http --save
+    @just run docs openapi --save
 
 alias fmt := format
 

package/examples/full-example/scripts/dev-formula.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 /**
  * Stage or restore the dev Homebrew formula for `just install-local`.
- * `install` — back up release `Formula/{key}.rb` and write a `file://` dev formula.
+ * `install` — back up release `Formula/full-example.rb` and write a `file://` dev formula.
  * `reset` — restore the release formula from backup.
  */
 

package/examples/full-example/src/commands/echo/command.ts

@@ -16,6 +16,11 @@ export const echoCommand = {
     },
   ],
   handler: (ctx) => {
-    console.log(ctx.stringOpt("message") ?? "");
+    const message = ctx.stringOpt("message") ?? "";
+    if (ctx.invocation === "cli") {
+      console.log(message);
+      return;
+    }
+    return message;
   },
 } satisfies CliLeaf;

package/examples/full-example/src/program.ts

@@ -50,5 +50,8 @@ export const program = {
     mcpd: true,
     claudePlugin: true,
   },
+  apiServer: {
+    enabled: true,
+  },
   commands: [echoCommand, statusCommand],
 } satisfies CliProgram;

package/examples/mcp-test.ts

@@ -49,7 +49,12 @@ const program = {
       ],
       handler: (ctx) => {
         const name = ctx.stringOpt("name") ?? "";
-        console.log(process.env[name] ?? "");
+        const value = process.env[name] ?? "";
+        if (ctx.invocation === "cli") {
+          console.log(value);
+          return;
+        }
+        return value;
       },
     },
     {
@@ -65,7 +70,13 @@ const program = {
         },
       ],
       handler: (ctx) => {
-        console.log(`mode=${ctx.stringOpt("mode")}`);
+        const mode = ctx.stringOpt("mode") ?? "";
+        const text = `mode=${mode}`;
+        if (ctx.invocation === "cli") {
+          console.log(text);
+          return;
+        }
+        return text;
       },
     },
   ],

package/examples/nested.ts

@@ -64,10 +64,19 @@ const program = {
                   process.exit(1);
                 }
                 if (ctx.hasFlag("json")) {
-                  console.log(JSON.stringify({ user, path }));
-                } else {
-                  console.log(`lookup user=${user} path=${path}`);
+                  const payload = { user, path };
+                  if (ctx.invocation === "cli") {
+                    console.log(JSON.stringify(payload));
+                    return;
+                  }
+                  return payload;
                 }
+                const text = `lookup user=${user} path=${path}`;
+                if (ctx.invocation === "cli") {
+                  console.log(text);
+                  return;
+                }
+                return text;
               },
             },
           ],

package/examples/servers.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+/*
+This example shows the smallest end-to-end CLI+MCP+API setup.
+It includes one command, a couple of options, and a direct call to the runtime so
+readers can copy the pattern into their own scripts quickly.
+
+Demonstrates: `servers.ts hello`, MCP tool `hello`, and `POST /tools/hello`.
+
+Ex API Call:
+curl -s -X POST http://127.0.0.1:3000/tools/hello \
+  -H 'content-type: application/json' \
+  -d '{"name":"alice"}'
+Ex API Response:
+{ "greeting": "hello alice" }
+
+
+*/
+
+import pkg from "../package.json" with { type: "json" };
+import { Cli, CliOptionKind, type CliProgram } from "../src/index.ts";
+
+const program = {
+  key: "servers.ts",
+  version: pkg.version,
+  description: "Tiny demo.",
+  mcpServer: { enabled: true },
+  apiServer: { enabled: true },
+  docs: {
+    enabled: true,
+    topics: {
+      readme: { text: "# servers.ts\n\nServers demo.\n" },
+    },
+  },
+  commands: [
+    {
+      key: "hello",
+      description: "Say hello.",
+      positionals: [
+        {
+          name: "name",
+          description: "Who to greet.",
+          kind: CliOptionKind.String,
+          argMin: 0,
+          argMax: 1,
+        },
+      ],
+      options: [
+        {
+          name: "verbose",
+          description: "Enable extra logging.",
+          kind: CliOptionKind.Presence,
+          shortName: "v",
+        },
+      ],
+      handler: (ctx) => {
+        const name = ctx.args[0] ?? "world";
+        if (ctx.hasFlag("verbose") && ctx.invocation === "cli") {
+          console.log("verbose mode");
+        }
+        const greeting = `hello ${name}`;
+        if (ctx.invocation === "cli") {
+          console.log(greeting);
+          return;
+        }
+        return { greeting, verbose: ctx.hasFlag("verbose") };
+      },
+    },
+  ],
+} satisfies CliProgram;
+
+const cli = new Cli(program);
+await cli.run();

package/index.d.ts

@@ -57,8 +57,18 @@ export declare class CliContext {
 	readonly opts: Record<string, string>;
 	readonly invocation: CliInvocation;
 	readonly appConfig: AnyAppConfigSnapshot;
+	/** Original flat tool arguments for API/MCP invocations (when provided). */
+	readonly toolArgs?: Record<string, unknown>;
+	private response?;
 	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot);
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>);
+	/**
+	 * Sets the machine-readable response for API/MCP invocations, or writes to stdout in CLI mode.
+	 * May only be called once per invocation.
+	 */
+	respond(opts: CliRespondOptions): void;
+	/** Returns the respond payload set by {@link respond}, if any. */
+	getResponse(): CliRespondOptions | undefined;
 	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
 	hasFlag(name: string): boolean;
 	/** Returns the string value for a string-valued option, if present. */
@@ -90,7 +100,7 @@ export declare class CliContext {
 /**
  * How a leaf handler was dispatched.
  */
-export type CliInvocation = "cli" | "mcp";
+export type CliInvocation = "cli" | "mcp" | "api";
 /**
  * Option kinds: presence (boolean flag), string (free-form text), number (strict double), or enum (fixed choices).
  */
@@ -227,6 +237,38 @@ export interface CliMcpServerConfig {
 	/** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
 	bundle?: CliMcpBundleConfig;
 }
+/**
+ * Enables `myapp api` and the HTTP tool server (program root only).
+ * Must include `enabled: true`; omit `apiServer` entirely to disable HTTP.
+ */
+export interface CliApiServerConfig {
+	/** When `true`, enables the `api` built-in and HTTP tool server. */
+	enabled: boolean;
+	/** Listen host (default: `127.0.0.1`). */
+	host?: string;
+	/** Listen port (default: `3000`). */
+	port?: number;
+}
+/**
+ * Declarative HTTP response hints for a leaf (used by OpenAPI and default headers).
+ */
+export interface CliApiResponseConfig {
+	/** Default success Content-Type (default: `application/json`). */
+	contentType?: string;
+	/** Optional Content-Disposition (e.g. `attachment; filename="invoice.pdf"`). */
+	contentDisposition?: string;
+}
+/** Body types accepted by {@link CliContext.respond}. */
+export type CliRespondBody = string | Uint8Array | Record<string, unknown> | unknown[];
+/** Options for {@link CliContext.respond} and headless invoke results. */
+export interface CliRespondOptions {
+	body: CliRespondBody;
+	/** Default: `application/json` for objects/arrays, `text/plain` for strings; binary requires explicit type. */
+	contentType?: string;
+	/** HTTP status (default: 200). */
+	status?: number;
+	headers?: Record<string, string>;
+}
 /**
  * A custom MCP resource exposed under resources/list and resources/read.
  */
@@ -429,9 +471,13 @@ export type CliLeaf = CliNodeBase & {
 	positionals?: CliPositional[];
 	/**
 	 * JSON Schema for structured stdout (e.g. with `--json` or MCP when the handler emits JSON).
-	 * Exported in `docs schema`, `docs api`, and MCP `tools/list`; not validated at runtime yet.
+	 * Exported in `docs cli-schema`, `docs api`, and MCP `tools/list`; not validated at runtime yet.
 	 */
 	outputSchema?: Record<string, unknown>;
+	/** JSON Schema for MCP/HTTP tool arguments (flat object). */
+	inputSchema?: Record<string, unknown>;
+	/** Declarative HTTP response metadata (Content-Type, Content-Disposition). */
+	apiResponse?: CliApiResponseConfig;
 	/** Per-tool MCP exposure and metadata. */
 	mcpTool?: CliMcpToolConfig;
 };
@@ -461,6 +507,8 @@ export type CliProgram = CliNode & {
 	appConfig?: CliAppConfig;
 	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
 	mcpServer?: CliMcpServerConfig;
+	/** When set with `enabled: true`, enables the `api` built-in HTTP server. */
+	apiServer?: CliApiServerConfig;
 	/** Opt-out and defaults for `configure`. */
 	configure?: CliConfigureConfig;
 	/** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
@@ -470,9 +518,9 @@ export type CliProgram = CliNode & {
 };
 /**
  * Handler closure type for leaf commands.
- * Supports both sync and async handlers.
+ * Supports sync and async handlers; non-undefined return values become implicit JSON responses for headless invocations.
  */
-export type CliHandler = (ctx: CliContext) => void | Promise<void>;
+export type CliHandler = (ctx: CliContext) => unknown | Promise<unknown>;
 /**
  * Error thrown when the static CLI tree violates ArgsBarg rules.
  */
@@ -480,8 +528,13 @@ export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
 	constructor(message: string);
 }
+/** Generates an OpenAPI 3.1 document for the program's exposed tools. */
+export declare function generateOpenApi(program: CliProgram): Record<string, unknown>;
+/** Pretty-printed OpenAPI JSON (same document as `GET /openapi.json`). */
+export declare function openApiJson(program: CliProgram): string;
 /** Platform builtins derived from program config and runtime. */
 export interface CliCapabilities {
+	api: boolean;
 	completion: boolean;
 	mcp: boolean;
 	configure: boolean;
@@ -510,6 +563,8 @@ export interface CliInvokeResult {
 	stdout: string;
 	stderr: string;
 	errorMsg?: string;
+	/** Headless response payload when invocation is `api` or `mcp` and the handler succeeded. */
+	response?: CliRespondOptions;
 }
 /** Argsbarg runtime for a validated, frozen {@link CliProgram}. */
 export declare class Cli {
@@ -523,8 +578,12 @@ export declare class Cli {
 	exportCommandSchema(): CliSchemaExport;
 	exportAppConfigSchema(): Record<string, unknown> | undefined;
 	run(argv?: string[]): Promise<never>;
-	invoke(argv: string[]): Promise<CliInvokeResult>;
+	invoke(argv: string[], opts?: {
+		invocation?: CliInvocation;
+		toolArgs?: Record<string, unknown>;
+	}): Promise<CliInvokeResult>;
 	serveMcp(): Promise<never>;
+	serveApi(): Promise<never>;
 	private prepareDispatch;
 	private buildAppConfigSnapshot;
 }
@@ -539,7 +598,7 @@ export declare function parseDate(s: string): string;
 export declare function parseDateTime(s: string): string;
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
-/** True when `--json` was passed or the handler was invoked via MCP. */
+/** True when `--json` was passed or the handler was invoked headlessly over MCP/HTTP. */
 export declare function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean;
 /**
  * Headless when MCP, `--json`, `--dry-run`, or stdin is not a TTY.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.1.15",
+  "version": "6.0.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"