chapterhouse 0.1.1

package/dist/wiki/fs.js

@@ -0,0 +1,195 @@
+// ---------------------------------------------------------------------------
+// Wiki file system primitives
+// ---------------------------------------------------------------------------
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync, statSync, renameSync, openSync, fsyncSync, closeSync } from "fs";
+import { join, dirname, relative, resolve, sep } from "path";
+import { WIKI_DIR, WIKI_PAGES_DIR, WIKI_SOURCES_DIR } from "../paths.js";
+import { normalizeWikiPath } from "./path-utils.js";
+const INDEX_PATH = join(WIKI_DIR, "index.md");
+const LOG_PATH = join(WIKI_DIR, "log.md");
+/**
+ * Write a file atomically: write to a temp file in the same directory, fsync,
+ * then rename over the destination. Prevents partial writes on crash and
+ * gives readers an all-or-nothing view.
+ */
+export function writeFileAtomic(fullPath, content) {
+    mkdirSync(dirname(fullPath), { recursive: true });
+    const tmp = `${fullPath}.${process.pid}.${Date.now()}.tmp`;
+    const fd = openSync(tmp, "w");
+    try {
+        writeFileSync(fd, content, "utf-8");
+        try {
+            fsyncSync(fd);
+        }
+        catch { /* fsync may fail on some FSes; non-fatal */ }
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, fullPath);
+}
+/** Throw if the given relative path is not safely under pages/. Used by mutation tools. */
+export function assertPagePath(relativePath) {
+    if (!relativePath || typeof relativePath !== "string") {
+        throw new Error("Wiki path is required");
+    }
+    const normalizedPath = normalizeWikiPath(relativePath);
+    if (normalizedPath.includes("\0") || normalizedPath.includes("..")) {
+        throw new Error(`Refused unsafe wiki path: ${relativePath}`);
+    }
+    if (!normalizedPath.startsWith("pages/")) {
+        throw new Error(`Refused: only pages under pages/ may be modified by tools. Got: ${relativePath}`);
+    }
+    if (!normalizedPath.endsWith(".md")) {
+        throw new Error(`Wiki page paths must end in .md: ${relativePath}`);
+    }
+    // resolvePath also enforces the wiki-root containment check.
+    resolvePath(normalizedPath);
+}
+function getInitialIndex() {
+    return `# Wiki Index
+
+_Max's knowledge base. This file is maintained automatically._
+
+Last updated: ${new Date().toISOString().slice(0, 10)}
+
+## Pages
+
+_(No pages yet.)_
+`;
+}
+const INITIAL_LOG = `# Wiki Log
+
+_Chronological record of wiki operations._
+
+`;
+/**
+ * Create the wiki directory structure if it doesn't exist.
+ * Returns true if the wiki was just created (first run).
+ */
+export function ensureWikiStructure() {
+    const isNew = !existsSync(WIKI_DIR);
+    mkdirSync(WIKI_PAGES_DIR, { recursive: true });
+    mkdirSync(WIKI_SOURCES_DIR, { recursive: true });
+    if (!existsSync(INDEX_PATH)) {
+        writeFileAtomic(INDEX_PATH, getInitialIndex());
+    }
+    if (!existsSync(LOG_PATH)) {
+        writeFileAtomic(LOG_PATH, INITIAL_LOG);
+    }
+    return isNew;
+}
+/** Read a wiki page by path relative to the wiki root. Returns undefined if not found. */
+export function readPage(relativePath) {
+    const fullPath = resolvePath(relativePath);
+    if (!existsSync(fullPath))
+        return undefined;
+    return readFileSync(fullPath, "utf-8");
+}
+/** Write a wiki page atomically. Creates parent directories automatically. */
+export function writePage(relativePath, content) {
+    const fullPath = resolvePath(relativePath);
+    writeFileAtomic(fullPath, content);
+}
+/** Delete a wiki page. Returns true if the file existed and was removed. */
+export function deletePage(relativePath) {
+    const fullPath = resolvePath(relativePath);
+    if (!existsSync(fullPath))
+        return false;
+    unlinkSync(fullPath);
+    return true;
+}
+/** Check if a wiki page exists. */
+export function pageExists(relativePath) {
+    return existsSync(resolvePath(relativePath));
+}
+/** List all .md files under pages/, returning paths relative to the wiki root. */
+export function listPages() {
+    if (!existsSync(WIKI_PAGES_DIR))
+        return [];
+    return walkDir(WIKI_PAGES_DIR)
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => normalizeWikiPath(relative(WIKI_DIR, f)));
+}
+/** Save a raw source document (immutable). */
+export function writeRawSource(name, content) {
+    const safeName = name.replace(/[^a-zA-Z0-9._/-]/g, "-").replace(/\.\.+/g, "-");
+    const fullPath = resolve(WIKI_SOURCES_DIR, safeName);
+    if (!fullPath.startsWith(WIKI_SOURCES_DIR + sep)) {
+        throw new Error(`Source path escapes sources dir: ${name}`);
+    }
+    writeFileAtomic(fullPath, content);
+}
+/** Read a raw source document. */
+export function readRawSource(name) {
+    const safeName = name.replace(/[^a-zA-Z0-9._-]/g, "-");
+    const fullPath = join(WIKI_SOURCES_DIR, safeName);
+    if (!existsSync(fullPath))
+        return undefined;
+    return readFileSync(fullPath, "utf-8");
+}
+/** List all source files. */
+export function listSources() {
+    if (!existsSync(WIKI_SOURCES_DIR))
+        return [];
+    return readdirSync(WIKI_SOURCES_DIR).filter((f) => {
+        const full = join(WIKI_SOURCES_DIR, f);
+        return statSync(full).isFile();
+    });
+}
+/** Read index.md raw content. */
+export function readIndexFile() {
+    ensureWikiStructure();
+    return readFileSync(INDEX_PATH, "utf-8");
+}
+/** Write index.md content atomically. */
+export function writeIndexFile(content) {
+    writeFileAtomic(INDEX_PATH, content);
+}
+/** Read log.md raw content. */
+export function readLogFile() {
+    ensureWikiStructure();
+    return readFileSync(LOG_PATH, "utf-8");
+}
+/** Write log.md content atomically. */
+export function writeLogFile(content) {
+    writeFileAtomic(LOG_PATH, content);
+}
+/** Get the full wiki directory path (for external tools that need it). */
+export function getWikiDir() {
+    return WIKI_DIR;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function resolvePath(relativePath) {
+    const normalizedPath = normalizeWikiPath(relativePath);
+    let base;
+    if (normalizedPath.startsWith("pages/") || normalizedPath.startsWith("sources/") ||
+        normalizedPath === "index.md" || normalizedPath === "log.md") {
+        base = WIKI_DIR;
+    }
+    else {
+        base = WIKI_PAGES_DIR;
+    }
+    const resolved = resolve(base, normalizedPath);
+    // Prevent path traversal outside the wiki directory
+    if (!resolved.startsWith(WIKI_DIR + sep) && resolved !== WIKI_DIR) {
+        throw new Error(`Path escapes wiki directory: ${relativePath}`);
+    }
+    return resolved;
+}
+function walkDir(dir) {
+    const results = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkDir(full));
+        }
+        else {
+            results.push(full);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=fs.js.map

package/dist/wiki/fs.test.js

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `wiki-fs-${process.pid}`);
+const actualHome = join(sandboxRoot, ".chapterhouse");
+const wikiDir = join(actualHome, "wiki");
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+async function loadFsModule() {
+    return await import(new URL(`./fs.js?case=${Date.now()}-${Math.random()}`, import.meta.url).href);
+}
+test.after(() => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("wiki fs creates the wiki structure and supports page CRUD", async () => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    const wiki = await loadFsModule();
+    assert.equal(wiki.ensureWikiStructure(), true);
+    assert.equal(wiki.ensureWikiStructure(), false);
+    assert.equal(existsSync(join(wikiDir, "index.md")), true);
+    assert.equal(existsSync(join(wikiDir, "log.md")), true);
+    wiki.writePage("pages/shared/runbooks/deploy.md", "# Deploy\n");
+    assert.equal(wiki.pageExists("pages/shared/runbooks/deploy.md"), true);
+    assert.equal(wiki.readPage("pages/shared/runbooks/deploy.md"), "# Deploy\n");
+    assert.deepEqual(wiki.listPages(), ["pages/shared/runbooks/deploy.md"]);
+    assert.equal(wiki.deletePage("pages/shared/runbooks/deploy.md"), true);
+    assert.equal(wiki.deletePage("pages/shared/runbooks/deploy.md"), false);
+    assert.equal(wiki.readPage("pages/shared/runbooks/deploy.md"), undefined);
+});
+test("wiki fs rejects unsafe page paths", async () => {
+    const wiki = await loadFsModule();
+    assert.doesNotThrow(() => wiki.assertPagePath("pages/shared/runbooks/deploy.md"));
+    assert.throws(() => wiki.assertPagePath("../secrets.md"), /unsafe wiki path|escapes wiki directory/);
+    assert.throws(() => wiki.assertPagePath("sources/raw.md"), /only pages under pages\//);
+    assert.throws(() => wiki.assertPagePath("pages/shared/runbooks/deploy.txt"), /must end in \.md/);
+});
+//# sourceMappingURL=fs.test.js.map

package/dist/wiki/index-manager.js

@@ -0,0 +1,359 @@
+// ---------------------------------------------------------------------------
+// Wiki index.md manager — parse, update, and search the page catalog
+// ---------------------------------------------------------------------------
+import { existsSync, statSync } from "fs";
+import { join } from "path";
+import { WIKI_DIR } from "../paths.js";
+import { readIndexFile, writeIndexFile, listPages, readPage } from "./fs.js";
+import { normalizeWikiPath } from "./path-utils.js";
+const INDEX_PATH = join(WIKI_DIR, "index.md");
+// mtime-based cache so per-message context injection doesn't re-parse on every turn.
+let cache;
+function invalidateCache() {
+    cache = undefined;
+}
+/**
+ * Parse index.md into structured entries.
+ * Expected format (new):
+ *   ## Section Name
+ *   - [Title](path) — Summary text | tags: tag1, tag2 | updated: 2026-04-17
+ * Also supports legacy format without tags/updated.
+ */
+export function parseIndex() {
+    let mtimeMs = 0, size = 0;
+    if (existsSync(INDEX_PATH)) {
+        const st = statSync(INDEX_PATH);
+        mtimeMs = st.mtimeMs;
+        size = st.size;
+        if (cache && cache.mtimeMs === mtimeMs && cache.size === size) {
+            return cache.entries;
+        }
+    }
+    const content = readIndexFile();
+    const entries = [];
+    let currentSection = "Uncategorized";
+    for (const line of content.split("\n")) {
+        // Section headers
+        const sectionMatch = line.match(/^##\s+(.+)/);
+        if (sectionMatch) {
+            currentSection = sectionMatch[1].trim();
+            continue;
+        }
+        // Entry lines: - [Title](path) — Summary | tags: t1, t2 | updated: YYYY-MM-DD
+        const entryMatch = line.match(/^-\s+\[(.+?)\]\((.+?)\)\s*[—–-]\s*(.+)/);
+        if (entryMatch) {
+            const rawSummary = entryMatch[3].trim();
+            // Parse optional | tags: ... | updated: ... suffixes
+            let summary = rawSummary;
+            let tags = [];
+            let updated = "";
+            const tagsMatch = rawSummary.match(/\|\s*tags:\s*([^|]+)/);
+            if (tagsMatch) {
+                tags = tagsMatch[1].split(",").map((t) => t.trim()).filter(Boolean);
+                summary = summary.replace(tagsMatch[0], "").trim();
+            }
+            const updatedMatch = rawSummary.match(/\|\s*updated:\s*(\S+)/);
+            if (updatedMatch) {
+                updated = updatedMatch[1].trim();
+                summary = summary.replace(updatedMatch[0], "").trim();
+            }
+            // Clean trailing pipe if any
+            summary = summary.replace(/\|?\s*$/, "").trim();
+            entries.push({
+                title: entryMatch[1].trim(),
+                path: normalizeWikiPath(entryMatch[2].trim()),
+                summary,
+                section: currentSection,
+                tags: tags.length > 0 ? tags : undefined,
+                updated: updated || undefined,
+            });
+        }
+    }
+    // Self-heal: if index is empty/corrupted but pages exist on disk, rebuild from disk.
+    if (entries.length === 0) {
+        const pages = listPages();
+        if (pages.length > 0) {
+            const rebuilt = rebuildIndexFromPages();
+            cache = { mtimeMs, size, entries: rebuilt };
+            return rebuilt;
+        }
+    }
+    cache = { mtimeMs, size, entries };
+    return entries;
+}
+/** Parse YAML frontmatter (very simple — supports key: value and key: [a, b]). */
+function parseFrontmatter(content) {
+    const m = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!m)
+        return {};
+    const out = {};
+    for (const line of m[1].split("\n")) {
+        const idx = line.indexOf(":");
+        if (idx <= 0)
+            continue;
+        const key = line.slice(0, idx).trim();
+        let value = line.slice(idx + 1).trim();
+        if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
+            value = value.slice(1, -1).split(",").map((s) => s.trim()).filter(Boolean);
+        }
+        else if (typeof value === "string") {
+            value = value.replace(/^['"]|['"]$/g, "");
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/** Build (or refresh) an IndexEntry by reading the page from disk. */
+export function buildIndexEntryForPage(path, fallback) {
+    const normalizedPath = normalizeWikiPath(path);
+    const content = readPage(normalizedPath);
+    if (!content)
+        return undefined;
+    const fm = parseFrontmatter(content);
+    const title = (typeof fm.title === "string" && fm.title) || fallback?.title || basenameTitle(normalizedPath);
+    const tags = Array.isArray(fm.tags) ? fm.tags : (fallback?.tags ?? []);
+    const updated = (typeof fm.updated === "string" && fm.updated) || fallback?.updated;
+    // Summary heuristic: existing summary if provided, else first non-frontmatter
+    // non-heading content line trimmed to 160 chars.
+    let summary = fallback?.summary?.trim() || "";
+    if (!summary) {
+        const body = content.replace(/^---[\s\S]*?---\s*/, "");
+        for (const raw of body.split("\n")) {
+            const line = raw.trim();
+            if (!line || line.startsWith("#"))
+                continue;
+            summary = line.replace(/^[-*]\s+/, "").replace(/_\(\d{4}-\d{2}-\d{2}\)_$/, "").trim();
+            break;
+        }
+    }
+    if (summary.length > 160)
+        summary = summary.slice(0, 157) + "…";
+    return {
+        path: normalizedPath,
+        title,
+        summary: summary || title,
+        section: fallback?.section || "Knowledge",
+        tags: tags.length ? tags : undefined,
+        updated,
+    };
+}
+function basenameTitle(path) {
+    const normalizedPath = normalizeWikiPath(path);
+    const file = normalizedPath.split("/").pop() || normalizedPath;
+    const base = file.replace(/\.md$/, "");
+    return base.split(/[-_]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+/** Rebuild every index entry from on-disk pages. Preserves section if known. */
+export function rebuildIndexFromPages() {
+    const pages = listPages();
+    const previous = new Map();
+    // Try to keep section assignments by re-parsing the (possibly-corrupted) index without recursion.
+    try {
+        const raw = readIndexFile();
+        let section = "Knowledge";
+        for (const line of raw.split("\n")) {
+            const sm = line.match(/^##\s+(.+)/);
+            if (sm) {
+                section = sm[1].trim();
+                continue;
+            }
+            const em = line.match(/^-\s+\[.+?\]\((.+?)\)/);
+            if (em) {
+                const normalizedPath = normalizeWikiPath(em[1].trim());
+                previous.set(normalizedPath, { path: normalizedPath, title: "", summary: "", section });
+            }
+        }
+    }
+    catch { /* ignore */ }
+    const entries = [];
+    for (const p of pages) {
+        const entry = buildIndexEntryForPage(p, previous.get(p));
+        if (entry)
+            entries.push(entry);
+    }
+    // Write directly without recursion through addToIndex.
+    writeIndexInternal(entries);
+    invalidateCache();
+    return entries;
+}
+/** Regenerate index.md from a list of entries, grouped by section. */
+export function writeIndex(entries) {
+    writeIndexInternal(entries);
+    invalidateCache();
+}
+function writeIndexInternal(entries) {
+    const sections = new Map();
+    for (const entry of entries) {
+        const list = sections.get(entry.section) || [];
+        list.push(entry);
+        sections.set(entry.section, list);
+    }
+    const lines = [
+        "# Wiki Index",
+        "",
+        "_Max's knowledge base. This file is maintained automatically._",
+        "",
+        `Last updated: ${new Date().toISOString().slice(0, 10)}`,
+        "",
+    ];
+    for (const [section, items] of sections) {
+        lines.push(`## ${section}`, "");
+        for (const item of items) {
+            let line = `- [${item.title}](${item.path}) — ${item.summary}`;
+            if (item.tags?.length)
+                line += ` | tags: ${item.tags.join(", ")}`;
+            if (item.updated)
+                line += ` | updated: ${item.updated}`;
+            lines.push(line);
+        }
+        lines.push("");
+    }
+    if (sections.size === 0) {
+        lines.push("## Pages", "", "_(No pages yet.)_", "");
+    }
+    writeIndexFile(lines.join("\n"));
+}
+/** Add or update an entry in the index. Upserts by path. */
+export function addToIndex(entry) {
+    const normalizedEntry = { ...entry, path: normalizeWikiPath(entry.path) };
+    const entries = parseIndex();
+    const existing = entries.findIndex((e) => e.path === normalizedEntry.path);
+    if (existing >= 0) {
+        entries[existing] = normalizedEntry;
+    }
+    else {
+        entries.push(normalizedEntry);
+    }
+    writeIndex(entries);
+}
+/** Remove an entry from the index by path. */
+export function removeFromIndex(path) {
+    const normalizedPath = normalizeWikiPath(path);
+    const entries = parseIndex();
+    const filtered = entries.filter((e) => e.path !== normalizedPath);
+    if (filtered.length === entries.length)
+        return false;
+    writeIndex(filtered);
+    return true;
+}
+/**
+ * Search the index for entries matching a query.
+ * Matches against title, summary, section, path, and tags using keyword overlap.
+ * Boosts recently updated pages as a tiebreaker.
+ *
+ * - Short tokens (>=2 chars) are kept so acronyms like "AI"/"UI"/"JS" work.
+ * - Single-letter tokens are dropped to avoid noise.
+ * - Tag/title exact matches and prefix matches get a strong score boost.
+ * - Falls back to scanning page bodies when index search returns nothing.
+ */
+export function searchIndex(query, limit = 10) {
+    const entries = parseIndex();
+    if (entries.length === 0)
+        return [];
+    const queryWords = new Set(query.toLowerCase().split(/\s+/).filter((w) => w.length >= 2));
+    if (queryWords.size === 0) {
+        return entries.slice(0, limit);
+    }
+    const now = Date.now();
+    const scored = entries.map((entry) => {
+        const titleLc = entry.title.toLowerCase();
+        const summaryLc = entry.summary.toLowerCase();
+        const sectionLc = entry.section.toLowerCase();
+        const pathLc = entry.path.toLowerCase();
+        const tagSet = new Set((entry.tags || []).map((t) => t.toLowerCase()));
+        let hits = 0;
+        for (const q of queryWords) {
+            // Strongest signals: exact tag or exact title
+            if (tagSet.has(q)) {
+                hits += 5;
+                continue;
+            }
+            if (titleLc === q) {
+                hits += 5;
+                continue;
+            }
+            // Strong: title starts with token, or path basename equals token
+            if (titleLc.startsWith(q)) {
+                hits += 3;
+                continue;
+            }
+            const base = pathLc.split("/").pop()?.replace(/\.md$/, "") || "";
+            if (base === q) {
+                hits += 3;
+                continue;
+            }
+            // Medium: substring in title/summary/section
+            if (titleLc.includes(q) || summaryLc.includes(q) || sectionLc.includes(q)) {
+                hits += 2;
+                continue;
+            }
+            // Weak: substring in path or any tag
+            if (pathLc.includes(q)) {
+                hits += 1;
+                continue;
+            }
+            for (const tag of tagSet) {
+                if (tag.includes(q)) {
+                    hits += 1;
+                    break;
+                }
+            }
+        }
+        let recencyBoost = 0;
+        if (entry.updated) {
+            const daysSince = (now - new Date(entry.updated).getTime()) / (1000 * 60 * 60 * 24);
+            if (daysSince < 7)
+                recencyBoost = 0.5;
+            else if (daysSince < 30)
+                recencyBoost = 0.2;
+        }
+        return { entry, score: hits + recencyBoost };
+    })
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    if (scored.length > 0) {
+        return scored.map((s) => s.entry);
+    }
+    // Fallback: scan page bodies (bounded to avoid O(N*size) blowup).
+    const MAX_BODY_SCAN = 50;
+    const bodyHits = [];
+    for (const entry of entries.slice(0, MAX_BODY_SCAN)) {
+        const body = readPage(entry.path);
+        if (!body)
+            continue;
+        const bodyLc = body.toLowerCase();
+        let bodyScore = 0;
+        for (const q of queryWords) {
+            if (bodyLc.includes(q))
+                bodyScore += 1;
+        }
+        if (bodyScore > 0)
+            bodyHits.push({ entry, score: bodyScore });
+    }
+    bodyHits.sort((a, b) => b.score - a.score);
+    return bodyHits.slice(0, limit).map((s) => s.entry);
+}
+/** Get a compact text summary of the index for injection into context. */
+export function getIndexSummary() {
+    const entries = parseIndex();
+    if (entries.length === 0)
+        return "";
+    const sections = new Map();
+    for (const e of entries) {
+        const list = sections.get(e.section) || [];
+        let item = `${e.title}: ${e.summary}`;
+        if (e.tags?.length)
+            item += ` [${e.tags.join(", ")}]`;
+        if (e.updated)
+            item += ` (${e.updated})`;
+        list.push(item);
+        sections.set(e.section, list);
+    }
+    const parts = [];
+    for (const [section, items] of sections) {
+        parts.push(`**${section}**: ${items.join("; ")}`);
+    }
+    return parts.join("\n");
+}
+//# sourceMappingURL=index-manager.js.map