clawvault 3.1.0 → 3.2.0

package/bin/command-registration.test.js

@@ -83,7 +83,8 @@ describe('CLI command registration modules', () => {
       'sync',
       'reindex',
       'remember',
-      'shell-init'
+      'shell-init',
+      'dashboard'
     ]));
   });
 
@@ -129,6 +130,7 @@ describe('CLI command registration modules', () => {
       'archive',
       'migrate-observations',
       'replay',
+      'sync-bd',
       'checkpoint',
       'recover',
       'status',

package/bin/command-runtime.js

@@ -4,6 +4,7 @@ import path from 'path';
 import {
   ClawVault,
   QmdUnavailableError,
+  QmdConfigurationError,
   QMD_INSTALL_COMMAND,
   resolveVaultPath as resolveConfiguredVaultPath
 } from '../dist/index.js';
@@ -90,4 +91,11 @@ export function printQmdMissing() {
   console.log(chalk.dim(`Install: ${QMD_INSTALL_COMMAND}`));
 }
 
-export { QmdUnavailableError };
+export function printQmdConfigError(err) {
+  console.error(chalk.red(`Error: ${err.message}`));
+  if (err.hint) {
+    console.log(chalk.yellow(`Hint: ${err.hint}`));
+  }
+}
+
+export { QmdUnavailableError, QmdConfigurationError };

package/bin/register-core-commands.js

@@ -19,6 +19,7 @@ export function registerCoreCommands(
     .option('--no-tasks', 'Skip tasks/ and backlog/ directories')
     .option('--no-graph', 'Skip initial graph build')
     .option('--categories <list>', 'Comma-separated list of custom categories to create')
+    .option('--canvas', 'Generate a vault status canvas dashboard on init')
     .option('--theme <style>', 'Graph color theme to apply (neural, minimal, none) (default: none)', 'none')
     .option('--minimal', 'Create minimal vault (memory categories only, no tasks/bases/graph)')
     .action(async (vaultPath, options) => {
@@ -80,14 +81,8 @@ export function registerCoreCommands(
             '**/*.md'
           ]);
           console.log(chalk.green('✓ qmd collection created'));
-        } catch (err) {
-          if (err instanceof QmdUnavailableError || err?.message?.includes('ENOENT') || err?.message?.includes('ERR_MODULE_NOT_FOUND')) {
-            console.log(chalk.yellow('⚠ qmd not available — skipping semantic search setup'));
-            console.log(chalk.dim('  Install qmd for semantic search: npm install -g github:tobi/qmd'));
-            console.log(chalk.dim('  Vault initialized successfully without qmd.'));
-          } else {
-            console.log(chalk.yellow('⚠ qmd collection may already exist'));
-          }
+        } catch {
+          console.log(chalk.yellow('⚠ qmd collection may already exist'));
         }
 
         // Apply theme if requested
@@ -97,6 +92,7 @@ export function registerCoreCommands(
             await setupCommand({
               graphColors: true,
               bases: false,
+              canvas: false,
               theme: options.theme,
               vault: resolvedPath
             });
@@ -105,6 +101,22 @@ export function registerCoreCommands(
           }
         }
 
+        // Generate canvas if requested
+        if (options.canvas) {
+          try {
+            const { setupCommand } = await import('../dist/commands/setup.js');
+            await setupCommand({
+              graphColors: false,
+              bases: false,
+              canvas: true,
+              theme: 'none',
+              vault: resolvedPath
+            });
+          } catch {
+            console.log(chalk.yellow(`⚠ Could not generate canvas`));
+          }
+        }
+
         console.log(chalk.green('\n✅ ClawVault ready!\n'));
         console.log('  ' + chalk.bold('Try these:'));
         console.log(chalk.dim('  clawvault capture "my first thought"     # quick capture'));
@@ -128,6 +140,8 @@ export function registerCoreCommands(
     .option('--no-graph-colors', 'Skip graph color configuration')
     .option('--bases', 'Generate Obsidian Bases views for task management')
     .option('--no-bases', 'Skip Bases file generation')
+    .option('--canvas', 'Generate vault status canvas dashboard')
+    .option('--no-canvas', 'Skip canvas generation')
     .option('--theme <style>', 'Graph color theme (neural, minimal, none) (default: neural)', 'neural')
     .option('--force', 'Overwrite existing configuration files')
     .option('-v, --vault <path>', 'Vault path')
@@ -137,6 +151,7 @@ export function registerCoreCommands(
         await setupCommand({
           graphColors: options.graphColors,
           bases: options.bases,
+          canvas: options.canvas,
           theme: options.theme,
           force: options.force,
           vault: options.vault
@@ -219,24 +234,4 @@ export function registerCoreCommands(
         process.exit(1);
       }
     });
-  // === PLUGIN-PATH ===
-  program
-    .command('plugin-path')
-    .description('Print the OpenClaw plugin path for configuration')
-    .action(() => {
-      const pluginDir = path.dirname(path.dirname(new URL(import.meta.url).pathname));
-      const pluginPath = path.join(pluginDir, 'dist', 'plugin', 'index.js');
-      if (fs.existsSync(pluginPath)) {
-        console.log(pluginPath);
-      } else {
-        // Dev mode — use source
-        const srcPath = path.join(pluginDir, 'src', 'plugin', 'index.ts');
-        if (fs.existsSync(srcPath)) {
-          console.log(srcPath);
-        } else {
-          console.error('Plugin not found. Run: npm run build');
-          process.exit(1);
-        }
-      }
-    });
 }

package/bin/register-maintenance-commands.js

@@ -26,8 +26,8 @@ export function registerMaintenanceCommands(program, { chalk }) {
 
         console.log(chalk.cyan('\n🩺 ClawVault Health Check\n'));
         console.log(chalk.dim(`Vault: ${report.vaultPath}`));
-        if (report.qmdCollection) console.log(chalk.dim(`qmd collection: ${report.qmdCollection}`));
-        if (report.qmdRoot) console.log(chalk.dim(`qmd root: ${report.qmdRoot}`));
+        console.log(chalk.dim(`qmd collection: ${report.qmdCollection}`));
+        console.log(chalk.dim(`qmd root: ${report.qmdRoot}`));
         console.log();
 
         for (const check of report.checks) {
@@ -36,7 +36,7 @@ export function registerMaintenanceCommands(program, { chalk }) {
             : check.status === 'warn'
               ? chalk.yellow('⚠')
               : chalk.red('✗');
-          const line = check.detail ? `${check.label}: ${check.detail}` : check.label;
+          const line = `${check.label}: ${check.detail}`;
           const renderedLine = check.status === 'ok'
             ? chalk.green(line)
             : check.status === 'warn'
@@ -80,6 +80,25 @@ export function registerMaintenanceCommands(program, { chalk }) {
       }
     });
 
+  // === REBUILD-EMBEDDINGS ===
+  program
+    .command('rebuild-embeddings')
+    .description('Rebuild local embedding cache for hybrid search (uses all-MiniLM-L6-v2)')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--force', 'Force rebuild all embeddings (ignore cache)')
+    .action(async (options) => {
+      try {
+        const { rebuildEmbeddingsCommand } = await import('../dist/commands/rebuild-embeddings.js');
+        await rebuildEmbeddingsCommand({
+          vaultPath: options.vault,
+          force: options.force
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
   // === COMPAT (OpenClaw compatibility) ===
   program
     .command('compat')
@@ -262,4 +281,21 @@ export function registerMaintenanceCommands(program, { chalk }) {
     });
 
   // === SYNC-BD ===
+  program
+    .command('sync-bd')
+    .description('Sync active Beads tasks into views/now.md (optional)')
+    .option('--dry-run', 'Show sync output without writing')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const { syncBdCommand } = await import('../dist/commands/sync-bd.js');
+        await syncBdCommand({
+          vaultPath: options.vault,
+          dryRun: options.dryRun
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
 }

package/bin/register-query-commands.js

@@ -9,13 +9,15 @@ export function registerQueryCommands(
     getVault,
     resolveVaultPath,
     QmdUnavailableError,
-    printQmdMissing
+    QmdConfigurationError,
+    printQmdMissing,
+    printQmdConfigError
   }
 ) {
   // === SEARCH ===
   program
     .command('search <query>')
-    .description('Search the vault via qmd (BM25)')
+    .description('Search the vault via qmd (BM25), optionally with semantic hybrid search')
     .option('-n, --limit <n>', 'Max results (default: 10)', '10')
     .option('-c, --category <category>', 'Filter by category')
     .option('--tags <tags>', 'Filter by tags (comma-separated)')
@@ -23,20 +25,57 @@ export function registerQueryCommands(
     .option('--full', 'Include full content in results')
     .option('-v, --vault <path>', 'Vault path')
     .option('--json', 'Output as JSON')
+    .option('--semantic', 'Enable hybrid search (BM25 + semantic with RRF)')
+    .option('--rebuild-embeddings', 'Rebuild the embedding cache before searching')
     .action(async (query, options) => {
       try {
+        const vaultPath = resolveVaultPath(options.vault);
         const vault = await getVault(options.vault);
 
-        const results = await vault.find(query, {
-          limit: parseInt(options.limit, 10),
+        // Handle --rebuild-embeddings flag
+        if (options.rebuildEmbeddings) {
+          const { rebuildEmbeddingsForVault } = await import('../dist/commands/rebuild-embeddings.js');
+          console.log(chalk.cyan('Rebuilding embedding cache...'));
+          const stats = await rebuildEmbeddingsForVault(vaultPath, { 
+            onProgress: (current, total) => {
+              process.stdout.write(`\r  Embedding ${current}/${total} documents...`);
+            }
+          });
+          console.log(chalk.green(`\n  Done. ${stats.total} embeddings (${stats.added} new, ${stats.skipped} cached)`));
+          console.log();
+        }
+
+        // Get BM25 results
+        const bm25Results = await vault.find(query, {
+          limit: options.semantic ? 50 : parseInt(options.limit, 10),
           category: options.category,
           tags: options.tags?.split(',').map((value) => value.trim()),
           fullContent: options.full,
           temporalBoost: options.recent
         });
 
+        let results = bm25Results;
+        let searchMode = 'BM25';
+
+        // Apply hybrid search if --semantic flag is set
+        if (options.semantic) {
+          const { EmbeddingCache, hybridSearch } = await import('../dist/lib/hybrid-search.js');
+          const cache = new EmbeddingCache(vaultPath);
+          cache.load();
+
+          if (cache.size === 0) {
+            console.log(chalk.yellow('Warning: No embeddings found. Run with --rebuild-embeddings to build the cache.'));
+          } else {
+            results = await hybridSearch(query, bm25Results, cache, {
+              topK: parseInt(options.limit, 10),
+              rrfK: 60
+            });
+            searchMode = 'Hybrid (BM25 + Semantic)';
+          }
+        }
+
         if (options.json) {
-          console.log(JSON.stringify(results, null, 2));
+          console.log(JSON.stringify({ searchMode, results }, null, 2));
           return;
         }
 
@@ -45,7 +84,8 @@ export function registerQueryCommands(
           return;
         }
 
-        console.log(chalk.cyan(`\n🔍 Found ${results.length} result(s) for "${query}":\n`));
+        const icon = options.semantic ? '🔍🧠' : '🔍';
+        console.log(chalk.cyan(`\n${icon} Found ${results.length} result(s) for "${query}" [${searchMode}]:\n`));
 
         for (const result of results) {
           const scoreBar = '█'.repeat(Math.round(result.score * 10)).padEnd(10, '░');
@@ -62,6 +102,10 @@ export function registerQueryCommands(
           printQmdMissing();
           process.exit(1);
         }
+        if (err instanceof QmdConfigurationError) {
+          printQmdConfigError(err);
+          process.exit(1);
+        }
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);
       }
@@ -117,6 +161,10 @@ export function registerQueryCommands(
           printQmdMissing();
           process.exit(1);
         }
+        if (err instanceof QmdConfigurationError) {
+          printQmdConfigError(err);
+          process.exit(1);
+        }
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);
       }
@@ -163,6 +211,10 @@ export function registerQueryCommands(
           printQmdMissing();
           process.exit(1);
         }
+        if (err instanceof QmdConfigurationError) {
+          printQmdConfigError(err);
+          process.exit(1);
+        }
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);
       }
@@ -292,29 +344,6 @@ export function registerQueryCommands(
       }
     });
 
-  // === REWEAVE ===
-  program
-    .command('reweave')
-    .description('Backward memory consolidation — detect and mark superseded observations')
-    .option('--since <date>', 'Only check observations since this date (YYYY-MM-DD)')
-    .option('--dry-run', 'Show what would be superseded without writing')
-    .option('--threshold <n>', 'Entity similarity threshold (0-1, default 0.3)', '0.3')
-    .option('-v, --vault <path>', 'Vault path')
-    .action(async (options) => {
-      try {
-        const { reweaveCommand } = await import('../dist/commands/reweave.js');
-        await reweaveCommand({
-          vaultPath: resolveVaultPath(options.vault),
-          since: options.since,
-          dryRun: options.dryRun,
-          threshold: parseFloat(options.threshold),
-        });
-      } catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
-        process.exit(1);
-      }
-    });
-
   // === SESSION-RECAP ===
   program
     .command('session-recap <sessionKey>')

package/bin/register-tailscale-commands.js

@@ -0,0 +1,106 @@
+/**
+ * Tailscale networking command registrations.
+ * Provides vault synchronization over Tailscale networks.
+ */
+
+export function registerTailscaleCommands(program, { chalk }) {
+  // === TAILSCALE-STATUS ===
+  program
+    .command('tailscale-status')
+    .alias('ts-status')
+    .description('Show Tailscale connection status and peers')
+    .option('--json', 'Output as JSON')
+    .option('--peers', 'Show all peers including offline')
+    .action(async (options) => {
+      try {
+        const { tailscaleStatusCommand } = await import('../dist/commands/tailscale.js');
+        await tailscaleStatusCommand({
+          json: options.json,
+          peers: options.peers
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === TAILSCALE-SYNC ===
+  program
+    .command('tailscale-sync')
+    .alias('ts-sync')
+    .description('Sync vault with a peer on the Tailscale network')
+    .requiredOption('--peer <hostname>', 'Peer hostname or IP to sync with')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--port <number>', 'Port on the peer (default: 8384)', parseInt)
+    .option('--direction <dir>', 'Sync direction: push, pull, or bidirectional (default: bidirectional)', 'bidirectional')
+    .option('--dry-run', 'Show what would be synced without making changes')
+    .option('--delete-orphans', 'Delete files that exist locally but not on peer (pull only)')
+    .option('--categories <list>', 'Comma-separated list of categories to sync')
+    .option('--https', 'Use HTTPS for connection')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const { tailscaleSyncCommand } = await import('../dist/commands/tailscale.js');
+        await tailscaleSyncCommand({
+          peer: options.peer,
+          vaultPath: options.vault,
+          port: options.port,
+          direction: options.direction,
+          dryRun: options.dryRun,
+          deleteOrphans: options.deleteOrphans,
+          categories: options.categories?.split(',').map(c => c.trim()),
+          https: options.https,
+          json: options.json
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === TAILSCALE-SERVE ===
+  program
+    .command('tailscale-serve')
+    .alias('ts-serve')
+    .description('Serve vault for sync over Tailscale')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--port <number>', 'Port to serve on (default: 8384)', parseInt)
+    .option('--funnel', 'Expose via Tailscale Funnel (public internet)')
+    .option('--background', 'Run in background')
+    .option('--stop', 'Stop serving')
+    .action(async (options) => {
+      try {
+        const { tailscaleServeCommand } = await import('../dist/commands/tailscale.js');
+        await tailscaleServeCommand({
+          vaultPath: options.vault,
+          port: options.port,
+          funnel: options.funnel,
+          background: options.background,
+          stop: options.stop
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === TAILSCALE-DISCOVER ===
+  program
+    .command('tailscale-discover')
+    .alias('ts-discover')
+    .description('Discover ClawVault peers on the Tailscale network')
+    .option('--port <number>', 'Port to check (default: 8384)', parseInt)
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const { tailscaleDiscoverCommand } = await import('../dist/commands/tailscale.js');
+        await tailscaleDiscoverCommand({
+          port: options.port,
+          json: options.json
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}

package/bin/register-task-commands.js

@@ -1,6 +1,6 @@
 /**
  * Task tracking command registrations for ClawVault
- * Registers task, backlog, and blocked commands
+ * Registers task, backlog, blocked, and canvas commands
  */
 
 function parseCsvList(value) {
@@ -328,4 +328,21 @@ export function registerTaskCommands(
     });
 
   // === CANVAS ===
+  program
+    .command('canvas')
+    .description('Generate an Obsidian canvas dashboard file')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
+    .option('--output <path>', 'Output file path (default: dashboard.canvas)')
+    .action(async (options) => {
+      try {
+        const vaultPath = resolveVaultPath(options.vault);
+        const { canvasCommand } = await import('../dist/commands/canvas.js');
+        await canvasCommand(vaultPath, {
+          output: options.output
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
 }

package/bin/register-task-commands.test.js

@@ -50,4 +50,20 @@ describe('register-task-commands', () => {
     ]));
   });
 
+  it('adds simplified canvas flags', () => {
+    const program = new Command();
+    registerTaskCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath
+    });
+
+    const canvasCommand = program.commands.find((command) => command.name() === 'canvas');
+    expect(canvasCommand).toBeDefined();
+
+    const optionFlags = canvasCommand?.options.map((option) => option.flags) ?? [];
+    expect(optionFlags).toEqual(expect.arrayContaining([
+      '-v, --vault <path>',
+      '--output <path>'
+    ]));
+  });
 });

package/bin/register-vault-operations-commands.js

@@ -1,5 +1,5 @@
 /**
- * Vault operation command registrations (browse/sync/reindex/remember/shell-init).
+ * Vault operation command registrations (browse/sync/reindex/remember/shell-init/dashboard).
  */
 
 import { validatePathWithinBase } from './command-runtime.js';
@@ -269,4 +269,32 @@ export function registerVaultOperationsCommands(
       }
     });
 
+  // === DASHBOARD ===
+  program
+    .command('dashboard')
+    .description('Run the local vault graph dashboard server')
+    .option('-p, --port <port>', 'Dashboard port (default: 3377)', '3377')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const parsedPort = Number.parseInt(options.port, 10);
+        if (Number.isNaN(parsedPort)) {
+          console.error(chalk.red(`Error: Invalid port: ${options.port}`));
+          process.exit(1);
+        }
+
+        const vaultPath = options.vault
+          ? path.resolve(options.vault)
+          : resolveVaultPath(undefined);
+
+        const { startDashboard } = await import('../dashboard/server.js');
+        await startDashboard({
+          port: parsedPort,
+          vaultPath
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
 }