argsbarg 0.1.0 → 1.0.1

package/src/completion.ts

@@ -8,43 +8,51 @@ It keeps completion aligned with the runtime schema so the generated commands,
 options, and descriptions stay in sync with the CLI definition.
 */
 
-import { CliCommand, CliOptionDef } from "./types.ts";
+import { CliCommand, CliOption } from "./types.ts";
 
 // ── Shared Types ───────────────────────────────────────────────────────────────
 
+/** One tab-completion scope: child commands, options, and path key for the schema walk. */
 interface ScopeRec {
+  /** Child `CliCommand` keys at this scope. */
   kids: CliCommand[];
-  opts: CliOptionDef[];
+  /** Options in scope (for option token completion). */
+  opts: CliOption[];
+  /** `/`-separated path of command keys from the root, or `""` for the root. */
   path: string;
+  /** True when a positional tail exists (bash/zsh may offer filenames). */
   wantsFiles: boolean;
 }
 
+/** True if the command declares at least one positional (used to enable file completion). */
 function hasPositionalArguments(cmd: CliCommand): boolean {
-  return (cmd.positionals ?? []).some((p) => p.positional);
+  return (cmd.positionals ?? []).length > 0;
 }
 
+/** Recursively appends a scope record for `cmd` and its subtree into `acc`. */
 function walkScopes(cmdPath: string, cmd: CliCommand, acc: ScopeRec[]): void {
   acc.push({
-    kids: cmd.children ?? [],
+    kids: cmd.commands ?? [],
     opts: cmd.options ?? [],
     path: cmdPath,
     wantsFiles: hasPositionalArguments(cmd),
   });
-  for (const ch of cmd.children ?? []) {
+  for (const ch of cmd.commands ?? []) {
     const nextPath = cmdPath === "" ? ch.key : cmdPath + "/" + ch.key;
     walkScopes(nextPath, ch, acc);
   }
 }
 
+/** Flattens the schema into a list of completion scopes (root + every command path). */
 function collectScopes(schema: CliCommand): ScopeRec[] {
   const acc: ScopeRec[] = [];
   acc.push({
-    kids: schema.children ?? [],
+    kids: schema.commands ?? [],
     opts: schema.options ?? [],
     path: "",
     wantsFiles: false,
   });
-  for (const c of schema.children ?? []) {
+  for (const c of schema.commands ?? []) {
     walkScopes(c.key, c, acc);
   }
   return acc;
@@ -52,14 +60,17 @@ function collectScopes(schema: CliCommand): ScopeRec[] {
 
 // ── Helpers ────────────────────────────────────────────────────────────────────
 
+/** Produces a shell-safe identifier from the app or command name (alnum → `_`). */
 function identToken(s: string): string {
   return s.replace(/[^a-zA-Z0-9]/g, "_");
 }
 
+/** Escapes a string for use inside single quotes in generated shell scripts. */
 function escShellSingleQuoted(s: string): string {
   return s.replace(/'/g, "'\\''");
 }
 
+/** Sanitizes the app key for generated shell function names (non-alnum removed). */
 function mainName(schemaName: string): string {
   return schemaName.replace(/[^a-zA-Z0-9]/g, "_");
 }
@@ -69,6 +80,7 @@ const kHelpShort = "-h";
 
 // ── Bash Completion ────────────────────────────────────────────────────────────
 
+/** Emits the bash helper that classifies a `--long` or `--long=val` token for each scope. */
 function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
   let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
   o += "  local sid=\"$1\" w=\"$2\" nw=\"$3\"\n";
@@ -78,7 +90,6 @@ function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
     o += "      case $w in\n";
     o += "        " + kHelpLong + "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n".replace(/\$\{kHelpLong\}/g, kHelpLong).replace(/\$\{kHelpShort\}/g, kHelpShort);
     for (const op of sc.opts) {
-      if (op.positional) continue;
       const base = "--" + op.name;
       if (op.kind === "presence") {
         o += "        " + base + "|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base);
@@ -97,6 +108,7 @@ function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
   return o;
 }
 
+/** Emits the bash helper that classifies a bundled/short `-x` / `-abc` token for each scope. */
 function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
   let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
   o += "  local sid=\"$1\" w=\"$2\"\n";
@@ -112,7 +124,6 @@ function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
     o += "        case $ch in\n";
     let boolChars = "";
     for (const op of sc.opts) {
-      if (op.positional) continue;
       if (!op.shortName) continue;
       if (op.kind === "presence") {
         boolChars += op.shortName + "|";
@@ -139,6 +150,7 @@ function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
   return o;
 }
 
+/** Emits the bash helper that maps a non-option token to the child scope id. */
 function emitMatchChild(ident: string, scopes: ScopeRec[], pathIndex: Record<string, number>): string {
   let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
   o += "  local sid=\"$1\" w=\"$2\"\n";
@@ -161,6 +173,7 @@ function emitMatchChild(ident: string, scopes: ScopeRec[], pathIndex: Record<str
   return o;
 }
 
+/** Emits bash that replays argv up to the current word to find the active completion scope. */
 function emitSimulate(ident: string): string {
   let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
   o += "  local i=1 sid=0 w steps next\n";
@@ -198,6 +211,7 @@ function emitSimulate(ident: string): string {
   return o;
 }
 
+/** Emits the main `COMPREPLY` driver and `complete -F` registration for bash. */
 function emitMainBodyBash(schema: CliCommand, ident: string): string {
   const main = mainName(schema.key);
   let o = "_${main}() {\n".replace("${main}", main);
@@ -231,6 +245,7 @@ function emitMainBodyBash(schema: CliCommand, ident: string): string {
   return o;
 }
 
+/** Returns a self-contained bash `complete` script for the given program schema. */
 export function completionBashScript(schema: CliCommand): string {
   const ident = identToken(schema.key);
   const scopes = collectScopes(schema);
@@ -246,7 +261,6 @@ export function completionBashScript(schema: CliCommand): string {
     out += "A_" + ident + "_" + i + "_opts=()\n";
     out += "A_" + ident + "_" + i + "_opts+=('" + kHelpLong + "' '" + kHelpShort + "')\n";
     for (const o of sc.opts) {
-      if (o.positional) continue;
       out += "A_" + ident + "_" + i + "_opts+=('--" + o.name + "')\n";
       if (o.shortName) {
         out += "A_" + ident + "_" + i + "_opts+=('-" + o.shortName + "')\n";
@@ -274,6 +288,7 @@ export function completionBashScript(schema: CliCommand): string {
 
 // ── Zsh Completion ─────────────────────────────────────────────────────────────
 
+/** Emits zsh `typeset` arrays of options and subcommands for each scope. */
 function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
   let out = "";
   for (const [i, sc] of scopes.entries()) {
@@ -305,6 +320,7 @@ function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
   return out;
 }
 
+/** Zsh: long-option classifier function source (mirrors bash consume_long). */
 function emitConsumeLongZsh(ident: string, scopes: ScopeRec[]): string {
   let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
   o += "  local sid=\"$1\" w=\"$2\" nw=\"$3\"\n";
@@ -314,7 +330,6 @@ function emitConsumeLongZsh(ident: string, scopes: ScopeRec[]): string {
     o += "      case $w in\n";
     o += "        " + kHelpLong + "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n".replace(/\$\{kHelpLong\}/g, kHelpLong).replace(/\$\{kHelpShort\}/g, kHelpShort);
     for (const op of sc.opts) {
-      if (op.positional) continue;
       const base = "--" + op.name;
       if (op.kind === "presence") {
         o += "        " + base + "|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base);
@@ -333,6 +348,7 @@ function emitConsumeLongZsh(ident: string, scopes: ScopeRec[]): string {
   return o;
 }
 
+/** Zsh: short-option classifier function source. */
 function emitConsumeShortZsh(ident: string, scopes: ScopeRec[]): string {
   let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
   o += "  local sid=\"$1\" w=\"$2\"\n";
@@ -348,7 +364,6 @@ function emitConsumeShortZsh(ident: string, scopes: ScopeRec[]): string {
     o += "        case $ch in\n";
     let boolChars = "";
     for (const op of sc.opts) {
-      if (op.positional) continue;
       if (!op.shortName) continue;
       if (op.kind === "presence") {
         boolChars += op.shortName + "|";
@@ -375,6 +390,7 @@ function emitConsumeShortZsh(ident: string, scopes: ScopeRec[]): string {
   return o;
 }
 
+/** Zsh: subcommand name → scope id matching helper. */
 function emitMatchChildZsh(ident: string, scopes: ScopeRec[], pathIndex: Record<string, number>): string {
   let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
   o += "  local sid=\"$1\" w=\"$2\"\n";
@@ -397,6 +413,7 @@ function emitMatchChildZsh(ident: string, scopes: ScopeRec[], pathIndex: Record<
   return o;
 }
 
+/** Zsh: simulates word traversal to the current completion context (sets `REPLY_SID`). */
 function emitSimulateZsh(ident: string): string {
   let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
   o += "  local i=2 sid=0 w steps next\n";
@@ -434,6 +451,7 @@ function emitSimulateZsh(ident: string): string {
   return o;
 }
 
+/** Zsh: `_main` completer and `compdef` registration. */
 function emitMainBodyZsh(schema: CliCommand, ident: string): string {
   const main = mainName(schema.key);
   let o = "_${main}() {\n".replace("${main}", main);
@@ -465,6 +483,7 @@ function emitMainBodyZsh(schema: CliCommand, ident: string): string {
   return o;
 }
 
+/** Returns a self-contained zsh completion script for the given program schema. */
 export function completionZshScript(schema: CliCommand): string {
   const ident = identToken(schema.key);
   const scopes = collectScopes(schema);
@@ -484,13 +503,13 @@ export function completionZshScript(schema: CliCommand): string {
 }
 
 /**
- * Builds the static `completion` / `bash` / `zsh` subtree used for shell integration.
+ * Builds the static `completion` / `bash` / `zsh` command subtree (merged into the program root at runtime).
  */
 export function cliBuiltinCompletionGroup(appName: string): CliCommand {
   return {
     key: "completion",
     description: "Generate the autocompletion script for shells.",
-    children: [
+    commands: [
       {
         key: "bash",
         description: "Print a bash tab-completion script.",

package/src/context.ts

@@ -20,6 +20,7 @@ export class CliContext {
   readonly schema: CliCommand;
   readonly opts: Record<string, string>;
 
+  /** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
     appName: string,
     commandPath: string[],
@@ -35,7 +36,7 @@ export class CliContext {
   }
 
   /** Returns whether a presence flag was set (including implicit "1" for boolean options). */
-  flag(name: string): boolean {
+  hasFlag(name: string): boolean {
     return this.opts[name] !== undefined;
   }
 

package/src/help.ts

@@ -7,32 +7,41 @@ It keeps help formatting shared across help and error paths so users see one con
 style no matter how help is reached.
 */
 
-import { CliCommand, CliOptionDef, CliOptionKind } from "./types.ts";
+import { CliCommand, CliOption, CliOptionKind, CliPositional } from "./types.ts";
 
 // ── ANSI Style Helpers ────────────────────────────────────────────────────────
 
+/** SGR wrappers for TTY help output. */
 const style = {
+  /** Joins a message with a prefix and a reset (or suffix) for ANSI SGR. */
   wrap(prefix: string, body: string, suffix: string): string {
     return prefix + body + suffix;
   },
+  /** Renders the message in red. */
   red(msg: string): string {
     return this.wrap("\u001B[31m", msg, "\u001B[0m");
   },
+  /** Renders the message in gray. */
   gray(msg: string): string {
     return this.wrap("\u001B[90m", msg, "\u001B[0m");
   },
+  /** Renders the message in bold. */
   bold(msg: string): string {
     return this.wrap("\u001B[1m", msg, "\u001B[0m");
   },
+  /** Renders the message in white. */
   white(msg: string): string {
     return this.wrap("\u001B[37m", msg, "\u001B[0m");
   },
+  /** Renders the message in bright aqua + bold. */
   aquaBold(msg: string): string {
     return this.wrap("\u001B[96m\u001B[1m", msg, "\u001B[0m");
   },
+  /** Renders the message in bright green. */
   greenBright(msg: string): string {
     return this.wrap("\u001B[92m", msg, "\u001B[0m");
   },
+  /** Renders a section title: gray and bold. */
   grayBoldTitle(title: string): string {
     return this.gray(this.bold(title));
   },
@@ -49,11 +58,13 @@ const kBoxH = "\u2500";  // ─
 
 // ── Terminal Detection ────────────────────────────────────────────────────────
 
+/** Returns a minimum column width for help, clamped to stdout width when known. */
 function getHelpWidth(): number {
   return Math.max(40, process.stdout.columns || 80);
 }
 
-function isTTY(fd: number): boolean {
+/** True when stdout is a TTY (used to decide on color). */
+function isTTY(): boolean {
   return process.stdout.isTTY !== undefined;
 }
 
@@ -78,20 +89,24 @@ function visibleWidth(s: string): number {
   return w;
 }
 
+/** Repeats the horizontal box-drawing character `n` times. */
 function repeatBoxH(n: number): string {
   return kBoxH.repeat(Math.max(0, n));
 }
 
+/** Returns a string of `n` spaces. */
 function spaces(n: number): string {
   return " ".repeat(Math.max(0, n));
 }
 
+/** Pads `s` to visible width (ANSI-aware) to `width` columns. */
 function padVisible(s: string, width: number): string {
   return s + spaces(Math.max(0, width - visibleWidth(s)));
 }
 
 // ── Text Wrapping ─────────────────────────────────────────────────────────────
 
+/** Word-wraps a single line of text to a maximum `width` in columns. */
 function wrapParagraph(text: string, width: number): string[] {
   const available = Math.max(1, width);
   const out: string[] = [];
@@ -113,6 +128,7 @@ function wrapParagraph(text: string, width: number): string[] {
   return out;
 }
 
+/** Splits on newlines and wraps each logical line, preserving intentional leading-indent lines. */
 function wrapText(text: string, width: number): string[] {
   const out: string[] = [];
   const lines = text.split("\n");
@@ -134,6 +150,7 @@ function wrapText(text: string, width: number): string[] {
 
 // ── Option Label Formatting ───────────────────────────────────────────────────
 
+/** Suffix for `--name` in usage (e.g. ` <string>`) based on value kind. */
 function optKindLabel(k: CliOptionKind): string {
   switch (k) {
     case CliOptionKind.Presence:
@@ -145,13 +162,8 @@ function optKindLabel(k: CliOptionKind): string {
   }
 }
 
-export function cliOptionLabel(o: CliOptionDef, color: boolean): string {
-  if (o.positional) {
-    if (o.argMax === 1) {
-      return o.argMin === 0 ? "[" + o.name + "]" : "<" + o.name + ">";
-    }
-    return o.argMin === 0 ? "[" + o.name + "...]" : "<" + o.name + "...>";
-  }
+/** Formats a flag/value option for help tables: `--name`, optional short, optional kind hint. */
+export function cliOptionLabel(o: CliOption, color: boolean): string {
   let r = "--" + o.name + optKindLabel(o.kind);
   if (o.shortName) r += ", -" + o.shortName;
   if (!color) return r;
@@ -163,13 +175,30 @@ export function cliOptionLabel(o: CliOptionDef, color: boolean): string {
   return style.aquaBold(left) + " " + style.greenBright(right);
 }
 
+/** Formats a positional slot label (`<n>`, `[n]`, or varargs) for help. */
+export function cliPositionalLabel(p: CliPositional, color: boolean): string {
+  const { argMin = 1, argMax = 1 } = p;
+  let r: string;
+  if (argMax === 1) {
+    r = argMin === 0 ? "[" + p.name + "]" : "<" + p.name + ">";
+  } else {
+    r = argMin === 0 ? "[" + p.name + "...]" : "<" + p.name + "...>";
+  }
+  if (!color) return r;
+  return style.aquaBold(r);
+}
+
 // ── Box Rendering ─────────────────────────────────────────────────────────────
 
+/** A single help table row: left column text and right-column description. */
 interface HelpRow {
+  /** Option flag or subcommand / positional label. */
   label: string;
+  /** Explanatory text (may be wrapped to multiple display lines). */
   description: string;
 }
 
+/** Renders a free-text or notes box with a Unicode border and `title` header. */
 function renderTextBox(title: string, lines: string[], hw: number, color: boolean): string[] {
   if (lines.length === 0) return [];
 
@@ -208,6 +237,7 @@ function renderTextBox(title: string, lines: string[], hw: number, color: boolea
   return out;
 }
 
+/** Renders a two-column label/description table in a box (options, subcommands, positionals). */
 function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boolean): string[] {
   if (rows.length === 0) return [];
 
@@ -273,6 +303,7 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
 
 // ── Usage & Rows ──────────────────────────────────────────────────────────────
 
+/** Builds one or two usage line strings (OPTIONS / COMMAND / ARGS) for the help header. */
 function usageLines(
   appName: string,
   helpPath: string[],
@@ -304,25 +335,25 @@ function usageLines(
   return out;
 }
 
-function rowsForOptions(defs: CliOptionDef[], color: boolean): HelpRow[] {
+/** Table rows for named options, including a synthetic `--help, -h` row. */
+function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
   const rows: HelpRow[] = [];
   const helpLabel = color
     ? style.aquaBold("--help, ") + style.greenBright("-h")
     : "--help, -h";
   rows.push({ label: helpLabel, description: "Show help for this command." });
   for (const o of defs) {
-    if (o.positional) continue;
     rows.push({ label: cliOptionLabel(o, color), description: o.description });
   }
   return rows;
 }
 
-function rowsForPositionals(defs: CliOptionDef[], color: boolean): HelpRow[] {
-  return defs
-    .filter((o) => o.positional)
-    .map((o) => ({ label: cliOptionLabel(o, color), description: o.description }));
+/** Table rows for positional `CliPositional` definitions. */
+function rowsForPositionals(defs: CliPositional[], color: boolean): HelpRow[] {
+  return defs.map((p) => ({ label: cliPositionalLabel(p, color), description: p.description }));
 }
 
+/** Table rows for subcommands, sorted by key. */
 function rowsForSubcommands(cmds: CliCommand[]): HelpRow[] {
   return cmds
     .sort((a, b) => a.key.localeCompare(b.key))
@@ -331,9 +362,13 @@ function rowsForSubcommands(cmds: CliCommand[]): HelpRow[] {
 
 // ── Main Help Render ──────────────────────────────────────────────────────────
 
+/**
+ * Renders full help for the app root or a nested command, following `helpPath` from the root key.
+ * `useStderr` is reserved for call-site consistency; width and color use stdout TTY.
+ */
 export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr: boolean): string {
   const hw = getHelpWidth();
-  const color = isTTY(1);
+  const color = isTTY();
 
   if (helpPath.length === 0) {
     const lines: string[] = [];
@@ -345,7 +380,7 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
     lines.push(
       renderTextBox(
         "Usage",
-        usageLines(schema.key, helpPath, (schema.children ?? []).length > 0, false, color),
+        usageLines(schema.key, helpPath, (schema.commands ?? []).length > 0, false, color),
         hw,
         color,
       ).join("\n"),
@@ -356,16 +391,16 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
       lines.push("");
       lines.push(optBox.join("\n"));
     }
-    if ((schema.children ?? []).length > 0) {
+    if ((schema.commands ?? []).length > 0) {
       lines.push("");
       lines.push(
-        renderTableBox("Commands", rowsForSubcommands(schema.children ?? []), hw, color).join("\n"),
+        renderTableBox("Commands", rowsForSubcommands(schema.commands ?? []), hw, color).join("\n"),
       );
     }
     return lines.join("\n") + "\n\n";
   }
 
-  let layer = schema.children ?? [];
+  let layer = schema.commands ?? [];
   let node: CliCommand | undefined;
   for (const seg of helpPath) {
     const ch = layer.find((c) => c.key === seg);
@@ -373,7 +408,7 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
       return (color ? style.red("Unknown help path.") : "Unknown help path.") + "\n";
     }
     node = ch;
-    layer = ch.children ?? [];
+    layer = ch.commands ?? [];
   }
   if (!node) {
     return (color ? style.red("Unknown help path.") : "Unknown help path.") + "\n";
@@ -388,7 +423,7 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
   lines.push(
     renderTextBox(
       "Usage",
-      usageLines(schema.key, helpPath, (node.children ?? []).length > 0, (node.positionals ?? []).length > 0, color),
+      usageLines(schema.key, helpPath, (node.commands ?? []).length > 0, (node.positionals ?? []).length > 0, color),
       hw,
       color,
     ).join("\n"),
@@ -406,7 +441,7 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
     lines.push(posBox.join("\n"));
   }
 
-  const subBox = renderTableBox("Subcommands", rowsForSubcommands(node.children ?? []), hw, color);
+  const subBox = renderTableBox("Subcommands", rowsForSubcommands(node.commands ?? []), hw, color);
   if (subBox.length > 0) {
     lines.push("");
     lines.push(subBox.join("\n"));