argsbarg 6.0.0 → 6.0.2

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

@@ -0,0 +1,60 @@
+/*
+Remove stale __generated__/ directories and files after schemagen runs.
+*/
+
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import type { SchemaRoot } from "./discover-schema-roots.ts";
+import { GENERATED_DIR, SCHEMA_FILE, schemaJsonBasename } from "./names.ts";
+
+function listGeneratedDirs(srcDir: string, projectRoot: string, out: string[]): void {
+  for (const ent of readdirSync(srcDir)) {
+    const full = join(srcDir, ent);
+    const st = statSync(full);
+    if (!st.isDirectory()) {
+      continue;
+    }
+    if (ent === GENERATED_DIR) {
+      out.push(relative(projectRoot, full));
+      continue;
+    }
+    listGeneratedDirs(full, projectRoot, out);
+  }
+}
+
+/** Drop orphan `__generated__/` trees and JSON files for removed schema kinds. */
+export function cleanStaleGenerated(
+  projectRoot: string,
+  srcDir: string,
+  activeBySchemaFile: Map<string, SchemaRoot[]>,
+): void {
+  const srcPath = join(projectRoot, srcDir);
+  if (!existsSync(srcPath)) {
+    return;
+  }
+
+  const generatedDirs: string[] = [];
+  listGeneratedDirs(srcPath, projectRoot, generatedDirs);
+
+  for (const relGeneratedDir of generatedDirs) {
+    const generatedDir = join(projectRoot, relGeneratedDir);
+    const relSchemaPath = relative(projectRoot, join(dirname(generatedDir), SCHEMA_FILE));
+    const roots = existsSync(join(projectRoot, relSchemaPath)) ? (activeBySchemaFile.get(relSchemaPath) ?? []) : [];
+
+    if (roots.length === 0) {
+      rmSync(generatedDir, { recursive: true, force: true });
+      console.log(`removed ${relGeneratedDir}`);
+      continue;
+    }
+
+    const keep = new Set(["index.ts", ...roots.map((root) => schemaJsonBasename(root.kind))]);
+    for (const ent of readdirSync(generatedDir)) {
+      if (keep.has(ent)) {
+        continue;
+      }
+      const stalePath = join(generatedDir, ent);
+      rmSync(stalePath, { recursive: true, force: true });
+      console.log(`removed ${relative(projectRoot, stalePath)}`);
+    }
+  }
+}

package/src/cli-tool/schemagen/discover-schema-roots.ts

@@ -0,0 +1,103 @@
+/*
+Discovers schema roots in schema.ts files via configType / inputType / outputType exports.
+*/
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { SCHEMA_FILE } from "./names.ts";
+
+export type SchemaRootKind = "config" | "input" | "output";
+
+export type SchemaRole = "configType" | "inputType" | "outputType";
+
+export interface SchemaRoot {
+  kind: SchemaRootKind;
+  typeName: string;
+  /** Path relative to project root (e.g. src/config/schema.ts). */
+  path: string;
+}
+
+const ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=\s*(\w+)/g;
+
+const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
+  configType: "config",
+  inputType: "input",
+  outputType: "output",
+};
+
+function listSchemaFiles(srcDir: string, baseDir: string, out: string[]): void {
+  for (const ent of readdirSync(srcDir)) {
+    const full = join(srcDir, ent);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      listSchemaFiles(full, baseDir, out);
+      continue;
+    }
+    if (ent === SCHEMA_FILE) {
+      out.push(relative(baseDir, full));
+    }
+  }
+}
+
+/** True when `typeName` is declared in this file (not a re-export alias to another module). */
+function isTypeDefinedInFile(text: string, typeName: string): boolean {
+  if (new RegExp(`export\\s+interface\\s+${typeName}\\b`).test(text)) {
+    return true;
+  }
+  if (new RegExp(`export\\s+type\\s+${typeName}\\s*=`).test(text)) {
+    return !["configType", "inputType", "outputType"].includes(typeName);
+  }
+  return false;
+}
+
+function discoverFromFile(path: string, text: string): SchemaRoot[] {
+  const rolesSeen = new Set<SchemaRole>();
+  const roots: SchemaRoot[] = [];
+
+  for (const match of text.matchAll(ROLE_EXPORT_RE)) {
+    const role = match[1] as SchemaRole | undefined;
+    const typeName = match[2];
+    if (!role || !typeName) {
+      continue;
+    }
+    if (rolesSeen.has(role)) {
+      throw new Error(`${path}: duplicate export type ${role}`);
+    }
+    rolesSeen.add(role);
+    if (!isTypeDefinedInFile(text, typeName)) {
+      continue;
+    }
+    roots.push({ kind: ROLE_TO_KIND[role], typeName, path });
+  }
+
+  return roots;
+}
+
+/** Find all schema roots under `srcDir` in files named `schema.ts`. */
+export function discoverSchemaRoots(projectRoot: string, srcDir = "src"): SchemaRoot[] {
+  const srcPath = join(projectRoot, srcDir);
+  const files: string[] = [];
+  listSchemaFiles(srcPath, projectRoot, files);
+
+  const roots: SchemaRoot[] = [];
+  const typeOwners = new Map<string, string>();
+
+  for (const relPath of files.sort()) {
+    const text = readFileSync(join(projectRoot, relPath), "utf8");
+    for (const root of discoverFromFile(relPath, text)) {
+      const prev = typeOwners.get(root.typeName);
+      if (prev) {
+        throw new Error(`${relPath}: duplicate schema root type ${root.typeName} (already declared in ${prev})`);
+      }
+      typeOwners.set(root.typeName, relPath);
+      roots.push(root);
+    }
+  }
+
+  const configRoots = roots.filter((r) => r.kind === "config");
+  if (configRoots.length > 1) {
+    throw new Error(`multiple config schema roots: ${configRoots.map((r) => `${r.typeName} (${r.path})`).join(", ")}`);
+  }
+
+  return roots;
+}

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

@@ -0,0 +1,3 @@
+export { discoverSchemaRoots, type SchemaRoot, type SchemaRootKind } from "./discover-schema-roots.ts";
+export { GENERATED_DIR, SCHEMA_FILE, schemaExportName, schemaJsonBasename } from "./names.ts";
+export { type RunSchemagenOptions, type RunSchemagenResult, runSchemagen } from "./run.ts";

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

@@ -0,0 +1,22 @@
+import type { SchemaRootKind } from "./discover-schema-roots.ts";
+
+/** Directory name for generated schema artifacts (next to `schema.ts`). */
+export const GENERATED_DIR = "__generated__";
+
+/** TypeScript schema root filename under `src/`. */
+export const SCHEMA_FILE = "schema.ts";
+
+/** JSON basename for a schema root kind (`outputSchema.json`, etc.). */
+export function schemaJsonBasename(kind: SchemaRootKind): string {
+  return `${kind}Schema.json`;
+}
+
+/** Export const name wired on leaves or `program.appConfig`. */
+export function schemaExportName(kind: SchemaRootKind): string {
+  return `${kind}Schema`;
+}
+
+/** Safe import binding for a schema JSON basename. */
+export function schemaJsonImportVar(kind: SchemaRootKind): string {
+  return `${kind}SchemaJson`;
+}

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

@@ -0,0 +1,108 @@
+/*
+Generate JSON Schema artifacts under __generated__/ and write index.ts re-exports.
+*/
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { createGenerator } from "ts-json-schema-generator";
+import { cleanStaleGenerated } from "./cleanup.ts";
+import { discoverSchemaRoots, type SchemaRoot, type SchemaRootKind } from "./discover-schema-roots.ts";
+import { GENERATED_DIR, schemaExportName, schemaJsonBasename, schemaJsonImportVar } from "./names.ts";
+
+const KIND_ORDER: SchemaRootKind[] = ["config", "input", "output"];
+
+export interface RunSchemagenOptions {
+  /** Project root (default: `process.cwd()`). */
+  projectRoot?: string;
+  /** Source tree directory relative to project root (default: `src`). */
+  srcDir?: string;
+  /** Path to tsconfig relative to project root (default: `tsconfig.json`). */
+  tsconfig?: string;
+}
+
+export interface RunSchemagenResult {
+  configRoots: number;
+  inputRoots: number;
+  outputRoots: number;
+}
+
+function resolveTsconfig(projectRoot: string, tsconfig: string): string {
+  const path = join(projectRoot, tsconfig);
+  try {
+    return path;
+  } catch {
+    throw new Error(`tsconfig not found: ${path}`);
+  }
+}
+
+function generateJson(projectRoot: string, tsconfigPath: string, root: SchemaRoot): Record<string, unknown> {
+  const generator = createGenerator({
+    path: join(projectRoot, root.path),
+    type: root.typeName,
+    tsconfig: tsconfigPath,
+    topRef: false,
+    skipTypeCheck: false,
+    jsDoc: "extended",
+    additionalProperties: root.kind === "config" ? false : undefined,
+  });
+  const schema = generator.createSchema(root.typeName) as Record<string, unknown>;
+  if (root.kind === "config") {
+    schema.additionalProperties = false;
+  }
+  return schema;
+}
+
+function writeGeneratedIndex(generatedDir: string, roots: SchemaRoot[]): void {
+  const sorted = [...roots].sort((left, right) => KIND_ORDER.indexOf(left.kind) - KIND_ORDER.indexOf(right.kind));
+  const lines = ["// Auto-generated by argsbarg schemagen — do not edit by hand.", ""];
+  for (const root of sorted) {
+    lines.push(`import ${schemaJsonImportVar(root.kind)} from "./${schemaJsonBasename(root.kind)}";`);
+  }
+  if (sorted.length > 0) {
+    lines.push("");
+  }
+  for (const root of sorted) {
+    lines.push(
+      `export const ${schemaExportName(root.kind)} = ${schemaJsonImportVar(root.kind)} as Record<string, unknown>;`,
+    );
+    lines.push("");
+  }
+  writeFileSync(join(generatedDir, "index.ts"), `${lines.join("\n")}`);
+}
+
+/** Generate colocated `__generated__` JSON schemas and `index.ts` barrels. */
+export function runSchemagen(options: RunSchemagenOptions = {}): RunSchemagenResult {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const srcDir = options.srcDir ?? "src";
+  const tsconfigPath = resolveTsconfig(projectRoot, options.tsconfig ?? "tsconfig.json");
+
+  const roots = discoverSchemaRoots(projectRoot, srcDir);
+  const bySchemaFile = new Map<string, SchemaRoot[]>();
+
+  for (const root of roots) {
+    const schema = generateJson(projectRoot, tsconfigPath, root);
+    const generatedDir = join(dirname(join(projectRoot, root.path)), GENERATED_DIR);
+    mkdirSync(generatedDir, { recursive: true });
+    const jsonPath = join(generatedDir, schemaJsonBasename(root.kind));
+    writeFileSync(jsonPath, `${JSON.stringify(schema, null, 2)}\n`);
+    console.log(`wrote ${relative(projectRoot, jsonPath)} (${root.typeName})`);
+
+    const list = bySchemaFile.get(root.path) ?? [];
+    list.push(root);
+    bySchemaFile.set(root.path, list);
+  }
+
+  for (const [relPath, fileRoots] of bySchemaFile) {
+    const generatedDir = join(dirname(join(projectRoot, relPath)), GENERATED_DIR);
+    writeGeneratedIndex(generatedDir, fileRoots);
+    console.log(`wrote ${relative(projectRoot, join(generatedDir, "index.ts"))}`);
+  }
+
+  cleanStaleGenerated(projectRoot, srcDir, bySchemaFile);
+
+  return {
+    configRoots: roots.filter((r) => r.kind === "config").length,
+    inputRoots: roots.filter((r) => r.kind === "input").length,
+    outputRoots: roots.filter((r) => r.kind === "output").length,
+  };
+}

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

@@ -0,0 +1,125 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverSchemaRoots } from "./discover-schema-roots.ts";
+import { schemaExportName, schemaJsonBasename } from "./names.ts";
+import { runSchemagen } from "./run.ts";
+
+const exampleRoot = join(import.meta.dir, "../../../examples/full-example");
+
+const tempRoots: string[] = [];
+
+afterEach(() => {
+  for (const root of tempRoots.splice(0)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+function makeTempProject(): string {
+  const root = mkdtempSync(join(tmpdir(), "argsbarg-schemagen-"));
+  tempRoots.push(root);
+  writeFileSync(
+    join(root, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          strict: true,
+          target: "ESNext",
+          module: "ESNext",
+          moduleResolution: "bundler",
+          resolveJsonModule: true,
+        },
+        include: ["src/**/*"],
+      },
+      null,
+      2,
+    ),
+  );
+  return root;
+}
+
+function writeSchema(root: string, relDir: string, body: string): void {
+  const dir = join(root, "src", relDir);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "schema.ts"), body);
+}
+
+describe("schemagen", () => {
+  test("discovers AppConfig and StatusJsonOutput in full-example", () => {
+    const roots = discoverSchemaRoots(exampleRoot);
+    expect(roots.map((r) => `${r.kind}:${r.typeName}`).sort()).toEqual(["config:AppConfig", "output:StatusJsonOutput"]);
+  });
+
+  test("maps schema kinds to __generated__ filenames and export names", () => {
+    expect(schemaJsonBasename("output")).toBe("outputSchema.json");
+    expect(schemaJsonBasename("config")).toBe("configSchema.json");
+    expect(schemaExportName("output")).toBe("outputSchema");
+  });
+
+  test("runSchemagen writes __generated__ artifacts in full-example", () => {
+    const counts = runSchemagen({ projectRoot: exampleRoot });
+    expect(counts).toEqual({ configRoots: 1, inputRoots: 0, outputRoots: 1 });
+  });
+
+  test("removes stale JSON files when a schema kind is dropped", () => {
+    const root = makeTempProject();
+    writeSchema(
+      root,
+      "commands/demo",
+      `/** Tool input. */
+export interface DemoInput { id: string; }
+/** Tool output. */
+export interface DemoOutput { ok: boolean; }
+export type inputType = DemoInput;
+export type outputType = DemoOutput;
+`,
+    );
+
+    runSchemagen({ projectRoot: root });
+    const generatedDir = join(root, "src/commands/demo/__generated__");
+    expect(existsSync(join(generatedDir, "inputSchema.json"))).toBe(true);
+    expect(existsSync(join(generatedDir, "outputSchema.json"))).toBe(true);
+
+    writeSchema(
+      root,
+      "commands/demo",
+      `/** Tool output. */
+export interface DemoOutput { ok: boolean; }
+export type outputType = DemoOutput;
+`,
+    );
+
+    runSchemagen({ projectRoot: root });
+    expect(existsSync(join(generatedDir, "inputSchema.json"))).toBe(false);
+    expect(existsSync(join(generatedDir, "outputSchema.json"))).toBe(true);
+    expect(existsSync(join(generatedDir, "index.ts"))).toBe(true);
+  });
+
+  test("removes orphan __generated__ when schema.ts is gone", () => {
+    const root = makeTempProject();
+    const generatedDir = join(root, "src/orphan/__generated__");
+    mkdirSync(generatedDir, { recursive: true });
+    writeFileSync(join(generatedDir, "outputSchema.json"), "{}\n");
+    writeFileSync(join(generatedDir, "index.ts"), "export const outputSchema = {};\n");
+
+    runSchemagen({ projectRoot: root });
+    expect(existsSync(generatedDir)).toBe(false);
+  });
+
+  test("removes __generated__ when schema.ts has no discoverable roots", () => {
+    const root = makeTempProject();
+    writeSchema(
+      root,
+      "commands/empty",
+      `export type outputType = never;
+`,
+    );
+    const generatedDir = join(root, "src/commands/empty/__generated__");
+    mkdirSync(generatedDir, { recursive: true });
+    writeFileSync(join(generatedDir, "outputSchema.json"), "{}\n");
+
+    runSchemagen({ projectRoot: root });
+    expect(existsSync(generatedDir)).toBe(false);
+  });
+});

package/src/docs/mcp-resources.ts

@@ -3,7 +3,7 @@ Auto MCP resources for user docs.topics when docs and MCP are both enabled.
 */
 
 import type { CliProgram } from "../types.ts";
-import { docsEnabled, docsTopicContent, docsTopicDescription, docsUserTopicKeys } from "./resolve.ts";
+import { docsEnabled, docsTopicDescription, docsTopicText, docsUserTopicKeys } from "./resolve.ts";
 
 /** Default URI pattern for a docs topic MCP resource (`<mcpId>://docs/<topicKey>`). */
 export function defaultDocsTopicResourceUri(mcpId: string, topicKey: string): string {
@@ -45,7 +45,10 @@ export function docsMcpResources(program: CliProgram): {
       name: key,
       description: docsTopicDescription(key, topic.description),
       mimeType: "text/markdown",
-      load: () => docsTopicContent(program, key),
+      load: () => {
+        const text = docsTopicText(program, key);
+        return text.endsWith("\n") ? text : `${text}\n`;
+      },
     };
   });
 }

package/src/headless/tool-call.ts

@@ -2,7 +2,7 @@
 Shared headless tool dispatch for MCP and HTTP: config bootstrap, argv conversion, and invoke.
 */
 
-import { apiErrorResponse, apiSuccessResponse } from "../api/result.ts";
+import { apiErrorResponse, apiSuccessResponse, firstErrorLine } from "../api/result.ts";
 import type { Cli, CliInvokeResult } from "../cli.ts";
 import { bootstrapAppConfig } from "../config/bootstrap.ts";
 import { formatMcpMissingConfigMessage, missingRequiredConfig } from "../config/resolve.ts";
@@ -137,11 +137,21 @@ export function headlessSuccessToHttpResponse(
 
 /** Maps a headless failure result to a JSON HTTP error Response. */
 export function headlessFailureToHttpResponse(result: HeadlessToolCallFailure): Response {
-  const status = result.kind === "argv" || result.kind === "help" ? 400 : 500;
+  const status = resolveHttpErrorStatus(result);
   return apiErrorResponse(status, {
-    error: result.message,
-    exitCode: result.exitCode,
-    stdout: result.stdout,
-    stderr: result.stderr,
+    error: firstErrorLine(result.message),
   });
 }
+
+function resolveHttpErrorStatus(result: HeadlessToolCallFailure): number {
+  if (result.kind === "argv" || result.kind === "help") {
+    return 400;
+  }
+  if (result.kind === "invoke" && result.message.includes("ctx.respond()")) {
+    return 500;
+  }
+  if (result.exitCode === 1) {
+    return 400;
+  }
+  return 500;
+}

package/examples/full-example/schemas/configSchemas.ts

@@ -1,6 +0,0 @@
-// Auto-generated by scripts/schemagen.ts — do not edit by hand.
-
-import app_config from "./generated/app-config.json";
-
-/** JSON Schema for program.appConfig.jsonSchema from `AppConfig`. */
-export const APP_CONFIG_JSON_SCHEMA = app_config as Record<string, unknown>;

package/examples/full-example/schemas/outputSchemas.ts

@@ -1,6 +0,0 @@
-// Auto-generated by scripts/schemagen.ts — do not edit by hand.
-
-import status from "./generated/status.json";
-
-/** JSON Schema for leaf outputSchema from `StatusJsonOutput`. */
-export const STATUS_JSON_OUTPUT_SCHEMA = status as Record<string, unknown>;

package/examples/full-example/scripts/schemagen/discover-schema-roots.test.ts

@@ -1,25 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { join } from "node:path";
-import { discoverSchemaRoots } from "./discover-schema-roots.ts";
-
-const projectRoot = join(import.meta.dir, "../..");
-
-describe("discover-schema-roots", () => {
-  test("finds AppConfig and StatusJsonOutput in src types.ts files", () => {
-    const roots = discoverSchemaRoots(projectRoot);
-    const config = roots.find((r) => r.kind === "config");
-    const output = roots.find((r) => r.kind === "output");
-    expect(config).toMatchObject({
-      typeName: "AppConfig",
-      relFile: "src/types.ts",
-      outfile: "app-config.json",
-      exportName: "APP_CONFIG_JSON_SCHEMA",
-    });
-    expect(output).toMatchObject({
-      typeName: "StatusJsonOutput",
-      relFile: "src/commands/status/types.ts",
-      outfile: "status.json",
-      exportName: "STATUS_JSON_OUTPUT_SCHEMA",
-    });
-  });
-});

package/examples/full-example/scripts/schemagen/discover-schema-roots.ts

@@ -1,93 +0,0 @@
-/*
-Discovers schema roots in src (recursive) types.ts files by JSDoc markers.
-Copy per consumer repo — see docs/output-schema.md and docs/config-schema.md.
-*/
-
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
-import {
-  configSchemaExportName,
-  outfileForConfigType,
-  outfileForOutputType,
-  outputSchemaExportName,
-} from "./naming.ts";
-
-export type SchemaRootKind = "config" | "output";
-
-export interface SchemaRoot {
-  kind: SchemaRootKind;
-  typeName: string;
-  /** Path relative to project root (e.g. src/types.ts). */
-  relFile: string;
-  outfile: string;
-  exportName: string;
-}
-
-const CONFIG_MARKER = "Config schema";
-const OUTPUT_MARKER = "JSON payload";
-
-const INTERFACE_RE = /\/\*\*([\s\S]*?)\*\/\s*export\s+interface\s+(\w+)/g;
-
-function listTypesTsFiles(srcDir: string, baseDir: string, out: string[]): void {
-  for (const ent of readdirSync(srcDir)) {
-    const full = join(srcDir, ent);
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      listTypesTsFiles(full, baseDir, out);
-      continue;
-    }
-    if (ent === "types.ts") {
-      out.push(relative(baseDir, full));
-    }
-  }
-}
-
-function classifyRoot(jsDoc: string, typeName: string, relFile: string): SchemaRoot | undefined {
-  const hasConfig = jsDoc.includes(CONFIG_MARKER);
-  const hasOutput = jsDoc.includes(OUTPUT_MARKER);
-  if (hasConfig && hasOutput) {
-    throw new Error(`${relFile}: ${typeName} has both Config schema and JSON payload markers`);
-  }
-  if (!hasConfig && !hasOutput) {
-    return undefined;
-  }
-  if (hasConfig) {
-    return {
-      kind: "config",
-      typeName,
-      relFile,
-      outfile: outfileForConfigType(typeName),
-      exportName: configSchemaExportName(typeName),
-    };
-  }
-  return {
-    kind: "output",
-    typeName,
-    relFile,
-    outfile: outfileForOutputType(typeName),
-    exportName: outputSchemaExportName(typeName),
-  };
-}
-
-/** Find all schema roots under `src/` in files named types.ts. */
-export function discoverSchemaRoots(projectRoot: string): SchemaRoot[] {
-  const srcDir = join(projectRoot, "src");
-  const files: string[] = [];
-  listTypesTsFiles(srcDir, projectRoot, files);
-  const roots: SchemaRoot[] = [];
-  for (const relFile of files.sort()) {
-    const text = readFileSync(join(projectRoot, relFile), "utf8");
-    for (const match of text.matchAll(INTERFACE_RE)) {
-      const jsDoc = match[1] ?? "";
-      const typeName = match[2];
-      if (!typeName) {
-        continue;
-      }
-      const root = classifyRoot(jsDoc, typeName, relFile);
-      if (root) {
-        roots.push(root);
-      }
-    }
-  }
-  return roots;
-}