knodin 0.7.6 → 0.8.2

package/dist/src/lifecycle-health.js

@@ -0,0 +1,282 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { compareBytes } from "./compare.js";
+import { isMirror, resolveDbPath } from "./engine/state-paths.js";
+import { inspectLefthookIntegration, isActiveLefthookHook } from "./hook-manager-integration.js";
+const MANAGED_MARKER = "KNODIN MANAGED HOOK";
+const HOOK_NAMES = ["post-commit", "post-checkout", "post-merge", "post-rewrite"];
+const HOOK_FAILURE_FILE = "last-refresh-failure";
+function readEvent(target) {
+    try {
+        const [kind = "", legacyBefore = "", legacyAfter = "", ...rest] = fs
+            .readFileSync(target, "utf-8")
+            .split(/\r?\n/);
+        if (!kind)
+            return null;
+        const metadata = new Map([legacyBefore, legacyAfter, ...rest]
+            .map((line) => {
+            const separator = line.indexOf("=");
+            return separator < 0 ? null : [line.slice(0, separator), line.slice(separator + 1)];
+        })
+            .filter((entry) => entry !== null));
+        return {
+            sequence: metadata.get("sequence") || null,
+            kind,
+            before: metadata.get("before") ||
+                (kind === "commit" || kind === "checkout" || kind === "merge" ? legacyBefore : "") ||
+                null,
+            after: metadata.get("after") ||
+                (kind === "commit" || kind === "checkout" || kind === "merge" ? legacyAfter : "") ||
+                null,
+            worktree: metadata.get("worktree") || null,
+            at: metadata.get("at") || fs.statSync(target).mtime.toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function readLastEvent(repo) {
+    return readEvent(path.join(repo, ".knodin", "hooks", "last-refresh-event"));
+}
+function readPendingEvent(repo) {
+    try {
+        const directory = path.join(repo, ".knodin", "hooks", "events");
+        const next = fs
+            .readdirSync(directory)
+            .filter((entry) => entry.endsWith(".event"))
+            // Byte order: `[0]` picks which queued event is reported as pending.
+            .sort(compareBytes)[0];
+        return next ? readEvent(path.join(directory, next)) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function processorState(repo) {
+    const pidPath = path.join(repo, ".knodin", "hooks", "refresh.lock", "pid");
+    if (!fs.existsSync(path.dirname(pidPath)))
+        return { state: "idle", pid: null };
+    let pid = null;
+    try {
+        const candidate = Number(fs.readFileSync(pidPath, "utf-8"));
+        if (Number.isInteger(candidate) && candidate > 0)
+            pid = candidate;
+    }
+    catch {
+        return { state: "stale-lock", pid: null };
+    }
+    if (pid === null)
+        return { state: "stale-lock", pid: null };
+    try {
+        process.kill(pid, 0);
+        return { state: "running", pid };
+    }
+    catch (error) {
+        if (error.code === "EPERM")
+            return { state: "running", pid };
+        return { state: "stale-lock", pid };
+    }
+}
+function queuedEventCount(repo) {
+    try {
+        return fs
+            .readdirSync(path.join(repo, ".knodin", "hooks", "events"))
+            .filter((entry) => entry.endsWith(".event")).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function activeHooksDirectory(repo) {
+    const output = childProcess.execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-path", "hooks"], { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    return output.trim();
+}
+/**
+ * Classifies how lifecycle hooks reach knodin. Both routes present reads as
+ * "mixed" rather than picking a winner, because that combination is what a
+ * partially-migrated repository looks like and the caller must be able to say so.
+ */
+function hookRouting(wrappers, managerNative) {
+    if (wrappers > 0 && managerNative > 0)
+        return "mixed";
+    if (wrappers > 0)
+        return "managed-wrapper";
+    return managerNative > 0 ? "manager-native" : "unavailable";
+}
+function inspectManagedHooks(repo, hooksDirectory) {
+    const activeHooks = [];
+    const missingHooks = [];
+    let wrappers = 0;
+    let managerNative = 0;
+    const lefthook = inspectLefthookIntegration(repo);
+    for (const hookName of HOOK_NAMES) {
+        try {
+            const hookPath = path.join(hooksDirectory, hookName);
+            const content = fs.readFileSync(hookPath, "utf-8");
+            const mode = fs.statSync(hookPath).mode;
+            const wrapper = content.startsWith(`#!/bin/sh\n# ${MANAGED_MARKER}: ${hookName}\n`);
+            const native = lefthook.configured && isActiveLefthookHook(content);
+            const active = (mode & 0o111) !== 0 && (wrapper || native);
+            if (active && wrapper)
+                wrappers++;
+            else if (active && native)
+                managerNative++;
+            (active ? activeHooks : missingHooks).push(hookName);
+        }
+        catch {
+            missingHooks.push(hookName);
+        }
+    }
+    return {
+        activeHooks,
+        missingHooks,
+        hookManager: lefthook.configured ? "lefthook" : null,
+        routing: hookRouting(wrappers, managerNative),
+    };
+}
+function readRefreshFailure(repo) {
+    const failurePath = path.join(repo, ".knodin", "hooks", HOOK_FAILURE_FILE);
+    if (!fs.existsSync(failurePath))
+        return null;
+    try {
+        return (fs.readFileSync(failurePath, "utf-8").split(/\r?\n/, 1)[0]?.trim() ||
+            "last background refresh failed");
+    }
+    catch {
+        return "last background refresh failed";
+    }
+}
+/** Read-only proof that committed Git activity can still reach knodin's indexer. */
+export function inspectLifecycleHealth(repoPath) {
+    const repo = path.resolve(repoPath);
+    // A mirror deliberately has no lifecycle hooks: its working tree is replaced
+    // wholesale on refresh and nothing of ours may live inside it. Judging it
+    // against hook health would report "degraded" and demand `knodin init` for
+    // every mirror, forever — a permanent false alarm that teaches callers to
+    // ignore genuine repair prompts. Its freshness comes from the recorded
+    // snapshot, not from Git events.
+    if (isMirror(repo)) {
+        return {
+            status: "healthy",
+            refreshCapable: false,
+            hooksDirectory: null,
+            activeHooks: [],
+            missingHooks: [],
+            issues: [],
+            queuedEvents: 0,
+            processor: { state: "idle", pid: null },
+            pendingEvent: null,
+            lastEvent: null,
+            lastError: null,
+            hookManager: null,
+            routing: "unavailable",
+        };
+    }
+    if (!fs.existsSync(resolveDbPath(repo))) {
+        return {
+            status: "unconfigured",
+            refreshCapable: false,
+            hooksDirectory: null,
+            activeHooks: [],
+            missingHooks: [...HOOK_NAMES],
+            issues: ["local graph database is not initialized"],
+            queuedEvents: 0,
+            processor: { state: "idle", pid: null },
+            pendingEvent: null,
+            lastEvent: null,
+            lastError: null,
+            hookManager: null,
+            routing: "unavailable",
+        };
+    }
+    let hooksDirectory;
+    try {
+        hooksDirectory = activeHooksDirectory(repo);
+    }
+    catch {
+        return {
+            status: "degraded",
+            refreshCapable: false,
+            hooksDirectory: null,
+            activeHooks: [],
+            missingHooks: [...HOOK_NAMES],
+            issues: ["active Git hooks directory could not be resolved"],
+            queuedEvents: queuedEventCount(repo),
+            processor: processorState(repo),
+            pendingEvent: readPendingEvent(repo),
+            lastEvent: readLastEvent(repo),
+            lastError: null,
+            hookManager: null,
+            routing: "unavailable",
+        };
+    }
+    const { activeHooks, missingHooks, hookManager, routing } = inspectManagedHooks(repo, hooksDirectory);
+    const background = path.join(repo, ".knodin", "hooks", "background-index.sh");
+    const backgroundReady = fs.existsSync(background) && (fs.statSync(background).mode & 0o111) !== 0;
+    const issues = missingHooks.map((hook) => `${hook} no longer routes through knodin's active Git hook path`);
+    if (!backgroundReady)
+        issues.push("background indexer is missing or not executable");
+    const lastError = readRefreshFailure(repo);
+    if (lastError)
+        issues.push(`${lastError} See .knodin/indexer.log for details`);
+    const refreshCapable = missingHooks.length === 0 && backgroundReady && issues.length === 0;
+    return {
+        status: refreshCapable ? "healthy" : "degraded",
+        refreshCapable,
+        hooksDirectory,
+        activeHooks,
+        missingHooks,
+        issues,
+        queuedEvents: queuedEventCount(repo),
+        processor: processorState(repo),
+        pendingEvent: readPendingEvent(repo),
+        lastEvent: readLastEvent(repo),
+        lastError,
+        hookManager,
+        routing,
+    };
+}
+/** Merge graph and refresh-path health without reporting absent evidence as healthy. */
+export function attachLifecycleHealth(repo, graph) {
+    const lifecycle = inspectLifecycleHealth(repo);
+    if (lifecycle.queuedEvents > 0 &&
+        graph.status !== "repair-needed" &&
+        graph.status !== "indexing" &&
+        graph.freshness) {
+        return {
+            ...graph,
+            status: "stale",
+            freshness: { ...graph.freshness, state: "queued" },
+            lifecycle,
+        };
+    }
+    if (graph.status !== "healthy" || lifecycle.status !== "degraded")
+        return { ...graph, lifecycle };
+    return {
+        ...graph,
+        status: "repair-needed",
+        missing: {
+            files: [...graph.missing.files],
+            records: [...graph.missing.records, ...lifecycle.issues],
+        },
+        repairSteps: [
+            ...graph.repairSteps,
+            "Run `knodin init` to restore managed lifecycle hooks.",
+            "Run `knodin status` again to verify graph and refresh-path health.",
+        ],
+        lifecycle,
+    };
+}
+/** Keep graph-repair success distinct from lifecycle integration health. */
+export function attachRepairLifecycle(repo, result) {
+    const lifecycle = inspectLifecycleHealth(repo);
+    return {
+        ...result,
+        lifecycle,
+        nextSteps: lifecycle.status === "degraded"
+            ? ["Run `knodin init` to restore lifecycle routing, then `knodin status`."]
+            : [],
+    };
+}

package/dist/src/lsp-readonly.js

@@ -0,0 +1,217 @@
+/**
+ * Read-only local language-service adapters.
+ *
+ * This deliberately embeds no daemon and never invokes workspace commands. The
+ * first adapter is TypeScript's compiler language service, which implements the
+ * same source-position operations exposed by an LSP server. Other languages are
+ * explicitly unavailable until a similarly local, read-only adapter is added.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const TYPESCRIPT_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"]);
+function unavailable(pattern, target, reason) {
+    return {
+        pattern,
+        target,
+        count: 0,
+        results: [],
+        adapter: "none",
+        available: false,
+        readOnly: true,
+        reason,
+    };
+}
+function parseTarget(repoPath, target) {
+    const match = target.match(/^(.*?)(?::(\d+):(\d+))?$/);
+    if (!match?.[1])
+        return undefined;
+    const file = match[1].replaceAll("\\", "/");
+    const absoluteFile = path.resolve(repoPath, file);
+    const relative = path.relative(repoPath, absoluteFile);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        return undefined;
+    if ((match[2] === undefined) !== (match[3] === undefined))
+        return undefined;
+    return {
+        file: relative.replaceAll(path.sep, "/"),
+        absoluteFile,
+        ...(match[2] ? { line: Number(match[2]), column: Number(match[3]) } : {}),
+    };
+}
+function filesForService(repoPath, ts) {
+    const isInsideRepo = (file) => {
+        try {
+            const relativePath = path.relative(repoPath, fs.realpathSync(file));
+            return !relativePath.startsWith("..") && !path.isAbsolute(relativePath);
+        }
+        catch {
+            return false;
+        }
+    };
+    const config = ts.findConfigFile(repoPath, ts.sys.fileExists, "tsconfig.json");
+    if (config) {
+        const loaded = ts.readConfigFile(config, ts.sys.readFile);
+        if (!loaded.error) {
+            const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, path.dirname(config));
+            return parsed.fileNames.filter((file) => TYPESCRIPT_EXTENSIONS.has(path.extname(file)) && isInsideRepo(file));
+        }
+    }
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".knodin")
+                continue;
+            const candidate = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(candidate);
+            else if (entry.isFile() && TYPESCRIPT_EXTENSIONS.has(path.extname(entry.name)))
+                files.push(candidate);
+        }
+    };
+    visit(repoPath);
+    return files;
+}
+function createService(repoPath, files, ts) {
+    const versions = new Map(files.map((file) => [file, "0"]));
+    const options = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        strict: true,
+        skipLibCheck: true,
+    };
+    return ts.createLanguageService({
+        getCompilationSettings: () => options,
+        getScriptFileNames: () => files,
+        getScriptVersion: (file) => versions.get(file) ?? "0",
+        getScriptSnapshot: (file) => {
+            try {
+                return ts.ScriptSnapshot.fromString(fs.readFileSync(file, "utf-8"));
+            }
+            catch {
+                return undefined;
+            }
+        },
+        getCurrentDirectory: () => repoPath,
+        getDefaultLibFileName: (settings) => ts.getDefaultLibFilePath(settings),
+        fileExists: ts.sys.fileExists,
+        readFile: ts.sys.readFile,
+        readDirectory: ts.sys.readDirectory,
+        directoryExists: ts.sys.directoryExists,
+        getDirectories: ts.sys.getDirectories,
+    });
+}
+function relative(repoPath, file) {
+    return path.relative(repoPath, file).replaceAll(path.sep, "/");
+}
+function positionFor(source, line, column) {
+    if (!Number.isInteger(line) || !Number.isInteger(column) || line < 1 || column < 1)
+        return undefined;
+    const lines = source.split("\n");
+    if (line > lines.length || column > lines[line - 1].length + 1)
+        return undefined;
+    return (lines.slice(0, line - 1).reduce((offset, current) => offset + current.length + 1, 0) +
+        column -
+        1);
+}
+function diagnosticRow(repoPath, diagnostic, ts) {
+    const file = diagnostic.file;
+    const location = file && diagnostic.start !== undefined
+        ? file.getLineAndCharacterOfPosition(diagnostic.start)
+        : undefined;
+    return {
+        file: file ? relative(repoPath, file.fileName) : undefined,
+        line: location ? location.line + 1 : undefined,
+        column: location ? location.character + 1 : undefined,
+        kind: ts.DiagnosticCategory[diagnostic.category].toLowerCase(),
+        message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+        code: diagnostic.code,
+    };
+}
+function navigationRows(repoPath, entries, ts) {
+    return (entries ?? []).map((entry) => {
+        const source = fs.readFileSync(entry.fileName, "utf-8");
+        const location = ts
+            .createSourceFile(entry.fileName, source, ts.ScriptTarget.Latest)
+            .getLineAndCharacterOfPosition(entry.textSpan.start);
+        return {
+            file: relative(repoPath, entry.fileName),
+            line: location.line + 1,
+            column: location.character + 1,
+            kind: entry.kind,
+            symbol: "name" in entry ? entry.name : undefined,
+        };
+    });
+}
+/** Executes a bounded, local compiler-language-service query without writes. */
+export async function runReadOnlyLspQuery(pattern, target, repoPath) {
+    let ts;
+    try {
+        ts = await import("typescript");
+    }
+    catch {
+        return unavailable(pattern, target, "No local TypeScript language-service adapter is installed; install TypeScript to enable this read-only query.");
+    }
+    let canonicalRepoPath;
+    try {
+        canonicalRepoPath = fs.realpathSync(repoPath);
+    }
+    catch {
+        return unavailable(pattern, target, "Repository path must be an accessible directory.");
+    }
+    const parsed = parseTarget(repoPath, target);
+    if (!parsed || !fs.existsSync(parsed.absoluteFile))
+        return unavailable(pattern, target, "Target must be an existing repo-relative file, optionally with :line:column.");
+    if (!TYPESCRIPT_EXTENSIONS.has(path.extname(parsed.absoluteFile)))
+        return unavailable(pattern, target, `No local LSP adapter is installed for ${path.extname(parsed.absoluteFile) || "this file type"}.`);
+    let realTarget;
+    try {
+        realTarget = fs.realpathSync(parsed.absoluteFile);
+        const relativeTarget = path.relative(canonicalRepoPath, realTarget);
+        if (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget))
+            return unavailable(pattern, target, "Target must resolve inside the repository.");
+    }
+    catch {
+        return unavailable(pattern, target, "Target must be a readable regular file.");
+    }
+    if (pattern !== "lsp_diagnostics" && (parsed.line === undefined || parsed.column === undefined))
+        return unavailable(pattern, target, "Navigation queries require target syntax file:line:column.");
+    const files = filesForService(canonicalRepoPath, ts);
+    if (!files.includes(realTarget))
+        files.push(realTarget);
+    const service = createService(canonicalRepoPath, files, ts);
+    try {
+        let rows;
+        if (pattern === "lsp_diagnostics") {
+            rows = [
+                ...service.getSyntacticDiagnostics(realTarget),
+                ...service.getSemanticDiagnostics(realTarget),
+            ].map((diagnostic) => diagnosticRow(canonicalRepoPath, diagnostic, ts));
+        }
+        else {
+            const line = parsed.line;
+            const column = parsed.column;
+            if (line === undefined || column === undefined)
+                return unavailable(pattern, target, "Navigation queries require target syntax file:line:column.");
+            const position = positionFor(fs.readFileSync(realTarget, "utf-8"), line, column);
+            if (position === undefined)
+                return unavailable(pattern, target, "Target line and column must identify a position inside the source file.");
+            rows = navigationRows(canonicalRepoPath, pattern === "lsp_implementations"
+                ? service.getImplementationAtPosition(realTarget, position)
+                : service.getDefinitionAtPosition(realTarget, position), ts);
+        }
+        return {
+            pattern,
+            target,
+            count: rows.length,
+            results: rows.slice(0, 100),
+            hasMore: rows.length > 100 || undefined,
+            adapter: "typescript-language-service",
+            available: true,
+            readOnly: true,
+        };
+    }
+    finally {
+        service.dispose();
+    }
+}

package/dist/src/mcp-graph-worker.js

@@ -0,0 +1,69 @@
+import readline from "node:readline";
+import { DatabaseSync } from "node:sqlite";
+import { resolveDbPath } from "./engine/state-paths.js";
+import { attachMcpRequestSignal, handleKnodinTool } from "./tools/knodin-tools.js";
+const IPC_VERSION = 1;
+const active = new Map();
+function send(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+async function receive(message) {
+    if (message.version !== IPC_VERSION)
+        return;
+    if (message.type === "cancel") {
+        active.get(message.id)?.abort("gateway-cancelled");
+        return;
+    }
+    const controller = new AbortController();
+    active.set(message.id, controller);
+    send({ version: IPC_VERSION, type: "progress", id: message.id, sequence: 1, phase: "dispatch" });
+    try {
+        const fault = message.args?.__c89Fault;
+        if (process.env.KNODIN_MCP_FAULT_FIXTURES === "1") {
+            if (fault === "crash")
+                process.exit(91);
+            if (fault === "hang")
+                await new Promise(() => undefined);
+            if (fault === "lock") {
+                const repo = message.args.repoPath ?? process.cwd();
+                const database = new DatabaseSync(resolveDbPath(repo));
+                database.exec("INSERT INTO c89_lock_fixture(value) VALUES ('worker')");
+                database.close();
+            }
+        }
+        attachMcpRequestSignal(message.args, controller.signal);
+        const result = await handleKnodinTool(message.args);
+        send({ version: IPC_VERSION, type: "result", id: message.id, result });
+    }
+    catch (error) {
+        send({
+            version: IPC_VERSION,
+            type: "error",
+            id: message.id,
+            error: {
+                name: error instanceof Error ? error.name : "Error",
+                message: error instanceof Error ? error.message : String(error),
+                code: typeof error?.code === "string"
+                    ? error.code
+                    : null,
+            },
+        });
+    }
+    finally {
+        active.delete(message.id);
+    }
+}
+const lines = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Number.POSITIVE_INFINITY,
+});
+lines.on("line", (line) => {
+    try {
+        void receive(JSON.parse(line));
+    }
+    catch {
+        send({ version: IPC_VERSION, type: "protocol-error" });
+    }
+});
+lines.on("close", () => process.exit(0));
+send({ version: IPC_VERSION, type: "ready", pid: process.pid });