@velvetmonkey/flywheel-crank 0.8.0 → 0.9.0

package/dist/index.js

@@ -14,6 +14,10 @@ import matter from "gray-matter";
 
 // src/core/constants.ts
 var HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
+function estimateTokens(content) {
+  const str = typeof content === "string" ? content : JSON.stringify(content);
+  return Math.ceil(str.length / 4);
+}
 
 // src/core/writer.ts
 var SENSITIVE_PATH_PATTERNS = [
@@ -510,9 +514,12 @@ async function undoLastCommit(vaultPath2) {
 import {
   scanVaultEntities,
   getAllEntities,
+  getEntityName,
+  getEntityAliases,
   applyWikilinks,
   loadEntityCache,
-  saveEntityCache
+  saveEntityCache,
+  ENTITY_CACHE_VERSION
 } from "@velvetmonkey/vault-core";
 import path4 from "path";
 
@@ -1411,6 +1418,12 @@ async function initializeEntityIndex(vaultPath2) {
   try {
     const cached = await loadEntityCache(cacheFile);
     if (cached) {
+      const cacheVersion = cached._metadata.version ?? 1;
+      if (cacheVersion < ENTITY_CACHE_VERSION) {
+        console.error(`[Crank] Cache version ${cacheVersion} < ${ENTITY_CACHE_VERSION}, rebuilding...`);
+        await rebuildIndex(vaultPath2, cacheFile);
+        return;
+      }
       entityIndex = cached;
       indexReady = true;
       console.error(`[Crank] Loaded ${cached._metadata.total_entities} entities from cache`);
@@ -1569,33 +1582,51 @@ var STRICTNESS_CONFIGS = {
 var DEFAULT_STRICTNESS = "conservative";
 var MIN_SUGGESTION_SCORE = STRICTNESS_CONFIGS.balanced.minSuggestionScore;
 var MIN_MATCH_RATIO = STRICTNESS_CONFIGS.balanced.minMatchRatio;
-function scoreEntity(entityName, contentTokens, contentStems, config) {
-  const entityTokens = tokenize(entityName);
-  if (entityTokens.length === 0)
-    return 0;
-  const entityStems = entityTokens.map((t) => stem(t));
+function scoreNameAgainstContent(name, contentTokens, contentStems, config) {
+  const nameTokens = tokenize(name);
+  if (nameTokens.length === 0) {
+    return { score: 0, matchedWords: 0, exactMatches: 0, totalTokens: 0 };
+  }
+  const nameStems = nameTokens.map((t) => stem(t));
   let score = 0;
   let matchedWords = 0;
   let exactMatches = 0;
-  for (let i = 0; i < entityTokens.length; i++) {
-    const token = entityTokens[i];
-    const entityStem = entityStems[i];
+  for (let i = 0; i < nameTokens.length; i++) {
+    const token = nameTokens[i];
+    const nameStem = nameStems[i];
     if (contentTokens.has(token)) {
       score += config.exactMatchBonus;
       matchedWords++;
       exactMatches++;
-    } else if (contentStems.has(entityStem)) {
+    } else if (contentStems.has(nameStem)) {
       score += config.stemMatchBonus;
       matchedWords++;
     }
   }
-  if (entityTokens.length > 1) {
-    const matchRatio = matchedWords / entityTokens.length;
+  return { score, matchedWords, exactMatches, totalTokens: nameTokens.length };
+}
+function scoreEntity(entity, contentTokens, contentStems, config) {
+  const entityName = getEntityName(entity);
+  const aliases = getEntityAliases(entity);
+  const nameResult = scoreNameAgainstContent(entityName, contentTokens, contentStems, config);
+  let bestAliasResult = { score: 0, matchedWords: 0, exactMatches: 0, totalTokens: 0 };
+  for (const alias of aliases) {
+    const aliasResult = scoreNameAgainstContent(alias, contentTokens, contentStems, config);
+    if (aliasResult.score > bestAliasResult.score) {
+      bestAliasResult = aliasResult;
+    }
+  }
+  const bestResult = nameResult.score >= bestAliasResult.score ? nameResult : bestAliasResult;
+  const { score, matchedWords, exactMatches, totalTokens } = bestResult;
+  if (totalTokens === 0)
+    return 0;
+  if (totalTokens > 1) {
+    const matchRatio = matchedWords / totalTokens;
     if (matchRatio < config.minMatchRatio) {
       return 0;
     }
   }
-  if (config.requireMultipleMatches && entityTokens.length === 1) {
+  if (config.requireMultipleMatches && totalTokens === 1) {
     if (exactMatches === 0) {
       return 0;
     }
@@ -1628,7 +1659,7 @@ function suggestRelatedLinks(content, options = {}) {
   const scoredEntities = [];
   const directlyMatchedEntities = /* @__PURE__ */ new Set();
   for (const entity of entities) {
-    const entityName = typeof entity === "string" ? entity : entity.name;
+    const entityName = getEntityName(entity);
     if (!entityName)
       continue;
     if (entityName.length > MAX_ENTITY_LENGTH) {
@@ -1640,7 +1671,7 @@ function suggestRelatedLinks(content, options = {}) {
     if (linkedEntities.has(entityName.toLowerCase())) {
       continue;
     }
-    const score = scoreEntity(entityName, contentTokens, contentStems, config);
+    const score = scoreEntity(entity, contentTokens, contentStems, config);
     if (score > 0) {
       directlyMatchedEntities.add(entityName);
     }
@@ -1650,7 +1681,7 @@ function suggestRelatedLinks(content, options = {}) {
   }
   if (cooccurrenceIndex && directlyMatchedEntities.size > 0) {
     for (const entity of entities) {
-      const entityName = typeof entity === "string" ? entity : entity.name;
+      const entityName = getEntityName(entity);
       if (!entityName)
         continue;
       if (entityName.length > MAX_ENTITY_LENGTH)
@@ -1710,8 +1741,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `File not found: ${notePath}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         const { content: fileContent, frontmatter } = await readVaultFile(vaultPath2, notePath);
@@ -1720,8 +1753,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `Section not found: ${section}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         let { content: processedContent, wikilinkInfo } = maybeApplyWikilinks(content, skipWikilinks);
@@ -1761,15 +1796,20 @@ function registerMutationTools(server2, vaultPath2) {
           path: notePath,
           preview,
           gitCommit,
-          gitError
+          gitError,
+          tokensEstimate: 0
+          // Will be set below
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (error) {
         const result = {
           success: false,
           message: `Failed to add content: ${error instanceof Error ? error.message : String(error)}`,
-          path: notePath
+          path: notePath,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     }
@@ -1794,8 +1834,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `File not found: ${notePath}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         const { content: fileContent, frontmatter } = await readVaultFile(vaultPath2, notePath);
@@ -1804,8 +1846,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `Section not found: ${section}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         const removeResult = removeFromSection(
@@ -1819,8 +1863,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `No content matching "${pattern}" found in section "${sectionBoundary.name}"`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         await writeVaultFile(vaultPath2, notePath, removeResult.content, frontmatter);
@@ -1840,15 +1886,19 @@ function registerMutationTools(server2, vaultPath2) {
           path: notePath,
           preview: removeResult.removedLines.join("\n"),
           gitCommit,
-          gitError
+          gitError,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (error) {
         const result = {
           success: false,
           message: `Failed to remove content: ${error instanceof Error ? error.message : String(error)}`,
-          path: notePath
+          path: notePath,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     }
@@ -1877,8 +1927,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `File not found: ${notePath}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         const { content: fileContent, frontmatter } = await readVaultFile(vaultPath2, notePath);
@@ -1887,8 +1939,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `Section not found: ${section}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         let { content: processedReplacement, wikilinkInfo } = maybeApplyWikilinks(replacement, skipWikilinks);
@@ -1912,8 +1966,10 @@ function registerMutationTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `No content matching "${search}" found in section "${sectionBoundary.name}"`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         await writeVaultFile(vaultPath2, notePath, replaceResult.content, frontmatter);
@@ -1937,15 +1993,19 @@ function registerMutationTools(server2, vaultPath2) {
           path: notePath,
           preview: previewLines.join("\n"),
           gitCommit,
-          gitError
+          gitError,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (error) {
         const result = {
           success: false,
           message: `Failed to replace content: ${error instanceof Error ? error.message : String(error)}`,
-          path: notePath
+          path: notePath,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     }
@@ -2019,8 +2079,10 @@ function registerTaskTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `File not found: ${notePath}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         const { content: fileContent, frontmatter } = await readVaultFile(vaultPath2, notePath);
@@ -2031,8 +2093,10 @@ function registerTaskTools(server2, vaultPath2) {
             const result2 = {
               success: false,
               message: `Section not found: ${section}`,
-              path: notePath
+              path: notePath,
+              tokensEstimate: 0
             };
+            result2.tokensEstimate = estimateTokens(result2);
             return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
           }
           sectionBoundary = found;
@@ -2046,8 +2110,10 @@ function registerTaskTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `No task found matching "${task}"${section ? ` in section "${section}"` : ""}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         const toggleResult = toggleTask(fileContent, matchingTask.line);
@@ -2055,8 +2121,10 @@ function registerTaskTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: "Failed to toggle task",
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         await writeVaultFile(vaultPath2, notePath, toggleResult.content, frontmatter);
@@ -2078,15 +2146,19 @@ function registerTaskTools(server2, vaultPath2) {
           path: notePath,
           preview: `${checkbox} ${matchingTask.text}`,
           gitCommit,
-          gitError
+          gitError,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (error) {
         const result = {
           success: false,
           message: `Failed to toggle task: ${error instanceof Error ? error.message : String(error)}`,
-          path: notePath
+          path: notePath,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     }
@@ -2115,8 +2187,10 @@ function registerTaskTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `File not found: ${notePath}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         const { content: fileContent, frontmatter } = await readVaultFile(vaultPath2, notePath);
@@ -2125,8 +2199,10 @@ function registerTaskTools(server2, vaultPath2) {
           const result2 = {
             success: false,
             message: `Section not found: ${section}`,
-            path: notePath
+            path: notePath,
+            tokensEstimate: 0
           };
+          result2.tokensEstimate = estimateTokens(result2);
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         let { content: processedTask, wikilinkInfo } = maybeApplyWikilinks(task.trim(), skipWikilinks);
@@ -2166,15 +2242,19 @@ function registerTaskTools(server2, vaultPath2) {
           preview: taskLine + (infoLines.length > 0 ? `
 (${infoLines.join("; ")})` : ""),
           gitCommit,
-          gitError
+          gitError,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (error) {
         const result = {
           success: false,
           message: `Failed to add task: ${error instanceof Error ? error.message : String(error)}`,
-          path: notePath
+          path: notePath,
+          tokensEstimate: 0
         };
+        result.tokensEstimate = estimateTokens(result);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-crank",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Deterministic vault mutations for Obsidian via MCP",
   "type": "module",
   "main": "dist/index.js",
@@ -41,10 +41,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@velvetmonkey/vault-core": "^0.1.0",
+    "@velvetmonkey/vault-core": "^0.2.0",
     "gray-matter": "^4.0.3",
-    "zod": "^3.22.4",
-    "simple-git": "^3.22.0"
+    "simple-git": "^3.22.0",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",