argsbarg 6.0.0 → 6.0.2

package/examples/full-example/src/commands/status/schema.ts

@@ -0,0 +1,14 @@
+/** JSON stdout for `full-example status --json`. */
+export interface StatusJsonOutput {
+  /** Resolved AWS region. */
+  defaultRegion?: string;
+  /** Resolved retry count. */
+  maxRetries?: number;
+  /** Whether apiToken is set (value never included). */
+  apiTokenSet: boolean;
+  /** App version from program root. */
+  version: string;
+}
+
+/** Schemagen root for leaf outputSchema. */
+export type outputType = StatusJsonOutput;

package/examples/full-example/src/commands/status/types.ts

@@ -1,11 +1 @@
-/** JSON payload for `full-example status --json`. */
-export interface StatusJsonOutput {
-  /** Resolved AWS region. */
-  defaultRegion?: string;
-  /** Resolved retry count. */
-  maxRetries?: number;
-  /** Whether apiToken is set (value never included). */
-  apiTokenSet: boolean;
-  /** App version from program root. */
-  version: string;
-}
+export type { StatusJsonOutput } from "./schema.ts";

package/examples/full-example/{schemas/generated/app-config.json → src/config/__generated__/configSchema.json}

@@ -35,6 +35,6 @@
     "maxRetries"
   ],
   "additionalProperties": false,
-  "description": "Config schema\n\nApplication settings for `full-example` (`program.appConfig`).",
+  "description": "Application settings for `full-example` (`program.appConfig`).",
   "definitions": {}
 }

package/examples/full-example/src/config/__generated__/index.ts

@@ -0,0 +1,5 @@
+// Auto-generated by argsbarg schemagen — do not edit by hand.
+
+import configSchemaJson from "./configSchema.json";
+
+export const configSchema = configSchemaJson as Record<string, unknown>;

package/examples/full-example/src/{types.ts → config/schema.ts}

@@ -1,6 +1,4 @@
 /**
- * Config schema
- *
  * Application settings for `full-example` (`program.appConfig`).
  */
 export interface AppConfig {
@@ -21,3 +19,6 @@ export interface AppConfig {
     ttl: number;
   };
 }
+
+/** Schemagen root for program.appConfig.jsonSchema. */
+export type configType = AppConfig;

package/examples/full-example/src/program.ts

@@ -4,12 +4,12 @@ Kitchen-sink CliProgram — every argsbarg builtin enabled; command registration
 
 import type { CliAppConfig, CliAppConfigEntry, CliProgram } from "argsbarg";
 import readmeText from "../README.md" with { type: "text" };
-import { APP_CONFIG_JSON_SCHEMA } from "../schemas/configSchemas.ts";
+import { configSchema } from "./config/__generated__/index.ts";
 import { createIdentity } from "../scripts/create-identity.ts";
 import { echoCommand } from "./commands/echo/command.ts";
 import { statusCommand } from "./commands/status/command.ts";
 
-const configSchema = {
+const configEntries = {
   apiToken: {
     description: "Create at https://example.com/settings/tokens",
     env: `${createIdentity.envPrefix}_API_TOKEN`,
@@ -34,8 +34,8 @@ export const program = {
   version: "1.0.0",
   description: createIdentity.desc,
   appConfig: {
-    jsonSchema: APP_CONFIG_JSON_SCHEMA,
-    entries: configSchema,
+    jsonSchema: configSchema,
+    entries: configEntries,
   } satisfies CliAppConfig,
   docs: {
     enabled: true,

package/package.json

@@ -1,25 +1,33 @@
 {
   "name": "argsbarg",
-  "version": "6.0.0",
-  "type": "module",
-  "engines": {
-    "bun": ">=1.3"
-  },
-  "scripts": {
-    "//just": "echo this app uses justfile for development tasks"
-  },
+  "version": "6.0.2",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
-  "types": "./index.d.ts",
-  "bin": {
-    "argsbarg": "src/cli-tool/main.ts"
+  "dependencies": {
+    "ts-json-schema-generator": "^2.3.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.12",
+    "dts-bundle-generator": "^9.5.1",
+    "typescript": "^5.9.3"
   },
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "default": "./src/index.ts"
+    },
+    "./schemagen": {
+      "types": "./src/cli-tool/schemagen/index.ts",
+      "default": "./src/cli-tool/schemagen/index.ts"
     }
   },
+  "bin": {
+    "argsbarg": "src/cli-tool/main.ts"
+  },
+  "engines": {
+    "bun": ">=1.3"
+  },
   "files": [
     "src",
     "index.d.ts",
@@ -29,10 +37,9 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
-    "@types/bun": "^1.3.12",
-    "dts-bundle-generator": "^9.5.1",
-    "typescript": "^5.9.3"
-  }
+  "scripts": {
+    "//just": "echo this app uses justfile for development tasks"
+  },
+  "type": "module",
+  "types": "./index.d.ts"
 }

package/src/api/openapi.ts

@@ -4,6 +4,7 @@ Hand-built OpenAPI 3.1 document from exposed MCP tools.
 
 import { collectMcpTools } from "../mcp/tools.ts";
 import type { CliProgram } from "../types.ts";
+import { dereferenceJsonSchema } from "./schema-deref.ts";
 
 const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
 
@@ -18,8 +19,9 @@ function buildSuccessResponse(tool: ReturnType<typeof collectMcpTools>[number]):
   const media: Record<string, unknown> = {};
 
   if (contentType.includes("application/json")) {
+    const outputSchema = tool.outputSchema ?? { type: "object" };
     media[contentType] = {
-      schema: tool.outputSchema ?? { type: "object" },
+      schema: dereferenceJsonSchema(outputSchema),
     };
   } else if (contentType.includes("text/html")) {
     media[contentType] = { schema: { type: "string" } };
@@ -48,7 +50,7 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
           required: false,
           content: {
             [JSON_CONTENT_TYPE]: {
-              schema: tool.inputSchema,
+              schema: dereferenceJsonSchema(tool.inputSchema),
             },
           },
         },

package/src/api/result.ts

@@ -12,6 +12,21 @@ export interface ApiToolCallErrorBody {
   stderr?: string;
 }
 
+/** Strips ANSI escape sequences from CLI-formatted text. */
+export function stripAnsi(text: string): string {
+  const ansiEscape = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+  return text.replace(ansiEscape, "");
+}
+
+/** Returns the first non-empty line of text with ANSI escapes removed. */
+export function firstErrorLine(text: string): string {
+  const line = stripAnsi(text)
+    .split("\n")
+    .map((part) => part.trim())
+    .find((part) => part.length > 0);
+  return line ?? stripAnsi(text).trim();
+}
+
 /** Wide-open CORS headers applied to all API responses. */
 export const API_CORS_HEADERS: Readonly<Record<string, string>> = {
   "access-control-allow-origin": "*",
@@ -82,8 +97,15 @@ export function apiDocsHtml(): string {
   <title>API Reference</title>
 </head>
 <body>
-  <script id="api-reference" data-url="/openapi.json"></script>
+  <div id="api-reference"></div>
   <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  <script>
+    Scalar.createApiReference("#api-reference", {
+      url: "/openapi.json",
+      orderSchemaPropertiesBy: "preserve",
+      orderRequiredPropertiesFirst: false,
+    });
+  </script>
 </body>
 </html>`;
 }

package/src/api/schema-deref.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from "bun:test";
+import { dereferenceJsonSchema } from "./schema-deref.ts";
+
+test("dereferenceJsonSchema inlines nested definitions", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      invoice: { $ref: "#/definitions/InvoiceData" },
+    },
+    definitions: {
+      InvoiceData: {
+        type: "object",
+        properties: { id: { type: "string" } },
+        required: ["id"],
+      },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({
+    invoice: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    },
+  });
+  expect(out.definitions).toBeUndefined();
+});
+
+test("dereferenceJsonSchema supports $defs", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      item: { $ref: "#/$defs/Item" },
+    },
+    $defs: {
+      Item: { type: "string" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({ item: { type: "string" } });
+  expect(out.$defs).toBeUndefined();
+});
+
+test("dereferenceJsonSchema merges $ref siblings", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      invoice: {
+        $ref: "#/definitions/InvoiceData",
+        description: "Invoice payload",
+      },
+    },
+    definitions: {
+      InvoiceData: { type: "object" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema) as {
+    properties: { invoice: { type: string; description: string } };
+  };
+  expect(out.properties.invoice).toEqual({
+    type: "object",
+    description: "Invoice payload",
+  });
+});
+
+test("dereferenceJsonSchema ignores circular refs", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      self: { $ref: "#/definitions/Node" },
+    },
+    definitions: {
+      Node: {
+        type: "object",
+        properties: {
+          again: { $ref: "#/definitions/Node" },
+        },
+      },
+    },
+  };
+  const out = dereferenceJsonSchema(schema) as {
+    properties: { self: { type: string; properties: { again: { $ref: string } } } };
+  };
+  expect(out.properties.self.type).toBe("object");
+  expect(out.properties.self.properties.again).toEqual({ $ref: "#/definitions/Node" });
+});
+
+test("dereferenceJsonSchema leaves external refs unchanged", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      remote: { $ref: "https://example.com/schema.json" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({
+    remote: { $ref: "https://example.com/schema.json" },
+  });
+});

package/src/api/schema-deref.ts

@@ -0,0 +1,76 @@
+/*
+Inline JSON Schema $ref dereferencing for OpenAPI embedding.
+*/
+
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Resolves a same-document JSON Pointer (`#/definitions/Foo`). */
+function resolveJsonPointer(root: Record<string, unknown>, ref: string): unknown {
+  if (!ref.startsWith("#/")) {
+    return undefined;
+  }
+  const segments = ref
+    .slice(2)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (!isPlainObject(current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+function derefValue(value: unknown, root: Record<string, unknown>, resolving: Set<string>): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => derefValue(item, root, resolving));
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+
+  if (typeof value.$ref === "string") {
+    const { $ref, ...siblings } = value;
+    if (resolving.has($ref)) {
+      return value;
+    }
+    const target = resolveJsonPointer(root, $ref);
+    if (target === undefined) {
+      return value;
+    }
+    resolving.add($ref);
+    const resolved = derefValue(structuredClone(target), root, resolving);
+    resolving.delete($ref);
+    if (!isPlainObject(resolved)) {
+      return resolved;
+    }
+    if (Object.keys(siblings).length === 0) {
+      return resolved;
+    }
+    return { ...resolved, ...siblings };
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "definitions" || key === "$defs") {
+      continue;
+    }
+    out[key] = derefValue(child, root, resolving);
+  }
+  return out;
+}
+
+/** Inlines internal `$ref` pointers and drops `definitions` / `$defs` from the output. */
+export function dereferenceJsonSchema(schema: Record<string, unknown>): Record<string, unknown> {
+  const root = structuredClone(schema);
+  return derefValue(root, root, new Set()) as Record<string, unknown>;
+}

package/src/api.integration.test.ts

@@ -8,7 +8,7 @@ import { $ } from "bun";
 import { generateOpenApi } from "./api/openapi.ts";
 import { API_CORS_HEADERS } from "./api/result.ts";
 import { handleApiRequest } from "./api/server.ts";
-import { Cli, CliContext, type CliContext as CliContextType, CliOptionKind } from "./index.ts";
+import { Cli, CliContext, type CliContext as CliContextType, CliOptionKind, cliErrWithHelp } from "./index.ts";
 import { nestedMcpFixture, testProgram } from "./test-fixtures.ts";
 import { cliValidateProgram } from "./validate.ts";
 
@@ -290,6 +290,37 @@ describe("HTTP API routes", () => {
     expect(res.status).toBe(400);
     const body = (await res.json()) as { error: string };
     expect(body.error).toContain("Missing argument: path");
+    expect(body).not.toHaveProperty("stderr");
+    expect(body.error).not.toContain("\u001B[");
+  });
+
+  test("POST /tools/:name returns plain JSON validation errors", async () => {
+    const failProgram = testProgram({
+      key: "app",
+      description: "Test app",
+      apiServer: { enabled: true },
+      commands: [
+        {
+          key: "fail",
+          description: "Fails with cliErrWithHelp.",
+          handler: (ctx: CliContextType) => {
+            cliErrWithHelp(ctx, "bad input");
+          },
+        },
+      ],
+    });
+    cliValidateProgram(failProgram);
+    const res = await apiRequest(
+      failProgram,
+      new Request("http://127.0.0.1/tools/fail", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toEqual({ error: "bad input" });
   });
 
   test("GET /openapi.json lists tool paths", async () => {
@@ -304,7 +335,10 @@ describe("HTTP API routes", () => {
     const res = await apiRequest(program, new Request("http://127.0.0.1/openapi-browser"));
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toContain("text/html");
-    expect(await res.text()).toContain("@scalar/api-reference");
+    const html = await res.text();
+    expect(html).toContain("@scalar/api-reference");
+    expect(html).toContain('orderSchemaPropertiesBy: "preserve"');
+    expect(html).toContain("orderRequiredPropertiesFirst: false");
   });
 });
 
@@ -319,6 +353,55 @@ test("generateOpenApi maps binary content types", () => {
   expect(pdf.schema.format).toBe("binary");
 });
 
+test("generateOpenApi dereferences nested inputSchema definitions", () => {
+  const program = testProgram({
+    key: "app",
+    description: "Test app",
+    apiServer: { enabled: true },
+    commands: [
+      {
+        key: "render",
+        description: "Render a document.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            invoice: { $ref: "#/definitions/InvoiceData" },
+          },
+          definitions: {
+            InvoiceData: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+              },
+              required: ["id"],
+            },
+          },
+        },
+        handler: () => ({ ok: true }),
+      },
+    ],
+  });
+  cliValidateProgram(program);
+  const doc = generateOpenApi(program) as {
+    paths: Record<
+      string,
+      {
+        post: {
+          requestBody: {
+            content: Record<string, { schema: { properties: { invoice: Record<string, unknown> } } }>;
+          };
+        };
+      }
+    >;
+  };
+  const schema = doc.paths["/tools/render"]?.post.requestBody.content["application/json; charset=utf-8"].schema;
+  expect(schema.properties.invoice).toEqual({
+    type: "object",
+    properties: { id: { type: "string" } },
+    required: ["id"],
+  });
+});
+
 test("ctx.respond throws when called twice", () => {
   const program = testProgram({
     key: "app",

package/src/cli-errors.ts

@@ -7,6 +7,9 @@ import type { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
 
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
+  if (ctx.invocation === "api" || ctx.invocation === "mcp") {
+    throw new Error(msg);
+  }
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
   process.stderr.write(`${line}\n`);

package/src/cli-tool/full-example-capabilities.test.ts

@@ -63,7 +63,8 @@ describe("full-example template", () => {
 
   test("status command defines outputSchema", () => {
     const statusSource = readFileSync(join(exampleRoot, "src/commands/status/command.ts"), "utf8");
-    expect(statusSource).toContain("outputSchema:");
+    expect(statusSource).toMatch(/outputSchema[,:]/);
+    expect(statusSource).toContain('from "./__generated__/index.ts"');
   });
 
   test("resolveCapabilities matches full sink shape", () => {

package/src/cli-tool/post-create.ts

@@ -41,10 +41,10 @@ export async function runPostCreate(targetDir: string, dryRun: boolean): Promise
       },
     },
     {
-      label: "bun scripts/schemagen.ts",
+      label: "argsbarg schemagen",
       run: () => {
         if (dryRun) return;
-        const proc = Bun.spawnSync(["bun", "scripts/schemagen.ts"], {
+        const proc = Bun.spawnSync(["argsbarg", "schemagen"], {
           cwd: abs,
           stdout: "inherit",
           stderr: "inherit",
@@ -103,7 +103,7 @@ export async function runPostCreate(targetDir: string, dryRun: boolean): Promise
 export function printPostCreatePlan(): void {
   process.stderr.write("Post-create steps:\n");
   process.stderr.write("  1. bun install\n");
-  process.stderr.write("  2. bun scripts/schemagen.ts\n");
+  process.stderr.write("  2. just schemagen\n");
   process.stderr.write("  3. bun test\n");
   process.stderr.write("  4. git init + Initial commit (skipped inside existing git work tree)\n");
 }

package/src/cli-tool/program.ts

@@ -5,6 +5,7 @@ Argsbarg developer tools — bootstrap consumer CLIs via `create`.
 import pkg from "../../package.json" with { type: "json" };
 import { CliOptionKind, type CliProgram } from "../index.ts";
 import { runCreate } from "./run-create.ts";
+import { runSchemagenCli } from "./run-schemagen.ts";
 
 export const program = {
   key: "argsbarg",
@@ -92,5 +93,39 @@ export const program = {
         process.exit(code);
       },
     },
+    {
+      key: "schemagen",
+      description: "Generate JSON Schema artifacts from src/**/schema.ts into colocated __generated__/ directories.",
+      options: [
+        {
+          name: "root",
+          description: "Project root (default: current working directory).",
+          kind: CliOptionKind.String,
+        },
+        {
+          name: "src-dir",
+          description: "Source directory relative to --root (default: src).",
+          kind: CliOptionKind.String,
+        },
+        {
+          name: "tsconfig",
+          description: "Path to tsconfig relative to --root (default: tsconfig.json).",
+          kind: CliOptionKind.String,
+        },
+      ],
+      handler: (ctx) => {
+        try {
+          runSchemagenCli({
+            root: ctx.stringOpt("root"),
+            srcDir: ctx.stringOpt("src-dir"),
+            tsconfig: ctx.stringOpt("tsconfig"),
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          process.stderr.write(`${message}\n`);
+          process.exit(1);
+        }
+      },
+    },
   ],
 } satisfies CliProgram;

package/src/cli-tool/run-schemagen.ts

@@ -0,0 +1,23 @@
+/** Run argsbarg schemagen in the current working directory (or `--root`). */
+
+import { resolve } from "node:path";
+import { runSchemagen } from "./schemagen/run.ts";
+
+export interface RunSchemagenCliOptions {
+  root?: string;
+  srcDir?: string;
+  tsconfig?: string;
+}
+
+/** Exit 0 on success; throws on failure. */
+export function runSchemagenCli(options: RunSchemagenCliOptions = {}): void {
+  const projectRoot = resolve(options.root ?? process.cwd());
+  const counts = runSchemagen({
+    projectRoot,
+    srcDir: options.srcDir,
+    tsconfig: options.tsconfig,
+  });
+  console.log(
+    `config roots: ${counts.configRoots}, input roots: ${counts.inputRoots}, output roots: ${counts.outputRoots}`,
+  );
+}