argsbarg 6.1.4 → 6.1.6

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

@@ -5,10 +5,256 @@
     "version": "1.0.0",
     "description": "Argsbarg full example reference app"
   },
+  "tags": [
+    {
+      "name": "health",
+      "description": "Orchestrator health probes — liveness (online) vs readiness (online + checks passed)."
+    },
+    {
+      "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/liveness": {
+      "get": {
+        "tags": [
+          "health"
+        ],
+        "operationId": "health_liveness",
+        "summary": "Liveness probe",
+        "description": "Returns 200 when the HTTP server is online and accepting requests. Does not run config or readiness checks — use for orchestrator liveness probes only.",
+        "responses": {
+          "200": {
+            "description": "Server is online",
+            "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": "Returns 200 when the server is online and all readiness checks pass (config file, required app config, and optional program.readiness). Returns 503 when any check fails — use for orchestrator readiness probes before routing traffic.",
+        "responses": {
+          "200": {
+            "description": "Online and 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": "Online but not ready (one or more checks failed)",
+            "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 +361,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 +475,12 @@
         }
       }
     },
-    "/api/status": {
+    "/status": {
       "post": {
-        "operationId": "_api_status",
+        "tags": [
+          "status"
+        ],
+        "operationId": "_status",
         "summary": "Show app version.",
         "responses": {
           "201": {
@@ -343,9 +595,12 @@
         }
       }
     },
-    "/api/workspaces": {
+    "/workspaces": {
       "get": {
-        "operationId": "_api_workspaces",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces",
         "summary": "List workspaces.",
         "responses": {
           "200": {
@@ -434,7 +689,10 @@
         "parameters": []
       },
       "post": {
-        "operationId": "_api_workspaces",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces",
         "summary": "Create a workspace.",
         "responses": {
           "201": {
@@ -543,9 +801,12 @@
         }
       }
     },
-    "/api/workspaces/{id}": {
+    "/workspaces/{id}": {
       "get": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Get one workspace.",
         "responses": {
           "200": {
@@ -643,7 +904,10 @@
         ]
       },
       "put": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Replace a workspace.",
         "responses": {
           "200": {
@@ -762,7 +1026,10 @@
         }
       },
       "patch": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Patch a workspace name.",
         "responses": {
           "200": {
@@ -881,7 +1148,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.6",
   "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/liveness, 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/liveness` | Liveness — server is online and accepting requests |",
+    "| `GET` | `/health/readiness` | Readiness — online plus config and `program.readiness` checks passed |",
     "| `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/liveness`,
+    `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

@@ -150,35 +150,35 @@ function jsonResponseEntry(description: string, schema: Record<string, unknown>)
   };
 }
 
-function livenessGetOp(operationId: string, summary: string): Record<string, unknown> {
+function livenessGetOp(): Record<string, unknown> {
   return {
     tags: [HEALTH_TAG],
-    operationId,
-    summary,
+    operationId: "health_liveness",
+    summary: "Liveness probe",
+    description:
+      "Returns 200 when the HTTP server is online and accepting requests. Does not run config or readiness checks — use for orchestrator liveness probes only.",
     responses: {
-      "200": jsonResponseEntry("Server is listening", livenessResponseSchema),
+      "200": jsonResponseEntry("Server is online", livenessResponseSchema),
     },
   };
 }
 
-/** 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)"),
+    "/health/liveness": {
+      get: livenessGetOp(),
     },
-    "/health/live": {
-      get: livenessGetOp("health_live", "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.",
+        description:
+          "Returns 200 when the server is online and all readiness checks pass (config file, required app config, and optional program.readiness). Returns 503 when any check fails — use for orchestrator readiness probes before routing traffic.",
         responses: {
-          "200": jsonResponseEntry("Ready to serve traffic", readinessResponseSchema),
-          "503": jsonResponseEntry("Not ready", readinessResponseSchema),
+          "200": jsonResponseEntry("Online and ready to serve traffic", readinessResponseSchema),
+          "503": jsonResponseEntry("Online but not ready (one or more checks failed)", readinessResponseSchema),
         },
       },
     },
@@ -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) => {
@@ -278,7 +278,15 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
       description: program.description,
     },
     ...(program.httpServer?.enabled
-      ? { tags: [{ name: HEALTH_TAG, description: "Server health probes" }, ...commandTags] }
+      ? {
+          tags: [
+            {
+              name: HEALTH_TAG,
+              description: "Orchestrator health probes — liveness (online) vs readiness (online + checks passed).",
+            },
+            ...commandTags,
+          ],
+        }
       : {}),
     paths,
   };