argsbarg 6.1.3 → 6.1.5

package/src/http/openapi.ts

@@ -3,8 +3,8 @@ 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 type { CliHttpMethod, CliNode, CliProgram } from "~/core/types.ts";
+import { CliOptionKind, isCliLeaf, isJsonLeaf } from "~/core/types.ts";
 import { collectHttpRoutes, defaultSuccessStatus } from "./routes.ts";
 import { dereferenceJsonSchema } from "./schema-deref.ts";
 
@@ -106,15 +106,120 @@ function methodLower(method: CliHttpMethod): string {
   return method.toLowerCase();
 }
 
+const HEALTH_TAG = "health";
+
+const livenessResponseSchema = {
+  type: "object",
+  properties: { ok: { type: "boolean", const: true } },
+  required: ["ok"],
+} as const;
+
+const readinessCheckSchema = {
+  type: "object",
+  properties: {
+    ok: { type: "boolean" },
+    error: { type: "string" },
+    missing: { type: "array", items: { type: "string" } },
+  },
+  required: ["ok"],
+} as const;
+
+const readinessResponseSchema = {
+  type: "object",
+  properties: {
+    ok: { type: "boolean" },
+    checks: {
+      type: "object",
+      properties: {
+        config_file: readinessCheckSchema,
+        config_required: readinessCheckSchema,
+        custom: readinessCheckSchema,
+      },
+      required: ["config_file", "config_required", "custom"],
+    },
+  },
+  required: ["ok", "checks"],
+} as const;
+
+function jsonResponseEntry(description: string, schema: Record<string, unknown>): Record<string, unknown> {
+  return {
+    description,
+    content: {
+      [JSON_CONTENT_TYPE]: { schema },
+    },
+  };
+}
+
+function livenessGetOp(operationId: string, summary: string): Record<string, unknown> {
+  return {
+    tags: [HEALTH_TAG],
+    operationId,
+    summary,
+    responses: {
+      "200": jsonResponseEntry("Server is listening", livenessResponseSchema),
+    },
+  };
+}
+
+/** Framework health probe paths served alongside user command routes. */
+function buildHealthPaths(): Record<string, unknown> {
+  return {
+    "/health": {
+      get: livenessGetOp("health", "Liveness probe (alias of /health/liveness)"),
+    },
+    "/health/liveness": {
+      get: livenessGetOp("health_liveness", "Liveness probe"),
+    },
+    "/health/readiness": {
+      get: {
+        tags: [HEALTH_TAG],
+        operationId: "health_readiness",
+        summary: "Readiness probe",
+        description: "Config file, required app config, and optional program.readiness checks.",
+        responses: {
+          "200": jsonResponseEntry("Ready to serve traffic", readinessResponseSchema),
+          "503": jsonResponseEntry("Not ready", readinessResponseSchema),
+        },
+      },
+    },
+  };
+}
+
+type HttpRoute = ReturnType<typeof collectHttpRoutes>[number];
+
+/** Top-level command key for OpenAPI grouping (first non-`:param` segment). */
+function topLevelCommandKey(route: HttpRoute, program: CliProgram): string {
+  const key = route.commandPath.find((k) => !k.startsWith(":"));
+  return key ?? program.key;
+}
+
+function findTopLevelCommand(program: CliProgram, key: string): CliNode | undefined {
+  if (isCliLeaf(program)) {
+    return program.key === key ? program : undefined;
+  }
+  return program.commands.find((c) => c.key === key);
+}
+
+/** OpenAPI tags for user command routes, one per top-level command. */
+function collectCommandTags(program: CliProgram, routes: HttpRoute[]): { name: string; description?: string }[] {
+  const names = [...new Set(routes.map((route) => topLevelCommandKey(route, program)))].sort();
+  return names.map((name) => {
+    const node = findTopLevelCommand(program, name);
+    return node?.description ? { name, description: node.description } : { name };
+  });
+}
+
 /** 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> = {};
+  const paths: Record<string, unknown> = program.httpServer?.enabled ? buildHealthPaths() : {};
+  const commandTags = collectCommandTags(program, routes);
 
   for (const route of routes) {
     const pathKey = route.openApiPath;
     const existing = (paths[pathKey] as Record<string, unknown> | undefined) ?? {};
     const op: Record<string, unknown> = {
+      tags: [topLevelCommandKey(route, program)],
       operationId: route.openApiPath.replace(/\//g, "_").replace(/[{}]/g, ""),
       summary: route.leaf.description ?? route.leaf.key,
       responses: {
@@ -150,9 +255,9 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
           description: opt.description,
         })),
       ];
-    } else if (!isJsonLeaf(route.leaf)) {
+    } else {
       op.requestBody = {
-        required: false,
+        required: isJsonLeaf(route.leaf),
         content: {
           [JSON_CONTENT_TYPE]: {
             schema: dereferenceJsonSchema(buildInputSchema(program, route)),
@@ -172,6 +277,9 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
       version: program.version,
       description: program.description,
     },
+    ...(program.httpServer?.enabled
+      ? { tags: [{ name: HEALTH_TAG, description: "Server health probes" }, ...commandTags] }
+      : {}),
     paths,
   };
 }

package/src/http/paths.ts

@@ -0,0 +1,39 @@
+/*
+HTTP path prefix helpers and framework route guards.
+*/
+
+import type { CliProgram } from "~/core/types.ts";
+
+/** Top-level segments reserved for framework routes when `pathPrefix` is empty. */
+export const HTTP_RESERVED_TOP_LEVEL_SEGMENTS = new Set(["health", "openapi.json", "swagger", "tools"]);
+
+/** Resolved path prefix for user HTTP routes (`""` by default, or e.g. `"/api"`). */
+export function resolveHttpPathPrefix(program: CliProgram): string {
+  const raw = program.httpServer?.pathPrefix;
+  if (raw === undefined || raw === "") {
+    return "";
+  }
+  return raw;
+}
+
+/** OpenAPI / route path for a user command from URL segments. */
+export function buildHttpUserPath(prefix: string, urlSegments: string[]): string {
+  const tail = urlSegments.map((s) => (s.startsWith(":") ? `{${s.slice(1)}}` : s)).join("/");
+  if (!prefix) {
+    return tail ? `/${tail}` : "/";
+  }
+  return tail ? `${prefix}/${tail}` : prefix;
+}
+
+/** Regex-safe path prefix for route matching. */
+export function httpUserPathRegexPrefix(prefix: string): string {
+  if (!prefix) {
+    return "";
+  }
+  return prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Wildcard label for docs (e.g. `/api/*` or `/*`). */
+export function httpUserPathGlob(prefix: string): string {
+  return prefix ? `${prefix}/*` : "/*";
+}

package/src/http/readiness.ts

@@ -1,5 +1,5 @@
 /*
-HTTP/MCP readiness checks for GET /health/ready (orchestrator probes only).
+HTTP/MCP readiness checks for GET /health/readiness (orchestrator probes only).
 */
 
 import type { AnyAppConfigSnapshot } from "~/config/context.ts";

package/src/http/result.ts

@@ -98,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">
@@ -106,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

@@ -14,13 +14,14 @@ import {
 } from "~/core/types.ts";
 import { formatMcpOptionValue } from "~/mcp/tools.ts";
 import { isHttpDisabled, isHttpHidden } from "~/runtime/exposure.ts";
+import { buildHttpUserPath, httpUserPathRegexPrefix, resolveHttpPathPrefix } from "./paths.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}`. */
+  /** OpenAPI-style path e.g. `/workspaces/{id}` or `/api/workspaces/{id}`. */
   openApiPath: string;
   /** Regex matching pathname (no query). */
   pathPattern: RegExp;
@@ -67,7 +68,7 @@ type WalkState = {
   paramNames: string[];
 };
 
-function pushRoute(routes: HttpRouteDef[], leaf: CliLeaf, state: WalkState): void {
+function pushRoute(routes: HttpRouteDef[], leaf: CliLeaf, state: WalkState, pathPrefix: string): void {
   const urlSegments = [...state.urlSegments];
   const commandPath = [...state.commandPath];
   if (!isVerbLeaf(leaf)) {
@@ -79,9 +80,11 @@ function pushRoute(routes: HttpRouteDef[], leaf: CliLeaf, state: WalkState): voi
       commandPath.push(leaf.key);
     }
   }
-  const openApiPath = `/api/${urlSegments.map((s) => (s.startsWith(":") ? `{${s.slice(1)}}` : s)).join("/")}`;
+  const openApiPath = buildHttpUserPath(pathPrefix, urlSegments);
   const patternParts = urlSegments.map((s) => (s.startsWith(":") ? "([^/]+)" : escapeRegex(s)));
-  const pathPattern = new RegExp(`^/api/${patternParts.join("/")}/?$`);
+  const regexPrefix = httpUserPathRegexPrefix(pathPrefix);
+  const tail = patternParts.length > 0 ? `/${patternParts.join("/")}` : "";
+  const pathPattern = new RegExp(`^${regexPrefix}${tail}/?$`);
   routes.push({
     method: inferHttpMethod(leaf),
     openApiPath,
@@ -92,14 +95,14 @@ function pushRoute(routes: HttpRouteDef[], leaf: CliLeaf, state: WalkState): voi
   });
 }
 
-function walk(node: CliNode, state: WalkState, routes: HttpRouteDef[]): void {
+function walk(node: CliNode, state: WalkState, routes: HttpRouteDef[], pathPrefix: string): void {
   if (isHttpDisabled(node) || isHttpHidden(node)) {
     return;
   }
 
   if (isCliLeaf(node)) {
     if (leafHttpExposed(node)) {
-      pushRoute(routes, node, state);
+      pushRoute(routes, node, state, pathPrefix);
     }
     return;
   }
@@ -115,6 +118,7 @@ function walk(node: CliNode, state: WalkState, routes: HttpRouteDef[]): void {
           paramNames: [...state.paramNames, paramName],
         },
         routes,
+        pathPrefix,
       );
       continue;
     }
@@ -127,6 +131,7 @@ function walk(node: CliNode, state: WalkState, routes: HttpRouteDef[]): void {
           paramNames: state.paramNames,
         },
         routes,
+        pathPrefix,
       );
       continue;
     }
@@ -139,6 +144,7 @@ function walk(node: CliNode, state: WalkState, routes: HttpRouteDef[]): void {
         paramNames: state.paramNames,
       },
       routes,
+      pathPrefix,
     );
   }
 }
@@ -154,8 +160,10 @@ export function collectHttpRoutes(program: CliProgram): HttpRouteDef[] {
     return routes;
   }
 
+  const pathPrefix = resolveHttpPathPrefix(program);
+
   if (isCliLeaf(program)) {
-    walk(program, { urlSegments: [], commandPath: [], paramNames: [] }, routes);
+    walk(program, { urlSegments: [], commandPath: [], paramNames: [] }, routes, pathPrefix);
     return routes;
   }
 
@@ -171,9 +179,14 @@ export function collectHttpRoutes(program: CliProgram): HttpRouteDef[] {
       continue;
     }
     if (isCliLeaf(child)) {
-      walk(child, { urlSegments: [], commandPath: [child.key], paramNames: [] }, routes);
+      walk(child, { urlSegments: [], commandPath: [child.key], paramNames: [] }, routes, pathPrefix);
     } else {
-      walk(child, { urlSegments: [segmentForNode(child)], commandPath: [child.key], paramNames: [] }, routes);
+      walk(
+        child,
+        { urlSegments: [segmentForNode(child)], commandPath: [child.key], paramNames: [] },
+        routes,
+        pathPrefix,
+      );
     }
   }
 

package/src/http/server.ts

@@ -112,11 +112,11 @@ export async function handleApiRequest(
   const root = cli.program;
   const path = url.pathname;
 
-  if (request.method === "GET" && (path === "/health" || path === "/health/live")) {
+  if (request.method === "GET" && (path === "/health" || path === "/health/liveness")) {
     return finish(jsonResponse(200, { ok: true }));
   }
 
-  if (request.method === "GET" && path === "/health/ready") {
+  if (request.method === "GET" && path === "/health/readiness") {
     const runtime = cli.server?.runtime;
     if (!runtime) {
       return finish(jsonResponse(200, { ok: true }));
@@ -129,7 +129,7 @@ export async function handleApiRequest(
     return finish(jsonResponse(200, generateOpenApi(root)));
   }
 
-  if (request.method === "GET" && path === "/openapi-browser") {
+  if (request.method === "GET" && path === "/swagger") {
     return finish(
       new Response(apiDocsHtml(), {
         status: 200,
@@ -141,12 +141,12 @@ export async function handleApiRequest(
     );
   }
 
-  if (path.startsWith("/api")) {
-    const match = matchHttpRoute(root, request.method, path);
-    if (!match.ok) {
-      return finish(apiErrorResponse(404, { error: "Not found" }));
-    }
+  if (path.startsWith("/tools")) {
+    return finish(apiErrorResponse(404, { error: "Not found" }));
+  }
 
+  const match = matchHttpRoute(root, request.method, path);
+  if (match.ok) {
     let body: Record<string, unknown> = {};
     if (request.method === "POST" || request.method === "PUT" || request.method === "PATCH") {
       const rawBody = await request.text();
@@ -181,10 +181,6 @@ export async function handleApiRequest(
     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" }));
 }