@winspan/claude-forge 8.53.2 → 8.54.3

package/src/cli/commands/skills.ts

@@ -1,328 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { homedir } from 'os';
-import { fileURLToPath } from 'url';
-import { promises as fsPromises } from 'node:fs';
-import type { Command } from 'commander';
-import { loadOfficialSkills } from '../../skills/official-skills.js';
-import { SkillRegistry } from '../../skills/registry.js';
-import { skillInvoke } from '../../skills/tools/skill-invoke.js';
-import { skillList } from '../../skills/tools/skill-list.js';
-import {
-  pullCandidates,
-  matchToOfficial,
-  evaluateWithAI,
-  generateReport,
-  applyDecisions,
-  DEFAULT_SOURCES,
-} from '../../skills/upgrade-engine.js';
-import type { ReportEntry } from '../../skills/upgrade-engine.js';
-import { ConfigManager } from '../../core/config.js';
-import { ClaudeProvider } from '../../core/ai/provider.js';
-import { FORGE_PATHS } from '../../core/constants.js';
-
-const SKILLS_DIR = path.join(homedir(), '.claude', 'skills');
-
-function resolveBuiltinDir(): string {
-  const thisFile = fileURLToPath(import.meta.url);
-  return path.join(path.dirname(thisFile), '../../skills/official');
-}
-
-interface ListOptions {
-  keywords?: string;
-  json?: boolean;
-}
-
-interface InvokeOptions {
-  reason?: string;
-  json?: boolean;
-}
-
-/**
- * List skills with optional keyword filter and JSON output.
- * Delegates to the shared skillList() tool so CLI and Agent share one code path.
- */
-async function listSkills(options: ListOptions): Promise<void> {
-  const registry = new SkillRegistry();
-  const keywords = options.keywords
-    ? options.keywords
-        .split(',')
-        .map(k => k.trim())
-        .filter(k => k.length > 0)
-    : undefined;
-
-  const result = await skillList({ keywords }, { skillRegistry: registry });
-
-  if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  if (result.total === 0) {
-    console.log('No skills found.');
-    return;
-  }
-
-  // Human-readable output. Include `isOfficial` hint via registry lookup.
-  console.log(`Available skills (${result.total}):\n`);
-  for (const s of result.skills) {
-    const full = registry.get(s.id);
-    const type = full?.isOfficial ? 'official' : 'user';
-    console.log(`- ${s.id} [${type}]`);
-    console.log(`  name: ${s.name}`);
-    if (s.description) {
-      console.log(`  description: ${s.description}`);
-    }
-    if (s.keywords.length > 0) {
-      console.log(`  keywords: ${s.keywords.join(', ')}`);
-    }
-    console.log();
-  }
-}
-
-/**
- * Invoke a skill by id, printing its full methodology content.
- * Exit code 1 on failure so Bash callers can detect errors.
- */
-async function invokeSkill(skillId: string, options: InvokeOptions): Promise<void> {
-  const registry = new SkillRegistry();
-
-  try {
-    const result = await skillInvoke(
-      { skill_id: skillId, reason: options.reason },
-      { skillRegistry: registry },
-    );
-
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    console.log(`# ${result.skill_name}`);
-    if (result.keywords.length > 0) {
-      console.log(`\n> keywords: ${result.keywords.join(', ')}`);
-    }
-    console.log();
-    console.log(result.content);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`Error: ${msg}`);
-    process.exit(1);
-  }
-}
-
-interface UpgradeOptions {
-  apply?: boolean;
-  rollback?: string;
-  report?: string;
-}
-
-/**
- * Coordinate the full skill upgrade pipeline.
- * Default: dry-run — generates a report without writing to src/.
- * --apply: read report and apply decisions.
- * --rollback <ts>: restore official skills from a backup timestamp.
- */
-async function upgradeSkills(options: UpgradeOptions): Promise<void> {
-  const reportPath = options.report ?? FORGE_PATHS.skillUpgradeReport();
-  const officialDir = resolveBuiltinDir();
-  const backupBaseDir = FORGE_PATHS.backups('skills');
-  const candidatesDir = FORGE_PATHS.skillCandidates();
-
-  // ── Rollback mode ────────────────────────────────────────────────────────
-  if (options.rollback) {
-    const backupPath = path.join(backupBaseDir, options.rollback);
-    try {
-      await fsPromises.access(backupPath);
-    } catch {
-      console.error(`Backup not found: ${backupPath}`);
-      process.exit(1);
-    }
-    const files = await fsPromises.readdir(backupPath);
-    for (const file of files) {
-      if (!file.endsWith('.md')) continue;
-      await fsPromises.copyFile(path.join(backupPath, file), path.join(officialDir, file));
-    }
-    console.log(`Rolled back ${files.filter(f => f.endsWith('.md')).length} files from ${backupPath}`);
-    console.log('Run `npm run build` to rebuild with restored skills.');
-    return;
-  }
-
-  // ── Apply mode ───────────────────────────────────────────────────────────
-  if (options.apply) {
-    try {
-      await fsPromises.access(reportPath);
-    } catch {
-      console.error(`Report not found: ${reportPath}`);
-      console.error('Run `cf skills upgrade` first to generate a report.');
-      process.exit(1);
-    }
-    console.log(`Applying decisions from ${reportPath}...`);
-    const result = await applyDecisions(reportPath, officialDir, backupBaseDir);
-    console.log(`\nApply complete:`);
-    console.log(`  Applied : ${result.applied}`);
-    console.log(`  Skipped : ${result.skipped}`);
-    console.log(`  Backup  : ${result.backupPath}`);
-    console.log('\nRun `npm run build` to rebuild with updated skills.');
-    return;
-  }
-
-  // ── Dry-run (report generation) mode ────────────────────────────────────
-  console.log('Fetching candidate skills...');
-  const candidates = await pullCandidates(DEFAULT_SOURCES, candidatesDir);
-  console.log(`  Found ${candidates.length} candidate skills`);
-
-  const officialSkills = loadOfficialSkills(officialDir);
-  console.log(`  Loaded ${officialSkills.length} official skills`);
-
-  // Set up AI provider
-  const config = new ConfigManager().get();
-  if (!config.ai.api_key) {
-    console.error('No AI API key configured. Run `cf menu` to set it up.');
-    process.exit(1);
-  }
-  const aiProvider = new ClaudeProvider(config.ai.api_key, config.ai.model, config.ai.base_url);
-
-  let matched = 0;
-  let unmatched = 0;
-  const entries: ReportEntry[] = [];
-
-  console.log('\nEvaluating candidates...');
-
-  for (const candidate of candidates) {
-    const matchResult = matchToOfficial(candidate, officialSkills);
-    if (!matchResult) {
-      unmatched++;
-      continue;
-    }
-
-    matched++;
-    const official = officialSkills.find((o) => o.name === matchResult.officialId);
-    if (!official) continue;
-
-    process.stdout.write(`  ${candidate.id} → ${official.name} (score ${matchResult.score})... `);
-
-    const decision = await evaluateWithAI(candidate, official, aiProvider);
-    const action = (decision as { needs_review?: boolean }).needs_review
-      ? 'needs_review'
-      : decision.action;
-
-    process.stdout.write(`${action}\n`);
-
-    entries.push({
-      officialId: official.name,
-      candidateId: candidate.id,
-      candidateSource: candidate.source,
-      action,
-      confidence: decision.confidence,
-      reasoning: decision.reasoning,
-      candidateFilePath: candidate.filePath,
-      merged_content: decision.merged_content,
-    });
-  }
-
-  const stats = { total: candidates.length, matched, unmatched };
-  await generateReport(entries, reportPath, stats);
-
-  console.log(`\nReport generated: ${reportPath}`);
-  console.log(`Summary: ${matched} matched, ${unmatched} unmatched (of ${candidates.length} total)`);
-  console.log('\nReview the report, then run:');
-  console.log('  cf skills upgrade --apply   (to apply decisions)');
-}
-
-
-function registerSkillSubcommands(skills: Command): void {
-  skills
-    .command('sync')
-    .description('Write official skills to ~/.claude/skills/')
-    .option('-f, --force', 'Overwrite existing files regardless of version')
-    .action((options: { force?: boolean }) => {
-      syncSkills(options);
-    });
-
-  skills
-    .command('list')
-    .description('List all skills (official + user) with optional keyword filter')
-    .option('--keywords <keywords>', 'Comma-separated keywords to filter by')
-    .option('--json', 'Output as JSON (machine-readable)')
-    .action(async (options: ListOptions) => {
-      await listSkills(options);
-    });
-
-  skills
-    .command('invoke <skill_id>')
-    .description('Invoke a skill and print its full methodology content')
-    .option('--reason <reason>', 'Reason for invoking (used for audit log)')
-    .option('--json', 'Output as JSON (machine-readable)')
-    .action(async (skillId: string, options: InvokeOptions) => {
-      await invokeSkill(skillId, options);
-    });
-
-  skills
-    .command('upgrade')
-    .description('AI-assisted upgrade of official skills (dry-run by default)')
-    .option('--apply', 'Apply decisions from the last report')
-    .option('--rollback <timestamp>', 'Rollback to a backup (e.g. 20260518-1930)')
-    .option('--report <path>', 'Custom report path')
-    .action(async (options: UpgradeOptions) => {
-      await upgradeSkills(options);
-    });
-}
-
-export function register(program: Command): void {
-  // Primary command: `cf skills ...`
-  const skills = program
-    .command('skills')
-    .description('Manage official and user skills (list | invoke | sync)');
-  registerSkillSubcommands(skills);
-
-  // Singular alias: `cf skill ...` — preferred for Agent Bash calls where
-  // `cf skill invoke <id>` reads more naturally than the plural form.
-  const skill = program
-    .command('skill')
-    .description('Alias of `skills` (list | invoke | sync)');
-  registerSkillSubcommands(skill);
-}
-function syncSkills(options: { force?: boolean }): void {
-  if (!fs.existsSync(SKILLS_DIR)) {
-    fs.mkdirSync(SKILLS_DIR, { recursive: true });
-  }
-
-  let added = 0;
-  let skipped = 0;
-  let updated = 0;
-
-  const officialSkills = loadOfficialSkills(resolveBuiltinDir());
-
-  for (const skill of officialSkills) {
-    const filePath = path.join(SKILLS_DIR, `${skill.name}.md`);
-    const exists = fs.existsSync(filePath);
-
-    if (exists && !options.force) {
-      // Check version to decide if update is needed
-      const existing = fs.readFileSync(filePath, 'utf-8');
-      const versionMatch = existing.match(/^version:\s*(.+)$/m);
-      const existingVersion = versionMatch ? versionMatch[1].trim() : '0.0.0';
-
-      if (existingVersion === skill.version) {
-        skipped++;
-        continue;
-      }
-
-      // Version mismatch - update
-      fs.writeFileSync(filePath, skill.content, 'utf-8');
-      updated++;
-      console.log(`  updated: ${skill.name} (${existingVersion} -> ${skill.version})`);
-    } else if (exists && options.force) {
-      fs.writeFileSync(filePath, skill.content, 'utf-8');
-      updated++;
-      console.log(`  updated: ${skill.name} (forced)`);
-    } else {
-      fs.writeFileSync(filePath, skill.content, 'utf-8');
-      added++;
-      console.log(`  added: ${skill.name}`);
-    }
-  }
-
-  console.log(`\nSync complete: ${added} added, ${updated} updated, ${skipped} skipped`);
-}

package/src/cli/commands/stats.ts

@@ -1,73 +0,0 @@
-/**
- * CLI Command: cf stats
- *
- * 查询统计信息
- */
-
-import { Command } from 'commander';
-import { SQLiteStorage } from '../../core/storage/sqlite.js';
-import chalk from 'chalk';
-import { FORGE_PATHS } from '../../core/constants.js';
-
-export function createStatsCommand(): Command {
-  const cmd = new Command('stats');
-  cmd.description('查询统计信息');
-
-  cmd
-    .option('-d, --days <days>', '统计天数', '7')
-    .option('-p, --project <path>', '项目路径')
-    .action((options: { days: string; project?: string }) => {
-      const dbPath = FORGE_PATHS.database();
-      const storage = new SQLiteStorage(dbPath);
-
-      const days = parseInt(options.days);
-      const now = Date.now();
-      const startTime = now - days * 24 * 60 * 60 * 1000;
-
-      // 查询统计数据
-      const sessions = storage.querySessions({ limit: 1000 });
-      const events = storage.queryEvents({ limit: 10000 });
-
-      // 过滤时间范围
-      const recentSessions = sessions.filter(s => {
-        const time = new Date(s.start_time).getTime();
-        return time >= startTime;
-      });
-
-      const recentEvents = events.filter(e => {
-        const time = new Date(e.timestamp).getTime();
-        return time >= startTime;
-      });
-
-      // 工具使用统计
-      const toolUsage: Record<string, number> = {};
-      recentEvents.forEach(e => {
-        if (e.tool_name) {
-          toolUsage[e.tool_name] = (toolUsage[e.tool_name] || 0) + 1;
-        }
-      });
-
-      // 输出统计信息
-      console.log(chalk.bold(`\n📊 Statistics (Last ${days} days)\n`));
-
-      console.log(chalk.cyan('Sessions:'));
-      console.log(`  Total: ${recentSessions.length}`);
-      console.log(`  Avg events per session: ${Math.round(recentEvents.length / recentSessions.length || 0)}`);
-      console.log();
-
-      console.log(chalk.cyan('Events:'));
-      console.log(`  Total: ${recentEvents.length}`);
-      console.log();
-
-      console.log(chalk.cyan('Tool Usage:'));
-      Object.entries(toolUsage)
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 10)
-        .forEach(([tool, count]) => {
-          console.log(`  ${tool}: ${count}`);
-        });
-      console.log();
-    });
-
-  return cmd;
-}

package/src/cli/commands/status.ts

@@ -1,69 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { homedir } from 'os';
-import type { Command } from 'commander';
-import { FORGE_PATHS } from '../../core/constants.js';
-import { ConfigManager } from '../../core/config.js';
-
-const PID_FILE = FORGE_PATHS.daemonPid();
-
-function readPid(): number | null {
-  if (!fs.existsSync(PID_FILE)) return null;
-  const content = fs.readFileSync(PID_FILE, 'utf-8').trim();
-  const pid = parseInt(content, 10);
-  return isNaN(pid) ? null : pid;
-}
-
-function isRunning(): boolean {
-  const pid = readPid();
-  if (!pid) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function resolveDbPath(): string {
-  try {
-    const cfg = new ConfigManager().get();
-    const raw = cfg.storage?.path ?? FORGE_PATHS.database();
-    return raw.startsWith('~') ? path.join(homedir(), raw.slice(1)) : raw;
-  } catch {
-    return FORGE_PATHS.database();
-  }
-}
-
-export function register(program: Command): void {
-  program
-    .command('status')
-    .description('Show Forge daemon status')
-    .action(async () => {
-      // Daemon status
-      const pid = readPid();
-      if (pid && isRunning()) {
-        console.log(`Daemon: running (PID: ${pid})`);
-      } else {
-        console.log('Daemon: stopped');
-        if (pid) {
-          console.log('  Stale PID file found, daemon may have crashed');
-        }
-        console.log('  Run: cf daemon start');
-      }
-
-      // Config status
-      const configPath = FORGE_PATHS.config();
-      console.log(`Config: ${fs.existsSync(configPath) ? configPath : 'not initialized'}`);
-
-      // Database status
-      const dbPath = resolveDbPath();
-      if (fs.existsSync(dbPath)) {
-        const stats = fs.statSync(dbPath);
-        const sizeMB = (stats.size / 1024 / 1024).toFixed(1);
-        console.log(`Database: ${dbPath} (${sizeMB} MB)`);
-      } else {
-        console.log(`Database: not initialized (expected at ${dbPath})`);
-      }
-    });
-}

package/src/cli/commands/template.ts

@@ -1,77 +0,0 @@
-/**
- * CLI Command: cf template
- *
- * 管理项目模板
- */
-
-import { Command } from 'commander';
-import { TemplateManager } from '../../templates/template-manager.js';
-import chalk from 'chalk';
-
-export function createTemplateCommand(): Command {
-  const cmd = new Command('template');
-  cmd.description('管理项目模板');
-
-  // cf template list
-  cmd
-    .command('list')
-    .description('列出所有可用的模板')
-    .action(() => {
-      const manager = new TemplateManager();
-      manager.loadAll();
-
-      const templates = manager.listTemplates();
-
-      if (templates.length === 0) {
-        console.log(chalk.yellow('No templates found'));
-        return;
-      }
-
-      console.log(chalk.bold('\n📦 Available Templates:\n'));
-
-      templates.forEach(({ id, template }) => {
-        console.log(chalk.cyan(`  ${id}`));
-        console.log(`    ${template.description}`);
-        console.log(chalk.dim(`    Conventions: ${template.conventions.join(', ')}`));
-        console.log();
-      });
-    });
-
-  // cf template init <template-id>
-  cmd
-    .command('init <template-id>')
-    .description('使用模板初始化当前项目')
-    .option('-p, --path <path>', '项目路径', process.cwd())
-    .action((templateId: string, options: { path: string }) => {
-      const manager = new TemplateManager();
-      manager.loadAll();
-
-      try {
-        manager.initProject(templateId, options.path);
-        console.log(chalk.green('\n✓ Template initialized successfully!'));
-        console.log(chalk.dim(`\nRun ${chalk.cyan('cf template show ' + templateId)} to see recommendations`));
-      } catch (err) {
-        console.error(chalk.red(`\n✗ Error: ${(err as Error).message}`));
-        process.exit(1);
-      }
-    });
-
-  // cf template show <template-id>
-  cmd
-    .command('show <template-id>')
-    .description('显示模板的推荐配置')
-    .action((templateId: string) => {
-      const manager = new TemplateManager();
-      manager.loadAll();
-
-      try {
-        const recommendations = manager.generateRecommendations(templateId);
-        console.log(recommendations);
-      } catch (err) {
-        console.error(chalk.red(`\n✗ Error: ${(err as Error).message}`));
-        process.exit(1);
-      }
-    });
-
-  return cmd;
-}

package/src/cli/commands/trace.ts

@@ -1,148 +0,0 @@
-/**
- * CLI Command: cf trace <commit>
- *
- * Trace a git commit back to its associated forge session(s).
- * Reads git notes to find session_id, then queries storage for details.
- */
-
-import { Command } from 'commander';
-import { execFileSync } from 'node:child_process';
-import path from 'node:path';
-import { homedir } from 'node:os';
-import chalk from 'chalk';
-import { SQLiteStorage } from '../../core/storage/sqlite.js';
-import { FORGE_PATHS, DEFAULTS } from '../../core/constants.js';
-import { ConfigManager } from '../../core/config.js';
-
-function resolveDbPath(): string {
-  try {
-    const cfg = new ConfigManager().get();
-    const raw = cfg.storage?.path ?? FORGE_PATHS.database();
-    return raw.startsWith('~') ? path.join(homedir(), raw.slice(1)) : raw;
-  } catch {
-    return FORGE_PATHS.database();
-  }
-}
-
-export function register(program: Command): void {
-  program
-    .command('trace [commit]')
-    .description('Trace a git commit to its forge session')
-    .option('-p, --project <path>', 'Project path (defaults to cwd)')
-    .action((commit: string | undefined, options: { project?: string }) => {
-      const projectPath = options.project || process.cwd();
-      const commitRef = commit || 'HEAD';
-
-      // 1. Resolve commit hash
-      let commitHash: string;
-      let commitMessage: string;
-      try {
-        commitHash = execFileSync('git', ['rev-parse', commitRef], {
-          cwd: projectPath, stdio: 'pipe', timeout: 5000,
-        }).toString().trim();
-      } catch {
-        console.error(chalk.red(`Error: Cannot resolve commit "${commitRef}". Not a git repository or invalid ref.`));
-        process.exit(1);
-      }
-
-      try {
-        commitMessage = execFileSync('git', ['log', '-1', '--format=%s', commitHash], {
-          cwd: projectPath, stdio: 'pipe', timeout: 5000,
-        }).toString().trim();
-      } catch {
-        commitMessage = '(unknown)';
-      }
-
-      // 2. Read git notes for this commit
-      let noteContent: string;
-      try {
-        noteContent = execFileSync('git', ['notes', 'show', commitHash], {
-          cwd: projectPath, stdio: 'pipe', timeout: 5000,
-        }).toString().trim();
-      } catch {
-        console.log(chalk.yellow(`No forge session associated with commit ${commitHash.slice(0, 7)}`));
-        console.log(chalk.dim('This commit was not made during a forge-tracked session.'));
-        process.exit(0);
-      }
-
-      // 3. Parse session IDs from notes
-      const sessionIds = noteContent
-        .split('\n')
-        .filter(line => line.startsWith('forge-session:'))
-        .map(line => line.replace('forge-session:', '').trim());
-
-      if (sessionIds.length === 0) {
-        console.log(chalk.yellow(`No forge session found in git notes for ${commitHash.slice(0, 7)}`));
-        process.exit(0);
-      }
-
-      // 4. Query storage for session details
-      const dbPath = resolveDbPath();
-      const storage = new SQLiteStorage(dbPath);
-
-      console.log(chalk.bold(`\nCommit: ${commitHash.slice(0, 7)} (${commitMessage})\n`));
-
-      for (const sessionId of sessionIds) {
-        printSessionTrace(storage, sessionId);
-      }
-    });
-}
-
-function printSessionTrace(
-  storage: SQLiteStorage,
-  sessionId: string,
-): void {
-  // Find session
-  const sessions = storage.querySessions({ limit: 5000 });
-  const session = sessions.find(s => s.session_id === sessionId || s.session_id.startsWith(sessionId));
-
-  if (!session) {
-    console.log(chalk.dim(`  Session: ${sessionId} (not found in database)`));
-    return;
-  }
-
-  const fullId = session.session_id;
-
-  // Time calculation
-  const start = new Date(session.start_time);
-  const end = new Date(session.end_time);
-  const durationMin = Math.round((end.getTime() - start.getTime()) / 60000);
-  const timeStr = `${formatTime(start)} - ${formatTime(end)} (${durationMin} min)`;
-
-  // 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 = 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 skillNames = storage.queryDistinctSkillIdsBySession(fullId);
-
-  // Output
-  console.log(chalk.cyan(`  Session: ${fullId}`));
-  console.log(`  Time: ${timeStr}`);
-  console.log(`  Events: ${totalEvents} (${breakdownStr})`);
-
-  if (totalAgents > 0) {
-    console.log(`  Agent calls: ${totalAgents} (${agentNames.join(', ')})`);
-  }
-
-  if (skillNames.length > 0) {
-    console.log(`  Skills: ${skillNames.join(', ')}`);
-  }
-
-  console.log(chalk.dim(`  Dashboard: http://localhost:${DEFAULTS.WEB_PORT}/sessions/${fullId}`));
-  console.log();
-}
-
-function formatTime(d: Date): string {
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
-}
-
-function pad(n: number): string {
-  return n < 10 ? `0${n}` : `${n}`;
-}