argsbarg 5.1.16 → 6.0.0

package/src/mcp/tools.ts

@@ -41,8 +41,10 @@ export function mcpServerId(root: CliProgram): string {
 
 /** One MCP tool derived from a leaf CLI command. */
 export interface McpToolDef {
-  /** MCP tool name (underscore-separated path). */
+  /** MCP tool name (underscore-separated, sanitized segments). */
   name: string;
+  /** HTTP API tool name (hyphen-separated path; preserves command key spelling). */
+  apiName: string;
   /** Tool description from the leaf command. */
   description: string;
   /** Command path segments from the program root. */
@@ -69,6 +71,14 @@ export function mcpToolName(root: CliProgram, path: string[]): string {
   return path.map(sanitizeToolSegment).join("_");
 }
 
+/** Builds the HTTP API tool name for a leaf at the given path (hyphen-joined, unsanitized). */
+export function apiToolName(root: CliProgram, path: string[]): string {
+  if (path.length === 0) {
+    return root.key;
+  }
+  return path.join("-");
+}
+
 /** JSON Schema property for one option. */
 function optionProperty(opt: CliOption): Record<string, unknown> {
   const base: Record<string, unknown> = { description: opt.description };
@@ -197,7 +207,7 @@ export function allMcpResources(root: CliProgram): McpResourceEntry[] {
   const builtIn: McpResourceEntry = {
     uri: schemaUri,
     name: "cli-schema",
-    description: "Full CLI command tree (same as docs schema).",
+    description: "Full CLI command tree (same as docs cli-schema).",
     mimeType: "application/json",
     load: () => cliSchemaJson(root),
   };
@@ -227,10 +237,11 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
       const outputSchema = leafOutputSchema(cmd);
       out.push({
         name: mcpToolName(root, path),
+        apiName: apiToolName(root, path),
         description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,
-        inputSchema: buildInputSchema(root, path, cmd),
+        inputSchema: cmd.inputSchema ?? buildInputSchema(root, path, cmd),
         ...(outputSchema === undefined ? {} : { outputSchema }),
       });
       return;

package/src/mcp.integration.test.ts

@@ -6,8 +6,15 @@ import { expect, test } from "bun:test";
 import { join } from "node:path";
 import { $ } from "bun";
 import type { CliProgram } from "./index.ts";
-import { buildToolCallSuccess } from "./mcp/result.ts";
-import { collectMcpTools, mcpToolCallToArgv, mcpToolDescription, sanitizeToolSegment } from "./mcp/tools.ts";
+import { buildToolCallSuccessFromResponse } from "./mcp/result.ts";
+import {
+  apiToolName,
+  collectMcpTools,
+  mcpToolCallToArgv,
+  mcpToolDescription,
+  mcpToolName,
+  sanitizeToolSegment,
+} from "./mcp/tools.ts";
 import { cliSchemaExport } from "./schema.ts";
 import { mcpRequest, nestedMcpFixture, testProgram } from "./test-fixtures.ts";
 import { cliValidateProgram } from "./validate.ts";
@@ -24,17 +31,25 @@ test("mcpToolDescription formats CLI path and root-leaf prefix", () => {
   expect(mcpToolDescription([], "helloapp", "Tiny demo.")).toBe("helloapp — Tiny demo.");
 });
 
+test("apiToolName hyphen-joins path; mcpToolName sanitizes to underscores", () => {
+  expect(apiToolName(nestedMcpFixture, ["stat", "owner", "lookup"])).toBe("stat-owner-lookup");
+  expect(mcpToolName(nestedMcpFixture, ["stat", "owner", "lookup"])).toBe("stat_owner_lookup");
+  expect(apiToolName(nestedMcpFixture, ["render-invoice"])).toBe("render-invoice");
+  expect(mcpToolName(nestedMcpFixture, ["render-invoice"])).toBe("render_invoice");
+});
+
 test("collectMcpTools lists user leaf commands only", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const names = tools.map((t) => t.name);
   expect(names).toContain("stat_owner_lookup");
+  const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
+  expect(lookup.apiName).toBe("stat-owner-lookup");
+  expect(lookup.description).toBe("stat owner lookup — Resolve owner info.");
   expect(names).toContain("read");
   expect(names).not.toContain("hidden");
   expect(names).not.toContain("configure");
   expect(names).not.toContain("mcp");
   expect(names).not.toContain("completion");
-  const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
-  expect(lookup.description).toBe("stat owner lookup — Resolve owner info.");
 });
 
 /** Tests that collectMcpTools appends leaf notes to MCP tool description. */
@@ -345,44 +360,35 @@ test("mcpTool on routing node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpTool is only supported on leaf commands/);
 });
 
-test("buildToolCallSuccess returns stdout only", () => {
-  const result = buildToolCallSuccess("hello\n", "");
+test("buildToolCallSuccessFromResponse maps JSON object", () => {
+  const result = buildToolCallSuccessFromResponse({ body: { a: 1 } });
   expect(result.isError).toBe(false);
-  expect(result.content).toEqual([{ type: "text", text: "hello\n" }]);
-  expect(result.structuredContent).toBeUndefined();
-});
-
-test("buildToolCallSuccess adds stderr as second content block", () => {
-  const result = buildToolCallSuccess("out\n", "warn\n");
-  expect(result.content).toEqual([
-    { type: "text", text: "out\n" },
-    { type: "text", text: "warn" },
-  ]);
-  expect(result.structuredContent).toBeUndefined();
-});
-
-test("buildToolCallSuccess stderr-only still includes stdout slot", () => {
-  const result = buildToolCallSuccess("", "warn\n");
-  expect(result.content).toEqual([
-    { type: "text", text: "" },
-    { type: "text", text: "warn" },
-  ]);
-});
-
-test("buildToolCallSuccess parses JSON structuredContent", () => {
-  const result = buildToolCallSuccess('{"a":1}\n', "");
   expect(result.structuredContent).toEqual({ a: 1 });
-  expect(result.content[0]?.text).toBe('{"a":1}\n');
+  expect(result.content[0]?.text).toBe("");
 });
 
-test("buildToolCallSuccess skips structuredContent for plain text", () => {
-  const result = buildToolCallSuccess("lookup user=x\n", "");
-  expect(result.structuredContent).toBeUndefined();
+test("buildToolCallSuccessFromResponse maps string body", () => {
+  const result = buildToolCallSuccessFromResponse({
+    body: "lookup user=x",
+    contentType: "text/plain; charset=utf-8",
+  });
+  expect(result.structuredContent).toEqual({
+    content: "lookup user=x",
+    contentType: "text/plain; charset=utf-8",
+  });
 });
 
-test("buildToolCallSuccess parses JSON primitives", () => {
-  const result = buildToolCallSuccess("true\n", "");
-  expect(result.structuredContent).toBe(true);
+test("buildToolCallSuccessFromResponse maps binary body as base64", () => {
+  const bytes = new Uint8Array([0x25, 0x50, 0x44, 0x46]);
+  const result = buildToolCallSuccessFromResponse({
+    body: bytes,
+    contentType: "application/pdf",
+  });
+  expect(result.structuredContent).toEqual({
+    data: "JVBERg==",
+    contentType: "application/pdf",
+    encoding: "base64",
+  });
 });
 
 test("MCP initialize returns tools and resources capabilities", async () => {
@@ -425,9 +431,11 @@ test("MCP tools/call runs stat_owner_lookup", async () => {
       },
     },
   ]);
-  const res = responses.get(4) as { result: { content: { text: string }[]; isError: boolean } };
+  const res = responses.get(4) as {
+    result: { content: { text: string }[]; structuredContent?: { content: string }; isError: boolean };
+  };
   expect(res.result.isError).toBe(false);
-  expect(res.result.content[0]?.text).toContain("lookup user=test");
+  expect(res.result.structuredContent?.content).toContain("lookup user=test");
 });
 
 /** MCP tools/call returns structuredContent for JSON stdout. */
@@ -453,7 +461,6 @@ test("MCP tools/call returns structuredContent for JSON stdout", async () => {
   };
   expect(res.result.isError).toBe(false);
   expect(res.result.structuredContent).toEqual({ user: "test", path: readme });
-  expect(JSON.parse(res.result.content[0]?.text.trim())).toEqual({ user: "test", path: readme });
 });
 
 /** MCP tools/call errors on missing required positional. */

package/src/parse.test.ts

@@ -503,8 +503,8 @@ test("leaf completion help prints correctly", async () => {
 });
 
 /** Docs schema exports JSON for nested CLIs. */
-test("docs schema exports JSON for nested CLIs", async () => {
-  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts docs schema`.nothrow().quiet();
+test("docs cli-schema exports JSON for nested CLIs", async () => {
+  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts docs cli-schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
   expect(stderr.toString()).toBe("");
 
@@ -520,8 +520,8 @@ test("docs schema exports JSON for nested CLIs", async () => {
 });
 
 /** Docs schema exports JSON for leaf roots. */
-test("docs schema exports JSON for leaf roots", async () => {
-  const { stdout, exitCode } = await $`bun run examples/minimal.ts docs schema`.nothrow().quiet();
+test("docs cli-schema exports JSON for leaf roots", async () => {
+  const { stdout, exitCode } = await $`bun run examples/minimal.ts docs cli-schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
 
   const schema = JSON.parse(stdout.toString());
@@ -658,8 +658,8 @@ test("docs help lists schema, api, and skill subcommands", () => {
     ],
   });
   const help = cliHelpRender(cliPresentationRoot(root), ["docs"], false);
-  expect(help).toContain("schema");
-  expect(help).toContain("Print the full command tree as JSON.");
+  expect(help).toContain("cli-schema");
+  expect(help).toContain("Print the full CLI command tree as JSON.");
   expect(help).toContain("api");
   expect(help).toContain("markdown");
   expect(help).toContain("skill");
@@ -814,6 +814,16 @@ test("cliValidateProgram rejects empty mcpServer", () => {
   expect(() => cliValidateProgram(root)).toThrow(/mcpServer requires enabled: true/);
 });
 
+test("cliValidateProgram rejects empty apiServer", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    apiServer: {} as { enabled: boolean },
+    handler: () => {},
+  });
+  expect(() => cliValidateProgram(root)).toThrow(/apiServer requires enabled: true/);
+});
+
 test("resolveMcpSchemaUri uses sanitized root key", () => {
   const root = testProgram({
     key: "nested.ts",

package/src/respond.ts

@@ -0,0 +1,48 @@
+/*
+Helpers for ctx.respond(): content-type defaults and CLI stdout serialization.
+*/
+
+import type { CliRespondBody, CliRespondOptions } from "./types.ts";
+
+/** Fills default contentType on respond options based on body shape. */
+export function normalizeRespondOptions(opts: CliRespondOptions): CliRespondOptions {
+  if (opts.contentType !== undefined) {
+    return opts;
+  }
+  const body = opts.body;
+  if (body instanceof Uint8Array) {
+    throw new Error("ctx.respond() with Uint8Array body requires an explicit contentType");
+  }
+  if (typeof body === "string") {
+    return { ...opts, contentType: "text/plain; charset=utf-8" };
+  }
+  return { ...opts, contentType: "application/json; charset=utf-8" };
+}
+
+/** Writes a respond body to process.stdout for CLI invocations. */
+export function writeRespondBodyToStdout(body: CliRespondBody): void {
+  if (body instanceof Uint8Array) {
+    process.stdout.write(body);
+    return;
+  }
+  if (typeof body === "string") {
+    process.stdout.write(body);
+    if (!body.endsWith("\n")) {
+      process.stdout.write("\n");
+    }
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(body, null, 2)}\n`);
+}
+
+/** Encodes binary respond bodies as base64 for MCP structuredContent. */
+export function encodeRespondBodyBase64(body: Uint8Array): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(body).toString("base64");
+  }
+  let binary = "";
+  for (const byte of body) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}

package/src/schema.ts

@@ -7,7 +7,7 @@ import { cliResolveNotes } from "./help.ts";
 import { visibleOptions } from "./hidden.ts";
 import { type CliNode, type CliProgram, isCliLeaf, isCliRouter, leafOutputSchema } from "./types.ts";
 
-const RESERVED = new Set(["completion", "configure", "docs", "mcp", "version"]);
+const RESERVED = new Set(["api", "completion", "configure", "docs", "mcp", "version"]);
 
 function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
   if (cmd.hidden) {

package/src/skill/generate.ts

@@ -218,7 +218,7 @@ function buildPluginSkillMd(root: CliProgram, dirName: string): string {
     "",
     `- Server id: \`${serverId}\` (configured in plugin \`.mcp.json\`)`,
     "- Tool names and argument shapes come from MCP `tools/list`",
-    `- Full schema: \`${schemaUri}\` (same as \`${root.key} docs schema\`)`,
+    `- Full schema: \`${schemaUri}\` (same as \`${root.key} docs cli-schema\`)`,
     "",
   ];
 

package/src/types.ts

@@ -9,7 +9,7 @@ import type { CliContext } from "./context.ts";
 /**
  * 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).
@@ -154,6 +154,42 @@ export interface CliMcpServerConfig {
   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.
  */
@@ -385,9 +421,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;
 };
@@ -420,6 +460,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`). */
@@ -445,9 +487,9 @@ export function leafOutputSchema(leaf: CliLeaf): Record<string, unknown> | undef
 
 /**
  * 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.

package/src/validate.ts

@@ -180,6 +180,10 @@ export function cliValidateProgram(program: CliProgram): void {
     throw new CliSchemaValidationError("mcpServer requires enabled: true; omit mcpServer to disable MCP");
   }
 
+  if (program.apiServer !== undefined && program.apiServer.enabled !== true) {
+    throw new CliSchemaValidationError("apiServer requires enabled: true; omit apiServer to disable HTTP API");
+  }
+
   if (program.docs !== undefined && program.docs.enabled !== true) {
     throw new CliSchemaValidationError("docs requires enabled: true; omit docs to disable bundled documentation");
   }
@@ -216,6 +220,9 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     if (rogue.mcpServer !== undefined) {
       throw new CliSchemaValidationError(`mcpServer is only supported on the program root (not on ${node.key})`);
     }
+    if (rogue.apiServer !== undefined) {
+      throw new CliSchemaValidationError(`apiServer is only supported on the program root (not on ${node.key})`);
+    }
     if (rogue.configure !== undefined) {
       throw new CliSchemaValidationError(`configure is only supported on the program root (not on ${node.key})`);
     }