@winspan/claude-forge 8.41.0 → 8.50.6

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,164 @@
+/**
+ * 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 } 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);
+      const db = storage.getDatabase();
+
+      console.log(chalk.bold(`\nCommit: ${commitHash.slice(0, 7)} (${commitMessage})\n`));
+
+      for (const sessionId of sessionIds) {
+        printSessionTrace(storage, db, sessionId);
+      }
+    });
+}
+
+function printSessionTrace(
+  storage: SQLiteStorage,
+  db: ReturnType<SQLiteStorage['getDatabase']>,
+  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)`;
+
+  // 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(', ');
+
+  // 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 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);
+
+  // 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:3721/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();

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

@@ -0,0 +1,132 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { FORGE_HOME } 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 HOOK_SCRIPT_NAMES = [
+  'pre-tool-use.sh',
+  'post-tool-use.sh',
+  'user-prompt-submit.sh',
+  'notification.sh',
+  'stop.sh',
+] as const;
+
+interface HookCommand {
+  type: string;
+  command: string;
+}
+
+interface HookMatcherBlock {
+  matcher: string;
+  hooks: HookCommand[];
+}
+
+interface ClaudeSettings {
+  hooks?: Record<string, HookMatcherBlock[]>;
+  [key: string]: unknown;
+}
+
+function isForgeCommand(cmd: string): boolean {
+  return cmd.includes('claude-forge') || cmd.includes('.claude-forge');
+}
+
+function entryRefersToForge(entry: HookMatcherBlock): boolean {
+  return entry.hooks.some((h) => isForgeCommand(h.command));
+}
+
+function getForgeHookEntries(): Record<string, HookMatcherBlock> {
+  return {
+    PreToolUse: {
+      matcher: '',
+      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'pre-tool-use.sh')}` }],
+    },
+    PostToolUse: {
+      matcher: '',
+      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'post-tool-use.sh')}` }],
+    },
+    UserPromptSubmit: {
+      matcher: '',
+      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'user-prompt-submit.sh')}` }],
+    },
+    Notification: {
+      matcher: '',
+      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'notification.sh')}` }],
+    },
+    Stop: {
+      matcher: '',
+      hooks: [{ type: 'command', command: `bash ${path.join(HOOKS_DIR, 'stop.sh')}` }],
+    },
+  };
+}
+
+/**
+ * Copy hook shell scripts from the package to ~/.claude-forge/hooks/
+ */
+export function copyHookScripts(): void {
+  if (!fs.existsSync(HOOKS_DIR)) {
+    fs.mkdirSync(HOOKS_DIR, { recursive: true });
+  }
+
+  const srcHooksDir = path.resolve(
+    path.dirname(new URL(import.meta.url).pathname),
+    '../../hooks',
+  );
+
+  for (const file of HOOK_SCRIPT_NAMES) {
+    const src = path.join(srcHooksDir, file);
+    const dest = path.join(HOOKS_DIR, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+      fs.chmodSync(dest, 0o755);
+    }
+  }
+}
+
+/**
+ * Backup Claude Code settings.json before modifying it.
+ * Returns the backup path, or null if no settings file exists.
+ */
+export function backupSettings(): string | null {
+  if (!fs.existsSync(SETTINGS_PATH)) return null;
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${SETTINGS_PATH}.backup-${timestamp}`;
+  fs.copyFileSync(SETTINGS_PATH, backupPath);
+  return backupPath;
+}
+
+/**
+ * Inject Forge hook entries into Claude Code settings.json.
+ * Idempotent: skips hooks that are already present.
+ */
+export function injectHooks(): void {
+  let settings: ClaudeSettings = {};
+
+  if (fs.existsSync(SETTINGS_PATH)) {
+    settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf-8')) as ClaudeSettings;
+  }
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  const forgeHooks = getForgeHookEntries();
+
+  for (const [hookType, block] of Object.entries(forgeHooks)) {
+    const existing = (settings.hooks[hookType] ?? []) as HookMatcherBlock[];
+    const alreadyInjected = existing.some((item) => entryRefersToForge(item));
+
+    if (!alreadyInjected) {
+      settings.hooks[hookType] = [...existing, block];
+    }
+  }
+
+  if (!fs.existsSync(CLAUDE_HOME)) {
+    fs.mkdirSync(CLAUDE_HOME, { recursive: true });
+  }
+
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf-8');
+}