@sksoftofficial/mindroot 1.0.0

package/src/server.js

@@ -0,0 +1,192 @@
+import http from "node:http";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { timingSafeEqual } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { handleRpc } from "./mcp.js";
+import { validSlug, ensureProject, getProjectRow } from "./indexer.js";
+import * as core from "./core.js";
+
+const DASHBOARD = path.join(path.dirname(fileURLToPath(import.meta.url)), "dashboard", "index.html");
+
+export function createServer(db, cfg) {
+  return http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, `http://127.0.0.1:${cfg.port}`);
+      if (url.pathname.length > 1 && url.pathname.endsWith("/")) url.pathname = url.pathname.slice(0, -1);
+
+      if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/dashboard")) {
+        const html = await fs.readFile(DASHBOARD, "utf8");
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(html);
+        return;
+      }
+
+      if (url.pathname === "/health") {
+        sendJson(res, 200, { ok: true });
+        return;
+      }
+
+      if (!authorized(req, cfg)) {
+        sendJson(res, 401, {
+          error: "unauthorized",
+          hint: "the apiKey in ~/.mindroot/config.json changed — update the Authorization Bearer key in your MCP client config",
+        });
+        return;
+      }
+
+      if (url.pathname === "/mcp") {
+        if (req.method !== "POST") {
+          sendJson(res, 405, { error: "method not allowed" });
+          return;
+        }
+        const rpc = await readJson(req);
+        const out = await handleRpc(db, rpc);
+        if (out.body === null) {
+          res.writeHead(out.status);
+          res.end();
+        } else {
+          sendJson(res, out.status, out.body);
+        }
+        return;
+      }
+
+      if (url.pathname.startsWith("/api/")) {
+        await handleApi(req, res, url, db);
+        return;
+      }
+
+      sendJson(res, 404, { error: "not found" });
+    } catch (err) {
+      const status = err.status ?? 500;
+      sendJson(res, status, { error: String(err.message) });
+    }
+  });
+}
+
+async function handleApi(req, res, url, db) {
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts[1] === "projects") {
+    const slug = parts[2];
+    if (!slug) {
+      if (req.method === "GET") return sendJson(res, 200, await core.listProjects(db));
+      if (req.method === "POST") {
+        const body = await readJson(req);
+        return sendJson(res, 201, ensureProject(db, body.slug));
+      }
+      throw methodNotAllowed();
+    }
+    if (!validSlug(slug)) throw badRequest("invalid project slug");
+
+    if (parts.length === 3) {
+      if (req.method === "GET") {
+        const project = getProjectRow(db, slug);
+        const [docs, memories] = await Promise.all([core.listDocs(db, slug), core.listMemories(db, slug)]);
+        return sendJson(res, 200, { slug, id: project.id, docs, memories });
+      }
+      if (req.method === "DELETE") return sendJson(res, 200, await core.deleteProject(db, slug));
+      throw methodNotAllowed();
+    }
+
+    if (parts[3] === "docs") {
+      if (req.method === "GET") return sendJson(res, 200, await core.listDocs(db, slug));
+      throw methodNotAllowed();
+    }
+    if (parts[3] === "doc") {
+      const relPath = url.searchParams.get("path");
+      if (!relPath) throw badRequest("path query param required");
+      if (req.method === "GET") return sendJson(res, 200, await core.readNote(db, slug, relPath));
+      if (req.method === "PUT") {
+        const body = await readJson(req);
+        return sendJson(res, 200, await core.saveNote(db, slug, relPath, body.content ?? ""));
+      }
+      if (req.method === "DELETE") return sendJson(res, 200, await core.deleteNote(db, slug, relPath));
+      throw methodNotAllowed();
+    }
+    if (parts[3] === "sections") {
+      if (req.method === "POST") {
+        const body = await readJson(req);
+        return sendJson(
+          res,
+          200,
+          await core.updateSection(db, slug, body.path, body.heading_path, body.content),
+        );
+      }
+      throw methodNotAllowed();
+    }
+    if (parts[3] === "memories") {
+      if (req.method === "GET" && !parts[4]) return sendJson(res, 200, await core.listMemories(db, slug));
+      if (req.method === "POST") {
+        const body = await readJson(req);
+        return sendJson(res, 201, await core.addMemory(db, slug, body.text, body.target_path));
+      }
+      if (req.method === "DELETE" && parts[4]) {
+        return sendJson(res, 200, await core.deleteMemory(db, slug, Number(parts[4])));
+      }
+      throw methodNotAllowed();
+    }
+    throw notFound();
+  }
+
+  if (parts[1] === "search" && req.method === "POST") {
+    const body = await readJson(req);
+    const limit = body.limit ?? 8;
+    let hits;
+    if (body.kind === "memories") {
+      hits = await core.searchMemories(db, body.project, body.query, limit);
+    } else if (body.kind === "notes") {
+      hits = await core.searchNotes(db, body.project, body.query, limit);
+    } else {
+      const [memories, notes] = await Promise.all([
+        core.searchMemories(db, body.project, body.query, limit),
+        core.searchNotes(db, body.project, body.query, limit),
+      ]);
+      hits = [...memories, ...notes].sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    return sendJson(res, 200, hits);
+  }
+
+  throw notFound();
+}
+
+function authorized(req, cfg) {
+  const expected = `Bearer ${cfg.apiKey}`;
+  const got = req.headers.authorization ?? "";
+  if (got.length !== expected.length) return false;
+  return timingSafeEqual(Buffer.from(got), Buffer.from(expected));
+}
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > 10 * 1024 * 1024) {
+        reject(Object.assign(new Error("body too large"), { status: 413 }));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => {
+      if (!chunks.length) return resolve({});
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      } catch {
+        reject(Object.assign(new Error("invalid json body"), { status: 400 }));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj, null, 2);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(body);
+}
+
+const badRequest = (m) => Object.assign(new Error(m), { status: 400 });
+const notFound = () => Object.assign(new Error("not found"), { status: 404 });
+const methodNotAllowed = () => Object.assign(new Error("method not allowed"), { status: 405 });

package/src/store/db.js

@@ -0,0 +1,107 @@
+import { DatabaseSync } from "node:sqlite";
+import { DB_PATH } from "../paths.js";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS projects (
+  id INTEGER PRIMARY KEY,
+  slug TEXT UNIQUE NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS docs (
+  id INTEGER PRIMARY KEY,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  rel_path TEXT NOT NULL,
+  title TEXT NOT NULL,
+  content_hash TEXT,
+  mtime INTEGER NOT NULL,
+  indexed_at INTEGER NOT NULL,
+  UNIQUE(project_id, rel_path)
+);
+
+CREATE TABLE IF NOT EXISTS sections (
+  id INTEGER PRIMARY KEY,
+  doc_id INTEGER NOT NULL REFERENCES docs(id) ON DELETE CASCADE,
+  heading_path TEXT NOT NULL,
+  content TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(doc_id, heading_path)
+);
+
+CREATE TABLE IF NOT EXISTS memories (
+  id INTEGER PRIMARY KEY,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  text TEXT NOT NULL,
+  target_type TEXT NOT NULL CHECK (target_type IN ('standalone','doc','section')),
+  target_path TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS embeddings (
+  id INTEGER PRIMARY KEY,
+  owner_type TEXT NOT NULL CHECK (owner_type IN ('memory','section')),
+  owner_id INTEGER NOT NULL,
+  dim INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  vec BLOB NOT NULL,
+  UNIQUE(owner_type, owner_id)
+);
+
+CREATE TABLE IF NOT EXISTS project_embeddings (
+  project_id INTEGER PRIMARY KEY REFERENCES projects(id) ON DELETE CASCADE,
+  dim INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  vec BLOB NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  text,
+  content='memories',
+  content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, text) VALUES (new.id, new.text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text) VALUES ('delete', old.id, old.text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text) VALUES ('delete', old.id, old.text);
+  INSERT INTO memories_fts(rowid, text) VALUES (new.id, new.text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_embeddings_ad AFTER DELETE ON memories BEGIN
+  DELETE FROM embeddings WHERE owner_type = 'memory' AND owner_id = old.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sections_embeddings_ad AFTER DELETE ON sections BEGIN
+  DELETE FROM embeddings WHERE owner_type = 'section' AND owner_id = old.id;
+END;
+`;
+
+function migrate(db) {
+  const hasDocs =
+    db.prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'docs'").get().n > 0;
+  if (!hasDocs) return;
+  const docCols = db.prepare("PRAGMA table_info(docs)").all().map((c) => c.name);
+  if (!docCols.includes("content_hash")) {
+    db.exec("ALTER TABLE docs ADD COLUMN content_hash TEXT");
+  }
+}
+
+export function open() {
+  const db = new DatabaseSync(DB_PATH);
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  ensureSchema(db);
+  return db;
+}
+
+export function ensureSchema(db) {
+  db.exec(SCHEMA);
+  migrate(db);
+}

package/test/markdown.test.js

@@ -0,0 +1,32 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseMarkdown, docTitle, replaceSectionBody } from "../src/markdown.js";
+
+test("parseMarkdown builds nested heading paths and excludes H1", () => {
+  const md = "# Title\n\nintro\n\n## Arch\n\ntop\n\n### Arch::Storage\n\nnested\n";
+  const parsed = parseMarkdown(md);
+  const paths = parsed.sections.map((s) => s.path);
+  assert.deepEqual(paths, ["", "Arch", "Arch::Arch::Storage"]);
+});
+
+test("parseMarkdown detects frontmatter", () => {
+  const parsed = parseMarkdown("---\ntitle: My Doc\n---\n\nbody");
+  assert.equal(parsed.frontmatter, "---\ntitle: My Doc\n---");
+  assert.equal(docTitle(parsed, "fallback.md"), "My Doc");
+});
+
+test("docTitle falls back to H1 then filename", () => {
+  assert.equal(docTitle(parseMarkdown("# H\n"), "x.md"), "H");
+  assert.equal(docTitle(parseMarkdown("no heads"), "x.md"), "x");
+});
+
+test("replaceSectionBody splices only the target section", () => {
+  const md = "# T\n\n## A\n\nold body\n\n## B\n\nkeep me\n";
+  const parsed = parseMarkdown(md);
+  const secA = parsed.sections.find((s) => s.path === "A");
+  const out = replaceSectionBody(md, secA, "new body");
+  assert.match(out, /new body/);
+  assert.doesNotMatch(out, /old body/);
+  assert.match(out, /keep me/);
+  assert.match(out, /^# T/);
+});

package/test/mcp.test.js

@@ -0,0 +1,74 @@
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+let handleRpc;
+let tools;
+let db;
+let open;
+
+const EXPECTED_TOOLS = [
+  "mindroot_list_projects",
+  "mindroot_search_projects",
+  "mindroot_search_memories",
+  "mindroot_search_notes",
+  "mindroot_save_memory",
+  "mindroot_delete_memory",
+  "mindroot_list_notes",
+  "mindroot_read_note",
+  "mindroot_save_note",
+  "mindroot_update_section",
+  "mindroot_delete_note",
+];
+
+before(async () => {
+  process.env.MINDROOT_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "mindroot-mcp-"));
+  ({ handleRpc, tools } = await import("../src/mcp.js"));
+  ({ open } = await import("../src/store/db.js"));
+  db = open();
+});
+
+function rpc(method, params) {
+  return handleRpc(db, { jsonrpc: "2.0", id: 1, method, params });
+}
+
+const call = (name, args) => rpc("tools/call", { name, arguments: args });
+
+test("tools/list exposes exactly the expected surface", async () => {
+  const res = await rpc("tools/list", {});
+  assert.deepEqual(res.body.result.tools.map((t) => t.name).sort(), [...EXPECTED_TOOLS].sort());
+  for (const t of res.body.result.tools) {
+    assert.ok(t.description.length > 20, `${t.name} needs a description`);
+  }
+});
+
+test("notifications get 202 with no body", async () => {
+  const res = await handleRpc(db, { jsonrpc: "2.0", method: "notify/x" });
+  assert.equal(res.status, 202);
+  assert.equal(res.body, null);
+});
+
+test("unknown tool returns clean error", async () => {
+  const res = await call("mindroot_nope", {});
+  assert.equal(res.body.result.isError, true);
+  assert.match(res.body.result.content[0].text, /unknown tool/);
+});
+
+test("search without project is a clean isError", async () => {
+  const res = await call("mindroot_search_memories", { query: "x" });
+  assert.equal(res.body.result.isError, true);
+  assert.match(res.body.result.content[0].text, /project is required/);
+});
+
+test("invalid slug is rejected before any lookup", async () => {
+  const res = await call("mindroot_search_memories", { project: "../evil", query: "x" });
+  assert.equal(res.body.result.isError, true);
+  assert.match(res.body.result.content[0].text, /invalid project slug/);
+});
+
+test("unknown project is a clean error", async () => {
+  const res = await call("mindroot_search_memories", { project: "ghost", query: "x" });
+  assert.match(res.body.result.content[0].text, /unknown project: ghost/);
+});

package/test/search.test.js

@@ -0,0 +1,87 @@
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+let open;
+
+function vec(arr) {
+  const f = new Float32Array(arr);
+  return Buffer.from(f.buffer, f.byteOffset, f.byteLength);
+}
+
+async function freshDb(name) {
+  process.env.MINDROOT_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "mindroot-search-"));
+  ({ open } = await import("../src/store/db.js"));
+  return open();
+}
+
+before(freshDb);
+
+test("rankMemories blends vector and keyword scores, respects limit", async () => {
+  const { rankMemories } = await import("../src/search.js");
+  const db = open();
+  db.prepare("INSERT INTO projects (slug, created_at) VALUES ('p1', 1)").run();
+  const pid = db.prepare("SELECT id FROM projects WHERE slug='p1'").get().id;
+
+  const ins = db.prepare(
+    "INSERT INTO memories (project_id, text, target_type, created_at, updated_at) VALUES (?, ?, 'standalone', 1, 1)",
+  );
+  const m1 = Number(ins.run(pid, "deploy by tag push to production").lastInsertRowid);
+  const m2 = Number(ins.run(pid, "unrelated note about cooking pasta").lastInsertRowid);
+  const emb = db.prepare(
+    "INSERT INTO embeddings (owner_type, owner_id, dim, model, vec) VALUES ('memory', ?, ?, 'm', ?)",
+  );
+  emb.run(m1, 2, vec([1, 0]));
+  emb.run(m2, 2, vec([0, 1]));
+
+  // query vector aligned with m1; keywords also match m1
+  const hits = rankMemories(db, pid, new Float32Array([1, 0]), "deploy production", 8);
+  assert.equal(hits[0].id, m1);
+  assert.ok(hits[0].score > 0.75);
+  assert.equal(hits.length, 2);
+
+  assert.equal(rankMemories(db, pid, new Float32Array([1, 0]), "x", 1).length, 1);
+
+  // embeddings with wrong dim are skipped, not crashed on
+  emb.run(Number(ins.run(pid, "dim mismatch").lastInsertRowid), 3, vec([1, 0, 0]));
+  assert.equal(rankMemories(db, pid, new Float32Array([1, 0]), "x", 10).some((h) => h.text === "dim mismatch"), false);
+});
+
+test("rankNotes ranks sections scoped to the project", async () => {
+  const { rankNotes } = await import("../src/search.js");
+  const db = open();
+  db.prepare("INSERT INTO projects (slug, created_at) VALUES ('p2', 2)").run();
+  const pid = db.prepare("SELECT id FROM projects WHERE slug='p2'").get().id;
+  db.prepare(
+    "INSERT INTO docs (project_id, rel_path, title, content_hash, mtime, indexed_at) VALUES (?, 'a.md', 'A', NULL, 1, 1)",
+  ).run(pid);
+  const docId = db.prepare("SELECT id FROM docs").get().id;
+  db.prepare(
+    "INSERT INTO sections (doc_id, heading_path, content, updated_at) VALUES (?, 'Deploy', 'tag push deploys', 1)",
+  ).run(docId);
+  const secId = db.prepare("SELECT id FROM sections").get().id;
+  db.prepare(
+    "INSERT INTO embeddings (owner_type, owner_id, dim, model, vec) VALUES ('section', ?, ?, 'm', ?)",
+  ).run(secId, 2, vec([0.9, 0.1]));
+
+  const hits = rankNotes(db, pid, new Float32Array([0.9, 0.1]), 8);
+  assert.equal(hits[0].kind, "note_section");
+  assert.equal(hits[0].target, "a.md::Deploy");
+});
+
+test("rankProjects applies token-overlap bonus and threshold", async () => {
+  const { rankProjects } = await import("../src/search.js");
+  const db = open();
+  db.prepare("INSERT INTO projects (slug, created_at) VALUES ('proper-agent-memory', 3)").run();
+  db.prepare("INSERT INTO projects (slug, created_at) VALUES ('zzz', 3)").run();
+
+  const hits = rankProjects(db, new Float32Array([1, 0]), "mem-agent-mcp");
+  const top = hits.find((h) => h.project === "proper-agent-memory");
+  assert.ok(top, "fuzzy name should match");
+  assert.ok(Math.abs(top.score - (0.55 + 0.4 * (2 / 3))) < 1e-9);
+
+  // no token overlap + no vector => excluded
+  assert.equal(hits.some((h) => h.project === "zzz"), false);
+});

package/test/store.test.js

@@ -0,0 +1,34 @@
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+let dir;
+
+before(async () => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "mindroot-store-"));
+  process.env.MINDROOT_DIR = dir;
+});
+
+test("open() creates the full schema and is idempotent", async () => {
+  const { open } = await import("../src/store/db.js");
+  const db = open();
+
+  const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map((r) => r.name);
+  for (const t of ["projects", "docs", "sections", "memories", "embeddings", "project_embeddings"]) {
+    assert.ok(tables.includes(t), `missing table ${t}`);
+  }
+  assert.ok(tables.includes("memories_fts"));
+
+  db.prepare("INSERT INTO projects (slug, created_at) VALUES ('p1', 1)").run();
+  db.prepare(
+    "INSERT INTO memories (project_id, text, target_type, created_at, updated_at) VALUES (1, 'fts indexed', 'standalone', 1, 1)",
+  ).run();
+  const hits = db.prepare("SELECT rowid FROM memories_fts WHERE memories_fts MATCH 'indexed'").all();
+  assert.equal(hits.length, 1);
+
+  db.close();
+  const db2 = open();
+  assert.equal(db2.prepare("SELECT COUNT(*) n FROM memories").get().n, 1);
+});