argsbarg 5.1.15 → 6.0.0

package/src/builtins/api.ts

@@ -0,0 +1,38 @@
+import { resolveApiListenAddress } from "../api/server.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import { docsEnabled } from "../docs/resolve.ts";
+import { CliFallbackMode, type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
+
+/** Built-in `api` router: bare `myapp api` runs the HTTP server (via hidden `serve` fallback). */
+export function cliBuiltinApiCommand(program: CliProgram): CliRouter {
+  const caps = resolveCapabilities(program);
+  const { hostname, port } = resolveApiListenAddress(program);
+  const lines = [
+    `HTTP tool server on http://${hostname}:${port}.`,
+    "",
+    "Endpoints: GET /health, GET /openapi.json, GET /openapi-browser, POST /tools/:name",
+    "",
+  ];
+  if (caps.configure) {
+    lines.push("Configure app settings:", "", "  {argsbarg:program} configure", "");
+  }
+  if (docsEnabled(program)) {
+    lines.push("Full setup guide: {argsbarg:program} docs http");
+  }
+
+  const serve: CliLeaf = {
+    key: "serve",
+    hidden: true,
+    description: "Run as an HTTP API server for tools.",
+    handler: () => {},
+  };
+
+  return {
+    key: "api",
+    description: "HTTP API server for tools.",
+    notes: lines.join("\n"),
+    fallbackCommand: "serve",
+    fallbackMode: CliFallbackMode.MissingOnly,
+    commands: [serve],
+  };
+}

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-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/bootstrap.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import type { CliAppConfigEntry } from "../types.ts";
+import { shouldWizardPromptConfigKey } from "./bootstrap.ts";
+
+const requiredEntry: CliAppConfigEntry = {
+  description: "API token.",
+  required: true,
+};
+
+describe("shouldWizardPromptConfigKey", () => {
+  test("skips addressed keys by default", () => {
+    expect(
+      shouldWizardPromptConfigKey(
+        "apiToken",
+        { apiToken: "tok", _bindings: { apiToken: "file" } },
+        requiredEntry,
+        { apiToken: "tok" },
+        {},
+      ),
+    ).toBe(false);
+  });
+
+  test("rePromptAll prompts addressed keys", () => {
+    expect(
+      shouldWizardPromptConfigKey(
+        "apiToken",
+        { apiToken: "tok", _bindings: { apiToken: "file" } },
+        requiredEntry,
+        { apiToken: "tok" },
+        { rePromptAll: true },
+      ),
+    ).toBe(true);
+  });
+
+  test("prompts when env binding is broken", () => {
+    expect(
+      shouldWizardPromptConfigKey(
+        "apiToken",
+        { _bindings: { apiToken: "env" } },
+        { ...requiredEntry, env: "API_TOKEN" },
+        {},
+        {},
+      ),
+    ).toBe(true);
+  });
+});

package/src/config/bootstrap.ts

@@ -176,6 +176,8 @@ export interface RunInstallConfigureOpts {
   context?: "standalone" | "after-install";
   /** When false, omit the "Configuration Setup" banner (e.g. inside interactive `configure`). */
   showHeading?: boolean;
+  /** When true, prompt every entry (Enter keeps the current value). */
+  rePromptAll?: boolean;
 }
 
 /** Print the "Configuration Setup" heading before the configure prompts. */
@@ -199,6 +201,24 @@ function bindingsDiffer(a: Record<string, unknown>, b: Record<string, unknown>):
   return JSON.stringify(readBindings(a)) !== JSON.stringify(readBindings(b));
 }
 
+/** Whether the configure wizard should prompt for a config key. */
+export function shouldWizardPromptConfigKey(
+  key: string,
+  fileData: Record<string, unknown>,
+  entry: CliAppConfigEntry,
+  resolved: Record<string, unknown>,
+  opts: Pick<RunInstallConfigureOpts, "rePromptAll">,
+): boolean {
+  const bindings = readBindings(fileData);
+  if (bindings[key] === "env" && !isPresent(resolved[key])) {
+    return true;
+  }
+  if (opts.rePromptAll) {
+    return true;
+  }
+  return !isKeyAddressed(key, fileData, entry);
+}
+
 /** Ask the user for each required setting that is still empty; returns updates to save to the config file. */
 function promptMissingRequired(program: CliProgram): Record<string, unknown> {
   const appConfig = program.appConfig;
@@ -270,10 +290,7 @@ export function runConfigure(
   }
 
   for (const [key, entry] of Object.entries(program.appConfig.entries)) {
-    const bindings = readBindings(existing);
-    if (bindings[key] === "env" && !isPresent(resolved[key])) {
-      // Re-prompt when env binding is broken.
-    } else if (isKeyAddressed(key, existing, entry)) {
+    if (!shouldWizardPromptConfigKey(key, existing, entry, resolved, opts)) {
       continue;
     }
 
@@ -383,7 +400,7 @@ export function ensureAppConfig(program: CliProgram, opts: EnsureAppConfigOpts):
 
   if (opts.interactive && process.stdin.isTTY) {
     if (opts.configure) {
-      runConfigure(program, { context: "standalone" });
+      runConfigure(program, { context: "standalone", rePromptAll: true });
       fileData = readAppConfigFileRaw(resolveAppConfigPath(program));
       resolved = resolveAppConfig(program, fileData, hostEnv);
       exportConfigToEnv(program, resolved, hostEnv);

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/configure/index.ts

@@ -272,7 +272,7 @@ async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): P
     if (target.key === "configure") {
       if (!appConfigHasEntries(root)) continue;
 
-      const result = runConfigure(root, { context: "standalone", showHeading: false });
+      const result = runConfigure(root, { context: "standalone", showHeading: false, rePromptAll: true });
       if (result.changed) {
         installOut(`Wrote config: ${displayAppConfigPath(root)}`, mutationOpts);
         recordArtifactMutation(summary, [displayAppConfigPath(root)], "configured");

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