@winspan/claude-forge 8.41.0 → 8.51.0

package/src/cli/commands/skills.ts

@@ -0,0 +1,185 @@
+import fs from 'fs';
+import path from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+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';
+
+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);
+  }
+}
+
+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);
+    });
+}
+
+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

@@ -0,0 +1,73 @@
+/**
+ * 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

@@ -0,0 +1,69 @@
+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

@@ -0,0 +1,77 @@
+/**
+ * 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

@@ -0,0 +1,148 @@
+/**
+ * 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}`;
+}

package/src/cli/index.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { register as registerInit } from './commands/init.js';
+import { register as registerDaemon } from './commands/daemon.js';
+import { register as registerStatus } from './commands/status.js';
+import { register as registerConfig } from './commands/config.js';
+import { register as registerClaudeMd } from './commands/claudemd.js';
+import { register as registerSkills } from './commands/skills.js';
+import { register as registerLogs } from './commands/logs.js';
+import { register as registerMcp } from './commands/mcp.js';
+import { registerMenuCommand } from './commands/menu.js';
+import { createTemplateCommand } from './commands/template.js';
+import { createStatsCommand } from './commands/stats.js';
+import { registerExecutionsCommand } from './commands/executions.js';
+import { register as registerTrace } from './commands/trace.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json') as { version: string };
+
+const program = new Command();
+program
+  .name('claude-forge')
+  .alias('cf')
+  .description('Claude Code governance engine')
+  .version(version);
+
+registerInit(program);
+registerDaemon(program);
+registerStatus(program);
+registerConfig(program);
+registerClaudeMd(program);
+registerSkills(program);
+registerLogs(program);
+registerMcp(program);
+registerMenuCommand(program);
+program.addCommand(createTemplateCommand());
+program.addCommand(createStatsCommand());
+registerExecutionsCommand(program);
+registerTrace(program);
+
+program.parseAsync();