argsbarg 6.1.2 → 6.1.3

package/src/docs/mcp-resources.test.ts

@@ -3,7 +3,7 @@ Tests for docs/mcp-resources module behavior.
 */
 
 import { expect, test } from "bun:test";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
 import {
   defaultDocsTopicResourceUri,
   docsMcpResources,
@@ -21,14 +21,13 @@ function fixture(opts?: { docs?: boolean; mcp?: boolean }): CliProgram {
     ...(docs
       ? {
           docs: {
-            enabled: true,
             topics: {
               readme: { text: "# Readme\n", description: "User guide." },
               arch: { text: "# Arch\n" },
             },
           },
         }
-      : {}),
+      : { docs: { enabled: false } }),
     ...(mcp ? { mcpServer: { enabled: true } } : {}),
     handler: () => {},
   };

package/src/docs/mcp-resources.ts

@@ -2,8 +2,8 @@
 Auto MCP resources for user docs.topics when docs and MCP are both enabled.
 */
 
-import type { CliProgram } from "../types.ts";
-import { docsEnabled, docsTopicDescription, docsTopicText, docsUserTopicKeys } from "./resolve.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { docsEnabled, docsTopicDescription, docsTopicText, docsUserTopicKeys, resolveDocsConfig } from "./resolve.ts";
 
 /** Default URI pattern for a docs topic MCP resource (`<mcpId>://docs/<topicKey>`). */
 export function defaultDocsTopicResourceUri(mcpId: string, topicKey: string): string {
@@ -31,12 +31,10 @@ export function docsMcpResources(program: CliProgram): {
   if (!docsEnabled(program) || program.mcpServer?.enabled !== true) {
     return [];
   }
-  const docs = program.docs;
-  if (!docs) {
-    return [];
-  }
+  const docs = resolveDocsConfig(program);
+  const topics = docs.topics ?? {};
   return docsUserTopicKeys(docs).map((key) => {
-    const topic = docs.topics[key];
+    const topic = topics[key];
     if (!topic) {
       throw new Error(`docs topic missing: ${key}`);
     }
@@ -58,9 +56,6 @@ export function reservedDocsTopicResourceUris(program: CliProgram): string[] {
   if (!docsEnabled(program) || program.mcpServer?.enabled !== true) {
     return [];
   }
-  const docs = program.docs;
-  if (!docs) {
-    return [];
-  }
+  const docs = resolveDocsConfig(program);
   return docsUserTopicKeys(docs).map((key) => resolveDocsTopicResourceUri(program, key));
 }

package/src/docs/resolve.ts

@@ -1,13 +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 { cliSchemaJson } from "~/core/schema.ts";
+import type { CliDocsConfig, CliProgram } from "~/core/types.ts";
+import { openApiJson } from "~/http/openapi.ts";
+import { generateSkillBundle } from "~/skill/generate.ts";
+import { generateCliGuide } from "./cli-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 = ["http", "mcp", "all", "cli-schema", "api", "skill", "openapi"] as const;
+export const DOCS_BUILTIN_TOPIC_KEYS = ["http", "mcp", "all", "cli-schema", "cli", "skill", "openapi"] as const;
 
 export type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
 
@@ -16,28 +16,20 @@ export const DOCS_ROUTER_DESCRIPTION = "Print bundled CLI documentation.";
 
 /** Returns whether bundled docs are enabled on the program root. */
 export function docsEnabled(program: CliProgram): boolean {
-  return program.docs?.enabled === true;
+  return program.docs?.enabled !== false;
 }
 
-/** User topic keys in declaration order. */
-export function docsUserTopicKeys(docs: CliDocsConfig): string[] {
-  return Object.keys(docs.topics);
+/** Normalized docs config with defaults applied. */
+export function resolveDocsConfig(program: CliProgram): CliDocsConfig {
+  return {
+    description: program.docs?.description,
+    topics: program.docs?.topics ?? {},
+  };
 }
 
-/** Subcommand used when argv is bare `myapp docs`. */
-export function docsEffectiveDefaultTopic(docs: CliDocsConfig): string {
-  if (docs.defaultTopic !== undefined) {
-    return docs.defaultTopic;
-  }
-  const keys = docsUserTopicKeys(docs);
-  if (keys.length === 0) {
-    throw new Error("docs.topics must be non-empty");
-  }
-  const first = keys[0];
-  if (first === undefined) {
-    throw new Error("docs.topics must be non-empty");
-  }
-  return first;
+/** User topic keys in declaration order. */
+export function docsUserTopicKeys(docs: CliDocsConfig): string[] {
+  return Object.keys(docs.topics ?? {});
 }
 
 /** Whether MCP auto-guide topic is included. */
@@ -47,7 +39,7 @@ export function docsIncludesMcpTopic(program: CliProgram): boolean {
 
 /** Whether HTTP auto-guide topic is included. */
 export function docsIncludesHttpTopic(program: CliProgram): boolean {
-  return docsEnabled(program) && program.apiServer?.enabled === true;
+  return docsEnabled(program) && program.httpServer?.enabled === true;
 }
 
 /** Whether OpenAPI export topic is included. */
@@ -69,8 +61,7 @@ export function docsTopicDescription(key: string, custom?: string): string {
 
 /** Markdown body for one docs topic key. */
 export function docsTopicText(program: CliProgram, topic: string): string {
-  const docs = program.docs;
-  if (!docs) {
+  if (!docsEnabled(program)) {
     throw new Error("docs not enabled");
   }
   if (topic === "mcp") {
@@ -85,7 +76,8 @@ export function docsTopicText(program: CliProgram, topic: string): string {
     }
     return generateHttpGuide(program);
   }
-  const entry = docs.topics[topic];
+  const topics = program.docs?.topics ?? {};
+  const entry = topics[topic];
   if (!entry) {
     throw new Error(`Unknown docs topic '${topic}'.`);
   }
@@ -103,8 +95,8 @@ export function docsTopicContent(program: CliProgram, topic: string): string {
     }
     return openApiJson(program);
   }
-  if (topic === "api") {
-    return generateApiGuide(program);
+  if (topic === "cli") {
+    return generateCliGuide(program);
   }
   if (topic === "skill") {
     return `${generateSkillBundle(program, "cursor").skillMd}\n`;

package/src/docs/save.ts

@@ -1,14 +1,14 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { generatedFileHtmlComment, insertGeneratedHint } from "~/skill/hint.ts";
 import { docsTopicContent } from "./resolve.ts";
 
 /** Relative output directory for `docs --save`. */
 export const DOCS_SAVE_DIR = "docs";
 
 /** Builtin docs topics generated by argsbarg (not consumer `docs.topics`). */
-export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "api", "skill"] as const;
+export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "skill"] as const;
 
 /** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
 export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {

package/src/exports/cli.ts

@@ -0,0 +1,47 @@
+/*
+Public CLI runtime export (`argsbarg/cli`).
+*/
+
+export { displayAppConfigPath, resolveAppConfigPath } from "~/config/file.ts";
+export type { CliLeafInputs } from "~/core/context.ts";
+export { CliContext } from "~/core/context.ts";
+export {
+  parseCommaList,
+  parseDate,
+  parseDateTime,
+  parseDurationMs,
+} from "~/core/formats.ts";
+export type {
+  CliAppConfig,
+  CliAppConfigEntry,
+  CliConfigureConfig,
+  CliConfigureTargets,
+  CliDocsConfig,
+  CliDocsTopic,
+  CliFallbackMode,
+  CliHandler,
+  CliHttpResponseConfig,
+  CliHttpServerConfig,
+  CliInvocation,
+  CliLeafKind,
+  CliMcpResource,
+  CliMcpServerConfig,
+  CliMcpToolConfig,
+  CliOption,
+  CliPositional,
+  CliProgram,
+  CliRespondBody,
+  CliRespondOptions,
+  InstallAgentIntegration,
+  InstallTargetSpec,
+  ResolvedInstallTarget,
+} from "~/core/types.ts";
+export {
+  CliOptionKind,
+  CliSchemaValidationError,
+  CliValueFormat,
+  isJsonLeaf,
+} from "~/core/types.ts";
+export { Cli, type CliInvokeKind, type CliInvokeResult } from "~/runtime/cli.ts";
+export { cliErrWithHelp } from "~/runtime/cli-errors.ts";
+export { isInteractiveTty } from "~/utils.ts";

package/src/exports/headless.ts

@@ -0,0 +1,13 @@
+/*
+Headless routing helpers (`argsbarg/headless`).
+*/
+
+export type { HeadlessContext } from "~/headless/routing.ts";
+export {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsExplicitJson,
+} from "~/headless/routing.ts";

package/src/exports/http.ts

@@ -0,0 +1,6 @@
+/*
+HTTP/OpenAPI export (`argsbarg/http`).
+*/
+
+export { generateOpenApi, openApiJson } from "~/http/openapi.ts";
+export { handleApiRequest, httpServeHttp, resolveHttpListenAddress } from "~/http/server.ts";

package/src/exports/mcp.ts

@@ -0,0 +1,6 @@
+/*
+MCP bundle export (`argsbarg/mcp`). @experimental
+*/
+
+export type { McpBundlePaths, PackMcpBundleOpts } from "~/mcp/bundle.ts";
+export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "~/mcp/bundle.ts";

package/src/{headless.test.ts → headless/routing.test.ts}

@@ -10,18 +10,18 @@ import {
   shouldRunHeadlessWithPositionals,
   shouldRunHeadlessWithYes,
   wantsExplicitJson,
-} from "./headless.ts";
+} from "./routing.ts";
 
 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: "http" }, false)).toBe(true);
   expect(wantsExplicitJson({ invocation: "cli" }, true)).toBe(true);
 });
 
 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: "http" }, 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 → headless/routing.ts}

@@ -1,12 +1,12 @@
-import type { CliContext } from "./context.ts";
-import { isInteractiveTty } from "./utils.ts";
+import type { CliContext } from "~/core/context.ts";
+import { isInteractiveTty } from "~/utils.ts";
 
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 
 /** True when the handler was invoked via MCP or HTTP API. */
 function isToolInvocation(invocation: CliContext["invocation"]): boolean {
-  return invocation === "mcp" || invocation === "api";
+  return invocation === "mcp" || invocation === "http";
 }
 
 /** True when `--json` was passed or the handler was invoked headlessly over MCP/HTTP. */

package/src/headless/tool-call.ts

@@ -2,13 +2,16 @@
 Shared headless tool dispatch for MCP and HTTP: config bootstrap, argv conversion, and invoke.
 */
 
-import { apiErrorResponse, apiSuccessResponse, firstErrorLine } 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";
+import { bootstrapAppConfig } from "~/config/bootstrap.ts";
+import { formatMcpMissingConfigMessage, missingRequiredConfig } from "~/config/resolve.ts";
+import type { CliInvocation, CliProgram, InvokeFailureKind } from "~/core/types.ts";
+import { failureKindHttpStatus } from "~/hooks/run.ts";
+import { apiErrorResponse, apiSuccessResponse, firstErrorLine } from "~/http/result.ts";
+import { type HttpRouteDef, httpRequestToArgv } from "~/http/routes.ts";
+import { obscureUnexpectedClientMessage } from "~/log/emitter.ts";
+import { buildToolCallSuccessFromResponse } from "~/mcp/result.ts";
+import { collectMcpTools, type McpToolDef, mcpToolCallToArgv } from "~/mcp/tools.ts";
+import type { Cli, CliInvokeResult } from "~/runtime/cli.ts";
 
 /** Outcome of resolving a tool name against the program schema. */
 export type ToolLookupResult =
@@ -31,20 +34,16 @@ export interface HeadlessToolCallFailure {
   exitCode: number;
   stdout: string;
   stderr: string;
+  failureKind?: InvokeFailureKind;
   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 {
+/** Finds an exposed MCP tool by name. */
+export function lookupHeadlessTool(program: CliProgram, toolName: string): ToolLookupResult {
   const tools = collectMcpTools(program);
-  const tool =
-    invocation === "api" ? tools.find((t) => t.apiName === toolName) : tools.find((t) => t.name === toolName);
+  const tool = tools.find((t) => t.name === toolName);
   if (!tool) {
     return { ok: false, kind: "unknown", message: `Unknown tool: ${toolName}` };
   }
@@ -60,6 +59,33 @@ export function lookupHeadlessTool(
   return { ok: true, tool };
 }
 
+function invokeFailure(result: CliInvokeResult): HeadlessToolCallFailure {
+  const message = result.errorMsg ?? (result.stderr.trim() || `Exit code ${result.exitCode}`);
+  return {
+    ok: false,
+    kind: result.kind === "help" ? "help" : "invoke",
+    message,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    failureKind: result.failureKind,
+    invokeResult: result,
+  };
+}
+
+function noResponseFailure(result: CliInvokeResult): HeadlessToolCallFailure {
+  return {
+    ok: false,
+    kind: "invoke",
+    message: "Handler did not call ctx.respond() or return a value",
+    exitCode: 1,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    failureKind: "unexpected",
+    invokeResult: result,
+  };
+}
+
 /**
  * Converts flat tool arguments to argv and invokes the leaf handler headlessly.
  */
@@ -68,6 +94,7 @@ export async function executeHeadlessToolCall(
   tool: McpToolDef,
   args: Record<string, unknown>,
   invocation: CliInvocation,
+  mcp?: { rpcMethod: string; toolName?: string; requestId: string },
 ): Promise<HeadlessToolCallResult> {
   const argvResult = mcpToolCallToArgv(cli.program, tool, args);
   if ("error" in argvResult) {
@@ -78,20 +105,13 @@ export async function executeHeadlessToolCall(
       exitCode: 1,
       stdout: "",
       stderr: "",
+      failureKind: "validation",
     };
   }
 
-  const invokeResult = await cli.invoke(argvResult, { invocation, toolArgs: args });
+  const invokeResult = await cli.invoke(argvResult, { invocation, toolArgs: args, mcp });
   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,
-    };
+    return invokeFailure(invokeResult);
   }
 
   if (invokeResult.kind === "ok" && invokeResult.exitCode === 0 && invokeResult.response) {
@@ -104,46 +124,81 @@ export async function executeHeadlessToolCall(
   }
 
   if (invokeResult.kind === "ok" && invokeResult.exitCode === 0) {
+    return noResponseFailure(invokeResult);
+  }
+
+  return invokeFailure(invokeResult);
+}
+
+/**
+ * Invokes a matched HTTP REST route headlessly (query + body → argv → invoke).
+ */
+export async function executeHttpRouteCall(
+  cli: Cli,
+  route: HttpRouteDef,
+  pathParams: Record<string, string>,
+  query: Record<string, string>,
+  body: Record<string, unknown>,
+  http?: { request: Request; clientIp: string; requestId: string },
+): Promise<HeadlessToolCallResult> {
+  const argvResult = httpRequestToArgv(cli.program, route, pathParams, query, body);
+  if ("error" in argvResult) {
     return {
       ok: false,
-      kind: "invoke",
-      message: "Handler did not call ctx.respond() or return a value",
+      kind: "argv",
+      message: argvResult.error,
       exitCode: 1,
-      stdout: invokeResult.stdout,
-      stderr: invokeResult.stderr,
-      invokeResult,
+      stdout: "",
+      stderr: "",
+      failureKind: "validation",
     };
   }
 
-  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,
-  };
+  const toolArgs = { ...body, ...query, ...pathParams };
+  const invokeResult = await cli.invoke(argvResult, { invocation: "http", toolArgs, http });
+  if (invokeResult.kind === "help") {
+    return invokeFailure(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 noResponseFailure(invokeResult);
+  }
+
+  return invokeFailure(invokeResult);
 }
 
 /** Maps a headless success result to an HTTP Response. */
 export function headlessSuccessToHttpResponse(
   result: HeadlessToolCallSuccess,
-  leafApiResponse?: import("../types.ts").CliApiResponseConfig,
+  leafApiResponse?: import("~/core/types.ts").CliHttpResponseConfig,
+  defaultStatus?: number,
 ): Response {
-  return apiSuccessResponse(result.response, leafApiResponse);
+  return apiSuccessResponse(result.response, leafApiResponse, defaultStatus);
 }
 
 /** Maps a headless failure result to a JSON HTTP error Response. */
-export function headlessFailureToHttpResponse(result: HeadlessToolCallFailure): Response {
+export function headlessFailureToHttpResponse(result: HeadlessToolCallFailure, obscureUnexpected = false): Response {
   const status = resolveHttpErrorStatus(result);
-  return apiErrorResponse(status, {
-    error: firstErrorLine(result.message),
-  });
+  let message = firstErrorLine(result.message);
+  if (obscureUnexpected && result.failureKind === "unexpected") {
+    message = obscureUnexpectedClientMessage();
+  }
+  return apiErrorResponse(status, { error: message });
 }
 
 function resolveHttpErrorStatus(result: HeadlessToolCallFailure): number {
+  if (result.failureKind) {
+    return failureKindHttpStatus(result.failureKind);
+  }
   if (result.kind === "argv" || result.kind === "help") {
     return 400;
   }
@@ -155,3 +210,16 @@ function resolveHttpErrorStatus(result: HeadlessToolCallFailure): number {
   }
   return 500;
 }
+
+/** Maps invoke failure kind to MCP tools/call error text (respects obscureUnexpected). */
+export function headlessFailureMcpMessage(result: HeadlessToolCallFailure, obscureUnexpected = false): string {
+  if (obscureUnexpected && result.failureKind === "unexpected") {
+    return obscureUnexpectedClientMessage();
+  }
+  return firstErrorLine(result.message);
+}
+
+/** Missing-config lookup failures as MCP/HTTP pre-invoke errors. */
+export function missingConfigFailureKind(): InvokeFailureKind {
+  return "missing_config";
+}