clawvault 1.3.0 → 1.4.0

package/README.md

@@ -4,6 +4,18 @@
 
 Structured memory system for AI agents. Store, search, and link memories across sessions.
 
+> **Built for [OpenClaw](https://openclaw.ai)** — the AI agent framework. Works standalone too.
+
+## Install for OpenClaw Agents
+
+```bash
+# Install the skill (recommended for OpenClaw agents)
+clawhub install clawvault
+
+# Or install the CLI globally
+npm install -g clawvault
+```
+
 ## Requirements
 
 - **Node.js 18+**

package/bin/clawvault.js

@@ -16,7 +16,7 @@ import {
   findVault,
   hasQmd,
   QmdUnavailableError,
-  QMD_INSTALL_URL
+  QMD_INSTALL_COMMAND
 } from '../dist/index.js';
 
 const program = new Command();
@@ -66,13 +66,19 @@ async function runQmd(args) {
       if (code === 0) resolve();
       else reject(new Error(`qmd exited with code ${code}`));
     });
-    proc.on('error', reject);
+    proc.on('error', (err) => {
+      if (err?.code === 'ENOENT') {
+        reject(new QmdUnavailableError());
+      } else {
+        reject(err);
+      }
+    });
   });
 }
 
 function printQmdMissing() {
-  console.error(chalk.red('Error: qmd is not installed or not on PATH.'));
-  console.log(chalk.dim(`Install qmd: ${QMD_INSTALL_URL}`));
+  console.error(chalk.red('Error: ClawVault requires qmd.'));
+  console.log(chalk.dim(`Install: ${QMD_INSTALL_COMMAND}`));
 }
 
 program
@@ -100,31 +106,22 @@ program
       console.log(chalk.green('✓ Vault created'));
       console.log(chalk.dim(`  Categories: ${vault.getCategories().join(', ')}`));
 
-      const qmdAvailable = hasQmd();
-      
       // Always set up qmd collection (qmd is required)
       console.log(chalk.cyan('\nSetting up qmd collection...'));
-      if (!qmdAvailable) {
-        console.log(chalk.red('✗ qmd not found. Install qmd first:'));
-        console.log(chalk.dim(`  bun install -g qmd`));
-        console.log(chalk.dim(`  # or: npm install -g qmd`));
-        console.log(chalk.dim(`  Then run: qmd collection add ${vault.getQmdRoot()} --name ${vault.getQmdCollection()} --mask "**/*.md"`));
-      } else {
-        try {
-          await runQmd([
-            'collection',
-            'add',
-            vault.getQmdRoot(),
-            '--name',
-            vault.getQmdCollection(),
-            '--mask',
-            '**/*.md'
-          ]);
-          console.log(chalk.green('✓ qmd collection created'));
-        } catch (err) {
-          // Collection might already exist
-          console.log(chalk.yellow('⚠ qmd collection may already exist'));
-        }
+      try {
+        await runQmd([
+          'collection',
+          'add',
+          vault.getQmdRoot(),
+          '--name',
+          vault.getQmdCollection(),
+          '--mask',
+          '**/*.md'
+        ]);
+        console.log(chalk.green('✓ qmd collection created'));
+      } catch (err) {
+        // Collection might already exist
+        console.log(chalk.yellow('⚠ qmd collection may already exist'));
       }
       
       console.log(chalk.green('\n✅ ClawVault ready!\n'));
@@ -138,6 +135,20 @@ program
     }
   });
 
+// === SETUP ===
+program
+  .command('setup')
+  .description('Auto-discover and configure a ClawVault')
+  .action(async () => {
+    try {
+      const { setupCommand } = await import('../dist/commands/setup.js');
+      await setupCommand();
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
 // === STORE ===
 program
   .command('store')
@@ -174,14 +185,12 @@ program
       console.log(chalk.dim(`  Path: ${doc.path}`));
       
       // Auto-update qmd index unless --no-index
-      if (options.index !== false && hasQmd()) {
-        try {
-          const collection = vault.getQmdCollection();
-          await runQmd(collection ? ['update', '-c', collection] : ['update']);
-          if (options.embed) {
-            await runQmd(['embed']);
-          }
-        } catch { /* ignore qmd errors */ }
+      if (options.index !== false) {
+        const collection = vault.getQmdCollection();
+        await runQmd(collection ? ['update', '-c', collection] : ['update']);
+        if (options.embed) {
+          await runQmd(collection ? ['embed', '-c', collection] : ['embed']);
+        }
       }
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
@@ -203,11 +212,9 @@ program
       console.log(chalk.green(`✓ Captured: ${doc.id}`));
       
       // Auto-update qmd index unless --no-index
-      if (options.index !== false && hasQmd()) {
-        try {
-          const collection = vault.getQmdCollection();
-          await runQmd(collection ? ['update', '-c', collection] : ['update']);
-        } catch { /* ignore qmd errors */ }
+      if (options.index !== false) {
+        const collection = vault.getQmdCollection();
+        await runQmd(collection ? ['update', '-c', collection] : ['update']);
       }
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
@@ -317,7 +324,7 @@ program
         process.exit(1);
       }
       console.error(chalk.red(`Error: ${err.message}`));
-      console.log(chalk.dim(`\nTip: Install qmd for semantic search: ${QMD_INSTALL_URL}`));
+      console.log(chalk.dim(`\nTip: Install qmd: ${QMD_INSTALL_COMMAND}`));
       process.exit(1);
     }
   });
@@ -511,13 +518,9 @@ program
       
       if (options.qmd) {
         console.log(chalk.cyan('Updating qmd embeddings...'));
-        try {
-          const collection = vault.getQmdCollection();
-          await runQmd(collection ? ['update', '-c', collection] : ['update']);
-          console.log(chalk.green('✓ qmd updated'));
-        } catch {
-          console.log(chalk.yellow('⚠ qmd update failed'));
-        }
+        const collection = vault.getQmdCollection();
+        await runQmd(collection ? ['update', '-c', collection] : ['update']);
+        console.log(chalk.green('✓ qmd updated'));
       }
       
       console.log();
@@ -558,11 +561,9 @@ program
       console.log(chalk.green(`✓ Remembered (${type}): ${doc.id}`));
       
       // Auto-update qmd index unless --no-index
-      if (options.index !== false && hasQmd()) {
-        try {
-          const collection = vault.getQmdCollection();
-          await runQmd(collection ? ['update', '-c', collection] : ['update']);
-        } catch { /* ignore qmd errors */ }
+      if (options.index !== false) {
+        const collection = vault.getQmdCollection();
+        await runQmd(collection ? ['update', '-c', collection] : ['update']);
       }
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
@@ -608,11 +609,9 @@ program
       }
       
       // Auto-update qmd index unless --no-index
-      if (options.index !== false && hasQmd()) {
-        try {
-          const collection = vault.getQmdCollection();
-          await runQmd(collection ? ['update', '-c', collection] : ['update']);
-        } catch { /* ignore qmd errors */ }
+      if (options.index !== false) {
+        const collection = vault.getQmdCollection();
+        await runQmd(collection ? ['update', '-c', collection] : ['update']);
       }
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
@@ -652,6 +651,74 @@ program
     }
   });
 
+// === TEMPLATE ===
+const template = program
+  .command('template')
+  .description('Manage templates');
+
+template
+  .command('list')
+  .description('List available templates')
+  .option('-v, --vault <path>', 'Vault path')
+  .action(async (options) => {
+    try {
+      const { listTemplates } = await import('../dist/commands/template.js');
+      const templates = listTemplates({ vaultPath: options.vault });
+      if (templates.length === 0) {
+        console.log(chalk.yellow('No templates found.'));
+        return;
+      }
+      console.log(chalk.cyan('\n📄 Templates:\n'));
+      for (const name of templates) {
+        console.log(`- ${name}`);
+      }
+      console.log();
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+template
+  .command('create <name>')
+  .description('Create a file from a template')
+  .option('-t, --title <title>', 'Document title')
+  .option('-v, --vault <path>', 'Vault path')
+  .action(async (name, options) => {
+    try {
+      const { createFromTemplate } = await import('../dist/commands/template.js');
+      const result = createFromTemplate(name, {
+        title: options.title,
+        vaultPath: options.vault
+      });
+      console.log(chalk.green(`✓ Created from template: ${name}`));
+      console.log(chalk.dim(`  Output: ${result.outputPath}`));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+template
+  .command('add <file>')
+  .description('Add a custom template')
+  .requiredOption('--name <name>', 'Template name')
+  .option('-v, --vault <path>', 'Vault path')
+  .action(async (file, options) => {
+    try {
+      const { addTemplate } = await import('../dist/commands/template.js');
+      const result = addTemplate(file, {
+        name: options.name,
+        vaultPath: options.vault
+      });
+      console.log(chalk.green(`✓ Template added: ${result.name}`));
+      console.log(chalk.dim(`  Path: ${result.templatePath}`));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
 // === DOCTOR (health check) ===
 program
   .command('doctor')
@@ -667,7 +734,7 @@ program
       console.log(chalk.green('✓ qmd installed'));
     } else {
       console.log(chalk.red('✗ qmd not installed'));
-      console.log(chalk.dim(`  Install: bun install -g qmd`));
+      console.log(chalk.dim(`  Install: ${QMD_INSTALL_COMMAND}`));
       issues++;
     }
     
@@ -741,7 +808,10 @@ program
   .command('link [file]')
   .description('Auto-link entity mentions in markdown files')
   .option('--all', 'Link all files in vault')
+  .option('--backlinks <file>', 'Show backlinks to a file')
   .option('--dry-run', 'Show what would be linked without changing files')
+  .option('--orphans', 'List broken wiki-links')
+  .option('--rebuild', 'Rebuild backlinks index')
   .option('-v, --vault <path>', 'Vault path')
   .action(async (file, options) => {
     try {
@@ -752,7 +822,13 @@ program
       }
       
       const { linkCommand } = await import('../dist/commands/link.js');
-      await linkCommand(file, { all: options.all, dryRun: options.dryRun });
+      await linkCommand(file, {
+        all: options.all,
+        dryRun: options.dryRun,
+        backlinks: options.backlinks,
+        orphans: options.orphans,
+        rebuild: options.rebuild
+      });
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
       process.exit(1);
@@ -766,6 +842,7 @@ program
   .option('--working-on <text>', 'What you are currently working on')
   .option('--focus <text>', 'Current focus area')
   .option('--blocked <text>', 'What is blocking progress')
+  .option('--urgent', 'Trigger OpenClaw wake after checkpoint')
   .option('-v, --vault <path>', 'Vault path')
   .option('--json', 'Output as JSON')
   .action(async (options) => {
@@ -782,6 +859,7 @@ program
         workingOn: options.workingOn,
         focus: options.focus,
         blocked: options.blocked,
+        urgent: options.urgent
       });
       
       if (options.json) {
@@ -792,6 +870,7 @@ program
         if (data.workingOn) console.log(chalk.dim(`  Working on: ${data.workingOn}`));
         if (data.focus) console.log(chalk.dim(`  Focus: ${data.focus}`));
         if (data.blocked) console.log(chalk.dim(`  Blocked: ${data.blocked}`));
+        if (data.urgent) console.log(chalk.dim('  Urgent: yes'));
       }
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
@@ -804,6 +883,7 @@ program
   .command('recover')
   .description('Check for context death and recover state')
   .option('--clear', 'Clear the dirty death flag after recovery')
+  .option('--verbose', 'Show full checkpoint and handoff content')
   .option('-v, --vault <path>', 'Vault path')
   .option('--json', 'Output as JSON')
   .action(async (options) => {
@@ -815,12 +895,15 @@ program
       }
       
       const { recover, formatRecoveryInfo } = await import('../dist/commands/recover.js');
-      const info = await recover(path.resolve(vaultPath), options.clear);
+      const info = await recover(path.resolve(vaultPath), {
+        clearFlag: options.clear,
+        verbose: options.verbose
+      });
       
       if (options.json) {
         console.log(JSON.stringify(info, null, 2));
       } else {
-        console.log(formatRecoveryInfo(info));
+        console.log(formatRecoveryInfo(info, { verbose: options.verbose }));
       }
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
@@ -828,6 +911,28 @@ program
     }
   });
 
+// === STATUS ===
+program
+  .command('status')
+  .description('Show vault health and status')
+  .option('-v, --vault <path>', 'Vault path')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    try {
+      const vaultPath = options.vault || process.env.CLAWVAULT_PATH;
+      if (!vaultPath) {
+        console.error(chalk.red('Error: No vault path. Set CLAWVAULT_PATH or use -v'));
+        process.exit(1);
+      }
+
+      const { statusCommand } = await import('../dist/commands/status.js');
+      await statusCommand(path.resolve(vaultPath), { json: options.json });
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
 // === CLEAN-EXIT ===
 program
   .command('clean-exit')

package/dist/{chunk-4XJDHIKE.js → chunk-42MXU7A6.js}

@@ -31,6 +31,21 @@ function findProtectedRanges(content) {
 function isProtected(pos, ranges) {
   return ranges.some((r) => pos >= r.start && pos < r.end);
 }
+function createLineLookup(content) {
+  const lines = content.split("\n");
+  let charPos = 0;
+  const lineStarts = [];
+  for (const line of lines) {
+    lineStarts.push(charPos);
+    charPos += line.length + 1;
+  }
+  return (pos) => {
+    for (let i = lineStarts.length - 1; i >= 0; i--) {
+      if (pos >= lineStarts[i]) return i + 1;
+    }
+    return 1;
+  };
+}
 function autoLink(content, index) {
   const protectedRanges = findProtectedRanges(content);
   const sortedAliases = getSortedAliases(index);
@@ -65,19 +80,7 @@ function dryRunLink(content, index) {
   const sortedAliases = getSortedAliases(index);
   const linkedEntities = /* @__PURE__ */ new Set();
   const matches = [];
-  const lines = content.split("\n");
-  let charPos = 0;
-  const lineStarts = [];
-  for (const line of lines) {
-    lineStarts.push(charPos);
-    charPos += line.length + 1;
-  }
-  function getLineNumber(pos) {
-    for (let i = lineStarts.length - 1; i >= 0; i--) {
-      if (pos >= lineStarts[i]) return i + 1;
-    }
-    return 1;
-  }
+  const getLineNumber = createLineLookup(content);
   for (const { alias, path } of sortedAliases) {
     if (linkedEntities.has(path)) continue;
     const escapedAlias = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -96,8 +99,33 @@ function dryRunLink(content, index) {
   }
   return matches;
 }
+function findUnlinkedMentions(content, index) {
+  const protectedRanges = findProtectedRanges(content);
+  const sortedAliases = getSortedAliases(index);
+  const matches = [];
+  const seen = /* @__PURE__ */ new Set();
+  const getLineNumber = createLineLookup(content);
+  for (const { alias, path } of sortedAliases) {
+    if (seen.has(path)) continue;
+    const escapedAlias = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`\\b${escapedAlias}\\b`, "gi");
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      if (isProtected(match.index, protectedRanges)) continue;
+      matches.push({
+        alias: match[0],
+        path,
+        line: getLineNumber(match.index)
+      });
+      seen.add(path);
+      break;
+    }
+  }
+  return matches;
+}
 
 export {
   autoLink,
-  dryRunLink
+  dryRunLink,
+  findUnlinkedMentions
 };

package/dist/chunk-4VQTUVH7.js

@@ -0,0 +1,154 @@
+import {
+  buildEntityIndex
+} from "./chunk-J7ZWCI2C.js";
+
+// src/lib/backlinks.ts
+import * as fs from "fs";
+import * as path from "path";
+var CLAWVAULT_DIR = ".clawvault";
+var BACKLINKS_FILE = "backlinks.json";
+var WIKI_LINK_REGEX = /\[\[([^\]]+)\]\]/g;
+function ensureClawvaultDir(vaultPath) {
+  const dir = path.join(vaultPath, CLAWVAULT_DIR);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+function toVaultId(vaultPath, filePath) {
+  const relative2 = path.relative(vaultPath, filePath).replace(/\.md$/, "");
+  return relative2.split(path.sep).join("/");
+}
+function normalizeLinkTarget(raw) {
+  let target = raw.trim();
+  if (!target) return "";
+  if (target.startsWith("[[") && target.endsWith("]]")) {
+    target = target.slice(2, -2);
+  }
+  const pipeIndex = target.indexOf("|");
+  if (pipeIndex !== -1) {
+    target = target.slice(0, pipeIndex);
+  }
+  if (target.startsWith("#")) return "";
+  const hashIndex = target.indexOf("#");
+  if (hashIndex !== -1) {
+    target = target.slice(0, hashIndex);
+  }
+  target = target.trim();
+  if (!target) return "";
+  if (target.endsWith(".md")) {
+    target = target.slice(0, -3);
+  }
+  if (target.startsWith("/")) {
+    target = target.slice(1);
+  }
+  return target.replace(/\\/g, "/");
+}
+function listMarkdownFiles(vaultPath) {
+  const files = [];
+  const skipDirs = /* @__PURE__ */ new Set(["archive", "templates", "node_modules"]);
+  function walk(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith(".") || skipDirs.has(entry.name)) continue;
+        walk(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        files.push(fullPath);
+      }
+    }
+  }
+  walk(vaultPath);
+  return files;
+}
+function buildKnownIds(vaultPath, files) {
+  const ids = /* @__PURE__ */ new Set();
+  const idsLower = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const id = toVaultId(vaultPath, file);
+    ids.add(id);
+    const lower = id.toLowerCase();
+    if (!idsLower.has(lower)) {
+      idsLower.set(lower, id);
+    }
+  }
+  return { ids, idsLower };
+}
+function resolveTarget(target, known, entityIndex) {
+  if (!target) return null;
+  if (known.ids.has(target)) return target;
+  const lower = target.toLowerCase();
+  if (known.idsLower.has(lower)) return known.idsLower.get(lower);
+  if (entityIndex?.entries.has(lower)) return entityIndex.entries.get(lower);
+  return null;
+}
+function scanVaultLinks(vaultPath, options = {}) {
+  const files = listMarkdownFiles(vaultPath);
+  const known = buildKnownIds(vaultPath, files);
+  const entityIndex = options.entityIndex ?? buildEntityIndex(vaultPath);
+  const backlinks = /* @__PURE__ */ new Map();
+  const orphans = [];
+  let linkCount = 0;
+  for (const file of files) {
+    const sourceId = toVaultId(vaultPath, file);
+    const content = fs.readFileSync(file, "utf-8");
+    const matches = content.match(WIKI_LINK_REGEX) || [];
+    linkCount += matches.length;
+    for (const match of matches) {
+      const target = normalizeLinkTarget(match);
+      if (!target) continue;
+      const resolved = resolveTarget(target, known, entityIndex);
+      if (!resolved) {
+        orphans.push({ source: sourceId, target });
+        continue;
+      }
+      if (!backlinks.has(resolved)) {
+        backlinks.set(resolved, /* @__PURE__ */ new Set());
+      }
+      backlinks.get(resolved).add(sourceId);
+    }
+  }
+  const backlinksMap = /* @__PURE__ */ new Map();
+  for (const [target, sources] of backlinks) {
+    backlinksMap.set(target, [...sources].sort());
+  }
+  return { backlinks: backlinksMap, orphans, linkCount };
+}
+function writeBacklinksIndex(vaultPath, backlinks) {
+  const dir = ensureClawvaultDir(vaultPath);
+  const output = {};
+  const targets = [...backlinks.keys()].sort();
+  for (const target of targets) {
+    const sources = backlinks.get(target) || [];
+    output[target] = [...new Set(sources)].sort();
+  }
+  fs.writeFileSync(path.join(dir, BACKLINKS_FILE), JSON.stringify(output, null, 2));
+}
+function readBacklinksIndex(vaultPath) {
+  const filePath = path.join(vaultPath, CLAWVAULT_DIR, BACKLINKS_FILE);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    const map = /* @__PURE__ */ new Map();
+    for (const [target, sources] of Object.entries(raw)) {
+      if (Array.isArray(sources)) {
+        map.set(target, sources);
+      }
+    }
+    return map;
+  } catch {
+    return null;
+  }
+}
+function rebuildBacklinksIndex(vaultPath, options = {}) {
+  const result = scanVaultLinks(vaultPath, options);
+  writeBacklinksIndex(vaultPath, result.backlinks);
+  return result;
+}
+
+export {
+  scanVaultLinks,
+  readBacklinksIndex,
+  rebuildBacklinksIndex
+};

package/dist/chunk-7766SIJP.js

@@ -0,0 +1,22 @@
+// src/lib/template-engine.ts
+function buildTemplateVariables(input = {}, now = /* @__PURE__ */ new Date()) {
+  const datetime = input.datetime ?? now.toISOString();
+  const date = input.date ?? datetime.split("T")[0];
+  return {
+    title: input.title ?? "",
+    type: input.type ?? "",
+    date,
+    datetime
+  };
+}
+function renderTemplate(template, variables) {
+  return template.replace(/\{\{\s*([a-zA-Z0-9_-]+)\s*\}\}/g, (match, key) => {
+    const value = variables[key];
+    return value !== void 0 ? String(value) : match;
+  });
+}
+
+export {
+  buildTemplateVariables,
+  renderTemplate
+};

package/dist/chunk-7ZRP733D.js

@@ -0,0 +1,16 @@
+// src/lib/time.ts
+function formatAge(ms) {
+  if (!Number.isFinite(ms)) return "unknown";
+  const seconds = Math.max(0, Math.floor(ms / 1e3));
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  if (days > 0) return `${days}d ${hours % 24}h`;
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
+  return `${seconds}s`;
+}
+
+export {
+  formatAge
+};