argsbarg 6.0.2 → 6.1.1

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

@@ -1,10 +1,10 @@
 /*
-Discovers schema roots in schema.ts files via configType / inputType / outputType exports.
+Discovers schema roots in types.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";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { TYPES_FILE } from "./names.ts";
 
 export type SchemaRootKind = "config" | "input" | "output";
 
@@ -13,11 +13,15 @@ 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 to types.ts relative to project root (anchors __generated__/ output). */
   path: string;
+  /** Path to the file that defines `typeName` (defaults to `path`). */
+  sourcePath: string;
 }
 
 const ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=\s*(\w+)/g;
+const HAS_ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=/;
+const IMPORT_RE = /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
 
 const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
   configType: "config",
@@ -25,21 +29,25 @@ const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
   outputType: "output",
 };
 
-function listSchemaFiles(srcDir: string, baseDir: string, out: string[]): void {
+function listTypesManifestFiles(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);
+      listTypesManifestFiles(full, baseDir, out);
       continue;
     }
-    if (ent === SCHEMA_FILE) {
+    if (ent !== TYPES_FILE) {
+      continue;
+    }
+    const text = readFileSync(full, "utf8");
+    if (HAS_ROLE_EXPORT_RE.test(text)) {
       out.push(relative(baseDir, full));
     }
   }
 }
 
-/** True when `typeName` is declared in this file (not a re-export alias to another module). */
+/** True when `typeName` is declared in this file (not a schemagen role alias). */
 function isTypeDefinedInFile(text: string, typeName: string): boolean {
   if (new RegExp(`export\\s+interface\\s+${typeName}\\b`).test(text)) {
     return true;
@@ -50,7 +58,62 @@ function isTypeDefinedInFile(text: string, typeName: string): boolean {
   return false;
 }
 
-function discoverFromFile(path: string, text: string): SchemaRoot[] {
+function parseLocalTypeImports(text: string): Map<string, string> {
+  const imports = new Map<string, string>();
+  for (const match of text.matchAll(IMPORT_RE)) {
+    const names = match[1];
+    const from = match[2];
+    if (!names || !from?.startsWith(".")) {
+      continue;
+    }
+    for (const part of names.split(",")) {
+      const trimmed = part.trim();
+      const nameMatch = trimmed.match(/^(?:type\s+)?(\w+)(?:\s+as\s+(\w+))?$/);
+      if (!nameMatch?.[1]) {
+        continue;
+      }
+      const localName = nameMatch[2] ?? nameMatch[1];
+      imports.set(localName, from);
+    }
+  }
+  return imports;
+}
+
+function resolveModuleFile(manifestFile: string, specifier: string): string | null {
+  const base = join(dirname(manifestFile), specifier);
+  const candidates = [base, `${base}.ts`, join(base, "index.ts")];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/** Resolve a role alias to the module that defines `typeName`, when imported from a relative path. */
+function resolveAliasedTypeSource(
+  projectRoot: string,
+  manifestRelPath: string,
+  manifestText: string,
+  typeName: string,
+): string | null {
+  const manifestFile = join(projectRoot, manifestRelPath);
+  const specifier = parseLocalTypeImports(manifestText).get(typeName);
+  if (!specifier) {
+    return null;
+  }
+  const moduleFile = resolveModuleFile(manifestFile, specifier);
+  if (!moduleFile) {
+    return null;
+  }
+  const moduleText = readFileSync(moduleFile, "utf8");
+  if (!isTypeDefinedInFile(moduleText, typeName)) {
+    return null;
+  }
+  return relative(projectRoot, moduleFile);
+}
+
+function discoverFromFile(projectRoot: string, path: string, text: string): SchemaRoot[] {
   const rolesSeen = new Set<SchemaRole>();
   const roots: SchemaRoot[] = [];
 
@@ -64,27 +127,34 @@ function discoverFromFile(path: string, text: string): SchemaRoot[] {
       throw new Error(`${path}: duplicate export type ${role}`);
     }
     rolesSeen.add(role);
+
+    let sourcePath = path;
     if (!isTypeDefinedInFile(text, typeName)) {
-      continue;
+      const resolved = resolveAliasedTypeSource(projectRoot, path, text, typeName);
+      if (!resolved) {
+        continue;
+      }
+      sourcePath = resolved;
     }
-    roots.push({ kind: ROLE_TO_KIND[role], typeName, path });
+
+    roots.push({ kind: ROLE_TO_KIND[role], typeName, path, sourcePath });
   }
 
   return roots;
 }
 
-/** Find all schema roots under `srcDir` in files named `schema.ts`. */
+/** Find all schema roots under `srcDir` in `types.ts` files with role exports. */
 export function discoverSchemaRoots(projectRoot: string, srcDir = "src"): SchemaRoot[] {
   const srcPath = join(projectRoot, srcDir);
   const files: string[] = [];
-  listSchemaFiles(srcPath, projectRoot, files);
+  listTypesManifestFiles(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)) {
+    for (const root of discoverFromFile(projectRoot, relPath, text)) {
       const prev = typeOwners.get(root.typeName);
       if (prev) {
         throw new Error(`${relPath}: duplicate schema root type ${root.typeName} (already declared in ${prev})`);

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

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

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

@@ -1,10 +1,10 @@
 import type { SchemaRootKind } from "./discover-schema-roots.ts";
 
-/** Directory name for generated schema artifacts (next to `schema.ts`). */
+/** Directory name for generated schema artifacts (next to `types.ts`). */
 export const GENERATED_DIR = "__generated__";
 
-/** TypeScript schema root filename under `src/`. */
-export const SCHEMA_FILE = "schema.ts";
+/** TypeScript schemagen manifest filename under `src/`. */
+export const TYPES_FILE = "types.ts";
 
 /** JSON basename for a schema root kind (`outputSchema.json`, etc.). */
 export function schemaJsonBasename(kind: SchemaRootKind): string {

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

@@ -36,8 +36,9 @@ function resolveTsconfig(projectRoot: string, tsconfig: string): string {
 }
 
 function generateJson(projectRoot: string, tsconfigPath: string, root: SchemaRoot): Record<string, unknown> {
+  const typeFile = join(projectRoot, root.sourcePath);
   const generator = createGenerator({
-    path: join(projectRoot, root.path),
+    path: typeFile,
     type: root.typeName,
     tsconfig: tsconfigPath,
     topRef: false,

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

@@ -39,10 +39,10 @@ function makeTempProject(): string {
   return root;
 }
 
-function writeSchema(root: string, relDir: string, body: string): void {
+function writeTypes(root: string, relDir: string, body: string): void {
   const dir = join(root, "src", relDir);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "schema.ts"), body);
+  writeFileSync(join(dir, "types.ts"), body);
 }
 
 describe("schemagen", () => {
@@ -62,14 +62,38 @@ describe("schemagen", () => {
     expect(counts).toEqual({ configRoots: 1, inputRoots: 0, outputRoots: 1 });
   });
 
+  test("discovers roots from types.ts with interface and role export", () => {
+    const root = makeTempProject();
+    const dir = join(root, "src/commands/demo");
+    writeTypes(
+      root,
+      "commands/demo",
+      `export interface DemoOutput { ok: boolean; }
+
+/** Schemagen root for leaf outputSchema. */
+export type outputType = DemoOutput;
+`,
+    );
+
+    const roots = discoverSchemaRoots(root);
+    expect(roots).toEqual([
+      {
+        kind: "output",
+        typeName: "DemoOutput",
+        path: "src/commands/demo/types.ts",
+        sourcePath: "src/commands/demo/types.ts",
+      },
+    ]);
+    runSchemagen({ projectRoot: root });
+    expect(existsSync(join(dir, "__generated__/outputSchema.json"))).toBe(true);
+  });
+
   test("removes stale JSON files when a schema kind is dropped", () => {
     const root = makeTempProject();
-    writeSchema(
+    writeTypes(
       root,
       "commands/demo",
-      `/** Tool input. */
-export interface DemoInput { id: string; }
-/** Tool output. */
+      `export interface DemoInput { id: string; }
 export interface DemoOutput { ok: boolean; }
 export type inputType = DemoInput;
 export type outputType = DemoOutput;
@@ -81,11 +105,10 @@ export type outputType = DemoOutput;
     expect(existsSync(join(generatedDir, "inputSchema.json"))).toBe(true);
     expect(existsSync(join(generatedDir, "outputSchema.json"))).toBe(true);
 
-    writeSchema(
+    writeTypes(
       root,
       "commands/demo",
-      `/** Tool output. */
-export interface DemoOutput { ok: boolean; }
+      `export interface DemoOutput { ok: boolean; }
 export type outputType = DemoOutput;
 `,
     );
@@ -96,7 +119,7 @@ export type outputType = DemoOutput;
     expect(existsSync(join(generatedDir, "index.ts"))).toBe(true);
   });
 
-  test("removes orphan __generated__ when schema.ts is gone", () => {
+  test("removes orphan __generated__ when types.ts manifest is gone", () => {
     const root = makeTempProject();
     const generatedDir = join(root, "src/orphan/__generated__");
     mkdirSync(generatedDir, { recursive: true });
@@ -107,14 +130,9 @@ export type outputType = DemoOutput;
     expect(existsSync(generatedDir)).toBe(false);
   });
 
-  test("removes __generated__ when schema.ts has no discoverable roots", () => {
+  test("removes __generated__ when types.ts has no discoverable roots", () => {
     const root = makeTempProject();
-    writeSchema(
-      root,
-      "commands/empty",
-      `export type outputType = never;
-`,
-    );
+    writeTypes(root, "commands/empty", `export type outputType = never;\n`);
     const generatedDir = join(root, "src/commands/empty/__generated__");
     mkdirSync(generatedDir, { recursive: true });
     writeFileSync(join(generatedDir, "outputSchema.json"), "{}\n");

package/src/cli.ts

@@ -18,6 +18,7 @@ import { readAppConfigFileRaw, resolveAppConfigPath } from "./config/file.ts";
 import { effectiveJsonSchema } from "./config/schema.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
+import { LeafInputError, preloadPipableJson } from "./leaf-inputs.ts";
 import { bootstrapMcpEnv } from "./mcp/env.ts";
 import { mcpServeStdioLoop } from "./mcp/server.ts";
 import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
@@ -124,14 +125,41 @@ export class Cli {
       exitOnMissing: !skipRequiredConfig,
     });
 
-    const ctx = new CliContext(this.program.key, pr.path, pr.args, pr.opts, this.program, "cli", snapshot);
+    let preloadedJson: Record<string, unknown> = {};
     try {
+      preloadedJson = await preloadPipableJson(this.program, pr.path, pr.opts, "cli");
+    } catch (err) {
+      if (err instanceof LeafInputError) {
+        this.exitLeafInputError(err, pr.path);
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      const color = process.stderr.isTTY;
+      process.stderr.write(color ? `\u001B[31m${msg}\u001B[0m\n` : `${msg}\n`);
+      process.exit(1);
+    }
+
+    const ctx = new CliContext(
+      this.program.key,
+      pr.path,
+      pr.args,
+      pr.opts,
+      this.program,
+      "cli",
+      snapshot,
+      undefined,
+      preloadedJson,
+    );
+    try {
+      this.ensureValidatedLeafInputs(ctx, leaf);
       const handlerResult = await Promise.resolve(leaf.handler(ctx));
       if (handlerResult !== undefined && ctx.getResponse() === undefined) {
         ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
       }
       process.exit(0);
     } catch (err) {
+      if (err instanceof LeafInputError) {
+        this.exitLeafInputError(err, pr.path);
+      }
       if (err instanceof Error) {
         process.stderr.write(`${err.message}\n`);
       }
@@ -232,6 +260,7 @@ export class Cli {
         });
       }
 
+      this.ensureValidatedLeafInputs(ctx, leaf);
       const handlerResult = await Promise.resolve(leaf.handler(ctx));
       if (handlerResult !== undefined && ctx.getResponse() === undefined) {
         ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
@@ -260,6 +289,15 @@ export class Cli {
         const msg = stderr.trim() || `Exit code ${err.code}`;
         return { kind: "error", exitCode: err.code, stdout, stderr, errorMsg: msg };
       }
+      if (err instanceof LeafInputError) {
+        return {
+          kind: "error",
+          exitCode: 1,
+          stdout,
+          stderr: `${err.message}\n`,
+          errorMsg: err.message,
+        };
+      }
       if (err instanceof Error) {
         return {
           kind: "error",
@@ -320,6 +358,21 @@ export class Cli {
     }
   }
 
+  private ensureValidatedLeafInputs(ctx: CliContext, leaf: CliLeaf): void {
+    if (leaf.inputSchema === undefined) {
+      return;
+    }
+    ctx.inputs;
+  }
+
+  private exitLeafInputError(err: LeafInputError, helpPath: string[]): never {
+    const color = process.stderr.isTTY;
+    const msg = color ? `\u001B[31m${err.message}\u001B[0m` : err.message;
+    process.stderr.write(`${msg}\n`);
+    process.stderr.write(cliHelpRender(this.presentationRoot, helpPath, true));
+    process.exit(1);
+  }
+
   private prepareDispatch(
     argv: string[],
     opts?: { presentationFallback?: boolean },

package/src/context.ts

@@ -10,14 +10,14 @@ parsed values.
 import type { AnyAppConfigSnapshot } from "./config/context.ts";
 import { EmptyAppConfigSnapshot } from "./config/context.ts";
 import { parseCommaList, parseDate, parseDateTime, parseDurationMs } from "./formats.ts";
-import { collectOptionDefs } from "./parse.ts";
+import { loadLeafInputs, readJsonOptionValue } from "./leaf-inputs.ts";
 import { normalizeRespondOptions, writeRespondBodyToStdout } from "./respond.ts";
-import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram, CliRespondOptions } from "./types.ts";
-import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
+import type { CliInvocation, CliLeaf, CliNode, CliProgram, CliRespondOptions } from "./types.ts";
+import { isCliLeaf, isCliRouter } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
 /** Coerced leaf inputs keyed by option and positional names. */
-export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
+export type CliLeafInputs = Record<string, boolean | number | string | string[] | unknown | undefined>;
 
 /**
  * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
@@ -32,8 +32,11 @@ export class CliContext {
   readonly appConfig: AnyAppConfigSnapshot;
   /** Original flat tool arguments for API/MCP invocations (when provided). */
   readonly toolArgs?: Record<string, unknown>;
+  /** Pipable Json option values read from stdin before the handler (CLI only). */
+  readonly preloadedJson: Record<string, unknown>;
 
   private response?: CliRespondOptions;
+  private leafInputsCache?: CliLeafInputs;
 
   /** Captures the program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
@@ -45,6 +48,7 @@ export class CliContext {
     invocation: CliInvocation = "cli",
     appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(program),
     toolArgs?: Record<string, unknown>,
+    preloadedJson: Record<string, unknown> = {},
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
@@ -54,6 +58,7 @@ export class CliContext {
     this.invocation = invocation;
     this.appConfig = appConfig;
     this.toolArgs = toolArgs;
+    this.preloadedJson = preloadedJson;
   }
 
   /**
@@ -136,54 +141,50 @@ export class CliContext {
     return parseDateTime(s);
   }
 
+  /**
+   * Parsed Json option: `--name '<json>'`, preloaded piped stdin (when `pipable`), or MCP/API toolArgs.
+   * Flag wins over stdin and toolArgs.
+   */
+  jsonOpt(name: string): unknown | undefined {
+    return readJsonOptionValue(this, name);
+  }
+
   /** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
   positional(name: string): string | string[] | undefined {
     return this._positionalMap()[name];
   }
 
-  /** Reads coerced option and positional values for the current leaf from schema metadata. */
-  readLeafInputs(): CliLeafInputs {
-    const leaf = this._leafNode();
-    if (!leaf) return {};
-
-    const out: CliLeafInputs = {};
-    for (const opt of collectOptionDefs(this.program, this.commandPath)) {
-      out[opt.name] = this._readOptionValue(opt);
-    }
-    for (const p of leaf.positionals ?? []) {
-      const val = this.positional(p.name);
-      if (val === undefined) {
-        out[p.name] = undefined;
-      } else if (Array.isArray(val)) {
-        out[p.name] = val;
-      } else {
-        out[p.name] = val;
-      }
+  /**
+   * Coerced option and positional values for the current leaf.
+   * When `leaf.inputSchema` is set, argsbarg validates before the handler runs; this returns the cached result.
+   */
+  get inputs(): CliLeafInputs {
+    if (this.leafInputsCache !== undefined) {
+      return this.leafInputsCache;
     }
-    return out;
+    this.leafInputsCache = loadLeafInputs(this);
+    return this.leafInputsCache;
   }
 
-  private _readOptionValue(opt: CliOption): boolean | number | string | string[] | undefined {
-    if (opt.kind === CliOptionKind.Presence) {
-      return this.hasFlag(opt.name);
-    }
-    if (opt.kind === CliOptionKind.Number) {
-      const n = this.numberOpt(opt.name);
-      return n === null ? undefined : n;
-    }
-    if (opt.format === CliValueFormat.Duration) {
-      return this.durationOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.CommaList) {
-      return this.commaListOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.Date) {
-      return this.dateOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.DateTime) {
-      return this.dateTimeOpt(opt.name);
-    }
-    return this.stringOpt(opt.name);
+  /**
+   * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
+   */
+  inputsAs<T = CliLeafInputs>(): T {
+    return this.inputs as T;
+  }
+
+  /**
+   * @deprecated Use {@link inputs} or {@link inputsAs}.
+   */
+  readLeafInputs(): CliLeafInputs {
+    return this.inputs;
+  }
+
+  /**
+   * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
+   */
+  readLeafInputsAsync(): Promise<CliLeafInputs> {
+    return Promise.resolve(this.readLeafInputs());
   }
 
   private _leafNode(): CliLeaf | undefined {

package/src/help.ts

@@ -178,6 +178,8 @@ function optKindLabel(k: CliOptionKind, o?: CliOption): string {
       }
       return ` <${choices.slice(0, 3).join("|")}|…>`;
     }
+    case CliOptionKind.Json:
+      return " <json>";
   }
 }
 

package/src/index.ts

@@ -28,6 +28,14 @@ export {
   shouldRunHeadlessWithYes,
   wantsExplicitJson,
 } from "./headless.ts";
+export {
+  LeafInputError,
+  loadLeafInputs,
+  preloadPipableJson,
+  readJsonOptionValue,
+  readLeafInputs,
+  readLeafInputsAsync,
+} from "./leaf-inputs.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
 export type {