argsbarg 6.1.5 → 6.1.6

package/CHANGELOG.md

@@ -7,20 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.6] - 2026-07-24
+
+
 ## [6.1.5] - 2026-07-24
 
 ### Changed
 
 - **`httpServer.pathPrefix`** — configurable URL prefix for user routes (default `""`; routes at server root, e.g. `/workspaces`). Set `"/api"` for prefixed paths.
+- **Health probes** — removed `GET /health` liveness alias; use `GET /health/liveness`. OpenAPI descriptions clarify liveness (online) vs readiness (online + checks passed).
 
 ## [6.1.4] - 2026-07-24
 
 ### Changed
 
 - **`GET /swagger`** — Swagger UI API reference (replaces `GET /openapi-browser` and Scalar).
-- **`GET /openapi.json`** — documents `/health`, `/health/liveness`, and `/health/readiness` probe endpoints under a **Health** tag.
+- **`GET /openapi.json`** — documents `/health/liveness` and `/health/readiness` probe endpoints under a **Health** tag.
 - **OpenAPI tags** — user `/api/*` routes are grouped by top-level command key (router `description` becomes the tag description).
-- **Health probe paths** — `GET /health/liveness` and `GET /health/readiness` replace `/health/live` and `/health/ready` (`GET /health` remains a liveness alias).
+- **Health probe paths** — `GET /health/liveness` and `GET /health/readiness` replace `/health/live` and `/health/ready`.
 - **`httpServer.pathPrefix`** — configurable URL prefix for user routes (default `""`; routes at server root, e.g. `/workspaces`). Set `"/api"` for prefixed paths.
 
 ## [6.1.3] - 2026-07-24
@@ -849,7 +853,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.5...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.6...HEAD
+[6.1.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.6
 [6.1.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.5
 [6.1.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.4
 [6.1.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.3

package/docs/http-server.md

@@ -76,8 +76,8 @@ Per-surface exposure: `http.enabled: false` removes a leaf from the route table;
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/health` or `/health/liveness` | Liveness — 200 when server is listening |
-| `GET` | `/health/readiness` | Readiness — config + optional `program.readiness` |
+| `GET` | `/health/liveness` | Liveness — server is online and accepting requests |
+| `GET` | `/health/readiness` | Readiness — online plus config and optional `program.readiness` checks passed |
 | `GET` | `/openapi.json` | OpenAPI 3.1 REST paths (includes `/health/*` and user routes) |
 | `GET` | `/swagger` | Interactive Swagger UI API reference (CDN) |
 | `*` | `/{command}/...` | Invoke user commands (method per route; optional `pathPrefix`) |
@@ -88,7 +88,7 @@ Per-surface exposure: `http.enabled: false` removes a leaf from the route table;
 ## Examples
 
 ```bash
-curl -s http://127.0.0.1:3000/health
+curl -s http://127.0.0.1:3000/health/liveness
 curl -s http://127.0.0.1:3000/health/readiness
 curl -s http://127.0.0.1:3000/openapi.json
 open http://127.0.0.1:3000/swagger

package/examples/full-example/docs/cli-schema.json

@@ -191,7 +191,7 @@
         {
           "key": "http",
           "description": "HTTP API server for tools.",
-          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
           "options": [
             {
               "name": "host",
@@ -424,7 +424,7 @@
         {
           "key": "http",
           "description": "HTTP API server for tools.",
-          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
           "options": [
             {
               "name": "host",
@@ -679,7 +679,7 @@
         {
           "key": "http",
           "description": "HTTP API server for tools.",
-          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
           "options": [
             {
               "name": "host",
@@ -916,7 +916,7 @@
             {
               "key": "http",
               "description": "HTTP API server for tools.",
-              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
               "options": [
                 {
                   "name": "host",
@@ -1149,7 +1149,7 @@
             {
               "key": "http",
               "description": "HTTP API server for tools.",
-              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
               "options": [
                 {
                   "name": "host",
@@ -1386,7 +1386,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",
@@ -1619,7 +1619,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",
@@ -1852,7 +1852,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",
@@ -2085,7 +2085,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",

package/examples/full-example/docs/cli.md

@@ -213,7 +213,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -426,7 +426,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -667,7 +667,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -890,7 +890,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -1103,7 +1103,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -1327,7 +1327,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -1540,7 +1540,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -1753,7 +1753,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 
@@ -1966,7 +1966,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, /*
+> Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, /*
 > 
 > Configure app settings:
 > 

package/examples/full-example/docs/http.md

@@ -16,8 +16,8 @@ Bind is localhost-only in v0 — use a reverse proxy for remote access.
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/health` or `/health/liveness` | Liveness check |
-| `GET` | `/health/readiness` | 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 |
 | * | `/*` | Invoke user commands (method per route) |
@@ -28,7 +28,7 @@ Discover paths from `openapi.json` (`/*`). Query binds options; POST/PUT/PATCH b
 ## Examples
 
 ```bash
-curl -s http://127.0.0.1:3000/health
+curl -s http://127.0.0.1:3000/health/liveness
 curl -s http://127.0.0.1:3000/health/readiness
 curl -s http://127.0.0.1:3000/openapi.json
 curl -s http://127.0.0.1:3000/workspaces

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

@@ -8,7 +8,7 @@
   "tags": [
     {
       "name": "health",
-      "description": "Server health probes"
+      "description": "Orchestrator health probes — liveness (online) vs readiness (online + checks passed)."
     },
     {
       "name": "echo",
@@ -28,36 +28,6 @@
     }
   ],
   "paths": {
-    "/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": [
@@ -65,9 +35,10 @@
         ],
         "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 listening",
+            "description": "Server is online",
             "content": {
               "application/json; charset=utf-8": {
                 "schema": {
@@ -95,10 +66,10 @@
         ],
         "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": {
-            "description": "Ready to serve traffic",
+            "description": "Online and ready to serve traffic",
             "content": {
               "application/json; charset=utf-8": {
                 "schema": {
@@ -187,7 +158,7 @@
             }
           },
           "503": {
-            "description": "Not ready",
+            "description": "Online but not ready (one or more checks failed)",
             "content": {
               "application/json; charset=utf-8": {
                 "schema": {

package/package.json

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

package/src/builtins/http.ts

@@ -39,7 +39,7 @@ export function cliBuiltinHttpCommand(program: CliProgram): CliRouter {
   const lines = [
     `HTTP tool server on http://${hostname}:${port}.`,
     "",
-    `Endpoints: GET /health, GET /health/readiness, GET /openapi.json, GET /swagger, ${userGlob}`,
+    `Endpoints: GET /health/liveness, GET /health/readiness, GET /openapi.json, GET /swagger, ${userGlob}`,
     "",
   ];
   if (caps.configure) {

package/src/docs/http-guide.ts

@@ -51,8 +51,8 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     "| Method | Path | Purpose |",
     "| --- | --- | --- |",
-    "| `GET` | `/health` or `/health/liveness` | Liveness check |",
-    "| `GET` | `/health/readiness` | 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 |",
     `| * | \`${userGlob}\` | Invoke user commands (method per route) |`,
@@ -63,7 +63,7 @@ export function generateHttpGuide(root: CliProgram): string {
     "## Examples",
     "",
     "```bash",
-    `curl -s ${baseUrl}/health`,
+    `curl -s ${baseUrl}/health/liveness`,
     `curl -s ${baseUrl}/health/readiness`,
     `curl -s ${baseUrl}/openapi.json`,
     `curl -s ${baseUrl}${sampleWorkspaces}`,

package/src/http/openapi.ts

@@ -150,13 +150,15 @@ 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),
     },
   };
 }
@@ -164,21 +166,19 @@ function livenessGetOp(operationId: string, summary: string): Record<string, unk
 /** 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"),
+      get: livenessGetOp(),
     },
     "/health/readiness": {
       get: {
         tags: [HEALTH_TAG],
         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),
         },
       },
     },
@@ -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,
   };

package/src/http/server.ts

@@ -112,7 +112,7 @@ export async function handleApiRequest(
   const root = cli.program;
   const path = url.pathname;
 
-  if (request.method === "GET" && (path === "/health" || path === "/health/liveness")) {
+  if (request.method === "GET" && path === "/health/liveness") {
     return finish(jsonResponse(200, { ok: true }));
   }
 

package/src/test/integration/http.test.ts

@@ -289,8 +289,8 @@ describe("HTTP API routes", () => {
     expect(body.error).toBe("An unexpected error occurred.");
   });
 
-  test("GET /health includes CORS headers", async () => {
-    const res = await apiRequest(program, new Request("http://127.0.0.1/health"));
+  test("GET /health/liveness includes CORS headers", async () => {
+    const res = await apiRequest(program, new Request("http://127.0.0.1/health/liveness"));
     expect(res.status).toBe(200);
     expect(res.headers.get("access-control-allow-origin")).toBe("*");
     expect(await res.json()).toEqual({ ok: true });
@@ -449,9 +449,9 @@ describe("HTTP API routes", () => {
     const doc = (await res.json()) as { openapi: string; paths: Record<string, unknown> };
     expect(doc.openapi).toBe("3.1.0");
     expect(doc.paths["/stat/owner/lookup"]).toBeDefined();
-    expect(doc.paths["/health"]).toBeDefined();
     expect(doc.paths["/health/liveness"]).toBeDefined();
     expect(doc.paths["/health/readiness"]).toBeDefined();
+    expect(doc.paths["/health"]).toBeUndefined();
   });
 
   test("GET /swagger returns Swagger UI HTML", async () => {
@@ -480,13 +480,17 @@ test("generateOpenApi includes health probe paths", () => {
       {
         get: {
           tags: string[];
+          summary: string;
           responses: Record<string, { content: Record<string, { schema: Record<string, unknown> }> }>;
         };
       }
     >;
   };
   expect(doc.tags.some((t) => t.name === "health")).toBe(true);
-  expect(doc.paths["/health"]?.get.tags).toContain("health");
+  expect(doc.paths["/health"]).toBeUndefined();
+  expect(doc.paths["/health/liveness"]?.get.tags).toContain("health");
+  expect(doc.paths["/health/liveness"]?.get.summary).toBe("Liveness probe");
+  expect(doc.paths["/health/readiness"]?.get.summary).toBe("Readiness probe");
   expect(doc.paths["/health/liveness"]?.get.responses["200"]).toBeDefined();
   expect(doc.paths["/health/readiness"]?.get.responses["200"]).toBeDefined();
   expect(doc.paths["/health/readiness"]?.get.responses["503"]).toBeDefined();