packmind 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,112 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { findRoot } from "../state/project.js";
+import { makeContext, isInitialized, toolRecall, toolRemember, toolRecordSolution, toolProjectMap, toolUsageReport, toolInsights, toolHandoff, } from "./tools.js";
+const TOOLS = [
+    {
+        name: "recall",
+        description: "Semantic search over PackMind's project memory (knowledge, journal, solutions, source). Use before investigating or re-deriving anything.",
+        inputSchema: {
+            type: "object",
+            properties: { query: { type: "string", description: "What to search for" } },
+            required: ["query"],
+        },
+    },
+    {
+        name: "remember",
+        description: "Record a durable preference, decision, never-do rule, or note into project knowledge.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                note: { type: "string" },
+                kind: { type: "string", enum: ["Preferences", "Decisions", "Never Do", "Notes"] },
+            },
+            required: ["note"],
+        },
+    },
+    {
+        name: "record_solution",
+        description: "Record a bug and its fix so it is never re-investigated. Recording the same error again bumps its occurrence count.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                error: { type: "string" },
+                cause: { type: "string" },
+                fix: { type: "string" },
+                file: { type: "string", description: "Optional file path the bug relates to" },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["error"],
+        },
+    },
+    {
+        name: "project_map",
+        description: "List the project's files with descriptions and token estimates. Optional substring filter.",
+        inputSchema: { type: "object", properties: { filter: { type: "string" } } },
+    },
+    {
+        name: "usage_report",
+        description: "Token usage and dollar cost for this project (lifetime).",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "insights",
+        description: "Where tokens go and what PackMind saved: cost, estimated savings, map coverage, heaviest files, and upkeep notes.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "handoff",
+        description: "Get or set the session handoff note ('where we are / what's next').",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["get", "set"] },
+                content: { type: "string" },
+            },
+            required: ["action"],
+        },
+    },
+];
+function text(s) {
+    return { content: [{ type: "text", text: s }] };
+}
+async function main() {
+    const projectRoot = findRoot();
+    const server = new Server({ name: "packmind", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        if (!isInitialized(projectRoot)) {
+            return text("PackMind is not initialized in this project. Run `packmind init`.");
+        }
+        const ctx = makeContext(projectRoot);
+        const a = (req.params.arguments ?? {});
+        try {
+            switch (req.params.name) {
+                case "recall":
+                    return text(await toolRecall(ctx, String(a.query ?? "")));
+                case "remember":
+                    return text(toolRemember(ctx, String(a.note ?? ""), a.kind));
+                case "record_solution":
+                    return text(toolRecordSolution(ctx, { error: String(a.error ?? ""), cause: a.cause, fix: a.fix, file: a.file, tags: a.tags }));
+                case "project_map":
+                    return text(toolProjectMap(ctx, a.filter));
+                case "usage_report":
+                    return text(toolUsageReport(ctx));
+                case "insights":
+                    return text(toolInsights(ctx));
+                case "handoff":
+                    return text(toolHandoff(ctx, a.action === "set" ? "set" : "get", a.content));
+                default:
+                    return text(`Unknown tool: ${req.params.name}`);
+            }
+        }
+        catch (err) {
+            return text(`PackMind tool error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    await server.connect(new StdioServerTransport());
+}
+export function runMcpServer() {
+    return main();
+}

package/dist/mcp/tools.js

@@ -0,0 +1,130 @@
+import * as fs from "node:fs";
+import { brain } from "../state/files.js";
+import { loadConfig } from "../state/schema.js";
+import { readJsonOr, writeJson, appendLine, readTextOr, writeText } from "../util/fs-atomic.js";
+import { parseMap } from "../state/formats.js";
+import { readLedger, totalCost } from "../cost/ledger.js";
+import { recall as recallSearch } from "../recall/indexer.js";
+import { computeInsights } from "../cost/insights.js";
+import { LocalEmbedder } from "../recall/embedder.js";
+import { enqueue } from "../recall/queue.js";
+export function makeContext(projectRoot) {
+    const config = loadConfig(brain(projectRoot).config);
+    return { projectRoot, config, embedder: new LocalEmbedder(config.recall.embedModel) };
+}
+export async function toolRecall(ctx, query) {
+    if (!ctx.config.recall.enabled)
+        return "Recall is disabled in config.";
+    const hits = await recallSearch(ctx.projectRoot, ctx.config, ctx.embedder, query);
+    if (hits.length === 0)
+        return "No relevant memory found. Index may be empty — run `packmind index`.";
+    return hits
+        .map((h, i) => `${i + 1}. [${h.kind} · ${h.source} · score ${h.score.toFixed(2)}]\n${h.text.slice(0, 600)}`)
+        .join("\n\n");
+}
+export function toolRemember(ctx, note, kind = "Notes") {
+    const heading = ["Preferences", "Decisions", "Never Do", "Notes"].includes(kind) ? kind : "Notes";
+    const file = brain(ctx.projectRoot).knowledge;
+    const existing = readTextOr(file);
+    // Append under the heading if present; otherwise create it.
+    if (new RegExp(`^##\\s+${heading}\\b`, "m").test(existing)) {
+        appendLine(file, `\n<!-- ${heading} -->\n- ${new Date().toISOString().slice(0, 10)}: ${note}\n`);
+    }
+    else {
+        appendLine(file, `\n## ${heading}\n\n- ${new Date().toISOString().slice(0, 10)}: ${note}\n`);
+    }
+    enqueue(ctx.projectRoot, ".packmind/knowledge.md");
+    return `Recorded under "${heading}".`;
+}
+const normalizeError = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+export function toolRecordSolution(ctx, args) {
+    const path = brain(ctx.projectRoot).solutions;
+    const list = readJsonOr(path, []);
+    const now = new Date().toISOString();
+    // De-dupe: if we've seen this error before, bump its occurrence count instead
+    // of appending a near-duplicate (keeps the bug memory high-signal).
+    const key = normalizeError(args.error);
+    const existing = list.find((s) => normalizeError(s.error ?? "") === key);
+    if (existing) {
+        existing.occurrences = (existing.occurrences ?? 1) + 1;
+        existing.lastSeen = now;
+        if (args.fix && !existing.fix)
+            existing.fix = args.fix;
+        if (args.file && !existing.file)
+            existing.file = args.file;
+        for (const tag of args.tags ?? [])
+            if (!existing.tags?.includes(tag))
+                (existing.tags ??= []).push(tag);
+        writeJson(path, list);
+        enqueue(ctx.projectRoot, ".packmind/solutions.json");
+        return `Updated existing solution ${existing.id} — now seen ${existing.occurrences} times.`;
+    }
+    const entry = {
+        id: `sol-${Date.now()}`,
+        at: now,
+        lastSeen: now,
+        occurrences: 1,
+        error: args.error,
+        cause: args.cause ?? "",
+        fix: args.fix ?? "",
+        file: args.file ?? "",
+        tags: args.tags ?? [],
+    };
+    list.push(entry);
+    writeJson(path, list);
+    enqueue(ctx.projectRoot, ".packmind/solutions.json");
+    return `Recorded solution ${entry.id}.`;
+}
+export function toolProjectMap(ctx, filter) {
+    const map = parseMap(readTextOr(brain(ctx.projectRoot).map));
+    const out = [];
+    for (const [section, entries] of map) {
+        const rows = entries
+            .filter((e) => !filter || (section + e.file).toLowerCase().includes(filter.toLowerCase()))
+            .map((e) => `  ${section}${e.file} — ${e.description || "?"} (~${e.tokens} tok)`);
+        if (rows.length)
+            out.push(`${section}\n${rows.join("\n")}`);
+    }
+    return out.length ? out.join("\n") : "Map is empty — run `packmind scan`.";
+}
+export function toolInsights(ctx) {
+    const r = computeInsights(ctx.projectRoot, ctx.config);
+    const lines = [
+        `Cost so far: $${r.totalCost.toFixed(4)} (${r.inputTokens} in / ${r.outputTokens} out)`,
+        `Estimated saved: $${r.estCostSaved.toFixed(4)} (~${r.estTokensSaved} tokens; ${r.reReadsAvoided} re-reads avoided)`,
+        `Map coverage: ${r.mapCoverage === null ? "n/a" : Math.round(r.mapCoverage * 100) + "%"}`,
+    ];
+    if (r.topFiles.length) {
+        lines.push("Heaviest files:");
+        for (const f of r.topFiles)
+            lines.push(`  ${f.file} — ~${f.tokens} tok ($${f.cost.toFixed(4)})`);
+    }
+    for (const f of r.flags)
+        lines.push(`[${f.level}] ${f.title}: ${f.detail}`);
+    return lines.join("\n");
+}
+export function toolUsageReport(ctx) {
+    const ledger = readLedger(ctx.projectRoot, ctx.config.model);
+    const t = ledger.totals;
+    return [
+        `Model: ${ledger.model}`,
+        `Sessions: ${t.sessions}`,
+        `Reads: ${t.reads} (deduped ${t.dedupedReads}, map hits ${t.mapHits})`,
+        `Writes: ${t.writes}`,
+        `Tokens: ${t.inputTokens.toLocaleString()} in / ${t.outputTokens.toLocaleString()} out`,
+        `Cost: $${totalCost(ledger).toFixed(4)} ($${t.inputCost.toFixed(4)} in / $${t.outputCost.toFixed(4)} out)`,
+    ].join("\n");
+}
+export function toolHandoff(ctx, action, content) {
+    const file = brain(ctx.projectRoot).handoff;
+    if (action === "set") {
+        writeText(file, `# Session Handoff\n\n_Updated ${new Date().toISOString()}_\n\n${content ?? ""}\n`);
+        return "Handoff updated.";
+    }
+    const text = readTextOr(file).trim();
+    return text || "No handoff recorded yet.";
+}
+/** True if the project has been initialized. */
+export function isInitialized(projectRoot) {
+    return fs.existsSync(brain(projectRoot).config);
+}

package/dist/recall/chunker.js

@@ -0,0 +1,24 @@
+/**
+ * Split text into overlapping windows of roughly `size` characters, breaking on
+ * line boundaries where possible so chunks stay semantically coherent.
+ */
+export function chunkText(text, source, kind, size = 1200) {
+    const clean = text.trim();
+    if (!clean)
+        return [];
+    if (clean.length <= size)
+        return [{ source, kind, text: clean }];
+    const chunks = [];
+    const lines = clean.split(/\r?\n/);
+    let buf = "";
+    for (const line of lines) {
+        if (buf.length + line.length + 1 > size && buf) {
+            chunks.push({ source, kind, text: buf.trim() });
+            buf = "";
+        }
+        buf += line + "\n";
+    }
+    if (buf.trim())
+        chunks.push({ source, kind, text: buf.trim() });
+    return chunks;
+}

package/dist/recall/embedder.js

@@ -0,0 +1,51 @@
+import { userRoot } from "../util/platform.js";
+/**
+ * Local, offline embedder backed by transformers.js (WASM). The model is
+ * downloaded once and cached under ~/.packmind/models — no API key, no network
+ * after the first run, nothing leaves the machine.
+ */
+export class LocalEmbedder {
+    model;
+    pipe = null;
+    dims = 384;
+    constructor(model = "Xenova/all-MiniLM-L6-v2") {
+        this.model = model;
+    }
+    dimensions() {
+        return this.dims;
+    }
+    async ensure() {
+        if (this.pipe)
+            return this.pipe;
+        let mod;
+        try {
+            // Resolved at runtime only — the package is an OPTIONAL dependency, so a
+            // non-literal specifier keeps `tsc` from requiring it at compile time
+            // (it isn't installed in CI's --no-optional build).
+            const pkg = "@xenova/transformers";
+            mod = await import(pkg);
+        }
+        catch {
+            throw new Error("Semantic recall needs the optional '@xenova/transformers' package. Install it with:\n" +
+                "  npm install -g @xenova/transformers\n" +
+                "(or set recall.enabled = false in .packmind/config.json to disable recall).");
+        }
+        mod.env.cacheDir = `${userRoot()}/models`;
+        mod.env.allowLocalModels = true;
+        this.pipe = await mod.pipeline("feature-extraction", this.model);
+        return this.pipe;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const pipe = await this.ensure();
+        const out = [];
+        for (const text of texts) {
+            const tensor = await pipe(text, { pooling: "mean", normalize: true });
+            const vec = Array.from(tensor.data);
+            this.dims = vec.length;
+            out.push(vec);
+        }
+        return out;
+    }
+}

package/dist/recall/indexer.js

@@ -0,0 +1,94 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { walkProject } from "../state/walk.js";
+import { brain } from "../state/files.js";
+import { chunkText } from "./chunker.js";
+import { VectorStore } from "./store.js";
+import { drainQueue } from "./queue.js";
+/** Brain files that are worth embedding as searchable knowledge. */
+const BRAIN_SOURCES = [
+    { file: "knowledge.md", kind: "knowledge" },
+    { file: "journal.md", kind: "journal" },
+    { file: "solutions.json", kind: "solution" },
+    { file: "handoff.md", kind: "handoff" },
+];
+function collectChunks(projectRoot, config, sources) {
+    const chunks = [];
+    const want = sources ? new Set(sources) : null;
+    for (const { file, kind } of BRAIN_SOURCES) {
+        const rel = `.packmind/${file}`;
+        if (want && !want.has(rel))
+            continue;
+        try {
+            const text = fs.readFileSync(path.join(projectRoot, ".packmind", file), "utf8");
+            chunks.push(...chunkText(text, rel, kind, config.recall.chunkChars));
+        }
+        catch {
+            /* missing brain file */
+        }
+    }
+    for (const { abs, rel } of walkProject(projectRoot, config)) {
+        if (want && !want.has(rel))
+            continue;
+        try {
+            const text = fs.readFileSync(abs, "utf8");
+            chunks.push(...chunkText(text, rel, "code", config.recall.chunkChars));
+        }
+        catch {
+            /* unreadable */
+        }
+    }
+    return chunks;
+}
+async function embedChunks(embedder, chunks) {
+    if (chunks.length === 0)
+        return [];
+    const vectors = await embedder.embed(chunks.map((c) => c.text));
+    return chunks.map((c, i) => ({
+        id: `${c.source}#${i}`,
+        source: c.source,
+        kind: c.kind,
+        text: c.text,
+        vector: vectors[i],
+    }));
+}
+/** Full (re)index of the project into the vector store. */
+export async function buildIndex(projectRoot, config, embedder) {
+    const chunks = collectChunks(projectRoot, config, null);
+    const records = await embedChunks(embedder, chunks);
+    const store = new VectorStore(brain(projectRoot).vectors, config.recall.embedModel);
+    // Group by source so upsertBySource replaces cleanly.
+    const bySource = new Set(records.map((r) => r.source));
+    for (const s of store.sources())
+        if (!bySource.has(s))
+            store.removeSource(s);
+    store.upsertBySource(records);
+    store.save();
+    return store.size();
+}
+/** Incrementally embed whatever the hooks queued; drop deleted sources. */
+export async function refreshFromQueue(projectRoot, config, embedder) {
+    const queued = drainQueue(projectRoot);
+    if (queued.length === 0)
+        return 0;
+    const store = new VectorStore(brain(projectRoot).vectors, config.recall.embedModel);
+    const present = queued.filter((rel) => fs.existsSync(path.join(projectRoot, rel)) || rel.startsWith(".packmind/"));
+    for (const rel of queued)
+        if (!present.includes(rel))
+            store.removeSource(rel);
+    const chunks = collectChunks(projectRoot, config, present);
+    const records = await embedChunks(embedder, chunks);
+    store.upsertBySource(records);
+    store.save();
+    return records.length;
+}
+export async function recall(projectRoot, config, embedder, query) {
+    await refreshFromQueue(projectRoot, config, embedder);
+    const store = new VectorStore(brain(projectRoot).vectors, config.recall.embedModel);
+    if (store.size() === 0)
+        return [];
+    const [qv] = await embedder.embed([query]);
+    return store
+        .search(qv, config.recall.topK)
+        .map((r) => ({ source: r.source, kind: r.kind, text: r.text, score: r.score }));
+}

package/dist/recall/queue.js

@@ -0,0 +1,24 @@
+import { readJsonOr, writeJson } from "../util/fs-atomic.js";
+import { brain } from "../state/files.js";
+/**
+ * The index queue records source paths the hooks touched so the indexer can
+ * (re)embed them lazily. Hooks have no heavy dependencies, so they only enqueue;
+ * `packmind index` and the MCP server drain the queue.
+ */
+export function enqueue(projectRoot, relPath) {
+    const q = readJsonOr(brain(projectRoot).queue, []);
+    if (!q.includes(relPath)) {
+        q.push(relPath);
+        writeJson(brain(projectRoot).queue, q);
+    }
+}
+export function drainQueue(projectRoot) {
+    const path = brain(projectRoot).queue;
+    const q = readJsonOr(path, []);
+    if (q.length)
+        writeJson(path, []);
+    return q;
+}
+export function peekQueue(projectRoot) {
+    return readJsonOr(brain(projectRoot).queue, []);
+}

package/dist/recall/store.js

@@ -0,0 +1,48 @@
+import { readJsonOr, writeJson } from "../util/fs-atomic.js";
+export function cosine(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/** A flat-file vector index. Small projects fit comfortably in memory. */
+export class VectorStore {
+    file;
+    data;
+    constructor(file, model = "unknown") {
+        this.file = file;
+        this.data = readJsonOr(file, { version: 1, model, records: [] });
+    }
+    /** Replace all records whose source matches one being upserted. */
+    upsertBySource(records) {
+        const sources = new Set(records.map((r) => r.source));
+        this.data.records = this.data.records.filter((r) => !sources.has(r.source));
+        this.data.records.push(...records);
+    }
+    removeSource(source) {
+        this.data.records = this.data.records.filter((r) => r.source !== source);
+    }
+    sources() {
+        return new Set(this.data.records.map((r) => r.source));
+    }
+    search(queryVector, topK) {
+        return this.data.records
+            .map((r) => ({ ...r, score: cosine(queryVector, r.vector) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+    size() {
+        return this.data.records.length;
+    }
+    save() {
+        writeJson(this.file, this.data);
+    }
+}

package/dist/state/describe.js

@@ -0,0 +1,63 @@
+import * as path from "node:path";
+const KNOWN = {
+    "package.json": "Node package manifest",
+    "tsconfig.json": "TypeScript compiler config",
+    "Dockerfile": "Container build recipe",
+    "docker-compose.yml": "Docker Compose services",
+    ".gitignore": "Git ignore rules",
+    "Makefile": "Make build targets",
+    "README.md": "Project readme",
+    "LICENSE": "License text",
+    "pyproject.toml": "Python project config",
+    "Cargo.toml": "Rust crate manifest",
+    "go.mod": "Go module definition",
+    "vite.config.ts": "Vite build config",
+    "vitest.config.ts": "Vitest test config",
+};
+const COMMENT = /^\s*(?:\/\/+|#+|--|;|\*)\s?(.+)$/;
+/**
+ * Derive a one-line description of a file from its first 8KB. Original
+ * heuristic: known names first, then a leading doc/comment, a JSON description,
+ * or the first declared symbol. Returns "" when nothing meaningful is found.
+ */
+export function describeFile(filePath, content) {
+    const base = path.basename(filePath);
+    if (KNOWN[base])
+        return KNOWN[base];
+    const head = content.slice(0, 8192);
+    const ext = path.extname(base).toLowerCase();
+    if (ext === ".md" || ext === ".mdx") {
+        const h = head.match(/^#{1,3}\s+(.+)$/m);
+        if (h)
+            return cap(h[1]);
+    }
+    if (ext === ".json") {
+        try {
+            const j = JSON.parse(content);
+            if (typeof j.description === "string" && j.description)
+                return cap(j.description);
+            if (typeof j.name === "string" && j.name)
+                return cap(String(j.name));
+        }
+        catch {
+            /* not valid JSON */
+        }
+    }
+    for (const raw of head.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const c = line.match(COMMENT);
+        if (c && c[1].trim().length > 3 && !/^[=*-]+$/.test(c[1].trim()))
+            return cap(c[1]);
+        break; // only consider the very first non-blank line as a header comment
+    }
+    const sym = head.match(/\b(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|const|interface|type|def|struct|enum|fn)\s+([A-Za-z_$][\w$]*)/);
+    if (sym)
+        return cap(`Defines ${sym[1]}`);
+    return "";
+}
+function cap(s, max = 90) {
+    const clean = s.replace(/\s+/g, " ").trim();
+    return clean.length > max ? clean.slice(0, max - 1) + "…" : clean;
+}

package/dist/state/files.js

@@ -0,0 +1,45 @@
+import { stateFile } from "../util/paths.js";
+import { readJsonOr, writeJson } from "../util/fs-atomic.js";
+/** Resolve the standard brain-file paths for a project. */
+export function brain(projectRoot) {
+    return {
+        dir: stateFile(projectRoot),
+        protocol: stateFile(projectRoot, "PACKMIND.md"),
+        config: stateFile(projectRoot, "config.json"),
+        map: stateFile(projectRoot, "map.md"),
+        knowledge: stateFile(projectRoot, "knowledge.md"),
+        journal: stateFile(projectRoot, "journal.md"),
+        solutions: stateFile(projectRoot, "solutions.json"),
+        usage: stateFile(projectRoot, "usage.json"),
+        handoff: stateFile(projectRoot, "handoff.md"),
+        policy: stateFile(projectRoot, "policy.json"),
+        identity: stateFile(projectRoot, "identity.md"),
+        session: stateFile(projectRoot, "state", "session.json"),
+        recallDir: stateFile(projectRoot, "recall"),
+        queue: stateFile(projectRoot, "recall", "queue.json"),
+        vectors: stateFile(projectRoot, "recall", "vectors.json"),
+        hooksDir: stateFile(projectRoot, "hooks"),
+    };
+}
+export function emptySession(id) {
+    return {
+        id,
+        started: new Date().toISOString(),
+        reads: {},
+        writes: [],
+        editCounts: {},
+        inputTokens: 0,
+        outputTokens: 0,
+        inputCost: 0,
+        outputCost: 0,
+        mapHits: 0,
+        mapMisses: 0,
+        dedupedReads: 0,
+    };
+}
+export function readSession(projectRoot) {
+    return readJsonOr(brain(projectRoot).session, null);
+}
+export function writeSession(projectRoot, s) {
+    writeJson(brain(projectRoot).session, s);
+}

package/dist/state/formats.js

@@ -0,0 +1,80 @@
+/**
+ * Parsers and serializers for PackMind's human-readable brain files.
+ *
+ * Every split is CRLF-tolerant (`/\r?\n/`) so files authored on Windows or with
+ * `core.autocrlf=true` round-trip cleanly. This module is the single source of
+ * truth for these formats; the standalone hook runtime keeps a mirror that is
+ * verified identical by a parity test.
+ */
+export function lines(text) {
+    return text.split(/\r?\n/);
+}
+const SECTION = /^##\s+(.+?)\s*$/;
+// `- `name` · ~123 tok[ · $0.0012] — description`
+const ENTRY = /^-\s+`([^`]+)`\s+·\s+~(\d+)\s+tok(?:\s+·\s+\$([\d.]+))?(?:\s+—\s+(.*\S))?\s*$/;
+export function parseMap(text) {
+    const out = new Map();
+    let section = "";
+    for (const line of lines(text)) {
+        const s = line.match(SECTION);
+        if (s) {
+            section = s[1].trim();
+            if (!out.has(section))
+                out.set(section, []);
+            continue;
+        }
+        if (!section)
+            continue;
+        const e = line.match(ENTRY);
+        if (e) {
+            out.get(section).push({
+                file: e[1],
+                tokens: parseInt(e[2], 10),
+                cost: e[3] ? Number(e[3]) : undefined,
+                description: e[4] ? e[4].trim() : "",
+            });
+        }
+    }
+    return out;
+}
+export function serializeMap(sections, meta) {
+    const out = [
+        "# Project Map",
+        "",
+        `_Maintained by PackMind · ${meta.fileCount} files · updated ${meta.updated}_`,
+        "",
+    ];
+    for (const key of [...sections.keys()].sort()) {
+        const entries = sections.get(key);
+        if (entries.length === 0)
+            continue;
+        out.push(`## ${key}`, "");
+        for (const e of [...entries].sort((a, b) => a.file.localeCompare(b.file))) {
+            const cost = e.cost && e.cost > 0 ? ` · $${e.cost.toFixed(4)}` : "";
+            const desc = e.description ? ` — ${e.description}` : "";
+            out.push(`- \`${e.file}\` · ~${e.tokens} tok${cost}${desc}`);
+        }
+        out.push("");
+    }
+    return out.join("\n");
+}
+/**
+ * Extract entries under a `## Never Do` heading in knowledge.md so the write
+ * guard can warn before a known-bad pattern is reintroduced. CRLF-safe.
+ */
+export function parseNeverDo(knowledge) {
+    const result = [];
+    let active = false;
+    for (const line of lines(knowledge)) {
+        if (/^##\s+/.test(line)) {
+            active = /^##\s+Never\s*Do\b/i.test(line);
+            continue;
+        }
+        if (!active)
+            continue;
+        const m = line.match(/^[-*]\s+(?:\[[\d-]+\]\s*)?(.+?)\s*$/);
+        if (m)
+            result.push(m[1]);
+    }
+    return result;
+}