clawvault 2.5.1 → 2.5.3

package/bin/command-runtime.test.js

@@ -1,102 +1,154 @@
-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();
-    }
-  });
-});
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import path from 'path';
+
+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('injects qmd index from environment when configured', async () => {
+    const previous = process.env.CLAWVAULT_QMD_INDEX;
+    process.env.CLAWVAULT_QMD_INDEX = 'clawvault-test';
+
+    try {
+      const { runQmd } = await loadRuntimeModule();
+      spawnMock.mockImplementation((_command, _args) => {
+        const handlers = {};
+        const proc = {
+          on: (event, handler) => {
+            handlers[event] = handler;
+          }
+        };
+        queueMicrotask(() => {
+          handlers.close?.(0);
+        });
+        return proc;
+      });
+
+      await runQmd(['update']);
+      expect(spawnMock).toHaveBeenCalledWith(
+        'qmd',
+        ['--index', 'clawvault-test', 'update'],
+        { stdio: 'inherit' }
+      );
+    } finally {
+      if (previous === undefined) {
+        delete process.env.CLAWVAULT_QMD_INDEX;
+      } else {
+        process.env.CLAWVAULT_QMD_INDEX = previous;
+      }
+    }
+  });
+
+  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('exports and enforces argument/path sanitization helpers', async () => {
+    const { sanitizeQmdArg, validatePathWithinBase } = await loadRuntimeModule();
+    expect(sanitizeQmdArg('update')).toBe('update');
+    expect(sanitizeQmdArg(42)).toBe('42');
+    expect(() => sanitizeQmdArg('bad\0arg')).toThrow('contains null byte');
+
+    const safePath = validatePathWithinBase('notes/today.md', '/tmp/vault');
+    expect(safePath).toBe(path.resolve('/tmp/vault', 'notes/today.md'));
+    expect(() => validatePathWithinBase('../etc/passwd', '/tmp/vault')).toThrow('Path traversal detected');
+  });
+
+  it('rejects qmd args with null-byte injection attempts', async () => {
+    const { runQmd } = await loadRuntimeModule();
+    await expect(runQmd(['up\0date'])).rejects.toThrow('contains null byte');
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  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

@@ -1,28 +1,39 @@
-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('inject');
-    expect(help).toContain('compat');
-    expect(help).toContain('graph');
-    expect(help).toContain('reflect');
-    expect(help).toContain('replay');
-    expect(help).toContain('repair-session');
-    expect(help).toContain('template');
-    expect(help).toContain('config');
-    expect(help).toContain('route');
-  });
-
-  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');
-  });
-});
+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('inject');
+    expect(help).toContain('doctor');
+    expect(help).toContain('embed');
+    expect(help).toContain('compat');
+    expect(help).toContain('graph');
+    expect(help).toContain('reflect');
+    expect(help).toContain('replay');
+    expect(help).toContain('repair-session');
+    expect(help).toContain('project');
+    expect(help).toContain('template');
+    expect(help).toContain('config');
+    expect(help).toContain('route');
+  });
+
+  it('documents context/compat/inject/project help details', () => {
+    const program = registerAllCommandModules();
+    const contextHelp = program.commands.find((command) => command.name() === 'context')?.helpInformation() ?? '';
+    const compatHelp = program.commands.find((command) => command.name() === 'compat')?.helpInformation() ?? '';
+    const injectHelp = program.commands.find((command) => command.name() === 'inject')?.helpInformation() ?? '';
+    const projectCommand = program.commands.find((command) => command.name() === 'project');
+    const projectListHelp = projectCommand?.commands.find((command) => command.name() === 'list')?.helpInformation() ?? '';
+    const projectBoardHelp = projectCommand?.commands.find((command) => command.name() === 'board')?.helpInformation() ?? '';
+    expect(contextHelp).toContain('--profile <profile>');
+    expect(contextHelp).toContain('auto');
+    expect(compatHelp).toContain('--strict');
+    expect(injectHelp).toContain('inject.maxResults');
+    expect(injectHelp).toContain('inject.scope');
+    expect(projectListHelp).toContain('archived projects are hidden');
+    expect(projectBoardHelp).toContain('default: status');
+  });
+});

package/bin/register-config-commands.js

@@ -1,153 +1,153 @@
-/**
- * Runtime config command registrations backed by .clawvault.json.
- */
-
-function stringifyValue(value) {
-  if (Array.isArray(value)) {
-    if (value.every((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean')) {
-      return value.join(', ');
-    }
-    return JSON.stringify(value);
-  }
-  if (value && typeof value === 'object') {
-    return JSON.stringify(value);
-  }
-  if (value === null || value === undefined) {
-    return '(unset)';
-  }
-  return String(value);
-}
-
-function flattenConfig(value, prefix = '') {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    return [{ key: prefix || '(root)', value: stringifyValue(value) }];
-  }
-
-  const rows = [];
-  const keys = Object.keys(value).sort((left, right) => left.localeCompare(right));
-  for (const key of keys) {
-    const next = prefix ? `${prefix}.${key}` : key;
-    const entry = value[key];
-    if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
-      rows.push(...flattenConfig(entry, next));
-      continue;
-    }
-    rows.push({ key: next, value: stringifyValue(entry) });
-  }
-  return rows;
-}
-
-function printTable(rows) {
-  if (rows.length === 0) {
-    console.log('No config values found.');
-    return;
-  }
-  const keyWidth = Math.max(
-    'KEY'.length,
-    ...rows.map((row) => row.key.length)
-  );
-  const valueWidth = Math.max(
-    'VALUE'.length,
-    ...rows.map((row) => row.value.length)
-  );
-  const header = `${'KEY'.padEnd(keyWidth)}  ${'VALUE'.padEnd(valueWidth)}`;
-  const divider = `${'-'.repeat(keyWidth)}  ${'-'.repeat(valueWidth)}`;
-  console.log(header);
-  console.log(divider);
-  for (const row of rows) {
-    console.log(`${row.key.padEnd(keyWidth)}  ${row.value}`);
-  }
-}
-
-function normalizeConfigKey(key) {
-  return String(key || '').trim();
-}
-
-export function registerConfigCommands(program, { chalk, resolveVaultPath }) {
-  const config = program
-    .command('config')
-    .description('Read and modify runtime config');
-
-  config
-    .command('get <key>')
-    .description('Read a runtime config value (dot-notation supported)')
-    .option('-v, --vault <path>', 'Vault path')
-    .action(async (key, options) => {
-      try {
-        const { getConfigValue, SUPPORTED_CONFIG_KEYS } = await import('../dist/index.js');
-        const normalizedKey = normalizeConfigKey(key);
-        if (!SUPPORTED_CONFIG_KEYS.includes(normalizedKey)) {
-          throw new Error(`Unsupported config key: ${normalizedKey}`);
-        }
-
-        const value = getConfigValue(resolveVaultPath(options.vault), normalizedKey);
-        if (Array.isArray(value)) {
-          console.log(value.join(','));
-          return;
-        }
-        if (value && typeof value === 'object') {
-          console.log(JSON.stringify(value, null, 2));
-          return;
-        }
-        console.log(value === undefined || value === null ? '' : String(value));
-      } catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
-        process.exit(1);
-      }
-    });
-
-  config
-    .command('set <key> <value>')
-    .description('Set a runtime config value')
-    .option('-v, --vault <path>', 'Vault path')
-    .action(async (key, value, options) => {
-      try {
-        const { setConfigValue, SUPPORTED_CONFIG_KEYS } = await import('../dist/index.js');
-        const normalizedKey = normalizeConfigKey(key);
-        if (!SUPPORTED_CONFIG_KEYS.includes(normalizedKey)) {
-          throw new Error(`Unsupported config key: ${normalizedKey}`);
-        }
-        const result = setConfigValue(resolveVaultPath(options.vault), normalizedKey, value);
-        console.log(chalk.green(`✓ Updated ${normalizedKey}`));
-        console.log(chalk.dim(`  Value: ${stringifyValue(result.value)}`));
-      } catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
-        process.exit(1);
-      }
-    });
-
-  config
-    .command('list')
-    .description('List all config values')
-    .option('-v, --vault <path>', 'Vault path')
-    .action(async (options) => {
-      try {
-        const { listConfig } = await import('../dist/index.js');
-        const values = listConfig(resolveVaultPath(options.vault));
-        const rows = flattenConfig(values);
-        printTable(rows);
-      } catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
-        process.exit(1);
-      }
-    });
-
-  config
-    .command('reset')
-    .description('Reset runtime config values to defaults')
-    .option('--confirm', 'Confirm reset')
-    .option('-v, --vault <path>', 'Vault path')
-    .action(async (options) => {
-      try {
-        if (!options.confirm) {
-          throw new Error('Refusing to reset config without --confirm.');
-        }
-        const { resetConfig } = await import('../dist/index.js');
-        resetConfig(resolveVaultPath(options.vault));
-        console.log(chalk.green('✓ Config reset to defaults'));
-      } catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
-        process.exit(1);
-      }
-    });
-}
+/**
+ * Runtime config command registrations backed by .clawvault.json.
+ */
+
+function stringifyValue(value) {
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean')) {
+      return value.join(', ');
+    }
+    return JSON.stringify(value);
+  }
+  if (value && typeof value === 'object') {
+    return JSON.stringify(value);
+  }
+  if (value === null || value === undefined) {
+    return '(unset)';
+  }
+  return String(value);
+}
+
+function flattenConfig(value, prefix = '') {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return [{ key: prefix || '(root)', value: stringifyValue(value) }];
+  }
+
+  const rows = [];
+  const keys = Object.keys(value).sort((left, right) => left.localeCompare(right));
+  for (const key of keys) {
+    const next = prefix ? `${prefix}.${key}` : key;
+    const entry = value[key];
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+      rows.push(...flattenConfig(entry, next));
+      continue;
+    }
+    rows.push({ key: next, value: stringifyValue(entry) });
+  }
+  return rows;
+}
+
+function printTable(rows) {
+  if (rows.length === 0) {
+    console.log('No config values found.');
+    return;
+  }
+  const keyWidth = Math.max(
+    'KEY'.length,
+    ...rows.map((row) => row.key.length)
+  );
+  const valueWidth = Math.max(
+    'VALUE'.length,
+    ...rows.map((row) => row.value.length)
+  );
+  const header = `${'KEY'.padEnd(keyWidth)}  ${'VALUE'.padEnd(valueWidth)}`;
+  const divider = `${'-'.repeat(keyWidth)}  ${'-'.repeat(valueWidth)}`;
+  console.log(header);
+  console.log(divider);
+  for (const row of rows) {
+    console.log(`${row.key.padEnd(keyWidth)}  ${row.value}`);
+  }
+}
+
+function normalizeConfigKey(key) {
+  return String(key || '').trim();
+}
+
+export function registerConfigCommands(program, { chalk, resolveVaultPath }) {
+  const config = program
+    .command('config')
+    .description('Read and modify runtime configuration');
+
+  config
+    .command('get <key>')
+    .description('Read a runtime config value (dot-notation supported)')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (key, options) => {
+      try {
+        const { getConfigValue, SUPPORTED_CONFIG_KEYS } = await import('../dist/index.js');
+        const normalizedKey = normalizeConfigKey(key);
+        if (!SUPPORTED_CONFIG_KEYS.includes(normalizedKey)) {
+          throw new Error(`Unsupported config key: ${normalizedKey}`);
+        }
+
+        const value = getConfigValue(resolveVaultPath(options.vault), normalizedKey);
+        if (Array.isArray(value)) {
+          console.log(value.join(','));
+          return;
+        }
+        if (value && typeof value === 'object') {
+          console.log(JSON.stringify(value, null, 2));
+          return;
+        }
+        console.log(value === undefined || value === null ? '' : String(value));
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  config
+    .command('set <key> <value>')
+    .description('Set a runtime config value')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (key, value, options) => {
+      try {
+        const { setConfigValue, SUPPORTED_CONFIG_KEYS } = await import('../dist/index.js');
+        const normalizedKey = normalizeConfigKey(key);
+        if (!SUPPORTED_CONFIG_KEYS.includes(normalizedKey)) {
+          throw new Error(`Unsupported config key: ${normalizedKey}`);
+        }
+        const result = setConfigValue(resolveVaultPath(options.vault), normalizedKey, value);
+        console.log(chalk.green(`✓ Updated ${normalizedKey}`));
+        console.log(chalk.dim(`  Value: ${stringifyValue(result.value)}`));
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  config
+    .command('list')
+    .description('List all config values')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const { listConfig } = await import('../dist/index.js');
+        const values = listConfig(resolveVaultPath(options.vault));
+        const rows = flattenConfig(values);
+        printTable(rows);
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  config
+    .command('reset')
+    .description('Reset runtime config values to defaults')
+    .option('--confirm', 'Confirm reset (required)')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        if (!options.confirm) {
+          throw new Error('Refusing to reset config without --confirm.');
+        }
+        const { resetConfig } = await import('../dist/index.js');
+        resetConfig(resolveVaultPath(options.vault));
+        console.log(chalk.green('✓ Config reset to defaults'));
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}