knodin 0.6.0 → 0.7.3

package/dist/src/diagnostics.js

@@ -0,0 +1,449 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+const CONFIG_PATH = ".knodin/diagnostics/config.json";
+const JOURNAL_PATH = ".knodin/diagnostics/events.jsonl";
+const JOURNAL_LOCK_PATH = ".knodin/diagnostics/events.lock";
+const DEFAULT_RETENTION_DAYS = 14;
+const MAX_RETENTION_DAYS = 365;
+const MAX_RECORDS = 500;
+const MAX_LOG_BYTES = 64 * 1024;
+const MAX_BUNDLE_BYTES = 20 * 1024 * 1024;
+const MAX_JOURNAL_BYTES = 2 * 1024 * 1024;
+const OPERATIONS = new Set([
+    "init",
+    "configure",
+    "index",
+    "doctor",
+    "status",
+    "wait",
+    "repair",
+    "serve",
+    "context",
+    "explain",
+    "review",
+    "map",
+    "search",
+    "query",
+    "rename",
+    "wiki",
+    "visualize",
+    "pack",
+    "compress",
+    "prs",
+    "worktrees",
+    "telemetry",
+    "diagnostics",
+    "system",
+    "repos",
+    "repositories",
+    "update",
+    "docs",
+    "unknown",
+]);
+function containedPath(repoPath, requested, purpose) {
+    const repo = fs.realpathSync(repoPath);
+    const target = path.resolve(repo, requested);
+    if (target !== repo && !target.startsWith(`${repo}${path.sep}`))
+        throw new Error(`knodin diagnostics ${purpose}: path must stay inside the repository`);
+    let cursor = repo;
+    for (const segment of path.relative(repo, target).split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, segment);
+        try {
+            if (fs.lstatSync(cursor).isSymbolicLink())
+                throw new Error(`knodin diagnostics ${purpose}: refusing symlinked path`);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+    return { repo, target };
+}
+function atomicPrivateWrite(target, data) {
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+    fs.writeFileSync(temporary, data, { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, target);
+}
+function withJournalLock(repo, run) {
+    const { target: lock } = containedPath(repo, JOURNAL_LOCK_PATH, "record");
+    fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.mkdirSync(lock, { mode: 0o700 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > 30_000) {
+                    fs.rmdirSync(lock);
+                    continue;
+                }
+            }
+            catch (inspectionError) {
+                if (inspectionError.code === "ENOENT")
+                    continue;
+                throw inspectionError;
+            }
+            if (attempt >= 100)
+                throw new Error("knodin diagnostics record: journal is busy");
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+        }
+    }
+    try {
+        return run();
+    }
+    finally {
+        try {
+            fs.rmdirSync(lock);
+        }
+        catch {
+            // Recording is best-effort; stale-lock recovery handles interrupted cleanup.
+        }
+    }
+}
+function validRetention(days) {
+    if (!Number.isInteger(days) || days < 1 || days > MAX_RETENTION_DAYS)
+        throw new Error(`knodin diagnostics: retention days must be an integer from 1 to ${MAX_RETENTION_DAYS}`);
+    return days;
+}
+function readConfig(repoPath) {
+    const { target } = containedPath(repoPath, CONFIG_PATH, "status");
+    if (!fs.existsSync(target))
+        return null;
+    try {
+        const value = JSON.parse(fs.readFileSync(target, "utf8"));
+        if (value.schemaVersion !== 1 || value.enabled !== true)
+            return null;
+        validRetention(value.retentionDays);
+        if (!Number.isInteger(value.generation) || value.generation < 1)
+            value.generation = 1;
+        if (typeof value.sessionId !== "string" || !/^[a-f0-9]{32}$/.test(value.sessionId))
+            value.sessionId = crypto
+                .createHash("sha256")
+                .update(value.enabledAt)
+                .digest("hex")
+                .slice(0, 32);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function safeLabel(value, fallback) {
+    return value && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,63}$/.test(value) ? value : fallback;
+}
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === "string" &&
+        /^(?:E[A-Z0-9]+|ERR_[A-Z0-9_]+|SQLITE_[A-Z0-9_]+|KNODIN_[A-Z0-9_]+)$/.test(code)
+        ? code
+        : null;
+}
+function scrubText(raw, repo) {
+    let value = raw;
+    let redactions = 0;
+    const replace = (pattern, replacement) => {
+        value = value.replace(pattern, () => {
+            redactions++;
+            return replacement;
+        });
+    };
+    for (const exact of [repo, os.homedir()].filter(Boolean).sort((a, b) => b.length - a.length))
+        replace(new RegExp(exact.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), "<path>");
+    replace(/\b(?:ghp|github_pat|sk|xox[baprs])-[-A-Za-z0-9_]{10,}\b/g, "<secret>");
+    replace(/\b(?:password|passwd|token|secret|api[_-]?key|authorization)\s*[=:]\s*[^\s,;]+/gi, "$1=<secret>");
+    replace(/\b[A-Z]:\\(?:[^\s<>:"|?*]+\\)*[^\s<>:"|?*]*/g, "<path>");
+    replace(/(?:^|[\s('"`])\/(?:[^\s)'"`]+\/)*[^\s)'"`]*/g, "<path>");
+    replace(/\b(?:[A-Za-z0-9_.-]+\/)+(?:[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,12})\b/g, "<path>");
+    replace(/\b[A-Za-z0-9_.+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, "<email>");
+    return { value: value.slice(0, 2_000), redactions };
+}
+function sanitizeStack(error, repo) {
+    return (error.stack ?? "")
+        .split(/\r?\n/)
+        .slice(1, 9)
+        .map((line) => `at ${line.includes(repo) ? "<repository>" : "<runtime>"}`);
+}
+function sanitizeUnknown(value, repo, state) {
+    if (typeof value === "string") {
+        const scrubbed = scrubText(value, repo);
+        state.redactions += scrubbed.redactions;
+        return scrubbed.value;
+    }
+    if (Array.isArray(value))
+        return value.slice(0, 500).map((item) => sanitizeUnknown(item, repo, state));
+    if (value && typeof value === "object") {
+        const output = {};
+        for (const [key, item] of Object.entries(value).slice(0, 500)) {
+            const safeKey = /[\\/]|\.[A-Za-z0-9]{1,12}$/.test(key) ? "<path-key>" : key;
+            if (safeKey !== key)
+                state.redactions++;
+            if (/^(?:source|content|query|command|arguments?|env(?:ironment)?|remote)$/i.test(key)) {
+                output[safeKey] = "<omitted>";
+                state.redactions++;
+            }
+            else
+                output[safeKey] = sanitizeUnknown(item, repo, state);
+        }
+        return output;
+    }
+    return value;
+}
+function readEvents(repoPath, retentionDays, since) {
+    const { target } = containedPath(repoPath, JOURNAL_PATH, "read");
+    if (!fs.existsSync(target))
+        return [];
+    if (fs.statSync(target).size > MAX_JOURNAL_BYTES)
+        throw new Error("knodin diagnostics read: journal exceeds the 2 MiB safety limit");
+    const cutoff = Math.max(Date.now() - validRetention(retentionDays) * 86_400_000, since?.getTime() ?? Number.NEGATIVE_INFINITY);
+    return fs
+        .readFileSync(target, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            const record = JSON.parse(line);
+            return record.schemaVersion === 1 && Date.parse(record.at) >= cutoff ? [record] : [];
+        }
+        catch {
+            return [];
+        }
+    })
+        .slice(-MAX_RECORDS);
+}
+export function enableDiagnostics(repoPath, retentionDays = DEFAULT_RETENTION_DAYS) {
+    const { repo, target } = containedPath(repoPath, CONFIG_PATH, "enable");
+    withJournalLock(repo, () => {
+        const previous = readConfig(repo);
+        const config = {
+            schemaVersion: 1,
+            enabled: true,
+            retentionDays: validRetention(retentionDays),
+            enabledAt: new Date().toISOString(),
+            generation: (previous?.generation ?? 0) + 1,
+            sessionId: crypto.randomBytes(16).toString("hex"),
+        };
+        atomicPrivateWrite(target, `${JSON.stringify(config, null, 2)}\n`);
+    });
+    return { ...diagnosticsStatus(repo), message: "Local diagnostics enabled; nothing is uploaded." };
+}
+export function disableDiagnostics(repoPath) {
+    const { repo, target } = containedPath(repoPath, CONFIG_PATH, "disable");
+    withJournalLock(repo, () => {
+        if (fs.existsSync(target))
+            fs.unlinkSync(target);
+    });
+    return {
+        ...diagnosticsStatus(repo),
+        message: "Local diagnostics disabled; retained events were not deleted.",
+    };
+}
+export function diagnosticsStatus(repoPath) {
+    const config = readConfig(repoPath);
+    const retentionDays = config?.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    let events = [];
+    let journal = {
+        status: "healthy",
+        issue: null,
+    };
+    try {
+        events = readEvents(repoPath, retentionDays);
+    }
+    catch (error) {
+        journal = {
+            status: "unavailable",
+            issue: error instanceof Error ? error.message : "diagnostic journal is unavailable",
+        };
+    }
+    return {
+        schemaVersion: 1,
+        enabled: config !== null,
+        localOnly: true,
+        uploaded: false,
+        retentionDays,
+        records: events.length,
+        oldestAt: events[0]?.at ?? null,
+        newestAt: events.at(-1)?.at ?? null,
+        journal,
+    };
+}
+export function recordDiagnosticFailure(repoPath, input) {
+    try {
+        const repo = fs.realpathSync(repoPath);
+        const observed = readConfig(repo);
+        if (!observed)
+            return { recorded: false, reason: "disabled" };
+        return withJournalLock(repo, () => {
+            const config = readConfig(repo);
+            if (!config)
+                return { recorded: false, reason: "disabled" };
+            if (config.sessionId !== observed.sessionId || config.generation !== observed.generation)
+                return { recorded: false, reason: "state-changed" };
+            const error = input.error instanceof Error ? input.error : new Error(String(input.error));
+            const message = scrubText(error.message, repo).value;
+            const event = {
+                schemaVersion: 1,
+                at: new Date().toISOString(),
+                correlationId: crypto.randomBytes(8).toString("hex"),
+                surface: input.surface,
+                operation: OPERATIONS.has(input.operation) ? input.operation : "unknown",
+                phase: safeLabel(input.phase, "operation"),
+                error: {
+                    name: safeLabel(error.name, "Error"),
+                    code: errorCode(input.error),
+                    messageFingerprint: crypto
+                        .createHash("sha256")
+                        .update(message)
+                        .digest("hex")
+                        .slice(0, 16),
+                    stack: sanitizeStack(error, repo),
+                },
+            };
+            const events = [...readEvents(repo, config.retentionDays), event].slice(-MAX_RECORDS);
+            const { target } = containedPath(repo, JOURNAL_PATH, "record");
+            atomicPrivateWrite(target, `${events.map((record) => JSON.stringify(record)).join("\n")}\n`);
+            return { recorded: true, correlationId: event.correlationId };
+        });
+    }
+    catch {
+        return { recorded: false, reason: "unavailable" };
+    }
+}
+export function clearDiagnostics(repoPath) {
+    const { repo, target } = containedPath(repoPath, JOURNAL_PATH, "clear");
+    return withJournalLock(repo, () => {
+        if (!fs.existsSync(target))
+            return { removed: false, records: 0, bytes: 0 };
+        let records = null;
+        try {
+            records = readEvents(repo, MAX_RETENTION_DAYS).length;
+        }
+        catch {
+            // Deletion must remain the recovery path for an unreadable or oversized journal.
+        }
+        const bytes = fs.statSync(target).size;
+        fs.unlinkSync(target);
+        const config = readConfig(repo);
+        if (config) {
+            atomicPrivateWrite(containedPath(repo, CONFIG_PATH, "clear").target, `${JSON.stringify({ ...config, generation: config.generation + 1 }, null, 2)}\n`);
+        }
+        return { removed: true, records, bytes };
+    });
+}
+function defaultBundlePath() {
+    return `.knodin/diagnostics/knodin-diagnostics-${new Date().toISOString().replace(/[:.]/g, "-")}.json.gz`;
+}
+function lifecycleLog(repo, state) {
+    const target = path.join(repo, ".knodin", "indexer.log");
+    if (!fs.existsSync(target) || fs.lstatSync(target).isSymbolicLink())
+        return [];
+    const size = fs.statSync(target).size;
+    const descriptor = fs.openSync(target, "r");
+    try {
+        const length = Math.min(size, MAX_LOG_BYTES);
+        const buffer = Buffer.alloc(length);
+        fs.readSync(descriptor, buffer, 0, length, Math.max(0, size - length));
+        return buffer
+            .toString("utf8")
+            .split(/\r?\n/)
+            .filter(Boolean)
+            .slice(-200)
+            .map((line) => sanitizeUnknown(line, repo, state));
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+export function collectDiagnostics(repoPath, options = {}) {
+    const { repo, target } = containedPath(repoPath, options.outputPath ?? defaultBundlePath(), "collect");
+    if (fs.existsSync(target))
+        throw new Error("knodin diagnostics collect: refusing to overwrite an existing bundle");
+    const sinceHours = options.sinceHours ?? 24;
+    if (!Number.isFinite(sinceHours) || sinceHours <= 0 || sinceHours > 24 * 365)
+        throw new Error("knodin diagnostics collect: --since must be from 1h through 8760h");
+    const state = { redactions: 0 };
+    const status = diagnosticsStatus(repo);
+    const bundle = {
+        manifest: {
+            schemaVersion: 1,
+            generatedAt: new Date().toISOString(),
+            privacy: "redacted-local-only",
+            localOnly: true,
+            uploaded: false,
+            redactions: 0,
+            omissions: [
+                "source",
+                "queries-and-arguments",
+                "environment-values",
+                "git-remotes-diffs-and-messages",
+                "raw-paths",
+            ],
+        },
+        runtime: {
+            ...(options.knodinVersion ? { knodinVersion: options.knodinVersion } : {}),
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        diagnostics: status,
+        diagnosticEvents: readEvents(repo, status.retentionDays, new Date(Date.now() - sinceHours * 3_600_000)),
+        telemetry: sanitizeUnknown(options.telemetry ?? [], repo, state),
+        doctor: sanitizeUnknown(options.doctor ?? null, repo, state),
+        graph: sanitizeUnknown(options.graph ?? null, repo, state),
+        lifecycleLog: lifecycleLog(repo, state),
+    };
+    bundle.manifest.redactions = state.redactions;
+    atomicPrivateWrite(target, zlib.gzipSync(`${JSON.stringify(bundle, null, 2)}\n`, { level: 9 }));
+    return {
+        schemaVersion: 1,
+        outputPath: path.relative(repo, target),
+        format: "gzip-json",
+        localOnly: true,
+        uploaded: false,
+        bytes: fs.statSync(target).size,
+        records: bundle.diagnosticEvents.length,
+        redactions: bundle.manifest.redactions,
+        message: "Bundle created locally. Run `knodin diagnostics inspect <bundle>` before sharing it.",
+    };
+}
+export function inspectDiagnosticsBundle(repoPath, bundlePath) {
+    const { target } = containedPath(repoPath, bundlePath, "inspect");
+    if (!fs.existsSync(target))
+        throw new Error("knodin diagnostics inspect: bundle does not exist");
+    if (fs.statSync(target).size > 10 * 1024 * 1024)
+        throw new Error("knodin diagnostics inspect: bundle exceeds the 10 MiB safety limit");
+    let parsed;
+    try {
+        parsed = JSON.parse(zlib
+            .gunzipSync(fs.readFileSync(target), { maxOutputLength: MAX_BUNDLE_BYTES })
+            .toString("utf8"));
+    }
+    catch {
+        throw new Error("knodin diagnostics inspect: invalid gzip JSON bundle");
+    }
+    if (parsed.manifest?.schemaVersion !== 1 || parsed.manifest.privacy !== "redacted-local-only")
+        throw new Error("knodin diagnostics inspect: unsupported or unsafe bundle manifest");
+    if (!Array.isArray(parsed.diagnosticEvents) ||
+        !Array.isArray(parsed.telemetry) ||
+        !Array.isArray(parsed.lifecycleLog))
+        throw new Error("knodin diagnostics inspect: malformed bundle sections");
+    return {
+        manifest: parsed.manifest,
+        runtime: parsed.runtime,
+        diagnostics: parsed.diagnostics,
+        sections: ["diagnosticEvents", "telemetry", "doctor", "graph", "lifecycleLog"],
+        counts: {
+            diagnosticEvents: parsed.diagnosticEvents.length,
+            telemetry: parsed.telemetry.length,
+            lifecycleLogLines: parsed.lifecycleLog.length,
+        },
+        bundle: parsed,
+    };
+}