knodin 0.7.4 → 0.7.6

package/dist/src/cli-args.js

@@ -1,274 +0,0 @@
-/**
- * CLI argument & repo-target resolution for the `knodin` CLI (R19).
- *
- * The MCP gateway takes an explicit `repoPath`; the CLI historically fell back
- * to `process.cwd()` with no equivalent flag, so `knodin index /other/repo` from
- * the wrong cwd silently indexed nothing and exited 0. These pure helpers give
- * the CLI one unambiguous way to target a repo (`--repo`) and make every no-op
- * fail loudly. Kept side-effect-free (only stat the filesystem) so bin/cli.ts is
- * a thin caller and the logic is unit-testable without an engine or database.
- */
-import fs from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
-const GLOBAL_VALUE_FLAGS = new Set([
-    "--identity",
-    "--file",
-    "--kind",
-    "--to-identity",
-    "--to-file",
-    "--to-kind",
-    "--bytes",
-    "--tokens",
-    "--items",
-    "--impact-mode",
-    "--direction",
-    "--depth",
-    "--relations",
-    "--min-confidence",
-    "--limit",
-]);
-const GLOBAL_BOOLEAN_FLAGS = new Set(["--exclude-tests", "--data-flow", "--json"]);
-const isDir = (p) => {
-    try {
-        return fs.statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-};
-const RUNTIME_MODULE_FLAGS = new Set([
-    "--import",
-    "--loader",
-    "--experimental-loader",
-    "--require",
-    "-r",
-]);
-function resolveRuntimeModuleReference(value, cwd, resolveModule) {
-    if (path.isAbsolute(value) || /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value))
-        return value;
-    if (value.startsWith("."))
-        return path.resolve(cwd, value);
-    return resolveModule(value, cwd);
-}
-/**
- * Reconstruct the executable command that launched this CLI. Source-checkout
- * invocations need loader arguments such as `node --import tsx`; dropping
- * `execArgv` creates a background hook that exists but cannot start. Bare
- * loader names are resolved now because the hook later runs from another repo.
- */
-export function resolveCliRuntimeCommand(runtime, resolveModule = (specifier, cwd) => createRequire(path.join(cwd, "package.json")).resolve(specifier)) {
-    const entry = runtime.argv[1];
-    if (!entry)
-        throw new Error("knodin: CLI entry path is unavailable");
-    const cwd = runtime.cwd();
-    const runtimeArguments = [];
-    for (let index = 0; index < runtime.execArgv.length; index++) {
-        const argument = runtime.execArgv[index];
-        if (RUNTIME_MODULE_FLAGS.has(argument)) {
-            const value = runtime.execArgv[index + 1];
-            if (!value)
-                throw new Error(`knodin: ${argument} requires a runtime module`);
-            runtimeArguments.push(argument, resolveRuntimeModuleReference(value, cwd, resolveModule));
-            index++;
-            continue;
-        }
-        const equalsFlag = [...RUNTIME_MODULE_FLAGS].find((flag) => argument.startsWith(`${flag}=`));
-        if (equalsFlag) {
-            const value = argument.slice(equalsFlag.length + 1);
-            if (!value)
-                throw new Error(`knodin: ${equalsFlag} requires a runtime module`);
-            runtimeArguments.push(`${equalsFlag}=${resolveRuntimeModuleReference(value, cwd, resolveModule)}`);
-            continue;
-        }
-        runtimeArguments.push(argument);
-    }
-    return [path.resolve(cwd, runtime.execPath), ...runtimeArguments, path.resolve(cwd, entry)];
-}
-/**
- * Pull a global `--repo <path>` / `--repo=<path>` out of an argv slice and
- * move any other documented global flags before the subcommand to immediately
- * after it. This preserves the existing command parsers while accepting both
- * conventional `knodin --file x explain y` and `knodin explain y --file x`.
- */
-export function extractRepoFlag(argv) {
-    const rest = [];
-    const leadingGlobalOptions = [];
-    let repoFlag;
-    let commandSeen = false;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--repo") {
-            repoFlag = argv[i + 1] ?? "";
-            i++; // consume the value
-        }
-        else if (a.startsWith("--repo=")) {
-            repoFlag = a.slice("--repo=".length);
-        }
-        else if (!commandSeen && GLOBAL_VALUE_FLAGS.has(a)) {
-            leadingGlobalOptions.push(a);
-            if (argv[i + 1] !== undefined)
-                leadingGlobalOptions.push(argv[++i]);
-        }
-        else if (!commandSeen && GLOBAL_BOOLEAN_FLAGS.has(a)) {
-            leadingGlobalOptions.push(a);
-        }
-        else {
-            rest.push(a);
-            commandSeen = true;
-        }
-    }
-    rest.push(...leadingGlobalOptions);
-    return { repoFlag, rest };
-}
-/** Return positional arguments without mistaking recognized option values for paths. */
-export function extractPositionals(args) {
-    const positionals = [];
-    for (let index = 0; index < args.length; index++) {
-        const argument = args[index];
-        if (argument.startsWith("--")) {
-            if (!argument.includes("=") && GLOBAL_VALUE_FLAGS.has(argument))
-                index++;
-            continue;
-        }
-        positionals.push(argument);
-    }
-    return positionals;
-}
-/**
- * Resolve the target repo: an explicit `--repo` (validated as an existing
- * directory) wins over `cwd`. An absent flag falls back to `cwd`.
- */
-export function resolveRepo(repoFlag, cwd) {
-    if (repoFlag === undefined)
-        return { ok: true, repo: cwd };
-    if (repoFlag === "")
-        return { ok: false, error: "knodin: --repo requires a <path>" };
-    const repo = path.resolve(cwd, repoFlag);
-    if (!fs.existsSync(repo)) {
-        return { ok: false, error: `knodin: --repo path does not exist: ${repo}` };
-    }
-    if (!isDir(repo)) {
-        return { ok: false, error: `knodin: --repo path is not a directory: ${repo}` };
-    }
-    return { ok: true, repo };
-}
-/**
- * Decide what `knodin index [positionals...]` actually targets, closing the
- * silent-no-op hole:
- *   - a lone directory positional with no `--repo` IS the repo (full reindex) —
- *     this is the observed-bug fix: `knodin index /other/repo` now indexes it;
- *   - any other directory positional is rejected, pointing at `--repo`;
- *   - file positionals resolving outside the target repo are rejected loudly;
- *   - otherwise the positionals are files to index within the resolved repo.
- */
-export function planIndex(repoFlag, positionals, cwd) {
-    // Case A: no --repo and a single directory positional => that directory is
-    // the repo to index, not a file. Absorb it as the target.
-    if (repoFlag === undefined && positionals.length === 1) {
-        const abs = path.resolve(cwd, positionals[0]);
-        if (isDir(abs)) {
-            return { ok: true, repo: abs, files: undefined };
-        }
-    }
-    const resolved = resolveRepo(repoFlag, cwd);
-    if (!resolved.ok)
-        return resolved;
-    const repo = resolved.repo;
-    if (positionals.length === 0) {
-        return { ok: true, repo, files: undefined }; // full reindex
-    }
-    // Case B: positionals are files. Validate each is a within-repo non-directory.
-    const rejectedDirs = [];
-    const rejectedOutside = [];
-    const files = [];
-    for (const p of positionals) {
-        const abs = path.resolve(repo, p);
-        const rel = path.relative(repo, abs);
-        if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
-            rejectedOutside.push(p);
-            continue;
-        }
-        if (isDir(abs)) {
-            rejectedDirs.push(p);
-            continue;
-        }
-        files.push(p);
-    }
-    if (rejectedOutside.length > 0 || rejectedDirs.length > 0) {
-        const parts = [];
-        if (rejectedOutside.length > 0) {
-            parts.push(`outside repo (${rejectedOutside.join(", ")})`);
-        }
-        if (rejectedDirs.length > 0) {
-            const hint = repoFlag === undefined
-                ? "use --repo to index a whole repo"
-                : "pass files, not directories, alongside --repo";
-            parts.push(`directories — ${hint} (${rejectedDirs.join(", ")})`);
-        }
-        return {
-            ok: false,
-            error: `knodin index: refusing to index against ${repo}; rejected ${parts.join("; ")}`,
-        };
-    }
-    return { ok: true, repo, files };
-}
-/**
- * Guard against reporting success for a no-op: an index run that touched zero
- * files must exit non-zero with a diagnostic naming the repo it actually used.
- */
-export function checkIndexed(indexed, repo) {
-    if (!indexed || indexed.length === 0) {
-        return { ok: false, error: `knodin index: indexed 0 files in ${repo} (nothing matched)` };
-    }
-    return { ok: true };
-}
-/** Pure parser for `knodin review`, shared by the executable and CLI contract tests. */
-export function parseReviewArgs(args) {
-    const value = (flag) => {
-        const index = args.indexOf(flag);
-        if (index < 0)
-            return undefined;
-        const candidate = args[index + 1];
-        if (!candidate || candidate.startsWith("--")) {
-            throw new Error(`knodin review: ${flag} requires a value`);
-        }
-        return candidate;
-    };
-    const rawScope = value("--scope");
-    const scopes = ["unstaged", "staged", "all", "compare"];
-    if (rawScope && !scopes.includes(rawScope)) {
-        throw new Error(`invalid review scope: ${rawScope}`);
-    }
-    const optionValues = new Set([
-        ...GLOBAL_VALUE_FLAGS,
-        "--scope",
-        "--from",
-        "--to",
-        "--files",
-        "--scip",
-    ]);
-    const positionals = args.filter((arg, index) => {
-        if (arg.startsWith("--"))
-            return false;
-        return index === 0 || !optionValues.has(args[index - 1]);
-    });
-    const filesValue = value("--files");
-    const files = filesValue
-        ?.split(",")
-        .map((file) => file.trim())
-        .filter(Boolean);
-    if (filesValue !== undefined && files?.length === 0) {
-        throw new Error("knodin review: --files requires at least one repo-relative path");
-    }
-    return {
-        base: positionals.find((item) => item !== "minimal") ?? "HEAD~1",
-        detailLevel: positionals.includes("minimal") ? "minimal" : "standard",
-        options: {
-            scope: rawScope,
-            from: value("--from"),
-            to: value("--to"),
-            files,
-        },
-    };
-}

package/dist/src/cli-model.js

@@ -1,358 +0,0 @@
-import { Argument, Command, CommanderError, Option } from "commander";
-import { formatTerminalHelp } from "./terminal-help.js";
-function integer(value, flags) {
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed))
-        throw new CommanderError(1, "knodin.invalidNumber", `${flags.split(" ")[0]} must be an integer`);
-    return parsed;
-}
-function numeric(value, flags) {
-    const parsed = Number(value);
-    if (!Number.isFinite(parsed))
-        throw new CommanderError(1, "knodin.invalidNumber", `${flags.split(" ")[0]} must be a number`);
-    return parsed;
-}
-function collect(value, previous) {
-    return [...previous, value];
-}
-function option(flags, description, parser) {
-    const configured = new Option(flags, description);
-    if (parser === "integer")
-        configured.argParser((value) => integer(value, flags));
-    else if (parser === "number")
-        configured.argParser((value) => numeric(value, flags));
-    else if (parser === "collect")
-        configured.argParser(collect).default([]);
-    return configured;
-}
-function leaf(parent, syntax, description, capture) {
-    const command = parent.command(syntax).description(description).allowExcessArguments(false);
-    command.action((...values) => capture(values.at(-1)));
-    return command;
-}
-function addGlobalOptions(program) {
-    program
-        .option("-v, --version", "print the installed knodin version")
-        .addOption(option("--repo <path>", "target a repository instead of the current directory"))
-        .option("--json", "emit stable JSON")
-        .addOption(option("--identity <id>", "select a stable symbol identity"))
-        .addOption(option("--file <path>", "select a repo-relative definition file"))
-        .addOption(option("--kind <kind>", "select a symbol kind"))
-        .addOption(option("--to-identity <id>", "select a destination identity"))
-        .addOption(option("--to-file <path>", "select a destination file"))
-        .addOption(option("--to-kind <kind>", "select a destination kind"))
-        .addOption(option("--bytes <count>", "bound serialized response bytes", "integer"))
-        .addOption(option("--tokens <count>", "bound serialized response tokens", "integer"))
-        .addOption(option("--items <count>", "bound serialized response items", "integer"))
-        .option("--impact-mode <mode>", "symbol or file impact")
-        .option("--direction <direction>", "upstream, downstream, or both")
-        .addOption(option("--depth <count>", "bounded traversal depth", "integer"))
-        .option("--relations <kinds>", "comma-separated relationship kinds")
-        .addOption(option("--min-confidence <value>", "minimum edge confidence", "number"))
-        .option("--limit <count>", "result limit")
-        .option("--exclude-tests", "exclude tests from impact")
-        .option("--data-flow", "include bounded data-flow evidence");
-}
-function addRepositoryCommands(program, capture) {
-    const repos = program.command("repos").description("manage a portfolio of repositories");
-    for (const action of ["discover", "init", "status", "doctor"]) {
-        const command = leaf(repos, `${action} <roots...>`, `${action} repositories beneath one or more roots`, capture)
-            .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
-            .option("--linked-worktrees <mode>", "skip or include linked worktrees");
-        if (action === "init") {
-            command
-                .addOption(option("--include <selector>", "include a repository id or path", "collect"))
-                .addOption(option("--exclude <selector>", "exclude a repository id or path", "collect"))
-                .option("--manifest <path>", "write or resume a portfolio manifest")
-                .option("--dry-run", "report actions without changing repositories");
-        }
-        if (action === "discover") {
-            command
-                .option("--signals", "include bounded repository applicability signals")
-                .addOption(option("--items <count>", "bound returned repositories and signal arrays", "integer"))
-                .addOption(option("--bytes <count>", "bound serialized response bytes", "integer"))
-                .addOption(option("--tokens <count>", "bound estimated response tokens", "integer"))
-                .addHelpText("after", "\n--signals returns hookManager, markerFiles, sanitized remotes, ciProviders, agentConfigs, and aidevTrackReferenced when known; every returned repository has signals, including {}. Inspection uses fixed documented marker/hook allowlists, reads only bounded hook configuration, and performs no network, credential, or marker-content reads. Linked worktrees inspect their own checkout when --linked-worktrees include is selected. See docs/REPOSITORIES-AND-WORKTREES.md for omissions and limits.\n");
-        }
-    }
-    leaf(repos, "search <query>", "search selected repositories sequentially", capture)
-        .addOption(option("--root <path>", "portfolio root", "collect"))
-        .addOption(option("--include <selector>", "include a repository id or path", "collect"))
-        .addOption(option("--exclude <selector>", "exclude a repository id or path", "collect"))
-        .option("--cursor <cursor>", "resume from an opaque cursor")
-        .option("--allow-partial", "return healthy repository results when another degrades");
-    const fleet = program.command("fleet").description("deprecated repository-fleet compatibility");
-    leaf(fleet, "init <roots...>", "initialize a repository fleet", capture)
-        .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
-        .option("--worktrees <mode>", "skip or include linked worktrees")
-        .option("--dry-run", "report actions without mutation");
-}
-function addGraphCommands(program, capture) {
-    leaf(program, "context <task> [base]", "build compact task orientation", capture);
-    leaf(program, "explain <symbol> [detail]", "explain one ambiguity-safe symbol", capture);
-    leaf(program, "review [base] [detail]", "review an explicit Git diff scope", capture)
-        .option("--scope <scope>", "unstaged, staged, all, or compare")
-        .option("--from <ref>", "comparison start revision")
-        .option("--to <ref>", "comparison end revision")
-        .option("--files <paths>", "comma-separated repo-relative paths");
-    leaf(program, "map", "show architecture communities and edges", capture)
-        .option("--standard", "include full map detail")
-        .addOption(option("--top <count>", "maximum ranked communities", "integer"))
-        .option("--sort <mode>", "relevance, name, size, degree, or complexity")
-        .option("--relations <kinds>", "comma-separated relationship kinds");
-    leaf(program, "wiki", "write local architecture wiki pages", capture).option("--force", "rewrite unchanged pages");
-    leaf(program, "visualize <entry>", "write a local architecture/call-flow HTML artifact", capture)
-        .requiredOption("--output <path>", "repo-relative HTML output path")
-        .addOption(option("--depth <count>", "call-flow depth", "integer"))
-        .addOption(option("--max-bytes <count>", "hard artifact budget", "integer"));
-    leaf(program, "search <query> [limit]", "hybrid symbol search", capture)
-        .option("--languages <values>", "comma-separated languages")
-        .option("--extensions <values>", "comma-separated extensions")
-        .option("--kinds <values>", "comma-separated symbol kinds")
-        .option("--path <prefix>", "repo-relative path prefix")
-        .option("--tests-only", "search test symbols only")
-        .option("--production-only", "search production symbols only")
-        .option("--no-source", "omit source snippets")
-        .addOption(option("--offset <count>", "pagination offset", "integer"))
-        .addOption(option("--limit <count>", "result limit", "integer"));
-    leaf(program, "query <pattern> [targets...]", "run one structured graph query", capture)
-        .option("--impact-mode <mode>", "symbol or file impact")
-        .option("--direction <direction>", "upstream, downstream, or both")
-        .addOption(option("--depth <count>", "bounded traversal depth", "integer"))
-        .option("--relations <kinds>", "comma-separated relationship kinds")
-        .addOption(option("--min-confidence <value>", "minimum edge confidence", "number"))
-        .option("--exclude-tests", "exclude tests from impact")
-        .option("--data-flow", "include bounded data-flow evidence")
-        .option("--limit <count>", "result limit")
-        .addOption(option("--min-lines <count>", "minimum line count", "integer"))
-        .addOption(option("--min-complexity <count>", "minimum complexity", "integer"))
-        .option("--kinds <values>", "comma-separated symbol kinds")
-        .option("--path <prefix>", "repo-relative path prefix")
-        .option("--variable <name>", "flow-analysis variable")
-        .option("--facets <values>", "comma-separated architecture facets")
-        .addOption(option("--top <count>", "maximum ranked results", "integer"))
-        .option("--sort <mode>", "result ordering");
-    leaf(program, "rename <old> <new>", "preview or apply an ambiguity-safe rename", capture)
-        .option("--apply", "apply the verified edit")
-        .option("--no-verify", "skip post-apply typecheck");
-}
-function addArtifactCommands(program, capture) {
-    leaf(program, "evidence <level> <file>", "deliver progressive source evidence", capture)
-        .option("--continuation <handle>", "resume an exact prior response")
-        .option("--baseline-hash <sha256>", "complete baseline SHA-256")
-        .addOption(option("--baseline-bytes <count>", "complete baseline UTF-8 bytes", "integer"))
-        .addOption(option("--start <line>", "first source line", "integer"))
-        .addOption(option("--end <line>", "last source line", "integer"));
-    const pack = program.command("pack").description("export bounded portable context");
-    pack
-        .argument("[input]")
-        .option("--format <format>", "markdown, json, or xml")
-        .option("--include <globs>", "comma-separated include globs")
-        .option("--exclude <globs>", "comma-separated exclude globs")
-        .option("--policy <assignments>", "comma-separated glob policies")
-        .option("--already-present <paths>", "comma-separated paths already in context")
-        .option("--chat-files <paths>", "comma-separated chat paths")
-        .option("--line-numbers", "include source line numbers")
-        .option("--tree", "include repository tree")
-        .option("--output <path>", "write a repo-relative retained artifact")
-        .option("--diff-scope <scope>", "unstaged, staged, all, or compare")
-        .option("--from <ref>", "comparison start revision")
-        .option("--to <ref>", "comparison end revision")
-        .addOption(option("--log <count>", "include recent commits", "integer"))
-        .action((...values) => capture(values.at(-1)));
-    leaf(pack, "read <artifact>", "read a retained context artifact", capture)
-        .addOption(option("--start <line>", "first line", "integer"))
-        .addOption(option("--end <line>", "last line", "integer"));
-    leaf(pack, "grep <artifact> <regex>", "search an artifact with a linear-time regex", capture)
-        .option("--flags <flags>", "regular-expression flags")
-        .addOption(option("--limit <count>", "match limit", "integer"));
-    const compress = program.command("compress").description("compress already-produced output");
-    compress
-        .argument("[input]")
-        .option("--strategy <strategy>", "smart, head-tail, or errors-only")
-        .option("--adapter <adapter>", "structured output adapter")
-        .addOption(option("--lines <count>", "hard line budget", "integer"))
-        .addOption(option("--max-output-bytes <count>", "hard output byte budget", "integer"))
-        .addOption(option("--context <count>", "signal context lines", "integer"))
-        .addOption(option("--exit-code <code>", "source process exit code", "integer"))
-        .option("--signal <name>", "source process termination signal")
-        .addOption(option("--max-input-bytes <count>", "hard input byte limit", "integer"))
-        .option("--no-retain", "do not retain raw drill-down data")
-        .option("--no-redact", "disable secret redaction")
-        .action((...values) => capture(values.at(-1)));
-    for (const action of ["read", "diagnose"]) {
-        leaf(compress, `${action} <artifact>`, `${action} a retained output artifact`, capture)
-            .addOption(option("--start <line>", "first line", "integer"))
-            .addOption(option("--end <line>", "last line", "integer"))
-            .addOption(option("--max-output-bytes <count>", "hard output byte budget", "integer"))
-            .addOption(option("--context <count>", "diagnostic context lines", "integer"))
-            .addOption(option("--limit <count>", "diagnostic result limit", "integer"))
-            .addOption(option("--offset <count>", "resume retained diagnostics at offset", "integer"))
-            .option("--raw", "return unredacted retained bytes");
-    }
-    leaf(compress, "delete <artifact>", "delete a retained output artifact", capture);
-}
-function createCliProgram(capture = () => { }) {
-    const program = new Command("knodin")
-        .description("knodin — source-evidenced local code intelligence with known bounds")
-        .showHelpAfterError()
-        .showSuggestionAfterError()
-        .passThroughOptions(false)
-        .allowExcessArguments(false)
-        .exitOverride();
-    program.configureOutput({ writeErr: () => { } });
-    addGlobalOptions(program);
-    program.addHelpText("after", "\nMCP callers use the `prs` operation and corresponding operations on the single `knodin` gateway.\nknodin update status|check|explain|apply|rollback consumes only threshold-signed metadata.\n");
-    leaf(program, "init", "initialize graph, lifecycle hooks, and agent integration", capture)
-        .option("--scope <scope>", "personal, team, or cli-only")
-        .addHelpText("after", "\nUsage: knodin init [--scope personal|team|cli-only] [--json]\n\npersonal  recommended; local/excluded agent adapters and a clean Git status\nteam      commit-ready shared agent configuration\ncli-only  no agent discovery; AI agents will not know to invoke knodin\n\nChange later with `knodin configure --scope <scope>`.\nTracked files are never added to Git exclude files.\n");
-    leaf(program, "configure", "change or inspect agent integration", capture)
-        .option("--scope <scope>", "personal, team, or cli-only")
-        .option("--status", "inspect configuration without changing it");
-    leaf(program, "index [files...]", "index a repository or selected files", capture)
-        .option("--clean", "rebuild selected index state")
-        .option("--force", "force clean indexing")
-        .option("--scip <file>", "opt in to a bounded local SCIP protobuf import");
-    leaf(program, "doctor", "diagnose installation, clients, hooks, graph, and updates", capture).option("--client <client>", "claude, codex, gemini, or antigravity");
-    leaf(program, "status", "report graph, lifecycle, integration, and update state", capture)
-        .option("--deep", "run a full graph audit")
-        .option("--watch", "stream status snapshots")
-        .addOption(option("--interval <seconds>", "watch interval", "number"));
-    leaf(program, "wait", "wait for current graph evidence", capture)
-        .option("--fresh", "wait for a fresh graph")
-        .addOption(option("--timeout <seconds>", "deadline", "number"));
-    leaf(program, "repair", "audit and reconcile graph state", capture)
-        .option("--plan", "report the repair plan without mutation")
-        .option("--jsonl", "stream JSONL progress")
-        .option("--progress <mode>", "tty, jsonl, plain, or none")
-        .option("--progress-interval <duration>", "progress interval such as 750ms, 30s, or 2m");
-    leaf(program, "serve", "run the one-tool MCP gateway on stdio", capture);
-    leaf(program, "version", "print the installed knodin version", capture);
-    leaf(program, "hook-refresh <kind> [values...]", "internal Git lifecycle refresh", capture);
-    leaf(program, "refresh-artifacts [event]", "refresh external graph artifacts", capture);
-    addRepositoryCommands(program, capture);
-    addGraphCommands(program, capture);
-    addArtifactCommands(program, capture);
-    const system = program.command("system").description("inspect declared multi-repository systems");
-    leaf(system, "list", "list configured systems", capture);
-    for (const action of ["show", "validate", "query"]) {
-        const command = leaf(system, `${action} <system-id>`, `${action} one configured system`, capture);
-        if (action === "query")
-            command.option("--allow-partial", "return healthy components");
-    }
-    const update = program
-        .command("update")
-        .description("inspect or apply threshold-signed updates")
-        .allowExcessArguments(false)
-        .addArgument(new Argument("<action>").choices(["status", "check", "explain", "apply", "rollback"]));
-    update.action((...values) => capture(values.at(-1)));
-    leaf(program, "docs <topic>", "read canonical product documentation", capture);
-    leaf(program, "prs [action]", "audit pull requests, reviews, and checks", capture)
-        .option("--state <state>", "open, merged, closed, or all")
-        .addOption(option("--limit <count>", "pull-request limit", "integer"))
-        .option("--branches <pattern>", "branch-name pattern")
-        .option("--range <range>", "pull-request number range")
-        .option("--base <ref>", "audit base revision")
-        .option("--head <ref>", "audit head revision")
-        .option("--expected-login <login>", "expected GitHub identity");
-    leaf(program, "worktrees [action] [path]", "inspect, reconcile, or remove managed worktrees", capture).option("--dry-run", "report removal without mutation");
-    const telemetry = program
-        .command("telemetry")
-        .description("manage local opt-in ROI telemetry")
-        .allowExcessArguments(false)
-        .addArgument(new Argument("<action>").choices(["status", "report", "export", "clear"]));
-    telemetry
-        .option("--input <path>", "telemetry input path")
-        .option("--output <path>", "dashboard or evidence-bundle output path")
-        .addOption(option("--retention-days <count>", "retention window in days", "integer"))
-        .action((...values) => capture(values.at(-1)));
-    const diagnostics = program
-        .command("diagnostics")
-        .description("manage local troubleshooting diagnostics and support bundles")
-        .allowExcessArguments(false)
-        .addArgument(new Argument("<action>").choices([
-        "enable",
-        "status",
-        "collect",
-        "inspect",
-        "clear",
-        "disable",
-    ]))
-        .addArgument(new Argument("[bundle]"));
-    diagnostics
-        .addOption(option("--retention-days <count>", "local event retention in days", "integer"))
-        .option("--since <duration>", "collection window, such as 24h or 7d")
-        .option("--output <path>", "repository-contained .json.gz bundle path")
-        .action((...values) => capture(values.at(-1)));
-    return program;
-}
-function flattenPositionals(values) {
-    return values
-        .flatMap((value) => (Array.isArray(value) ? value : [value]))
-        .filter((value) => typeof value === "string");
-}
-/** Parse and validate one invocation without running a product operation. */
-export function parseCliInvocation(argv) {
-    let selected;
-    const program = createCliProgram((command) => {
-        selected = command;
-    });
-    program.parse([process.execPath, "knodin", ...argv]);
-    if (!selected)
-        return { commandPath: [], positionals: [], options: program.opts() };
-    const command = selected;
-    const commandPath = [];
-    for (let current = command; current?.parent; current = current.parent) {
-        commandPath.unshift(current.name());
-    }
-    return {
-        commandPath,
-        positionals: flattenPositionals(command.processedArgs),
-        options: command.optsWithGlobals(),
-    };
-}
-/** Render root or nested help from the exact parser model. */
-export function renderCliHelp(commandPath, columns) {
-    const program = createCliProgram();
-    let selected = program;
-    for (const name of commandPath) {
-        const child = selected.commands.find((command) => command.name() === name);
-        if (!child)
-            throw new Error(`knodin: unknown help command ${commandPath.join(" ")}`);
-        selected = child;
-    }
-    selected.configureHelp({ helpWidth: Math.max(60, Math.floor(columns ?? 100) - 1) });
-    let output = "";
-    selected.configureOutput({ writeOut: (value) => (output += value), writeErr: () => { } });
-    selected.outputHelp();
-    return formatTerminalHelp(output, columns);
-}
-/** Resolve the deepest declared command before a help flag or positional. */
-export function helpCommandPath(argv) {
-    const program = createCliProgram();
-    const path = [];
-    let selected = program;
-    for (let index = 0; index < argv.length; index++) {
-        const value = argv[index];
-        if (value === "-h" || value === "--help")
-            break;
-        if (value.startsWith("-")) {
-            const optionName = value.split("=", 1)[0];
-            let cursor = selected;
-            let declared;
-            while (cursor && !declared) {
-                declared = cursor.options.find((candidate) => candidate.short === optionName || candidate.long === optionName);
-                cursor = cursor.parent;
-            }
-            if (declared?.required && !value.includes("="))
-                index++;
-            continue;
-        }
-        const child = selected.commands.find((command) => command.name() === value);
-        if (!child)
-            break;
-        selected = child;
-        path.push(value);
-    }
-    return path;
-}