engramx 0.1.1 → 0.2.1

package/dist/{chunk-44GN6IRQ.js → chunk-22ADJYQ5.js}

@@ -1,6 +1,7 @@
 // src/core.ts
-import { join as join3, resolve as resolve2 } from "path";
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4 } from "fs";
+import { join as join4, resolve as resolve2 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync2, unlinkSync } from "fs";
+import { homedir } from "os";
 
 // src/graph/store.ts
 import initSqlJs from "sql.js";
@@ -164,7 +165,7 @@ var GraphStore = class _GraphStore {
       `SELECT n.*, COUNT(*) as degree
        FROM nodes n
        JOIN edges e ON e.source = n.id OR e.target = n.id
-       WHERE n.kind NOT IN ('file', 'import', 'module')
+       WHERE n.kind NOT IN ('file', 'import', 'module', 'concept')
        GROUP BY n.id
        ORDER BY degree DESC
        LIMIT ?`
@@ -293,7 +294,34 @@ var GraphStore = class _GraphStore {
   }
 };
 
+// src/graph/render-utils.ts
+function sliceGraphemeSafe(s, max) {
+  if (max <= 0) return "";
+  if (s.length <= max) return s;
+  let cut = max;
+  const code = s.charCodeAt(cut - 1);
+  if (code >= 55296 && code <= 56319) cut--;
+  return s.slice(0, cut);
+}
+function truncateGraphemeSafe(s, max) {
+  if (max <= 0) return "";
+  if (s.length <= max) return s;
+  let cut = max - 1;
+  if (cut <= 0) return "";
+  const code = s.charCodeAt(cut - 1);
+  if (code >= 55296 && code <= 56319) cut--;
+  return s.slice(0, cut) + "\u2026";
+}
+
 // src/graph/query.ts
+var MISTAKE_SCORE_BOOST = 2.5;
+var KEYWORD_SCORE_DOWNWEIGHT = 0.5;
+var MAX_MISTAKE_LABEL_CHARS = 500;
+function isHiddenKeyword(node) {
+  if (node.kind !== "concept") return false;
+  const meta = node.metadata;
+  return meta?.subkind === "keyword";
+}
 var CHARS_PER_TOKEN = 4;
 function scoreNodes(store, terms) {
   const allNodes = store.getAllNodes();
@@ -306,7 +334,11 @@ function scoreNodes(store, terms) {
       if (label.includes(t)) score += 2;
       if (file.includes(t)) score += 1;
     }
-    if (score > 0) scored.push({ score, node });
+    if (score > 0) {
+      if (node.kind === "mistake") score *= MISTAKE_SCORE_BOOST;
+      if (isHiddenKeyword(node)) score *= KEYWORD_SCORE_DOWNWEIGHT;
+      scored.push({ score, node });
+    }
   }
   return scored.sort((a, b) => b.score - a.score);
 }
@@ -321,6 +353,12 @@ function queryGraph(store, question, options = {}) {
   for (const n of startNodes) store.incrementQueryCount(n.id);
   const visited = new Set(startNodes.map((n) => n.id));
   const collectedEdges = [];
+  const shouldSkipEdgeFrom = (currentNodeId, edge) => {
+    if (edge.relation !== "triggered_by") return false;
+    const currentNode = store.getNode(currentNodeId);
+    if (!currentNode) return false;
+    return !isHiddenKeyword(currentNode);
+  };
   if (mode === "bfs") {
     let frontier = new Set(startNodes.map((n) => n.id));
     for (let d = 0; d < depth; d++) {
@@ -328,6 +366,7 @@ function queryGraph(store, question, options = {}) {
       for (const nid of frontier) {
         const neighbors = store.getNeighbors(nid);
         for (const { node, edge } of neighbors) {
+          if (shouldSkipEdgeFrom(nid, edge)) continue;
           if (!visited.has(node.id)) {
             nextFrontier.add(node.id);
             collectedEdges.push(edge);
@@ -344,6 +383,7 @@ function queryGraph(store, question, options = {}) {
       if (d > depth) continue;
       const neighbors = store.getNeighbors(id);
       for (const { node, edge } of neighbors) {
+        if (shouldSkipEdgeFrom(id, edge)) continue;
         if (!visited.has(node.id)) {
           visited.add(node.id);
           stack.push({ id: node.id, d: d + 1 });
@@ -420,12 +460,28 @@ function shortestPath(store, sourceTerm, targetTerm, maxHops = 8) {
 function renderSubgraph(nodes, edges, tokenBudget) {
   const charBudget = tokenBudget * CHARS_PER_TOKEN;
   const lines = [];
+  const mistakes2 = nodes.filter((n) => n.kind === "mistake");
+  const visible = nodes.filter(
+    (n) => n.kind !== "mistake" && !isHiddenKeyword(n)
+  );
+  const hiddenKeywordIds = new Set(
+    nodes.filter(isHiddenKeyword).map((n) => n.id)
+  );
+  if (mistakes2.length > 0) {
+    lines.push("\u26A0\uFE0F PAST MISTAKES (relevant to your query):");
+    for (const m of mistakes2) {
+      const label = truncateGraphemeSafe(m.label, MAX_MISTAKE_LABEL_CHARS);
+      const confNote = m.confidence === "EXTRACTED" ? "" : ` [confidence ${m.confidenceScore}]`;
+      lines.push(`  - ${label} (from ${m.sourceFile})${confNote}`);
+    }
+    lines.push("");
+  }
   const degreeMap = /* @__PURE__ */ new Map();
   for (const e of edges) {
     degreeMap.set(e.source, (degreeMap.get(e.source) ?? 0) + 1);
     degreeMap.set(e.target, (degreeMap.get(e.target) ?? 0) + 1);
   }
-  const sorted = [...nodes].sort(
+  const sorted = [...visible].sort(
     (a, b) => (degreeMap.get(b.id) ?? 0) - (degreeMap.get(a.id) ?? 0)
   );
   for (const n of sorted) {
@@ -433,7 +489,18 @@ function renderSubgraph(nodes, edges, tokenBudget) {
       `NODE ${n.label} [${n.kind}] src=${n.sourceFile} ${n.sourceLocation ?? ""}`
     );
   }
+  const skillConceptIds = new Set(
+    nodes.filter(
+      (n) => n.kind === "concept" && n.metadata?.subkind === "skill"
+    ).map((n) => n.id)
+  );
   for (const e of edges) {
+    if (hiddenKeywordIds.has(e.source) || hiddenKeywordIds.has(e.target)) {
+      continue;
+    }
+    if (e.relation === "similar_to" && skillConceptIds.has(e.source) && skillConceptIds.has(e.target)) {
+      continue;
+    }
     const srcNode = nodes.find((n) => n.id === e.source);
     const tgtNode = nodes.find((n) => n.id === e.target);
     if (srcNode && tgtNode) {
@@ -445,7 +512,7 @@ function renderSubgraph(nodes, edges, tokenBudget) {
   }
   let output = lines.join("\n");
   if (output.length > charBudget) {
-    output = output.slice(0, charBudget) + `
+    output = sliceGraphemeSafe(output, charBudget) + `
 ... (truncated to ~${tokenBudget} token budget)`;
   }
   return output;
@@ -1031,34 +1098,358 @@ function learnFromSession(text, sourceLabel = "session") {
   return mineText(text, sourceLabel);
 }
 
+// src/miners/skills-miner.ts
+import {
+  existsSync as existsSync4,
+  readFileSync as readFileSync4,
+  readdirSync as readdirSync3,
+  realpathSync as realpathSync2,
+  statSync
+} from "fs";
+import { basename as basename3, dirname as dirname2, join as join3 } from "path";
+function makeId4(...parts) {
+  return parts.filter(Boolean).join("_").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_|_$/g, "").toLowerCase().slice(0, 120);
+}
+function parseFrontmatter(content) {
+  if (!content.startsWith("---")) {
+    return { data: {}, body: content, parseOk: false };
+  }
+  const closeMatch = content.slice(3).match(/\n---\s*(\n|$)/);
+  if (!closeMatch || closeMatch.index === void 0) {
+    return { data: {}, body: content, parseOk: false };
+  }
+  const yamlBlock = content.slice(3, 3 + closeMatch.index).trim();
+  const bodyStart = 3 + closeMatch.index + closeMatch[0].length;
+  const body = content.slice(bodyStart);
+  try {
+    const data = parseYaml(yamlBlock);
+    return { data, body, parseOk: true };
+  } catch {
+    return { data: {}, body, parseOk: false };
+  }
+}
+function parseYaml(block) {
+  const data = {};
+  const lines = block.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith("#")) {
+      i++;
+      continue;
+    }
+    const topMatch = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!topMatch) {
+      throw new Error(`YAML parse: unexpected line ${i}: ${line}`);
+    }
+    const [, key, rest] = topMatch;
+    if (rest === ">" || rest === "|") {
+      const style = rest;
+      const collected = [];
+      i++;
+      while (i < lines.length) {
+        const next = lines[i];
+        if (next === "" || /^\s/.test(next)) {
+          collected.push(next.replace(/^ {2}/, "").replace(/^\t/, ""));
+          i++;
+        } else {
+          break;
+        }
+      }
+      data[key] = style === ">" ? collected.filter((l) => l.trim()).join(" ").trim() : collected.join("\n").trim();
+    } else if (rest === "") {
+      const nested = {};
+      i++;
+      while (i < lines.length && /^\s+\S/.test(lines[i])) {
+        const childMatch = lines[i].match(
+          /^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/
+        );
+        if (childMatch) {
+          nested[childMatch[1]] = stripQuotes(childMatch[2]);
+        }
+        i++;
+      }
+      data[key] = nested;
+    } else {
+      data[key] = stripQuotes(rest);
+      i++;
+    }
+  }
+  return data;
+}
+function stripQuotes(s) {
+  const trimmed = s.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if (first === '"' && last === '"') {
+    return trimmed.slice(1, -1).replace(
+      /\\u([0-9a-fA-F]{4})/g,
+      (_, hex) => String.fromCharCode(parseInt(hex, 16))
+    ).replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\\\/g, "\\");
+  }
+  if (first === "'" && last === "'") {
+    return trimmed.slice(1, -1).replace(/''/g, "'");
+  }
+  return trimmed;
+}
+var QUOTED_PHRASE_RE = /[\u0022\u0027\u201C\u201D\u2018\u2019]([^\u0022\u0027\u201C\u201D\u2018\u2019\n]{4,100}?)[\u0022\u0027\u201C\u201D\u2018\u2019]/g;
+var USE_WHEN_RE = /\bUse when\s+(.+?)(?=\.\s+[A-Z]|[\n\r]|$)/g;
+function extractTriggers(text) {
+  const triggers = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(QUOTED_PHRASE_RE)) {
+    const t = m[1]?.trim();
+    if (t && t.length >= 4) triggers.add(t);
+  }
+  for (const m of text.matchAll(USE_WHEN_RE)) {
+    const t = m[1]?.trim().replace(/[.,;]+$/, "");
+    if (t && t.length > 0 && t.length < 120) triggers.add(t);
+  }
+  return [...triggers];
+}
+function extractRelatedSkills(body) {
+  const sectionMatch = body.match(
+    /##\s*Related Skills\s*\r?\n([\s\S]*?)(?=\r?\n##|\r?\n#[^#]|$)/i
+  );
+  if (!sectionMatch) return [];
+  const section = sectionMatch[1];
+  const names = [];
+  for (const line of section.split(/\r?\n/)) {
+    const m = line.match(/^[\s]*[-*+]\s+`?([a-z][a-z0-9-]*)`?/i);
+    if (m) names.push(m[1].toLowerCase());
+  }
+  return [...new Set(names)];
+}
+function discoverSkillFiles(skillsDir) {
+  if (!existsSync4(skillsDir)) return [];
+  let entries;
+  try {
+    entries = readdirSync3(skillsDir, {
+      withFileTypes: true,
+      encoding: "utf-8"
+    });
+  } catch {
+    return [];
+  }
+  const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+  const results = [];
+  for (const entry of sorted) {
+    if (entry.name.startsWith(".")) continue;
+    let isDir = entry.isDirectory();
+    if (entry.isSymbolicLink()) {
+      try {
+        const resolved = realpathSync2(join3(skillsDir, entry.name));
+        isDir = statSync(resolved).isDirectory();
+      } catch {
+        continue;
+      }
+    }
+    if (!isDir) continue;
+    const skillMdPath = join3(skillsDir, entry.name, "SKILL.md");
+    if (existsSync4(skillMdPath)) {
+      results.push(skillMdPath);
+    }
+  }
+  return results;
+}
+function mineSkills(skillsDir) {
+  const result = {
+    nodes: [],
+    edges: [],
+    skillCount: 0,
+    anomalies: []
+  };
+  const skillFiles = discoverSkillFiles(skillsDir);
+  if (skillFiles.length === 0) return result;
+  const now = Date.now();
+  const keywordIds = /* @__PURE__ */ new Set();
+  const skillIdByDirName = /* @__PURE__ */ new Map();
+  const pendingRelated = [];
+  for (const skillPath of skillFiles) {
+    let content;
+    try {
+      content = readFileSync4(skillPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const skillDirName = basename3(dirname2(skillPath));
+    const { data, body, parseOk } = parseFrontmatter(content);
+    const hasFrontmatter = parseOk && Object.keys(data).length > 0;
+    let name;
+    let description;
+    let version;
+    if (hasFrontmatter) {
+      name = String(data.name ?? skillDirName);
+      description = String(data.description ?? "");
+      const meta = data.metadata;
+      if (meta && typeof meta === "object" && "version" in meta) {
+        version = String(meta.version);
+      }
+    } else {
+      result.anomalies.push(skillPath);
+      const headingMatch = content.match(/^#\s+(.+)$/m);
+      name = headingMatch?.[1]?.trim() ?? skillDirName;
+      const paragraphs = content.split(/\r?\n\s*\r?\n/).map((p) => p.trim()).filter((p) => p && !p.startsWith("#"));
+      description = paragraphs[0] ?? "";
+    }
+    const skillId = makeId4("skill", skillDirName);
+    skillIdByDirName.set(skillDirName.toLowerCase(), skillId);
+    const sourceFileRel = `${skillDirName}/SKILL.md`;
+    const sizeLines = content.split("\n").length;
+    result.nodes.push({
+      id: skillId,
+      label: name,
+      kind: "concept",
+      sourceFile: sourceFileRel,
+      sourceLocation: skillPath,
+      confidence: "EXTRACTED",
+      confidenceScore: 1,
+      lastVerified: now,
+      queryCount: 0,
+      metadata: {
+        miner: "skills",
+        subkind: "skill",
+        description: truncateGraphemeSafe(description, 500),
+        sizeLines,
+        hasFrontmatter,
+        version,
+        skillDir: skillDirName
+      }
+    });
+    result.skillCount++;
+    const triggers = extractTriggers(description + "\n\n" + body);
+    for (const trigger of triggers) {
+      const normalized = trigger.toLowerCase().trim();
+      if (normalized.length === 0 || normalized.length > 120) continue;
+      const keywordId = makeId4("keyword", normalized);
+      if (!keywordIds.has(keywordId)) {
+        result.nodes.push({
+          id: keywordId,
+          label: trigger,
+          kind: "concept",
+          sourceFile: sourceFileRel,
+          sourceLocation: null,
+          confidence: "EXTRACTED",
+          confidenceScore: 1,
+          lastVerified: now,
+          queryCount: 0,
+          metadata: { miner: "skills", subkind: "keyword" }
+        });
+        keywordIds.add(keywordId);
+      }
+      result.edges.push({
+        source: keywordId,
+        target: skillId,
+        relation: "triggered_by",
+        confidence: "EXTRACTED",
+        confidenceScore: 1,
+        sourceFile: sourceFileRel,
+        sourceLocation: skillPath,
+        lastVerified: now,
+        metadata: { miner: "skills" }
+      });
+    }
+    if (hasFrontmatter || body.length > 0) {
+      const relatedNames = extractRelatedSkills(body);
+      for (const relatedName of relatedNames) {
+        pendingRelated.push({ fromId: skillId, toName: relatedName });
+      }
+    }
+  }
+  for (const { fromId, toName } of pendingRelated) {
+    const toId = skillIdByDirName.get(toName.toLowerCase());
+    if (toId && toId !== fromId) {
+      result.edges.push({
+        source: fromId,
+        target: toId,
+        relation: "similar_to",
+        confidence: "INFERRED",
+        confidenceScore: 0.8,
+        sourceFile: "SKILL.md",
+        sourceLocation: null,
+        lastVerified: Date.now(),
+        metadata: { miner: "skills", via: "related_skills_section" }
+      });
+    }
+  }
+  return result;
+}
+
 // src/core.ts
 var ENGRAM_DIR = ".engram";
 var DB_FILE = "graph.db";
+var LOCK_FILE = "init.lock";
+var DEFAULT_SKILLS_DIR = join4(homedir(), ".claude", "skills");
 function getDbPath(projectRoot) {
-  return join3(projectRoot, ENGRAM_DIR, DB_FILE);
+  return join4(projectRoot, ENGRAM_DIR, DB_FILE);
 }
 async function getStore(projectRoot) {
   return GraphStore.open(getDbPath(projectRoot));
 }
-async function init(projectRoot) {
+async function init(projectRoot, options = {}) {
   const root = resolve2(projectRoot);
   const start = Date.now();
-  mkdirSync2(join3(root, ENGRAM_DIR), { recursive: true });
-  const { nodes, edges, fileCount, totalLines } = extractDirectory(root);
-  const gitResult = mineGitHistory(root);
-  const sessionResult = mineSessionHistory(root);
-  const allNodes = [...nodes, ...gitResult.nodes, ...sessionResult.nodes];
-  const allEdges = [...edges, ...gitResult.edges, ...sessionResult.edges];
-  const store = await getStore(root);
+  mkdirSync2(join4(root, ENGRAM_DIR), { recursive: true });
+  const lockPath = join4(root, ENGRAM_DIR, LOCK_FILE);
+  try {
+    writeFileSync2(lockPath, String(process.pid), { flag: "wx" });
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      throw new Error(
+        `engram: another init is running on ${root} (lock: ${lockPath}). If no other process is active, delete the lock file manually.`
+      );
+    }
+    throw err;
+  }
   try {
-    store.clearAll();
-    store.bulkUpsert(allNodes, allEdges);
-    store.setStat("last_mined", String(Date.now()));
-    store.setStat("project_root", root);
+    const { nodes, edges, fileCount, totalLines } = extractDirectory(root);
+    const gitResult = mineGitHistory(root);
+    const sessionResult = mineSessionHistory(root);
+    let skillCount = 0;
+    let skillNodes = [];
+    let skillEdges = [];
+    if (options.withSkills) {
+      const skillsDir = typeof options.withSkills === "string" ? options.withSkills : DEFAULT_SKILLS_DIR;
+      const skillsResult = mineSkills(skillsDir);
+      skillCount = skillsResult.skillCount;
+      skillNodes = skillsResult.nodes;
+      skillEdges = skillsResult.edges;
+    }
+    const allNodes = [
+      ...nodes,
+      ...gitResult.nodes,
+      ...sessionResult.nodes,
+      ...skillNodes
+    ];
+    const allEdges = [
+      ...edges,
+      ...gitResult.edges,
+      ...sessionResult.edges,
+      ...skillEdges
+    ];
+    const store = await getStore(root);
+    try {
+      store.clearAll();
+      store.bulkUpsert(allNodes, allEdges);
+      store.setStat("last_mined", String(Date.now()));
+      store.setStat("project_root", root);
+    } finally {
+      store.close();
+    }
+    return {
+      nodes: allNodes.length,
+      edges: allEdges.length,
+      fileCount,
+      totalLines,
+      timeMs: Date.now() - start,
+      skillCount
+    };
   } finally {
-    store.close();
+    try {
+      unlinkSync(lockPath);
+    } catch {
+    }
   }
-  return { nodes: allNodes.length, edges: allEdges.length, fileCount, totalLines, timeMs: Date.now() - start };
 }
 async function query(projectRoot, question, options = {}) {
   const store = await getStore(projectRoot);
@@ -1110,6 +1501,28 @@ async function learn(projectRoot, text, sourceLabel = "manual") {
   }
   return { nodesAdded: nodes.length };
 }
+async function mistakes(projectRoot, options = {}) {
+  const store = await getStore(projectRoot);
+  try {
+    let items = store.getAllNodes().filter((n) => n.kind === "mistake");
+    if (options.sinceDays !== void 0) {
+      const cutoff = Date.now() - options.sinceDays * 24 * 60 * 60 * 1e3;
+      items = items.filter((m) => m.lastVerified >= cutoff);
+    }
+    items.sort((a, b) => b.lastVerified - a.lastVerified);
+    const limit = options.limit ?? 20;
+    return items.slice(0, limit).map((m) => ({
+      id: m.id,
+      label: m.label,
+      confidence: m.confidence,
+      confidenceScore: m.confidenceScore,
+      sourceFile: m.sourceFile,
+      lastVerified: m.lastVerified
+    }));
+  } finally {
+    store.close();
+  }
+}
 async function benchmark(projectRoot, questions) {
   const root = resolve2(projectRoot);
   const store = await getStore(root);
@@ -1121,8 +1534,8 @@ async function benchmark(projectRoot, questions) {
       if (node.sourceFile && !seenFiles.has(node.sourceFile)) {
         seenFiles.add(node.sourceFile);
         try {
-          const fullPath = join3(root, node.sourceFile);
-          if (existsSync4(fullPath)) fullCorpusChars += readFileSync4(fullPath, "utf-8").length;
+          const fullPath = join4(root, node.sourceFile);
+          if (existsSync5(fullPath)) fullCorpusChars += readFileSync5(fullPath, "utf-8").length;
         } catch {
         }
       }
@@ -1143,8 +1556,8 @@ async function benchmark(projectRoot, questions) {
         let relevantChars = 0;
         for (const f of matchedFiles) {
           try {
-            const fullPath = join3(root, f);
-            if (existsSync4(fullPath)) relevantChars += readFileSync4(fullPath, "utf-8").length;
+            const fullPath = join4(root, f);
+            if (existsSync5(fullPath)) relevantChars += readFileSync5(fullPath, "utf-8").length;
           } catch {
           }
         }
@@ -1174,11 +1587,15 @@ async function benchmark(projectRoot, questions) {
 
 export {
   GraphStore,
+  sliceGraphemeSafe,
+  truncateGraphemeSafe,
+  MAX_MISTAKE_LABEL_CHARS,
   queryGraph,
   shortestPath,
   SUPPORTED_EXTENSIONS,
   extractFile,
   extractDirectory,
+  mineSkills,
   getDbPath,
   getStore,
   init,
@@ -1187,5 +1604,6 @@ export {
   godNodes,
   stats,
   learn,
+  mistakes,
   benchmark
 };