nodedex 0.1.0

package/dist/server.js

@@ -0,0 +1,298 @@
+import "./boot-env.js"; // FIRST: load ~/.nodedex/.env before any module reads process.env
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WorkspaceDB } from "./store/database.js";
+import { EmbeddingEngine, blockEmbeddingText } from "./engine/embeddings.js";
+import { fileURLToPath } from "url";
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { buildWorkspaceServer, agentToolAllowlist, writesExposed } from "./mcp-server.js";
+import { startApiServer } from "./api-server.js";
+import { getLLMProvider } from "./engine/providers/index.js";
+export const schedulerHealth = {
+    gc: { name: "Garbage Collection", interval_label: "6h", interval_ms: 6 * 60 * 60 * 1000, running: false, run_count: 0, last_run: null, last_result: null, last_error: null },
+    reembed: { name: "Re-embed", interval_label: "10min", interval_ms: 10 * 60 * 1000, running: false, run_count: 0, last_run: null, last_result: null, last_error: null },
+    enrich: { name: "Concept Enrich", interval_label: "5min", interval_ms: 5 * 60 * 1000, running: false, run_count: 0, last_run: null, last_result: null, last_error: null },
+    gaps: { name: "Gap Audit", interval_label: "1h", interval_ms: 60 * 60 * 1000, running: false, run_count: 0, last_run: null, last_result: null, last_error: null },
+};
+// ─── Initialize ──────────────────────────────────────────────────
+// Always resolve DB path relative to this file (../../data/workspace.db from src/ or dist/)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const dbPath = process.env.WORKSPACE_DB_PATH || process.env.DB_PATH || path.resolve(__dirname, "../../data/workspace.db");
+const db = new WorkspaceDB(dbPath);
+const embeddings = new EmbeddingEngine();
+// The Workspace MCP server (instructions + read-only gating + all tools) — built by the
+// shared factory so the stdio transport here and the HTTP transport (routes/mcp-http.ts,
+// for networked/Dockerized clients) expose the IDENTICAL tool surface. See mcp-server.ts.
+const server = buildWorkspaceServer(db, embeddings);
+// ─── Start Server ────────────────────────────────────────────────
+async function main() {
+    await db.init();
+    console.error("Workspace MCP Server v1.0.0-MVP starting...");
+    const encryptionEnabled = !!process.env.WORKSPACE_ENCRYPTION_KEY;
+    console.error(`Encryption: ${encryptionEnabled ? "enabled (AES-256)" : "disabled (no WORKSPACE_ENCRYPTION_KEY)"}`);
+    console.error(`Embeddings: ${embeddings.isAvailable() ? "enabled" : "disabled (no embedding API key)"}`);
+    const provider = getLLMProvider();
+    console.error(`AI provider: ${provider.getName()} — ${provider.isAvailable() ? "ready" : "NOT AVAILABLE (no API key set — check .env)"}`);
+    // ── Agent identity env vars ───────────────────────────────────────
+    // Set these when spawning sub-agents so they know who they are:
+    //   WMCS_AGENT_ID   = unique name for this agent instance (e.g. "researcher-1", "coder-main")
+    //   WMCS_AGENT_ROLE = agent's role (e.g. "researcher", "coder", "reviewer")
+    // NOTE: WMCS_ prefix is a Wmcs-era leftover; pending rename to NODEDEX_AGENT_ID.
+    const agentId = process.env.WMCS_AGENT_ID;
+    const agentRole = process.env.WMCS_AGENT_ROLE;
+    if (agentId) {
+        console.error(`Agent identity: ${agentId} (role: ${agentRole || "general"})`);
+        db.agentHeartbeat(agentId, agentRole || "general");
+    }
+    else {
+        console.error(`Agent identity: not set (set WMCS_AGENT_ID + WMCS_AGENT_ROLE when spawning sub-agents)`);
+    }
+    // ── One-time: prune any embedding vectors stored in block_history ────────
+    const { deleted: histPruned } = db.pruneEmbeddingHistory();
+    if (histPruned > 0)
+        console.error(`Pruned ${histPruned} embedding history entry(ies) from block_history.`);
+    // ── Backfill embeddings for blocks created before embedding support ──────
+    if (embeddings.isAvailable()) {
+        const allBlocks = db.getAllBlocks();
+        const missing = allBlocks.filter((b) => !b.embedding);
+        if (missing.length > 0) {
+            console.error(`Backfilling embeddings for ${missing.length} block(s)...`);
+            for (const block of missing) {
+                try {
+                    const embeddingText = blockEmbeddingText({ essence: block.essence, concepts: block.concepts });
+                    const vec = await embeddings.embed(embeddingText);
+                    if (vec)
+                        db.updateEmbedding(block.id, vec);
+                }
+                catch { /* skip silently */ }
+            }
+            console.error("Embedding backfill complete.");
+        }
+    }
+    // ── Warm up the LOCAL embedder so its model downloads NOW (at boot), not on the
+    //    first extraction. The bundled bge-small lazy-downloads on first embed; a fresh
+    //    install has no blocks to backfill, so without this the ~30MB download would stall
+    //    the user's first real turn. Local-only (a hosted provider has nothing to pre-fetch).
+    //    Fire-and-forget so boot stays fast; the model is ready long before the agent connects.
+    const embProvider = (process.env.EMBEDDING_PROVIDER ?? "local").toLowerCase();
+    if (embProvider === "local" && embeddings.isAvailable()) {
+        console.error("[boot] warming up the local embedding model (first run downloads it — one-time)…");
+        embeddings.embed("warmup")
+            .then(() => console.error("[boot] local embedding model ready."))
+            .catch(() => { });
+    }
+    // ── Start Web UI API server (HTTP) ───────────────────────────────
+    // Port defaults to 3001 but is overridable via PORT env. This is the
+    // hinge for TEST ISOLATION: the global reflect Stop hook is hardcoded
+    // to localhost:3001, so a test server booted on a different PORT (e.g.
+    // PORT=3099) physically cannot be reached by the hook firing on our
+    // own live conversation — closing the harness-pollution leak that
+    // pause/benchmark band-aids couldn't (the hook hits 3001, not us).
+    const apiPort = Number(process.env.PORT) || 3001;
+    const httpServer = startApiServer(db, schedulerHealth, apiPort, embeddings);
+    // ── PID file + graceful shutdown (ops gap 3) ─────────────────────────────────
+    // Write a pidfile so tooling can find this server; on a deliverable signal,
+    // close the HTTP server (release the port) and the DB (release the file lock)
+    // so a restart never fights a lingering handle. NB on Windows, Stop-Process
+    // -Force (TerminateProcess) bypasses handlers — but the EADDRINUSE-exit guard
+    // in api-server.ts already prevents the zombie accumulation that was the real
+    // problem; this is the clean path for Ctrl+C / SIGTERM-respecting stops.
+    const pidDir = path.join(os.homedir(), ".nodedex");
+    const pidFile = path.join(pidDir, `nodedex-server-${apiPort}.pid`);
+    try {
+        if (!fs.existsSync(pidDir))
+            fs.mkdirSync(pidDir, { recursive: true });
+        fs.writeFileSync(pidFile, String(process.pid));
+    }
+    catch { /* non-fatal */ }
+    let shuttingDown = false;
+    const gracefulShutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.error(`[shutdown] ${signal} — closing server + DB, releasing the port + DB lock`);
+        try {
+            httpServer.close();
+        }
+        catch { /* ignore */ }
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+        try {
+            if (fs.existsSync(pidFile))
+                fs.unlinkSync(pidFile);
+        }
+        catch { /* ignore */ }
+        process.exit(0);
+    };
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK"]) {
+        try {
+            process.on(sig, () => gracefulShutdown(sig));
+        }
+        catch { /* signal not supported on this platform */ }
+    }
+    // ── Background scheduling ────────────────────────────────────────
+    function runJob(key, fn) {
+        const job = schedulerHealth[key];
+        if (job.running)
+            return;
+        job.running = true;
+        job.last_run = new Date().toISOString();
+        fn()
+            .then((result) => {
+            job.last_result = result;
+            job.last_error = null;
+            job.run_count++;
+        })
+            .catch((e) => {
+            job.last_error = String(e);
+            job.run_count++;
+            console.error(`[scheduler:${key}] error:`, e);
+        })
+            .finally(() => { job.running = false; });
+    }
+    // GC — every 6 hours
+    setInterval(() => runJob("gc", async () => {
+        const r = db.runGC();
+        const { deleted } = db.pruneEmbeddingHistory();
+        return `archived=${r.archived} promoted=${r.promoted} hist_pruned=${deleted}`;
+    }), schedulerHealth.gc.interval_ms);
+    // Reembed + enrich — only when Gemini is available
+    if (embeddings.isAvailable()) {
+        // Reembed missing embeddings every 10 minutes
+        setInterval(() => runJob("reembed", async () => {
+            const missing = db.getAllBlocks().filter((b) => !b.embedding).slice(0, 20);
+            if (missing.length === 0)
+                return "nothing to reembed";
+            let done = 0;
+            for (const block of missing) {
+                try {
+                    const text = blockEmbeddingText({ essence: block.essence, concepts: block.concepts });
+                    const vec = await embeddings.embed(text);
+                    if (vec) {
+                        db.updateEmbedding(block.id, vec);
+                        done++;
+                    }
+                }
+                catch { /* skip */ }
+            }
+            return `reembedded ${done}/${missing.length}`;
+        }), schedulerHealth.reembed.interval_ms);
+        // Concept enrichment every 30 minutes
+        setInterval(() => runJob("enrich", async () => {
+            const enrichProvider = getLLMProvider();
+            if (!enrichProvider.isAvailable())
+                return "skipped (AI provider not available)";
+            const targets = db.getAllBlocks().filter((b) => {
+                if (b.status === "archived")
+                    return false;
+                try {
+                    const c = JSON.parse(b.content);
+                    // Never overwrite concepts the agent tagged manually
+                    if (c.concepts_source === "agent")
+                        return false;
+                    return (c.concepts_source === "keyword_auto" || c.concepts_source === "gemini_reflect") && !b.enriched_at;
+                }
+                catch {
+                    return false;
+                }
+            }).slice(0, 10);
+            if (targets.length === 0)
+                return "nothing to enrich";
+            const enrichSysInstr = "Return 4-8 specific search tags as a JSON array. Tags must be specific named things a future user would search for: technologies, tools, mechanisms, measurements, named failure modes, named people or teams. NOT category labels, NOT type descriptions, NOT vague process words. Respond ONLY with a JSON array of lowercase strings.";
+            let enriched = 0;
+            for (const block of targets) {
+                try {
+                    const c = JSON.parse(block.content);
+                    const enrichText = await enrichProvider.generate(`${enrichSysInstr}\n\nBlock: "${block.label}" (${block.type})\nEssence: "${block.essence}"\nReturn 4-8 specific named things (technologies, mechanisms, measurements) as a JSON array. Not categories.`);
+                    const newConcepts = JSON.parse((enrichText ?? "").trim().replace(/```json\n?|```/g, ""));
+                    if (Array.isArray(newConcepts) && newConcepts.length > 0) {
+                        c.concepts = newConcepts;
+                        c.concepts_source = "gemini_enriched";
+                        db.updateBlock(block.id, { content: JSON.stringify(c), enriched_at: new Date().toISOString() }, "auto-enriched by scheduler");
+                        // Recompute quality score — enrichment adds is_a/unique/concepts so the
+                        // creation-time score (before content existed) is now stale.
+                        const concepts = (() => { try {
+                            return JSON.parse(block.concepts || "[]");
+                        }
+                        catch {
+                            return [];
+                        } })();
+                        let qScore = 0;
+                        if (block.essence && block.essence.trim().length > 0)
+                            qScore++;
+                        if (c.is_a)
+                            qScore++;
+                        if (c.unique && Object.keys(c.unique).length >= 2)
+                            qScore++;
+                        if (concepts.length >= 3)
+                            qScore++;
+                        const relCount = db.getRelations(block.id).length;
+                        if (block.type === "project" || relCount > 0)
+                            qScore++;
+                        db.updateBlock(block.id, { quality_score: Math.min(qScore, 5) });
+                        enriched++;
+                    }
+                }
+                catch { /* skip */ }
+            }
+            return `enriched ${enriched}/${targets.length}`;
+        }), schedulerHealth.enrich.interval_ms);
+    }
+    // Gap audit — every hour, logs to console and saves a note block if critical gaps found
+    setInterval(() => runJob("gaps", async () => {
+        const allBlocks = db.getAllBlocks().filter(b => b.status !== "archived");
+        const allRelations = db.getAllRelations(false);
+        const connectedIds = new Set();
+        for (const r of allRelations) {
+            connectedIds.add(r.source_id);
+            connectedIds.add(r.target_id);
+        }
+        const orphans = allBlocks.filter(b => b.type !== "project" && !connectedIds.has(b.id)).length;
+        const openQ = allBlocks.filter(b => b.type === "question").filter(b => {
+            const qRels = allRelations.filter(r => r.source_id === b.id || r.target_id === b.id);
+            return !qRels.some(r => {
+                const oid = r.source_id === b.id ? r.target_id : r.source_id;
+                return ["fact", "decision"].includes(allBlocks.find(x => x.id === oid)?.type || "");
+            });
+        }).length;
+        const unlinkedDE = allBlocks.filter(b => b.type === "dead_end").filter(b => {
+            return !allRelations.some(r => (r.source_id === b.id || r.target_id === b.id) && r.type === "contradicts");
+        }).length;
+        const sevenAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+        const staleDrafts = allBlocks.filter(b => {
+            if (b.type !== "draft")
+                return false;
+            const c = (() => { try {
+                return JSON.parse(b.content);
+            }
+            catch {
+                return {};
+            } })();
+            return c?.unique?.draft_status !== "promoted" && b.created_at < sevenAgo;
+        }).length;
+        const total = orphans + openQ + unlinkedDE + staleDrafts;
+        const summary = `orphans=${orphans} open_questions=${openQ} unlinked_dead_ends=${unlinkedDE} stale_drafts=${staleDrafts}`;
+        if (total > 0)
+            console.error(`[scheduler:gaps] ${total} gap(s) detected — ${summary}`);
+        return total === 0 ? "no gaps" : summary;
+    }), schedulerHealth.gaps.interval_ms);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Workspace MCP Server running on stdio.");
+    if (writesExposed()) {
+        console.error("Agent tools: ALL exposed (NODEDEX_EXPOSE_WRITE_TOOLS=on) — read + write + admin.");
+    }
+    else {
+        console.error(`Agent tools (READ-ONLY surface): ${[...agentToolAllowlist()].join(", ")}`);
+        console.error("  write/admin/maintenance tools HIDDEN (the pipeline writes; agent only reads). NODEDEX_EXPOSE_WRITE_TOOLS=on to expose; NODEDEX_EXPOSE_TASKS=on for task tools.");
+    }
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/store/__tests__/backup.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backup.test.d.ts.map

package/dist/store/__tests__/backup.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.test.d.ts","sourceRoot":"","sources":["../../../src/store/__tests__/backup.test.ts"],"names":[],"mappings":""}

package/dist/store/__tests__/backup.test.js

@@ -0,0 +1,53 @@
+/**
+ * Ops gap 3 — scheduled/consistent DB backups.
+ * Run: node --import=tsx/esm --test src/store/__tests__/backup.test.ts
+ */
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import Database from "better-sqlite3";
+import { WorkspaceDB } from "../database.js";
+import { performBackup } from "../backup.js";
+const dir = path.join(os.tmpdir(), `nodedex-backup-test-${process.pid}`);
+const dbPath = path.join(dir, "workspace.db");
+const backupDir = path.join(dir, "backups");
+let db;
+before(async () => {
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    db = new WorkspaceDB(dbPath);
+    await db.init();
+    db.createBlock({ label: "backup_test_fact", type: "fact", essence: "backup me", content: {}, ttl: "permanent" });
+});
+after(() => {
+    try {
+        db["db"]?.close();
+    }
+    catch { /* ignore */ }
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+describe("performBackup", () => {
+    test("creates a consistent, readable backup", () => {
+        const r = performBackup(db, { keep: 5 });
+        assert.ok(r.backed_up, "returns a backup path");
+        assert.ok(fs.existsSync(r.backed_up), "backup file exists");
+        const bk = new Database(r.backed_up, { readonly: true });
+        const row = bk.prepare("SELECT essence FROM blocks WHERE label = 'backup_test_fact'").get();
+        bk.close();
+        assert.equal(row?.essence, "backup me", "backup contains the written block (checkpoint folded the WAL in)");
+    });
+    test("rotates to the most recent `keep`", () => {
+        for (let i = 0; i < 6; i++)
+            fs.writeFileSync(path.join(backupDir, `workspace-2026-01-0${i}.db`), "x");
+        performBackup(db, { keep: 5 });
+        const remaining = fs.readdirSync(backupDir).filter((f) => /^workspace-.*\.db$/.test(f));
+        assert.equal(remaining.length, 5, "keeps exactly 5");
+    });
+    test("throttle skips a too-soon backup", () => {
+        const r = performBackup(db, { throttleMs: 60 * 60 * 1000, keep: 5 });
+        assert.equal(r.skipped, true);
+    });
+});
+//# sourceMappingURL=backup.test.js.map

package/dist/store/__tests__/backup.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.test.js","sourceRoot":"","sources":["../../../src/store/__tests__/backup.test.ts"],"names":[],"mappings":"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"}

package/dist/store/__tests__/quality.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=quality.test.d.ts.map

package/dist/store/__tests__/quality.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.test.d.ts","sourceRoot":"","sources":["../../../src/store/__tests__/quality.test.ts"],"names":[],"mappings":""}

package/dist/store/__tests__/quality.test.js

@@ -0,0 +1,75 @@
+/**
+ * store/quality — block-quality scoring tests.
+ *
+ * Bug 1 fix (2026-05-28) extracted computeQualityScore from routes/blocks.ts
+ * so the reflect pipeline can stamp scores at block creation. These tests
+ * lock the existing scoring contract — same numbers blocks.ts has been
+ * producing all along, just from a shared module now.
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { computeQualityScore } from "../quality.js";
+describe("computeQualityScore", () => {
+    test("baseline block returns 1", () => {
+        const block = { id: "blk_1", type: "note", content: {} };
+        assert.equal(computeQualityScore(block, []), 1);
+    });
+    test("is_a adds 1 (→ 2)", () => {
+        const block = { id: "blk_2", type: "fact", content: { is_a: "fact" } };
+        assert.equal(computeQualityScore(block, []), 2);
+    });
+    test("unique with >=2 keys adds 1 (→ 3 with is_a)", () => {
+        const block = { id: "blk_3", type: "fact", content: { is_a: "fact", unique: { value: "x", source: "y" } } };
+        assert.equal(computeQualityScore(block, []), 3);
+    });
+    test("unique with 1 key does NOT add (still 2 with is_a)", () => {
+        const block = { id: "blk_4", type: "fact", content: { is_a: "fact", unique: { value: "x" } } };
+        assert.equal(computeQualityScore(block, []), 2);
+    });
+    test("concepts >=3 adds 1 (→ 4 with is_a + unique)", () => {
+        const block = { id: "blk_5", type: "fact", content: { is_a: "fact", unique: { a: "1", b: "2" } } };
+        assert.equal(computeQualityScore(block, ["one", "two", "three"]), 4);
+    });
+    test("concepts <3 does NOT add", () => {
+        const block = { id: "blk_6", type: "fact", content: { is_a: "fact" } };
+        assert.equal(computeQualityScore(block, ["one", "two"]), 2);
+    });
+    test("project type gets +1 bonus (→ 3 with is_a, no unique)", () => {
+        // ★ THE BUG 1 CASE: pipeline-created projects had quality_score=0 and got
+        // rejected by recall.ts:149. With computeQualityScore now stamped, they
+        // arrive at q=3 (1 base + 1 is_a + 1 project bonus).
+        const block = { id: "blk_7", type: "project", content: { is_a: "project", unique: {} } };
+        assert.equal(computeQualityScore(block, []), 3);
+    });
+    test("project with unique{} and concepts hits 5 cap", () => {
+        const block = { id: "blk_8", type: "project", content: { is_a: "project", unique: { a: "1", b: "2" } } };
+        assert.equal(computeQualityScore(block, ["x", "y", "z"]), 5);
+    });
+    test("score caps at 5", () => {
+        // Maxes all 4 conditions: base=1 + is_a + unique + concepts + project = 5.
+        // Without project: 1 + is_a + unique + concepts = 4. Adding project would be 5.
+        // Anything beyond is capped.
+        const block = { id: "blk_9", type: "project", content: { is_a: "project", unique: { a: "1", b: "2", c: "3", d: "4", e: "5" } } };
+        assert.equal(computeQualityScore(block, ["x", "y", "z", "w"]), 5);
+    });
+    test("string content (JSON-stringified) is parsed", () => {
+        const block = { id: "blk_10", type: "fact", content: JSON.stringify({ is_a: "fact", unique: { a: "1", b: "2" } }) };
+        assert.equal(computeQualityScore(block, []), 3);
+    });
+    test("malformed string content falls back to {} (only base score)", () => {
+        const block = { id: "blk_11", type: "fact", content: "{not valid json" };
+        assert.equal(computeQualityScore(block, []), 1);
+    });
+    test("null/undefined content is handled (only base score)", () => {
+        const block1 = { id: "blk_12", type: "fact", content: null };
+        const block2 = { id: "blk_13", type: "fact" }; // no content key
+        assert.equal(computeQualityScore(block1, []), 1);
+        assert.equal(computeQualityScore(block2, []), 1);
+    });
+    test("process-type block (session state) gets 2 with is_a, no project bonus", () => {
+        // The other STRUCTURAL_TYPE in the recall.ts guard — session state blocks.
+        const block = { id: "blk_14", type: "process", content: { is_a: "process" } };
+        assert.equal(computeQualityScore(block, []), 2);
+    });
+});
+//# sourceMappingURL=quality.test.js.map

package/dist/store/__tests__/quality.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.test.js","sourceRoot":"","sources":["../../../src/store/__tests__/quality.test.ts"],"names":[],"mappings":"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"}

package/dist/store/backup.d.ts

@@ -0,0 +1,14 @@
+import type { WorkspaceDB } from "./database.js";
+export interface BackupResult {
+    backed_up?: string;
+    skipped?: boolean;
+    reason?: string;
+    kept: number;
+}
+export declare function performBackup(db: WorkspaceDB, opts?: {
+    throttleMs?: number;
+    keep?: number;
+}): BackupResult;
+export declare function startBackupTimer(db: WorkspaceDB): boolean;
+export declare function stopBackupTimer(): void;
+//# sourceMappingURL=backup.d.ts.map

package/dist/store/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/store/backup.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAID,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CA8B9G;AAoBD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAkBzD;AAED,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/store/backup.js

@@ -0,0 +1,95 @@
+// store/backup.ts — ops gap 3: consistent, scheduled DB backups.
+//
+// Two fixes over the old inline /api/admin/backup (which fs.copyFileSync'd the
+// live DB directly):
+//   1. CONSISTENCY: checkpoint (TRUNCATE) folds the WAL into the main file FIRST,
+//      so the copy is a complete snapshot. A raw copy of a WAL DB misses the
+//      uncommitted-to-main pages sitting in the -wal file.
+//   2. ENCRYPTION-SAFE: a byte copy preserves the on-disk bytes — so an encrypted
+//      DB's backup stays encrypted. SQLite's online .backup() API would copy the
+//      DECRYPTED pages into an unkeyed file = a plaintext leak of an encrypted DB.
+//
+// Shared by the manual endpoint and the scheduled timer. Backups land in
+// <db-dir>/backups/workspace-<ts>.db, rotated to the most recent `keep`.
+import fs from "fs";
+import path from "path";
+const BACKUP_RE = /^workspace-.*\.db$/;
+export function performBackup(db, opts = {}) {
+    const keep = opts.keep ?? 5;
+    const throttleMs = opts.throttleMs ?? 0;
+    const dbPath = db.dbPath;
+    if (!dbPath || !fs.existsSync(dbPath))
+        throw new Error("DB path not found");
+    const backupDir = path.join(path.dirname(dbPath), "backups");
+    if (!fs.existsSync(backupDir))
+        fs.mkdirSync(backupDir, { recursive: true });
+    const existing = fs.readdirSync(backupDir).filter((f) => BACKUP_RE.test(f)).sort();
+    if (throttleMs > 0 && existing.length > 0) {
+        const lastMs = fs.statSync(path.join(backupDir, existing[existing.length - 1])).mtimeMs;
+        if (Date.now() - lastMs < throttleMs) {
+            return { skipped: true, reason: `last backup < ${Math.round(throttleMs / 60000)}m ago`, kept: existing.length };
+        }
+    }
+    // checkpoint THEN copy — consistent + encryption-preserving (see header).
+    try {
+        db.rawDb.pragma("wal_checkpoint(TRUNCATE)");
+    }
+    catch { /* best-effort; copy still proceeds */ }
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const dest = path.join(backupDir, `workspace-${ts}.db`);
+    fs.copyFileSync(dbPath, dest);
+    const all = fs.readdirSync(backupDir).filter((f) => BACKUP_RE.test(f)).sort();
+    if (all.length > keep) {
+        for (const f of all.slice(0, all.length - keep)) {
+            try {
+                fs.unlinkSync(path.join(backupDir, f));
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return { backed_up: dest, kept: Math.min(all.length, keep) };
+}
+// ─── Scheduled backups ─────────────────────────────────────────────────────────
+// DEFAULT ON — unlike the LLM-spending timers (which default OFF for cost),
+// backups are $0 and protective; the worst outcome for a memory tool is losing
+// the graph. Disable with NODEDEX_BACKUP_ENABLED=0; interval via
+// NODEDEX_BACKUP_INTERVAL_MS (default 6h). Keeps the 5 most recent.
+let _handle = null;
+function backupEnabled() {
+    const v = (process.env.NODEDEX_BACKUP_ENABLED ?? "on").toLowerCase();
+    return v !== "0" && v !== "off" && v !== "false";
+}
+function backupIntervalMs() {
+    const v = parseInt(process.env.NODEDEX_BACKUP_INTERVAL_MS ?? "", 10);
+    return Number.isFinite(v) && v > 0 ? v : 6 * 60 * 60 * 1000; // 6h
+}
+export function startBackupTimer(db) {
+    if (!backupEnabled()) {
+        console.log("[backup] disabled (set NODEDEX_BACKUP_ENABLED=on to enable)");
+        return false;
+    }
+    if (_handle !== null)
+        return false;
+    const interval = backupIntervalMs();
+    console.log(`[backup] scheduled every ${Math.round(interval / 3600000)}h, keeping 5 in data/backups/ (NODEDEX_BACKUP_ENABLED=0 to disable)`);
+    _handle = setInterval(() => {
+        try {
+            const r = performBackup(db, { throttleMs: Math.floor(interval / 2), keep: 5 });
+            if (r.backed_up)
+                console.log(`[backup] wrote ${path.basename(r.backed_up)} (kept ${r.kept})`);
+        }
+        catch (e) {
+            console.warn(`[backup] failed: ${e?.message ?? e}`);
+        }
+    }, interval);
+    if (typeof _handle.unref === "function")
+        _handle.unref();
+    return true;
+}
+export function stopBackupTimer() {
+    if (_handle !== null) {
+        clearInterval(_handle);
+        _handle = null;
+    }
+}
+//# sourceMappingURL=backup.js.map

package/dist/store/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../src/store/backup.ts"],"names":[],"mappings":"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"}