argsbarg 3.6.4 → 4.0.1

package/src/cli.ts

@@ -0,0 +1,389 @@
+/*
+Runtime entry point: validate program, cache derived state, run / invoke / MCP serve.
+*/
+
+import { format } from "node:util";
+import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
+import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
+import { assertBuiltinAllowed, type CliCapabilities, resolveCapabilities } from "./capabilities.ts";
+import {
+  bootstrapAppConfig,
+  type EnsureAppConfigOpts,
+  ensureAppConfig,
+} from "./config/bootstrap.ts";
+import { type AnyAppConfigSnapshot, createAppConfigSnapshot } from "./config/context.ts";
+import { effectiveJsonSchema } from "./config/schema.ts";
+import { CliContext } from "./context.ts";
+import { cliHelpRender } from "./help.ts";
+import { bootstrapMcpEnv } from "./mcp/env.ts";
+import { mcpServeStdioLoop } from "./mcp/server.ts";
+import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
+import { type CliSchemaExport, cliSchemaExport } from "./schema.ts";
+import type { CliHandler, CliLeaf, CliNode, CliProgram, CliRouter } from "./types.ts";
+import { isCliLeaf, isCliRouter } from "./types.ts";
+import { cliValidateProgram } from "./validate.ts";
+
+/** Outcome of a non-exiting CLI invocation. */
+export type CliInvokeKind = "ok" | "help" | "error";
+
+/** Result of Cli.invoke: captured output and exit metadata without process.exit. */
+export interface CliInvokeResult {
+  kind: CliInvokeKind;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  errorMsg?: string;
+}
+
+class CliInvokeExit extends Error {
+  readonly code: number;
+
+  constructor(code: number) {
+    super(`process.exit(${code})`);
+    this.name = "CliInvokeExit";
+    this.code = code;
+  }
+}
+
+interface PreparedDispatch {
+  pr: ParseResult;
+  parseRoot: CliNode;
+  completionParseRoot: CliRouter;
+  isLeafCompletionIntercept: boolean;
+  leaf: CliLeaf & { handler: CliHandler };
+}
+
+/** Argsbarg runtime for a validated, frozen {@link CliProgram}. */
+export class Cli {
+  readonly program: CliProgram;
+  readonly caps: CliCapabilities;
+  private readonly parseRootMerged: CliRouter;
+  private readonly presentationRoot: CliRouter;
+  private _appConfig?: AnyAppConfigSnapshot;
+
+  constructor(program: CliProgram) {
+    cliValidateProgram(program);
+    Object.freeze(program);
+    this.program = program;
+    this.caps = resolveCapabilities(program);
+    this.parseRootMerged = cliParseRoot(program);
+    this.presentationRoot = cliPresentationRoot(program);
+  }
+
+  get appConfig(): AnyAppConfigSnapshot {
+    if (this._appConfig === undefined) {
+      this._appConfig = this.buildAppConfigSnapshot({
+        exitOnMissing: false,
+        interactive: false,
+      });
+    }
+    return this._appConfig;
+  }
+
+  exportCommandSchema(): CliSchemaExport {
+    return cliSchemaExport(this.program);
+  }
+
+  exportAppConfigSchema(): Record<string, unknown> | undefined {
+    return effectiveJsonSchema(this.program);
+  }
+
+  async run(argv: string[] = process.argv.slice(2)): Promise<never> {
+    assertBuiltinAllowed(argv, this.caps);
+
+    const prep = this.prepareDispatch(argv);
+    if ("error" in prep) {
+      if (prep.error.kind === ParseKind.Help) {
+        process.stdout.write(cliHelpRender(this.parseRootMerged, prep.error.helpPath, false));
+        process.exit(prep.error.helpExplicit ? 0 : 1);
+      }
+      const color = process.stderr.isTTY;
+      const msg = color ? `\u001B[31m${prep.error.errorMsg}\u001B[0m` : prep.error.errorMsg;
+      process.stderr.write(`${msg}\n`);
+      process.stderr.write(cliHelpRender(this.presentationRoot, prep.error.errorHelpPath, true));
+      process.exit(1);
+    }
+
+    const { pr, completionParseRoot, isLeafCompletionIntercept, leaf } = prep;
+
+    if (pr.kind === ParseKind.Ok) {
+      await dispatchBuiltin(this.program, pr, {
+        isLeafCompletionIntercept,
+        parseRoot: completionParseRoot,
+      });
+    }
+
+    const isConfigCmd = pr.path[0] === "config" && this.caps.configCommands;
+    const snapshot = this.buildAppConfigSnapshot({
+      interactive: !isConfigCmd && !!process.stdin.isTTY,
+      exitOnMissing: !isConfigCmd,
+    });
+
+    const ctx = new CliContext(
+      this.program.key,
+      pr.path,
+      pr.args,
+      pr.opts,
+      this.program,
+      "cli",
+      snapshot,
+    );
+    try {
+      await Promise.resolve(leaf.handler(ctx));
+      process.exit(0);
+    } catch (err) {
+      if (err instanceof Error) {
+        process.stderr.write(`${err.message}\n`);
+      }
+      process.exit(1);
+    }
+  }
+
+  async invoke(argv: string[]): Promise<CliInvokeResult> {
+    const prep = this.prepareDispatch(argv, { presentationFallback: true });
+    if ("error" in prep) {
+      if (prep.error.kind === ParseKind.Help) {
+        return {
+          kind: "help",
+          exitCode: 1,
+          stdout: "",
+          stderr: "",
+          errorMsg: "Help is not available via MCP tool calls.",
+        };
+      }
+      return {
+        kind: "error",
+        exitCode: 1,
+        stdout: "",
+        stderr: prep.error.errorMsg,
+        errorMsg: prep.error.errorMsg,
+      };
+    }
+
+    const { pr, completionParseRoot, isLeafCompletionIntercept, leaf } = prep;
+    const snapshot = this.buildAppConfigSnapshot({
+      interactive: false,
+      exitOnMissing: false,
+    });
+
+    const ctx = new CliContext(
+      this.program.key,
+      pr.path,
+      pr.args,
+      pr.opts,
+      this.program,
+      "mcp",
+      snapshot,
+    );
+
+    let stdout = "";
+    let stderr = "";
+    const origExit = process.exit;
+    const origStdoutWrite = process.stdout.write.bind(process.stdout);
+    const origStderrWrite = process.stderr.write.bind(process.stderr);
+    const origConsoleLog = console.log;
+    const origConsoleError = console.error;
+    const origConsoleInfo = console.info;
+    const origConsoleWarn = console.warn;
+
+    process.exit = ((code?: number) => {
+      throw new CliInvokeExit(code ?? 0);
+    }) as typeof process.exit;
+
+    process.stdout.write = ((chunk: string | Uint8Array, ...args: unknown[]) => {
+      stdout += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+      if (typeof args[0] === "function") {
+        (args[0] as () => void)();
+      }
+      return true;
+    }) as typeof process.stdout.write;
+
+    process.stderr.write = ((chunk: string | Uint8Array, ...args: unknown[]) => {
+      stderr += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+      if (typeof args[0] === "function") {
+        (args[0] as () => void)();
+      }
+      return true;
+    }) as typeof process.stderr.write;
+
+    console.log = (...args: unknown[]) => {
+      stdout += `${format(...args)}\n`;
+    };
+    console.info = (...args: unknown[]) => {
+      stdout += `${format(...args)}\n`;
+    };
+    console.warn = (...args: unknown[]) => {
+      stderr += `${format(...args)}\n`;
+    };
+    console.error = (...args: unknown[]) => {
+      stderr += `${format(...args)}\n`;
+    };
+
+    try {
+      if (pr.kind === ParseKind.Ok) {
+        await dispatchBuiltin(this.program, pr, {
+          isLeafCompletionIntercept,
+          parseRoot: completionParseRoot,
+        });
+      }
+
+      await Promise.resolve(leaf.handler(ctx));
+      return { kind: "ok", exitCode: 0, stdout, stderr };
+    } catch (err) {
+      if (err instanceof CliInvokeExit) {
+        if (err.code === 0) {
+          return { kind: "ok", exitCode: 0, stdout, stderr };
+        }
+        const msg = stderr.trim() || `Exit code ${err.code}`;
+        return { kind: "error", exitCode: err.code, stdout, stderr, errorMsg: msg };
+      }
+      if (err instanceof Error) {
+        return {
+          kind: "error",
+          exitCode: 1,
+          stdout,
+          stderr: `${err.message}\n`,
+          errorMsg: err.message,
+        };
+      }
+      return {
+        kind: "error",
+        exitCode: 1,
+        stdout,
+        stderr: "Unknown error\n",
+        errorMsg: "Unknown error",
+      };
+    } finally {
+      process.exit = origExit;
+      process.stdout.write = origStdoutWrite;
+      process.stderr.write = origStderrWrite;
+      console.log = origConsoleLog;
+      console.error = origConsoleError;
+      console.info = origConsoleInfo;
+      console.warn = origConsoleWarn;
+    }
+  }
+
+  async serveMcp(): Promise<never> {
+    try {
+      if (this.program.mcpServer) {
+        bootstrapMcpEnv(this.program.mcpServer);
+      }
+      bootstrapAppConfig(this.program, { validateFile: false });
+      await mcpServeStdioLoop(this);
+      process.exit(0);
+    } catch (err) {
+      if (err instanceof Error) {
+        process.stderr.write(`${err.message}\n`);
+      } else {
+        process.stderr.write("MCP server error.\n");
+      }
+      process.exit(1);
+    }
+  }
+
+  private prepareDispatch(
+    argv: string[],
+    opts?: { presentationFallback?: boolean },
+  ): PreparedDispatch | { error: ParseResult } {
+    const program = this.program;
+    let parseRoot: CliNode;
+    let completionParseRoot: CliRouter = opts?.presentationFallback
+      ? this.presentationRoot
+      : this.parseRootMerged;
+    let isLeafCompletionIntercept = false;
+
+    if (isCliLeaf(program)) {
+      const intercept = builtinInterceptRoot(program, argv);
+      if (intercept.isLeafCompletionIntercept || intercept.parseRoot !== program) {
+        parseRoot = intercept.parseRoot;
+        completionParseRoot = isCliRouter(intercept.parseRoot)
+          ? intercept.parseRoot
+          : opts?.presentationFallback
+            ? this.presentationRoot
+            : this.parseRootMerged;
+        isLeafCompletionIntercept = intercept.isLeafCompletionIntercept;
+      } else {
+        parseRoot = program;
+      }
+    } else {
+      parseRoot = this.parseRootMerged;
+    }
+
+    let pr = parse(parseRoot, argv);
+    pr = postParseValidate(parseRoot, pr);
+
+    if (pr.kind !== ParseKind.Ok) {
+      return { error: pr };
+    }
+
+    let current: CliNode = parseRoot;
+    for (const seg of pr.path) {
+      if (!isCliRouter(current)) {
+        const msg = "Internal error: missing handler for path.";
+        return {
+          error: {
+            kind: ParseKind.Error,
+            path: pr.path,
+            args: pr.args,
+            opts: pr.opts,
+            helpExplicit: false,
+            helpPath: [],
+            errorMsg: msg,
+            errorHelpPath: pr.path,
+          },
+        };
+      }
+      const ch = current.commands.find((candidate) => candidate.key === seg);
+      if (!ch) {
+        const msg = "Internal error: missing handler for path.";
+        return {
+          error: {
+            kind: ParseKind.Error,
+            path: pr.path,
+            args: pr.args,
+            opts: pr.opts,
+            helpExplicit: false,
+            helpPath: [],
+            errorMsg: msg,
+            errorHelpPath: pr.path,
+          },
+        };
+      }
+      current = ch;
+    }
+
+    if (!isCliLeaf(current) || !current.handler) {
+      const msg = "Internal error: missing handler for path.";
+      return {
+        error: {
+          kind: ParseKind.Error,
+          path: pr.path,
+          args: pr.args,
+          opts: pr.opts,
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: msg,
+          errorHelpPath: pr.path,
+        },
+      };
+    }
+
+    return {
+      pr,
+      parseRoot,
+      completionParseRoot,
+      isLeafCompletionIntercept,
+      leaf: current,
+    };
+  }
+
+  private buildAppConfigSnapshot(opts: EnsureAppConfigOpts): AnyAppConfigSnapshot {
+    const bootstrap = ensureAppConfig(this.program, opts);
+    const snapshot = bootstrap
+      ? createAppConfigSnapshot(this.program, bootstrap.fileData, bootstrap.resolved)
+      : createAppConfigSnapshot(this.program, {}, {});
+    this._appConfig = snapshot;
+    return snapshot;
+  }
+}

package/src/config/bootstrap.ts

@@ -0,0 +1,265 @@
+/*
+Bootstrap: load config, validate, resolve, export, TTY prompts, install --configure.
+*/
+
+import { existsSync, readSync } from "node:fs";
+import type { CliAppConfigEntry, CliProgram } from "../types.ts";
+import {
+  configEntryRequired,
+  configEntrySensitive,
+  defaultConfigEntryTitle,
+  jsonSchemaRequiredKeys,
+} from "./entry.ts";
+import {
+  displayAppConfigPath,
+  readAppConfigFile,
+  readAppConfigFileRaw,
+  resolveAppConfigPath,
+  writeAppConfigFile,
+} from "./file.ts";
+import type { ResolvedConfig } from "./resolve.ts";
+import {
+  exportConfigToEnv,
+  formatMissingConfigMessage,
+  missingRequiredConfig,
+  resolveAppConfig,
+  stringifyConfigValue,
+} from "./resolve.ts";
+import { effectiveJsonSchema } from "./schema.ts";
+
+export interface EnsureAppConfigOpts {
+  interactive: boolean;
+  exitOnMissing: boolean;
+  configure?: boolean;
+}
+
+export interface ConfigBootstrapResult {
+  fileData: Record<string, unknown>;
+  resolved: ResolvedConfig;
+}
+
+/** Load, validate, resolve, and export config. */
+export function bootstrapAppConfig(
+  program: CliProgram,
+  opts: { validateFile: boolean },
+): ConfigBootstrapResult {
+  const path = resolveAppConfigPath(program);
+  const fileData = opts.validateFile ? readAppConfigFile(program) : readAppConfigFileRaw(path);
+  const resolved = resolveAppConfig(program, fileData);
+  exportConfigToEnv(program, resolved);
+  return { fileData, resolved };
+}
+
+function readPromptLine(mask: boolean): string {
+  if (!mask) {
+    const buf = Buffer.alloc(4096);
+    const n = readSync(0, buf, { length: 4096 });
+    return buf.toString("utf8", 0, n).replace(/\r?\n$/, "");
+  }
+  let result = "";
+  const buf = Buffer.alloc(1);
+  while (true) {
+    const n = readSync(0, buf, { length: 1 });
+    if (n <= 0) {
+      break;
+    }
+    const byte = buf[0];
+    if (byte === undefined) {
+      continue;
+    }
+    if (byte === 10 || byte === 13) {
+      break;
+    }
+    if (byte === 127 || byte === 8) {
+      result = result.slice(0, -1);
+      continue;
+    }
+    result += String.fromCharCode(byte);
+    process.stderr.write("*");
+  }
+  process.stderr.write("\n");
+  return result;
+}
+
+function promptConfigKey(
+  key: string,
+  entry: CliAppConfigEntry,
+  current: unknown,
+  configure: boolean,
+  jsonSchemaRequired: Set<string> | undefined,
+): unknown {
+  const title = entry.title ?? defaultConfigEntryTitle(key);
+  const required = configEntryRequired(key, entry, jsonSchemaRequired);
+  const heading = required || !configure ? title : `${title} (optional)`;
+  process.stderr.write(`${heading}\n`);
+  process.stderr.write(`  ${entry.description}\n`);
+  const hasCurrent = current !== undefined && current !== null && String(current).length > 0;
+  if (hasCurrent) {
+    const sensitive = configEntrySensitive(key, entry);
+    process.stderr.write(`Current: ${sensitive ? "REDACTED" : stringifyConfigValue(current)}\n`);
+    process.stderr.write("Value (Enter to keep): ");
+  } else {
+    process.stderr.write("Value: ");
+  }
+  const input = readPromptLine(hasCurrent && configEntrySensitive(key, entry));
+  if (input.length === 0 && hasCurrent) {
+    return current;
+  }
+  return input.length > 0 ? input : undefined;
+}
+
+function promptMissingRequired(program: CliProgram): Record<string, unknown> {
+  const appConfig = program.appConfig;
+  const updates: Record<string, unknown> = {};
+  if (!appConfig) {
+    return updates;
+  }
+  const jsonSchema = effectiveJsonSchema(program);
+  const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
+  const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+  for (const [key, entry] of Object.entries(appConfig.entries)) {
+    if (!configEntryRequired(key, entry, fromSchema)) {
+      continue;
+    }
+    const current = resolved[key];
+    if (current !== undefined && current !== null && String(current).length > 0) {
+      continue;
+    }
+    const value = promptConfigKey(key, entry, undefined, false, fromSchema);
+    if (value !== undefined && String(value).length > 0) {
+      updates[key] = value;
+    }
+  }
+  return updates;
+}
+
+/** Interactive `install --configure`. */
+export function runInstallConfigure(program: CliProgram): { path: string; changed: boolean } {
+  if (!program.appConfig) {
+    throw new Error("install --configure requires program.appConfig on the program root.");
+  }
+  if (!process.stdin.isTTY) {
+    const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+    const missing = missingRequiredConfig(program, resolved);
+    if (missing.length > 0) {
+      process.stderr.write(`${formatMissingConfigMessage(program, missing)}\n`);
+    } else {
+      process.stderr.write("install --configure requires an interactive terminal.\n");
+    }
+    process.exit(1);
+  }
+
+  const path = resolveAppConfigPath(program);
+  const existing = readAppConfigFileRaw(path);
+  const jsonSchema = effectiveJsonSchema(program);
+  const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
+  const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+  const next: Record<string, unknown> = { ...existing };
+  let changed = false;
+
+  for (const [key, entry] of Object.entries(program.appConfig.entries)) {
+    const current = resolved[key];
+    const before = next[key];
+    const value = promptConfigKey(key, entry, current, true, fromSchema);
+    if (value !== undefined && String(value).length > 0) {
+      if (JSON.stringify(value) !== JSON.stringify(before)) {
+        changed = true;
+      }
+      next[key] = value;
+    }
+  }
+
+  if (changed) {
+    writeAppConfigFile(program, next);
+    const updated = resolveAppConfig(program, next);
+    exportConfigToEnv(program, updated);
+    return { path, changed: true };
+  }
+  return { path, changed: false };
+}
+
+/** Config status for install --status (values never included). */
+export function appConfigStatus(program: CliProgram):
+  | {
+      path: string;
+      exists: boolean;
+      required: Array<{ key: string; set: boolean }>;
+    }
+  | undefined {
+  if (!program.appConfig) {
+    return undefined;
+  }
+  const path = resolveAppConfigPath(program);
+  let fileData: Record<string, unknown> = {};
+  try {
+    fileData = readAppConfigFile(program);
+  } catch {
+    fileData = readAppConfigFileRaw(path);
+  }
+  const resolved = resolveAppConfig(program, fileData);
+  exportConfigToEnv(program, resolved);
+  const jsonSchema = effectiveJsonSchema(program);
+  const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
+  const required = Object.entries(program.appConfig.entries)
+    .filter(([key, entry]) => configEntryRequired(key, entry, fromSchema))
+    .map(([key]) => ({
+      key,
+      set:
+        resolved[key] !== undefined && resolved[key] !== null && String(resolved[key]).length > 0,
+    }));
+  return { path, exists: existsSync(path), required };
+}
+
+/** Loads config, optionally prompts, and enforces required keys. */
+export function ensureAppConfig(
+  program: CliProgram,
+  opts: EnsureAppConfigOpts,
+): ConfigBootstrapResult | undefined {
+  if (!program.appConfig) {
+    return undefined;
+  }
+
+  let fileData: Record<string, unknown>;
+  try {
+    fileData = readAppConfigFile(program);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${msg}\n`);
+    process.exit(1);
+  }
+
+  let resolved = resolveAppConfig(program, fileData);
+  exportConfigToEnv(program, resolved);
+
+  if (opts.interactive && process.stdin.isTTY) {
+    if (opts.configure) {
+      runInstallConfigure(program);
+      fileData = readAppConfigFileRaw(resolveAppConfigPath(program));
+      resolved = resolveAppConfig(program, fileData);
+      exportConfigToEnv(program, resolved);
+      return { fileData, resolved };
+    }
+    const updates = promptMissingRequired(program);
+    if (Object.keys(updates).length > 0) {
+      const merged = { ...fileData, ...updates };
+      writeAppConfigFile(program, merged);
+      fileData = merged;
+      resolved = resolveAppConfig(program, fileData);
+      exportConfigToEnv(program, resolved);
+    }
+  }
+
+  const missing = missingRequiredConfig(program, resolved);
+  if (missing.length === 0) {
+    return { fileData, resolved };
+  }
+
+  if (opts.exitOnMissing) {
+    process.stderr.write(`${formatMissingConfigMessage(program, missing)}\n`);
+    process.exit(1);
+  }
+
+  return { fileData, resolved };
+}
+
+export { displayAppConfigPath };