knodin 0.5.0

package/dist/src/agent-integration.js

@@ -0,0 +1,250 @@
+import child_process from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+export function parseInitScope(value) {
+    if (value === "personal" || value === "team" || value === "cli-only")
+        return value;
+    throw new Error("knodin: --scope must be personal, team, or cli-only");
+}
+const MCP_NAME = "knodin";
+const LEGACY_MCP_NAME = "reckon-graph";
+const TOML_START = "# knodin:start";
+const TOML_END = "# knodin:end";
+const LEGACY_TOML_START = "# reckon-graph:start";
+const LEGACY_TOML_END = "# reckon-graph:end";
+const TOML_BLOCK = `${TOML_START}
+[mcp_servers."${MCP_NAME}"]
+command = "knodin"
+args = ["serve"]
+${TOML_END}`;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function commandExists(command) {
+    try {
+        child_process.execFileSync("which", [command], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Detect primary MCP-capable coding agents without launching them. */
+export function detectSupportedAgents() {
+    const detected = [];
+    if (commandExists("claude"))
+        detected.push("claude");
+    if (commandExists("codex"))
+        detected.push("codex");
+    if (commandExists("gemini"))
+        detected.push("gemini");
+    if (commandExists("antigravity") || commandExists("agy"))
+        detected.push("antigravity");
+    return detected;
+}
+function defaultRunner(command) {
+    try {
+        child_process.execFileSync(command.executable, command.args, {
+            cwd: command.cwd,
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+    }
+    catch (error) {
+        if (command.executable !== "claude" || !command.args.includes("add"))
+            throw error;
+        child_process.execFileSync("claude", ["mcp", "get", MCP_NAME], {
+            cwd: command.cwd,
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+    }
+}
+/**
+ * Configure command-backed personal integrations. Claude stores local scope
+ * outside the checkout; Codex/Gemini/Antigravity use excluded project files.
+ */
+export function configurePersonalAgents(options) {
+    const run = options.run ?? defaultRunner;
+    const configured = [];
+    const removed = [];
+    const failed = [];
+    for (const agent of options.detected) {
+        if (agent !== "claude")
+            continue;
+        const removeLegacy = {
+            executable: "claude",
+            args: ["mcp", "remove", LEGACY_MCP_NAME, "--scope", "local"],
+        };
+        try {
+            run(removeLegacy);
+        }
+        catch {
+            // A missing legacy registration is already the desired state.
+        }
+        const command = options.remove
+            ? {
+                executable: "claude",
+                args: ["mcp", "remove", MCP_NAME, "--scope", "local"],
+            }
+            : {
+                executable: "claude",
+                args: ["mcp", "add", MCP_NAME, "--scope", "local", "--", "knodin", "serve"],
+            };
+        try {
+            run(command);
+            (options.remove ? removed : configured).push(agent);
+        }
+        catch (error) {
+            // Removing a missing registration is already the desired state.
+            if (options.remove)
+                removed.push(agent);
+            else
+                failed.push({ agent, message: errorMessage(error) });
+        }
+    }
+    return { configured, removed, failed, projectFiles: [] };
+}
+function readJsonObject(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new Error("expected a JSON object");
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw new Error(`${filePath}: ${errorMessage(error)}`);
+    }
+}
+function assertSafeProjectPath(repo, filePath) {
+    const relative = path.relative(repo, filePath);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`${filePath}: agent configuration must stay inside the repository`);
+    let current = repo;
+    for (const part of relative.split(path.sep)) {
+        current = path.join(current, part);
+        try {
+            if (fs.lstatSync(current).isSymbolicLink())
+                throw new Error(`${filePath}: refusing to follow a symbolic link`);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+}
+function formatProjectJson(document) {
+    return `${JSON.stringify(document, null, "\t").replace(/"args": \[\n(\t+)"serve"\n\t+\]/g, '"args": ["serve"]')}\n`;
+}
+function updateJsonMcp(filePath, remove) {
+    const document = readJsonObject(filePath);
+    const existing = document.mcpServers;
+    const servers = typeof existing === "object" && existing !== null && !Array.isArray(existing)
+        ? { ...existing }
+        : {};
+    delete servers[LEGACY_MCP_NAME];
+    if (remove)
+        delete servers[MCP_NAME];
+    else
+        servers[MCP_NAME] = { command: "knodin", args: ["serve"] };
+    if (Object.keys(servers).length > 0)
+        document.mcpServers = servers;
+    else
+        delete document.mcpServers;
+    if (remove && Object.keys(document).length === 0) {
+        fs.rmSync(filePath, { force: true });
+        return false;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, formatProjectJson(document), "utf-8");
+    return true;
+}
+function updateTomlMcp(filePath, remove) {
+    let existing = "";
+    try {
+        existing = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    function removeManagedBlock(content, startMarker, endMarker) {
+        const start = content.indexOf(startMarker);
+        const end = content.indexOf(endMarker);
+        return start >= 0 && end >= start
+            ? `${content.slice(0, start)}${content.slice(end + endMarker.length)}`.trim()
+            : content.trim();
+    }
+    const without = removeManagedBlock(removeManagedBlock(existing, LEGACY_TOML_START, LEGACY_TOML_END), TOML_START, TOML_END);
+    const next = remove ? without : [without, TOML_BLOCK].filter(Boolean).join("\n\n");
+    if (!next) {
+        fs.rmSync(filePath, { force: true });
+        return false;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${next}\n`, "utf-8");
+    return true;
+}
+/** Merge or remove knodin's project-local agent adapters without replacing user configuration. */
+export function configureProjectAgents(options) {
+    const repo = path.resolve(options.repo);
+    const remove = options.scope === "cli-only";
+    const agents = options.scope === "team"
+        ? ["claude", "codex", "gemini", "antigravity"]
+        : options.agents;
+    const commandResult = options.scope === "team"
+        ? { configured: [], removed: [], failed: [], projectFiles: [] }
+        : configurePersonalAgents({
+            detected: agents,
+            remove,
+            run: options.run ?? ((command) => defaultRunner({ ...command, cwd: repo })),
+        });
+    const configured = [...commandResult.configured];
+    const removed = [...commandResult.removed];
+    const failed = [...commandResult.failed];
+    const projectFiles = [];
+    for (const agent of agents) {
+        try {
+            let relative = null;
+            let remains = false;
+            if (agent === "claude" && options.scope === "team") {
+                relative = ".mcp.json";
+                assertSafeProjectPath(repo, path.join(repo, relative));
+                remains = updateJsonMcp(path.join(repo, relative), false);
+            }
+            else if (agent === "claude") {
+                relative = ".mcp.json";
+                assertSafeProjectPath(repo, path.join(repo, relative));
+                remains = updateJsonMcp(path.join(repo, relative), true);
+            }
+            else if (agent === "codex") {
+                relative = ".codex/config.toml";
+                assertSafeProjectPath(repo, path.join(repo, relative));
+                remains = updateTomlMcp(path.join(repo, relative), remove);
+            }
+            else if (agent === "gemini") {
+                relative = ".gemini/settings.json";
+                assertSafeProjectPath(repo, path.join(repo, relative));
+                remains = updateJsonMcp(path.join(repo, relative), remove);
+            }
+            else if (agent === "antigravity") {
+                relative = ".agents/mcp_config.json";
+                assertSafeProjectPath(repo, path.join(repo, relative));
+                remains = updateJsonMcp(path.join(repo, relative), remove);
+            }
+            if (relative && remains)
+                projectFiles.push(relative);
+            if (agent === "claude" && options.scope === "team" && !configured.includes(agent))
+                configured.push(agent);
+            if (agent !== "claude" && !remove && !configured.includes(agent))
+                configured.push(agent);
+            if (remove && !removed.includes(agent))
+                removed.push(agent);
+        }
+        catch (error) {
+            failed.push({ agent, message: errorMessage(error) });
+        }
+    }
+    return { configured, removed, failed, projectFiles };
+}

package/dist/src/artifact-refresh.js

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+const REFRESH_TIMEOUT_MS = 30_000;
+function defaultRuntime() {
+    return {
+        commandExists: (command) => {
+            const probe = spawnSync(command, ["--help"], { stdio: "ignore", timeout: 5_000 });
+            return (probe.status !== null ||
+                probe.error?.code !== "ENOENT");
+        },
+        run: (command, cwd) => {
+            const startedAt = performance.now();
+            const result = spawnSync(command[0], command.slice(1), {
+                stdio: "ignore",
+                timeout: REFRESH_TIMEOUT_MS,
+                cwd,
+            });
+            return {
+                exitCode: result.status,
+                elapsedMs: Math.round(performance.now() - startedAt),
+                timedOut: result.signal === "SIGTERM" || result.signal === "SIGKILL",
+            };
+        },
+    };
+}
+/**
+ * Explicitly refresh supported local, external graph artifacts. This is never a
+ * commit hook: callers opt in, each rebuild is time-bounded, and unavailable
+ * tools are recorded as skipped rather than being represented as fresh.
+ */
+export function refreshExternalGraphArtifacts(repoPath, event, runtime = defaultRuntime()) {
+    const repo = path.resolve(repoPath);
+    const gitNexusRunner = path.join(repo, ".gitnexus", "run.cjs");
+    const commands = [
+        fs.existsSync(gitNexusRunner)
+            ? {
+                artifact: "gitnexus",
+                command: ["node", gitNexusRunner, "analyze"],
+                requiredCommand: "node",
+            }
+            : {
+                artifact: "gitnexus",
+                command: ["gitnexus", "analyze", repo],
+                requiredCommand: "gitnexus",
+            },
+        { artifact: "graphify", command: ["graphify", "update", repo], requiredCommand: "graphify" },
+    ];
+    const artifacts = commands.map(({ artifact, command, requiredCommand }) => {
+        if (!runtime.commandExists(requiredCommand)) {
+            return { artifact, state: "skipped", reason: `${artifact} is not installed` };
+        }
+        const result = runtime.run(command, repo);
+        if (result.exitCode === 0) {
+            return { artifact, state: "success", command, elapsedMs: result.elapsedMs };
+        }
+        return {
+            artifact,
+            state: "failed",
+            command,
+            elapsedMs: result.elapsedMs,
+            reason: result.timedOut
+                ? `timed out after ${REFRESH_TIMEOUT_MS}ms`
+                : `exited ${result.exitCode ?? "unknown"}`,
+        };
+    });
+    const successes = artifacts.filter((artifact) => artifact.state === "success").length;
+    const failures = artifacts.filter((artifact) => artifact.state === "failed").length;
+    const status = failures > 0 && successes === 0
+        ? "failed"
+        : failures > 0 || successes > 0
+            ? "partial"
+            : "skipped";
+    return { event, status, artifacts };
+}
+/** Persist an audit record locally; no source content or tool output is retained. */
+export function writeArtifactRefreshRecord(repoPath, result) {
+    const knodinDir = path.join(path.resolve(repoPath), ".reckon");
+    fs.mkdirSync(knodinDir, { recursive: true });
+    fs.appendFileSync(path.join(knodinDir, "artifact-refresh.jsonl"), `${JSON.stringify({ at: new Date().toISOString(), ...result })}\n`, "utf8");
+}

package/dist/src/cli-args.js

@@ -0,0 +1,267 @@
+/**
+ * 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"]);
+    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,
+        },
+    };
+}