argsbarg 5.1.16 → 6.0.1

package/src/builtins/dispatch.ts

@@ -7,6 +7,7 @@ import type { ParseResult } from "../parse.ts";
 import { ParseKind } from "../parse.ts";
 import type { CliNode, CliProgram, CliRouter } from "../types.ts";
 import { isCliLeaf } from "../types.ts";
+import { cliBuiltinApiCommand } from "./api.ts";
 import { completionBashScript } from "./completion-bash.ts";
 import { completionFishScript } from "./completion-fish.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
@@ -68,6 +69,20 @@ export async function dispatchBuiltin(program: CliProgram, pr: ParseResult, opts
     process.exit(0);
   }
 
+  if (pr.path[0] === "api") {
+    if (!caps.api) {
+      process.stderr.write(capabilityDeniedMessage("api"));
+      process.exit(1);
+    }
+    const sub = pr.path[1];
+    if (pr.path.length === 1 || sub === "serve") {
+      await new Cli(program).serveApi();
+      process.exit(0);
+    }
+    process.stderr.write(`Unknown subcommand: api ${pr.path.slice(1).join(" ")}\n`);
+    process.exit(1);
+  }
+
   if (pr.path[0] === "mcp") {
     if (!caps.mcp) {
       process.stderr.write(capabilityDeniedMessage("mcp"));
@@ -142,6 +157,17 @@ export function builtinInterceptRoot(
     };
   }
 
+  if (first === "api" && caps.api) {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinApiCommand(program)],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
   if (first === "mcp" && caps.mcp) {
     return {
       parseRoot: {

package/src/builtins/registry.ts

@@ -1,6 +1,7 @@
 import type { CliCapabilities } from "../capabilities.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import type { CliNode, CliProgram } from "../types.ts";
+import { cliBuiltinApiCommand } from "./api.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinConfigureCommand } from "./configure.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
@@ -32,5 +33,8 @@ export function resolveBuiltins(program: CliProgram, caps: CliCapabilities): Cli
   if (caps.mcp) {
     pushBuiltin(builtins, program, (p) => cliBuiltinMcpCommand(p));
   }
+  if (caps.api) {
+    pushBuiltin(builtins, program, (p) => cliBuiltinApiCommand(p));
+  }
   return builtins;
 }

package/src/capabilities.ts

@@ -8,6 +8,7 @@ import type { CliProgram } from "./types.ts";
 
 /** Platform builtins derived from program config and runtime. */
 export interface CliCapabilities {
+  api: boolean;
   completion: boolean;
   mcp: boolean;
   configure: boolean;
@@ -19,6 +20,7 @@ export interface CliCapabilities {
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
   const configure = program.configure?.enabled !== false;
   return {
+    api: program.apiServer?.enabled === true,
     completion: program.completion?.enabled !== false,
     mcp: program.mcpServer?.enabled === true,
     configure,
@@ -42,6 +44,9 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   if (caps.mcp) {
     names.push("mcp");
   }
+  if (caps.api) {
+    names.push("api");
+  }
   return names;
 }
 
@@ -60,13 +65,15 @@ export function skipsRequiredAppConfigExit(path: string[], caps: CliCapabilities
   return false;
 }
 
-export type CapabilityFeature = "mcp" | "configure" | "docs" | "completion";
+export type CapabilityFeature = "api" | "mcp" | "configure" | "docs" | "completion";
 
 /** Stderr message when a disabled built-in is invoked from the CLI. */
 export function capabilityDeniedMessage(feature: CapabilityFeature): string {
   switch (feature) {
     case "completion":
       return "Shell completion is not available for this app.\n";
+    case "api":
+      return "HTTP API is not available for this app.\n";
     case "mcp":
       return "MCP is not available for this app.\n";
     case "configure":
@@ -90,6 +97,10 @@ export function assertBuiltinAllowed(argv: string[], caps: CliCapabilities): voi
     process.stderr.write(capabilityDeniedMessage("mcp"));
     process.exit(1);
   }
+  if (first === "api" && !caps.api) {
+    process.stderr.write(capabilityDeniedMessage("api"));
+    process.exit(1);
+  }
   if (first === "configure" && !caps.configure) {
     process.stderr.write(capabilityDeniedMessage("configure"));
     process.exit(1);

package/src/cli-errors.ts

@@ -7,6 +7,9 @@ import type { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
 
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
+  if (ctx.invocation === "api" || ctx.invocation === "mcp") {
+    throw new Error(msg);
+  }
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
   process.stderr.write(`${line}\n`);

package/src/cli-tool/full-example-capabilities.test.ts

@@ -26,6 +26,7 @@ const sinkProgram = {
     topics: { readme: { text: "# readme\n" } },
   },
   mcpServer: { enabled: true },
+  apiServer: { enabled: true },
   configure: {},
   commands: [
     {
@@ -54,6 +55,7 @@ describe("full-example template", () => {
   /** Tests that program source enables every builtin flag. */
   test("program source enables every builtin flag", () => {
     expect(programSource).toContain("mcpServer: {");
+    expect(programSource).toContain("apiServer: {");
     expect(programSource).toContain("enabled: true");
     expect(programSource).toContain("docs:");
     expect(programSource).toContain("appConfig:");
@@ -66,6 +68,7 @@ describe("full-example template", () => {
 
   test("resolveCapabilities matches full sink shape", () => {
     expect(resolveCapabilities(sinkProgram)).toEqual({
+      api: true,
       completion: true,
       mcp: true,
       configure: true,

package/src/cli.ts

@@ -3,6 +3,7 @@ Runtime entry point: validate program, cache derived state, run / invoke / MCP s
 */
 
 import { format } from "node:util";
+import { apiServeHttp } from "./api/server.ts";
 import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
 import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
 import {
@@ -21,7 +22,7 @@ import { bootstrapMcpEnv } from "./mcp/env.ts";
 import { mcpServeStdioLoop } from "./mcp/server.ts";
 import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
 import { type CliSchemaExport, cliSchemaExport } from "./schema.ts";
-import type { CliHandler, CliLeaf, CliNode, CliProgram, CliRouter } from "./types.ts";
+import type { CliHandler, CliInvocation, CliLeaf, CliNode, CliProgram, CliRespondOptions, CliRouter } from "./types.ts";
 import { isCliLeaf, isCliRouter } from "./types.ts";
 import { cliValidateProgram } from "./validate.ts";
 
@@ -35,6 +36,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;
 }
 
 class CliInvokeExit extends Error {
@@ -123,7 +126,10 @@ export class Cli {
 
     const ctx = new CliContext(this.program.key, pr.path, pr.args, pr.opts, this.program, "cli", snapshot);
     try {
-      await Promise.resolve(leaf.handler(ctx));
+      const handlerResult = await Promise.resolve(leaf.handler(ctx));
+      if (handlerResult !== undefined && ctx.getResponse() === undefined) {
+        ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
+      }
       process.exit(0);
     } catch (err) {
       if (err instanceof Error) {
@@ -133,7 +139,11 @@ export class Cli {
     }
   }
 
-  async invoke(argv: string[]): Promise<CliInvokeResult> {
+  async invoke(
+    argv: string[],
+    opts?: { invocation?: CliInvocation; toolArgs?: Record<string, unknown> },
+  ): Promise<CliInvokeResult> {
+    const invocation = opts?.invocation ?? "mcp";
     const prep = this.prepareDispatch(argv, { presentationFallback: true });
     if ("error" in prep) {
       if (prep.error.kind === ParseKind.Help) {
@@ -142,7 +152,7 @@ export class Cli {
           exitCode: 1,
           stdout: "",
           stderr: "",
-          errorMsg: "Help is not available via MCP tool calls.",
+          errorMsg: "Help is not available via tool calls.",
         };
       }
       return {
@@ -160,7 +170,16 @@ export class Cli {
       exitOnMissing: false,
     });
 
-    const ctx = new CliContext(this.program.key, pr.path, pr.args, pr.opts, this.program, "mcp", snapshot);
+    const ctx = new CliContext(
+      this.program.key,
+      pr.path,
+      pr.args,
+      pr.opts,
+      this.program,
+      invocation,
+      snapshot,
+      opts?.toolArgs,
+    );
 
     let stdout = "";
     let stderr = "";
@@ -213,12 +232,30 @@ export class Cli {
         });
       }
 
-      await Promise.resolve(leaf.handler(ctx));
-      return { kind: "ok", exitCode: 0, stdout, stderr };
+      const handlerResult = await Promise.resolve(leaf.handler(ctx));
+      if (handlerResult !== undefined && ctx.getResponse() === undefined) {
+        ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
+      }
+
+      const response = ctx.getResponse();
+      return {
+        kind: "ok",
+        exitCode: 0,
+        stdout,
+        stderr,
+        ...(response ? { response } : {}),
+      };
     } catch (err) {
       if (err instanceof CliInvokeExit) {
         if (err.code === 0) {
-          return { kind: "ok", exitCode: 0, stdout, stderr };
+          const response = ctx.getResponse();
+          return {
+            kind: "ok",
+            exitCode: 0,
+            stdout,
+            stderr,
+            ...(response ? { response } : {}),
+          };
         }
         const msg = stderr.trim() || `Exit code ${err.code}`;
         return { kind: "error", exitCode: err.code, stdout, stderr, errorMsg: msg };
@@ -268,6 +305,21 @@ export class Cli {
     }
   }
 
+  async serveApi(): Promise<never> {
+    try {
+      bootstrapAppConfig(this.program, { validateFile: false });
+      await apiServeHttp(this);
+      process.exit(0);
+    } catch (err) {
+      if (err instanceof Error) {
+        process.stderr.write(`${err.message}\n`);
+      } else {
+        process.stderr.write("HTTP API server error.\n");
+      }
+      process.exit(1);
+    }
+  }
+
   private prepareDispatch(
     argv: string[],
     opts?: { presentationFallback?: boolean },

package/src/config.integration.test.ts

@@ -75,9 +75,18 @@ test("MCP program.appConfig succeeds when env present", async () => {
     ],
     { script: "examples/mcp-test.ts", env: { ARGS_TEST_SECRET: "sekrit" } },
   );
-  const res = responses.get(14) as { result: { isError: boolean; content: { text: string }[] } };
+  const res = responses.get(14) as {
+    result: {
+      isError: boolean;
+      structuredContent?: { content: string; contentType: string };
+      content: { text: string }[];
+    };
+  };
   expect(res.result.isError).toBe(false);
-  expect(res.result.content[0]?.text.trim()).toBe("sekrit");
+  expect(res.result.structuredContent).toEqual({
+    content: "sekrit",
+    contentType: "text/plain; charset=utf-8",
+  });
 });
 
 /** MCP config file loads and exports vars for tool handlers. */
@@ -100,9 +109,18 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
       env: { HOME: dir, ARGS_TEST_SECRET: "present" },
     },
   );
-  const res = responses.get(15) as { result: { isError: boolean; content: { text: string }[] } };
+  const res = responses.get(15) as {
+    result: {
+      isError: boolean;
+      structuredContent?: { content: string; contentType: string };
+      content: { text: string }[];
+    };
+  };
   expect(res.result.isError).toBe(false);
-  expect(res.result.content[0]?.text.trim()).toBe("present");
+  expect(res.result.structuredContent).toEqual({
+    content: "present",
+    contentType: "text/plain; charset=utf-8",
+  });
   rmSync(dir, { recursive: true, force: true });
 });
 

package/src/context.ts

@@ -11,7 +11,8 @@ import type { AnyAppConfigSnapshot } from "./config/context.ts";
 import { EmptyAppConfigSnapshot } from "./config/context.ts";
 import { parseCommaList, parseDate, parseDateTime, parseDurationMs } from "./formats.ts";
 import { collectOptionDefs } from "./parse.ts";
-import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram } from "./types.ts";
+import { normalizeRespondOptions, writeRespondBodyToStdout } from "./respond.ts";
+import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram, CliRespondOptions } from "./types.ts";
 import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
@@ -29,6 +30,10 @@ export 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?: CliRespondOptions;
 
   /** Captures the program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
@@ -39,6 +44,7 @@ export class CliContext {
     program: CliProgram,
     invocation: CliInvocation = "cli",
     appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(program),
+    toolArgs?: Record<string, unknown>,
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
@@ -47,6 +53,28 @@ export class CliContext {
     this.program = program;
     this.invocation = invocation;
     this.appConfig = appConfig;
+    this.toolArgs = toolArgs;
+  }
+
+  /**
+   * 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 {
+    if (this.response !== undefined) {
+      throw new Error("ctx.respond() was already called for this invocation");
+    }
+    const normalized = normalizeRespondOptions(opts);
+    if (this.invocation === "cli") {
+      writeRespondBodyToStdout(normalized.body);
+      return;
+    }
+    this.response = normalized;
+  }
+
+  /** Returns the respond payload set by {@link respond}, if any. */
+  getResponse(): CliRespondOptions | undefined {
+    return this.response;
   }
 
   /** Returns whether a presence flag was set (including implicit "1" for boolean options). */

package/src/docs/api-guide.ts

@@ -152,7 +152,7 @@ export function generateApiGuideBody(program: CliProgram): string {
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
-/** Generates markdown API reference from the same export as `docs schema`. */
+/** Generates markdown API reference from the same export as `docs cli-schema`. */
 export function generateApiGuide(program: CliProgram): string {
   const schema = cliSchemaExport(program);
   const lines: string[] = [
@@ -160,7 +160,7 @@ export function generateApiGuide(program: CliProgram): string {
     "",
     schema.description,
     "",
-    `Machine-readable export: \`${program.key} docs schema\``,
+    `Machine-readable export: \`${program.key} docs cli-schema\``,
     "",
   ];
 

package/src/docs/builtin.ts

@@ -12,7 +12,9 @@ import {
   DOCS_ROUTER_DESCRIPTION,
   docsEffectiveDefaultTopic,
   docsEnabled,
+  docsIncludesHttpTopic,
   docsIncludesMcpTopic,
+  docsIncludesOpenApiTopic,
   docsTopicDescription,
   docsUserTopicKeys,
   printDocsTopic,
@@ -70,8 +72,16 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
     leaves.push(docsLeaf(program, "mcp", "Print MCP server setup and tool guidance."));
   }
 
+  if (docsIncludesHttpTopic(program)) {
+    leaves.push(docsLeaf(program, "http", "Print HTTP API setup and tool guidance."));
+  }
+
+  if (docsIncludesOpenApiTopic(program)) {
+    leaves.push(docsLeaf(program, "openapi", "Print the HTTP OpenAPI 3.1 document as JSON."));
+  }
+
   leaves.push(
-    docsLeaf(program, "schema", "Print the full command tree as JSON."),
+    docsLeaf(program, "cli-schema", "Print the full CLI command tree as JSON."),
     docsLeaf(program, "api", "Print the full command reference as markdown."),
     docsLeaf(program, "skill", docsSkillTopicDescription(program, resolveCapabilities(program))),
   );

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");