argsbarg 6.1.2 → 6.1.3

package/src/http/routes.ts

@@ -0,0 +1,329 @@
+/*
+HTTP REST route collection and request matching from the CLI command tree.
+*/
+
+import { collectOptionDefs } from "~/core/parse.ts";
+import {
+  type CliHttpMethod,
+  type CliLeaf,
+  type CliNode,
+  type CliProgram,
+  isCliLeaf,
+  isJsonLeaf,
+  CliOptionKind as OptKind,
+} from "~/core/types.ts";
+import { formatMcpOptionValue } from "~/mcp/tools.ts";
+import { isHttpDisabled, isHttpHidden } from "~/runtime/exposure.ts";
+
+const VERB_KEYS = new Set(["get", "post", "put", "patch", "delete"]);
+
+/** One HTTP route derived from a user leaf command. */
+export interface HttpRouteDef {
+  method: CliHttpMethod;
+  /** OpenAPI-style path e.g. `/api/workspaces/{id}`. */
+  openApiPath: string;
+  /** Regex matching pathname (no query). */
+  pathPattern: RegExp;
+  /** Argv command path; `:id` tokens replaced at request time. */
+  commandPath: string[];
+  /** Param names in URL order (without `:`). */
+  paramNames: string[];
+  leaf: CliLeaf;
+}
+
+function isParamRouterKey(key: string): boolean {
+  return key.startsWith(":");
+}
+
+function inferHttpMethod(leaf: CliLeaf): CliHttpMethod {
+  if (leaf.http?.method) {
+    return leaf.http.method;
+  }
+  const lower = leaf.key.toLowerCase();
+  if (VERB_KEYS.has(lower)) {
+    return lower.toUpperCase() as CliHttpMethod;
+  }
+  return "POST";
+}
+
+function isVerbLeaf(leaf: CliLeaf): boolean {
+  return VERB_KEYS.has(leaf.key.toLowerCase()) && leaf.http?.method === undefined;
+}
+
+function segmentForNode(node: CliNode): string {
+  return node.http?.segment ?? node.key;
+}
+
+function leafHttpExposed(leaf: CliLeaf): boolean {
+  if (isHttpDisabled(leaf) || isHttpHidden(leaf)) {
+    return false;
+  }
+  return true;
+}
+
+type WalkState = {
+  urlSegments: string[];
+  commandPath: string[];
+  paramNames: string[];
+};
+
+function pushRoute(routes: HttpRouteDef[], leaf: CliLeaf, state: WalkState): void {
+  const urlSegments = [...state.urlSegments];
+  const commandPath = [...state.commandPath];
+  if (!isVerbLeaf(leaf)) {
+    const seg = segmentForNode(leaf);
+    if (urlSegments[urlSegments.length - 1] !== seg) {
+      urlSegments.push(seg);
+    }
+    if (commandPath[commandPath.length - 1] !== leaf.key) {
+      commandPath.push(leaf.key);
+    }
+  }
+  const openApiPath = `/api/${urlSegments.map((s) => (s.startsWith(":") ? `{${s.slice(1)}}` : s)).join("/")}`;
+  const patternParts = urlSegments.map((s) => (s.startsWith(":") ? "([^/]+)" : escapeRegex(s)));
+  const pathPattern = new RegExp(`^/api/${patternParts.join("/")}/?$`);
+  routes.push({
+    method: inferHttpMethod(leaf),
+    openApiPath,
+    pathPattern,
+    commandPath,
+    paramNames: [...state.paramNames],
+    leaf,
+  });
+}
+
+function walk(node: CliNode, state: WalkState, routes: HttpRouteDef[]): void {
+  if (isHttpDisabled(node) || isHttpHidden(node)) {
+    return;
+  }
+
+  if (isCliLeaf(node)) {
+    if (leafHttpExposed(node)) {
+      pushRoute(routes, node, state);
+    }
+    return;
+  }
+
+  for (const child of node.commands) {
+    if (isParamRouterKey(child.key)) {
+      const paramName = child.key.slice(1);
+      walk(
+        child,
+        {
+          urlSegments: [...state.urlSegments, child.key],
+          commandPath: [...state.commandPath, child.key],
+          paramNames: [...state.paramNames, paramName],
+        },
+        routes,
+      );
+      continue;
+    }
+    if (isCliLeaf(child)) {
+      walk(
+        child,
+        {
+          urlSegments: state.urlSegments,
+          commandPath: [...state.commandPath, child.key],
+          paramNames: state.paramNames,
+        },
+        routes,
+      );
+      continue;
+    }
+    const seg = segmentForNode(child);
+    walk(
+      child,
+      {
+        urlSegments: [...state.urlSegments, seg],
+        commandPath: [...state.commandPath, child.key],
+        paramNames: state.paramNames,
+      },
+      routes,
+    );
+  }
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Collects all HTTP routes for exposed user leaves. */
+export function collectHttpRoutes(program: CliProgram): HttpRouteDef[] {
+  const routes: HttpRouteDef[] = [];
+  if (!program.httpServer?.enabled) {
+    return routes;
+  }
+
+  if (isCliLeaf(program)) {
+    walk(program, { urlSegments: [], commandPath: [], paramNames: [] }, routes);
+    return routes;
+  }
+
+  for (const child of program.commands) {
+    if (
+      child.key === "completion" ||
+      child.key === "configure" ||
+      child.key === "docs" ||
+      child.key === "mcp" ||
+      child.key === "version" ||
+      child.key === "http"
+    ) {
+      continue;
+    }
+    if (isCliLeaf(child)) {
+      walk(child, { urlSegments: [], commandPath: [child.key], paramNames: [] }, routes);
+    } else {
+      walk(child, { urlSegments: [segmentForNode(child)], commandPath: [child.key], paramNames: [] }, routes);
+    }
+  }
+
+  return routes;
+}
+
+/** Match result for an incoming HTTP request. */
+export type HttpRouteMatch = { ok: true; route: HttpRouteDef; pathParams: Record<string, string> } | { ok: false };
+
+/** Finds the best matching route for method + pathname. */
+export function matchHttpRoute(program: CliProgram, method: string, pathname: string): HttpRouteMatch {
+  const routes = collectHttpRoutes(program);
+  const upper = method.toUpperCase();
+  let best: { route: HttpRouteDef; pathParams: Record<string, string>; score: number } | undefined;
+
+  for (const route of routes) {
+    if (route.method !== upper) {
+      continue;
+    }
+    const m = route.pathPattern.exec(pathname);
+    if (!m) {
+      continue;
+    }
+    const pathParams: Record<string, string> = {};
+    for (let i = 0; i < route.paramNames.length; i++) {
+      const name = route.paramNames[i];
+      const val = m[i + 1];
+      if (name && val !== undefined) {
+        pathParams[name] = decodeURIComponent(val);
+      }
+    }
+    const score = route.openApiPath.length;
+    if (!best || score > best.score) {
+      best = { route, pathParams, score };
+    }
+  }
+
+  if (!best) {
+    return { ok: false };
+  }
+  return { ok: true, route: best.route, pathParams: best.pathParams };
+}
+
+/** Builds argv from an HTTP route match, query string, and optional JSON body. */
+export function httpRequestToArgv(
+  program: CliProgram,
+  route: HttpRouteDef,
+  pathParams: Record<string, string>,
+  query: Record<string, string>,
+  body: Record<string, unknown>,
+): string[] | { error: string } {
+  const argv: string[] = [];
+  for (const key of route.commandPath) {
+    if (isParamRouterKey(key)) {
+      const name = key.slice(1);
+      const val = pathParams[name];
+      if (val === undefined || val.length === 0) {
+        return { error: `Missing path parameter: ${name}` };
+      }
+      argv.push(val);
+    } else {
+      argv.push(key);
+    }
+  }
+
+  const leaf = route.leaf;
+  if (isJsonLeaf(leaf)) {
+    return argv;
+  }
+
+  const merged: Record<string, unknown> = { ...body, ...query };
+  for (const [k, v] of Object.entries(query)) {
+    if (typeof v === "string" && (v.startsWith("{") || v.startsWith("["))) {
+      try {
+        merged[k] = JSON.parse(v);
+      } catch {
+        merged[k] = v;
+      }
+    }
+  }
+
+  for (const opt of collectOptionDefs(program, argv)) {
+    if (opt.kind === OptKind.Json) {
+      continue;
+    }
+    const val = merged[opt.name];
+    if (val === undefined) {
+      continue;
+    }
+    if (opt.kind === OptKind.Presence) {
+      if (val === true || val === "true" || val === "1") {
+        argv.push(`--${opt.name}`);
+      }
+      continue;
+    }
+    const formatted = formatMcpOptionValue(opt, val);
+    if (typeof formatted !== "string") {
+      return formatted;
+    }
+    argv.push(`--${opt.name}`, formatted);
+  }
+
+  for (const p of leaf.positionals ?? []) {
+    const val = merged[p.name] ?? pathParams[p.name];
+    const { argMin = 1, argMax = 1 } = p;
+
+    if (argMax === 0) {
+      const raw = merged[p.name];
+      if (raw === undefined) {
+        if (argMin >= 1) {
+          return { error: `Missing argument: ${p.name} (use a JSON array)` };
+        }
+        continue;
+      }
+      if (!Array.isArray(raw)) {
+        return { error: `Argument ${p.name} must be a JSON array of strings` };
+      }
+      const items = raw.map(String).filter(Boolean);
+      if (items.length === 0 && argMin >= 1) {
+        return { error: `Missing argument: ${p.name}` };
+      }
+      argv.push(...items);
+      continue;
+    }
+
+    if (val === undefined || val === "") {
+      if (argMin >= 1) {
+        return { error: `Missing argument: ${p.name}` };
+      }
+      continue;
+    }
+    argv.push(String(val));
+  }
+
+  return argv;
+}
+
+/** Default success HTTP status for a route method when handler omits status. */
+export function defaultSuccessStatus(method: CliHttpMethod, hasBody: boolean): number {
+  switch (method) {
+    case "GET":
+      return 200;
+    case "POST":
+      return 201;
+    case "PUT":
+    case "PATCH":
+      return 200;
+    case "DELETE":
+      return hasBody ? 200 : 204;
+    default:
+      return 200;
+  }
+}

package/src/http/server.ts

@@ -0,0 +1,225 @@
+/*
+HTTP tool server for ArgsBarg programs: health, OpenAPI, and REST API invocation.
+*/
+
+import { randomUUID } from "node:crypto";
+import type { CliHttpWireContext, CliProgram } from "~/core/types.ts";
+import {
+  executeHttpRouteCall,
+  headlessFailureToHttpResponse,
+  headlessSuccessToHttpResponse,
+} from "~/headless/tool-call.ts";
+import type { Cli } from "~/runtime/cli.ts";
+import { leafHttpResponseDefaults } from "~/runtime/exposure.ts";
+import type { ResolvedHttpServeConfig } from "~/server/overrides.ts";
+import { generateOpenApi } from "./openapi.ts";
+import { evaluateReadiness } from "./readiness.ts";
+import { API_CORS_HEADERS, apiDocsHtml, apiErrorResponse, apiOptionsResponse } from "./result.ts";
+import { defaultSuccessStatus, matchHttpRoute } from "./routes.ts";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3000;
+
+/** Resolved listen address for the HTTP API server. */
+export function resolveHttpListenAddress(program: CliProgram): { hostname: string; port: number } {
+  const config = program.httpServer;
+  return {
+    hostname: config?.host ?? DEFAULT_HOST,
+    port: config?.port ?? DEFAULT_PORT,
+  };
+}
+
+/** Resolves client IP, optionally honoring X-Forwarded-For. */
+export function resolveClientIp(request: Request, trustProxy: boolean): string {
+  if (trustProxy) {
+    const xff = request.headers.get("x-forwarded-for");
+    if (xff) {
+      return xff.split(",")[0]?.trim() ?? "unknown";
+    }
+  }
+  return "unknown";
+}
+
+/** Writes a JSON HTTP response with CORS headers. */
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      ...API_CORS_HEADERS,
+      "content-type": "application/json; charset=utf-8",
+    },
+  });
+}
+
+function parseQuery(url: URL): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of url.searchParams.entries()) {
+    out[k] = v;
+  }
+  return out;
+}
+
+/** Handles one HTTP request for the API server. */
+export async function handleApiRequest(
+  cli: Cli,
+  request: Request,
+  resolved?: ResolvedHttpServeConfig,
+): Promise<Response> {
+  const httpConfig = resolved ?? cli.server?.http;
+  const trustProxy = httpConfig?.trustProxy ?? cli.program.httpServer?.trustProxy ?? false;
+  const requestId = randomUUID();
+  const url = new URL(request.url);
+  const clientIp = resolveClientIp(request, trustProxy);
+  const wireCtx: CliHttpWireContext = {
+    request,
+    requestId,
+    clientIp,
+    path: url.pathname,
+    method: request.method,
+  };
+  const hooks = cli.server?.httpHooks ?? cli.program.httpServer?.hooks;
+  const emitter = cli.server?.emitter;
+  const started = performance.now();
+
+  const finish = async (response: Response, failureKind?: string, error?: unknown): Promise<Response> => {
+    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, status: response.status, durationMs });
+    }
+    emitter?.emitAccess({
+      method: request.method,
+      path: url.pathname,
+      status: response.status,
+      durationMs,
+      requestId,
+      clientIp,
+    });
+    return response;
+  };
+
+  await hooks?.onRequest?.(wireCtx);
+
+  if (request.method === "OPTIONS") {
+    return finish(apiOptionsResponse());
+  }
+
+  const root = cli.program;
+  const path = url.pathname;
+
+  if (request.method === "GET" && (path === "/health" || path === "/health/live")) {
+    return finish(jsonResponse(200, { ok: true }));
+  }
+
+  if (request.method === "GET" && path === "/health/ready") {
+    const runtime = cli.server?.runtime;
+    if (!runtime) {
+      return finish(jsonResponse(200, { ok: true }));
+    }
+    const readiness = await evaluateReadiness(root, "http", runtime, cli.appConfig);
+    return finish(jsonResponse(readiness.ok ? 200 : 503, readiness));
+  }
+
+  if (request.method === "GET" && path === "/openapi.json") {
+    return finish(jsonResponse(200, generateOpenApi(root)));
+  }
+
+  if (request.method === "GET" && path === "/openapi-browser") {
+    return finish(
+      new Response(apiDocsHtml(), {
+        status: 200,
+        headers: {
+          ...API_CORS_HEADERS,
+          "content-type": "text/html; charset=utf-8",
+        },
+      }),
+    );
+  }
+
+  if (path.startsWith("/api")) {
+    const match = matchHttpRoute(root, request.method, path);
+    if (!match.ok) {
+      return finish(apiErrorResponse(404, { error: "Not found" }));
+    }
+
+    let body: Record<string, unknown> = {};
+    if (request.method === "POST" || request.method === "PUT" || request.method === "PATCH") {
+      const rawBody = await request.text();
+      if (rawBody.trim().length > 0) {
+        try {
+          const parsed = JSON.parse(rawBody);
+          if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return finish(apiErrorResponse(400, { error: "Request body must be a JSON object" }));
+          }
+          body = parsed as Record<string, unknown>;
+        } catch {
+          return finish(apiErrorResponse(400, { error: "Invalid JSON body" }));
+        }
+      }
+    }
+
+    const query = parseQuery(url);
+    const result = await executeHttpRouteCall(cli, match.route, match.pathParams, query, body, {
+      request,
+      clientIp,
+      requestId,
+    });
+    if (result.ok) {
+      const leafHttp = leafHttpResponseDefaults(match.route.leaf);
+      const hasBody = result.response.body !== undefined;
+      const methodDefault =
+        match.route.leaf.http?.successStatus ??
+        defaultSuccessStatus(match.route.method, hasBody && match.route.method !== "DELETE");
+      return finish(headlessSuccessToHttpResponse(result, leafHttp, methodDefault));
+    }
+    const obscure = httpConfig?.obscureUnexpected ?? false;
+    return finish(headlessFailureToHttpResponse(result, obscure), result.invokeResult?.failureKind, result.message);
+  }
+
+  if (path.startsWith("/tools")) {
+    return finish(apiErrorResponse(404, { error: "Not found" }));
+  }
+
+  return finish(apiErrorResponse(404, { error: "Not found" }));
+}
+
+/** Runs the HTTP API server until the process is interrupted. */
+export async function httpServeHttp(cli: Cli, resolved?: ResolvedHttpServeConfig): Promise<never> {
+  const listen = resolved ?? {
+    hostname: resolveHttpListenAddress(cli.program).hostname,
+    port: resolveHttpListenAddress(cli.program).port,
+    trustProxy: cli.program.httpServer?.trustProxy ?? false,
+    obscureUnexpected: cli.program.httpServer?.errors?.obscureUnexpected ?? false,
+    log: { format: "json" as const, access: true, errors: true, dev: false },
+  };
+  const server = Bun.serve({
+    hostname: listen.hostname,
+    port: listen.port,
+    fetch: (request) => handleApiRequest(cli, request, listen),
+  });
+  const url = `http://${server.hostname}:${server.port}`;
+  const emitter = cli.server?.emitter;
+  if (emitter && listen.log.format === "text") {
+    emitter.emitLifecycle(
+      `${cli.program.key} ${cli.program.version} — HTTP API listening on ${url}`,
+      "http.server.start",
+    );
+  } else {
+    emitter?.emit({
+      level: "info",
+      message: `HTTP API listening on ${url}`,
+      action: "http.server.start",
+      labels: { url },
+    });
+    if (!emitter) {
+      process.stderr.write(`HTTP API listening on ${url}\n`);
+    }
+  }
+  await new Promise<never>(() => {});
+  throw new Error("HTTP API server stopped unexpectedly");
+}

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,27 +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,
   isJsonLeaf,
-} from "./types.ts";
+} 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");
+  });
+});