argsbarg 6.1.1 → 6.1.3

package/src/index.ts

@@ -7,40 +7,21 @@ 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";
-export type { CliLeafInputs } from "./context.ts";
-export { CliContext } from "./context.ts";
+export type { CliLeafInputs } from "./core/context.ts";
+export { CliContext } from "./core/context.ts";
 export {
   parseCommaList,
   parseDate,
   parseDateTime,
   parseDurationMs,
-} from "./formats.ts";
-export type { HeadlessContext } from "./headless.ts";
-export {
-  formatDryRunMessage,
-  requireYesInNonTty,
-  shouldRunHeadless,
-  shouldRunHeadlessWithPositionals,
-  shouldRunHeadlessWithYes,
-  wantsExplicitJson,
-} from "./headless.ts";
+} from "./core/formats.ts";
 export {
   LeafInputError,
-  loadLeafInputs,
   preloadPipableJson,
   readJsonOptionValue,
-  readLeafInputs,
-  readLeafInputsAsync,
-} from "./leaf-inputs.ts";
-export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
-export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
+} from "./core/leaf-inputs.ts";
 export type {
-  CliApiResponseConfig,
-  CliApiServerConfig,
   CliAppConfig,
   CliAppConfigEntry,
   CliAppConfigResolveContext,
@@ -49,25 +30,57 @@ export type {
   CliConfigureTargets,
   CliDocsConfig,
   CliDocsTopic,
+  ClientErrorOverride,
   CliHandler,
+  CliHttpServerConfig,
+  CliHttpWireContext,
+  CliHttpWireHooks,
   CliInvocation,
+  CliInvokeHookResult,
+  CliLeafKind,
+  CliLocals,
+  CliLogConfig,
   CliMcpBundleConfig,
   CliMcpResource,
   CliMcpServerConfig,
   CliMcpToolConfig,
+  CliMcpWireContext,
+  CliMcpWireHooks,
   CliOption,
   CliPositional,
   CliProgram,
+  CliProgramHooks,
   CliRespondBody,
   CliRespondOptions,
+  ErrorHookContext,
   InstallAgentIntegration,
   InstallTargetSpec,
+  InvokeFailureKind,
+  InvokeHookContext,
+  ReadinessContext,
   ResolvedInstallTarget,
-} from "./types.ts";
+  ServerRuntime,
+  ServerState,
+} from "./core/types.ts";
 export {
   CliFallbackMode,
   CliOptionKind,
   CliSchemaValidationError,
   CliValueFormat,
-} from "./types.ts";
+  isJsonLeaf,
+} from "./core/types.ts";
+export type { HeadlessContext } from "./headless/routing.ts";
+export {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsExplicitJson,
+} from "./headless/routing.ts";
+export { generateOpenApi, openApiJson } from "./http/openapi.ts";
+export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
+export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.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/log/ecs.test.ts

@@ -0,0 +1,43 @@
+/*
+Unit tests for ECS log line formatting.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { formatEcsLine } from "./ecs.ts";
+
+describe("formatEcsLine", () => {
+  test("includes service fields and event action", () => {
+    const line = formatEcsLine(
+      { name: "myapp", version: "7.0.0" },
+      {
+        level: "info",
+        message: "HTTP API listening",
+        action: "http.server.start",
+      },
+    );
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed["service.name"]).toBe("myapp");
+    expect(parsed["service.version"]).toBe("7.0.0");
+    expect(parsed["event.action"]).toBe("http.server.start");
+    expect(parsed.message).toBe("HTTP API listening");
+    expect(parsed["log.level"]).toBe("info");
+    expect(typeof parsed["@timestamp"]).toBe("string");
+  });
+
+  test("includes error stack fields", () => {
+    const err = new Error("boom");
+    const line = formatEcsLine(
+      { name: "app", version: "1.0.0" },
+      {
+        level: "error",
+        message: "invoke failed",
+        action: "invoke.error",
+        error: err,
+      },
+    );
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed["error.message"]).toBe("boom");
+    expect(parsed["error.type"]).toBe("Error");
+    expect(String(parsed["error.stack_trace"])).toContain("boom");
+  });
+});

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