@soleri/core 9.0.3 → 9.2.0

package/src/vault/vault-maintenance.ts

@@ -0,0 +1,205 @@
+/**
+ * Vault maintenance operations — optimize, FTS rebuild, export, age report, archive/restore.
+ * Extracted from vault.ts as part of Wave 0C decomposition.
+ */
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { ProjectInfo } from './vault.js';
+import { rowToEntry } from './vault-entries.js';
+
+export function optimize(provider: PersistenceProvider): {
+  vacuumed: boolean;
+  analyzed: boolean;
+  ftsRebuilt: boolean;
+} {
+  let vacuumed = false;
+  let analyzed = false;
+  let ftsRebuilt = false;
+
+  if (provider.backend === 'sqlite') {
+    try {
+      provider.execSql('VACUUM');
+      vacuumed = true;
+    } catch {
+      // VACUUM may fail inside a transaction
+    }
+  }
+
+  try {
+    provider.execSql('ANALYZE');
+    analyzed = true;
+  } catch {
+    // Non-critical
+  }
+
+  try {
+    provider.ftsRebuild('entries');
+    provider.ftsRebuild('memories');
+    ftsRebuilt = true;
+  } catch {
+    // Non-critical
+  }
+
+  return { vacuumed, analyzed, ftsRebuilt };
+}
+
+export function rebuildFtsIndex(provider: PersistenceProvider): void {
+  try {
+    provider.run("INSERT INTO entries_fts(entries_fts) VALUES('rebuild')");
+  } catch {
+    // Graceful degradation — FTS rebuild failed
+  }
+}
+
+export function exportAll(provider: PersistenceProvider): {
+  entries: IntelligenceEntry[];
+  exportedAt: number;
+  count: number;
+} {
+  const rows = provider.all<Record<string, unknown>>(
+    'SELECT * FROM entries ORDER BY domain, title',
+  );
+  const entries = rows.map(rowToEntry);
+  return { entries, exportedAt: Math.floor(Date.now() / 1000), count: entries.length };
+}
+
+export function getAgeReport(provider: PersistenceProvider): {
+  total: number;
+  buckets: Array<{ label: string; count: number; minDays: number; maxDays: number }>;
+  oldestTimestamp: number | null;
+  newestTimestamp: number | null;
+} {
+  const rows = provider.all<{ created_at: number; updated_at: number }>(
+    'SELECT created_at, updated_at FROM entries',
+  );
+  const now = Math.floor(Date.now() / 1000);
+  const bucketDefs = [
+    { label: 'today', minDays: 0, maxDays: 1 },
+    { label: 'this_week', minDays: 1, maxDays: 7 },
+    { label: 'this_month', minDays: 7, maxDays: 30 },
+    { label: 'this_quarter', minDays: 30, maxDays: 90 },
+    { label: 'older', minDays: 90, maxDays: Infinity },
+  ];
+  const counts = Array.from<number>({ length: bucketDefs.length }).fill(0);
+  let oldest: number | null = null;
+  let newest: number | null = null;
+  for (const row of rows) {
+    const ts = row.created_at;
+    if (oldest === null || ts < oldest) oldest = ts;
+    if (newest === null || ts > newest) newest = ts;
+    const ageDays = (now - ts) / 86400;
+    for (let i = 0; i < bucketDefs.length; i++) {
+      if (ageDays >= bucketDefs[i].minDays && ageDays < bucketDefs[i].maxDays) {
+        counts[i]++;
+        break;
+      }
+    }
+  }
+  return {
+    total: rows.length,
+    buckets: bucketDefs.map((b, i) => Object.assign({}, b, { count: counts[i] })),
+    oldestTimestamp: oldest,
+    newestTimestamp: newest,
+  };
+}
+
+export function archive(
+  provider: PersistenceProvider,
+  options: { olderThanDays: number; reason?: string },
+): { archived: number } {
+  const cutoff = Math.floor(Date.now() / 1000) - options.olderThanDays * 86400;
+  const reason = options.reason ?? `Archived: older than ${options.olderThanDays} days`;
+
+  return provider.transaction(() => {
+    const candidates = provider.all<{ id: string }>(
+      'SELECT id FROM entries WHERE updated_at < ?',
+      [cutoff],
+    );
+
+    if (candidates.length === 0) return { archived: 0 };
+
+    let archived = 0;
+    for (const { id } of candidates) {
+      provider.run(
+        `INSERT OR IGNORE INTO entries_archive (id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until, archive_reason)
+         SELECT id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until, ?
+         FROM entries WHERE id = ?`,
+        [reason, id],
+      );
+      const result = provider.run('DELETE FROM entries WHERE id = ?', [id]);
+      archived += result.changes;
+    }
+
+    return { archived };
+  });
+}
+
+export function restore(provider: PersistenceProvider, id: string): boolean {
+  return provider.transaction(() => {
+    const archivedRow = provider.get<Record<string, unknown>>(
+      'SELECT * FROM entries_archive WHERE id = ?',
+      [id],
+    );
+    if (!archivedRow) return false;
+
+    provider.run(
+      `INSERT OR REPLACE INTO entries (id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until)
+       SELECT id, type, domain, title, severity, description, context, example, counter_example, why, tags, applies_to, created_at, updated_at, valid_from, valid_until
+       FROM entries_archive WHERE id = ?`,
+      [id],
+    );
+    provider.run('DELETE FROM entries_archive WHERE id = ?', [id]);
+    return true;
+  });
+}
+
+// ── Project operations ──────────────────────────────────────────────────
+
+export function registerProject(
+  provider: PersistenceProvider,
+  path: string,
+  name?: string,
+): ProjectInfo {
+  const projectName = name ?? path.replace(/\/$/, '').split('/').pop() ?? path;
+  const existing = getProject(provider, path);
+  if (existing) {
+    provider.run(
+      'UPDATE projects SET last_seen_at = unixepoch(), session_count = session_count + 1 WHERE path = ?',
+      [path],
+    );
+    return getProject(provider, path)!;
+  }
+  provider.run('INSERT INTO projects (path, name) VALUES (?, ?)', [path, projectName]);
+  return getProject(provider, path)!;
+}
+
+export function getProject(
+  provider: PersistenceProvider,
+  path: string,
+): ProjectInfo | null {
+  const row = provider.get<Record<string, unknown>>(
+    'SELECT * FROM projects WHERE path = ?',
+    [path],
+  );
+  if (!row) return null;
+  return {
+    path: row.path as string,
+    name: row.name as string,
+    registeredAt: row.registered_at as number,
+    lastSeenAt: row.last_seen_at as number,
+    sessionCount: row.session_count as number,
+  };
+}
+
+export function listProjects(provider: PersistenceProvider): ProjectInfo[] {
+  const rows = provider.all<Record<string, unknown>>(
+    'SELECT * FROM projects ORDER BY last_seen_at DESC',
+  );
+  return rows.map((row) => ({
+    path: row.path as string,
+    name: row.name as string,
+    registeredAt: row.registered_at as number,
+    lastSeenAt: row.last_seen_at as number,
+    sessionCount: row.session_count as number,
+  }));
+}

package/src/vault/vault-manager.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { VaultManager } from './vault-manager.js';
+
+// ─── Mock Vault ──────────────────────────────────────────────────────
+
+vi.mock('./vault.js', () => {
+  const MockVault = function (this: Record<string, unknown>, path: string) {
+    this._path = path;
+    this.search = vi.fn().mockReturnValue([]);
+    this.stats = vi.fn().mockReturnValue({ totalEntries: 0, byType: {}, byDomain: {}, bySeverity: {} });
+    this.close = vi.fn();
+  } as unknown as typeof import('./vault.js')['Vault'];
+  return { Vault: MockVault };
+});
+
+function makeManager(weights?: Partial<Record<'agent' | 'project' | 'team', number>>): VaultManager {
+  return new VaultManager({ agentId: 'test-agent', weights });
+}
+
+describe('VaultManager', () => {
+  let mgr: VaultManager;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mgr = makeManager();
+  });
+
+  // ── open / getTier / hasTier ────────────────────────────────────────
+
+  it('opens a vault for a tier', () => {
+    const vault = mgr.open('agent', '/tmp/agent.db');
+    expect(vault).toBeDefined();
+    expect(mgr.hasTier('agent')).toBe(true);
+    expect(mgr.size).toBe(1);
+  });
+
+  it('getTier returns the vault for an open tier', () => {
+    mgr.open('project', '/tmp/project.db');
+    const v = mgr.getTier('project');
+    expect(v).toBeDefined();
+  });
+
+  it('getTier throws for unconnected tier', () => {
+    expect(() => mgr.getTier('team')).toThrow("Vault tier 'team' is not connected");
+  });
+
+  it('re-opening a tier closes the previous vault', () => {
+    const first = mgr.open('agent', '/tmp/a.db');
+    mgr.open('agent', '/tmp/b.db');
+    expect(first.close).toHaveBeenCalled();
+    expect(mgr.size).toBe(1);
+  });
+
+  // ── disconnect ──────────────────────────────────────────────────────
+
+  it('disconnects a tier and closes its vault', () => {
+    const vault = mgr.open('agent', '/tmp/a.db');
+    expect(mgr.disconnect('agent')).toBe(true);
+    expect(vault.close).toHaveBeenCalled();
+    expect(mgr.hasTier('agent')).toBe(false);
+  });
+
+  it('disconnect returns false for unconnected tier', () => {
+    expect(mgr.disconnect('team')).toBe(false);
+  });
+
+  // ── connect / disconnectNamed / listConnected / getConnected ────────
+
+  it('connects a named vault source', () => {
+    const entry = mgr.connect('shared', '/tmp/shared.db', 0.7);
+    expect(entry.name).toBe('shared');
+    expect(entry.priority).toBe(0.7);
+  });
+
+  it('throws when connecting duplicate named vault', () => {
+    mgr.connect('shared', '/tmp/shared.db');
+    expect(() => mgr.connect('shared', '/tmp/other.db')).toThrow("already connected");
+  });
+
+  it('disconnects a named vault', () => {
+    const entry = mgr.connect('shared', '/tmp/shared.db');
+    expect(mgr.disconnectNamed('shared')).toBe(true);
+    expect(entry.vault.close).toHaveBeenCalled();
+  });
+
+  it('disconnectNamed returns false for unknown name', () => {
+    expect(mgr.disconnectNamed('unknown')).toBe(false);
+  });
+
+  it('listConnected returns entries sorted by priority desc', () => {
+    mgr.connect('low', '/tmp/low.db', 0.3);
+    mgr.connect('high', '/tmp/high.db', 0.9);
+    mgr.connect('mid', '/tmp/mid.db', 0.5);
+    const list = mgr.listConnected();
+    expect(list.map((e) => e.name)).toEqual(['high', 'mid', 'low']);
+  });
+
+  it('getConnected returns the entry or undefined', () => {
+    mgr.connect('x', '/tmp/x.db');
+    expect(mgr.getConnected('x')).toBeDefined();
+    expect(mgr.getConnected('y')).toBeUndefined();
+  });
+
+  // ── search ──────────────────────────────────────────────────────────
+
+  it('returns empty array when no vaults connected', () => {
+    expect(mgr.search('query')).toEqual([]);
+  });
+
+  it('merges results from tier vaults with weight', () => {
+    const agentVault = mgr.open('agent', '/tmp/a.db');
+    (agentVault.search as ReturnType<typeof vi.fn>).mockReturnValue([
+      { entry: { id: 'e1', title: 'A' }, score: 1.0 },
+    ]);
+
+    const results = mgr.search('test');
+    expect(results).toHaveLength(1);
+    // agent weight is 1.0, so score stays 1.0
+    expect(results[0].score).toBe(1.0);
+  });
+
+  it('deduplicates entries keeping highest weighted score', () => {
+    const entry = { id: 'e1', title: 'Shared' };
+    const agentVault = mgr.open('agent', '/tmp/a.db');
+    (agentVault.search as ReturnType<typeof vi.fn>).mockReturnValue([
+      { entry, score: 0.5 },
+    ]);
+
+    const teamVault = mgr.open('team', '/tmp/t.db');
+    (teamVault.search as ReturnType<typeof vi.fn>).mockReturnValue([
+      { entry, score: 0.8 },
+    ]);
+
+    const results = mgr.search('test');
+    // Agent: 0.5 * 1.0 = 0.5, Team: 0.8 * 0.6 = 0.48 → agent wins
+    expect(results).toHaveLength(1);
+    expect(results[0].score).toBe(0.5);
+  });
+
+  it('includes named vault results in search', () => {
+    const entry = mgr.connect('extra', '/tmp/extra.db', 0.9);
+    (entry.vault.search as ReturnType<typeof vi.fn>).mockReturnValue([
+      { entry: { id: 'e2', title: 'Extra' }, score: 1.0 },
+    ]);
+
+    const results = mgr.search('test');
+    expect(results).toHaveLength(1);
+    expect(results[0].score).toBe(0.9); // 1.0 * 0.9 priority
+  });
+
+  it('respects limit parameter', () => {
+    const vault = mgr.open('agent', '/tmp/a.db');
+    const manyResults = Array.from({ length: 30 }, (_, i) => ({
+      entry: { id: `e${i}`, title: `Entry ${i}` },
+      score: 1 - i * 0.01,
+    }));
+    (vault.search as ReturnType<typeof vi.fn>).mockReturnValue(manyResults);
+
+    expect(mgr.search('test', 5)).toHaveLength(5);
+  });
+
+  // ── listTiers ───────────────────────────────────────────────────────
+
+  it('lists all three tiers with connection status', () => {
+    mgr.open('agent', '/tmp/a.db');
+    const tiers = mgr.listTiers();
+    expect(tiers).toHaveLength(3);
+
+    const agent = tiers.find((t) => t.tier === 'agent');
+    expect(agent!.connected).toBe(true);
+
+    const project = tiers.find((t) => t.tier === 'project');
+    expect(project!.connected).toBe(false);
+    expect(project!.entryCount).toBe(0);
+  });
+
+  // ── getConfig / close ───────────────────────────────────────────────
+
+  it('returns the config', () => {
+    expect(mgr.getConfig().agentId).toBe('test-agent');
+  });
+
+  it('close shuts down all vaults', () => {
+    const av = mgr.open('agent', '/tmp/a.db');
+    const cv = mgr.connect('extra', '/tmp/e.db');
+    mgr.close();
+    expect(av.close).toHaveBeenCalled();
+    expect(cv.vault.close).toHaveBeenCalled();
+    expect(mgr.size).toBe(0);
+    expect(mgr.listConnected()).toEqual([]);
+  });
+
+  // ── custom weights ──────────────────────────────────────────────────
+
+  it('applies custom weights to search scoring', () => {
+    const customMgr = makeManager({ team: 2.0 });
+    const teamVault = customMgr.open('team', '/tmp/t.db');
+    (teamVault.search as ReturnType<typeof vi.fn>).mockReturnValue([
+      { entry: { id: 'e1', title: 'T' }, score: 0.5 },
+    ]);
+
+    const results = customMgr.search('test');
+    expect(results[0].score).toBe(1.0); // 0.5 * 2.0
+    customMgr.close();
+  });
+});

package/src/vault/vault-markdown-sync.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import {
+  entryToMarkdown,
+  syncEntryToMarkdown,
+  syncAllToMarkdown,
+  generateIndex,
+  titleToSlug,
+} from './vault-markdown-sync.js';
+import { Vault } from './vault.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+function makeEntry(overrides: Partial<IntelligenceEntry> = {}): IntelligenceEntry {
+  return {
+    id: `test-${randomUUID().slice(0, 8)}`,
+    type: 'pattern',
+    domain: 'architecture',
+    title: 'Test Pattern',
+    severity: 'suggestion',
+    description: 'A test pattern description.',
+    tags: ['testing', 'unit'],
+    ...overrides,
+  };
+}
+
+describe('vault-markdown-sync', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `vault-md-sync-${randomUUID().slice(0, 8)}`);
+    mkdirSync(tmpDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // ── titleToSlug ──────────────────────────────────────────────────
+
+  describe('titleToSlug', () => {
+    it('should slugify titles', () => {
+      expect(titleToSlug('Hello World')).toBe('hello-world');
+      expect(titleToSlug('Use Semantic Tokens!')).toBe('use-semantic-tokens');
+      expect(titleToSlug('  spaces  and -- dashes  ')).toBe('spaces-and-dashes');
+    });
+
+    it('should truncate long titles', () => {
+      const long = 'a'.repeat(200);
+      expect(titleToSlug(long).length).toBeLessThanOrEqual(80);
+    });
+  });
+
+  // ── entryToMarkdown ──────────────────────────────────────────────
+
+  describe('entryToMarkdown', () => {
+    it('should produce valid frontmatter', () => {
+      const entry = makeEntry({ title: 'My Pattern', domain: 'design' });
+      const md = entryToMarkdown(entry);
+
+      expect(md).toMatch(/^---\n/);
+      expect(md).toMatch(/\n---\n/);
+      expect(md).toContain(`id: "${entry.id}"`);
+      expect(md).toContain('type: "pattern"');
+      expect(md).toContain('domain: "design"');
+      expect(md).toContain('tags: ["testing", "unit"]');
+      expect(md).toContain('content_hash:');
+      expect(md).toContain('# My Pattern');
+      expect(md).toContain('A test pattern description.');
+    });
+
+    it('should include optional sections', () => {
+      const entry = makeEntry({
+        context: 'Some context.',
+        example: 'An example.',
+        counterExample: 'A counter-example.',
+        why: 'Because reasons.',
+      });
+      const md = entryToMarkdown(entry);
+
+      expect(md).toContain('## Context');
+      expect(md).toContain('Some context.');
+      expect(md).toContain('## Example');
+      expect(md).toContain('An example.');
+      expect(md).toContain('## Counter-Example');
+      expect(md).toContain('A counter-example.');
+      expect(md).toContain('## Why');
+      expect(md).toContain('Because reasons.');
+    });
+
+    it('should include tier and origin when present', () => {
+      const entry = makeEntry({ tier: 'project', origin: 'user' });
+      const md = entryToMarkdown(entry);
+      expect(md).toContain('tier: "project"');
+      expect(md).toContain('origin: "user"');
+    });
+  });
+
+  // ── syncEntryToMarkdown ──────────────────────────────────────────
+
+  describe('syncEntryToMarkdown', () => {
+    it('should create file in correct directory', async () => {
+      const entry = makeEntry({ domain: 'design', title: 'Color Tokens' });
+      await syncEntryToMarkdown(entry, tmpDir);
+
+      const filePath = join(tmpDir, 'vault', 'design', 'color-tokens.md');
+      expect(existsSync(filePath)).toBe(true);
+
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain('# Color Tokens');
+    });
+
+    it('should handle entries without domain', async () => {
+      const entry = makeEntry({ domain: '', title: 'No Domain Entry' });
+      await syncEntryToMarkdown(entry, tmpDir);
+
+      const filePath = join(tmpDir, 'vault', '_general', 'no-domain-entry.md');
+      expect(existsSync(filePath)).toBe(true);
+    });
+
+    it('should create missing knowledge dir automatically', async () => {
+      const deepDir = join(tmpDir, 'nested', 'deep');
+      const entry = makeEntry({ title: 'Deep Entry' });
+      await syncEntryToMarkdown(entry, deepDir);
+
+      const filePath = join(deepDir, 'vault', 'architecture', 'deep-entry.md');
+      expect(existsSync(filePath)).toBe(true);
+    });
+  });
+
+  // ── syncAllToMarkdown ────────────────────────────────────────────
+
+  describe('syncAllToMarkdown', () => {
+    let vault: Vault;
+
+    beforeEach(() => {
+      vault = new Vault(':memory:');
+    });
+
+    afterEach(() => {
+      vault.close();
+    });
+
+    it('should sync all entries', async () => {
+      vault.seed([
+        makeEntry({ title: 'Entry One', domain: 'design' }),
+        makeEntry({ title: 'Entry Two', domain: 'code' }),
+      ]);
+
+      const result = await syncAllToMarkdown(vault, tmpDir);
+      expect(result.synced).toBe(2);
+      expect(result.skipped).toBe(0);
+
+      expect(existsSync(join(tmpDir, 'vault', 'design', 'entry-one.md'))).toBe(true);
+      expect(existsSync(join(tmpDir, 'vault', 'code', 'entry-two.md'))).toBe(true);
+    });
+
+    it('should skip entries with existing up-to-date .md files', async () => {
+      const entry = makeEntry({ title: 'Stable Entry', domain: 'arch' });
+      vault.seed([entry]);
+
+      // First sync
+      const first = await syncAllToMarkdown(vault, tmpDir);
+      expect(first.synced).toBe(1);
+
+      // Second sync — should skip
+      const second = await syncAllToMarkdown(vault, tmpDir);
+      expect(second.skipped).toBe(1);
+      expect(second.synced).toBe(0);
+    });
+  });
+
+  // ── generateIndex ────────────────────────────────────────────────
+
+  describe('generateIndex', () => {
+    it('should count entries per domain', async () => {
+      // Set up vault directory structure
+      const vaultDir = join(tmpDir, 'vault');
+      mkdirSync(join(vaultDir, 'design'), { recursive: true });
+      mkdirSync(join(vaultDir, 'code'), { recursive: true });
+
+      writeFileSync(join(vaultDir, 'design', 'a.md'), '# A', 'utf-8');
+      writeFileSync(join(vaultDir, 'design', 'b.md'), '# B', 'utf-8');
+      writeFileSync(join(vaultDir, 'code', 'c.md'), '# C', 'utf-8');
+
+      await generateIndex(tmpDir);
+
+      const index = readFileSync(join(vaultDir, '_index.md'), 'utf-8');
+      expect(index).toContain('3 entries across 2 domains');
+      expect(index).toContain('design');
+      expect(index).toContain('code');
+    });
+
+    it('should handle missing knowledge dir gracefully', async () => {
+      const nonExistent = join(tmpDir, 'does-not-exist');
+      await generateIndex(nonExistent);
+      // Should not throw
+      expect(existsSync(join(nonExistent, 'vault', '_index.md'))).toBe(false);
+    });
+  });
+});