argsbarg 0.1.0

package/src/parse.ts

@@ -0,0 +1,487 @@
+/*
+This module parses argv into commands, options, and positional tails.
+It resolves fallback routing, tracks help requests, and shapes the parse result that
+later validation and runtime dispatch both consume.
+
+It keeps handler dispatch and help on one parser so the CLI behavior stays consistent
+across every entry path.
+*/
+
+import { CliContext } from "./context.ts";
+import {
+  CliCommand,
+  CliOptionDef,
+  CliOptionKind,
+  CliFallbackMode,
+} from "./types.ts";
+import { fullStringIsDouble } from "./utils.ts";
+
+// ── Parse Result ──────────────────────────────────────────────────────────────
+
+/** Outcome of a parse: success, help request, or fatal user error. */
+export enum ParseKind {
+  Ok = "ok",
+  Help = "help",
+  Error = "error",
+}
+
+/** Structured parse output: routed path, merged options, positional args, and help/error metadata. */
+export interface ParseResult {
+  kind: ParseKind;
+  path: string[];
+  opts: Record<string, string>;
+  args: string[];
+  helpExplicit: boolean;
+  helpPath: string[];
+  errorMsg: string;
+  errorHelpPath: string[];
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const helpShort = "-h";
+const helpLong = "--help";
+
+function isHelpTok(tok: string): boolean {
+  return tok === helpShort || tok === helpLong;
+}
+
+function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
+  return cmds.find((c) => c.key === name);
+}
+
+function findOptionByName(defs: CliOptionDef[], name: string): CliOptionDef | undefined {
+  return defs.find((o) => o.name === name);
+}
+
+function findOptionDefByShort(defs: CliOptionDef[], short: string): CliOptionDef | undefined {
+  return defs.find((o) => !o.positional && o.shortName === short);
+}
+
+// ── Option Consumption ────────────────────────────────────────────────────────
+
+interface ConsumeReport {
+  err: string | null;
+  stoppedOnUnknown: boolean;
+  sawDoubleDash: boolean;
+}
+
+function consumeOptions(
+  defs: CliOptionDef[],
+  lenientUnknown: boolean,
+  argv: string[],
+  i: number,
+  opts: Record<string, string>,
+): { report: ConsumeReport; nextIndex: number } {
+  let idx = i;
+
+  function consumeLong(tok: string): string | null {
+    const body = tok.slice(2);
+    let optName: string;
+    let inlineVal: string | undefined;
+
+    const eqIdx = body.indexOf("=");
+    if (eqIdx !== -1) {
+      optName = body.slice(0, eqIdx);
+      inlineVal = body.slice(eqIdx + 1);
+    } else {
+      optName = body;
+      inlineVal = undefined;
+    }
+
+    const def = findOptionByName(defs, optName);
+    if (!def) {
+      if (lenientUnknown) return "";
+      return `Unknown option: --${optName}`;
+    }
+
+    if (inlineVal !== undefined) {
+      if (def.kind === CliOptionKind.Presence) {
+        opts[def.name] = "1";
+      } else {
+        opts[def.name] = inlineVal;
+      }
+      idx += 1;
+      return null;
+    }
+
+    if (def.kind === CliOptionKind.Presence) {
+      opts[def.name] = "1";
+    } else {
+      idx += 1;
+      if (idx >= argv.length) {
+        return `Missing value for option: --${optName}`;
+      }
+      opts[def.name] = argv[idx];
+    }
+    idx += 1;
+    return null;
+  }
+
+  function consumeShort(tok: string): string | null {
+    if (tok.length < 2) return `Unexpected option token: ${tok}`;
+    const shorts = tok.slice(1);
+    let j = 0;
+
+    while (j < shorts.length) {
+      const shortChar = shorts[j];
+      const def = findOptionDefByShort(defs, shortChar);
+
+      if (!def) {
+        if (lenientUnknown) return "";
+        return `Unknown option: -${shortChar}`;
+      }
+
+      if (def.kind === CliOptionKind.Presence) {
+        opts[def.name] = "1";
+        j += 1;
+        continue;
+      }
+
+      // Non-presence short option: cannot be bundled
+      if (j !== 0 || j + 1 < shorts.length) {
+        return `Short option -${shortChar} requires a value and cannot be bundled: ${tok}`;
+      }
+
+      idx += 1;
+      if (idx >= argv.length) {
+        return `Missing value for option: -${shortChar}`;
+      }
+      opts[def.name] = argv[idx];
+      idx += 1;
+      return null;
+    }
+
+    idx += 1;
+    return null;
+  }
+
+  while (idx < argv.length) {
+    const tok = argv[idx];
+
+    if (isHelpTok(tok)) break;
+    if (!tok.startsWith("-")) break;
+
+    if (tok === "--") {
+      idx += 1;
+      return { report: { err: null, stoppedOnUnknown: false, sawDoubleDash: true }, nextIndex: idx };
+    }
+
+    if (tok.startsWith("--")) {
+      const err = consumeLong(tok);
+      if (err === "") return { report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false }, nextIndex: idx };
+      if (err) return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
+    } else {
+      const err = consumeShort(tok);
+      if (err === "") return { report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false }, nextIndex: idx };
+      if (err) return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
+    }
+  }
+
+  return { report: { err: null, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
+}
+
+// ── Positional Collection ─────────────────────────────────────────────────────
+
+function finishLeaf(
+  node: CliCommand,
+  startIdx: number,
+  argv: string[],
+  path: string[],
+  opts: Record<string, string>,
+): ParseResult {
+  function errorResult(msg: string): ParseResult {
+    const pr: ParseResult = {
+      kind: ParseKind.Error,
+      path: [],
+      opts: {},
+      args: [],
+      helpExplicit: false,
+      helpPath: [],
+      errorMsg: msg,
+      errorHelpPath: path,
+    };
+    return pr;
+  }
+
+  let idx = startIdx;
+  const args: string[] = [];
+
+  for (const p of node.positionals ?? []) {
+    if (!p.positional) continue;
+
+    if (p.argMax === 1) {
+      if (p.argMin >= 1) {
+        if (idx >= argv.length) {
+          return errorResult(`Missing positional argument: ${p.name}`);
+        }
+        args.push(argv[idx]);
+        idx += 1;
+      } else if (idx < argv.length) {
+        args.push(argv[idx]);
+        idx += 1;
+      }
+      continue;
+    }
+
+    let count = 0;
+    if (p.argMax === 0) {
+      while (idx < argv.length) {
+        args.push(argv[idx]);
+        idx += 1;
+        count += 1;
+      }
+    } else {
+      while (count < p.argMax && idx < argv.length) {
+        args.push(argv[idx]);
+        idx += 1;
+        count += 1;
+      }
+    }
+    if (count < p.argMin) {
+      return errorResult(`Expected at least ${p.argMin} argument(s) for ${p.name}, got ${count}`);
+    }
+  }
+
+  if (idx < argv.length) {
+    return errorResult("Unexpected extra arguments");
+  }
+
+  return { kind: ParseKind.Ok, path, opts, args, helpExplicit: false, helpPath: [], errorMsg: "", errorHelpPath: [] };
+}
+
+// ── Main Parser ───────────────────────────────────────────────────────────────
+
+function helpResult(p: string[], explicit: boolean): ParseResult {
+  return {
+    kind: ParseKind.Help,
+    path: [],
+    opts: {},
+    args: [],
+    helpExplicit: explicit,
+    helpPath: p,
+    errorMsg: "",
+    errorHelpPath: [],
+  };
+}
+
+export function parse(root: CliCommand, argv: string[]): ParseResult {
+  let i = 0;
+  const path: string[] = [];
+  const opts: Record<string, string> = {};
+
+  const rootLenient =
+    root.fallbackCommand !== undefined &&
+    ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
+
+  // Consume root-level options first
+  const rootRep = consumeOptions(root.options ?? [], rootLenient, argv, i, opts);
+  if (rootRep.report.err) {
+    return {
+      kind: ParseKind.Error,
+      path: [],
+      opts: {},
+      args: [],
+      helpExplicit: false,
+      helpPath: [],
+      errorMsg: rootRep.report.err,
+      errorHelpPath: [],
+    };
+  }
+  i = rootRep.nextIndex;
+  let forcePositionals = rootRep.report.sawDoubleDash;
+
+  if (i < argv.length && !forcePositionals && isHelpTok(argv[i])) {
+    return helpResult([], true);
+  }
+
+  // Determine which subcommand to route to
+  let cmdName: string;
+  let node: CliCommand | undefined;
+
+  if (i >= argv.length) {
+    if (root.fallbackCommand !== undefined && ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOnly || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown)) {
+      cmdName = root.fallbackCommand;
+      node = findChild(root.children ?? [], cmdName);
+      if (!node) {
+        return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
+      }
+    } else {
+      return helpResult([], false);
+    }
+  } else {
+    const peek = argv[i];
+    const childPick = !forcePositionals ? findChild(root.children ?? [], peek) : undefined;
+
+    if (childPick !== undefined) {
+      cmdName = peek;
+      i += 1;
+      node = childPick;
+    } else {
+      const canRouteUnknown =
+        root.fallbackCommand !== undefined &&
+        ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown ||
+          (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
+
+      if (canRouteUnknown) {
+        cmdName = root.fallbackCommand!;
+        node = findChild(root.children ?? [], cmdName);
+        if (!node) {
+          return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
+        }
+      } else {
+        cmdName = peek;
+        if (!forcePositionals) i += 1;
+        node = findChild(root.children ?? [], cmdName);
+        if (!node) {
+          return {
+            kind: ParseKind.Error,
+            path: [],
+            opts: {},
+            args: [],
+            helpExplicit: false,
+            helpPath: [],
+            errorMsg: forcePositionals ? `Expected subcommand but got positional: ${cmdName}` : `Unknown command: ${cmdName}`,
+            errorHelpPath: path,
+          };
+        }
+      }
+    }
+  }
+
+  path.push(cmdName);
+  let current = node!;
+
+  // Walk the command tree
+  while (true) {
+    if (!forcePositionals) {
+      const orep = consumeOptions(current.options ?? [], false, argv, i, opts);
+      if (orep.report.err) {
+        return {
+          kind: ParseKind.Error,
+          path,
+          opts: {},
+          args: [],
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: orep.report.err,
+          errorHelpPath: path,
+        };
+      }
+      i = orep.nextIndex;
+      if (orep.report.sawDoubleDash) {
+        forcePositionals = true;
+      }
+    }
+
+    if (i < argv.length && !forcePositionals && isHelpTok(argv[i])) {
+      return helpResult(path, true);
+    }
+
+    if (i >= argv.length) {
+      if ((current.children ?? []).length > 0) {
+        return helpResult(path, false);
+      }
+      return finishLeaf(current, i, argv, path, opts);
+    }
+
+    const tok = argv[i];
+    if (!forcePositionals && tok.startsWith("-")) {
+      return {
+        kind: ParseKind.Error,
+        path,
+        opts: {},
+        args: [],
+        helpExplicit: false,
+        helpPath: [],
+        errorMsg: `Unexpected option token: ${tok}`,
+        errorHelpPath: path,
+      };
+    }
+
+    if (!forcePositionals) {
+      const childOpt = findChild(current.children ?? [], tok);
+      if (childOpt !== undefined) {
+        i += 1;
+        path.push(tok);
+        current = childOpt;
+        continue;
+      }
+    }
+
+    if ((current.children ?? []).length > 0) {
+      return {
+        kind: ParseKind.Error,
+        path,
+        opts: {},
+        args: [],
+        helpExplicit: false,
+        helpPath: [],
+        errorMsg: forcePositionals ? `Expected subcommand but got positional: ${tok}` : `Unknown subcommand: ${tok}`,
+        errorHelpPath: path,
+      };
+    }
+
+    return finishLeaf(current, i, argv, path, opts);
+  }
+}
+
+// ── Post-Parse Validation ─────────────────────────────────────────────────────
+
+export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResult {
+  if (pr.kind !== ParseKind.Ok) return pr;
+
+  let defs = [...(root.options ?? [])];
+  let cmds = root.children ?? [];
+
+  for (const seg of pr.path) {
+    const ch = findChild(cmds, seg);
+    if (!ch) {
+      return {
+        kind: ParseKind.Error,
+        path: pr.path,
+        opts: {},
+        args: [],
+        helpExplicit: false,
+        helpPath: [],
+        errorMsg: "Internal path error",
+        errorHelpPath: pr.path,
+      };
+    }
+    defs.push(...(ch.options ?? []));
+    defs.push(...(ch.positionals ?? []));
+    cmds = ch.children ?? [];
+  }
+
+  for (const [k, v] of Object.entries(pr.opts)) {
+    const d = findOptionByName(defs, k);
+    if (!d) {
+      return {
+        kind: ParseKind.Error,
+        path: pr.path,
+        opts: {},
+        args: [],
+        helpExplicit: false,
+        helpPath: [],
+        errorMsg: `Unknown option key: ${k}`,
+        errorHelpPath: pr.path,
+      };
+    }
+    if (d.kind === CliOptionKind.Number) {
+      if (!fullStringIsDouble(v)) {
+        return {
+          kind: ParseKind.Error,
+          path: pr.path,
+          opts: {},
+          args: [],
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: `Invalid number for option --${k}: ${v}`,
+          errorHelpPath: pr.path,
+        };
+      }
+    }
+  }
+
+  return pr;
+}

package/src/runtime.ts

@@ -0,0 +1,113 @@
+/*
+This module runs parsed commands, help, errors, completion, and leaf handlers.
+It owns the top-level control flow after parsing, including validation failures,
+shell completion dispatch, and leaf handler invocation.
+
+It keeps execution flow out of the public barrel so the exported API stays small and
+the runtime responsibilities remain easy to reason about.
+*/
+
+import { cliBuiltinCompletionGroup, completionBashScript, completionZshScript } from "./completion.ts";
+import { CliContext } from "./context.ts";
+import { cliHelpRender } from "./help.ts";
+import { parse, postParseValidate } from "./parse.ts";
+import { CliCommand } from "./types.ts";
+import { cliValidateRoot } from "./validate.ts";
+
+/**
+ * Merges the caller's program root with the reserved `completion` subtree.
+ */
+function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
+  const merged = { ...root };
+  merged.children = [...(root.children ?? []), cliBuiltinCompletionGroup(root.key)];
+  return merged;
+}
+
+/**
+ * Validates the schema, parses argv, prints help or errors, runs completion or the leaf handler, then exits.
+ *
+ * @param root The root CliCommand.
+ * @param argv Override the default argv (process.argv.slice(2)).
+ */
+export async function cliRun(root: CliCommand, argv: string[] = process.argv.slice(2)): Promise<never> {
+  try {
+    cliValidateRoot(root);
+  } catch (err) {
+    if (err instanceof Error) {
+      process.stderr.write(err.message + "\n");
+    } else {
+      process.stderr.write("Invalid CLI definition.\n");
+    }
+    process.exit(1);
+  }
+
+  const merged = cliRootMergedWithBuiltins(root);
+  let pr = parse(merged, argv);
+  pr = postParseValidate(merged, pr);
+
+  if (pr.kind === "help") {
+    process.stdout.write(cliHelpRender(merged, pr.helpPath, false));
+    process.exit(pr.helpExplicit ? 0 : 1);
+  }
+
+  if (pr.kind === "error") {
+    const color = process.stderr.isTTY;
+    const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
+    process.stderr.write(msg + "\n");
+    process.stderr.write(cliHelpRender(merged, pr.errorHelpPath, true));
+    process.exit(1);
+  }
+
+  if (pr.path.length === 0) {
+    process.stderr.write("Internal error: empty path.\n");
+    process.exit(1);
+  }
+
+  if (pr.path[0] === "completion") {
+    if (pr.path[1] === "bash") {
+      process.stdout.write(completionBashScript(merged));
+      process.exit(0);
+    }
+    if (pr.path[1] === "zsh") {
+      process.stdout.write(completionZshScript(merged));
+      process.exit(0);
+    }
+  }
+
+  let current = merged;
+  for (const seg of pr.path) {
+    const ch = (current.children ?? []).find((candidate: CliCommand) => candidate.key === seg);
+    if (!ch) {
+      process.stderr.write("Internal error: missing handler for path.\n");
+      process.exit(1);
+    }
+    current = ch;
+  }
+
+  if (!current.handler) {
+    process.stderr.write("Internal error: missing handler for path.\n");
+    process.exit(1);
+  }
+
+  const ctx = new CliContext(merged.key, pr.path, pr.args, pr.opts, merged);
+  try {
+    await Promise.resolve(current.handler(ctx));
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof Error) {
+      process.stderr.write(err.message + "\n");
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Prints a red error line and contextual help on stderr, then exits with status 1.
+ */
+export function cliErrWithHelp(ctx: CliContext, msg: string): never {
+  const color = process.stderr.isTTY;
+  const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
+  process.stderr.write(line + "\n");
+  process.stderr.write(cliHelpRender(ctx.schema, ctx.commandPath, true));
+  process.exit(1);
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+/*
+This module defines the CLI schema, option kinds, fallback modes, and helpers.
+It is the shared declarative model that parsing, validation, help, and completion all
+read from, so the package has one source of truth.
+
+It gives the package one shared model for both library users and internal modules.
+*/
+
+import type { CliContext } from "./context.ts";
+
+/**
+ * Option kinds: presence (boolean flag), string (free-form text), or number (strict double).
+ */
+export enum CliOptionKind {
+  Presence = "presence",
+  String = "string",
+  Number = "number",
+}
+
+/**
+ * When fallbackCommand is used for missing or unknown top-level tokens.
+ * Only the program root may set a non-default mode or a non-nil fallbackCommand.
+ */
+export enum CliFallbackMode {
+  /** Use the fallback only when argv has no first subcommand token. */
+  MissingOnly = "missingOnly",
+  /** Use the fallback when the first token is missing or not a known child name. */
+  MissingOrUnknown = "missingOrUnknown",
+  /** Use the fallback only when the first token is not a known child name. */
+  UnknownOnly = "unknownOnly",
+}
+
+/**
+ * One CLI flag, option, or positional definition.
+ */
+export interface CliOptionDef {
+  /** Option name (e.g., "name", "verbose"). */
+  name: string;
+  /** Description shown in help. */
+  description: string;
+  /** Option kind: presence flag, string value, or number value. */
+  kind: CliOptionKind;
+  /** Short option character (e.g., 'n' for -n). */
+  shortName?: string;
+  /** Whether this is a positional argument (true) or a flag/option (false). */
+  positional: boolean;
+  /** Minimum number of values required (for positionals). */
+  argMin: number;
+  /** Maximum number of values allowed (0 = unlimited, for positionals). */
+  argMax: number;
+}
+
+/**
+ * A command node: routing group (has children) or leaf (has handler).
+ *
+ * The value passed to cliRun is the program root: name is the app/binary name,
+ * children are top-level subcommands, options are global flags.
+ * The root must not set handler or declare positionals (validated at startup).
+ */
+export interface CliCommand {
+  /** Program or command key (e.g., "myapp", "stat", "owner"). */
+  key: string;
+  /** Short description shown in help. */
+  description: string;
+  /** Additional notes shown in help (supports {app} placeholder). */
+  notes?: string;
+  /** Global or command-level flags/options. */
+  options?: CliOptionDef[];
+  /** Positional argument definitions. */
+  positionals?: CliOptionDef[];
+  /** Child subcommands (empty for leaf commands). */
+  children?: CliCommand[];
+  /** Handler function for leaf commands. */
+  handler?: CliHandler;
+  /** Default top-level subcommand when argv omits a command or uses an unknown first token (root only). */
+  fallbackCommand?: string;
+  /** How fallbackCommand is applied (root only). */
+  fallbackMode?: CliFallbackMode;
+}
+
+/**
+ * Handler closure type for leaf commands.
+ * Supports both sync and async handlers.
+ */
+export type CliHandler = (ctx: CliContext) => void | Promise<void>;
+
+/**
+ * Error thrown when the static CliCommand tree violates ArgsBarg rules.
+ */
+export class CliSchemaValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CliSchemaValidationError";
+  }
+}
+
+/**
+ * Creates a new CliOptionDef with sensible defaults.
+ */
+export function createOption(
+  name: string,
+  description: string,
+  options?: Partial<CliOptionDef>,
+): CliOptionDef {
+  return {
+    name,
+    description,
+    kind: options?.kind ?? CliOptionKind.Presence,
+    shortName: options?.shortName,
+    positional: options?.positional ?? false,
+    argMin: options?.argMin ?? 1,
+    argMax: options?.argMax ?? 1,
+  };
+}