argsbarg 6.0.1 → 6.1.0

package/src/validate.ts

@@ -247,6 +247,31 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     if (resolved !== undefined && (typeof resolved !== "object" || resolved === null || Array.isArray(resolved))) {
       throw new CliSchemaValidationError("outputSchema must be a JSON Schema object (not null or an array)");
     }
+    const inputSchema = node.inputSchema;
+    if (
+      inputSchema !== undefined &&
+      (typeof inputSchema !== "object" || inputSchema === null || Array.isArray(inputSchema))
+    ) {
+      throw new CliSchemaValidationError("inputSchema must be a JSON Schema object (not null or an array)");
+    }
+    if (inputSchema !== undefined) {
+      const properties = inputSchema.properties;
+      if (
+        properties !== undefined &&
+        (typeof properties !== "object" || properties === null || Array.isArray(properties))
+      ) {
+        throw new CliSchemaValidationError(`inputSchema.properties must be an object on ${node.key}`);
+      }
+      if (properties) {
+        for (const opt of node.options ?? []) {
+          if (opt.kind === CliOptionKind.Json && !(opt.name in properties)) {
+            throw new CliSchemaValidationError(
+              `Json option '${opt.name}' is missing from inputSchema.properties on ${node.key}`,
+            );
+          }
+        }
+      }
+    }
   } else {
     const rogue = node as unknown as CliLeaf;
     if (rogue.mcpTool !== undefined) {
@@ -301,7 +326,22 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
 
 function validateOptions(scopeKey: string, options: import("./types.ts").CliOption[]): void {
   const seenShorts = new Set<string>();
+  let pipableCount = 0;
   for (const opt of options) {
+    if (opt.pipable) {
+      pipableCount++;
+      if (opt.kind !== CliOptionKind.Json) {
+        throw new CliSchemaValidationError(`pipable is only valid on Json kind: ${scopeKey}/${opt.name}`);
+      }
+    }
+    if (opt.kind === CliOptionKind.Json) {
+      if (opt.format !== undefined || opt.pattern !== undefined || opt.default !== undefined) {
+        throw new CliSchemaValidationError(
+          `Json option cannot use format, pattern, or default: ${scopeKey}/${opt.name}`,
+        );
+      }
+    }
+
     if (opt.required && opt.kind === CliOptionKind.Presence) {
       throw new CliSchemaValidationError(`Presence option cannot be required: ${scopeKey}/${opt.name}`);
     }
@@ -340,6 +380,9 @@ function validateOptions(scopeKey: string, options: import("./types.ts").CliOpti
       validateOptionValueMetadata(scopeKey, opt);
     }
   }
+  if (pipableCount > 1) {
+    throw new CliSchemaValidationError(`At most one pipable Json option per command: ${scopeKey}`);
+  }
 }
 
 function validateOptionValueMetadata(scopeKey: string, opt: import("./types.ts").CliOption): void {

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 schema-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",
-      path: "src/config/schema-types.ts",
-      outfile: "app-config.json",
-      exportName: "APP_CONFIG_JSON_SCHEMA",
-    });
-    expect(output).toMatchObject({
-      typeName: "StatusJsonOutput",
-      path: "src/commands/status/schema-types.ts",
-      outfile: "status.json",
-      exportName: "STATUS_JSON_OUTPUT_SCHEMA",
-    });
-  });
-});

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

@@ -1,148 +0,0 @@
-/*
-Discovers schema roots in schema-types.ts files via configType / inputType / outputType exports.
-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,
-  inputSchemaExportName,
-  outfileForConfigType,
-  outfileForInputType,
-  outfileForOutputType,
-  outputSchemaExportName,
-} from "./naming.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-types.ts). */
-  path: string;
-  outfile: string;
-  exportName: string;
-}
-
-const SCHEMA_TYPES_FILE = "schema-types.ts";
-
-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 listSchemaTypesFiles(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()) {
-      listSchemaTypesFiles(full, baseDir, out);
-      continue;
-    }
-    if (ent === SCHEMA_TYPES_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 rootForRole(role: SchemaRole, typeName: string, path: string): SchemaRoot {
-  const kind = ROLE_TO_KIND[role];
-  if (kind === "config") {
-    return {
-      kind,
-      typeName,
-      path,
-      outfile: outfileForConfigType(typeName),
-      exportName: configSchemaExportName(typeName),
-    };
-  }
-  if (kind === "input") {
-    return {
-      kind,
-      typeName,
-      path,
-      outfile: outfileForInputType(typeName),
-      exportName: inputSchemaExportName(typeName),
-    };
-  }
-  return {
-    kind,
-    typeName,
-    path,
-    outfile: outfileForOutputType(typeName),
-    exportName: outputSchemaExportName(typeName),
-  };
-}
-
-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(rootForRole(role, typeName, path));
-  }
-
-  return roots;
-}
-
-/** Find all schema roots under `src/` in files named schema-types.ts. */
-export function discoverSchemaRoots(projectRoot: string): SchemaRoot[] {
-  const srcDir = join(projectRoot, "src");
-  const files: string[] = [];
-  listSchemaTypesFiles(srcDir, 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/examples/full-example/scripts/schemagen/naming.ts

@@ -1,99 +0,0 @@
-/*
-Maps discovered schema root type names to generated filenames and bridge export constants.
-Matches conventions in docs/output-schema.md and docs/config-schema.md.
-*/
-
-/** kebab-case from PascalCase segments. */
-export function camelToKebab(name: string): string {
-  return name
-    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
-    .toLowerCase();
-}
-
-/** SCREAMING_SNAKE from PascalCase. */
-export function camelToScreamingSnake(name: string): string {
-  return camelToKebab(name).replace(/-/g, "_").toUpperCase();
-}
-
-/** Generated JSON filename for a tool-input schema root. */
-export function outfileForInputType(typeName: string): string {
-  if (typeName.endsWith("ToolInput")) {
-    return `${camelToKebab(typeName.slice(0, -"ToolInput".length))}-tool-input.json`;
-  }
-  return `${camelToKebab(typeName)}-tool-input.json`;
-}
-
-/** Bridge export constant for a tool-input schema root. */
-export function inputSchemaExportName(typeName: string): string {
-  if (typeName.endsWith("ToolInput")) {
-    const base = typeName.slice(0, -"ToolInput".length);
-    return `${camelToScreamingSnake(base)}_TOOL_INPUT_SCHEMA`;
-  }
-  return `${camelToScreamingSnake(typeName)}_TOOL_INPUT_SCHEMA`;
-}
-
-/** Generated JSON filename for an output-schema root type. */
-export function outfileForOutputType(typeName: string): string {
-  if (typeName.endsWith("JsonOutput")) {
-    return `${camelToKebab(typeName.slice(0, -"JsonOutput".length))}.json`;
-  }
-  if (typeName.endsWith("OpResult")) {
-    return `${camelToKebab(typeName.slice(0, -"OpResult".length))}-op-result.json`;
-  }
-  if (typeName.endsWith("Output")) {
-    return `${camelToKebab(typeName.slice(0, -"Output".length))}.json`;
-  }
-  if (typeName.endsWith("Result")) {
-    return `${camelToKebab(typeName.slice(0, -"Result".length))}.json`;
-  }
-  return `${camelToKebab(typeName)}.json`;
-}
-
-/** Bridge export constant for an output-schema root. */
-export function outputSchemaExportName(typeName: string): string {
-  if (typeName.endsWith("JsonOutput")) {
-    const base = typeName.slice(0, -"JsonOutput".length);
-    return `${camelToScreamingSnake(base)}_JSON_OUTPUT_SCHEMA`;
-  }
-  if (typeName.endsWith("OpResult")) {
-    const base = typeName.slice(0, -"OpResult".length);
-    return `${camelToScreamingSnake(base)}_OP_RESULT_OUTPUT_SCHEMA`;
-  }
-  if (typeName.endsWith("Output")) {
-    const base = typeName.slice(0, -"Output".length);
-    return `${camelToScreamingSnake(base)}_OUTPUT_SCHEMA`;
-  }
-  if (typeName.endsWith("Result")) {
-    const base = typeName.slice(0, -"Result".length);
-    return `${camelToScreamingSnake(base)}_RESULT_OUTPUT_SCHEMA`;
-  }
-  return `${camelToScreamingSnake(typeName)}_OUTPUT_SCHEMA`;
-}
-
-/** Generated JSON filename for a config-schema root (typically AppConfig → app-config.json). */
-export function outfileForConfigType(typeName: string): string {
-  if (typeName.endsWith("Config")) {
-    return `${camelToKebab(typeName.slice(0, -"Config".length))}-config.json`;
-  }
-  return `${camelToKebab(typeName)}-config.json`;
-}
-
-/** Bridge export constant for a config-schema root (AppConfig → APP_CONFIG_JSON_SCHEMA). */
-export function configSchemaExportName(typeName: string): string {
-  if (typeName.endsWith("Config")) {
-    const base = typeName.slice(0, -"Config".length);
-    return `${camelToScreamingSnake(base)}_CONFIG_JSON_SCHEMA`;
-  }
-  return `${camelToScreamingSnake(typeName)}_CONFIG_JSON_SCHEMA`;
-}
-
-/** Import path basename for a generated JSON file (no extension). */
-export function jsonImportBasename(outfile: string): string {
-  return outfile.replace(/\.json$/, "");
-}
-
-/** Safe import binding for a generated JSON file (no extension, hyphens → underscores). */
-export function jsonImportVar(outfile: string): string {
-  return jsonImportBasename(outfile).replace(/-/g, "_");
-}

package/examples/full-example/scripts/schemagen.ts

@@ -1,91 +0,0 @@
-/*
-Generate JSON Schema artifacts and bridge modules from discovered schema-types.ts roots.
-*/
-
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { createGenerator } from "ts-json-schema-generator";
-import { discoverSchemaRoots, type SchemaRoot } from "./schemagen/discover-schema-roots.ts";
-import { jsonImportVar } from "./schemagen/naming.ts";
-
-const projectRoot = join(import.meta.dir, "..");
-const generatedDir = join(projectRoot, "schemas", "generated");
-
-function generateJson(root: SchemaRoot): Record<string, unknown> {
-  const generator = createGenerator({
-    path: join(projectRoot, root.path),
-    type: root.typeName,
-    tsconfig: join(projectRoot, "tsconfig.json"),
-    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 writeBridge(path: string, scriptName: string, roots: SchemaRoot[], banner: string): void {
-  /** Sort by import binding so Biome `organizeImports` does not reorder the bridge file. */
-  const sorted = [...roots].sort((left, right) =>
-    jsonImportVar(left.outfile).localeCompare(jsonImportVar(right.outfile)),
-  );
-  const lines = [`// Auto-generated by scripts/${scriptName} — do not edit by hand.`, ""];
-  for (const root of sorted) {
-    const varName = jsonImportVar(root.outfile);
-    lines.push(`import ${varName} from "./generated/${root.outfile}";`);
-  }
-  if (sorted.length > 0) {
-    lines.push("");
-  }
-  for (const root of sorted) {
-    const varName = jsonImportVar(root.outfile);
-    lines.push(`/** ${banner} \`${root.typeName}\`. */`);
-    lines.push(`export const ${root.exportName} = ${varName} as Record<string, unknown>;`);
-    lines.push("");
-  }
-  writeFileSync(path, `${lines.join("\n")}`);
-}
-
-const roots = discoverSchemaRoots(projectRoot);
-const configRoots = roots.filter((r) => r.kind === "config");
-const inputRoots = roots.filter((r) => r.kind === "input");
-const outputRoots = roots.filter((r) => r.kind === "output");
-
-mkdirSync(generatedDir, { recursive: true });
-
-for (const root of roots) {
-  const schema = generateJson(root);
-  const outPath = join(generatedDir, root.outfile);
-  mkdirSync(dirname(outPath), { recursive: true });
-  writeFileSync(outPath, `${JSON.stringify(schema, null, 2)}\n`);
-  console.log(`wrote schemas/generated/${root.outfile} (${root.typeName})`);
-}
-
-writeBridge(
-  join(projectRoot, "schemas", "configSchemas.ts"),
-  "schemagen.ts",
-  configRoots,
-  "JSON Schema for program.appConfig.jsonSchema from",
-);
-if (inputRoots.length > 0) {
-  writeBridge(
-    join(projectRoot, "schemas", "inputSchemas.ts"),
-    "schemagen.ts",
-    inputRoots,
-    "JSON Schema for leaf inputSchema from",
-  );
-}
-writeBridge(
-  join(projectRoot, "schemas", "outputSchemas.ts"),
-  "schemagen.ts",
-  outputRoots,
-  "JSON Schema for leaf outputSchema from",
-);
-
-console.log(
-  `config roots: ${configRoots.length}, input roots: ${inputRoots.length}, output roots: ${outputRoots.length}`,
-);

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

@@ -1,14 +0,0 @@
-/** 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;