argsbarg 6.1.2 → 6.1.4

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,
@@ -87,7 +98,7 @@ export function apiErrorResponse(status: number, body: ApiToolCallErrorBody): Re
   });
 }
 
-/** Scalar API reference HTML served at GET /openapi-browser. */
+/** Swagger UI HTML served at GET /swagger. */
 export function apiDocsHtml(): string {
   return `<!doctype html>
 <html lang="en">
@@ -95,15 +106,15 @@ export function apiDocsHtml(): string {
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>API Reference</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css" />
 </head>
 <body>
-  <div id="api-reference"></div>
-  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js" crossorigin></script>
   <script>
-    Scalar.createApiReference("#api-reference", {
+    SwaggerUIBundle({
       url: "/openapi.json",
-      orderSchemaPropertiesBy: "preserve",
-      orderRequiredPropertiesFirst: false,
+      dom_id: "#swagger-ui",
     });
   </script>
 </body>

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