harnery 0.0.1 → 0.2.0

package/src/lib/completion/bash.ts

@@ -0,0 +1,291 @@
+/**
+ * Bash completion generator. Walks a CommandSpec tree and emits a single
+ * self-contained bash function `_<bin>` plus the `complete -F _<bin> <bin>`
+ * directive that registers it. The bin name is injected by the caller so the
+ * same generator serves any host CLI.
+ *
+ * Generated script architecture:
+ *   1. `_<bin>_path()`: walks COMP_WORDS forward, skipping options and option
+ *      values, returns the current command-path string (e.g., "anthropic cost").
+ *   2. `_<bin>_options()` / `_<bin>_subcommands()` / `_<bin>_option_takes_value()` /
+ *      `_<bin>_option_choices()`: table-lookup functions, generated as big
+ *      case statements from the spec tree.
+ *   3. `_<bin>()`: main entry. Sets COMPREPLY based on whether the cursor is
+ *      on a subcommand name, option name (--<TAB>), or value.
+ *   4. Dynamic value paths shell out to `<bin> __complete <provider> -- "$cur"`.
+ *
+ * Important escaping rules:
+ *   - Single-quoted strings in bash don't honor escapes. We replace `'` in
+ *     descriptions/choices with `'\''` (the standard bash single-quote escape).
+ *   - We avoid descriptions in bash output because bash COMPREPLY can't render
+ *     them; descriptions are a zsh/fish feature.
+ */
+
+import type { CommandSpec, OptionSpec, PositionalSpec } from "./walk.js";
+
+/**
+ * Derive a valid shell function-name prefix from the bin name (e.g. `my-cli`
+ * → `_my_cli`). Non-identifier characters collapse to `_`.
+ */
+function fnPrefix(binName: string): string {
+  return `_${binName.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+}
+
+/**
+ * Encode a positional/option value source as a single string the bash driver
+ * can parse: `DYN:<provider>` for dynamic, `ENUM:val1 val2 val3` for static
+ * choices, or empty when there's nothing to suggest.
+ */
+function valueSpec(opt: { dynamicProvider?: string; valueChoices?: string[] }): string {
+  if (opt.dynamicProvider) return `DYN:${opt.dynamicProvider}`;
+  if (opt.valueChoices && opt.valueChoices.length > 0) {
+    return `ENUM:${opt.valueChoices.join(" ")}`;
+  }
+  return "";
+}
+
+export function generateBash(root: CommandSpec, binName: string): string {
+  const fn = fnPrefix(binName);
+  // Build lookup tables keyed by command path. Path "" represents the root.
+  const subcommandsByPath = new Map<string, string[]>();
+  const optionsByPath = new Map<string, OptionSpec[]>();
+  const positionalsByPath = new Map<string, PositionalSpec[]>();
+
+  const walk = (s: CommandSpec): void => {
+    subcommandsByPath.set(s.path, s.subcommands.map((c) => c.name).sort());
+    optionsByPath.set(s.path, s.options);
+    positionalsByPath.set(s.path, s.positionals);
+    for (const sub of s.subcommands) walk(sub);
+  };
+  walk(root);
+
+  const out: string[] = [];
+  out.push(
+    `# ${binName} bash completion, generated by \`${binName} completion bash\`. Do not edit.`,
+  );
+  out.push(`# Source via:  eval "$(${binName} completion bash)"`);
+  out.push("");
+  out.push(`${fn}_subcommands() {`);
+  out.push(`  case "$1" in`);
+  for (const [path, names] of [...subcommandsByPath.entries()].sort()) {
+    if (names.length === 0) continue;
+    out.push(`    ${bashCase(path)}) echo '${names.join(" ")}' ;;`);
+  }
+  out.push("  esac");
+  out.push("}");
+  out.push("");
+  out.push(`${fn}_options() {`);
+  out.push(`  case "$1" in`);
+  for (const [path, opts] of [...optionsByPath.entries()].sort()) {
+    if (opts.length === 0) continue;
+    const flags = opts.flatMap((o) => [o.long, o.short]).filter((f) => f.length > 0);
+    out.push(`    ${bashCase(path)}) echo '${flags.join(" ")}' ;;`);
+  }
+  out.push("  esac");
+  out.push("}");
+  out.push("");
+  out.push(`${fn}_option_takes_value() {`);
+  out.push(
+    `  # echo "1" if option takes a value, empty otherwise. $1 = command path, $2 = option flag.`,
+  );
+  out.push(`  case "$1|$2" in`);
+  for (const [path, opts] of [...optionsByPath.entries()].sort()) {
+    for (const o of opts) {
+      if (!o.takesValue) continue;
+      for (const flag of [o.long, o.short].filter((f) => f.length > 0)) {
+        out.push(`    ${bashCase(path)}\\|${bashEscape(flag)}) echo 1 ;;`);
+      }
+    }
+  }
+  out.push("  esac");
+  out.push("}");
+  out.push("");
+  out.push(`${fn}_option_completion() {`);
+  out.push(`  # Echo "DYN:<provider>" or "ENUM:val1 val2 ...". Empty if no spec.`);
+  out.push(`  case "$1|$2" in`);
+  for (const [path, opts] of [...optionsByPath.entries()].sort()) {
+    for (const o of opts) {
+      if (!o.takesValue) continue;
+      const spec = valueSpec(o);
+      if (!spec) continue;
+      for (const flag of [o.long, o.short].filter((f) => f.length > 0)) {
+        out.push(`    ${bashCase(path)}\\|${bashEscape(flag)}) echo '${bashEscape(spec)}' ;;`);
+      }
+    }
+  }
+  out.push("  esac");
+  out.push("}");
+  out.push("");
+  out.push(`${fn}_positional_completion() {`);
+  out.push(
+    `  # Echo "DYN:<provider>" or "ENUM:val1 val2 ...". $1 = command path, $2 = positional index.`,
+  );
+  out.push(`  case "$1|$2" in`);
+  for (const [path, positionals] of [...positionalsByPath.entries()].sort()) {
+    positionals.forEach((p, i) => {
+      const spec = valueSpec(p);
+      if (!spec) return;
+      out.push(`    ${bashCase(path)}\\|${i}) echo '${bashEscape(spec)}' ;;`);
+    });
+  }
+  out.push("  esac");
+  out.push("}");
+  out.push("");
+  out.push(bashDriver(fn, binName));
+  out.push("");
+  out.push(`complete -F ${fn} ${binName}`);
+  return `${out.join("\n")}\n`;
+}
+
+/**
+ * Converts a command path to a bash `case` pattern. Empty path → "ROOT".
+ * Replace spaces with `__` since bash case patterns don't tolerate spaces well
+ * inside an unquoted pattern. The driver substitutes the same way.
+ */
+function bashCase(path: string): string {
+  if (path === "") return "ROOT";
+  return path.replace(/ /g, "__");
+}
+
+/**
+ * Escape a string for safe embedding in a single-quoted bash string. Inside
+ * single quotes the only character that needs escaping is the single quote
+ * itself, which we close, escape, and reopen: `'\''`.
+ */
+function bashEscape(s: string): string {
+  return s.replace(/'/g, `'\\''`);
+}
+
+/**
+ * The driver: the parts of the completion that don't depend on the command
+ * tree. Walks COMP_WORDS to determine the current command path, then dispatches
+ * to subcommand / option / value completion. `fn` is the function-name prefix
+ * and `binName` is the CLI name used for the `__complete` callback.
+ */
+function bashDriver(fn: string, binName: string): string {
+  return `${fn}() {
+  local cur prev words cword
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Walk forward through words, skipping options and option-values, to
+  # determine which command path we're currently inside. Stop when we hit
+  # COMP_CWORD (the position the cursor is on).
+  local -a path_parts=()
+  local i=1
+  local path_str="ROOT"
+  while [ $i -lt $COMP_CWORD ]; do
+    local w="\${COMP_WORDS[$i]}"
+    case "$w" in
+      -*)
+        # Option. If it takes a value, skip the next word too.
+        if [ "$(${fn}_option_takes_value "$path_str" "$w")" = "1" ]; then
+          i=$((i+1))
+        fi
+        ;;
+      *)
+        path_parts+=("$w")
+        local joined
+        joined=$(printf '%s__' "\${path_parts[@]}")
+        joined="\${joined%__}"
+        # If this word is a known subcommand at our current path, descend.
+        local known
+        known=$(${fn}_subcommands "$path_str")
+        if [[ " $known " == *" $w "* ]]; then
+          path_str="$joined"
+        fi
+        ;;
+    esac
+    i=$((i+1))
+  done
+
+  # --- decide what we're completing ----------------------------------------
+
+  # Case 1: previous word is an option that takes a value → complete that value.
+  if [ -n "$prev" ] && [ "$(${fn}_option_takes_value "$path_str" "$prev")" = "1" ]; then
+    local spec
+    spec=$(${fn}_option_completion "$path_str" "$prev")
+    ${fn}_emit_values "$spec" "$cur"
+    return
+  fi
+
+  # Case 2: current word starts with - → complete option name.
+  if [[ "$cur" == -* ]]; then
+    local opts
+    opts=$(${fn}_options "$path_str")
+    if [ -n "$opts" ]; then
+      COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+    fi
+    return
+  fi
+
+  # Case 3: complete subcommand name (and any positional values for this command).
+  local subs
+  subs=$(${fn}_subcommands "$path_str")
+
+  # How many positional args have we accumulated for the current path? Count
+  # path_parts entries beyond the part that matched a subcommand.
+  local pos_index=0
+  if [ -n "$subs" ]; then
+    # If subs are still available here, the cursor is on a subcommand slot.
+    COMPREPLY=( $(compgen -W "$subs" -- "$cur") )
+    return
+  fi
+
+  # No more subcommands, we're on a positional. Determine which positional
+  # index we're on by counting non-option words after the last matched subcommand.
+  local after_cmd=0
+  local j=1
+  local seen_path="ROOT"
+  while [ $j -lt $COMP_CWORD ]; do
+    local w="\${COMP_WORDS[$j]}"
+    case "$w" in
+      -*)
+        if [ "$(${fn}_option_takes_value "$seen_path" "$w")" = "1" ]; then
+          j=$((j+1))
+        fi
+        ;;
+      *)
+        local joined
+        if [ "$seen_path" = "ROOT" ]; then joined="$w"; else joined="\${seen_path}__\${w}"; fi
+        local known
+        known=$(${fn}_subcommands "$seen_path")
+        if [[ " $known " == *" $w "* ]]; then
+          seen_path="$joined"
+        else
+          after_cmd=$((after_cmd+1))
+        fi
+        ;;
+    esac
+    j=$((j+1))
+  done
+  pos_index=$after_cmd
+
+  local pos_spec
+  pos_spec=$(${fn}_positional_completion "$path_str" "$pos_index")
+  if [ -n "$pos_spec" ]; then
+    ${fn}_emit_values "$pos_spec" "$cur"
+    return
+  fi
+
+  # Fallback: file completion.
+  COMPREPLY=( $(compgen -f -- "$cur") )
+}
+
+${fn}_emit_values() {
+  local spec="$1"
+  local cur="$2"
+  if [[ "$spec" == DYN:* ]]; then
+    local provider="\${spec#DYN:}"
+    local values
+    values=$(${binName} __complete "$provider" -- "$cur" 2>/dev/null)
+    if [ -n "$values" ]; then
+      COMPREPLY=( $(compgen -W "$values" -- "$cur") )
+    fi
+  elif [[ "$spec" == ENUM:* ]]; then
+    local choices="\${spec#ENUM:}"
+    COMPREPLY=( $(compgen -W "$choices" -- "$cur") )
+  fi
+}`;
+}

package/src/lib/completion/fish.ts

@@ -0,0 +1,134 @@
+/**
+ * Fish completion generator. Fish has the cleanest completion grammar of the
+ * three shells: one `complete` line per option per command. No driver function
+ * needed; fish's built-in `__fish_seen_subcommand_from` and friends do the
+ * subcommand parsing for us. The bin name is injected by the caller.
+ *
+ * Layout per command path:
+ *   complete -c <bin> -n '<condition>' -a <subcommand> -d '<description>'
+ *   complete -c <bin> -n '<condition>' -l <long> [-s <short>] -d '<description>' [-r] [-x] [-a '<choices>']
+ *
+ * Dynamic values: fish runs the command in `-a '(...)'` at completion time,
+ * giving us per-tab callbacks for free.
+ */
+
+import type { CommandSpec } from "./walk.js";
+
+function fishEscape(s: string): string {
+  // Inside single-quoted fish strings, escape \\ and '.
+  return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+
+function truncate(s: string, n: number): string {
+  if (!s) return "";
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+/**
+ * Returns the fish condition expression for "we are inside the command path".
+ * Path "" (root) means "no subcommand seen yet".
+ */
+function pathCondition(path: string): string {
+  if (path === "") {
+    return "__fish_use_subcommand";
+  }
+  const parts = path.split(" ");
+  // Build: __fish_seen_subcommand_from a; and __fish_seen_subcommand_from b; ...
+  // Fish's __fish_seen_subcommand_from accepts a list of allowed words at a
+  // given depth. For a 2-deep path "anthropic cost", the condition is:
+  //   __fish_seen_subcommand_from anthropic; and __fish_seen_subcommand_from cost
+  const clauses = parts.map((p) => `__fish_seen_subcommand_from ${p}`);
+  return clauses.join("; and ");
+}
+
+function valueAction(
+  opt: { dynamicProvider?: string; valueChoices?: string[] },
+  binName: string,
+): {
+  flag: string;
+  arg: string;
+} {
+  // Fish flag semantics:
+  //   -r/--require-parameter   : the flag requires an argument
+  //   -x/--exclusive           : flag requires an argument AND no further completion after
+  //   -a '<arg>'               : completions for the argument
+  if (opt.dynamicProvider) {
+    return {
+      flag: "-r",
+      arg: `-a '(${binName} __complete ${opt.dynamicProvider} -- (commandline -ct))'`,
+    };
+  }
+  if (opt.valueChoices && opt.valueChoices.length > 0) {
+    return {
+      flag: "-r",
+      arg: `-a '${opt.valueChoices.map(fishEscape).join(" ")}'`,
+    };
+  }
+  return { flag: "-r", arg: "" };
+}
+
+export function generateFish(root: CommandSpec, binName: string): string {
+  const out: string[] = [];
+  out.push(
+    `# ${binName} fish completion, generated by \`${binName} completion fish\`. Do not edit.`,
+  );
+  out.push(`# Source via:  ${binName} completion fish | source`);
+  out.push(
+    `# Or install:  ${binName} completion fish > ~/.config/fish/completions/${binName}.fish`,
+  );
+  out.push("");
+
+  const walk = (s: CommandSpec): void => {
+    const cond = pathCondition(s.path);
+    // Subcommands at this depth
+    for (const sub of s.subcommands) {
+      const desc = truncate(sub.description, 80);
+      out.push(
+        `complete -c ${binName} -f -n '${cond}' -a '${fishEscape(sub.name)}' -d '${fishEscape(desc)}'`,
+      );
+    }
+    // Options for this command
+    for (const o of s.options) {
+      const long = o.long ? o.long.replace(/^--/, "") : "";
+      const short = o.short ? o.short.replace(/^-/, "") : "";
+      const desc = truncate(o.description, 80);
+      let line = `complete -c ${binName} -n '${cond}'`;
+      if (long) line += ` -l ${long}`;
+      if (short) line += ` -s ${short}`;
+      if (o.takesValue) {
+        const v = valueAction(o, binName);
+        line += ` ${v.flag}`;
+        if (v.arg) line += ` ${v.arg}`;
+        else line += " -f";
+      } else {
+        line += " -f";
+      }
+      line += ` -d '${fishEscape(desc)}'`;
+      out.push(line);
+    }
+    // Positional values: fish doesn't natively handle Nth positional, but we
+    // can suggest values when no subcommand follows. The condition becomes:
+    // "in this path AND not seen another subcommand from this path's subs".
+    if (s.positionals.length > 0) {
+      const subNames = s.subcommands.map((c) => c.name).join(" ");
+      const positionalCond =
+        s.subcommands.length > 0
+          ? `${cond}; and not __fish_seen_subcommand_from ${subNames}`
+          : cond;
+      // We only render the first positional; fish has limited support for
+      // distinguishing positional indices in this completion grammar.
+      const p = s.positionals[0];
+      if (p) {
+        const v = valueAction(p, binName);
+        if (v.arg) {
+          out.push(`complete -c ${binName} -f -n '${positionalCond}' ${v.arg}`);
+        }
+      }
+    }
+
+    for (const sub of s.subcommands) walk(sub);
+  };
+  walk(root);
+
+  return `${out.join("\n")}\n`;
+}

package/src/lib/completion/index.ts

@@ -0,0 +1,10 @@
+export { generateBash } from "./bash.js";
+export { generateFish } from "./fish.js";
+export {
+  type CommandSpec,
+  type CompletionContextLookup,
+  type OptionSpec,
+  type PositionalSpec,
+  walkProgram,
+} from "./walk.js";
+export { generateZsh } from "./zsh.js";

package/src/lib/completion/walk.ts

@@ -0,0 +1,184 @@
+/**
+ * Walks the Commander program tree and produces a normalized CommandSpec tree
+ * that the bash/zsh/fish completion generators consume. Decoupled from
+ * Commander internals so the generators don't have to know about Option/Argument
+ * classes, just the spec types defined here.
+ */
+
+import type { Argument, Command, Option } from "commander";
+
+/**
+ * Caller-injected lookup that maps a (commandPath, option-or-positional)
+ * pair to a dynamic-provider key. The shell completion script later
+ * invokes `<bin> __complete <key>` at tab-time and the consumer's
+ * provider registry produces the actual values. harn standalone uses
+ * the default no-op lookup (no dynamic completion).
+ */
+export type CompletionContextLookup = (key: {
+  commandPath: string;
+  option?: string;
+  positional?: number;
+}) => string | undefined;
+
+const noopLookup: CompletionContextLookup = () => undefined;
+
+export interface CommandSpec {
+  /** Bare command name (e.g., "anthropic", "cost"). */
+  name: string;
+  /** Full path from root, space-separated (e.g., "anthropic cost"). Empty for the root program. */
+  path: string;
+  description: string;
+  subcommands: CommandSpec[];
+  options: OptionSpec[];
+  positionals: PositionalSpec[];
+  /** True if this command has the `--help` flag (default for all Commander commands). */
+  hasHelp: boolean;
+  /** True if this is a hidden command; completion can skip it. */
+  hidden: boolean;
+}
+
+export interface OptionSpec {
+  /** Long form including `--`, e.g., "--workspace". May be empty if only short form exists. */
+  long: string;
+  /** Short form including `-`, e.g., "-w". May be empty. */
+  short: string;
+  description: string;
+  /** True if the option requires a value (e.g., `--workspace <id>`). */
+  takesValue: boolean;
+  /** Optional static choice list for the value (e.g. `--format json|csv|table`). */
+  valueChoices?: string[];
+  /** Optional dynamic-value provider key; completion script calls back via `harn __complete <key>`. */
+  dynamicProvider?: string;
+  /** True if the option can be repeated. */
+  variadic: boolean;
+}
+
+export interface PositionalSpec {
+  name: string;
+  description: string;
+  required: boolean;
+  variadic: boolean;
+  valueChoices?: string[];
+  dynamicProvider?: string;
+}
+
+/**
+ * Walks the Commander program tree and returns the root CommandSpec.
+ * The root represents `harn` itself; its `subcommands` are the top-level
+ * subcommands.
+ */
+export function walkProgram(
+  program: Command,
+  lookup: CompletionContextLookup = noopLookup,
+): CommandSpec {
+  return walkCommand(program, "", true, lookup);
+}
+
+function walkCommand(
+  cmd: Command,
+  parentPath: string,
+  isRoot: boolean,
+  lookup: CompletionContextLookup,
+): CommandSpec {
+  const name = cmd.name();
+  // The root program represents `harn` itself; its path stays empty so that
+  // top-level subcommands have paths like "anthropic", not "harn anthropic".
+  // The shell driver walks COMP_WORDS[1..], so it's already operating in
+  // post-`harn` space and shouldn't see "bp" in its lookup keys.
+  const path = isRoot ? "" : parentPath ? `${parentPath} ${name}` : name;
+
+  const subcommands: CommandSpec[] = cmd.commands
+    .filter((c) => !isHidden(c))
+    // Skip the auto-injected `help` subcommand; noisy without being useful.
+    .filter((c) => c.name() !== "help")
+    .map((c) => walkCommand(c, path, false, lookup));
+
+  // Sort subcommands alphabetically for predictable output.
+  subcommands.sort((a, b) => a.name.localeCompare(b.name));
+
+  const options: OptionSpec[] = cmd.options
+    .filter((o) => !o.hidden)
+    .map((o) => optionSpec(o, path, lookup));
+
+  // Commander auto-injects `-h, --help` for every command but doesn't expose
+  // it in `cmd.options`. Add a synthetic entry so tab-completion suggests it.
+  options.push({
+    long: "--help",
+    short: "-h",
+    description: "Show help for this command",
+    takesValue: false,
+    variadic: false,
+  });
+
+  const positionals: PositionalSpec[] = cmd.registeredArguments.map((a, i) =>
+    positionalSpec(a, path, i, lookup),
+  );
+
+  return {
+    name,
+    path,
+    description: (cmd.description() || "").replace(/\s+/g, " ").trim(),
+    subcommands,
+    options,
+    positionals,
+    hasHelp: true,
+    hidden: isHidden(cmd),
+  };
+}
+
+function optionSpec(opt: Option, commandPath: string, lookup: CompletionContextLookup): OptionSpec {
+  const long = opt.long ?? "";
+  const short = opt.short ?? "";
+  const takesValue = opt.required || opt.optional;
+  const provider = lookup({
+    commandPath,
+    option: long || short,
+  });
+  return {
+    long,
+    short,
+    description: (opt.description || "").replace(/\s+/g, " ").trim(),
+    takesValue,
+    valueChoices: opt.argChoices ? [...opt.argChoices] : undefined,
+    dynamicProvider: provider,
+    variadic: opt.variadic,
+  };
+}
+
+function positionalSpec(
+  arg: Argument,
+  commandPath: string,
+  index: number,
+  lookup: CompletionContextLookup,
+): PositionalSpec {
+  const provider = lookup({
+    commandPath,
+    positional: index,
+  });
+  return {
+    name: arg.name(),
+    description: (arg.description || "").replace(/\s+/g, " ").trim(),
+    required: arg.required,
+    variadic: arg.variadic,
+    valueChoices: arg.argChoices ? [...arg.argChoices] : undefined,
+    dynamicProvider: provider,
+  };
+}
+
+function isHidden(cmd: Command): boolean {
+  // Commander marks hidden commands via `command(..., { hidden: true })`.
+  // The flag lives on a private field; we read it defensively via `any`.
+  const c = cmd as unknown as { _hidden?: boolean };
+  return c._hidden === true;
+}
+
+/** Flatten the spec tree into a list of (path, spec) entries for code generation. */
+export function flatten(root: CommandSpec): Array<{ path: string; spec: CommandSpec }> {
+  const out: Array<{ path: string; spec: CommandSpec }> = [];
+  const walk = (s: CommandSpec): void => {
+    out.push({ path: s.path, spec: s });
+    for (const sub of s.subcommands) walk(sub);
+  };
+  walk(root);
+  return out;
+}