@winspan/claude-forge 8.39.0 → 8.50.6

package/tests/unit/storage/sessions-aggregate.test.ts

@@ -0,0 +1,435 @@
+/**
+ * sessions 聚合表测试
+ *
+ * 背景：querySessions 旧实现对 events 表做 GROUP BY + 子查询提取 first_prompt，
+ * 复杂度 O(sessions × events)。现在在 writeEvent 里 upsert 到 sessions 聚合表，
+ * querySessions 直接读聚合表 → O(sessions)。
+ *
+ * 覆盖：
+ *   1. writeEvent 首次命中 session_id 时插入聚合行
+ *   2. 同一 session 多次事件 → event_count 递增、end_time 更新
+ *   3. 首条 UserPromptSubmit 写入 first_prompt；后续事件不覆盖
+ *   4. querySessions 从聚合表读取，不触及 events 相关子查询
+ *   5. 旧库启动时的 backfill 迁移：空 sessions + 有 events → 自动对齐
+ *   6. upsertSession 失败不应阻塞原 events 写入（硬性约束）
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import Database from 'better-sqlite3';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import type { ForgeEvent } from '../../../src/core/types.js';
+
+describe('SQLiteStorage: sessions aggregate table', () => {
+  let tmp: string;
+  let dbPath: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-sess-agg-'));
+    dbPath = join(tmp, 'data.db');
+    storage = new SQLiteStorage(dbPath);
+  });
+
+  afterEach(() => {
+    try {
+      storage.getDatabase().close();
+    } catch {
+      // already closed
+    }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function makeEvent(overrides: Partial<ForgeEvent>): ForgeEvent {
+    return {
+      session_id: 's1',
+      project_path: '/tmp/proj',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      ...overrides,
+    };
+  }
+
+  it('首次写入事件应在 sessions 表创建一行', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 's-new',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: '你好',
+    }));
+
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT * FROM sessions WHERE session_id = ?')
+      .get('s-new') as Record<string, unknown>;
+
+    expect(row).toBeDefined();
+    expect(row.session_id).toBe('s-new');
+    expect(row.project_path).toBe('/tmp/proj');
+    expect(row.first_prompt).toBe('你好');
+    expect(row.start_time).toBe('2026-05-10T10:00:00.000Z');
+    expect(row.end_time).toBe('2026-05-10T10:00:00.000Z');
+    expect(row.event_count).toBe(1);
+  });
+
+  it('同一 session 多次事件应累加 event_count 并推进 end_time', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 's-multi',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'first',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 's-multi',
+      timestamp: '2026-05-10T10:05:00.000Z',
+      hook_type: 'PreToolUse',
+      tool_name: 'Read',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 's-multi',
+      timestamp: '2026-05-10T10:10:00.000Z',
+      hook_type: 'PostToolUse',
+      tool_name: 'Read',
+    }));
+
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT event_count, start_time, end_time, last_event_time FROM sessions WHERE session_id = ?')
+      .get('s-multi') as Record<string, unknown>;
+
+    expect(row.event_count).toBe(3);
+    expect(row.start_time).toBe('2026-05-10T10:00:00.000Z');
+    expect(row.end_time).toBe('2026-05-10T10:10:00.000Z');
+    expect(row.last_event_time).toBe('2026-05-10T10:10:00.000Z');
+  });
+
+  it('first_prompt 仅在首次 UserPromptSubmit 时落库，后续事件不覆盖', () => {
+    // 第一条：非 UserPromptSubmit → first_prompt 应为 null
+    storage.writeEvent(makeEvent({
+      session_id: 's-fp',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'PreToolUse',
+      tool_name: 'Read',
+    }));
+
+    let row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-fp') as Record<string, unknown>;
+    expect(row.first_prompt).toBeNull();
+
+    // 第二条：UserPromptSubmit → first_prompt 应被填充
+    storage.writeEvent(makeEvent({
+      session_id: 's-fp',
+      timestamp: '2026-05-10T10:01:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: '真正的第一条 prompt',
+    }));
+
+    row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-fp') as Record<string, unknown>;
+    expect(row.first_prompt).toBe('真正的第一条 prompt');
+
+    // 第三条：又一条 UserPromptSubmit → 不应覆盖第二条
+    storage.writeEvent(makeEvent({
+      session_id: 's-fp',
+      timestamp: '2026-05-10T10:02:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: '后续的 prompt 不应覆盖',
+    }));
+
+    row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-fp') as Record<string, unknown>;
+    expect(row.first_prompt).toBe('真正的第一条 prompt');
+  });
+
+  it('user_prompt 超长时 first_prompt 截断到 200 字', () => {
+    const longPrompt = 'x'.repeat(500);
+    storage.writeEvent(makeEvent({
+      session_id: 's-long',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: longPrompt,
+    }));
+
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-long') as Record<string, unknown>;
+    expect((row.first_prompt as string).length).toBe(200);
+  });
+
+  it('querySessions 直接读聚合表，不执行 events 相关子查询', () => {
+    // 构造 3 个 session，每个 3 条事件
+    const sessionIds = ['sq-a', 'sq-b', 'sq-c'];
+    for (const sid of sessionIds) {
+      storage.writeEvent(makeEvent({
+        session_id: sid,
+        timestamp: `2026-05-10T10:0${sessionIds.indexOf(sid)}:00.000Z`,
+        hook_type: 'UserPromptSubmit',
+        user_prompt: `prompt of ${sid}`,
+      }));
+      storage.writeEvent(makeEvent({
+        session_id: sid,
+        timestamp: `2026-05-10T10:0${sessionIds.indexOf(sid)}:30.000Z`,
+        hook_type: 'PreToolUse',
+        tool_name: 'Read',
+      }));
+      storage.writeEvent(makeEvent({
+        session_id: sid,
+        timestamp: `2026-05-10T10:0${sessionIds.indexOf(sid)}:40.000Z`,
+        hook_type: 'PostToolUse',
+        tool_name: 'Read',
+      }));
+    }
+
+    // 用 EXPLAIN QUERY PLAN 验证只扫聚合表
+    const plan = storage
+      .getDatabase()
+      .prepare(`EXPLAIN QUERY PLAN
+        SELECT session_id, first_prompt, event_count, start_time,
+               COALESCE(end_time, last_event_time, start_time) AS end_time
+        FROM sessions
+        ORDER BY start_time DESC
+        LIMIT 10`)
+      .all() as Array<{ detail: string }>;
+    const planText = plan.map(p => p.detail).join(' | ');
+    expect(planText).toMatch(/sessions/i);
+    expect(planText).not.toMatch(/events/i);
+
+    const results = storage.querySessions({ limit: 10 });
+    expect(results).toHaveLength(3);
+    expect(results.map(r => r.session_id).sort()).toEqual(['sq-a', 'sq-b', 'sq-c']);
+    // start_time DESC → sq-c, sq-b, sq-a
+    expect(results[0].session_id).toBe('sq-c');
+    for (const r of results) {
+      expect(r.event_count).toBe(3);
+      expect(r.first_prompt).toBe(`prompt of ${r.session_id}`);
+    }
+  });
+
+  it('querySessions 支持 project_path 过滤', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 'proj-a-1',
+      project_path: '/proj/a',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'a-1',
+      timestamp: '2026-05-10T10:00:00.000Z',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 'proj-b-1',
+      project_path: '/proj/b',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'b-1',
+      timestamp: '2026-05-10T10:01:00.000Z',
+    }));
+
+    const results = storage.querySessions({ project_path: '/proj/a', limit: 10 });
+    expect(results).toHaveLength(1);
+    expect(results[0].session_id).toBe('proj-a-1');
+  });
+
+  it('backfill 迁移：旧库只有 events、sessions 为空时启动应自动对齐', () => {
+    // 先用当前 storage 写几条事件，随后清空 sessions 模拟旧库
+    storage.writeEvent(makeEvent({
+      session_id: 'bf-1',
+      timestamp: '2026-05-10T09:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'backfill-prompt-1',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 'bf-1',
+      timestamp: '2026-05-10T09:05:00.000Z',
+      hook_type: 'PreToolUse',
+      tool_name: 'Read',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 'bf-2',
+      timestamp: '2026-05-10T09:10:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'backfill-prompt-2',
+    }));
+
+    // 清空 sessions，模拟"旧库已有 events，但无聚合"
+    storage.getDatabase().exec('DELETE FROM sessions');
+    expect(
+      (storage.getDatabase().prepare('SELECT COUNT(*) AS c FROM sessions').get() as { c: number }).c
+    ).toBe(0);
+
+    // 关闭当前 storage，重新打开 → 触发 runMigrations → backfillSessionsIfNeeded
+    storage.getDatabase().close();
+    storage = new SQLiteStorage(dbPath);
+
+    const rows = storage
+      .getDatabase()
+      .prepare('SELECT session_id, first_prompt, event_count FROM sessions ORDER BY session_id')
+      .all() as Array<Record<string, unknown>>;
+    expect(rows).toHaveLength(2);
+    expect(rows[0].session_id).toBe('bf-1');
+    expect(rows[0].first_prompt).toBe('backfill-prompt-1');
+    expect(rows[0].event_count).toBe(2);
+    expect(rows[1].session_id).toBe('bf-2');
+    expect(rows[1].first_prompt).toBe('backfill-prompt-2');
+    expect(rows[1].event_count).toBe(1);
+  });
+
+  it('backfill 幂等：sessions 已有 first_prompt 时再次打开不会重复回填/覆盖', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 'idem-1',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'original',
+      timestamp: '2026-05-10T08:00:00.000Z',
+    }));
+
+    // 手工把 event_count 改成一个明显异常值，重新打开后如果被 backfill 覆盖就会恢复为 1
+    storage.getDatabase().prepare('UPDATE sessions SET event_count = 999 WHERE session_id = ?').run('idem-1');
+    storage.getDatabase().close();
+
+    storage = new SQLiteStorage(dbPath);
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT event_count, first_prompt FROM sessions WHERE session_id = ?')
+      .get('idem-1') as Record<string, unknown>;
+    expect(row.event_count).toBe(999); // 未被回填覆盖
+    expect(row.first_prompt).toBe('original');
+  });
+
+  it('upsertSession 失败不应阻塞 writeEvent 的事件写入', () => {
+    // 注入一个会让 upsert 抛错的场景：伪造一个 hook_type 约束内合法但 session 列有
+    // 致命冲突的情况较复杂，这里改用直接 monkey-patch upsertSession 来模拟失败路径，
+    // 断言 events 表仍然写入成功。
+    const originalUpsert = storage.upsertSession.bind(storage);
+    let upsertCalls = 0;
+    storage.upsertSession = (evt: ForgeEvent): void => {
+      upsertCalls += 1;
+      throw new Error('simulated upsert failure');
+    };
+
+    const evt = makeEvent({
+      session_id: 'fail-session',
+      timestamp: '2026-05-10T11:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'still written',
+    });
+    expect(() => storage.writeEvent(evt)).not.toThrow();
+    expect(upsertCalls).toBe(1);
+
+    // events 表中应该有这条事件
+    const eventRow = storage
+      .getDatabase()
+      .prepare('SELECT session_id, user_prompt FROM events WHERE session_id = ?')
+      .get('fail-session') as Record<string, unknown>;
+    expect(eventRow).toBeDefined();
+    expect(eventRow.user_prompt).toBe('still written');
+
+    // 恢复，避免污染其它用例
+    storage.upsertSession = originalUpsert;
+  });
+
+  it('runMigrations 对已有 first_prompt 列的库应幂等（重复打开不报错）', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 're-open',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'hi',
+    }));
+    storage.getDatabase().close();
+
+    // 再打开两次，不应抛异常
+    expect(() => {
+      const s2 = new SQLiteStorage(dbPath);
+      s2.getDatabase().close();
+      const s3 = new SQLiteStorage(dbPath);
+      s3.getDatabase().close();
+    }).not.toThrow();
+
+    storage = new SQLiteStorage(dbPath);
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('re-open') as Record<string, unknown>;
+    expect(row.first_prompt).toBe('hi');
+  });
+});
+
+describe('SQLiteStorage: legacy DB without first_prompt column', () => {
+  let tmp: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-sess-legacy-'));
+    dbPath = join(tmp, 'legacy.db');
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('旧 sessions 表无 first_prompt 列时 runMigrations 应自动 ALTER + backfill', () => {
+    // 手工建一个老版本的库：events 表 + 老 sessions 表（无 first_prompt 列）
+    const raw = new Database(dbPath);
+    raw.exec(`
+      CREATE TABLE events (
+        event_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        project_path TEXT NOT NULL,
+        timestamp TEXT NOT NULL,
+        hook_type TEXT NOT NULL,
+        tool_name TEXT,
+        tool_input TEXT,
+        tool_output TEXT,
+        user_prompt TEXT,
+        ai_response TEXT,
+        distilled INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE TABLE sessions (
+        session_id TEXT PRIMARY KEY,
+        project_path TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active',
+        start_time TEXT NOT NULL,
+        end_time TEXT,
+        last_event_time TEXT,
+        event_count INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+    `);
+    // 插入 events（模拟旧库残留的未聚合数据）
+    raw.prepare(`
+      INSERT INTO events (event_id, session_id, project_path, timestamp, hook_type, user_prompt)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run('e1', 'legacy-1', '/proj', '2026-05-10T07:00:00.000Z', 'UserPromptSubmit', 'legacy prompt');
+    raw.prepare(`
+      INSERT INTO events (event_id, session_id, project_path, timestamp, hook_type, tool_name)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run('e2', 'legacy-1', '/proj', '2026-05-10T07:05:00.000Z', 'PreToolUse', 'Read');
+    raw.close();
+
+    // 用 SQLiteStorage 打开 → 期待：ALTER 加 first_prompt 列 + backfill
+    const storage = new SQLiteStorage(dbPath);
+    try {
+      // 列存在
+      const cols = storage
+        .getDatabase()
+        .prepare('PRAGMA table_info(sessions)')
+        .all() as Array<{ name: string }>;
+      expect(cols.some(c => c.name === 'first_prompt')).toBe(true);
+
+      // backfill 填充
+      const row = storage
+        .getDatabase()
+        .prepare('SELECT first_prompt, event_count FROM sessions WHERE session_id = ?')
+        .get('legacy-1') as Record<string, unknown>;
+      expect(row).toBeDefined();
+      expect(row.first_prompt).toBe('legacy prompt');
+      expect(row.event_count).toBe(2);
+    } finally {
+      storage.getDatabase().close();
+    }
+  });
+});