@winspan/claude-forge 8.50.6 → 8.51.0

package/src/cli/commands/stats.ts

@@ -7,8 +7,7 @@
 import { Command } from 'commander';
 import { SQLiteStorage } from '../../core/storage/sqlite.js';
 import chalk from 'chalk';
-import path from 'node:path';
-import { homedir } from 'node:os';
+import { FORGE_PATHS } from '../../core/constants.js';
 
 export function createStatsCommand(): Command {
   const cmd = new Command('stats');
@@ -18,7 +17,7 @@ export function createStatsCommand(): Command {
     .option('-d, --days <days>', '统计天数', '7')
     .option('-p, --project <path>', '项目路径')
     .action((options: { days: string; project?: string }) => {
-      const dbPath = path.join(homedir(), '.claude-forge', 'data.db');
+      const dbPath = FORGE_PATHS.database();
       const storage = new SQLiteStorage(dbPath);
 
       const days = parseInt(options.days);

package/src/cli/commands/status.ts

@@ -2,10 +2,10 @@ import fs from 'fs';
 import path from 'path';
 import { homedir } from 'os';
 import type { Command } from 'commander';
-import { FORGE_HOME, FORGE_PATHS } from '../../core/constants.js';
+import { FORGE_PATHS } from '../../core/constants.js';
 import { ConfigManager } from '../../core/config.js';
 
-const PID_FILE = path.join(FORGE_HOME, 'daemon.pid');
+const PID_FILE = FORGE_PATHS.daemonPid();
 
 function readPid(): number | null {
   if (!fs.existsSync(PID_FILE)) return null;

package/src/cli/commands/trace.ts

@@ -11,7 +11,7 @@ import path from 'node:path';
 import { homedir } from 'node:os';
 import chalk from 'chalk';
 import { SQLiteStorage } from '../../core/storage/sqlite.js';
-import { FORGE_PATHS } from '../../core/constants.js';
+import { FORGE_PATHS, DEFAULTS } from '../../core/constants.js';
 import { ConfigManager } from '../../core/config.js';
 
 function resolveDbPath(): string {
@@ -79,19 +79,17 @@ export function register(program: Command): void {
       // 4. Query storage for session details
       const dbPath = resolveDbPath();
       const storage = new SQLiteStorage(dbPath);
-      const db = storage.getDatabase();
 
       console.log(chalk.bold(`\nCommit: ${commitHash.slice(0, 7)} (${commitMessage})\n`));
 
       for (const sessionId of sessionIds) {
-        printSessionTrace(storage, db, sessionId);
+        printSessionTrace(storage, sessionId);
       }
     });
 }
 
 function printSessionTrace(
   storage: SQLiteStorage,
-  db: ReturnType<SQLiteStorage['getDatabase']>,
   sessionId: string,
 ): void {
   // Find session
@@ -111,32 +109,18 @@ function printSessionTrace(
   const durationMin = Math.round((end.getTime() - start.getTime()) / 60000);
   const timeStr = `${formatTime(start)} - ${formatTime(end)} (${durationMin} min)`;
 
-  // Event breakdown
-  const eventBreakdown = db.prepare(`
-    SELECT hook_type, COUNT(*) as cnt FROM events
-    WHERE session_id = ? GROUP BY hook_type
-  `).all(fullId) as Array<{ hook_type: string; cnt: number }>;
-
-  const totalEvents = eventBreakdown.reduce((sum, r) => sum + r.cnt, 0);
-  const breakdownStr = eventBreakdown.map(r => `${r.hook_type}: ${r.cnt}`).join(', ');
+  // H2 Phase 3: 改用 facade 聚合方法。
+  const eventBreakdown = storage.aggregateHookTypeBySession(fullId);
+  const totalEvents = eventBreakdown.reduce((sum, r) => sum + r.count, 0);
+  const breakdownStr = eventBreakdown.map(r => `${r.hook_type}: ${r.count}`).join(', ');
 
   // Agent calls
-  const agentRows = db.prepare(`
-    SELECT json_extract(tool_input, '$.subagent_type') as agent_type, COUNT(*) as cnt
-    FROM events
-    WHERE session_id = ? AND tool_name IN ('Agent', 'Task') AND tool_input IS NOT NULL
-    GROUP BY agent_type
-  `).all(fullId) as Array<{ agent_type: string | null; cnt: number }>;
-
-  const totalAgents = agentRows.reduce((sum, r) => sum + r.cnt, 0);
+  const agentRows = storage.aggregateAgentTypeBySession(fullId);
+  const totalAgents = agentRows.reduce((sum, r) => sum + r.count, 0);
   const agentNames = agentRows.filter(r => r.agent_type).map(r => r.agent_type as string);
 
   // Skills
-  const skillRows = db.prepare(`
-    SELECT DISTINCT skill_id FROM skill_invocations WHERE session_id = ?
-  `).all(fullId) as Array<{ skill_id: string }>;
-
-  const skillNames = skillRows.map(r => r.skill_id);
+  const skillNames = storage.queryDistinctSkillIdsBySession(fullId);
 
   // Output
   console.log(chalk.cyan(`  Session: ${fullId}`));
@@ -151,7 +135,7 @@ function printSessionTrace(
     console.log(`  Skills: ${skillNames.join(', ')}`);
   }
 
-  console.log(chalk.dim(`  Dashboard: http://localhost:3721/sessions/${fullId}`));
+  console.log(chalk.dim(`  Dashboard: http://localhost:${DEFAULTS.WEB_PORT}/sessions/${fullId}`));
   console.log();
 }
 

package/src/cli/init/hook-manager.ts

@@ -1,11 +1,11 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { FORGE_HOME } from '../../core/constants.js';
+import { FORGE_PATHS } from '../../core/constants.js';
 
 export const CLAUDE_HOME = path.join(os.homedir(), '.claude');
 export const SETTINGS_PATH = path.join(CLAUDE_HOME, 'settings.json');
-export const HOOKS_DIR = path.join(FORGE_HOME, 'hooks');
+export const HOOKS_DIR = FORGE_PATHS.hooks();
 
 export const HOOK_SCRIPT_NAMES = [
   'pre-tool-use.sh',

package/src/core/ai/provider.ts

@@ -24,8 +24,8 @@ export interface CompleteWithImageOptions extends CompleteOptions {
   images: ImageInput[];
 }
 import { logger } from '../utils/logger.js';
+import { DEFAULTS } from '../constants.js';
 
-const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
 const DEFAULT_MAX_TOKENS = 4096;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_RETRIES = 2;
@@ -98,7 +98,7 @@ export class ClaudeProvider {
   private totalLatencyMs = 0;
 
   constructor(apiKey: string, model?: string, baseUrl?: string) {
-    this.model = model || DEFAULT_MODEL;
+    this.model = model || DEFAULTS.AI_MODEL;
     this.client = new Anthropic({
       apiKey,
       ...(baseUrl ? { baseURL: baseUrl } : {}),

package/src/core/constants.ts

@@ -11,6 +11,23 @@ export const FORGE_PATHS = {
   config: () => join(FORGE_HOME, 'config.yaml'),
   database: () => join(FORGE_HOME, 'data.db'),
   logs: () => join(FORGE_HOME, 'logs'),
+
+  // ── Daemon runtime files ────────────────────────────────
+  daemonSocket: () => join(FORGE_HOME, 'daemon.sock'),
+  daemonPid:    () => join(FORGE_HOME, 'daemon.pid'),
+  daemonToken:  () => join(FORGE_HOME, 'daemon.token'),
+  daemonLog:    () => join(FORGE_HOME, 'daemon.log'),
+  daemonStdout: () => join(FORGE_HOME, 'daemon-stdout.log'),
+  daemonStderr: () => join(FORGE_HOME, 'daemon-stderr.log'),
+
+  // ── Subdirs ─────────────────────────────────────────────
+  hooks:        () => join(FORGE_HOME, 'hooks'),
+  queue:        () => join(FORGE_HOME, 'queue'),
+  queueDead:    () => join(FORGE_HOME, 'queue', 'dead'),
+
+  // ── Patchable targets ───────────────────────────────────
+  routingYaml:  () => join(FORGE_HOME, 'routing.yaml'),
+  backups:      (kind: 'skills' | 'routing') => join(FORGE_HOME, 'backups', kind),
 } as const;
 
 /**
@@ -41,5 +58,5 @@ export const DEFAULTS = {
   AI_MODEL: 'claude-sonnet-4-6',
   AI_PROVIDER: 'anthropic',
   STORAGE_MAX_SIZE_MB: 500,
-  WEB_PORT: 3456,
+  WEB_PORT: 3721,
 } as const;

package/src/core/event-fields.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed getters for ForgeEvent.tool_input fields.
+ *
+ * Centralises the defensive-access pattern that previously lived as
+ * `(e.tool_input as any)?.command ?? ''` across 30+ call sites. Each
+ * getter returns `string | undefined`; callers decide their own fallback.
+ *
+ * Adding a new tool field? Extend ToolInputFields in core/types.ts first,
+ * then add a getter here if it needs a normalised access entry.
+ */
+import type { ForgeEvent } from './types.js';
+
+export function getCommand(e: ForgeEvent): string | undefined {
+  const c = e.tool_input?.command;
+  return typeof c === 'string' ? c : undefined;
+}
+
+export function getFilePath(e: ForgeEvent): string | undefined {
+  const fp = e.tool_input?.file_path ?? e.tool_input?.notebook_path;
+  return typeof fp === 'string' && fp.length > 0 ? fp : undefined;
+}
+
+export function getUserPrompt(e: ForgeEvent): string | undefined {
+  if (typeof e.user_prompt === 'string') return e.user_prompt;
+  const fallback = e.tool_input?.user_prompt;
+  return typeof fallback === 'string' ? fallback : undefined;
+}
+
+export function getSubagentType(e: ForgeEvent): string | undefined {
+  const s = e.tool_input?.subagent_type;
+  return typeof s === 'string' ? s : undefined;
+}

package/src/core/queue/index.ts

@@ -16,16 +16,15 @@
 import { mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import type { SQLiteStorage } from '../storage/sqlite.js';
 import type { ForgeEvent } from '../types.js';
 import { logger } from '../utils/logger.js';
+import { FORGE_PATHS } from '../constants.js';
 
 // ── Constants ──────────────────────────────────────────────────────────────
-const FORGE_DIR = join(homedir(), '.claude-forge');
-export const QUEUE_DIR = join(FORGE_DIR, 'queue');
-export const DEAD_DIR = join(FORGE_DIR, 'queue', 'dead');
+export const QUEUE_DIR = FORGE_PATHS.queue();
+export const DEAD_DIR = FORGE_PATHS.queueDead();
 export const MAX_FILES = 500;
 export const TTL_DAYS = 7;
 

package/src/core/storage/base.ts

@@ -3,7 +3,7 @@
  *
  * 拆分自 sqlite.ts。仅负责：
  * - 打开数据库连接 + 配置 PRAGMA
- * - 加载 schema.sql 或 inline fallback
+ * - 加载 schema.sql（缺失则抛错）
  * - 增量迁移（hasColumn / addColumnIfMissing）
  * - 一次性 sessions 回填
  *
@@ -43,32 +43,43 @@ export class SQLiteBase {
     this.db.pragma('mmap_size = 30000000000'); // 30GB memory-mapped I/O
     this.db.pragma('page_size = 4096'); // Optimal page size for most systems
 
+    // Order matters:
+    //   1) runColumnMigrations() ALTERs missing columns on PRE-EXISTING tables.
+    //      Must run BEFORE initSchema() because schema.sql contains indexes that
+    //      reference new columns (e.g. idx_skill_invocations_workflow). On a
+    //      legacy DB those CREATE INDEX statements would otherwise fail because
+    //      CREATE TABLE IF NOT EXISTS skips the old table and never adds the column.
+    //   2) initSchema() applies schema.sql (idempotent CREATE TABLE/INDEX).
+    //   3) runIndexMigrations() patches indexes that may still be missing on
+    //      legacy DBs (defensive; schema.sql already creates them on new DBs).
+    this.runColumnMigrations();
     this.initSchema();
-    this.runMigrations();
+    this.runIndexMigrations();
+    this.runPostMigrations();
   }
 
   private initSchema(): void {
     const thisDir = dirname(fileURLToPath(import.meta.url));
     const schemaPath = join(thisDir, 'schema.sql');
 
-    if (existsSync(schemaPath)) {
-      const schema = readFileSync(schemaPath, 'utf-8');
-      this.db.exec(schema);
-    } else {
-      // Inline fallback — events table only
-      this.db.exec(`
-        CREATE TABLE IF NOT EXISTS 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 INDEX IF NOT EXISTS idx_events_session ON events(session_id);
-        CREATE INDEX IF NOT EXISTS idx_events_project ON events(project_path);
-        CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp DESC);
-        CREATE INDEX IF NOT EXISTS idx_events_distilled ON events(distilled);
-      `);
+    if (!existsSync(schemaPath)) {
+      throw new Error(
+        `[SQLiteStorage] schema.sql not found at ${schemaPath}. ` +
+        `This indicates a broken build/install. Run \`npm run build\` or reinstall the package.`,
+      );
+    }
+    const schema = readFileSync(schemaPath, 'utf-8');
+    this.db.exec(schema);
+  }
+
+  protected hasTable(name: string): boolean {
+    try {
+      const row = this.db
+        .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name = ?`)
+        .get(name);
+      return !!row;
+    } catch {
+      return false;
     }
   }
 
@@ -82,6 +93,10 @@ export class SQLiteBase {
   }
 
   protected addColumnIfMissing(table: string, column: string, definition: string): void {
+    // Skip silently if the table doesn't exist yet — new DBs hit this path on
+    // first boot (initSchema runs after column migrations); the column will be
+    // created by schema.sql's CREATE TABLE.
+    if (!this.hasTable(table)) return;
     if (!this.hasColumn(table, column)) {
       try {
         this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
@@ -92,10 +107,38 @@ export class SQLiteBase {
     }
   }
 
+  protected hasIndex(name: string): boolean {
+    try {
+      const row = this.db
+        .prepare(`SELECT name FROM sqlite_master WHERE type='index' AND name = ?`)
+        .get(name);
+      return !!row;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Create an index only if it's missing. The CREATE INDEX IF NOT EXISTS already
+   * makes this safe; the hasIndex guard makes it explicit which indexes are still
+   * being patched by migrations (vs. provided by schema.sql).
+   */
+  private createIndexIfMissing(name: string, ddl: string): void {
+    if (this.hasIndex(name)) return;
+    try {
+      this.db.exec(ddl);
+      logger.debug(`[SQLiteStorage] migration created ${name}`);
+    } catch (err) {
+      logger.warn(`[SQLiteStorage] migration: create ${name} failed: ${err}`);
+    }
+  }
+
   /**
-   * Incremental schema migrations. Kept idempotent so daemon restarts are safe.
+   * Column migrations run BEFORE initSchema() so legacy tables get missing
+   * columns (e.g. skill_invocations.workflow) before schema.sql's CREATE INDEX
+   * statements try to reference them.
    */
-  private runMigrations(): void {
+  private runColumnMigrations(): void {
     this.addColumnIfMissing('sessions', 'first_prompt', 'TEXT');
 
     this.addColumnIfMissing('routing_events', 'skill_confidence', 'REAL');
@@ -105,45 +148,69 @@ export class SQLiteBase {
     this.addColumnIfMissing('skill_invocations', 'phase', 'TEXT');
     this.addColumnIfMissing('skill_invocations', 'feature_slug', 'TEXT');
     this.addColumnIfMissing('skill_invocations', 'artifact_path', 'TEXT');
+  }
 
-    try {
-      this.db.exec(
-        `CREATE INDEX IF NOT EXISTS idx_skill_invocations_workflow ON skill_invocations(workflow, phase);
-         CREATE INDEX IF NOT EXISTS idx_skill_invocations_feature ON skill_invocations(feature_slug);`,
-      );
-    } catch (err) {
-      logger.warn(`[SQLiteStorage] migration: create skill_invocations workflow indexes failed: ${err}`);
-    }
+  /**
+   * Index migrations run AFTER initSchema(). Each call is guarded by hasIndex
+   * so:
+   *   - new DBs: schema.sql already created the index → skipped
+   *   - legacy DBs: schema.sql skipped (existing index) for indexes it tries to
+   *     create or covered above; remaining migration-only / pre-H1 indexes are
+   *     patched here.
+   * CREATE INDEX IF NOT EXISTS is preserved as a second line of defense.
+   */
+  private runIndexMigrations(): void {
+    this.createIndexIfMissing(
+      'idx_skill_invocations_workflow',
+      `CREATE INDEX IF NOT EXISTS idx_skill_invocations_workflow ON skill_invocations(workflow, phase)`,
+    );
+    this.createIndexIfMissing(
+      'idx_skill_invocations_feature',
+      `CREATE INDEX IF NOT EXISTS idx_skill_invocations_feature ON skill_invocations(feature_slug)`,
+    );
 
-    try {
-      this.db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC)');
-    } catch (err) {
-      logger.warn(`[SQLiteStorage] migration: create idx_sessions_start_time failed: ${err}`);
-    }
+    this.createIndexIfMissing(
+      'idx_sessions_start_time',
+      `CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC)`,
+    );
 
-    // Composite indexes for high-frequency session-scoped queries (idempotent)
-    try {
-      this.db.exec(`
-        CREATE INDEX IF NOT EXISTS idx_events_session_ts ON events(session_id, timestamp DESC);
-        CREATE INDEX IF NOT EXISTS idx_routing_events_session_ts ON routing_events(session_id, ts DESC);
-        CREATE INDEX IF NOT EXISTS idx_skill_invocations_session_ts ON skill_invocations(session_id, timestamp DESC);
-      `);
-    } catch (err) {
-      logger.warn(`[SQLiteStorage] migration: create composite indexes failed: ${err}`);
-    }
+    // Composite indexes for high-frequency session-scoped queries
+    this.createIndexIfMissing(
+      'idx_events_session_ts',
+      `CREATE INDEX IF NOT EXISTS idx_events_session_ts ON events(session_id, timestamp DESC)`,
+    );
+    this.createIndexIfMissing(
+      'idx_routing_events_session_ts',
+      `CREATE INDEX IF NOT EXISTS idx_routing_events_session_ts ON routing_events(session_id, ts DESC)`,
+    );
+    this.createIndexIfMissing(
+      'idx_skill_invocations_session_ts',
+      `CREATE INDEX IF NOT EXISTS idx_skill_invocations_session_ts ON skill_invocations(session_id, timestamp DESC)`,
+    );
 
-    // Phase 1 Refactor: Additional performance indexes (idempotent)
-    try {
-      this.db.exec(`
-        CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts ON routing_events(obeyed, ts DESC);
-        CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook_type, timestamp DESC);
-        CREATE INDEX IF NOT EXISTS idx_injections_session_handler ON injections(session_id, source_handler);
-      `);
-      logger.info('[SQLiteStorage] Phase 1 performance indexes created');
-    } catch (err) {
-      logger.warn(`[SQLiteStorage] migration: create Phase 1 performance indexes failed: ${err}`);
-    }
+    // Phase 1 Refactor: Additional performance indexes
+    this.createIndexIfMissing(
+      'idx_routing_events_obeyed_ts',
+      `CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts ON routing_events(obeyed, ts DESC)`,
+    );
+    this.createIndexIfMissing(
+      'idx_events_session_hook',
+      `CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook_type, timestamp DESC)`,
+    );
+    this.createIndexIfMissing(
+      'idx_injections_session_handler',
+      `CREATE INDEX IF NOT EXISTS idx_injections_session_handler ON injections(session_id, source_handler)`,
+    );
+    this.createIndexIfMissing(
+      'idx_routing_events_type_ts',
+      `CREATE INDEX IF NOT EXISTS idx_routing_events_type_ts ON routing_events(routed_to_type, ts DESC)`,
+    );
+  }
 
+  /**
+   * One-shot data migrations + deprecated table cleanup.
+   */
+  private runPostMigrations(): void {
     this.backfillSessionsIfNeeded();
 
     const deprecatedTables = [
@@ -211,6 +278,15 @@ export class SQLiteBase {
     }
   }
 
+  /**
+   * @internal 仅供 *Operations 子类、migration、初始化使用。
+   *
+   * Routes / Handlers / Analytics 禁止直接调用。需要查询请走 SQLiteStorage facade
+   * 上的具名方法（query* / get* / list* / count* / aggregate*）；若 facade 缺方法，
+   * 应在对应 Operations 类下沉 SQL 并补 facade 转发，而不是 db.prepare() 直写。
+   *
+   * 历史：H2 (2026-05) 已收敛 27 处越权 SQL，新增越权请走同样的下沉模式。
+   */
   getDatabase(): Database.Database {
     return this.db;
   }