argsbarg 5.1.15 → 6.0.0

package/src/docs/docs.test.ts

@@ -73,14 +73,20 @@ test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
   const docs = root.docs;
   if (!docs) throw new Error("expected docs fixture");
-  docs.topics.schema = { text: "nope" };
+  docs.topics["cli-schema"] = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
-  delete docs.topics.schema;
+  delete docs.topics["cli-schema"];
   docs.topics.skill = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
   delete docs.topics.skill;
   docs.topics.api = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
+  delete docs.topics.api;
+  docs.topics.openapi = { text: "nope" };
+  expect(() => cliValidateProgram(root)).toThrow(/reserved/);
+  delete docs.topics.openapi;
+  docs.topics.http = { text: "nope" };
+  expect(() => cliValidateProgram(root)).toThrow(/reserved/);
 });
 
 test("docsEffectiveDefaultTopic uses first topic key", () => {
@@ -132,6 +138,46 @@ test("docs mcp absent from router when MCP disabled", async () => {
   expect(result.exitCode).not.toBe(0);
 });
 
+test("docs http when API enabled", async () => {
+  const root = docsFixture(true);
+  root.apiServer = { enabled: true };
+  cliValidateProgram(root);
+  const result = await new Cli(root).invoke(["docs", "http"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("HTTP API (myapp)");
+  expect(result.stdout).toContain("curl -s -X POST");
+});
+
+test("docs http absent from router when API disabled", async () => {
+  const root = docsFixture(false);
+  const presentation = cliPresentationRoot(root);
+  const docsNode = presentation.commands.find((c) => c.key === "docs");
+  expect(docsNode && "commands" in docsNode).toBe(true);
+  if (docsNode && "commands" in docsNode) {
+    expect(docsNode.commands.some((c) => c.key === "http")).toBe(false);
+    expect(docsNode.commands.some((c) => c.key === "openapi")).toBe(false);
+  }
+  const result = await new Cli(root).invoke(["docs", "http"]);
+  expect(result.exitCode).not.toBe(0);
+});
+
+test("docs openapi when API enabled", async () => {
+  const root = docsFixture(true);
+  root.apiServer = { enabled: true };
+  cliValidateProgram(root);
+  const result = await new Cli(root).invoke(["docs", "openapi"]);
+  expect(result.exitCode).toBe(0);
+  const doc = JSON.parse(result.stdout) as { openapi: string; paths: Record<string, unknown> };
+  expect(doc.openapi).toBe("3.1.0");
+  expect(doc.paths).toBeDefined();
+});
+
+test("docs openapi absent when API disabled", async () => {
+  const root = docsFixture(false);
+  const result = await new Cli(root).invoke(["docs", "openapi"]);
+  expect(result.exitCode).not.toBe(0);
+});
+
 test("presentation includes docs subtree", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
@@ -139,8 +185,8 @@ test("presentation includes docs subtree", () => {
   expect(docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme")).toBe(true);
 });
 
-test("docs schema prints JSON", async () => {
-  const result = await new Cli(docsFixture()).invoke(["docs", "schema"]);
+test("docs cli-schema prints JSON", async () => {
+  const result = await new Cli(docsFixture()).invoke(["docs", "cli-schema"]);
   expect(result.exitCode).toBe(0);
   const schema = JSON.parse(result.stdout);
   expect(schema.key).toBe("myapp");
@@ -153,7 +199,7 @@ test("docs api prints markdown reference", async () => {
   expect(result.stdout).toContain("# myapp — CLI API reference");
   expect(result.stdout).toContain("## `myapp run`");
   expect(result.stdout).toContain("Run something.");
-  expect(result.stdout).toContain("myapp docs schema");
+  expect(result.stdout).toContain("myapp docs cli-schema");
 });
 
 test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
@@ -195,12 +241,12 @@ test("docs skill help recommends configure", async () => {
   }
 });
 
-test("presentation includes docs schema and skill", () => {
+test("presentation includes docs cli-schema and skill", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
   expect(docsNode && "commands" in docsNode).toBe(true);
   if (docsNode && "commands" in docsNode) {
-    expect(docsNode.commands.some((c) => c.key === "schema")).toBe(true);
+    expect(docsNode.commands.some((c) => c.key === "cli-schema")).toBe(true);
     expect(docsNode.commands.some((c) => c.key === "api")).toBe(true);
     expect(docsNode.commands.some((c) => c.key === "skill")).toBe(true);
   }
@@ -210,7 +256,7 @@ test("completions offer docs subcommands", () => {
   const bash = completionBashScript(cliPresentationRoot(docsFixture()));
   expect(bash).toContain("docs) echo");
   expect(bash).toContain("readme) echo");
-  expect(bash).toContain("schema) echo");
+  expect(bash).toContain("cli-schema) echo");
   expect(bash).toContain("api) echo");
   expect(bash).toContain("skill) echo");
 });
@@ -255,16 +301,28 @@ test("docs skill --save keeps frontmatter first", async () => {
   expect(text.indexOf(hint)).toBeGreaterThan(text.indexOf("---\n", 4));
 });
 
-test("docs schema --save writes JSON file", async () => {
-  const result = await new Cli(docsFixture()).invoke(["docs", "schema", "--save"]);
+test("docs cli-schema --save writes JSON file", async () => {
+  const result = await new Cli(docsFixture()).invoke(["docs", "cli-schema", "--save"]);
   expect(result.exitCode).toBe(0);
-  expect(result.stdout.trim()).toBe("docs/schema.json");
-  const text = readFileSync(join(workDir, "docs/schema.json"), "utf8");
+  expect(result.stdout.trim()).toBe("docs/cli-schema.json");
+  const text = readFileSync(join(workDir, "docs/cli-schema.json"), "utf8");
   expect(text).not.toContain("Generated by");
   const schema = JSON.parse(text);
   expect(schema.key).toBe("myapp");
 });
 
+test("docs openapi --save writes JSON file", async () => {
+  const root = docsFixture(true);
+  root.apiServer = { enabled: true };
+  const result = await new Cli(root).invoke(["docs", "openapi", "--save"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout.trim()).toBe("docs/openapi.json");
+  const text = readFileSync(join(workDir, "docs/openapi.json"), "utf8");
+  expect(text).not.toContain("Generated by");
+  const doc = JSON.parse(text) as { openapi: string };
+  expect(doc.openapi).toBe("3.1.0");
+});
+
 test("saveDocsTopic returns relative path", () => {
   const path = saveDocsTopic(docsFixture(), "api");
   expect(path).toBe("docs/api.md");

package/src/docs/http-guide.ts

@@ -0,0 +1,132 @@
+import { resolveApiListenAddress } from "../api/server.ts";
+import { defaultConfigEntryTitle } from "../config/entry.ts";
+import { displayAppConfigPath } from "../config/file.ts";
+import { collectMcpTools, type McpToolDef } from "../mcp/tools.ts";
+import { collectOptionDefs } from "../parse.ts";
+import { CliOptionKind, type CliProgram } from "../types.ts";
+
+/** Formats one exposed tool for the auto-generated HTTP guide. */
+function formatToolLine(root: CliProgram, tool: McpToolDef): string {
+  const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
+  let line = `- \`${tool.apiName}\` (MCP: \`${tool.name}\`, CLI: \`${cliPath}\`) — ${tool.description}`;
+  const opts = collectOptionDefs(root, tool.path);
+  const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
+  if (flags.length > 0) {
+    line += ` (flags: ${flags.join(", ")})`;
+  }
+  return line;
+}
+
+/** Generates the auto `docs http` markdown guide from schema and API config. */
+export function generateHttpGuide(root: CliProgram): string {
+  const api = root.apiServer;
+  if (!api) {
+    throw new Error("HTTP API server not enabled");
+  }
+
+  const tools = collectMcpTools(root);
+  const { hostname, port } = resolveApiListenAddress(root);
+  const baseUrl = `http://${hostname}:${port}`;
+
+  const lines: string[] = [
+    `# HTTP API (${root.key})`,
+    "",
+    `${root.key} exposes the same callable tools over HTTP as MCP.`,
+    "",
+    "## Running",
+    "",
+    "```bash",
+    `${root.key} api`,
+    "```",
+    "",
+    `Listens on **${baseUrl}** by default (\`apiServer.host\` / \`apiServer.port\`).`,
+    "",
+    "Bind is localhost-only in v0 — use a reverse proxy for remote access.",
+    "",
+    "## Endpoints",
+    "",
+    "| Method | Path | Purpose |",
+    "| --- | --- | --- |",
+    "| `GET` | `/health` | Liveness check |",
+    "| `GET` | `/openapi.json` | OpenAPI 3.1 document (tool paths and request shapes) |",
+    "| `GET` | `/openapi-browser` | Interactive Scalar API reference |",
+    "| `POST` | `/tools/:name` | Invoke with flat JSON args object in the body |",
+    "| `OPTIONS` | `*` | CORS preflight |",
+    "",
+    "Replace `{tool-key}` below with a path segment from `openapi.json` (`paths` keys are `/tools/{tool-key}`). Match body keys to that tool's `requestBody` schema in the spec.",
+    "",
+    "## Examples",
+    "",
+    "```bash",
+    `curl -s ${baseUrl}/health`,
+    `curl -s ${baseUrl}/openapi.json`,
+    `curl -s -X POST ${baseUrl}/tools/{tool-key} \\`,
+    '  -H "content-type: application/json" \\',
+    "  -d '{...}'",
+    "```",
+    "",
+    "## Responses",
+    "",
+    "Success (`200`): raw response body (JSON object, string, or binary). No `{ ok, stdout }` envelope.",
+    "",
+    "Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.",
+    "",
+    'Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.',
+    "",
+  ];
+
+  if (root.appConfig?.entries && Object.keys(root.appConfig.entries).length > 0) {
+    lines.push("## Configuration", "");
+    lines.push(
+      `Configure before first use: \`${root.key} configure\`.`,
+      "",
+      `Default config file: \`${displayAppConfigPath(root)}\`.`,
+      "",
+    );
+    for (const [key, entry] of Object.entries(root.appConfig.entries)) {
+      const label = entry.title ?? defaultConfigEntryTitle(key);
+      const req = entry.required === false ? "optional" : "required";
+      const envNote = entry.env ? ` → env \`${entry.env}\`` : "";
+      lines.push(`- **${label}** (\`${key}\`, ${req}${envNote}) — ${entry.description}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Exposed tools", "");
+
+  if (tools.length === 0) {
+    lines.push("(No tools exposed.)", "");
+  } else {
+    for (const tool of tools) {
+      lines.push(formatToolLine(root, tool));
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## Tool arguments",
+    "",
+    "POST bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
+    "",
+    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /openapi-browser\`**) for per-tool request shapes — each \`POST /tools/{name}\` path has a \`requestBody\` schema.`,
+    "",
+    "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
+    "Options with `format: comma-list` accept a comma-separated string or JSON array.",
+    "Options with a schema `default` are applied when omitted.",
+    "",
+    `Shell invocation reference: \`${root.key} docs api\`. Full CLI tree JSON: \`${root.key} docs cli-schema\`.`,
+    "",
+    "## OpenAPI",
+    "",
+    "The HTTP API is described in OpenAPI 3.1.",
+    "",
+    `- **Browse** — [${baseUrl}/openapi-browser](${baseUrl}/openapi-browser) (Scalar UI; loads \`/openapi.json\`)`,
+    `- **Fetch** — \`curl -s ${baseUrl}/openapi.json\``,
+    `- **Save offline** — \`${root.key} docs openapi --save\` → \`./docs/openapi.json\` (or \`just docgen\` in app repos)`,
+    "",
+    "Use the spec to discover tool names (`paths`) and request/response shapes before calling `POST /tools/:name`.",
+    "",
+  );
+
+  return lines.join("\n");
+}

package/src/docs/mcp-guide.ts

@@ -202,7 +202,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "|-----------|---------|",
     "| `tools/list` | Callable tools for exposed leaf commands |",
     "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
-    `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs schema\` |`,
+    `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs cli-schema\` |`,
   );
   if (docsEnabled(root)) {
     const docs = root.docs;
@@ -228,7 +228,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "## Tool arguments",
     "",
     "Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
-    `See \`${root.key} docs schema\` or the schema resource for per-tool shapes.`,
+    `See \`${root.key} docs cli-schema\` or the schema resource for per-tool shapes.`,
     "",
     "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
     "Options with `format: comma-list` accept a comma-separated string or JSON array.",
@@ -236,7 +236,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
     "## Protocol",
     "",
-    "Stdio NDJSON JSON-RPC. Help and `docs schema` are not available through tool calls.",
+    "Stdio NDJSON JSON-RPC. Help and `docs cli-schema` are not available through tool calls.",
     `Run \`${root.key} docs\` for bundled user documentation.`,
     "",
   );

package/src/docs/resolve.ts

@@ -1,11 +1,13 @@
+import { openApiJson } from "../api/openapi.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { generateSkillBundle } from "../skill/generate.ts";
 import type { CliDocsConfig, CliProgram } from "../types.ts";
 import { generateApiGuide } from "./api-guide.ts";
+import { generateHttpGuide } from "./http-guide.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
 
 /** Built-in docs subcommand keys not allowed in `docs.topics`. */
-export const DOCS_BUILTIN_TOPIC_KEYS = ["mcp", "all", "schema", "api", "skill"] as const;
+export const DOCS_BUILTIN_TOPIC_KEYS = ["http", "mcp", "all", "cli-schema", "api", "skill", "openapi"] as const;
 
 export type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
 
@@ -43,6 +45,16 @@ export function docsIncludesMcpTopic(program: CliProgram): boolean {
   return docsEnabled(program) && program.mcpServer?.enabled === true;
 }
 
+/** Whether HTTP auto-guide topic is included. */
+export function docsIncludesHttpTopic(program: CliProgram): boolean {
+  return docsEnabled(program) && program.apiServer?.enabled === true;
+}
+
+/** Whether OpenAPI export topic is included. */
+export function docsIncludesOpenApiTopic(program: CliProgram): boolean {
+  return docsIncludesHttpTopic(program);
+}
+
 /** Leaf help description for a user topic. */
 export function docsTopicDescription(key: string, custom?: string): string {
   if (custom) {
@@ -67,6 +79,12 @@ export function docsTopicText(program: CliProgram, topic: string): string {
     }
     return generateMcpGuide(program);
   }
+  if (topic === "http") {
+    if (!docsIncludesHttpTopic(program)) {
+      throw new Error("Unknown docs topic 'http'.");
+    }
+    return generateHttpGuide(program);
+  }
   const entry = docs.topics[topic];
   if (!entry) {
     throw new Error(`Unknown docs topic '${topic}'.`);
@@ -76,9 +94,15 @@ export function docsTopicText(program: CliProgram, topic: string): string {
 
 /** Full file body for a docs topic (stdout or `--save`). */
 export function docsTopicContent(program: CliProgram, topic: string): string {
-  if (topic === "schema") {
+  if (topic === "cli-schema") {
     return cliSchemaJson(program);
   }
+  if (topic === "openapi") {
+    if (!docsIncludesOpenApiTopic(program)) {
+      throw new Error("Unknown docs topic 'openapi'.");
+    }
+    return openApiJson(program);
+  }
   if (topic === "api") {
     return generateApiGuide(program);
   }

package/src/docs/save.ts

@@ -36,8 +36,11 @@ export function docsTopicContentForSave(program: CliProgram, topic: string): str
 
 /** Filename for a saved docs topic. */
 export function docsSaveFilename(topic: string): string {
-  if (topic === "schema") {
-    return "schema.json";
+  if (topic === "cli-schema") {
+    return "cli-schema.json";
+  }
+  if (topic === "openapi") {
+    return "openapi.json";
   }
   return `${topic}.md`;
 }

package/src/headless/tool-call.ts

@@ -0,0 +1,147 @@
+/*
+Shared headless tool dispatch for MCP and HTTP: config bootstrap, argv conversion, and invoke.
+*/
+
+import { apiErrorResponse, apiSuccessResponse } from "../api/result.ts";
+import type { Cli, CliInvokeResult } from "../cli.ts";
+import { bootstrapAppConfig } from "../config/bootstrap.ts";
+import { formatMcpMissingConfigMessage, missingRequiredConfig } from "../config/resolve.ts";
+import { buildToolCallSuccessFromResponse } from "../mcp/result.ts";
+import { collectMcpTools, type McpToolDef, mcpToolCallToArgv } from "../mcp/tools.ts";
+import type { CliInvocation, CliProgram } from "../types.ts";
+
+/** Outcome of resolving a tool name against the program schema. */
+export type ToolLookupResult =
+  | { ok: true; tool: McpToolDef }
+  | { ok: false; kind: "unknown"; message: string }
+  | { ok: false; kind: "missing_config"; message: string };
+
+/** Successful headless tool invocation payload shared by MCP and HTTP. */
+export interface HeadlessToolCallSuccess {
+  ok: true;
+  response: NonNullable<CliInvokeResult["response"]>;
+  mcpResult: ReturnType<typeof buildToolCallSuccessFromResponse>;
+}
+
+/** Failed headless tool invocation payload shared by MCP and HTTP. */
+export interface HeadlessToolCallFailure {
+  ok: false;
+  kind: "argv" | "invoke" | "help";
+  message: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  invokeResult?: CliInvokeResult;
+}
+
+export type HeadlessToolCallResult = HeadlessToolCallSuccess | HeadlessToolCallFailure;
+
+/** Finds an exposed tool by MCP or HTTP API tool name. */
+export function lookupHeadlessTool(
+  program: CliProgram,
+  toolName: string,
+  invocation: CliInvocation = "mcp",
+): ToolLookupResult {
+  const tools = collectMcpTools(program);
+  const tool =
+    invocation === "api" ? tools.find((t) => t.apiName === toolName) : tools.find((t) => t.name === toolName);
+  if (!tool) {
+    return { ok: false, kind: "unknown", message: `Unknown tool: ${toolName}` };
+  }
+  const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+  const missingConfig = missingRequiredConfig(program, resolved);
+  if (missingConfig.length > 0) {
+    return {
+      ok: false,
+      kind: "missing_config",
+      message: formatMcpMissingConfigMessage(program, missingConfig),
+    };
+  }
+  return { ok: true, tool };
+}
+
+/**
+ * Converts flat tool arguments to argv and invokes the leaf handler headlessly.
+ */
+export async function executeHeadlessToolCall(
+  cli: Cli,
+  tool: McpToolDef,
+  args: Record<string, unknown>,
+  invocation: CliInvocation,
+): Promise<HeadlessToolCallResult> {
+  const argvResult = mcpToolCallToArgv(cli.program, tool, args);
+  if ("error" in argvResult) {
+    return {
+      ok: false,
+      kind: "argv",
+      message: argvResult.error,
+      exitCode: 1,
+      stdout: "",
+      stderr: "",
+    };
+  }
+
+  const invokeResult = await cli.invoke(argvResult, { invocation, toolArgs: args });
+  if (invokeResult.kind === "help") {
+    return {
+      ok: false,
+      kind: "help",
+      message: invokeResult.errorMsg ?? "Help is not available via tool calls.",
+      exitCode: invokeResult.exitCode,
+      stdout: invokeResult.stdout,
+      stderr: invokeResult.stderr,
+      invokeResult,
+    };
+  }
+
+  if (invokeResult.kind === "ok" && invokeResult.exitCode === 0 && invokeResult.response) {
+    const mcpResult = buildToolCallSuccessFromResponse(invokeResult.response);
+    return {
+      ok: true,
+      response: invokeResult.response,
+      mcpResult,
+    };
+  }
+
+  if (invokeResult.kind === "ok" && invokeResult.exitCode === 0) {
+    return {
+      ok: false,
+      kind: "invoke",
+      message: "Handler did not call ctx.respond() or return a value",
+      exitCode: 1,
+      stdout: invokeResult.stdout,
+      stderr: invokeResult.stderr,
+      invokeResult,
+    };
+  }
+
+  const message = invokeResult.errorMsg ?? (invokeResult.stderr.trim() || `Exit code ${invokeResult.exitCode}`);
+  return {
+    ok: false,
+    kind: "invoke",
+    message,
+    exitCode: invokeResult.exitCode,
+    stdout: invokeResult.stdout,
+    stderr: invokeResult.stderr,
+    invokeResult,
+  };
+}
+
+/** Maps a headless success result to an HTTP Response. */
+export function headlessSuccessToHttpResponse(
+  result: HeadlessToolCallSuccess,
+  leafApiResponse?: import("../types.ts").CliApiResponseConfig,
+): Response {
+  return apiSuccessResponse(result.response, leafApiResponse);
+}
+
+/** Maps a headless failure result to a JSON HTTP error Response. */
+export function headlessFailureToHttpResponse(result: HeadlessToolCallFailure): Response {
+  const status = result.kind === "argv" || result.kind === "help" ? 400 : 500;
+  return apiErrorResponse(status, {
+    error: result.message,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  });
+}

package/src/headless.test.ts

@@ -12,14 +12,16 @@ import {
   wantsExplicitJson,
 } from "./headless.ts";
 
-test("wantsExplicitJson includes MCP invocation", () => {
+test("wantsExplicitJson includes MCP and API invocation", () => {
   expect(wantsExplicitJson({ invocation: "cli" }, false)).toBe(false);
   expect(wantsExplicitJson({ invocation: "mcp" }, false)).toBe(true);
+  expect(wantsExplicitJson({ invocation: "api" }, false)).toBe(true);
   expect(wantsExplicitJson({ invocation: "cli" }, true)).toBe(true);
 });
 
-test("shouldRunHeadless is true for MCP and json", () => {
+test("shouldRunHeadless is true for MCP, API, and json", () => {
   expect(shouldRunHeadless({ invocation: "mcp" }, false)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "api" }, false)).toBe(true);
   expect(shouldRunHeadless({ invocation: "cli" }, true)).toBe(true);
   expect(shouldRunHeadless({ invocation: "cli" }, false, true)).toBe(true);
   expect(shouldRunHeadless({ invocation: "cli" }, false, false, false)).toBe(true);

package/src/headless.ts

@@ -4,9 +4,14 @@ import { isInteractiveTty } from "./utils.ts";
 /** 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 the handler was invoked via MCP or HTTP API. */
+function isToolInvocation(invocation: CliContext["invocation"]): boolean {
+  return invocation === "mcp" || invocation === "api";
+}
+
+/** True when `--json` was passed or the handler was invoked headlessly over MCP/HTTP. */
 export function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean {
-  return hasJsonFlag || ctx.invocation === "mcp";
+  return hasJsonFlag || isToolInvocation(ctx.invocation);
 }
 
 /**
@@ -19,7 +24,7 @@ export function shouldRunHeadless(
   hasDryRunFlag = false,
   interactive: boolean = isInteractiveTty,
 ): boolean {
-  if (ctx.invocation === "mcp") return true;
+  if (isToolInvocation(ctx.invocation)) return true;
   if (hasJsonFlag || hasDryRunFlag) return true;
   return !interactive;
 }
@@ -35,7 +40,7 @@ export function shouldRunHeadlessWithPositionals(
   hasDryRunFlag = false,
   interactive: boolean = isInteractiveTty,
 ): boolean {
-  if (ctx.invocation === "mcp") return true;
+  if (isToolInvocation(ctx.invocation)) return true;
   if (hasJsonFlag || hasDryRunFlag) return true;
   return !interactive && positionals.length > 0;
 }
@@ -49,7 +54,7 @@ export function shouldRunHeadlessWithYes(
   opts: { yes: boolean; hasRequiredArgs: boolean; dryRun?: boolean },
   interactive: boolean = isInteractiveTty,
 ): boolean {
-  if (ctx.invocation === "mcp") {
+  if (isToolInvocation(ctx.invocation)) {
     return opts.hasRequiredArgs && (opts.yes || Boolean(opts.dryRun));
   }
   if (opts.dryRun && opts.hasRequiredArgs) return true;

package/src/index.ts

@@ -7,6 +7,7 @@ It gives consumers one stable import path without forcing them to know the inter
 module layout.
 */
 
+export { generateOpenApi, openApiJson } from "./api/openapi.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./cli.ts";
 export { cliErrWithHelp } from "./cli-errors.ts";
 export { displayAppConfigPath, resolveAppConfigPath } from "./config/file.ts";
@@ -30,6 +31,8 @@ export {
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
 export type {
+  CliApiResponseConfig,
+  CliApiServerConfig,
   CliAppConfig,
   CliAppConfigEntry,
   CliAppConfigResolveContext,
@@ -47,6 +50,8 @@ export type {
   CliOption,
   CliPositional,
   CliProgram,
+  CliRespondBody,
+  CliRespondOptions,
   InstallAgentIntegration,
   InstallTargetSpec,
   ResolvedInstallTarget,