chapterhouse 0.7.0 → 0.8.1

package/dist/wiki/ingest.js

@@ -0,0 +1,347 @@
+// ---------------------------------------------------------------------------
+// PKB ingestion pipeline — parse, extract entities, write wiki pages
+// ---------------------------------------------------------------------------
+import { createHash } from "node:crypto";
+import { exec } from "node:child_process";
+import { mkdirSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { getDb } from "../store/db.js";
+import { ensureWikiStructure, writeRawSource, assertPagePath } from "./fs.js";
+import { appendTimeline } from "./timeline.js";
+import { validateAndBackfillFrontmatter } from "./frontmatter.js";
+import { writePage, readPage } from "./fs.js";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("ingest");
+const execAsync = promisify(exec);
+// ---------------------------------------------------------------------------
+// Source ID
+// ---------------------------------------------------------------------------
+export function computeSourceId(sourceType, origin) {
+    return createHash("sha256").update(sourceType + origin).digest("hex");
+}
+// ---------------------------------------------------------------------------
+// Content parsers
+// ---------------------------------------------------------------------------
+export function assertSafeRemoteUrl(url) {
+    const parsedUrl = new URL(url);
+    if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+        throw new Error(`Only http/https URLs supported, got: ${parsedUrl.protocol}`);
+    }
+    const host = parsedUrl.hostname.toLowerCase();
+    const octets = host.split(".").map((part) => Number(part));
+    const isIpv4 = octets.length === 4 && octets.every((part) => Number.isInteger(part) && part >= 0 && part <= 255);
+    const isPrivateIpv4 = isIpv4 && (octets[0] === 10
+        || (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31)
+        || (octets[0] === 192 && octets[1] === 168));
+    if (host === "localhost" || host === "127.0.0.1" || host === "::1"
+        || isPrivateIpv4
+        || host.startsWith("169.254.") || host === "metadata.google.internal") {
+        throw new Error("Cannot fetch internal/private URLs.");
+    }
+    return parsedUrl;
+}
+export function createEntityPageContent({ pageTitle, pageSummary, entityType, updatedAt, }) {
+    return `---\ntitle: ${pageTitle}\nsummary: ${pageSummary}\nupdated: ${updatedAt}\ntags: []\nmetadata:\n  entity_type: ${entityType}\n---\n\n# ${pageTitle}\n\n## Summary\n\n${pageSummary}\n\n## Timeline\n`;
+}
+async function parseUrl(url) {
+    const parsedUrl = assertSafeRemoteUrl(url);
+    const res = await fetch(url, { headers: { "User-Agent": "Chapterhouse/1.0 PKB-Ingest" } });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status} ${res.statusText} fetching ${url}`);
+    const html = await res.text();
+    // Try @mozilla/readability if available
+    let text;
+    let title = parsedUrl.hostname;
+    try {
+        const { Readability } = await import("@mozilla/readability");
+        const { JSDOM } = await import("jsdom");
+        const dom = new JSDOM(html, { url });
+        const reader = new Readability(dom.window.document);
+        const article = reader.parse();
+        if (article) {
+            text = article.textContent;
+            title = article.title || title;
+        }
+        else {
+            text = stripHtml(html);
+        }
+    }
+    catch {
+        text = stripHtml(html);
+        // Try to extract title from <title> tag
+        const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+        if (titleMatch)
+            title = titleMatch[1].trim();
+    }
+    if (text.length > 50_000)
+        text = text.slice(0, 50_000);
+    return { text, title };
+}
+function stripHtml(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, "")
+        .replace(/<style[\s\S]*?<\/style>/gi, "")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/\s{2,}/g, " ")
+        .trim()
+        .slice(0, 10_000);
+}
+async function parsePdf(filePath) {
+    try {
+        const pdfParse = await import("pdf-parse");
+        const buf = readFileSync(filePath);
+        const data = await pdfParse.default(buf);
+        return { text: data.text.slice(0, 50_000), title: filePath.replace(/.*\//, "").replace(/\.pdf$/i, "") };
+    }
+    catch {
+        throw new Error("PDF ingestion requires pdf-parse: npm install pdf-parse");
+    }
+}
+async function parseRepo(repoUrl) {
+    const tmpDir = join(process.cwd(), ".test-work", `repo-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+        await execAsync(`git clone --depth 1 ${JSON.stringify(repoUrl)} ${JSON.stringify(tmpDir)}`, { timeout: 60_000 });
+        const parts = [];
+        // README
+        for (const name of ["README.md", "README.rst", "README.txt", "README"]) {
+            const p = join(tmpDir, name);
+            if (existsSync(p)) {
+                parts.push(`## README\n\n${readFileSync(p, "utf-8").slice(0, 10_000)}`);
+                break;
+            }
+        }
+        // package.json / Cargo.toml / go.mod
+        for (const name of ["package.json", "Cargo.toml", "go.mod"]) {
+            const p = join(tmpDir, name);
+            if (existsSync(p)) {
+                parts.push(`## ${name}\n\n\`\`\`\n${readFileSync(p, "utf-8").slice(0, 2_000)}\n\`\`\``);
+            }
+        }
+        const { stdout } = await execAsync(`ls -la ${JSON.stringify(tmpDir)}`);
+        parts.push(`## Directory listing\n\n\`\`\`\n${stdout}\n\`\`\``);
+        const title = repoUrl.replace(/.*\//, "").replace(/\.git$/, "");
+        return { text: parts.join("\n\n"), title };
+    }
+    finally {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+}
+// ---------------------------------------------------------------------------
+// Entity extraction via LLM
+// ---------------------------------------------------------------------------
+async function extractEntities(text, topic) {
+    // Skip entity extraction if no auth token is configured
+    const { config } = await import("../config.js");
+    const token = config.copilotAuthToken || process.env.COPILOT_TOKEN || process.env.GITHUB_TOKEN;
+    if (!token) {
+        log.debug("No Copilot auth token configured, skipping entity extraction");
+        return { entities: [], relationships: [] };
+    }
+    const topicHint = topic ? ` Focus especially on entities related to: ${topic}.` : "";
+    const systemPrompt = "Extract entities and relationships from this content. Return JSON only, no other text: " +
+        `{ "entities": [{"name": string, "type": string, "description": string}], ` +
+        `"relationships": [{"from": string, "to": string, "type": string}] }`;
+    const userMessage = `${systemPrompt}${topicHint}\n\n---\n\n${text.slice(0, 8_000)}`;
+    try {
+        const { CopilotClient, approveAll } = await import("@github/copilot-sdk");
+        // Use a one-shot client (autoRestart: false) so it doesn't keep the process alive
+        const client = new CopilotClient({
+            autoStart: true,
+            autoRestart: false,
+            gitHubToken: token,
+        });
+        await client.start();
+        try {
+            const session = await client.createSession({
+                model: "claude-haiku-4.5",
+                tools: [],
+                onPermissionRequest: approveAll,
+            });
+            try {
+                const result = await session.sendAndWait({ prompt: userMessage }, 30_000);
+                const rawText = typeof result === "string" ? result : JSON.stringify(result);
+                // Extract JSON from the response (may be wrapped in markdown code blocks)
+                const jsonMatch = rawText.match(/\{[\s\S]*\}/);
+                if (!jsonMatch)
+                    return { entities: [], relationships: [] };
+                const parsed = JSON.parse(jsonMatch[0]);
+                return {
+                    entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+                    relationships: Array.isArray(parsed.relationships) ? parsed.relationships : [],
+                };
+            }
+            finally {
+                try {
+                    session.destroy();
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        finally {
+            try {
+                await client.stop();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : err }, "Entity extraction LLM call failed, skipping");
+        return { entities: [], relationships: [] };
+    }
+}
+// ---------------------------------------------------------------------------
+// Slug helper
+// ---------------------------------------------------------------------------
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64) || "unknown";
+}
+// ---------------------------------------------------------------------------
+// Main ingest function
+// ---------------------------------------------------------------------------
+export async function ingestSource(source, type, topic, session) {
+    ensureWikiStructure();
+    const db = getDb();
+    const origin = type === "text" ? source.slice(0, 200) : source;
+    const sourceId = computeSourceId(type, origin);
+    // Idempotency check
+    const existing = db.prepare(`SELECT id, pages_updated FROM wiki_sources WHERE id = ?`).get(sourceId);
+    if (existing) {
+        log.info({ sourceId, type, origin }, "Source already ingested, skipping");
+        const pagesUpdated = JSON.parse(existing.pages_updated || "[]");
+        return {
+            source_id: sourceId,
+            pages_created: [],
+            pages_updated: pagesUpdated,
+            entities: [],
+            already_existed: true,
+        };
+    }
+    // Parse content
+    let parsedText;
+    let title;
+    switch (type) {
+        case "url": {
+            const r = await parseUrl(source);
+            parsedText = r.text;
+            title = r.title;
+            break;
+        }
+        case "pdf": {
+            const r = await parsePdf(source);
+            parsedText = r.text;
+            title = r.title;
+            break;
+        }
+        case "repo": {
+            const r = await parseRepo(source);
+            parsedText = r.text;
+            title = r.title;
+            break;
+        }
+        case "text":
+        default:
+            parsedText = source;
+            title = topic ?? `text-${sourceId.slice(0, 8)}`;
+            break;
+    }
+    // Save raw source archive
+    const rawFileName = `${sourceId.slice(0, 16)}.md`;
+    writeRawSource(rawFileName, parsedText);
+    // Persist to wiki_sources
+    const ingestedAt = new Date().toISOString();
+    db.prepare(`
+    INSERT INTO wiki_sources (id, source_type, origin, title, ingested_at, raw_path, parsed_content, pages_updated, session_id, session_name)
+    VALUES (?, ?, ?, ?, ?, ?, ?, '[]', ?, ?)
+  `).run(sourceId, type, origin, title, ingestedAt, `sources/${rawFileName}`, parsedText.slice(0, 100_000), session?.sessionId ?? null, session?.sessionName ?? null);
+    // Extract entities
+    const extraction = await extractEntities(parsedText, topic);
+    const pagesCreated = [];
+    const pagesUpdated = [];
+    const entitySummaries = [];
+    for (const entity of extraction.entities) {
+        if (!entity.name || !entity.type)
+            continue;
+        const entitySlug = slugify(entity.name);
+        const typeLower = entity.type.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+        const pagePath = `pages/${typeLower}/${entitySlug}/index.md`;
+        // Validate path is safe
+        try {
+            assertPagePath(pagePath);
+        }
+        catch {
+            // Use topics fallback for unknown entity types
+            const fallbackPath = `pages/topics/${entitySlug}/index.md`;
+            try {
+                assertPagePath(fallbackPath);
+            }
+            catch {
+                continue;
+            }
+        }
+        const safePagePath = (() => {
+            try {
+                assertPagePath(pagePath);
+                return pagePath;
+            }
+            catch {
+                return `pages/topics/${entitySlug}/index.md`;
+            }
+        })();
+        const existed = readPage(safePagePath) !== undefined;
+        const timelineEntry = `Source ingested: ${title}\n\n${entity.description || entity.name}`;
+        if (!existed) {
+            const pageTitle = entity.name;
+            const pageSummary = (entity.description || entity.name).slice(0, 180).replace(/\n/g, " ");
+            const pageContent = createEntityPageContent({
+                pageTitle,
+                pageSummary,
+                entityType: typeLower,
+                updatedAt: ingestedAt.slice(0, 10),
+            });
+            const { content: backfilled } = validateAndBackfillFrontmatter(safePagePath, pageContent);
+            writePage(safePagePath, backfilled);
+            pagesCreated.push(safePagePath);
+        }
+        else {
+            pagesUpdated.push(safePagePath);
+        }
+        appendTimeline(safePagePath, timelineEntry);
+        entitySummaries.push({ name: entity.name, type: entity.type, path: safePagePath });
+    }
+    // Update wiki_sources with pages_updated
+    const allPages = [...new Set([...pagesCreated, ...pagesUpdated])];
+    db.prepare(`UPDATE wiki_sources SET pages_updated = ? WHERE id = ?`).run(JSON.stringify(allPages), sourceId);
+    return {
+        source_id: sourceId,
+        pages_created: pagesCreated,
+        pages_updated: pagesUpdated,
+        entities: entitySummaries,
+        already_existed: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Type auto-detection
+// ---------------------------------------------------------------------------
+export function detectSourceType(source) {
+    const trimmed = source.trim();
+    if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+        if (trimmed.endsWith(".pdf"))
+            return "pdf";
+        if (trimmed.includes("github.com") || trimmed.includes("gitlab.com") || trimmed.endsWith(".git"))
+            return "repo";
+        return "url";
+    }
+    if (trimmed.endsWith(".pdf") && !trimmed.includes(" "))
+        return "pdf";
+    return "text";
+}
+//# sourceMappingURL=ingest.js.map

package/dist/wiki/ingest.test.js

@@ -0,0 +1,111 @@
+// ---------------------------------------------------------------------------
+// Ingestion pipeline tests — ingestSource
+// Sandbox: single CHAPTERHOUSE_HOME per file to avoid module-singleton confusion
+// ---------------------------------------------------------------------------
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+// Single sandbox shared across all tests in this file
+let SANDBOX;
+let mods;
+test.before(async () => {
+    mkdirSync(join(process.cwd(), ".test-work"), { recursive: true });
+    SANDBOX = mkdtempSync(join(process.cwd(), ".test-work", "ingest-"));
+    process.env.CHAPTERHOUSE_HOME = SANDBOX;
+    const nonce = `${Date.now()}-${Math.random()}`;
+    const ingestMod = await import(new URL(`./ingest.js?c=${nonce}`, import.meta.url).href);
+    const wikiFs = await import(new URL(`./fs.js?c=${nonce}`, import.meta.url).href);
+    const dbMod = await import(new URL(`../store/db.js?c=${nonce}`, import.meta.url).href);
+    mods = { ingestMod, wikiFs, dbMod };
+    mods.wikiFs.ensureWikiStructure();
+});
+test.after(() => {
+    try {
+        rmSync(SANDBOX, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+});
+test("ingestSource(text) creates wiki_sources record", async () => {
+    const text = `Source-A: Alice is a senior engineer at Acme Corp. timestamp=${Date.now()}`;
+    const result = await mods.ingestMod.ingestSource(text, "text", "people");
+    assert.ok(result.source_id, "Should return a source_id");
+    assert.equal(result.already_existed, false, "Should not already exist on first call");
+    const db = mods.dbMod.getDb();
+    const row = db.prepare(`SELECT * FROM wiki_sources WHERE id = ?`).get(result.source_id);
+    assert.ok(row, "Should be persisted in wiki_sources");
+    assert.equal(row.source_type, "text");
+});
+test("ingestSource(text) saves raw source file", async () => {
+    const text = `Source-B: Bob leads the platform engineering team at TechCo. timestamp=${Date.now()}`;
+    const result = await mods.ingestMod.ingestSource(text, "text");
+    const sources = mods.wikiFs.listSources();
+    assert.ok(sources.length > 0, "Should have saved a raw source file");
+    assert.ok(sources.some((s) => s.startsWith(result.source_id.slice(0, 16))), "Source file should be named with source_id prefix");
+});
+test("ingestSource duplicate ingestion returns already_existed=true", async () => {
+    const text = `Source-C: Carol is a product manager at StartupXYZ. timestamp=${Date.now()}`;
+    const first = await mods.ingestMod.ingestSource(text, "text");
+    assert.equal(first.already_existed, false, "First call should not be a duplicate");
+    const second = await mods.ingestMod.ingestSource(text, "text");
+    assert.equal(second.already_existed, true, "Second ingestion should be idempotent");
+    assert.equal(second.source_id, first.source_id, "Should return same source_id");
+    const db = mods.dbMod.getDb();
+    const count = db.prepare(`SELECT COUNT(*) as c FROM wiki_sources WHERE id = ?`).get(first.source_id).c;
+    assert.equal(count, 1, "Should only have one row in wiki_sources");
+});
+test("computeSourceId is deterministic and type-scoped", () => {
+    const id1 = mods.ingestMod.computeSourceId("text", "hello world");
+    const id2 = mods.ingestMod.computeSourceId("text", "hello world");
+    assert.equal(id1, id2, "Same input should give same id");
+    const id3 = mods.ingestMod.computeSourceId("url", "hello world");
+    assert.notEqual(id1, id3, "Different types should give different ids");
+});
+test("detectSourceType identifies URLs, repos, and text", () => {
+    assert.equal(mods.ingestMod.detectSourceType("https://tokio.rs"), "url");
+    assert.equal(mods.ingestMod.detectSourceType("http://example.com"), "url");
+    assert.equal(mods.ingestMod.detectSourceType("https://github.com/user/repo"), "repo");
+    assert.equal(mods.ingestMod.detectSourceType("some plain text content"), "text");
+    assert.equal(mods.ingestMod.detectSourceType(""), "text");
+});
+test("assertSafeRemoteUrl blocks all RFC 1918 private ranges", () => {
+    assert.throws(() => mods.ingestMod.assertSafeRemoteUrl("http://10.1.2.3"), /Cannot fetch internal\/private URLs\./);
+    assert.throws(() => mods.ingestMod.assertSafeRemoteUrl("http://172.16.5.4"), /Cannot fetch internal\/private URLs\./);
+    assert.throws(() => mods.ingestMod.assertSafeRemoteUrl("http://172.31.255.255"), /Cannot fetch internal\/private URLs\./);
+    assert.throws(() => mods.ingestMod.assertSafeRemoteUrl("http://192.168.1.9"), /Cannot fetch internal\/private URLs\./);
+});
+test("createEntityPageContent uses the Summary and Timeline headings", () => {
+    const content = mods.ingestMod.createEntityPageContent({
+        pageTitle: "Alice Example",
+        pageSummary: "Senior engineer at Acme.",
+        entityType: "people",
+        updatedAt: "2026-05-15",
+    });
+    assert.match(content, /## Summary/);
+    assert.match(content, /## Timeline/);
+    assert.doesNotMatch(content, /## Compiled Truth/);
+});
+test("ingestSource stores optional research session metadata in wiki_sources", async () => {
+    const text = `Source-D: Research session metadata should persist. timestamp=${Date.now()}`;
+    const result = await mods.ingestMod.ingestSource(text, "text", "topics", {
+        sessionId: "compiler-research",
+        sessionName: "Compiler research",
+    });
+    const db = mods.dbMod.getDb();
+    const row = db.prepare(`SELECT session_id, session_name FROM wiki_sources WHERE id = ?`).get(result.source_id);
+    assert.deepEqual(row, {
+        session_id: "compiler-research",
+        session_name: "Compiler research",
+    });
+});
+// URL/PDF/repo tests are skipped if connectivity or dependencies are unavailable
+test.skip("ingestSource(url) fetches and parses content — requires network", async () => {
+    // Integration test: run manually with network access
+});
+test.skip("ingestSource(pdf) parses PDF — requires pdf-parse", async () => {
+    // Integration test: run manually with pdf-parse installed
+});
+test.skip("ingestSource(repo) clones and summarises repo — requires network + git", async () => {
+    // Integration test: run manually
+});
+//# sourceMappingURL=ingest.test.js.map

package/dist/wiki/links.js

@@ -0,0 +1,151 @@
+// ---------------------------------------------------------------------------
+// Wiki entity graph — link extraction and graph traversal
+// ---------------------------------------------------------------------------
+import { getDb } from "../store/db.js";
+import { readPage, pageExists } from "./fs.js";
+import { parseWikiFrontmatter } from "./frontmatter.js";
+import { normalizeWikiPath } from "./path-utils.js";
+const RELATIONSHIP_PATTERNS = [
+    { regex: /\bimplements\s+([A-Za-z0-9][^\n.,;:!?]{1,60})/gi, linkType: "implements" },
+    { regex: /\bsupersedes\s+([A-Za-z0-9][^\n.,;:!?]{1,60})/gi, linkType: "supersedes" },
+    { regex: /\bmember\s+of\s+([A-Za-z0-9][^\n.,;:!?]{1,60})/gi, linkType: "member_of" },
+    { regex: /\bworks?\s+at\s+([A-Za-z0-9][^\n.,;:!?]{1,60})/gi, linkType: "member_of" },
+    { regex: /\bworks\s+on\s+([A-Za-z0-9][^\n.,;:!?]{1,60})/gi, linkType: "works_on" },
+    { regex: /\bdecided\s+by\s+([A-Za-z0-9][^\n.,;:!?]{1,60})/gi, linkType: "decided_by" },
+    { regex: /\bdepends\s+on\s+([A-Za-z0-9][^\n.,;:!?]{1,60})/gi, linkType: "depends_on" },
+];
+function nameToSlug(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "");
+}
+function wikiLinkToPath(name) {
+    return `pages/${nameToSlug(name)}/index.md`;
+}
+function tagToTopicPath(tag) {
+    return `pages/topics/${nameToSlug(tag)}/index.md`;
+}
+/** Extract typed links from a page. Returns deduplicated WikiLink array. */
+export function extractLinks(pagePath) {
+    const normalizedPath = normalizeWikiPath(pagePath);
+    const content = readPage(normalizedPath);
+    if (!content)
+        return [];
+    const { parsed: fm, body } = parseWikiFrontmatter(content);
+    const links = [];
+    const seen = new Set();
+    const extractedAt = new Date().toISOString();
+    function addLink(toPage, linkType) {
+        const normalized = normalizeWikiPath(toPage);
+        if (!normalized || normalized === normalizedPath)
+            return;
+        const key = `${normalized}:${linkType}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        links.push({ from_page: normalizedPath, to_page: normalized, link_type: linkType, extracted_at: extractedAt });
+    }
+    // 1. [[Page Name]] wiki links
+    const wikiLinkRe = /\[\[([^\]]+)\]\]/g;
+    let m;
+    while ((m = wikiLinkRe.exec(body)) !== null) {
+        const target = wikiLinkToPath(m[1].trim());
+        addLink(target, "references");
+    }
+    // 2. Frontmatter `related` array
+    for (const rel of fm.related ?? []) {
+        if (typeof rel === "string" && rel.trim()) {
+            addLink(normalizeWikiPath(rel.trim()), "references");
+        }
+    }
+    // 3. Frontmatter `tags` → topic pages (only if target page exists on disk)
+    for (const tag of fm.tags ?? []) {
+        if (typeof tag === "string" && tag.trim()) {
+            const target = tagToTopicPath(tag.trim());
+            if (pageExists(target)) {
+                addLink(target, "references");
+            }
+        }
+    }
+    // 4. Relationship statements in body text
+    for (const { regex, linkType } of RELATIONSHIP_PATTERNS) {
+        regex.lastIndex = 0;
+        while ((m = regex.exec(body)) !== null) {
+            const rawTarget = nameToSlug(m[1].trim());
+            if (rawTarget) {
+                addLink(`pages/${rawTarget}/index.md`, linkType);
+            }
+        }
+    }
+    return links;
+}
+/** Re-extract links for a page and sync to wiki_links table. */
+export function updateLinks(pagePath) {
+    const normalizedPath = normalizeWikiPath(pagePath);
+    const db = getDb();
+    const existing = db.prepare(`SELECT COUNT(*) as c FROM wiki_links WHERE from_page = ?`).get(normalizedPath);
+    const removedCount = existing.c;
+    const newLinks = extractLinks(normalizedPath);
+    db.transaction(() => {
+        db.prepare(`DELETE FROM wiki_links WHERE from_page = ?`).run(normalizedPath);
+        const insert = db.prepare(`
+      INSERT OR IGNORE INTO wiki_links (from_page, to_page, link_type, extracted_at)
+      VALUES (?, ?, ?, ?)
+    `);
+        for (const link of newLinks) {
+            insert.run(link.from_page, link.to_page, link.link_type, link.extracted_at);
+        }
+    })();
+    return { added: newLinks.length, removed: removedCount };
+}
+/**
+ * Walk the entity graph from a starting page.
+ * Default depth 1, max depth 3. Returns flat list sorted by depth then page.
+ */
+export function traverse(pagePath, linkType, depth = 1) {
+    const MAX_DEPTH = 3;
+    const effectiveDepth = Math.min(Math.max(depth, 1), MAX_DEPTH);
+    const normalizedPath = normalizeWikiPath(pagePath);
+    const db = getDb();
+    const results = [];
+    const visited = new Set([normalizedPath]);
+    const queue = [{ page: normalizedPath, depth: 0 }];
+    while (queue.length > 0) {
+        const { page: currentPage, depth: currentDepth } = queue.shift();
+        if (currentDepth >= effectiveDepth)
+            continue;
+        const outbound = (linkType
+            ? db.prepare(`SELECT to_page, link_type FROM wiki_links WHERE from_page = ? AND link_type = ?`).all(currentPage, linkType)
+            : db.prepare(`SELECT to_page, link_type FROM wiki_links WHERE from_page = ?`).all(currentPage));
+        for (const row of outbound) {
+            if (!visited.has(row.to_page)) {
+                visited.add(row.to_page);
+                results.push({ page: row.to_page, link_type: row.link_type, direction: "outbound", depth: currentDepth + 1 });
+                if (currentDepth + 1 < effectiveDepth) {
+                    queue.push({ page: row.to_page, depth: currentDepth + 1 });
+                }
+            }
+        }
+        const inbound = (linkType
+            ? db.prepare(`SELECT from_page, link_type FROM wiki_links WHERE to_page = ? AND link_type = ?`).all(currentPage, linkType)
+            : db.prepare(`SELECT from_page, link_type FROM wiki_links WHERE to_page = ?`).all(currentPage));
+        for (const row of inbound) {
+            if (!visited.has(row.from_page)) {
+                visited.add(row.from_page);
+                results.push({ page: row.from_page, link_type: row.link_type, direction: "inbound", depth: currentDepth + 1 });
+                if (currentDepth + 1 < effectiveDepth) {
+                    queue.push({ page: row.from_page, depth: currentDepth + 1 });
+                }
+            }
+        }
+    }
+    results.sort((a, b) => {
+        if (a.depth !== b.depth)
+            return a.depth - b.depth;
+        return a.page.localeCompare(b.page);
+    });
+    return results;
+}
+//# sourceMappingURL=links.js.map