clawvault 1.11.2 → 2.0.0

package/bin/command-registration.test.js

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { registerCoreCommands } from './register-core-commands.js';
+import { registerMaintenanceCommands } from './register-maintenance-commands.js';
+import { registerQueryCommands } from './register-query-commands.js';
+import { registerResilienceCommands } from './register-resilience-commands.js';
+import { registerSessionLifecycleCommands } from './register-session-lifecycle-commands.js';
+import { registerTemplateCommands } from './register-template-commands.js';
+import { registerVaultOperationsCommands } from './register-vault-operations-commands.js';
+import {
+  chalkStub,
+  createGetVaultStub,
+  registerAllCommandModules,
+  stubResolveVaultPath
+} from './test-helpers/cli-command-fixtures.js';
+
+function listCommandNames(program) {
+  return program.commands.map((command) => command.name()).sort((a, b) => a.localeCompare(b));
+}
+
+describe('CLI command registration modules', () => {
+  it('registers core lifecycle commands', () => {
+    const program = new Command();
+    registerCoreCommands(program, {
+      chalk: chalkStub,
+      path,
+      fs,
+      createVault: async () => ({ getCategories: () => [], getQmdRoot: () => '', getQmdCollection: () => '' }),
+      getVault: createGetVaultStub({ store: async () => ({}), capture: async () => ({}) }),
+      runQmd: async () => {}
+    });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining(['init', 'setup', 'store', 'capture']));
+  });
+
+  it('registers query commands with profile option', () => {
+    const program = new Command();
+    registerQueryCommands(program, {
+      chalk: chalkStub,
+      getVault: createGetVaultStub({ find: async () => [], vsearch: async () => [] }),
+      resolveVaultPath: stubResolveVaultPath,
+      QmdUnavailableError: class extends Error {},
+      printQmdMissing: () => {}
+    });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining(['search', 'vsearch', 'context', 'observe', 'session-recap']));
+
+    const contextCommand = program.commands.find((command) => command.name() === 'context');
+    const profileOption = contextCommand?.options.find((option) => option.flags.includes('--profile <profile>'));
+    expect(profileOption?.description).toContain('auto');
+  });
+
+  it('registers vault operation commands', () => {
+    const program = new Command();
+    registerVaultOperationsCommands(program, {
+      chalk: chalkStub,
+      fs,
+      getVault: createGetVaultStub({
+        list: async () => [],
+        get: async () => null,
+        stats: async () => ({ tags: [], categories: {} }),
+        sync: async () => ({ copied: [], deleted: [], unchanged: [], errors: [] }),
+        reindex: async () => 0,
+        remember: async () => ({ id: '' }),
+        getQmdCollection: () => ''
+      }),
+      runQmd: async () => {},
+      resolveVaultPath: stubResolveVaultPath,
+      path
+    });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining([
+      'list',
+      'get',
+      'stats',
+      'sync',
+      'reindex',
+      'remember',
+      'shell-init',
+      'dashboard'
+    ]));
+  });
+
+  it('registers maintenance, resilience, session-lifecycle and template commands', () => {
+    const program = new Command();
+    registerMaintenanceCommands(program, { chalk: chalkStub });
+    registerResilienceCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath
+    });
+    registerSessionLifecycleCommands(program, {
+      chalk: chalkStub,
+      resolveVaultPath: stubResolveVaultPath,
+      QmdUnavailableError: class extends Error {},
+      printQmdMissing: () => {},
+      getVault: createGetVaultStub({
+        createHandoff: async () => ({ id: '', path: '' }),
+        getQmdCollection: () => '',
+        generateRecap: async () => ({}),
+        formatRecap: () => ''
+      }),
+      runQmd: async () => {}
+    });
+    registerTemplateCommands(program, { chalk: chalkStub });
+
+    const names = listCommandNames(program);
+    expect(names).toEqual(expect.arrayContaining([
+      'doctor',
+      'compat',
+      'graph',
+      'entities',
+      'link',
+      'checkpoint',
+      'recover',
+      'status',
+      'clean-exit',
+      'repair-session',
+      'wake',
+      'sleep',
+      'handoff',
+      'recap',
+      'template'
+    ]));
+
+    const templateCommand = program.commands.find((command) => command.name() === 'template');
+    const templateSubcommands = templateCommand?.commands.map((command) => command.name()) ?? [];
+    expect(templateSubcommands).toEqual(expect.arrayContaining(['list', 'create', 'add']));
+
+    const compatCommand = program.commands.find((command) => command.name() === 'compat');
+    const strictOption = compatCommand?.options.find((option) => option.flags.includes('--strict'));
+    const baseDirOption = compatCommand?.options.find((option) => option.flags.includes('--base-dir <path>'));
+    expect(strictOption).toBeTruthy();
+    expect(baseDirOption).toBeTruthy();
+  });
+
+  it('keeps top-level command names unique when modules are combined', () => {
+    const program = registerAllCommandModules(new Command());
+
+    const names = program.commands.map((command) => command.name());
+    const unique = new Set(names);
+    expect(unique.size).toBe(names.length);
+  });
+});

package/bin/command-runtime.js

@@ -0,0 +1,42 @@
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import {
+  ClawVault,
+  QmdUnavailableError,
+  QMD_INSTALL_COMMAND,
+  resolveVaultPath as resolveConfiguredVaultPath
+} from '../dist/index.js';
+
+export function resolveVaultPath(vaultPath) {
+  return resolveConfiguredVaultPath({ explicitPath: vaultPath });
+}
+
+export async function getVault(vaultPath) {
+  const vault = new ClawVault(resolveVaultPath(vaultPath));
+  await vault.load();
+  return vault;
+}
+
+export async function runQmd(args) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('qmd', args, { stdio: 'inherit' });
+    proc.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`qmd exited with code ${code}`));
+    });
+    proc.on('error', (err) => {
+      if (err?.code === 'ENOENT') {
+        reject(new QmdUnavailableError());
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+export function printQmdMissing() {
+  console.error(chalk.red('Error: ClawVault requires qmd.'));
+  console.log(chalk.dim(`Install: ${QMD_INSTALL_COMMAND}`));
+}
+
+export { QmdUnavailableError };

package/bin/command-runtime.test.js

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const {
+  spawnMock,
+  resolveConfiguredVaultPathMock,
+  clawvaultCtorMock,
+  loadMock
+} = vi.hoisted(() => ({
+  spawnMock: vi.fn(),
+  resolveConfiguredVaultPathMock: vi.fn(),
+  clawvaultCtorMock: vi.fn(),
+  loadMock: vi.fn()
+}));
+
+vi.mock('child_process', () => ({
+  spawn: spawnMock
+}));
+
+vi.mock('../dist/index.js', () => ({
+  ClawVault: clawvaultCtorMock,
+  resolveVaultPath: resolveConfiguredVaultPathMock,
+  QmdUnavailableError: class QmdUnavailableError extends Error {},
+  QMD_INSTALL_COMMAND: 'install-qmd'
+}));
+
+async function loadRuntimeModule() {
+  vi.resetModules();
+  return await import('./command-runtime.js');
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  clawvaultCtorMock.mockImplementation(() => ({
+    load: loadMock
+  }));
+});
+
+describe('command runtime helpers', () => {
+  it('delegates vault path resolution and loads vaults', async () => {
+    resolveConfiguredVaultPathMock.mockReturnValue('/resolved/vault');
+    loadMock.mockResolvedValue(undefined);
+    const { getVault, resolveVaultPath } = await loadRuntimeModule();
+
+    const resolved = resolveVaultPath('/explicit');
+    expect(resolveConfiguredVaultPathMock).toHaveBeenCalledWith({ explicitPath: '/explicit' });
+    expect(resolved).toBe('/resolved/vault');
+
+    await getVault('/explicit');
+    expect(clawvaultCtorMock).toHaveBeenCalledWith('/resolved/vault');
+    expect(loadMock).toHaveBeenCalled();
+  });
+
+  it('maps qmd ENOENT failures to QmdUnavailableError', async () => {
+    const { runQmd, QmdUnavailableError } = await loadRuntimeModule();
+    spawnMock.mockImplementation(() => {
+      const handlers = {};
+      const proc = {
+        on: (event, handler) => {
+          handlers[event] = handler;
+        }
+      };
+      queueMicrotask(() => {
+        handlers.error?.({ code: 'ENOENT' });
+      });
+      return proc;
+    });
+
+    await expect(runQmd(['update'])).rejects.toBeInstanceOf(QmdUnavailableError);
+  });
+
+  it('surfaces qmd non-zero exit codes as errors', async () => {
+    const { runQmd } = await loadRuntimeModule();
+    spawnMock.mockImplementation(() => {
+      const handlers = {};
+      const proc = {
+        on: (event, handler) => {
+          handlers[event] = handler;
+        }
+      };
+      queueMicrotask(() => {
+        handlers.close?.(2);
+      });
+      return proc;
+    });
+
+    await expect(runQmd(['update'])).rejects.toThrow('qmd exited with code 2');
+  });
+
+  it('prints consistent qmd missing guidance', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      const { printQmdMissing } = await loadRuntimeModule();
+      printQmdMissing();
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('ClawVault requires qmd.'));
+      expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('install-qmd'));
+    } finally {
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+});

package/bin/help-contract.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { registerAllCommandModules } from './test-helpers/cli-command-fixtures.js';
+
+describe('CLI help contract', () => {
+  it('includes expected high-level command surface', () => {
+    const help = registerAllCommandModules().helpInformation();
+    expect(help).toContain('init');
+    expect(help).toContain('context');
+    expect(help).toContain('compat');
+    expect(help).toContain('graph');
+    expect(help).toContain('repair-session');
+    expect(help).toContain('template');
+  });
+
+  it('documents context auto profile and compat strict options', () => {
+    const program = registerAllCommandModules();
+    const contextHelp = program.commands.find((command) => command.name() === 'context')?.helpInformation() ?? '';
+    const compatHelp = program.commands.find((command) => command.name() === 'compat')?.helpInformation() ?? '';
+    expect(contextHelp).toContain('--profile <profile>');
+    expect(contextHelp).toContain('auto');
+    expect(compatHelp).toContain('--strict');
+  });
+});

package/bin/register-core-commands.js

@@ -0,0 +1,139 @@
+/**
+ * Core vault lifecycle and write command registrations.
+ */
+
+export function registerCoreCommands(
+  program,
+  { chalk, path, fs, createVault, getVault, runQmd }
+) {
+  // === INIT ===
+  program
+    .command('init [path]')
+    .description('Initialize a new ClawVault')
+    .option('-n, --name <name>', 'Vault name')
+    .option('--qmd', 'Set up qmd semantic search collection')
+    .option('--qmd-collection <name>', 'qmd collection name (defaults to vault name)')
+    .action(async (vaultPath, options) => {
+      const targetPath = vaultPath || '.';
+      console.log(chalk.cyan(`\n🐘 Initializing ClawVault at ${path.resolve(targetPath)}...\n`));
+
+      try {
+        const vault = await createVault(targetPath, {
+          name: options.name || path.basename(path.resolve(targetPath)),
+          qmdCollection: options.qmdCollection
+        });
+
+        console.log(chalk.green('✓ Vault created'));
+        console.log(chalk.dim(`  Categories: ${vault.getCategories().join(', ')}`));
+
+        console.log(chalk.cyan('\nSetting up qmd collection...'));
+        try {
+          await runQmd([
+            'collection',
+            'add',
+            vault.getQmdRoot(),
+            '--name',
+            vault.getQmdCollection(),
+            '--mask',
+            '**/*.md'
+          ]);
+          console.log(chalk.green('✓ qmd collection created'));
+        } catch {
+          console.log(chalk.yellow('⚠ qmd collection may already exist'));
+        }
+
+        console.log(chalk.green('\n✅ ClawVault ready!\n'));
+        console.log(chalk.dim('Next steps:'));
+        console.log(chalk.dim('  clawvault store --category inbox --title "My note" --content "Hello world"'));
+        console.log(chalk.dim('  clawvault search "hello"'));
+        console.log();
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === 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')
+    .description('Store a new memory')
+    .requiredOption('-c, --category <category>', 'Category (preferences, decisions, patterns, people, projects, goals, transcripts, inbox)')
+    .requiredOption('-t, --title <title>', 'Document title')
+    .option('--content <content>', 'Content body')
+    .option('-f, --file <file>', 'Read content from file')
+    .option('--stdin', 'Read content from stdin')
+    .option('--overwrite', 'Overwrite if exists')
+    .option('--no-index', 'Skip qmd index update (auto-updates by default)')
+    .option('--embed', 'Also update qmd embeddings for vector search')
+    .option('-v, --vault <path>', 'Vault path (default: find nearest)')
+    .action(async (options) => {
+      try {
+        const vault = await getVault(options.vault);
+        let content = options.content || '';
+
+        if (options.file) {
+          content = fs.readFileSync(options.file, 'utf-8');
+        } else if (options.stdin) {
+          content = fs.readFileSync(0, 'utf-8');
+        }
+
+        const doc = await vault.store({
+          category: options.category,
+          title: options.title,
+          content,
+          overwrite: options.overwrite
+        });
+
+        console.log(chalk.green(`✓ Stored: ${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.embed) {
+            await runQmd(collection ? ['embed', '-c', collection] : ['embed']);
+          }
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === CAPTURE ===
+  program
+    .command('capture <note>')
+    .description('Quick capture to inbox')
+    .option('-t, --title <title>', 'Note title')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--no-index', 'Skip qmd index update')
+    .action(async (note, options) => {
+      try {
+        const vault = await getVault(options.vault);
+        const doc = await vault.capture(note, options.title);
+        console.log(chalk.green(`✓ Captured: ${doc.id}`));
+
+        if (options.index !== false) {
+          const collection = vault.getQmdCollection();
+          await runQmd(collection ? ['update', '-c', collection] : ['update']);
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}

package/bin/register-maintenance-commands.js

@@ -0,0 +1,137 @@
+/**
+ * Maintenance and graph-oriented command registrations.
+ * Split from the main CLI entrypoint to keep bin/clawvault.js maintainable.
+ */
+
+export function registerMaintenanceCommands(program, { chalk }) {
+  // === DOCTOR (health check) ===
+  program
+    .command('doctor')
+    .description('Check ClawVault setup health')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const { doctor } = await import('../dist/commands/doctor.js');
+        const report = await doctor(options.vault);
+
+        console.log(chalk.cyan('\n🩺 ClawVault Health Check\n'));
+        if (report.vaultPath) {
+          console.log(chalk.dim(`Vault: ${report.vaultPath}`));
+          console.log();
+        }
+
+        for (const check of report.checks) {
+          const prefix = check.status === 'ok'
+            ? chalk.green('✓')
+            : check.status === 'warn'
+              ? chalk.yellow('⚠')
+              : chalk.red('✗');
+          const detail = check.detail ? ` — ${check.detail}` : '';
+          console.log(`${prefix} ${check.label}${detail}`);
+          if (check.hint) {
+            console.log(chalk.dim(`  ${check.hint}`));
+          }
+        }
+
+        const issues = report.warnings + report.errors;
+        console.log();
+        if (issues === 0) {
+          console.log(chalk.green('✅ ClawVault is healthy!\n'));
+        } else {
+          console.log(chalk.yellow(`⚠ ${issues} issue(s) found\n`));
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === COMPAT (OpenClaw compatibility) ===
+  program
+    .command('compat')
+    .description('Check OpenClaw compatibility status')
+    .option('--strict', 'Exit non-zero when warnings are present')
+    .option('--base-dir <path>', 'Validate compatibility against alternate project root')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const { compatCommand, compatibilityExitCode } = await import('../dist/commands/compat.js');
+        const report = await compatCommand({
+          json: options.json,
+          strict: options.strict,
+          baseDir: options.baseDir
+        });
+        const exitCode = compatibilityExitCode(report, { strict: options.strict });
+        if (exitCode !== 0) {
+          process.exitCode = exitCode;
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === GRAPH ===
+  program
+    .command('graph')
+    .description('Show typed memory graph summary')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--refresh', 'Rebuild graph index before showing summary')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const { graphCommand } = await import('../dist/commands/graph.js');
+        await graphCommand({
+          vaultPath: options.vault,
+          refresh: options.refresh,
+          json: options.json
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === ENTITIES ===
+  program
+    .command('entities')
+    .description('List all linkable entities in the vault')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const { entitiesCommand } = await import('../dist/commands/entities.js');
+        await entitiesCommand({ json: options.json, vaultPath: options.vault });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === LINK ===
+  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 {
+        const { linkCommand } = await import('../dist/commands/link.js');
+        await linkCommand(file, {
+          all: options.all,
+          dryRun: options.dryRun,
+          backlinks: options.backlinks,
+          orphans: options.orphans,
+          rebuild: options.rebuild,
+          vaultPath: options.vault
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}