harnery 0.3.2 → 0.5.0

package/dist/lib/completion/bash.d.ts

@@ -22,4 +22,19 @@
  */
 import type { CommandSpec } from "./walk.js";
 export declare function generateBash(root: CommandSpec, binName: string): string;
+/**
+ * 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.
+ */
+/**
+ * DYNAMIC bash completion: a thin, tree-independent shim. Instead of baking the
+ * command tree into case-tables (which go stale on any command/flag change),
+ * it hands the live command line to `<bin> __complete-line` on every <Tab> and
+ * lets the binary — which always knows its own current tree — answer. Install
+ * once; never regenerate. The trailing `\x1f:<n>` line carries the directive
+ * bitmask (bit 0 = fall back to file completion).
+ */
+export declare function generateBashDynamic(binName: string): string;
 //# sourceMappingURL=bash.d.ts.map

package/dist/lib/completion/bash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/bash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAuBzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2FvE"}
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/bash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAuBzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2FvE;AAqBD;;;;;GAKG;AACH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA0B3D"}

package/dist/lib/completion/bash.js

@@ -155,6 +155,41 @@ function bashEscape(s) {
  * to subcommand / option / value completion. `fn` is the function-name prefix
  * and `binName` is the CLI name used for the `__complete` callback.
  */
+/**
+ * DYNAMIC bash completion: a thin, tree-independent shim. Instead of baking the
+ * command tree into case-tables (which go stale on any command/flag change),
+ * it hands the live command line to `<bin> __complete-line` on every <Tab> and
+ * lets the binary — which always knows its own current tree — answer. Install
+ * once; never regenerate. The trailing `\x1f:<n>` line carries the directive
+ * bitmask (bit 0 = fall back to file completion).
+ */
+export function generateBashDynamic(binName) {
+    const fn = fnPrefix(binName);
+    return `# ${binName} bash completion (dynamic; install once, never stale). Do not edit.
+# Source via:  eval "$(${binName} completion bash --dynamic)"
+${fn}() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local raw line directive=0
+  local -a cands=()
+  raw="$(${binName} __complete-line "$COMP_CWORD" -- "\${COMP_WORDS[@]}" 2>/dev/null)" || return
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    if [ "\${line:0:2}" = $'\\x1f:' ]; then
+      directive="\${line:2}"
+    else
+      cands+=( "\${line%%$'\\t'*}" )
+    fi
+  done <<< "$raw"
+  if (( directive & 1 )); then
+    COMPREPLY=( $(compgen -f -- "$cur") )
+    return
+  fi
+  local IFS=$'\\n'
+  COMPREPLY=( $(compgen -W "\${cands[*]}" -- "$cur") )
+}
+complete -F ${fn} ${binName}
+`;
+}
 function bashDriver(fn, binName) {
     return `${fn}() {
   local cur prev words cword

package/dist/lib/completion/fish.d.ts

@@ -12,5 +12,15 @@
  * giving us per-tab callbacks for free.
  */
 import type { CommandSpec } from "./walk.js";
+/**
+ * DYNAMIC fish completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Fish renders `value\tdescription` lines natively, so the
+ * helper just strips the trailing `\x1f:<n>` directive line. Note: fish's
+ * declarative `complete -a` cannot switch to file completion from inside the
+ * helper, so the File directive is a no-op here — use static fish completion
+ * (`completion fish`) if you need file fallback on a path-valued positional.
+ */
+export declare function generateFishDynamic(binName: string): string;
 export declare function generateFish(root: CommandSpec, binName: string): string;
 //# sourceMappingURL=fish.d.ts.map

package/dist/lib/completion/fish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fish.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/fish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAuD7C,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgEvE"}
+{"version":3,"file":"fish.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/fish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAuD7C;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW3D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgEvE"}

package/dist/lib/completion/fish.js

@@ -55,6 +55,27 @@ function valueAction(opt, binName) {
     }
     return { flag: "-r", arg: "" };
 }
+/**
+ * DYNAMIC fish completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Fish renders `value\tdescription` lines natively, so the
+ * helper just strips the trailing `\x1f:<n>` directive line. Note: fish's
+ * declarative `complete -a` cannot switch to file completion from inside the
+ * helper, so the File directive is a no-op here — use static fish completion
+ * (`completion fish`) if you need file fallback on a path-valued positional.
+ */
+export function generateFishDynamic(binName) {
+    const fn = `__${binName.replace(/[^a-zA-Z0-9_]/g, "_")}_complete`;
+    return `# ${binName} fish completion (dynamic; install once, never stale). Do not edit.
+# Source via:  ${binName} completion fish --dynamic | source
+function ${fn}
+  set -l toks (commandline -opc)
+  set -l cur (commandline -ct)
+  ${binName} __complete-line (count $toks) -- $toks $cur 2>/dev/null | string match -rv '^\\x1f:'
+end
+complete -c ${binName} -f -a '(${fn})'
+`;
+}
 export function generateFish(root, binName) {
     const out = [];
     out.push(`# ${binName} fish completion, generated by \`${binName} completion fish\`. Do not edit.`);

package/dist/lib/completion/index.d.ts

@@ -1,5 +1,6 @@
-export { generateBash } from "./bash.js";
-export { generateFish } from "./fish.js";
+export { generateBash, generateBashDynamic } from "./bash.js";
+export { generateFish, generateFishDynamic } from "./fish.js";
+export { type Candidate, type CompletionProviderRunner, type CompletionResult, DIRECTIVE_PREFIX, Directive, encodeResult, resolveCompletions, } from "./resolve.js";
 export { type CommandSpec, type CompletionContextLookup, type OptionSpec, type PositionalSpec, walkProgram, } from "./walk.js";
-export { generateZsh } from "./zsh.js";
+export { generateZsh, generateZshDynamic } from "./zsh.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/completion/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EACL,KAAK,SAAS,EACd,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/completion/index.js

@@ -1,4 +1,5 @@
-export { generateBash } from "./bash.js";
-export { generateFish } from "./fish.js";
+export { generateBash, generateBashDynamic } from "./bash.js";
+export { generateFish, generateFishDynamic } from "./fish.js";
+export { DIRECTIVE_PREFIX, Directive, encodeResult, resolveCompletions, } from "./resolve.js";
 export { walkProgram, } from "./walk.js";
-export { generateZsh } from "./zsh.js";
+export { generateZsh, generateZshDynamic } from "./zsh.js";

package/dist/lib/completion/resolve.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime completion resolver — the authoritative, in-process answer to
+ * "what should I suggest at this cursor position?".
+ *
+ * The static bash/zsh/fish generators bake the whole command tree into shell
+ * case-tables, which go stale the moment a command/flag is added (the script
+ * must be regenerated + reinstalled). The DYNAMIC completion path instead
+ * installs a thin, tree-independent shim that, on every <Tab>, hands the live
+ * command line back to the binary and calls THIS function. Because the binary
+ * always knows its own current command tree, a dynamic shim never goes stale —
+ * install once, ever.
+ *
+ * This mirrors the path-walking the static bash driver does, but in one place
+ * and in TypeScript, so all three shells share identical behavior. It is
+ * deliberately decoupled from Commander internals via the CommandSpec tree
+ * (walkProgram), exactly like the static generators.
+ */
+import type { Command } from "commander";
+import { type CompletionContextLookup } from "./walk.js";
+/** Bitmask of post-processing hints for the shell shim (Cobra-style). */
+export declare const Directive: {
+    /** Use the returned candidates as completion values. */
+    readonly Default: 0;
+    /** No candidates apply here — the shell should fall back to file completion. */
+    readonly File: 1;
+};
+export interface Candidate {
+    value: string;
+    description?: string;
+}
+export interface CompletionResult {
+    candidates: Candidate[];
+    directive: number;
+}
+/** Provider runner injected by the host CLI (same contract as `__complete`). */
+export type CompletionProviderRunner = (provider: string, partial: string) => Promise<string[]>;
+/**
+ * Compute completion candidates for `words` with the cursor at `cword`.
+ * `words[0]` is the bin name; `words[cword]` is the (possibly empty) token
+ * being completed. The shell shim does the final prefix-filtering against that
+ * token, so this returns the full candidate set for the slot.
+ */
+export declare function resolveCompletions(program: Command, words: string[], cword: number, lookup: CompletionContextLookup, runProvider: CompletionProviderRunner): Promise<CompletionResult>;
+/** Sentinel prefix for the trailing directive line in the wire protocol. */
+export declare const DIRECTIVE_PREFIX = "\u001F:";
+/**
+ * Serialize a result for the shell shim: one `value\tdescription` line per
+ * candidate, then a final `\x1f:<directive>` line. The \x1f (unit separator)
+ * prefix makes the directive line unambiguous against real candidate values.
+ */
+export declare function encodeResult(result: CompletionResult): string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/lib/completion/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAoB,KAAK,uBAAuB,EAAe,MAAM,WAAW,CAAC;AAExF,yEAAyE;AACzE,eAAO,MAAM,SAAS;IACpB,wDAAwD;;IAExD,gFAAgF;;CAExE,CAAC;AAEX,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,MAAM,wBAAwB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAiGhG;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,uBAAuB,EAC/B,WAAW,EAAE,wBAAwB,GACpC,OAAO,CAAC,gBAAgB,CAAC,CA4C3B;AAED,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,YAAU,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAM7D"}

package/dist/lib/completion/resolve.js

@@ -0,0 +1,171 @@
+/**
+ * Runtime completion resolver — the authoritative, in-process answer to
+ * "what should I suggest at this cursor position?".
+ *
+ * The static bash/zsh/fish generators bake the whole command tree into shell
+ * case-tables, which go stale the moment a command/flag is added (the script
+ * must be regenerated + reinstalled). The DYNAMIC completion path instead
+ * installs a thin, tree-independent shim that, on every <Tab>, hands the live
+ * command line back to the binary and calls THIS function. Because the binary
+ * always knows its own current command tree, a dynamic shim never goes stale —
+ * install once, ever.
+ *
+ * This mirrors the path-walking the static bash driver does, but in one place
+ * and in TypeScript, so all three shells share identical behavior. It is
+ * deliberately decoupled from Commander internals via the CommandSpec tree
+ * (walkProgram), exactly like the static generators.
+ */
+import { walkProgram } from "./walk.js";
+/** Bitmask of post-processing hints for the shell shim (Cobra-style). */
+export const Directive = {
+    /** Use the returned candidates as completion values. */
+    Default: 0,
+    /** No candidates apply here — the shell should fall back to file completion. */
+    File: 1,
+};
+function buildTables(root) {
+    const subcommandsByPath = new Map();
+    const optionsByPath = new Map();
+    const positionalsByPath = new Map();
+    const walk = (s) => {
+        subcommandsByPath.set(s.path, s.subcommands);
+        optionsByPath.set(s.path, s.options);
+        positionalsByPath.set(s.path, s.positionals);
+        for (const sub of s.subcommands)
+            walk(sub);
+    };
+    walk(root);
+    return { subcommandsByPath, optionsByPath, positionalsByPath };
+}
+function optionAt(tables, path, flag) {
+    const opts = tables.optionsByPath.get(path) ?? [];
+    return opts.find((o) => o.long === flag || o.short === flag);
+}
+function isKnownSubcommand(tables, path, name) {
+    return (tables.subcommandsByPath.get(path) ?? []).some((c) => c.name === name);
+}
+/**
+ * Walk the words before the cursor to determine the current command path,
+ * skipping options and the values they consume (mirrors the static driver).
+ * Returns the resolved command path ("" = root).
+ */
+function resolvePath(tables, words, cword) {
+    let path = "";
+    let i = 1; // words[0] is the bin name
+    while (i < cword) {
+        const w = words[i] ?? "";
+        if (w.startsWith("-")) {
+            const opt = optionAt(tables, path, w);
+            if (opt?.takesValue)
+                i += 1; // skip the option's value
+        }
+        else if (isKnownSubcommand(tables, path, w)) {
+            path = path ? `${path} ${w}` : w;
+        }
+        i += 1;
+    }
+    return path;
+}
+/** Count positional args consumed at the resolved path (non-option, non-subcommand words). */
+function positionalIndex(tables, words, cword) {
+    let seen = "";
+    let after = 0;
+    let j = 1;
+    while (j < cword) {
+        const w = words[j] ?? "";
+        if (w.startsWith("-")) {
+            const opt = optionAt(tables, seen, w);
+            if (opt?.takesValue)
+                j += 1;
+        }
+        else if (isKnownSubcommand(tables, seen, w)) {
+            seen = seen ? `${seen} ${w}` : w;
+        }
+        else {
+            after += 1;
+        }
+        j += 1;
+    }
+    return after;
+}
+/** Resolve the value source (enum / dynamic-provider / file) for a value slot. */
+async function valueCandidates(source, partial, runProvider) {
+    if (source.dynamicProvider) {
+        try {
+            const values = await runProvider(source.dynamicProvider, partial);
+            return { candidates: values.map((value) => ({ value })), directive: Directive.Default };
+        }
+        catch {
+            return { candidates: [], directive: Directive.File };
+        }
+    }
+    if (source.valueChoices && source.valueChoices.length > 0) {
+        return {
+            candidates: source.valueChoices.map((value) => ({ value })),
+            directive: Directive.Default,
+        };
+    }
+    // A value is expected but we have nothing to suggest → let the shell try files.
+    return { candidates: [], directive: Directive.File };
+}
+/**
+ * Compute completion candidates for `words` with the cursor at `cword`.
+ * `words[0]` is the bin name; `words[cword]` is the (possibly empty) token
+ * being completed. The shell shim does the final prefix-filtering against that
+ * token, so this returns the full candidate set for the slot.
+ */
+export async function resolveCompletions(program, words, cword, lookup, runProvider) {
+    const tables = buildTables(walkProgram(program, lookup));
+    const path = resolvePath(tables, words, cword);
+    const cur = words[cword] ?? "";
+    const prev = cword > 0 ? (words[cword - 1] ?? "") : "";
+    // Case 1: previous word is an option that takes a value → complete the value.
+    if (prev.startsWith("-")) {
+        const opt = optionAt(tables, path, prev);
+        if (opt?.takesValue)
+            return valueCandidates(opt, cur, runProvider);
+    }
+    // Case 2: completing an option name (cur starts with "-").
+    if (cur.startsWith("-")) {
+        const opts = tables.optionsByPath.get(path) ?? [];
+        const candidates = [];
+        for (const o of opts) {
+            if (o.long)
+                candidates.push({ value: o.long, description: o.description });
+            if (o.short)
+                candidates.push({ value: o.short, description: o.description });
+        }
+        return { candidates, directive: Directive.Default };
+    }
+    // Case 3: subcommands available at this path → suggest them.
+    const subs = tables.subcommandsByPath.get(path) ?? [];
+    if (subs.length > 0) {
+        return {
+            candidates: subs.map((c) => ({ value: c.name, description: c.description })),
+            directive: Directive.Default,
+        };
+    }
+    // Case 4: positional value slot.
+    const positionals = tables.positionalsByPath.get(path) ?? [];
+    const idx = positionalIndex(tables, words, cword);
+    const pos = positionals[idx] ??
+        (positionals[positionals.length - 1]?.variadic
+            ? positionals[positionals.length - 1]
+            : undefined);
+    if (pos)
+        return valueCandidates(pos, cur, runProvider);
+    // Nothing structured to suggest → file completion.
+    return { candidates: [], directive: Directive.File };
+}
+/** Sentinel prefix for the trailing directive line in the wire protocol. */
+export const DIRECTIVE_PREFIX = "\x1f:";
+/**
+ * Serialize a result for the shell shim: one `value\tdescription` line per
+ * candidate, then a final `\x1f:<directive>` line. The \x1f (unit separator)
+ * prefix makes the directive line unambiguous against real candidate values.
+ */
+export function encodeResult(result) {
+    const lines = result.candidates.map((c) => c.description ? `${c.value}\t${c.description}` : c.value);
+    lines.push(`${DIRECTIVE_PREFIX}${result.directive}`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/lib/completion/zsh.d.ts

@@ -10,4 +10,12 @@
  */
 import type { CommandSpec } from "./walk.js";
 export declare function generateZsh(root: CommandSpec, binName: string): string;
+/**
+ * DYNAMIC zsh completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Candidate lines are `value\tdescription`; the shim converts
+ * the tab to `:` so `_describe` renders descriptions. The trailing `\x1f:<n>`
+ * line carries the directive (bit 0 = file fallback → `_files`).
+ */
+export declare function generateZshDynamic(binName: string): string;
 //# sourceMappingURL=zsh.d.ts.map

package/dist/lib/completion/zsh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zsh.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/zsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAwBzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAsGtE"}
+{"version":3,"file":"zsh.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/zsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAwBzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAsGtE;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAyB1D"}

package/dist/lib/completion/zsh.js

@@ -129,6 +129,39 @@ function truncate(s, n) {
         return "";
     return s.length > n ? `${s.slice(0, n - 1)}…` : s;
 }
+/**
+ * DYNAMIC zsh completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Candidate lines are `value\tdescription`; the shim converts
+ * the tab to `:` so `_describe` renders descriptions. The trailing `\x1f:<n>`
+ * line carries the directive (bit 0 = file fallback → `_files`).
+ */
+export function generateZshDynamic(binName) {
+    const fn = fnPrefix(binName);
+    return `#compdef ${binName}
+# ${binName} zsh completion (dynamic; install once, never stale). Do not edit.
+${fn}() {
+  emulate -L zsh
+  local line directive=0
+  local -a raw display
+  raw=( "\${(@f)$(${binName} __complete-line $((CURRENT-1)) -- "\${words[@]}" 2>/dev/null)}" )
+  for line in $raw; do
+    [ -z "$line" ] && continue
+    if [[ "$line" == $'\\x1f:'* ]]; then
+      directive="\${line#$'\\x1f:'}"
+    else
+      display+=( "\${line//$'\\t'/:}" )
+    fi
+  done
+  if (( directive & 1 )); then
+    _files
+    return
+  fi
+  _describe -t values 'completions' display
+}
+compdef ${fn} ${binName}
+`;
+}
 /**
  * The driver walks `$words` to determine the current command path, then
  * dispatches to subcommand / option / value completion. `fn` is the

package/dist/lib/docs-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAYA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkVD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAoBlE"}
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAYA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAuVD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAoBlE"}

package/dist/lib/docs-lint.js

@@ -204,6 +204,12 @@ function checkNamingConvention(repoName, _repoPath, files) {
         // Allowlisted names
         if (ROOT_FILE_ALLOWLIST.has(name))
             continue;
+        // Leading-underscore files are deliberate templates / meta files
+        // (e.g. _template.md), not content. The underscore is a convention
+        // marking "copy me, don't read me as a real doc", so exempt them
+        // from naming discipline rather than forcing kebab-case.
+        if (name.startsWith("_"))
+            continue;
         // Dated files (audits/issues)
         if (DATED_FILE_PATTERN.test(name))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/schemas/config.schema.json

@@ -19,6 +19,10 @@
       "default": "harn",
       "description": "Host CLI bin name used in agent-facing strings (council prompts, end-of-turn nudges, command help). The coord binaries + web UI run as harnery and read this back since they can't see a consumer CLI's name. Stamped by `harn init` for a consumer. Resolution: HARNERY_BIN env -> this field -> 'harn'."
     },
+    "hooksSetupHint": {
+      "type": "string",
+      "description": "Host-specific command that (re)installs the project's git hooks (e.g. 'scripts/setup-hooks.sh'). Surfaced verbatim in the SessionStart 'commit guard not wired' nudge. harnery doesn't own git-hook installation (each host wires its own pre-commit to invoke `agent-coord verdict`) and the path/command is host-specific, so the host declares it here. Unset -> a generic, host-agnostic hint."
+    },
     "coord": {
       "type": "object",
       "additionalProperties": false,

package/src/commander.ts

@@ -27,6 +27,7 @@ import { registerCompletionCommand } from "./commands/completion.ts";
 import { registerConfigGetCommand } from "./commands/config-get.ts";
 import { registerContextCommand } from "./commands/context.ts";
 import { registerCookiesCommand } from "./commands/cookies.ts";
+import { registerDeinitCommand } from "./commands/deinit.ts";
 import { registerDocsCommand } from "./commands/docs.ts";
 import { registerDoctorCommand } from "./commands/doctor.ts";
 import { registerEditBatchCommand } from "./commands/edit-batch.ts";
@@ -45,7 +46,6 @@ import { registerSyncCommand } from "./commands/sync.ts";
 import { registerSectionCommand, registerTocCommand } from "./commands/toc.ts";
 import { registerTokensCommand } from "./commands/tokens.ts";
 import { registerTunnelCommand } from "./commands/tunnel.ts";
-import { registerUninstallCommand } from "./commands/uninstall.ts";
 import { registerWebCommand } from "./commands/web.ts";
 
 export interface HarneryContextOpts {
@@ -230,7 +230,7 @@ export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   registerAgentsCommand(program, emit);
   registerDoctorCommand(program, emit);
   registerInitCommand(program, emit, opts.binName);
-  registerUninstallCommand(program, emit);
+  registerDeinitCommand(program, emit, opts.binName);
   registerBackupCommand(program, emit);
   registerSyncCommand(program, emit);
   if (include("web")) registerWebCommand(program, emit);

package/src/commands/completion.ts

@@ -4,9 +4,15 @@ import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import {
   type CompletionContextLookup,
+  type CompletionProviderRunner,
+  encodeResult,
   generateBash,
+  generateBashDynamic,
   generateFish,
+  generateFishDynamic,
   generateZsh,
+  generateZshDynamic,
+  resolveCompletions,
   walkProgram,
 } from "../lib/completion/index.ts";
 
@@ -39,27 +45,39 @@ export function registerCompletionCommand(
       "Shell tab-completion. Emit a script per shell or install to the standard location.",
     );
 
+  const dynamicHint =
+    "Emit a thin shim that calls the binary at tab-time (never goes stale; install once)";
+
   root
     .command("bash")
     .description("Emit bash completion script to stdout")
-    .action(() => {
-      const out = generateBash(walkProgram(program, lookup), program.name());
+    .option("--dynamic", dynamicHint)
+    .action((opts: { dynamic?: boolean }) => {
+      const out = opts.dynamic
+        ? generateBashDynamic(program.name())
+        : generateBash(walkProgram(program, lookup), program.name());
       process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
 
   root
     .command("zsh")
     .description("Emit zsh completion script to stdout")
-    .action(() => {
-      const out = generateZsh(walkProgram(program, lookup), program.name());
+    .option("--dynamic", dynamicHint)
+    .action((opts: { dynamic?: boolean }) => {
+      const out = opts.dynamic
+        ? generateZshDynamic(program.name())
+        : generateZsh(walkProgram(program, lookup), program.name());
       process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
 
   root
     .command("fish")
     .description("Emit fish completion script to stdout")
-    .action(() => {
-      const out = generateFish(walkProgram(program, lookup), program.name());
+    .option("--dynamic", dynamicHint)
+    .action((opts: { dynamic?: boolean }) => {
+      const out = opts.dynamic
+        ? generateFishDynamic(program.name())
+        : generateFish(walkProgram(program, lookup), program.name());
       process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
 
@@ -69,6 +87,7 @@ export function registerCompletionCommand(
     .option("--shell <name>", "bash | zsh | fish (default: auto-detect from $SHELL)")
     .option("--path <file>", "Override destination path")
     .option("--print-path", "Print the destination path and exit (no write)")
+    .option("--dynamic", `${dynamicHint} (recommended)`)
     .action(async (opts: InstallOpts) => {
       await installCompletion(program, opts, lookup);
     });
@@ -92,12 +111,39 @@ export function registerCompletionCommand(
     });
   // Keep TS happy that the variable is used.
   void hidden;
+
+  // Hidden internal entry for DYNAMIC completion: the thin shim passes the live
+  // command line (cursor index + all words after `--`) and we compute the full
+  // candidate set from the live command tree. `--` stops option parsing so
+  // words like `-h` reach the variadic instead of being read as our flags.
+  const hiddenLine = program
+    .command("__complete-line <cword> [words...]", { hidden: true })
+    .description("Internal: full-line completion callback for the dynamic shell shim")
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action(async (cword: string, words: string[] | undefined) => {
+      try {
+        const result = await resolveCompletions(
+          program,
+          words ?? [],
+          Number.parseInt(cword, 10) || 0,
+          lookup,
+          runProvider as CompletionProviderRunner,
+        );
+        process.stdout.write(encodeResult(result)); // lint-ok-emission: shell callback; the encoded candidate/directive stream is the contract with the shim.
+      } catch {
+        // Never break the user's tab: emit just the file-fallback directive.
+        process.stdout.write("\x1f:1\n"); // lint-ok-emission: shell callback fallback directive.
+      }
+    });
+  void hiddenLine;
 }
 
 interface InstallOpts {
   shell?: string;
   path?: string;
   printPath?: boolean;
+  dynamic?: boolean;
 }
 
 async function installCompletion(
@@ -117,16 +163,23 @@ async function installCompletion(
     return;
   }
 
+  const name = program.name();
   let content: string;
   switch (shell) {
     case "bash":
-      content = generateBash(walkProgram(program, lookup), program.name());
+      content = opts.dynamic
+        ? generateBashDynamic(name)
+        : generateBash(walkProgram(program, lookup), name);
       break;
     case "zsh":
-      content = generateZsh(walkProgram(program, lookup), program.name());
+      content = opts.dynamic
+        ? generateZshDynamic(name)
+        : generateZsh(walkProgram(program, lookup), name);
       break;
     case "fish":
-      content = generateFish(walkProgram(program, lookup), program.name());
+      content = opts.dynamic
+        ? generateFishDynamic(name)
+        : generateFish(walkProgram(program, lookup), name);
       break;
     default:
       process.stderr.write(`Unknown shell: ${shell}\n`); // lint-ok-emission: install-time error, see above.