argsbarg 6.1.4 → 6.1.5

package/examples/full-example/docs/openapi.json

@@ -5,10 +5,285 @@
     "version": "1.0.0",
     "description": "Argsbarg full example reference app"
   },
+  "tags": [
+    {
+      "name": "health",
+      "description": "Server health probes"
+    },
+    {
+      "name": "echo",
+      "description": "Echo a message (MCP-friendly leaf)."
+    },
+    {
+      "name": "render-json",
+      "description": "Echo a JSON message (schema-first JSON leaf demo)."
+    },
+    {
+      "name": "status",
+      "description": "Show app version."
+    },
+    {
+      "name": "workspaces",
+      "description": "Workspace collection and CRUD."
+    }
+  ],
   "paths": {
-    "/api/echo": {
+    "/health": {
+      "get": {
+        "tags": [
+          "health"
+        ],
+        "operationId": "health",
+        "summary": "Liveness probe (alias of /health/liveness)",
+        "responses": {
+          "200": {
+            "description": "Server is listening",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "const": true
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/health/liveness": {
+      "get": {
+        "tags": [
+          "health"
+        ],
+        "operationId": "health_liveness",
+        "summary": "Liveness probe",
+        "responses": {
+          "200": {
+            "description": "Server is listening",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean",
+                      "const": true
+                    }
+                  },
+                  "required": [
+                    "ok"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/health/readiness": {
+      "get": {
+        "tags": [
+          "health"
+        ],
+        "operationId": "health_readiness",
+        "summary": "Readiness probe",
+        "description": "Config file, required app config, and optional program.readiness checks.",
+        "responses": {
+          "200": {
+            "description": "Ready to serve traffic",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "checks": {
+                      "type": "object",
+                      "properties": {
+                        "config_file": {
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean"
+                            },
+                            "error": {
+                              "type": "string"
+                            },
+                            "missing": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ]
+                        },
+                        "config_required": {
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean"
+                            },
+                            "error": {
+                              "type": "string"
+                            },
+                            "missing": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ]
+                        },
+                        "custom": {
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean"
+                            },
+                            "error": {
+                              "type": "string"
+                            },
+                            "missing": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "config_file",
+                        "config_required",
+                        "custom"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "checks"
+                  ]
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Not ready",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "checks": {
+                      "type": "object",
+                      "properties": {
+                        "config_file": {
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean"
+                            },
+                            "error": {
+                              "type": "string"
+                            },
+                            "missing": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ]
+                        },
+                        "config_required": {
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean"
+                            },
+                            "error": {
+                              "type": "string"
+                            },
+                            "missing": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ]
+                        },
+                        "custom": {
+                          "type": "object",
+                          "properties": {
+                            "ok": {
+                              "type": "boolean"
+                            },
+                            "error": {
+                              "type": "string"
+                            },
+                            "missing": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          },
+                          "required": [
+                            "ok"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "config_file",
+                        "config_required",
+                        "custom"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "checks"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/echo": {
       "post": {
-        "operationId": "_api_echo",
+        "tags": [
+          "echo"
+        ],
+        "operationId": "_echo",
         "summary": "Echo a message (MCP-friendly leaf).",
         "responses": {
           "201": {
@@ -115,9 +390,12 @@
         }
       }
     },
-    "/api/render-json": {
+    "/render-json": {
       "post": {
-        "operationId": "_api_render-json",
+        "tags": [
+          "render-json"
+        ],
+        "operationId": "_render-json",
         "summary": "Echo a JSON message (schema-first JSON leaf demo).",
         "responses": {
           "201": {
@@ -226,9 +504,12 @@
         }
       }
     },
-    "/api/status": {
+    "/status": {
       "post": {
-        "operationId": "_api_status",
+        "tags": [
+          "status"
+        ],
+        "operationId": "_status",
         "summary": "Show app version.",
         "responses": {
           "201": {
@@ -343,9 +624,12 @@
         }
       }
     },
-    "/api/workspaces": {
+    "/workspaces": {
       "get": {
-        "operationId": "_api_workspaces",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces",
         "summary": "List workspaces.",
         "responses": {
           "200": {
@@ -434,7 +718,10 @@
         "parameters": []
       },
       "post": {
-        "operationId": "_api_workspaces",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces",
         "summary": "Create a workspace.",
         "responses": {
           "201": {
@@ -543,9 +830,12 @@
         }
       }
     },
-    "/api/workspaces/{id}": {
+    "/workspaces/{id}": {
       "get": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Get one workspace.",
         "responses": {
           "200": {
@@ -643,7 +933,10 @@
         ]
       },
       "put": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Replace a workspace.",
         "responses": {
           "200": {
@@ -762,7 +1055,10 @@
         }
       },
       "patch": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Patch a workspace name.",
         "responses": {
           "200": {
@@ -881,7 +1177,10 @@
         }
       },
       "delete": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Delete a workspace.",
         "responses": {
           "204": {

package/examples/servers.ts

@@ -4,10 +4,10 @@ This example shows the smallest end-to-end CLI+MCP+API setup.
 It includes one command, a couple of options, and a direct call to the runtime so
 readers can copy the pattern into their own scripts quickly.
 
-Demonstrates: `servers.ts hello`, MCP tool `hello`, and `POST /api/hello`.
+Demonstrates: `servers.ts hello`, MCP tool `hello`, and `POST /hello`.
 
 Ex API Call:
-curl -s -X POST http://127.0.0.1:3000/api/hello \
+curl -s -X POST http://127.0.0.1:3000/hello \
   -H 'content-type: application/json' \
   -d '{"name":"alice"}'
 Ex API Response:

package/index.d.ts

@@ -353,6 +353,11 @@ export interface CliHttpServerConfig {
 	host?: string;
 	/** Listen port (default: `3000`). */
 	port?: number;
+	/**
+	 * URL prefix for user command routes (default: `""` — routes at server root, e.g. `/workspaces`).
+	 * Set to `"/api"` for `/api/workspaces`-style paths.
+	 */
+	pathPrefix?: string;
 	/** Honor `X-Forwarded-For` for client IP in hooks and logs. */
 	trustProxy?: boolean;
 	/** HTTP error response defaults. */
@@ -744,7 +749,7 @@ export type CliProgram = CliNode & {
 	docs?: CliDocsConfig;
 	/** Invoke and error hooks for user commands on CLI, HTTP, and MCP. */
 	hooks?: CliProgramHooks;
-	/** Optional readiness probe for HTTP/MCP `GET /health/ready` only. */
+	/** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
 	readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
 	/** Framework logging (stderr + optional file). */
 	log?: CliLogConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.1.4",
+  "version": "6.1.5",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/builtins/http.ts

@@ -7,6 +7,7 @@ import {
   type CliRouter,
 } from "~/core/types.ts";
 import { docsEnabled } from "~/docs/resolve.ts";
+import { httpUserPathGlob, resolveHttpPathPrefix } from "~/http/paths.ts";
 import { resolveHttpListenAddress } from "~/http/server.ts";
 import { resolveCapabilities } from "~/runtime/capabilities.ts";
 
@@ -34,10 +35,11 @@ const HTTP_SERVE_OPTIONS: CliOption[] = [
 export function cliBuiltinHttpCommand(program: CliProgram): CliRouter {
   const caps = resolveCapabilities(program);
   const { hostname, port } = resolveHttpListenAddress(program);
+  const userGlob = httpUserPathGlob(resolveHttpPathPrefix(program));
   const lines = [
     `HTTP tool server on http://${hostname}:${port}.`,
     "",
-    "Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*",
+    `Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, ${userGlob}`,
     "",
   ];
   if (caps.configure) {

package/src/core/types.ts

@@ -246,6 +246,11 @@ export interface CliHttpServerConfig {
   host?: string;
   /** Listen port (default: `3000`). */
   port?: number;
+  /**
+   * URL prefix for user command routes (default: `""` — routes at server root, e.g. `/workspaces`).
+   * Set to `"/api"` for `/api/workspaces`-style paths.
+   */
+  pathPrefix?: string;
   /** Honor `X-Forwarded-For` for client IP in hooks and logs. */
   trustProxy?: boolean;
   /** HTTP error response defaults. */
@@ -669,7 +674,7 @@ export type CliProgram = CliNode & {
   docs?: CliDocsConfig;
   /** Invoke and error hooks for user commands on CLI, HTTP, and MCP. */
   hooks?: CliProgramHooks;
-  /** Optional readiness probe for HTTP/MCP `GET /health/ready` only. */
+  /** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
   readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
   /** Framework logging (stderr + optional file). */
   log?: CliLogConfig;

package/src/core/validate.ts

@@ -5,6 +5,7 @@ This module validates CLI schemas before execution.
 import { AGENT_PAIRS, MCP_KEYS, mcpServerRequiredForArtifact } from "~/configure/artifacts/target-registry.ts";
 import { reservedDocsTopicResourceUris } from "~/docs/mcp-resources.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS, docsEnabled } from "~/docs/resolve.ts";
+import { HTTP_RESERVED_TOP_LEVEL_SEGMENTS } from "~/http/paths.ts";
 import { resolveMcpSchemaUri } from "~/mcp/tools.ts";
 import { reservedCommandNames, resolveCapabilities } from "~/runtime/capabilities.ts";
 import { validateFormatValue } from "./formats.ts";
@@ -180,6 +181,8 @@ export function cliValidateProgram(program: CliProgram): void {
     throw new CliSchemaValidationError("httpServer requires enabled: true; omit httpServer to disable HTTP API");
   }
 
+  validateHttpPathPrefix(program);
+
   if (docsEnabled(program) && program.docs?.topics !== undefined) {
     validateDocsConfig(program.docs);
   }
@@ -212,6 +215,46 @@ function isParamRouterKey(key: string): boolean {
   return key.startsWith(":");
 }
 
+/** Validates `httpServer.pathPrefix` and reserved top-level command keys. */
+function validateHttpPathPrefix(program: CliProgram): void {
+  if (!program.httpServer?.enabled) {
+    return;
+  }
+  const raw = program.httpServer.pathPrefix;
+  if (raw !== undefined && raw !== "") {
+    if (!raw.startsWith("/")) {
+      throw new CliSchemaValidationError(`httpServer.pathPrefix must start with / (got ${JSON.stringify(raw)})`);
+    }
+    if (raw.length > 1 && raw.endsWith("/")) {
+      throw new CliSchemaValidationError(`httpServer.pathPrefix must not end with / (got ${JSON.stringify(raw)})`);
+    }
+    if (raw.includes("//")) {
+      throw new CliSchemaValidationError("httpServer.pathPrefix must not contain //");
+    }
+    if (raw === "/health" || raw === "/swagger" || raw === "/openapi.json" || raw === "/tools") {
+      throw new CliSchemaValidationError(
+        `httpServer.pathPrefix must not be a framework path (got ${JSON.stringify(raw)})`,
+      );
+    }
+    return;
+  }
+  if (!isCliRouter(program)) {
+    if (isCliLeaf(program) && HTTP_RESERVED_TOP_LEVEL_SEGMENTS.has(program.key)) {
+      throw new CliSchemaValidationError(
+        `Reserved HTTP program key when httpServer.pathPrefix is empty: ${program.key}`,
+      );
+    }
+    return;
+  }
+  for (const child of program.commands) {
+    if (HTTP_RESERVED_TOP_LEVEL_SEGMENTS.has(child.key)) {
+      throw new CliSchemaValidationError(
+        `Reserved HTTP command name when httpServer.pathPrefix is empty: ${child.key} (set httpServer.pathPrefix or rename)`,
+      );
+    }
+  }
+}
+
 function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
   if (!isRoot) {
     const rogue = node as CliProgram;

package/src/docs/http-guide.ts

@@ -2,6 +2,7 @@ import { defaultConfigEntryTitle } from "~/config/entry.ts";
 import { displayAppConfigPath } from "~/config/file.ts";
 import { collectOptionDefs } from "~/core/parse.ts";
 import { CliOptionKind, type CliProgram } from "~/core/types.ts";
+import { httpUserPathGlob, resolveHttpPathPrefix } from "~/http/paths.ts";
 import { collectHttpRoutes } from "~/http/routes.ts";
 import { resolveHttpListenAddress } from "~/http/server.ts";
 
@@ -27,6 +28,9 @@ export function generateHttpGuide(root: CliProgram): string {
   const routes = collectHttpRoutes(root);
   const { hostname, port } = resolveHttpListenAddress(root);
   const baseUrl = `http://${hostname}:${port}`;
+  const pathPrefix = resolveHttpPathPrefix(root);
+  const userGlob = httpUserPathGlob(pathPrefix);
+  const sampleWorkspaces = `${pathPrefix}/workspaces`;
 
   const lines: string[] = [
     `# HTTP API (${root.key})`,
@@ -47,23 +51,23 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     "| Method | Path | Purpose |",
     "| --- | --- | --- |",
-    "| `GET` | `/health` or `/health/live` | Liveness check |",
-    "| `GET` | `/health/ready` | Readiness (config + `program.readiness`) |",
+    "| `GET` | `/health` or `/health/liveness` | Liveness check |",
+    "| `GET` | `/health/readiness` | Readiness (config + `program.readiness`) |",
     "| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |",
     "| `GET` | `/swagger` | Interactive Swagger UI API reference |",
-    "| `*` | `/api/...` | Invoke user commands (method per route) |",
+    `| * | \`${userGlob}\` | Invoke user commands (method per route) |`,
     "| `OPTIONS` | `*` | CORS preflight |",
     "",
-    "Discover paths from `openapi.json` (`/api/...`). Query binds options; POST/PUT/PATCH body binds options and `inputSchema` fields.",
+    `Discover paths from \`openapi.json\` (\`${userGlob}\`). Query binds options; POST/PUT/PATCH body binds options and \`inputSchema\` fields.`,
     "",
     "## Examples",
     "",
     "```bash",
     `curl -s ${baseUrl}/health`,
-    `curl -s ${baseUrl}/health/ready`,
+    `curl -s ${baseUrl}/health/readiness`,
     `curl -s ${baseUrl}/openapi.json`,
-    `curl -s ${baseUrl}/api/workspaces`,
-    `curl -s -X POST ${baseUrl}/api/workspaces \\`,
+    `curl -s ${baseUrl}${sampleWorkspaces}`,
+    `curl -s -X POST ${baseUrl}${sampleWorkspaces} \\`,
     '  -H "content-type: application/json" \\',
     `  -d '{"name":"qa2"}'`,
     "```",
@@ -127,7 +131,7 @@ export function generateHttpGuide(root: CliProgram): string {
     `- **Fetch** — \`curl -s ${baseUrl}/openapi.json\``,
     `- **Save offline** — \`${root.key} docs openapi --save\` → \`./docs/openapi.json\` (or \`just docgen\` in app repos)`,
     "",
-    "Use the spec to discover REST paths and request/response shapes before calling `/api/...`.",
+    `Use the spec to discover REST paths and request/response shapes before calling \`${userGlob}\`.`,
     "",
   );
 

package/src/http/openapi.ts

@@ -161,19 +161,19 @@ function livenessGetOp(operationId: string, summary: string): Record<string, unk
   };
 }
 
-/** Framework health probe paths served alongside `/api/*` routes. */
+/** Framework health probe paths served alongside user command routes. */
 function buildHealthPaths(): Record<string, unknown> {
   return {
     "/health": {
-      get: livenessGetOp("health", "Liveness probe (alias of /health/live)"),
+      get: livenessGetOp("health", "Liveness probe (alias of /health/liveness)"),
     },
-    "/health/live": {
-      get: livenessGetOp("health_live", "Liveness probe"),
+    "/health/liveness": {
+      get: livenessGetOp("health_liveness", "Liveness probe"),
     },
-    "/health/ready": {
+    "/health/readiness": {
       get: {
         tags: [HEALTH_TAG],
-        operationId: "health_ready",
+        operationId: "health_readiness",
         summary: "Readiness probe",
         description: "Config file, required app config, and optional program.readiness checks.",
         responses: {
@@ -200,7 +200,7 @@ function findTopLevelCommand(program: CliProgram, key: string): CliNode | undefi
   return program.commands.find((c) => c.key === key);
 }
 
-/** OpenAPI tags for user `/api/*` routes, one per top-level command. */
+/** 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) => {

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}/*` : "/*";
+}