argsbarg 6.1.3 → 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": {
@@ -202,12 +480,36 @@
               }
             }
           }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json; charset=utf-8": {
+              "schema": {
+                "$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {
+                  "message": {
+                    "type": "string",
+                    "description": "Message to echo back."
+                  }
+                },
+                "required": [
+                  "message"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
         }
       }
     },
-    "/api/status": {
+    "/status": {
       "post": {
-        "operationId": "_api_status",
+        "tags": [
+          "status"
+        ],
+        "operationId": "_status",
         "summary": "Show app version.",
         "responses": {
           "201": {
@@ -322,9 +624,12 @@
         }
       }
     },
-    "/api/workspaces": {
+    "/workspaces": {
       "get": {
-        "operationId": "_api_workspaces",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces",
         "summary": "List workspaces.",
         "responses": {
           "200": {
@@ -413,7 +718,10 @@
         "parameters": []
       },
       "post": {
-        "operationId": "_api_workspaces",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces",
         "summary": "Create a workspace.",
         "responses": {
           "201": {
@@ -522,9 +830,12 @@
         }
       }
     },
-    "/api/workspaces/{id}": {
+    "/workspaces/{id}": {
       "get": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Get one workspace.",
         "responses": {
           "200": {
@@ -622,7 +933,10 @@
         ]
       },
       "put": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Replace a workspace.",
         "responses": {
           "200": {
@@ -741,7 +1055,10 @@
         }
       },
       "patch": {
-        "operationId": "_api_workspaces_id",
+        "tags": [
+          "workspaces"
+        ],
+        "operationId": "_workspaces_id",
         "summary": "Patch a workspace name.",
         "responses": {
           "200": {
@@ -860,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.3",
+  "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 /openapi-browser, /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` | `/openapi-browser` | Interactive Scalar API reference |",
-    "| `*` | `/api/...` | Invoke user commands (method per route) |",
+    "| `GET` | `/swagger` | Interactive Swagger UI API reference |",
+    `| * | \`${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"}'`,
     "```",
@@ -111,7 +115,7 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     "POST/PUT/PATCH bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
     "",
-    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /openapi-browser\`**) for per-route request shapes.`,
+    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /swagger\`**) for per-route request shapes.`,
     "",
     "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
     "Options with `format: comma-list` accept a comma-separated string or JSON array.",
@@ -123,11 +127,11 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     "The HTTP API is described in OpenAPI 3.1.",
     "",
-    `- **Browse** — [${baseUrl}/openapi-browser](${baseUrl}/openapi-browser) (Scalar UI; loads \`/openapi.json\`)`,
+    `- **Browse** — [${baseUrl}/swagger](${baseUrl}/swagger) (Swagger UI; loads \`/openapi.json\`)`,
     `- **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}\`.`,
     "",
   );