knodin 0.5.0

package/dist/src/cli-model.js

@@ -0,0 +1,324 @@
+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");
+        }
+    }
+    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) {
+    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"))
+            .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");
+    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)));
+    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;
+}

package/dist/src/compact-structural.js

@@ -0,0 +1,96 @@
+const IDENTITY_PREFIX = "sym_";
+/** A stable, repository-scoped shorthand. Prefix collisions remain ambiguity-safe
+ * because selectors are expanded as prefixes rather than guessed as one symbol. */
+export function compactIdentity(identity) {
+    if (!identity)
+        return "~?";
+    const body = identity.startsWith(IDENTITY_PREFIX)
+        ? identity.slice(IDENTITY_PREFIX.length)
+        : identity;
+    return `~${body.slice(0, 6)}`;
+}
+export function expandCompactIdentity(identity) {
+    return identity?.startsWith("~") ? `${IDENTITY_PREFIX}${identity.slice(1)}*` : identity;
+}
+function freshness(value) {
+    if (value === "reconciled")
+        return "reconciled";
+    if (value === "unknown")
+        return "unknown";
+    return "fresh";
+}
+function terseSignature(row) {
+    const signature = row.signature?.replace(/\s+/g, " ").trim() ?? "";
+    if (!signature)
+        return "";
+    const python = /^(.*?:)(?:\s|$)/.exec(signature)?.[1];
+    return python ?? signature;
+}
+function rowLine(row, repeatFile) {
+    const nested = row.parent?.symbol ? `${row.parent.symbol}/` : "";
+    const filePrefix = repeatFile ? `${row.file ?? "?"}:` : "";
+    const location = `${filePrefix}${row.line ?? "?"}`;
+    const signature = terseSignature(row);
+    const signatureSuffix = signature ? ` ${signature}` : "";
+    return `${compactIdentity(row.identity)} ${row.kind ?? "?"} ${nested}${row.symbol ?? "?"}@${location}${signatureSuffix}`;
+}
+function withinBytes(header, rows, byteBudget) {
+    let selected = rows;
+    if (byteBudget !== undefined) {
+        while (selected.length > 0 &&
+            Buffer.byteLength([header(selected.length), ...selected].join("\n"), "utf8") > byteBudget)
+            selected = selected.slice(0, -1);
+    }
+    const output = [header(selected.length), ...selected].join("\n");
+    return byteBudget !== undefined && Buffer.byteLength(output, "utf8") > byteBudget ? "" : output;
+}
+export function compactQueryResult(result, byteBudget) {
+    if (result.ambiguity)
+        return compactAmbiguity(result.ambiguity.candidates, result.staleness);
+    const total = result.count;
+    const state = freshness(result.staleness);
+    if (result.pattern === "project_overview") {
+        const rows = result.results.map((row) => `${row.symbol ?? row.file ?? "."} ${row.fileCount ?? 0} ${row.sizeBytes ?? 0}B`);
+        return withinBytes((n) => `${state} ${n}/${total}`, rows, byteBudget);
+    }
+    const repeatFile = result.pattern === "batch_outline";
+    const rows = result.results.map((row) => rowLine(row, repeatFile));
+    return withinBytes((n) => {
+        const continuation = result.hasMore ? "+" : "";
+        const target = result.target ? ` ${result.target}` : "";
+        return `${state} ${n}/${total}${continuation}${target}`;
+    }, rows, byteBudget);
+}
+export function compactSearchResult(page, query, byteBudget) {
+    const normalize = (value) => value.toLocaleLowerCase().replace(/[^a-z0-9]/g, "");
+    const normalized = normalize(query);
+    const matches = page.results.filter((row) => normalize(row.symbol).includes(normalized));
+    const state = freshness(matches[0]?.staleness ?? page.results[0]?.staleness);
+    const rows = matches.map((row) => {
+        const source = row.source ? ` ${row.source}` : "";
+        return `${compactIdentity(row.identity)} ${row.kind} @${row.filePath}${source}`;
+    });
+    return withinBytes((n) => `${state} ${n}/${matches.length}${page.hasMore ? "+" : ""} ${query}`, rows, byteBudget);
+}
+export function compactExplainResult(result, selectorFile, byteBudget) {
+    if (result.ambiguity)
+        return compactAmbiguity(result.ambiguity.candidates, result.staleness);
+    const numbered = result.source ?? "";
+    const firstLine = Number(/^(\d+): /.exec(numbered)?.[1] ?? 0);
+    const source = numbered
+        .split("\n")
+        .map((line) => line.replace(/^\d+: /, ""))
+        .join("\n");
+    const header = `${freshness(result.staleness)} ${compactIdentity(result.identity)} ${selectorFile ?? "?"}:${firstLine || "?"}`;
+    const output = `${header}\n${source}`;
+    if (byteBudget === undefined || Buffer.byteLength(output, "utf8") <= byteBudget)
+        return output;
+    const omitted = `${header}\nomitted ${Buffer.byteLength(source, "utf8")}B`;
+    return Buffer.byteLength(omitted, "utf8") <= byteBudget ? omitted : "";
+}
+function compactAmbiguity(candidates, staleness) {
+    return [
+        `ambiguous ${freshness(staleness)} ${candidates.length}`,
+        ...candidates.map((candidate) => `${compactIdentity(candidate.identity)} ${candidate.kind} ${candidate.file}:${candidate.line}`),
+    ].join("\n");
+}

package/dist/src/competitive-constraints.js

@@ -0,0 +1,20 @@
+/** Verifies the local-only, single-gateway contract that qualifies a competitive replay. */
+export function assessCompetitiveConstraints(tools) {
+    const mcpToolNames = tools.map((tool) => tool.name).sort();
+    const schemaBytes = Buffer.byteLength(JSON.stringify(tools));
+    const violations = [];
+    if (tools.length !== 1)
+        violations.push(`Expected one MCP tool, found ${tools.length}`);
+    if (mcpToolNames.length !== 1 || mcpToolNames[0] !== "knodin")
+        violations.push(`Expected only the knodin gateway, found ${mcpToolNames.join(", ") || "none"}`);
+    return {
+        passed: violations.length === 0,
+        mcpToolCount: tools.length,
+        mcpToolNames,
+        schemaBytes,
+        schemaTokens: Math.ceil(schemaBytes / 4),
+        localOnly: true,
+        optionalServices: ["local GitHub CLI integration (prs operation)"],
+        violations,
+    };
+}