clawvault 1.11.2 → 2.0.0

package/bin/register-query-commands.js

@@ -0,0 +1,225 @@
+/**
+ * Query and context command registrations.
+ */
+
+export function registerQueryCommands(
+  program,
+  {
+    chalk,
+    getVault,
+    resolveVaultPath,
+    QmdUnavailableError,
+    printQmdMissing
+  }
+) {
+  // === SEARCH ===
+  program
+    .command('search <query>')
+    .description('Search the vault via qmd (BM25)')
+    .option('-n, --limit <n>', 'Max results', '10')
+    .option('-c, --category <category>', 'Filter by category')
+    .option('--tags <tags>', 'Filter by tags (comma-separated)')
+    .option('--recent', 'Boost recent documents')
+    .option('--full', 'Include full content in results')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--json', 'Output as JSON')
+    .action(async (query, options) => {
+      try {
+        const vault = await getVault(options.vault);
+
+        const results = await vault.find(query, {
+          limit: parseInt(options.limit, 10),
+          category: options.category,
+          tags: options.tags?.split(',').map((value) => value.trim()),
+          fullContent: options.full,
+          temporalBoost: options.recent
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(results, null, 2));
+          return;
+        }
+
+        if (results.length === 0) {
+          console.log(chalk.yellow('No results found.'));
+          return;
+        }
+
+        console.log(chalk.cyan(`\n🔍 Found ${results.length} result(s) for "${query}":\n`));
+
+        for (const result of results) {
+          const scoreBar = '█'.repeat(Math.round(result.score * 10)).padEnd(10, '░');
+          console.log(chalk.green(`📄 ${result.document.title}`));
+          console.log(chalk.dim(`   ${result.document.category}/${result.document.id.split('/').pop()}`));
+          console.log(chalk.dim(`   Score: ${scoreBar} ${(result.score * 100).toFixed(0)}%`));
+          if (result.snippet) {
+            console.log(chalk.white(`   ${result.snippet.split('\n')[0].slice(0, 80)}...`));
+          }
+          console.log();
+        }
+      } catch (err) {
+        if (err instanceof QmdUnavailableError) {
+          printQmdMissing();
+          process.exit(1);
+        }
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === VSEARCH ===
+  program
+    .command('vsearch <query>')
+    .description('Semantic search via qmd (requires qmd installed)')
+    .option('-n, --limit <n>', 'Max results', '5')
+    .option('-c, --category <category>', 'Filter by category')
+    .option('--tags <tags>', 'Filter by tags (comma-separated)')
+    .option('--recent', 'Boost recent documents')
+    .option('--full', 'Include full content in results')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--json', 'Output as JSON')
+    .action(async (query, options) => {
+      try {
+        const vault = await getVault(options.vault);
+
+        const results = await vault.vsearch(query, {
+          limit: parseInt(options.limit, 10),
+          category: options.category,
+          tags: options.tags?.split(',').map((value) => value.trim()),
+          fullContent: options.full,
+          temporalBoost: options.recent
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(results, null, 2));
+          return;
+        }
+
+        if (results.length === 0) {
+          console.log(chalk.yellow('No results found.'));
+          return;
+        }
+
+        console.log(chalk.cyan(`\n🧠 Found ${results.length} result(s) for "${query}":\n`));
+
+        for (const result of results) {
+          const scoreBar = '█'.repeat(Math.round(result.score * 10)).padEnd(10, '░');
+          console.log(chalk.green(`📄 ${result.document.title}`));
+          console.log(chalk.dim(`   ${result.document.category}/${result.document.id.split('/').pop()}`));
+          console.log(chalk.dim(`   Score: ${scoreBar} ${(result.score * 100).toFixed(0)}%`));
+          if (result.snippet) {
+            console.log(chalk.white(`   ${result.snippet.split('\n')[0].slice(0, 80)}...`));
+          }
+          console.log();
+        }
+      } catch (err) {
+        if (err instanceof QmdUnavailableError) {
+          printQmdMissing();
+          process.exit(1);
+        }
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === CONTEXT ===
+  program
+    .command('context <task>')
+    .description('Generate task-relevant context for prompt injection')
+    .option('-n, --limit <n>', 'Max results', '5')
+    .option('--format <format>', 'Output format (markdown|json)', 'markdown')
+    .option('--recent', 'Boost recent documents (enabled by default)', true)
+    .option('--include-observations', 'Include observation memories in output', true)
+    .option('--budget <number>', 'Optional token budget for assembled context')
+    .option('--profile <profile>', 'Context profile (default|planning|incident|handoff|auto)', 'default')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (task, options) => {
+      try {
+        const vaultPath = resolveVaultPath(options.vault);
+        const format = options.format === 'json' ? 'json' : 'markdown';
+        const parsedBudget = options.budget ? Number.parseInt(options.budget, 10) : undefined;
+        if (options.budget && (!Number.isFinite(parsedBudget) || parsedBudget <= 0)) {
+          throw new Error(`Invalid --budget value: ${options.budget}`);
+        }
+
+        const { contextCommand } = await import('../dist/commands/context.js');
+        await contextCommand(task, {
+          vaultPath,
+          limit: parseInt(options.limit, 10),
+          format,
+          recent: options.recent,
+          includeObservations: options.includeObservations,
+          budget: parsedBudget,
+          profile: options.profile
+        });
+      } catch (err) {
+        if (err instanceof QmdUnavailableError) {
+          printQmdMissing();
+          process.exit(1);
+        }
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === OBSERVE ===
+  program
+    .command('observe')
+    .description('Observe session files and build observational memory')
+    .option('--watch <path>', 'Watch session file or directory')
+    .option('--threshold <n>', 'Compression token threshold', '30000')
+    .option('--reflect-threshold <n>', 'Reflection token threshold', '40000')
+    .option('--model <model>', 'LLM model override')
+    .option('--compress <file>', 'One-shot compression for a conversation file')
+    .option('--daemon', 'Run in detached background mode')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const { observeCommand } = await import('../dist/commands/observe.js');
+        const threshold = Number.parseInt(options.threshold, 10);
+        const reflectThreshold = Number.parseInt(options.reflectThreshold, 10);
+        if (Number.isNaN(threshold) || threshold <= 0) {
+          throw new Error(`Invalid --threshold value: ${options.threshold}`);
+        }
+        if (Number.isNaN(reflectThreshold) || reflectThreshold <= 0) {
+          throw new Error(`Invalid --reflect-threshold value: ${options.reflectThreshold}`);
+        }
+
+        await observeCommand({
+          watch: options.watch,
+          threshold,
+          reflectThreshold,
+          model: options.model,
+          compress: options.compress,
+          daemon: options.daemon,
+          vaultPath: resolveVaultPath(options.vault)
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === SESSION-RECAP ===
+  program
+    .command('session-recap <sessionKey>')
+    .description('Generate recap from a specific OpenClaw session transcript')
+    .option('-n, --limit <n>', 'Number of messages to include', '15')
+    .option('--format <format>', 'Output format (markdown|json)', 'markdown')
+    .option('-a, --agent <id>', 'Agent ID (default: OPENCLAW_AGENT_ID or clawdious)')
+    .action(async (sessionKey, options) => {
+      try {
+        const { sessionRecapCommand } = await import('../dist/commands/session-recap.js');
+        const format = options.format === 'json' ? 'json' : 'markdown';
+        const parsedLimit = Number.parseInt(options.limit, 10);
+        await sessionRecapCommand(sessionKey, {
+          limit: Number.isNaN(parsedLimit) ? 15 : parsedLimit,
+          format,
+          agentId: options.agent
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}

package/bin/register-resilience-commands.js

@@ -0,0 +1,147 @@
+/**
+ * Context-resilience and session-repair command registrations.
+ */
+
+export function registerResilienceCommands(program, { chalk, resolveVaultPath }) {
+  // === CHECKPOINT ===
+  program
+    .command('checkpoint')
+    .description('Quick state checkpoint for context death resilience')
+    .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) => {
+      try {
+        const { checkpoint } = await import('../dist/commands/checkpoint.js');
+        const data = await checkpoint({
+          vaultPath: resolveVaultPath(options.vault),
+          workingOn: options.workingOn,
+          focus: options.focus,
+          blocked: options.blocked,
+          urgent: options.urgent
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(data, null, 2));
+        } else {
+          console.log(chalk.green('✓ Checkpoint saved'));
+          console.log(chalk.dim(`  Timestamp: ${data.timestamp}`));
+          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}`));
+        process.exit(1);
+      }
+    });
+
+  // === RECOVER ===
+  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) => {
+      try {
+        const { recover, formatRecoveryInfo } = await import('../dist/commands/recover.js');
+        const info = await recover(resolveVaultPath(options.vault), {
+          clearFlag: options.clear,
+          verbose: options.verbose
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(info, null, 2));
+        } else {
+          console.log(formatRecoveryInfo(info, { verbose: options.verbose }));
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === 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 { statusCommand } = await import('../dist/commands/status.js');
+        await statusCommand(resolveVaultPath(options.vault), { json: options.json });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === CLEAN-EXIT ===
+  program
+    .command('clean-exit')
+    .description('Mark session as cleanly exited (clears dirty death flag)')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const { cleanExit } = await import('../dist/commands/checkpoint.js');
+        await cleanExit(resolveVaultPath(options.vault));
+        console.log(chalk.green('✓ Clean exit recorded'));
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === REPAIR-SESSION ===
+  program
+    .command('repair-session')
+    .description('Repair corrupted OpenClaw session transcripts')
+    .option('-s, --session <id>', 'Session ID (defaults to current main session)')
+    .option('-a, --agent <id>', 'Agent ID (defaults to configured agent)')
+    .option('--backup', 'Create backup before repair (default: true)', true)
+    .option('--no-backup', 'Skip backup creation')
+    .option('--dry-run', 'Show what would be repaired without writing')
+    .option('--list', 'List available sessions')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const {
+          repairSessionCommand,
+          formatRepairResult,
+          listAgentSessions
+        } = await import('../dist/commands/repair-session.js');
+
+        if (options.list) {
+          console.log(listAgentSessions(options.agent));
+          return;
+        }
+
+        const result = await repairSessionCommand({
+          sessionId: options.session,
+          agentId: options.agent,
+          backup: options.backup,
+          dryRun: options.dryRun
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(formatRepairResult(result, { dryRun: options.dryRun }));
+        }
+
+        if (result.corruptedEntries.length > 0 && !result.repaired) {
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}

package/bin/register-session-lifecycle-commands.js

@@ -0,0 +1,204 @@
+/**
+ * Session lifecycle command registrations (wake/sleep/handoff/recap).
+ */
+
+export function registerSessionLifecycleCommands(
+  program,
+  { chalk, resolveVaultPath, QmdUnavailableError, printQmdMissing, getVault, runQmd }
+) {
+  // === WAKE (session start) ===
+  program
+    .command('wake')
+    .description('Start a session (recover + recap + summary)')
+    .option('-n, --handoff-limit <n>', 'Number of recent handoffs to include', '3')
+    .option('--full', 'Show full recap (default: brief)')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const vaultPath = resolveVaultPath(options.vault);
+        const { wake } = await import('../dist/commands/wake.js');
+        const { formatRecoveryInfo } = await import('../dist/commands/recover.js');
+        const result = await wake({
+          vaultPath,
+          handoffLimit: parseInt(options.handoffLimit, 10),
+          brief: !options.full
+        });
+
+        console.log(chalk.cyan('\n🌅 ClawVault Wake\n'));
+        console.log(formatRecoveryInfo(result.recovery));
+        console.log();
+        console.log(chalk.cyan('Recap'));
+        console.log(result.recapMarkdown.trim());
+        console.log();
+        console.log(chalk.green(`You were working on: ${result.summary}`));
+
+        process.exitCode = result.recovery.died ? 1 : 0;
+      } catch (err) {
+        if (err instanceof QmdUnavailableError) {
+          printQmdMissing();
+          process.exit(1);
+        }
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === SLEEP (session end) ===
+  program
+    .command('sleep <summary>')
+    .description('End a session with a handoff (and optional git commit)')
+    .option('-n, --next <items>', 'Next steps (comma-separated)')
+    .option('-b, --blocked <items>', 'Blocked items (comma-separated)')
+    .option('-d, --decisions <items>', 'Key decisions made (comma-separated)')
+    .option('-q, --questions <items>', 'Open questions (comma-separated)')
+    .option('-f, --feeling <state>', 'Emotional/energy state')
+    .option('-s, --session <key>', 'Session key')
+    .option('--session-transcript <path>', 'Session transcript path for auto-observe')
+    .option('--index', 'Update qmd index after handoff')
+    .option('--no-git', 'Skip git commit prompt')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (summary, options) => {
+      try {
+        const vaultPath = resolveVaultPath(options.vault);
+        const { sleep } = await import('../dist/commands/sleep.js');
+        const result = await sleep({
+          workingOn: summary,
+          next: options.next,
+          blocked: options.blocked,
+          decisions: options.decisions,
+          questions: options.questions,
+          feeling: options.feeling,
+          sessionKey: options.session,
+          sessionTranscript: options.sessionTranscript,
+          vaultPath,
+          index: options.index,
+          git: options.git
+        });
+
+        console.log(chalk.green(`✓ Handoff saved: ${result.document.id}`));
+        console.log(chalk.dim(`  Path: ${result.document.path}`));
+        console.log(chalk.dim(`  Working on: ${result.handoff.workingOn.join(', ')}`));
+        if (result.handoff.nextSteps.length > 0) {
+          console.log(chalk.dim(`  Next: ${result.handoff.nextSteps.join(', ')}`));
+        } else {
+          console.log(chalk.dim('  Next: (none)'));
+        }
+        if (result.handoff.blocked.length > 0) {
+          console.log(chalk.dim(`  Blocked: ${result.handoff.blocked.join(', ')}`));
+        } else {
+          console.log(chalk.dim('  Blocked: (none)'));
+        }
+        if (result.handoff.decisions?.length) {
+          console.log(chalk.dim(`  Decisions: ${result.handoff.decisions.join(', ')}`));
+        }
+        if (result.handoff.openQuestions?.length) {
+          console.log(chalk.dim(`  Questions: ${result.handoff.openQuestions.join(', ')}`));
+        }
+        if (result.handoff.feeling) {
+          console.log(chalk.dim(`  Feeling: ${result.handoff.feeling}`));
+        }
+        if (options.index) {
+          console.log(chalk.dim('  qmd: index updated'));
+        }
+        if (result.git) {
+          if (result.git.committed) {
+            console.log(chalk.green(`✓ Git commit created${result.git.message ? `: ${result.git.message}` : ''}`));
+          } else if (result.git.skippedReason === 'clean') {
+            console.log(chalk.dim('  Git: clean'));
+          } else if (result.git.skippedReason === 'declined') {
+            console.log(chalk.dim('  Git: commit skipped'));
+          }
+        }
+        if (result.observationRoutingSummary) {
+          console.log(chalk.dim(`  Observe: ${result.observationRoutingSummary}`));
+        }
+      } catch (err) {
+        if (err instanceof QmdUnavailableError) {
+          printQmdMissing();
+          process.exit(1);
+        }
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === HANDOFF (session bridge) ===
+  program
+    .command('handoff')
+    .description('Create a session handoff document')
+    .requiredOption('-w, --working-on <items>', 'What I was working on (comma-separated)')
+    .option('-b, --blocked <items>', 'What is blocked (comma-separated)')
+    .option('-n, --next <items>', 'What comes next (comma-separated)')
+    .option('-d, --decisions <items>', 'Key decisions made (comma-separated)')
+    .option('-q, --questions <items>', 'Open questions (comma-separated)')
+    .option('-f, --feeling <state>', 'Emotional/energy state')
+    .option('-s, --session <key>', 'Session key')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--no-index', 'Skip qmd index update (auto-updates by default)')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const vault = await getVault(options.vault);
+
+        const handoff = {
+          workingOn: options.workingOn.split(',').map((item) => item.trim()),
+          blocked: options.blocked ? options.blocked.split(',').map((item) => item.trim()) : [],
+          nextSteps: options.next ? options.next.split(',').map((item) => item.trim()) : [],
+          decisions: options.decisions ? options.decisions.split(',').map((item) => item.trim()) : undefined,
+          openQuestions: options.questions ? options.questions.split(',').map((item) => item.trim()) : undefined,
+          feeling: options.feeling,
+          sessionKey: options.session
+        };
+
+        const doc = await vault.createHandoff(handoff);
+
+        if (!options.json) {
+          console.log(chalk.green(`✓ Handoff created: ${doc.id}`));
+          console.log(chalk.dim(`  Path: ${doc.path}`));
+        }
+
+        if (options.index !== false) {
+          const collection = vault.getQmdCollection();
+          await runQmd(collection ? ['update', '-c', collection] : ['update']);
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify({ id: doc.id, path: doc.path, handoff }, null, 2));
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === RECAP (session bootstrap) ===
+  program
+    .command('recap')
+    .description('Generate a session recap - who I was (bootstrap hook)')
+    .option('-n, --handoff-limit <n>', 'Number of recent handoffs to include', '3')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--json', 'Output as JSON')
+    .option('--markdown', 'Output as markdown (default)')
+    .option('--brief', 'Minimal output for token savings')
+    .action(async (options) => {
+      try {
+        const vault = await getVault(options.vault);
+
+        const recap = await vault.generateRecap({
+          handoffLimit: parseInt(options.handoffLimit, 10),
+          brief: options.brief
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(recap, null, 2));
+          return;
+        }
+
+        const markdown = vault.formatRecap(recap, { brief: options.brief });
+        console.log(markdown);
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}

package/bin/register-template-commands.js

@@ -0,0 +1,72 @@
+/**
+ * Template command registrations split from main CLI entrypoint.
+ */
+
+export function registerTemplateCommands(program, { chalk }) {
+  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);
+      }
+    });
+}