argsbarg 6.1.2 → 6.1.3

package/src/{mcp.integration.test.ts → test/integration/mcp.test.ts}

@@ -5,19 +5,18 @@ Domain-specific regression tests (split from index.test.ts).
 import { expect, test } from "bun:test";
 import { join } from "node:path";
 import { $ } from "bun";
-import type { CliProgram } from "./index.ts";
-import { buildToolCallSuccessFromResponse } from "./mcp/result.ts";
+import { cliSchemaExport } from "~/core/schema.ts";
+import { cliValidateProgram } from "~/core/validate.ts";
+import type { CliProgram } from "~/index";
+import { buildToolCallSuccessFromResponse } from "~/mcp/result.ts";
 import {
-  apiToolName,
   collectMcpTools,
   mcpToolCallToArgv,
   mcpToolDescription,
   mcpToolName,
   sanitizeToolSegment,
-} from "./mcp/tools.ts";
-import { cliSchemaExport } from "./schema.ts";
-import { mcpRequest, nestedMcpFixture, testProgram } from "./test-fixtures.ts";
-import { cliValidateProgram } from "./validate.ts";
+} from "~/mcp/tools.ts";
+import { mcpRequest, nestedMcpFixture, testProgram } from "~/test/fixtures.ts";
 
 test("sanitizeToolSegment normalizes dotted app keys", () => {
   expect(sanitizeToolSegment("minimal.ts")).toBe("minimal_ts");
@@ -31,10 +30,8 @@ test("mcpToolDescription formats CLI path and root-leaf prefix", () => {
   expect(mcpToolDescription([], "helloapp", "Tiny demo.")).toBe("helloapp — Tiny demo.");
 });
 
-test("apiToolName hyphen-joins path; mcpToolName sanitizes to underscores", () => {
-  expect(apiToolName(nestedMcpFixture, ["stat", "owner", "lookup"])).toBe("stat-owner-lookup");
+test("mcpToolName sanitizes path segments to underscores", () => {
   expect(mcpToolName(nestedMcpFixture, ["stat", "owner", "lookup"])).toBe("stat_owner_lookup");
-  expect(apiToolName(nestedMcpFixture, ["render-invoice"])).toBe("render-invoice");
   expect(mcpToolName(nestedMcpFixture, ["render-invoice"])).toBe("render_invoice");
 });
 
@@ -43,7 +40,6 @@ test("collectMcpTools lists user leaf commands only", () => {
   const names = tools.map((t) => t.name);
   expect(names).toContain("stat_owner_lookup");
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
-  expect(lookup.apiName).toBe("stat-owner-lookup");
   expect(lookup.description).toBe("stat owner lookup — Resolve owner info.");
   expect(names).toContain("read");
   expect(names).not.toContain("hidden");
@@ -104,13 +100,13 @@ test("collectMcpTools resolves {argsbarg:program} in appended notes", () => {
       {
         key: "run",
         description: "Run.",
-        notes: "See `{argsbarg:program} docs api`.",
+        notes: "See `{argsbarg:program} docs cli`.",
         handler: () => {},
       },
     ],
   });
   const tools = collectMcpTools(root);
-  expect(tools[0]?.description).toContain("See `myapp docs api`.");
+  expect(tools[0]?.description).toContain("See `myapp docs cli`.");
 });
 
 /** CliSchemaExport includes leaf outputSchema. */
@@ -139,29 +135,6 @@ test("cliSchemaExport includes leaf outputSchema", () => {
   });
 });
 
-/** CliSchemaExport accepts legacy mcpTool.outputSchema. */
-test("cliSchemaExport accepts legacy mcpTool.outputSchema", () => {
-  const root = testProgram({
-    key: "app",
-    version: "1.0.0",
-    description: "Schema export demo.",
-    commands: [
-      {
-        key: "run",
-        description: "Run.",
-        mcpTool: {
-          outputSchema: { type: "object", properties: { id: { type: "string" } } },
-        },
-        handler: () => {},
-      },
-    ],
-  });
-  expect(cliSchemaExport(root).commands?.[0]?.outputSchema).toEqual({
-    type: "object",
-    properties: { id: { type: "string" } },
-  });
-});
-
 /** Tests that outputSchema must be a JSON Schema object. */
 test("outputSchema must be a JSON Schema object", () => {
   const root = testProgram({
@@ -180,25 +153,6 @@ test("outputSchema must be a JSON Schema object", () => {
   expect(() => cliValidateProgram(root)).toThrow(/outputSchema must be a JSON Schema object/);
 });
 
-/** Tests that outputSchema cannot be set on both leaf and mcpTool. */
-test("outputSchema cannot be set on both leaf and mcpTool", () => {
-  const root = testProgram({
-    key: "app",
-    version: "1.0.0",
-    description: "Duplicate output schema.",
-    commands: [
-      {
-        key: "run",
-        description: "Run.",
-        outputSchema: { type: "object" },
-        mcpTool: { outputSchema: { type: "object" } },
-        handler: () => {},
-      },
-    ],
-  });
-  expect(() => cliValidateProgram(root)).toThrow(/Set outputSchema on the leaf only/);
-});
-
 test("collectMcpTools merges parent options into inputSchema", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
@@ -419,7 +373,7 @@ test("MCP resources/read returns schema JSON", async () => {
 
 /** MCP tools/call runs stat_owner_lookup. */
 test("MCP tools/call runs stat_owner_lookup", async () => {
-  const readme = join(import.meta.dir, "..", "README.md");
+  const readme = join(import.meta.dir, "..", "..", "..", "README.md");
   const responses = await mcpRequest([
     {
       jsonrpc: "2.0",
@@ -440,7 +394,7 @@ test("MCP tools/call runs stat_owner_lookup", async () => {
 
 /** MCP tools/call returns structuredContent for JSON stdout. */
 test("MCP tools/call returns structuredContent for JSON stdout", async () => {
-  const readme = join(import.meta.dir, "..", "README.md");
+  const readme = join(import.meta.dir, "..", "..", "..", "README.md");
   const responses = await mcpRequest([
     {
       jsonrpc: "2.0",

package/docs/api-server.md

@@ -1,141 +0,0 @@
-# HTTP API server
-
-ArgsBarg can expose your CLI as an HTTP tool server. Each **leaf command** becomes a callable tool — the same exposure model as MCP. The server uses Bun's built-in HTTP stack and binds to **localhost by default**.
-
-The HTTP API is **opt-in**. Apps that do not set `apiServer` on the program root behave exactly as before.
-
-## Quick start
-
-1. Add `apiServer` to your program root:
-
-```typescript
-import pkg from "../package.json" with { type: "json" };
-
-const cli = {
-  key: "myapp",
-  version: pkg.version,
-  description: "My app.",
-  apiServer: { enabled: true },
-  commands: [/* ... */],
-} satisfies CliProgram;
-```
-
-`apiServer: { enabled: true }` opts in. Omit `apiServer` entirely to disable HTTP. Empty `apiServer: {}` is rejected at validation.
-
-2. Run the HTTP server:
-
-```bash
-myapp api
-```
-
-The process listens until interrupted. Startup prints the listen URL to stderr.
-
-## Configuration
-
-Set `apiServer` on the **program root only**. Validation rejects `apiServer` on nested nodes.
-
-| Field | Default | Purpose |
-| --- | --- | --- |
-| `enabled` | *(required)* | Must be `true` when `apiServer` is set |
-| `host` | `127.0.0.1` | Listen address |
-| `port` | `3000` | Listen port |
-
-`apiServer` and `mcpServer` are independent — enable either or both.
-
-## Tool names
-
-HTTP and MCP use different tool identifiers for the same leaf command:
-
-| CLI path | HTTP API (`POST /tools/:name`) | MCP (`tools/call`) |
-| --- | --- | --- |
-| `stat owner lookup` | `stat-owner-lookup` | `stat_owner_lookup` |
-| `render-invoice` | `render-invoice` | `render_invoice` |
-
-OpenAPI `paths` use the API id (`/tools/render-invoice`, etc.).
-
-## Endpoints
-
-| Method | Path | Purpose |
-| --- | --- | --- |
-| `GET` | `/health` | Liveness check |
-| `GET` | `/openapi.json` | OpenAPI 3.1 document (per-tool `POST /tools/{name}` paths) |
-| `GET` | `/openapi-browser` | Interactive Scalar API reference (CDN) |
-| `POST` | `/tools/:name` | Invoke tool; body is a flat JSON args object |
-| `OPTIONS` | `*` | CORS preflight (wide-open `Access-Control-Allow-Origin: *`) |
-
-## Examples
-
-```bash
-curl -s http://127.0.0.1:3000/health
-curl -s http://127.0.0.1:3000/openapi.json
-open http://127.0.0.1:3000/openapi-browser
-curl -s -X POST http://127.0.0.1:3000/tools/{tool-key} \
-  -H 'content-type: application/json' \
-  -d '{...}'
-```
-
-Replace `{tool-key}` with a path segment from `openapi.json` (`paths` keys are `/tools/{tool-key}`); body keys match that tool's flat JSON args (see `docs cli-schema` or `openapi.json`).
-
-## Handler responses (`ctx.respond()`)
-
-API and MCP tool handlers must return machine-readable output via **`ctx.respond()`** or by **returning a value** (implicit JSON). `console.log` is not included in HTTP/MCP success payloads.
-
-```typescript
-handler: (ctx) => {
-  if (ctx.hasFlag("json")) {
-    return { user: "alice", path: "/tmp" };
-  }
-  ctx.respond({
-    body: pdfBytes,
-    contentType: "application/pdf",
-    headers: { "Content-Disposition": 'inline; filename="invoice.pdf"' },
-  });
-},
-```
-
-**CLI mode:** `ctx.respond()` prints to stdout (JSON pretty-printed, strings as-is, `Uint8Array` as raw bytes). Handlers may still use `console.log` for human-only CLI output.
-
-### Leaf metadata
-
-```typescript
-apiResponse?: {
-  contentType?: string;           // default application/json
-  contentDisposition?: string;    // e.g. attachment; filename="invoice.pdf"
-};
-```
-
-Used by OpenAPI and as a default `Content-Type` when the handler does not set one.
-
-## Responses
-
-**Success (`200`):** raw body — no `{ ok, stdout }` envelope.
-
-| Body type | HTTP `Content-Type` |
-| --- | --- |
-| object / array | `application/json` |
-| string | handler `contentType` or `text/plain` |
-| `Uint8Array` | e.g. `application/pdf` (required on `respond()`) |
-
-**Errors:** JSON `{ "error": "...", "exitCode?": number }` with `400` (bad args), `404` (unknown tool), `503` (missing config), or `500` (handler failure).
-
-## MCP binary payloads
-
-Binary `ctx.respond()` bodies are encoded in MCP `structuredContent` as:
-
-```json
-{ "data": "<base64>", "contentType": "application/pdf", "encoding": "base64" }
-```
-
-String bodies use `{ "content": "...", "contentType": "..." }`. JSON objects are returned as-is in `structuredContent`.
-
-## CORS
-
-All responses include wide-open CORS headers (`Access-Control-Allow-Origin: *`). Not configurable in v1.
-
-## OpenAPI
-
-Call `generateOpenApi(program)` or `openApiJson(program)` from the package, fetch `GET /openapi.json` from a running server, or run `myapp docs openapi` / `myapp docs openapi --save` (writes `./docs/openapi.json` when `docs.enabled` and `apiServer.enabled`). Nested `inputSchema` / `outputSchema` `$ref` pointers are dereferenced when the OpenAPI document is built so API reference UIs can show nested request shapes.
-
-## Complex tool inputs
-
-For nested request bodies (e.g. invoice template data), set `inputSchema` on the leaf, declare a matching `kind: Json` option (optionally `pipable: true` for CLI stdin), and read inputs with `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — piped stdin is loaded before the handler runs.