argsbarg 6.1.2 → 6.1.3

package/src/log/ecs.ts

@@ -0,0 +1,59 @@
+/*
+Elastic Common Schema (ECS) JSON log line formatting for framework observability.
+*/
+
+/** Severity label for ECS `log.level`. */
+export type EcsLogLevel = "debug" | "info" | "warn" | "error";
+
+/** Fields merged into every ECS log line. */
+export interface EcsServiceFields {
+  name: string;
+  version: string;
+}
+
+/** Input for one ECS log event. */
+export interface EcsLogEvent {
+  level: EcsLogLevel;
+  message: string;
+  action?: string;
+  labels?: Record<string, string | number | boolean>;
+  error?: unknown;
+  fields?: Record<string, unknown>;
+}
+
+function errorFields(error: unknown): Record<string, unknown> {
+  if (error instanceof Error) {
+    return {
+      "error.message": error.message,
+      "error.type": error.name,
+      ...(error.stack ? { "error.stack_trace": error.stack } : {}),
+    };
+  }
+  return { "error.message": String(error) };
+}
+
+/** Formats one ECS-compatible JSON log line (newline omitted). */
+export function formatEcsLine(service: EcsServiceFields, event: EcsLogEvent): string {
+  const line: Record<string, unknown> = {
+    "@timestamp": new Date().toISOString(),
+    "log.level": event.level,
+    message: event.message,
+    "service.name": service.name,
+    "service.version": service.version,
+  };
+  if (event.action) {
+    line["event.action"] = event.action;
+  }
+  if (event.labels) {
+    for (const [key, value] of Object.entries(event.labels)) {
+      line[`labels.${key}`] = value;
+    }
+  }
+  if (event.fields) {
+    Object.assign(line, event.fields);
+  }
+  if (event.error !== undefined) {
+    Object.assign(line, errorFields(event.error));
+  }
+  return JSON.stringify(line);
+}

package/src/log/emitter.ts

@@ -0,0 +1,166 @@
+/*
+Framework log emitter: ECS json or human text to stderr with optional file tee.
+*/
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { CliProgram } from "~/core/types.ts";
+import { type EcsLogEvent, type EcsLogLevel, formatEcsLine } from "./ecs.ts";
+
+/** Resolved logging options for a server or invoke session. */
+export interface ResolvedLogConfig {
+  format: "json" | "text";
+  file?: string;
+  access: boolean;
+  errors: boolean;
+  dev: boolean;
+}
+
+/** Options for {@link LogEmitter}. */
+export interface LogEmitterOpts {
+  program: CliProgram;
+  resolved: ResolvedLogConfig;
+}
+
+const OBSCURE_CLIENT_MESSAGE = "An unexpected error occurred.";
+
+/** Fixed client message when `obscureUnexpected` hides internal failures. */
+export function obscureUnexpectedClientMessage(): string {
+  return OBSCURE_CLIENT_MESSAGE;
+}
+
+/** Merges program defaults with CLI flag / serve overrides. */
+export function resolveLogConfig(program: CliProgram, overrides: Partial<ResolvedLogConfig> = {}): ResolvedLogConfig {
+  const log = program.log;
+  return {
+    format: overrides.format ?? log?.format ?? "json",
+    file: overrides.file ?? log?.file,
+    access: overrides.access ?? log?.access ?? true,
+    errors: overrides.errors ?? log?.errors ?? true,
+    dev: overrides.dev ?? false,
+  };
+}
+
+/** Tee framework logs to stderr and an optional append-only file. */
+export class LogEmitter {
+  private readonly service: { name: string; version: string };
+  private readonly resolved: ResolvedLogConfig;
+
+  constructor(opts: LogEmitterOpts) {
+    this.service = { name: opts.program.key, version: opts.program.version };
+    this.resolved = opts.resolved;
+  }
+
+  get config(): ResolvedLogConfig {
+    return this.resolved;
+  }
+
+  /** Emits one log event to stderr (and optional file). */
+  emit(event: EcsLogEvent): void {
+    const line = this.formatLine(event);
+    process.stderr.write(`${line}\n`);
+    this.appendFile(line);
+  }
+
+  /** Human startup line or ECS/json event for lifecycle milestones. */
+  emitLifecycle(message: string, action: string, labels?: Record<string, string | number | boolean>): void {
+    if (this.resolved.format === "text") {
+      process.stderr.write(`${message}\n`);
+      this.appendFile(message);
+      return;
+    }
+    this.emit({ level: "info", message, action, labels });
+  }
+
+  /** Access log for one HTTP request or MCP RPC. */
+  emitAccess(fields: {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    requestId?: string;
+    clientIp?: string;
+  }): void {
+    if (!this.resolved.access) {
+      return;
+    }
+    if (this.resolved.format === "text") {
+      const rid = fields.requestId ? ` ${fields.requestId}` : "";
+      const line = `${fields.method} ${fields.path} ${fields.status} ${fields.durationMs}ms${rid}`;
+      process.stderr.write(`${line}\n`);
+      this.appendFile(line);
+      return;
+    }
+    this.emit({
+      level: "info",
+      message: `${fields.method} ${fields.path}`,
+      action: "http.access",
+      labels: {
+        ...(fields.requestId ? { request_id: fields.requestId } : {}),
+        ...(fields.clientIp ? { client_ip: fields.clientIp } : {}),
+        http_method: fields.method,
+        http_path: fields.path,
+        http_status: fields.status,
+        duration_ms: fields.durationMs,
+      },
+    });
+  }
+
+  /** Error log after the hook pipeline (real stack always included). */
+  emitInvokeError(
+    failureKind: string,
+    error: unknown,
+    clientMessage: string,
+    labels?: Record<string, string | number | boolean>,
+  ): void {
+    if (!this.resolved.errors) {
+      return;
+    }
+    this.emit({
+      level: failureKind === "unexpected" ? "error" : "warn",
+      message: clientMessage,
+      action: "invoke.error",
+      labels: { failure_kind: failureKind, ...labels },
+      error,
+    });
+    if (this.resolved.dev && error instanceof Error && error.stack) {
+      process.stderr.write(`${error.stack}\n`);
+      this.appendFile(error.stack);
+    }
+  }
+
+  private formatLine(event: EcsLogEvent): string {
+    if (this.resolved.format === "text") {
+      return this.formatTextLine(event);
+    }
+    return formatEcsLine(this.service, event);
+  }
+
+  private formatTextLine(event: EcsLogEvent): string {
+    const level = event.level.toUpperCase();
+    const action = event.action ? ` [${event.action}]` : "";
+    let line = `${level}${action}: ${event.message}`;
+    if (event.error instanceof Error && event.error.stack) {
+      line = `${line}\n${event.error.stack}`;
+    }
+    return line;
+  }
+
+  private appendFile(line: string): void {
+    const file = this.resolved.file;
+    if (!file) {
+      return;
+    }
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      appendFileSync(file, `${line}\n`, "utf8");
+    } catch {
+      // Best-effort file tee; stderr already has the line.
+    }
+  }
+}
+
+/** Maps ECS level strings for quick call sites. */
+export function ecsLevel(level: EcsLogLevel): EcsLogLevel {
+  return level;
+}

package/src/mcp/bundle.ts

@@ -6,8 +6,8 @@ Expects `dist/<program.key>` as the compiled binary input.
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import { buildProgramUserConfig } from "../config/manifest.ts";
-import type { CliMcpBundleConfig, CliProgram } from "../types.ts";
+import { buildProgramUserConfig } from "~/config/manifest.ts";
+import type { CliMcpBundleConfig, CliProgram } from "~/core/types.ts";
 import { packClaudePlugin } from "./claude.ts";
 import { collectMcpTools, mcpServerId } from "./tools.ts";
 import { zipStore } from "./zip.ts";

package/src/mcp/claude.test.ts

@@ -7,7 +7,7 @@ import { execSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
 import {
   defaultClaudePluginPaths,
   generatePluginManifest,

package/src/mcp/claude.ts

@@ -17,10 +17,10 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join, relative, resolve } from "node:path";
-import { buildPluginMcpEnvMapping, buildProgramUserConfig } from "../config/manifest.ts";
-import { generatePluginSkillBundle } from "../skill/generate.ts";
-import { applyPluginSkillHint } from "../skill/hint.ts";
-import type { CliMcpBundleConfig, CliProgram } from "../types.ts";
+import { buildPluginMcpEnvMapping, buildProgramUserConfig } from "~/config/manifest.ts";
+import type { CliMcpBundleConfig, CliProgram } from "~/core/types.ts";
+import { generatePluginSkillBundle } from "~/skill/generate.ts";
+import { applyPluginSkillHint } from "~/skill/hint.ts";
 import { defaultMcpBundlePaths, type PackMcpBundleOpts } from "./bundle.ts";
 import { mcpServerId } from "./tools.ts";
 import { type ZipFileEntry, zipStore } from "./zip.ts";

package/src/{hidden-mcpb.test.ts → mcp/hidden-mcpb.test.ts}

@@ -6,13 +6,13 @@ import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { exportPresentationBuiltins } from "./builtins/export.ts";
-import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
-import { cliHelpRender } from "./help.ts";
-import { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle, runMcpBundle } from "./mcp/bundle.ts";
-import { collectMcpTools } from "./mcp/tools.ts";
-import { cliSchemaExport } from "./schema.ts";
-import { CliOptionKind, type CliProgram } from "./types.ts";
+import { exportPresentationBuiltins } from "~/builtins/export.ts";
+import { cliParseRoot, cliPresentationRoot } from "~/builtins/presentation.ts";
+import { cliSchemaExport } from "~/core/schema.ts";
+import { CliOptionKind, type CliProgram } from "~/core/types.ts";
+import { cliHelpRender } from "~/help.ts";
+import { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle, runMcpBundle } from "./bundle.ts";
+import { collectMcpTools } from "./tools.ts";
 
 const hiddenFixture: CliProgram = {
   key: "myapp",
@@ -27,7 +27,8 @@ const hiddenFixture: CliProgram = {
     },
     {
       key: "secret",
-      hidden: true,
+      cli: { hidden: true },
+      mcpTool: { hidden: true },
       description: "Hidden command.",
       handler: () => {},
     },
@@ -42,7 +43,7 @@ const hiddenFixture: CliProgram = {
         },
         {
           name: "secret-flag",
-          hidden: true,
+          cli: { hidden: true },
           description: "Hidden option.",
           kind: CliOptionKind.Presence,
         },

package/src/mcp/result.ts

@@ -2,8 +2,8 @@
 This module builds MCP tools/call success results from handler respond payloads.
 */
 
-import { encodeRespondBodyBase64 } from "../respond.ts";
-import type { CliRespondOptions } from "../types.ts";
+import { encodeRespondBodyBase64 } from "~/core/respond.ts";
+import type { CliRespondOptions } from "~/core/types.ts";
 
 /** Text content block in an MCP tool result. */
 export interface McpTextContent {

package/src/mcp/server.ts

@@ -3,8 +3,9 @@ This module implements the MCP JSON-RPC server over stdio: initialize, tools,
 resources, and ping. Responses are newline-delimited JSON on stdout only.
 */
 
-import type { Cli } from "../cli.ts";
-import { executeHeadlessToolCall, lookupHeadlessTool } from "../headless/tool-call.ts";
+import { randomUUID } from "node:crypto";
+import { executeHeadlessToolCall, headlessFailureMcpMessage, lookupHeadlessTool } from "~/headless/tool-call.ts";
+import type { Cli } from "~/runtime/cli.ts";
 import { allMcpResources, collectMcpTools, resolveMcpServerInfo } from "./tools.ts";
 
 const MCP_PROTOCOL_VERSION = "2024-11-05";
@@ -37,6 +38,12 @@ function writeError(id: string | number | null | undefined, code: number, messag
 /** Handles one NDJSON request line. */
 async function handleRequestLine(cli: Cli, line: string): Promise<void> {
   const root = cli.program;
+  const requestId = randomUUID();
+  const started = performance.now();
+  const hooks = cli.server?.mcpHooks ?? root.mcpServer?.hooks;
+  const emitter = cli.server?.emitter;
+  const obscureUnexpected = cli.server?.mcp?.obscureUnexpected ?? root.mcpServer?.errors?.obscureUnexpected ?? false;
+
   let req: JsonRpcRequest;
   try {
     req = JSON.parse(line) as JsonRpcRequest;
@@ -46,17 +53,40 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
 
   const id = req.id;
   const hasId = id !== undefined;
+  const method = req.method ?? "";
+  const params = (req.params ?? {}) as Record<string, unknown>;
+  const wireCtx = { rpcMethod: method, requestId };
+
+  await hooks?.onRequest?.(wireCtx);
+
+  const finish = async (failureKind?: string, error?: unknown): Promise<void> => {
+    const durationMs = Math.round(performance.now() - started);
+    if (failureKind && error !== undefined) {
+      await hooks?.onError?.({
+        ...wireCtx,
+        failureKind: failureKind as import("~/core/types.ts").InvokeFailureKind,
+        error,
+      });
+    } else {
+      await hooks?.onResponse?.({ ...wireCtx, durationMs });
+    }
+    emitter?.emitAccess({
+      method: "MCP",
+      path: method,
+      status: failureKind ? 500 : 200,
+      durationMs,
+      requestId,
+    });
+  };
 
   if (req.jsonrpc !== "2.0") {
     if (hasId) {
       writeError(id, -32600, "Invalid Request");
     }
+    await finish("validation", new Error("Invalid Request"));
     return;
   }
 
-  const method = req.method ?? "";
-  const params = (req.params ?? {}) as Record<string, unknown>;
-
   if (method === "notifications/initialized") {
     return;
   }
@@ -77,11 +107,13 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
           serverInfo: { name: info.name, version: info.version },
         },
       });
+      await finish();
       return;
     }
 
     if (method === "ping") {
       writeResponse({ jsonrpc: "2.0", id, result: {} });
+      await finish();
       return;
     }
 
@@ -93,6 +125,7 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
         ...(t.outputSchema === undefined ? {} : { outputSchema: t.outputSchema }),
       }));
       writeResponse({ jsonrpc: "2.0", id, result: { tools } });
+      await finish();
       return;
     }
 
@@ -100,17 +133,20 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
       const name = params.name;
       if (typeof name !== "string") {
         writeError(id, -32602, "Invalid params: name required");
+        await finish("validation", new Error("Invalid params: name required"));
         return;
       }
       const rawArgs = params.arguments;
       if (rawArgs !== undefined && (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs))) {
         writeError(id, -32602, "Invalid params: arguments must be an object");
+        await finish("validation", new Error("Invalid params: arguments must be an object"));
         return;
       }
       const lookup = lookupHeadlessTool(root, name);
       if (!lookup.ok) {
         if (lookup.kind === "unknown") {
           writeError(id, -32602, lookup.message);
+          await finish("unknown_route", new Error(lookup.message));
           return;
         }
         writeResponse({
@@ -121,6 +157,7 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
             isError: true,
           },
         });
+        await finish("missing_config", new Error(lookup.message));
         return;
       }
       const invokeResult = await executeHeadlessToolCall(
@@ -128,6 +165,7 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
         lookup.tool,
         (rawArgs ?? {}) as Record<string, unknown>,
         "mcp",
+        { rpcMethod: method, toolName: name, requestId },
       );
       if (invokeResult.ok) {
         writeResponse({
@@ -135,16 +173,19 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
           id,
           result: invokeResult.mcpResult,
         });
+        await finish();
         return;
       }
+      const text = headlessFailureMcpMessage(invokeResult, obscureUnexpected);
       writeResponse({
         jsonrpc: "2.0",
         id,
         result: {
-          content: [{ type: "text", text: invokeResult.message }],
+          content: [{ type: "text", text }],
           isError: true,
         },
       });
+      await finish(invokeResult.failureKind ?? "invoke", new Error(invokeResult.message));
       return;
     }
 
@@ -156,6 +197,7 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
         mimeType: r.mimeType,
       }));
       writeResponse({ jsonrpc: "2.0", id, result: { resources } });
+      await finish();
       return;
     }
 
@@ -163,12 +205,14 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
       const uri = params.uri;
       if (typeof uri !== "string") {
         writeError(id, -32602, "Invalid params: uri required");
+        await finish("validation", new Error("Invalid params: uri required"));
         return;
       }
       const all = allMcpResources(root);
       const found = all.find((r) => r.uri === uri);
       if (!found) {
         writeError(id, -32602, `Unknown resource: ${uri}`);
+        await finish("unknown_route", new Error(`Unknown resource: ${uri}`));
         return;
       }
       let text: string;
@@ -177,6 +221,7 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         writeError(id, -32603, `Resource load failed: ${message}`);
+        await finish("unexpected", err);
         return;
       }
       writeResponse({
@@ -192,13 +237,16 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
           ],
         },
       });
+      await finish();
       return;
     }
 
     writeError(id, -32601, "Method not found");
+    await finish("unknown_route", new Error("Method not found"));
   } catch (err) {
     const message = err instanceof Error ? err.message : "Internal error";
     writeError(id, -32603, message);
+    await finish("unexpected", err);
   }
 }
 

package/src/mcp/tools.ts

@@ -3,11 +3,8 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for Cli.invoke.
 */
 
-import { docsMcpResources } from "../docs/mcp-resources.ts";
-import { cliResolveNotes } from "../help.ts";
-import { visibleOptions } from "../hidden.ts";
-import { collectOptionDefs } from "../parse.ts";
-import { cliSchemaJson } from "../schema.ts";
+import { collectOptionDefs } from "~/core/parse.ts";
+import { cliSchemaJson } from "~/core/schema.ts";
 import {
   type CliLeaf,
   type CliNode,
@@ -19,7 +16,10 @@ import {
   isCliLeaf,
   isJsonLeaf,
   leafOutputSchema,
-} from "../types.ts";
+} from "~/core/types.ts";
+import { docsMcpResources } from "~/docs/mcp-resources.ts";
+import { cliResolveNotes } from "~/help.ts";
+import { isMcpHidden, visibleOptions } from "~/runtime/exposure.ts";
 
 const DURATION_PATTERN = "^\\d+[hdms]?$";
 
@@ -28,7 +28,7 @@ export function defaultMcpSchemaUri(mcpId: string): string {
   return `${mcpId}://schema`;
 }
 
-export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "../docs/mcp-resources.ts";
+export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "~/docs/mcp-resources.ts";
 
 /** Sanitizes a command key segment for MCP tool names and server identity. */
 export function sanitizeToolSegment(key: string): string {
@@ -44,8 +44,6 @@ export function mcpServerId(root: CliProgram): string {
 export interface McpToolDef {
   /** 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. */
@@ -72,14 +70,6 @@ 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 };
@@ -122,7 +112,7 @@ function optionProperty(opt: CliOption): Record<string, unknown> {
   }
 }
 
-function formatMcpOptionValue(opt: CliOption, val: unknown): string | { error: string } {
+export function formatMcpOptionValue(opt: CliOption, val: unknown): string | { error: string } {
   if (opt.format === CliValueFormat.CommaList) {
     if (Array.isArray(val)) {
       const items = val.map(String).filter(Boolean);
@@ -238,13 +228,12 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
       if (cmd.key === "completion" || cmd.key === "configure" || cmd.key === "mcp" || cmd.key === "version") {
         return;
       }
-      if (cmd.hidden || cmd.mcpTool?.enabled === false) {
+      if (isMcpHidden(cmd)) {
         return;
       }
       const outputSchema = leafOutputSchema(cmd);
       out.push({
         name: mcpToolName(root, path),
-        apiName: apiToolName(root, path),
         description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,

package/src/{capabilities.ts → runtime/capabilities.ts}

@@ -3,12 +3,12 @@ Internal capability resolver — decides which platform builtins are active for
 Not exported from the public package barrel.
 */
 
-import { configCommandsEnabled } from "./config/entry.ts";
-import type { CliProgram } from "./types.ts";
+import { configCommandsEnabled } from "~/config/entry.ts";
+import type { CliProgram } from "~/core/types.ts";
 
 /** Platform builtins derived from program config and runtime. */
 export interface CliCapabilities {
-  api: boolean;
+  http: boolean;
   completion: boolean;
   mcp: boolean;
   configure: boolean;
@@ -20,11 +20,11 @@ export interface CliCapabilities {
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
   const configure = program.configure?.enabled !== false;
   return {
-    api: program.apiServer?.enabled === true,
+    http: program.httpServer?.enabled === true,
     completion: program.completion?.enabled !== false,
     mcp: program.mcpServer?.enabled === true,
     configure,
-    docs: program.docs?.enabled === true,
+    docs: program.docs?.enabled !== false,
     configCommands: configCommandsEnabled(program),
   };
 }
@@ -44,8 +44,8 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   if (caps.mcp) {
     names.push("mcp");
   }
-  if (caps.api) {
-    names.push("api");
+  if (caps.http) {
+    names.push("http");
   }
   return names;
 }
@@ -65,14 +65,14 @@ export function skipsRequiredAppConfigExit(path: string[], caps: CliCapabilities
   return false;
 }
 
-export type CapabilityFeature = "api" | "mcp" | "configure" | "docs" | "completion";
+export type CapabilityFeature = "http" | "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":
+    case "http":
       return "HTTP API is not available for this app.\n";
     case "mcp":
       return "MCP is not available for this app.\n";
@@ -97,8 +97,8 @@ 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"));
+  if (first === "http" && !caps.http) {
+    process.stderr.write(capabilityDeniedMessage("http"));
     process.exit(1);
   }
   if (first === "configure" && !caps.configure) {

package/src/{cli-errors.ts → runtime/cli-errors.ts}

@@ -2,12 +2,12 @@
 Handler error helper with contextual help.
 */
 
-import { cliPresentationRoot } from "./builtins/presentation.ts";
-import type { CliContext } from "./context.ts";
-import { cliHelpRender } from "./help.ts";
+import { cliPresentationRoot } from "~/builtins/presentation.ts";
+import type { CliContext } from "~/core/context.ts";
+import { cliHelpRender } from "~/help.ts";
 
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
-  if (ctx.invocation === "api" || ctx.invocation === "mcp") {
+  if (ctx.invocation === "http" || ctx.invocation === "mcp") {
     throw new Error(msg);
   }
   const color = process.stderr.isTTY;