argsbarg 5.1.16 → 6.0.1

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,18 +1,13 @@
 {
   "name": "argsbarg",
-  "version": "5.1.16",
-  "type": "module",
-  "engines": {
-    "bun": ">=1.3"
-  },
-  "scripts": {
-    "//just": "echo this app uses justfile for development tasks"
-  },
+  "version": "6.0.1",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
-  "types": "./index.d.ts",
-  "bin": {
-    "argsbarg": "src/cli-tool/main.ts"
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.12",
+    "dts-bundle-generator": "^9.5.1",
+    "typescript": "^5.9.3"
   },
   "exports": {
     ".": {
@@ -20,6 +15,12 @@
       "default": "./src/index.ts"
     }
   },
+  "bin": {
+    "argsbarg": "src/cli-tool/main.ts"
+  },
+  "engines": {
+    "bun": ">=1.3"
+  },
   "files": [
     "src",
     "index.d.ts",
@@ -29,10 +30,9 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
-    "@types/bun": "^1.3.12",
-    "dts-bundle-generator": "^9.5.1",
-    "typescript": "^5.9.3"
-  }
+  "scripts": {
+    "//just": "echo this app uses justfile for development tasks"
+  },
+  "type": "module",
+  "types": "./index.d.ts"
 }

package/src/api/openapi.ts

@@ -0,0 +1,117 @@
+/*
+Hand-built OpenAPI 3.1 document from exposed MCP tools.
+*/
+
+import { collectMcpTools } from "../mcp/tools.ts";
+import type { CliProgram } from "../types.ts";
+import { dereferenceJsonSchema } from "./schema-deref.ts";
+
+const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+
+/** Resolves the effective API content type for OpenAPI response mapping. */
+function effectiveApiContentType(tool: ReturnType<typeof collectMcpTools>[number]): string {
+  return tool.leaf.apiResponse?.contentType ?? "application/json";
+}
+
+/** Builds an OpenAPI 3.1 response schema for a tool's success payload. */
+function buildSuccessResponse(tool: ReturnType<typeof collectMcpTools>[number]): Record<string, unknown> {
+  const contentType = effectiveApiContentType(tool);
+  const media: Record<string, unknown> = {};
+
+  if (contentType.includes("application/json")) {
+    const outputSchema = tool.outputSchema ?? { type: "object" };
+    media[contentType] = {
+      schema: dereferenceJsonSchema(outputSchema),
+    };
+  } else if (contentType.includes("text/html")) {
+    media[contentType] = { schema: { type: "string" } };
+  } else {
+    media[contentType] = { schema: { type: "string", format: "binary" } };
+  }
+
+  return {
+    description: "Successful tool invocation",
+    content: media,
+  };
+}
+
+/** Generates an OpenAPI 3.1 document for the program's exposed tools. */
+export function generateOpenApi(program: CliProgram): Record<string, unknown> {
+  const tools = collectMcpTools(program);
+  const paths: Record<string, unknown> = {};
+
+  for (const tool of tools) {
+    const pathKey = `/tools/${tool.apiName}`;
+    paths[pathKey] = {
+      post: {
+        operationId: tool.apiName,
+        summary: tool.description,
+        requestBody: {
+          required: false,
+          content: {
+            [JSON_CONTENT_TYPE]: {
+              schema: dereferenceJsonSchema(tool.inputSchema),
+            },
+          },
+        },
+        responses: {
+          "200": buildSuccessResponse(tool),
+          "400": {
+            description: "Invalid arguments or help requested",
+            content: {
+              [JSON_CONTENT_TYPE]: {
+                schema: {
+                  type: "object",
+                  properties: {
+                    error: { type: "string" },
+                    exitCode: { type: "integer" },
+                  },
+                  required: ["error"],
+                },
+              },
+            },
+          },
+          "404": {
+            description: "Unknown tool",
+            content: {
+              [JSON_CONTENT_TYPE]: {
+                schema: {
+                  type: "object",
+                  properties: { error: { type: "string" } },
+                  required: ["error"],
+                },
+              },
+            },
+          },
+          "500": {
+            description: "Handler error",
+            content: {
+              [JSON_CONTENT_TYPE]: {
+                schema: {
+                  type: "object",
+                  properties: { error: { type: "string" } },
+                  required: ["error"],
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: program.key,
+      version: program.version,
+      description: program.description,
+    },
+    paths,
+  };
+}
+
+/** Pretty-printed OpenAPI JSON (same document as `GET /openapi.json`). */
+export function openApiJson(program: CliProgram): string {
+  return `${JSON.stringify(generateOpenApi(program), null, 2)}\n`;
+}

package/src/api/result.ts

@@ -0,0 +1,111 @@
+/*
+Maps headless respond payloads to native HTTP Response objects.
+*/
+
+import type { CliApiResponseConfig, CliRespondOptions } from "../types.ts";
+
+/** JSON body for a failed HTTP tool invocation. */
+export interface ApiToolCallErrorBody {
+  error: string;
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+}
+
+/** Strips ANSI escape sequences from CLI-formatted text. */
+export function stripAnsi(text: string): string {
+  const ansiEscape = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+  return text.replace(ansiEscape, "");
+}
+
+/** Returns the first non-empty line of text with ANSI escapes removed. */
+export function firstErrorLine(text: string): string {
+  const line = stripAnsi(text)
+    .split("\n")
+    .map((part) => part.trim())
+    .find((part) => part.length > 0);
+  return line ?? stripAnsi(text).trim();
+}
+
+/** Wide-open CORS headers applied to all API responses. */
+export const API_CORS_HEADERS: Readonly<Record<string, string>> = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "GET, POST, OPTIONS",
+  "access-control-allow-headers": "Content-Type, Authorization",
+  "access-control-max-age": "86400",
+};
+
+/** Builds a 204 OPTIONS preflight response with CORS headers. */
+export function apiOptionsResponse(): Response {
+  return new Response(null, { status: 204, headers: { ...API_CORS_HEADERS } });
+}
+
+/** Resolves effective Content-Type for a respond payload. */
+export function resolveRespondContentType(response: CliRespondOptions, leafApiResponse?: CliApiResponseConfig): string {
+  return (
+    response.contentType ??
+    leafApiResponse?.contentType ??
+    (typeof response.body === "string" ? "text/plain; charset=utf-8" : "application/json; charset=utf-8")
+  );
+}
+
+/** Builds a native HTTP Response from a successful headless respond payload. */
+export function apiSuccessResponse(response: CliRespondOptions, leafApiResponse?: CliApiResponseConfig): Response {
+  const contentType = resolveRespondContentType(response, leafApiResponse);
+  const headers: Record<string, string> = {
+    ...API_CORS_HEADERS,
+    "content-type": contentType,
+    ...(response.headers ?? {}),
+  };
+  if (leafApiResponse?.contentDisposition && !headers["content-disposition"]) {
+    headers["content-disposition"] = leafApiResponse.contentDisposition;
+  }
+
+  const status = response.status ?? 200;
+  const { body } = response;
+
+  if (body instanceof Uint8Array) {
+    return new Response(body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength) as ArrayBuffer, {
+      status,
+      headers,
+    });
+  }
+  if (typeof body === "string") {
+    return new Response(body, { status, headers });
+  }
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+/** Builds a JSON error HTTP Response with CORS headers. */
+export function apiErrorResponse(status: number, body: ApiToolCallErrorBody): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      ...API_CORS_HEADERS,
+      "content-type": "application/json; charset=utf-8",
+    },
+  });
+}
+
+/** Scalar API reference HTML served at GET /openapi-browser. */
+export function apiDocsHtml(): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>API Reference</title>
+</head>
+<body>
+  <div id="api-reference"></div>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  <script>
+    Scalar.createApiReference("#api-reference", {
+      url: "/openapi.json",
+      orderSchemaPropertiesBy: "preserve",
+      orderRequiredPropertiesFirst: false,
+    });
+  </script>
+</body>
+</html>`;
+}

package/src/api/schema-deref.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from "bun:test";
+import { dereferenceJsonSchema } from "./schema-deref.ts";
+
+test("dereferenceJsonSchema inlines nested definitions", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      invoice: { $ref: "#/definitions/InvoiceData" },
+    },
+    definitions: {
+      InvoiceData: {
+        type: "object",
+        properties: { id: { type: "string" } },
+        required: ["id"],
+      },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({
+    invoice: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    },
+  });
+  expect(out.definitions).toBeUndefined();
+});
+
+test("dereferenceJsonSchema supports $defs", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      item: { $ref: "#/$defs/Item" },
+    },
+    $defs: {
+      Item: { type: "string" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({ item: { type: "string" } });
+  expect(out.$defs).toBeUndefined();
+});
+
+test("dereferenceJsonSchema merges $ref siblings", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      invoice: {
+        $ref: "#/definitions/InvoiceData",
+        description: "Invoice payload",
+      },
+    },
+    definitions: {
+      InvoiceData: { type: "object" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema) as {
+    properties: { invoice: { type: string; description: string } };
+  };
+  expect(out.properties.invoice).toEqual({
+    type: "object",
+    description: "Invoice payload",
+  });
+});
+
+test("dereferenceJsonSchema ignores circular refs", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      self: { $ref: "#/definitions/Node" },
+    },
+    definitions: {
+      Node: {
+        type: "object",
+        properties: {
+          again: { $ref: "#/definitions/Node" },
+        },
+      },
+    },
+  };
+  const out = dereferenceJsonSchema(schema) as {
+    properties: { self: { type: string; properties: { again: { $ref: string } } } };
+  };
+  expect(out.properties.self.type).toBe("object");
+  expect(out.properties.self.properties.again).toEqual({ $ref: "#/definitions/Node" });
+});
+
+test("dereferenceJsonSchema leaves external refs unchanged", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      remote: { $ref: "https://example.com/schema.json" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({
+    remote: { $ref: "https://example.com/schema.json" },
+  });
+});