argsbarg 6.1.2 → 6.1.3

package/src/help.test.ts

@@ -0,0 +1,152 @@
+/*
+Help rendering and label formatting tests.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { cliPresentationRoot } from "./builtins/presentation.ts";
+import { type CliOption, CliOptionKind, type CliPositional } from "./core/types.ts";
+import { CLI_NOTES_PROGRAM, cliHelpRender, cliOptionLabel, cliPositionalLabel, cliResolveNotes } from "./help.ts";
+import { testProgram } from "./test/fixtures.ts";
+
+describe("cliOptionLabel", () => {
+  test.each([
+    {
+      name: "string option",
+      option: { name: "out", description: "Output path.", kind: CliOptionKind.String },
+      expected: "--out <string>",
+    },
+    {
+      name: "required enum",
+      option: {
+        name: "format",
+        description: "Format.",
+        kind: CliOptionKind.Enum,
+        choices: ["pdf", "html"],
+        required: true,
+      },
+      expected: "--format <pdf|html>",
+    },
+    {
+      name: "short name",
+      option: {
+        name: "verbose",
+        description: "Verbose.",
+        kind: CliOptionKind.Presence,
+        shortName: "v",
+      },
+      expected: "--verbose, -v",
+    },
+    {
+      name: "json option",
+      option: { name: "body", description: "JSON body.", kind: CliOptionKind.Json },
+      expected: "--body <json>",
+    },
+  ])("$name", ({ option, expected }) => {
+    expect(cliOptionLabel(option as CliOption, false)).toBe(expected);
+  });
+});
+
+describe("cliPositionalLabel", () => {
+  test.each([
+    { positional: { name: "file", description: "File." }, expected: "<file>" },
+    { positional: { name: "file", description: "File.", argMin: 0 }, expected: "[file]" },
+    { positional: { name: "paths", description: "Paths.", argMax: 0 }, expected: "<paths...>" },
+    { positional: { name: "paths", description: "Paths.", argMin: 0, argMax: 0 }, expected: "[paths...]" },
+  ])("$expected", ({ positional, expected }) => {
+    expect(cliPositionalLabel(positional as CliPositional, false)).toBe(expected);
+  });
+});
+
+describe("cliResolveNotes", () => {
+  test("replaces program placeholder", () => {
+    expect(cliResolveNotes(`Run \`${CLI_NOTES_PROGRAM} docs readme\`.`, "myapp")).toBe("Run `myapp docs readme`.");
+  });
+});
+
+describe("cliHelpRender", () => {
+  test("docs help lists schema, cli, and skill subcommands", () => {
+    const root = testProgram({
+      key: "app",
+      version: "1.0.0",
+      description: "demo",
+      docs: {
+        topics: { readme: { text: "# readme\n" } },
+      },
+      commands: [
+        {
+          key: "x",
+          description: "cmd",
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["docs"], false);
+    expect(help).toContain("cli-schema");
+    expect(help).toContain("Print the full CLI command tree as JSON.");
+    expect(help).toContain("cli");
+    expect(help).toContain("markdown");
+    expect(help).toContain("skill");
+    expect(help).toContain("reference agent SKILL");
+  });
+
+  test("root help omits legacy --schema flag", () => {
+    const root = testProgram({
+      key: "app",
+      version: "1.0.0",
+      description: "demo",
+      commands: [
+        {
+          key: "x",
+          description: "cmd",
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), [], false);
+    expect(help).not.toContain("--schema");
+  });
+
+  test("root help shows agent docs hint when docs enabled", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "demo",
+      docs: {
+        topics: { readme: { text: "# readme\n" } },
+      },
+      commands: [{ key: "run", description: "Run.", handler: () => {} }],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), [], false);
+    expect(help).toContain("For AI agents: `myapp docs skill`.");
+    expect(help).not.toContain("install --skill");
+  });
+
+  test("root help omits agent hint when docs disabled", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "demo",
+      docs: { enabled: false },
+      commands: [{ key: "run", description: "Run.", handler: () => {} }],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), [], false);
+    expect(help).not.toContain("Agents:");
+    expect(help).not.toContain("docs skill");
+  });
+
+  test("root help includes program notes and agent hint", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "demo",
+      notes: "See `{argsbarg:program} docs readme` for the user guide.",
+      docs: {
+        topics: { readme: { text: "# readme\n" } },
+      },
+      commands: [{ key: "run", description: "Run.", handler: () => {} }],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), [], false);
+    expect(help).toContain("See `myapp docs readme` for the user guide.");
+    expect(help).toContain("myapp docs skill");
+  });
+});

package/src/help.ts

@@ -7,7 +7,6 @@ It keeps help formatting shared across help and error paths so users see one con
 style no matter how help is reached.
 */
 
-import { visibleOptions, visibleSubcommands } from "./hidden.ts";
 import {
   type CliNode,
   type CliOption,
@@ -17,7 +16,8 @@ import {
   isCliLeaf,
   isCliRouter,
   isJsonLeaf,
-} from "./types.ts";
+} from "./core/types.ts";
+import { visibleOptions, visibleSubcommands } from "./runtime/exposure.ts";
 
 // ── ANSI Style Helpers ────────────────────────────────────────────────────────
 
@@ -197,7 +197,7 @@ export function cliOptionLabel(o: CliOption, color: boolean): string {
   return `${style.aquaBold(left)} ${style.greenBright(right)}`;
 }
 
-/** Placeholder in `notes` for the root program key (resolved in help, schema, and docs api). */
+/** Placeholder in `notes` for the root program key (resolved in help, schema, and docs cli). */
 export const CLI_NOTES_PROGRAM = "{argsbarg:program}";
 
 /** Replaces `{argsbarg:program}` in notes/help text with the program key. */

package/src/hooks/builtin.ts

@@ -0,0 +1,20 @@
+/*
+Detects built-in command paths so invoke hooks are skipped for framework commands.
+*/
+
+const BUILTIN_ROOTS = new Set(["completion", "version", "http", "mcp", "configure", "docs"]);
+
+/** True when `path` routes to a framework built-in (hooks are skipped). */
+export function isBuiltinInvokePath(path: string[]): boolean {
+  const root = path[0];
+  if (!root || !BUILTIN_ROOTS.has(root)) {
+    return false;
+  }
+  if (root === "http") {
+    return path.length <= 1 || path[1] === "serve";
+  }
+  if (root === "mcp") {
+    return path.length <= 1 || path[1] === "serve" || path[1] === "bundle";
+  }
+  return true;
+}

package/src/hooks/run.ts

@@ -0,0 +1,142 @@
+/*
+Safe async hook runner, failure classification, and invoke error pipeline.
+*/
+
+import type { CliContext } from "~/core/context.ts";
+import { LeafInputError } from "~/core/leaf-inputs.ts";
+import type {
+  ClientErrorOverride,
+  ErrorHookContext,
+  InvokeFailureKind,
+  InvokeHookContext,
+  ServerRuntime,
+} from "~/core/types.ts";
+import { firstErrorLine } from "~/http/result.ts";
+import { type LogEmitter, obscureUnexpectedClientMessage } from "~/log/emitter.ts";
+
+/** Runs a hook without letting hook throws escape uncaught. */
+export async function runHook<T>(hook: (() => T | Promise<T>) | undefined, label: string): Promise<T | undefined> {
+  if (!hook) {
+    return undefined;
+  }
+  try {
+    return await Promise.resolve(hook());
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`${label} hook failed: ${message}`, { cause: err });
+  }
+}
+
+/** Classifies an invoke failure for status mapping and logging. */
+export function classifyFailureKind(
+  err: unknown,
+  opts: { parseError?: boolean; help?: boolean; missingConfig?: boolean; notReady?: boolean },
+): InvokeFailureKind {
+  if (opts.help) {
+    return "help";
+  }
+  if (opts.missingConfig) {
+    return "missing_config";
+  }
+  if (opts.notReady) {
+    return "not_ready";
+  }
+  if (opts.parseError || err instanceof LeafInputError) {
+    return "validation";
+  }
+  if (err instanceof Error) {
+    return "validation";
+  }
+  return "unexpected";
+}
+
+/** HTTP status for a classified failure kind. */
+export function failureKindHttpStatus(kind: InvokeFailureKind): number {
+  switch (kind) {
+    case "validation":
+    case "help":
+      return 400;
+    case "unknown_route":
+      return 404;
+    case "missing_config":
+    case "not_ready":
+      return 503;
+    case "unexpected":
+      return 500;
+  }
+}
+
+/** Builds {@link InvokeHookContext} from a live {@link CliContext}. */
+export function buildInvokeHookContext(
+  ctx: CliContext,
+  extras: {
+    path: string[];
+    runtime?: ServerRuntime;
+    http?: InvokeHookContext["http"];
+    mcp?: InvokeHookContext["mcp"];
+  },
+): InvokeHookContext {
+  return {
+    invocation: ctx.invocation,
+    path: extras.path,
+    pathParams: { ...ctx.pathParams },
+    opts: ctx.opts,
+    locals: ctx.locals,
+    runtime: extras.runtime,
+    appConfig: ctx.appConfig,
+    http: extras.http,
+    mcp: extras.mcp,
+  };
+}
+
+function defaultClientError(err: unknown, _failureKind: InvokeFailureKind): ClientErrorOverride {
+  const message =
+    err instanceof Error ? err.message : typeof err === "string" ? err : firstErrorLine(String(err)) || "Error";
+  return { message, exitCode: 1 };
+}
+
+export interface ErrorPipelineResult {
+  failureKind: InvokeFailureKind;
+  clientError: ClientErrorOverride;
+  errorMsg: string;
+}
+
+/** Runs formatError → onError → ECS emit for one invoke failure. */
+export async function runErrorPipeline(
+  hookCtx: InvokeHookContext,
+  err: unknown,
+  failureKind: InvokeFailureKind,
+  hooks: import("~/core/types.ts").CliProgramHooks | undefined,
+  emitter: LogEmitter | undefined,
+  obscureUnexpected: boolean,
+): Promise<ErrorPipelineResult> {
+  let clientError = defaultClientError(err, failureKind);
+  if (failureKind === "unexpected" && obscureUnexpected) {
+    clientError = { message: obscureUnexpectedClientMessage(), exitCode: 1 };
+  }
+
+  const errorCtx: ErrorHookContext = {
+    ...hookCtx,
+    failureKind,
+    error: err,
+    clientError: { ...clientError },
+  };
+
+  const formatted = await runHook(() => hooks?.formatError?.(errorCtx), "formatError");
+  if (formatted) {
+    clientError = { ...clientError, ...formatted };
+    errorCtx.clientError = { ...clientError };
+  }
+
+  await runHook(() => hooks?.onError?.(errorCtx), "onError");
+
+  const displayMessage =
+    failureKind === "unexpected" && obscureUnexpected ? obscureUnexpectedClientMessage() : clientError.message;
+
+  emitter?.emitInvokeError(failureKind, err, displayMessage, {
+    invocation: hookCtx.invocation,
+    path: hookCtx.path.join(" "),
+  });
+
+  return { failureKind, clientError, errorMsg: displayMessage };
+}

package/src/http/openapi.ts

@@ -0,0 +1,182 @@
+/*
+Hand-built OpenAPI 3.1 document from exposed HTTP REST routes.
+*/
+
+import { collectOptionDefs } from "~/core/parse.ts";
+import type { CliHttpMethod, CliProgram } from "~/core/types.ts";
+import { CliOptionKind, isJsonLeaf } from "~/core/types.ts";
+import { collectHttpRoutes, defaultSuccessStatus } from "./routes.ts";
+import { dereferenceJsonSchema } from "./schema-deref.ts";
+
+const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+
+function defaultErrorSchema(): Record<string, unknown> {
+  return {
+    type: "object",
+    properties: { error: { type: "string" } },
+    required: ["error"],
+  };
+}
+
+function errorResponseSchema(program: CliProgram): Record<string, unknown> {
+  const custom = program.httpServer?.errors?.errorSchema;
+  return custom ? dereferenceJsonSchema(custom) : defaultErrorSchema();
+}
+
+function errorResponseEntry(program: CliProgram, description: string): Record<string, unknown> {
+  return {
+    description,
+    content: {
+      [JSON_CONTENT_TYPE]: {
+        schema: errorResponseSchema(program),
+      },
+    },
+  };
+}
+
+function buildInputSchema(
+  program: CliProgram,
+  route: ReturnType<typeof collectHttpRoutes>[number],
+): Record<string, unknown> {
+  const leaf = route.leaf;
+  if (leaf.inputSchema) {
+    return leaf.inputSchema;
+  }
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const p of route.paramNames) {
+    properties[p] = { type: "string" };
+    required.push(p);
+  }
+  const argv = route.commandPath.filter((k) => !k.startsWith(":"));
+  for (const opt of collectOptionDefs(program, argv)) {
+    if (opt.kind === CliOptionKind.Json) {
+      continue;
+    }
+    properties[opt.name] = { type: "string", description: opt.description };
+    if (opt.required) {
+      required.push(opt.name);
+    }
+  }
+  for (const p of leaf.positionals ?? []) {
+    properties[p.name] = { type: "string", description: p.description };
+    if ((p.argMin ?? 1) >= 1) {
+      required.push(p.name);
+    }
+  }
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  };
+}
+
+/** Builds success response entries for OpenAPI (status → response object). */
+function buildSuccessResponses(route: ReturnType<typeof collectHttpRoutes>[number]): Record<string, unknown> {
+  const contentType = route.leaf.http?.successContentType ?? "application/json";
+  const media: Record<string, unknown> = {};
+  const method = route.method;
+
+  if (contentType.includes("application/json")) {
+    const outputSchema = route.leaf.outputSchema ?? { type: "object" };
+    media[contentType] = {
+      schema: dereferenceJsonSchema(outputSchema),
+    };
+  } else if (contentType.includes("text/html")) {
+    media[contentType] = { schema: { type: "string" } };
+  } else {
+    media[contentType] = { schema: { type: "string", format: "binary" } };
+  }
+
+  const status = String(route.leaf.http?.successStatus ?? defaultSuccessStatus(method, method !== "DELETE"));
+  if (method === "DELETE" && status === "204") {
+    return {
+      "204": { description: "Successful invocation" },
+    };
+  }
+  return {
+    [status]: {
+      description: "Successful invocation",
+      content: media,
+    },
+  };
+}
+
+function methodLower(method: CliHttpMethod): string {
+  return method.toLowerCase();
+}
+
+/** Generates an OpenAPI 3.1 document for the program's HTTP routes. */
+export function generateOpenApi(program: CliProgram): Record<string, unknown> {
+  const routes = collectHttpRoutes(program);
+  const paths: Record<string, unknown> = {};
+
+  for (const route of routes) {
+    const pathKey = route.openApiPath;
+    const existing = (paths[pathKey] as Record<string, unknown> | undefined) ?? {};
+    const op: Record<string, unknown> = {
+      operationId: route.openApiPath.replace(/\//g, "_").replace(/[{}]/g, ""),
+      summary: route.leaf.description ?? route.leaf.key,
+      responses: {
+        ...buildSuccessResponses(route),
+        "400": errorResponseEntry(program, "Invalid arguments or help requested"),
+        "404": errorResponseEntry(program, "Not found"),
+        "500": errorResponseEntry(program, "Handler error"),
+        "503": errorResponseEntry(program, "Not ready or missing required config"),
+      },
+    };
+
+    if (route.paramNames.length > 0) {
+      op.parameters = route.paramNames.map((name) => ({
+        name,
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+      }));
+    }
+
+    const method = methodLower(route.method);
+    if (method === "get" || method === "delete") {
+      op.parameters = [
+        ...((op.parameters as unknown[]) ?? []),
+        ...collectOptionDefs(
+          program,
+          route.commandPath.filter((k) => !k.startsWith(":")),
+        ).map((opt) => ({
+          name: opt.name,
+          in: "query",
+          required: opt.required ?? false,
+          schema: { type: "string" },
+          description: opt.description,
+        })),
+      ];
+    } else if (!isJsonLeaf(route.leaf)) {
+      op.requestBody = {
+        required: false,
+        content: {
+          [JSON_CONTENT_TYPE]: {
+            schema: dereferenceJsonSchema(buildInputSchema(program, route)),
+          },
+        },
+      };
+    }
+
+    existing[method] = op;
+    paths[pathKey] = existing;
+  }
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: program.key,
+      version: program.version,
+      description: program.description,
+    },
+    paths,
+  };
+}
+
+/** Pretty-printed OpenAPI JSON (same document as `GET /openapi.json`). */
+export function openApiJson(program: CliProgram): string {
+  return `${JSON.stringify(generateOpenApi(program), null, 2)}\n`;
+}

package/src/http/readiness.ts

@@ -0,0 +1,78 @@
+/*
+HTTP/MCP readiness checks for GET /health/ready (orchestrator probes only).
+*/
+
+import type { AnyAppConfigSnapshot } from "~/config/context.ts";
+import { missingRequiredConfig } from "~/config/resolve.ts";
+import type { CliProgram, ReadinessContext, ServerRuntime } from "~/core/types.ts";
+
+const READINESS_CACHE_MS = 3000;
+
+export interface ReadinessCheck {
+  ok: boolean;
+  error?: string;
+  missing?: string[];
+}
+
+export interface ReadinessResult {
+  ok: boolean;
+  checks: Record<string, ReadinessCheck>;
+}
+
+function configFileCheck(runtime: ServerRuntime): ReadinessCheck {
+  const err = runtime.state.configFileError;
+  if (typeof err === "string" && err.length > 0) {
+    return { ok: false, error: err };
+  }
+  return { ok: true };
+}
+
+function configRequiredCheck(program: CliProgram, appConfig: AnyAppConfigSnapshot): ReadinessCheck {
+  if (!program.appConfig) {
+    return { ok: true };
+  }
+  const missing = missingRequiredConfig(program, appConfig.read());
+  if (missing.length > 0) {
+    return { ok: false, missing };
+  }
+  return { ok: true };
+}
+
+async function customReadinessCheck(ctx: ReadinessContext): Promise<ReadinessCheck> {
+  const fn = ctx.program.readiness;
+  if (!fn) {
+    return { ok: true };
+  }
+  try {
+    const ok = await Promise.resolve(fn(ctx));
+    return ok ? { ok: true } : { ok: false, error: "readiness check returned false" };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}
+
+/** Runs built-in + custom readiness checks (short TTL cache in runtime.state). */
+export async function evaluateReadiness(
+  program: CliProgram,
+  surface: "http" | "mcp",
+  runtime: ServerRuntime,
+  appConfig: AnyAppConfigSnapshot,
+): Promise<ReadinessResult> {
+  const cached = runtime.state.readinessCache;
+  if (cached && Date.now() - cached.at < READINESS_CACHE_MS) {
+    return cached.result;
+  }
+
+  const ctx: ReadinessContext = { program, surface, appConfig, runtime };
+  const checks: Record<string, ReadinessCheck> = {
+    config_file: configFileCheck(runtime),
+    config_required: configRequiredCheck(program, appConfig),
+    custom: await customReadinessCheck(ctx),
+  };
+  const ok = Object.values(checks).every((c) => c.ok);
+  const result: ReadinessResult = { ok, checks };
+  runtime.state.readinessCache = { at: Date.now(), result };
+  runtime.state.readiness = result;
+  return result;
+}

package/src/{api → http}/result.ts

@@ -2,7 +2,7 @@
 Maps headless respond payloads to native HTTP Response objects.
 */
 
-import type { CliApiResponseConfig, CliRespondOptions } from "../types.ts";
+import type { CliHttpResponseConfig, CliRespondOptions } from "~/core/types.ts";
 
 /** JSON body for a failed HTTP tool invocation. */
 export interface ApiToolCallErrorBody {
@@ -30,7 +30,7 @@ export function firstErrorLine(text: string): string {
 /** Wide-open CORS headers applied to all API responses. */
 export const API_CORS_HEADERS: Readonly<Record<string, string>> = {
   "access-control-allow-origin": "*",
-  "access-control-allow-methods": "GET, POST, OPTIONS",
+  "access-control-allow-methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
   "access-control-allow-headers": "Content-Type, Authorization",
   "access-control-max-age": "86400",
 };
@@ -41,7 +41,10 @@ export function apiOptionsResponse(): Response {
 }
 
 /** Resolves effective Content-Type for a respond payload. */
-export function resolveRespondContentType(response: CliRespondOptions, leafApiResponse?: CliApiResponseConfig): string {
+export function resolveRespondContentType(
+  response: CliRespondOptions,
+  leafApiResponse?: CliHttpResponseConfig,
+): string {
   return (
     response.contentType ??
     leafApiResponse?.contentType ??
@@ -50,7 +53,11 @@ export function resolveRespondContentType(response: CliRespondOptions, leafApiRe
 }
 
 /** Builds a native HTTP Response from a successful headless respond payload. */
-export function apiSuccessResponse(response: CliRespondOptions, leafApiResponse?: CliApiResponseConfig): Response {
+export function apiSuccessResponse(
+  response: CliRespondOptions,
+  leafApiResponse?: CliHttpResponseConfig,
+  defaultStatus?: number,
+): Response {
   const contentType = resolveRespondContentType(response, leafApiResponse);
   const headers: Record<string, string> = {
     ...API_CORS_HEADERS,
@@ -61,9 +68,13 @@ export function apiSuccessResponse(response: CliRespondOptions, leafApiResponse?
     headers["content-disposition"] = leafApiResponse.contentDisposition;
   }
 
-  const status = response.status ?? 200;
+  const status = response.status ?? defaultStatus ?? 200;
   const { body } = response;
 
+  if (status === 204) {
+    return new Response(null, { status: 204, headers });
+  }
+
   if (body instanceof Uint8Array) {
     return new Response(body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength) as ArrayBuffer, {
       status,