@winspan/claude-forge 8.39.0 → 8.50.6

package/src/cli/commands/claudemd.ts

@@ -0,0 +1,84 @@
+import fs from 'fs';
+import path from 'path';
+import type { Command } from 'commander';
+import { ClaudeMdManager } from '../../claudemd/index.js';
+import { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { ClaudeProvider } from '../../core/ai/provider.js';
+import { ConfigManager } from '../../core/config.js';
+import { expandPath } from '../../core/utils/path.js';
+
+export function register(program: Command): void {
+  const cmd = program.command('claudemd').description('Manage CLAUDE.md files');
+
+  cmd
+    .command('init')
+    .description('Generate CLAUDE.md for current project')
+    .option('--force', 'Overwrite existing CLAUDE.md')
+    .action(async (opts) => {
+      const projectPath = process.cwd();
+      const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+
+      // Check if CLAUDE.md already exists
+      if (fs.existsSync(claudeMdPath) && !opts.force) {
+        console.error('CLAUDE.md already exists. Use --force to overwrite.');
+        process.exit(1);
+      }
+
+      // Load config and AI provider
+      const config = new ConfigManager().get();
+      const apiKey = config.ai.api_key || process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        console.error('Error: No API key configured.');
+        console.error('Set ANTHROPIC_API_KEY environment variable or run: cf config edit');
+        process.exit(1);
+      }
+
+      const storage = new SQLiteStorage(expandPath(config.storage.path));
+      const ai = new ClaudeProvider(apiKey, config.ai.model, config.ai.base_url);
+      const manager = new ClaudeMdManager(storage, ai);
+
+      console.log('Detecting tech stack...');
+      const stack = manager.generator.detector.detect(projectPath);
+      console.log(`Found: ${stack.language.join(', ')} | ${stack.framework.join(', ')}`);
+
+      console.log('Generating CLAUDE.md...');
+      const content = await manager.generator.generate(projectPath);
+
+      fs.writeFileSync(claudeMdPath, content, 'utf-8');
+      console.log(`✓ CLAUDE.md created at ${claudeMdPath}`);
+
+      storage.close();
+    });
+
+  cmd
+    .command('show')
+    .description('Show current CLAUDE.md content')
+    .action(() => {
+      const projectPath = process.cwd();
+      const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+
+      if (!fs.existsSync(claudeMdPath)) {
+        console.error('CLAUDE.md not found. Run: cf claudemd init');
+        process.exit(1);
+      }
+
+      const content = fs.readFileSync(claudeMdPath, 'utf-8');
+      console.log(content);
+    });
+
+  cmd
+    .command('persona')
+    .description('Show detected persona for current project')
+    .action(() => {
+      const projectPath = process.cwd();
+      const config = new ConfigManager().get();
+      const storage = new SQLiteStorage(expandPath(config.storage.path));
+      const ai = new ClaudeProvider('dummy', 'dummy'); // Not used for persona detection
+      const manager = new ClaudeMdManager(storage, ai);
+
+      const persona = manager.persona.load(projectPath);
+      console.log(persona);
+
+      storage.close();
+    });
+}

package/src/cli/commands/config.ts

@@ -0,0 +1,46 @@
+import fs from 'fs';
+import type { Command } from 'commander';
+import { FORGE_PATHS } from '../../core/constants.js';
+
+export function register(program: Command): void {
+  const config = program.command('config').description('Manage configuration');
+
+  config
+    .command('show')
+    .description('Print current configuration')
+    .action(() => {
+      const configPath = FORGE_PATHS.config();
+      if (!fs.existsSync(configPath)) {
+        console.log('No config file found. Run: cf init');
+        return;
+      }
+      const content = fs.readFileSync(configPath, 'utf-8');
+      console.log(content);
+    });
+
+  config
+    .command('path')
+    .description('Print config file path')
+    .action(() => {
+      console.log(FORGE_PATHS.config());
+    });
+
+  config
+    .command('edit')
+    .description('Open config in default editor')
+    .action(async () => {
+      const configPath = FORGE_PATHS.config();
+      if (!fs.existsSync(configPath)) {
+        console.log('No config file found. Run: cf init');
+        return;
+      }
+      const editor = process.env.EDITOR || process.env.VISUAL || 'vi';
+      const { spawn } = await import('child_process');
+      const child = spawn(editor, [configPath], { stdio: 'inherit' });
+      child.on('exit', (code) => {
+        if (code !== 0) {
+          console.error(`Editor exited with code ${code}`);
+        }
+      });
+    });
+}

package/src/cli/commands/daemon.ts

@@ -0,0 +1,310 @@
+/**
+ * Forge daemon management CLI.
+ *
+ * Three ways to run the daemon:
+ *   1. Manual one-shot:    `cf daemon start` / `cf daemon stop`
+ *      Spawns a detached child process; no auto-restart on crash.
+ *
+ *   2. Local development:  `./scripts/dev-daemon.sh start`
+ *      Always uses the repo's `dist/daemon/index.js` build.
+ *
+ *   3. System service:     `cf daemon install`
+ *      Installs a macOS LaunchAgent at
+ *      `~/Library/LaunchAgents/com.claude-forge.daemon.plist`. With
+ *      `KeepAlive = { Crashed: true }` the daemon auto-restarts on crash
+ *      (OOM-kill, signal kill, uncaught exception). Normal exits via
+ *      `cf daemon stop` do NOT trigger a restart (`SuccessfulExit: false`).
+ *      `ThrottleInterval=10s` rate-limits restart loops.
+ *
+ * LaunchAgent logs:
+ *   ~/.claude-forge/daemon-stdout.log
+ *   ~/.claude-forge/daemon-stderr.log
+ *
+ * Uninstall:
+ *   cf daemon uninstall   # bootouts the service and removes the plist
+ *
+ * Platform: install/uninstall/launchd-status are macOS-only. On other platforms
+ * the commands print a clear "not supported" error.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { spawn, execSync } from 'child_process';
+import type { Command } from 'commander';
+import { FORGE_HOME } from '../../core/constants.js';
+import { fileURLToPath } from 'url';
+import {
+  install as installLaunchAgent,
+  uninstall as uninstallLaunchAgent,
+  status as launchdStatus,
+  PLIST_PATH,
+  LAUNCHD_LABEL,
+} from '../../daemon/launchd-installer.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PID_FILE = path.join(FORGE_HOME, 'daemon.pid');
+const DEFAULT_PORT = 3721;
+const STDOUT_LOG = path.join(FORGE_HOME, 'daemon-stdout.log');
+const STDERR_LOG = path.join(FORGE_HOME, 'daemon-stderr.log');
+
+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 findPidByPort(port: number): number | null {
+  try {
+    const out = execSync(`lsof -iTCP:${port} -sTCP:LISTEN -t 2>/dev/null`, { encoding: 'utf-8' });
+    const pid = parseInt(out.trim().split('\n')[0], 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveRunningPid(): number | null {
+  const pid = readPid();
+  if (pid && isAlive(pid)) return pid;
+  return findPidByPort(DEFAULT_PORT);
+}
+
+function tailFile(filePath: string, lines: number): string {
+  if (!fs.existsSync(filePath)) return '';
+  try {
+    return execSync(`tail -n ${lines} ${JSON.stringify(filePath)}`, { encoding: 'utf-8' });
+  } catch {
+    return '';
+  }
+}
+
+export function register(program: Command): void {
+  const daemon = program.command('daemon').description('Manage the Forge daemon');
+
+  daemon
+    .command('start')
+    .description('Start the daemon')
+    .option('-f, --foreground', 'Run in foreground')
+    .option('--no-web', 'Start daemon without the web server')
+    .action(async (opts) => {
+      const existingPid = resolveRunningPid();
+      if (existingPid) {
+        console.log(`Daemon already running (PID: ${existingPid})`);
+        return;
+      }
+
+      if (opts.foreground) {
+        console.log('Starting daemon in foreground...');
+        const { startDaemon } = await import('../../daemon/index.js');
+        await startDaemon(true, { web: opts.web });
+        return;
+      }
+
+      // Background mode: spawn detached child process
+      const daemonScript = path.resolve(__dirname, '../../daemon/index.js');
+      const logFile = path.join(FORGE_HOME, 'daemon.log');
+      const out = fs.openSync(logFile, 'a');
+
+      const env: Record<string, string> = {
+        ...process.env as Record<string, string>,
+        FORGE_DAEMON_FOREGROUND: '1',
+      };
+      if (!opts.web) {
+        env.FORGE_DAEMON_NO_WEB = '1';
+      }
+
+      const child = spawn(process.execPath, [daemonScript], {
+        detached: true,
+        stdio: ['ignore', out, out],
+        env,
+      });
+
+      child.unref();
+      console.log(`Daemon started (PID: ${child.pid})`);
+      console.log(`Log: ${logFile}`);
+    });
+
+  daemon
+    .command('stop')
+    .description('Stop the daemon')
+    .action(async () => {
+      const pid = resolveRunningPid();
+      if (!pid) {
+        console.log('Daemon not running');
+        return;
+      }
+
+      try {
+        process.kill(pid, 'SIGTERM');
+        if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE);
+        console.log(`Daemon stopped (PID: ${pid})`);
+      } catch (err) {
+        console.error('Failed to stop daemon:', err);
+      }
+    });
+
+  daemon
+    .command('install')
+    .description('Install the daemon as a macOS LaunchAgent (auto-restart on crash)')
+    .option('--dev', 'Use the local dist build instead of the global install')
+    .option('--node <path>', 'Override the node binary path')
+    .option('--daemon-path <path>', 'Override the daemon entry path')
+    .action(async (opts) => {
+      try {
+        const result = installLaunchAgent({
+          dev: Boolean(opts.dev),
+          nodePath: opts.node,
+          daemonPath: opts.daemonPath,
+        });
+        console.log('LaunchAgent installed.');
+        console.log(`  plist:  ${result.plistPath}`);
+        console.log(`  node:   ${result.nodePath}`);
+        console.log(`  daemon: ${result.daemonPath}`);
+        if (result.reloaded) {
+          console.log('  (reloaded existing LaunchAgent)');
+        }
+        console.log('');
+        console.log(`Logs: ${STDOUT_LOG}`);
+        console.log(`      ${STDERR_LOG}`);
+        console.log(`Run 'cf daemon status' to verify.`);
+      } catch (err) {
+        console.error(
+          `Install failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('uninstall')
+    .description('Uninstall the daemon LaunchAgent')
+    .action(async () => {
+      try {
+        const result = uninstallLaunchAgent();
+        if (!result.bootedOut && !result.removedPlist) {
+          console.log('LaunchAgent not installed (nothing to do).');
+          return;
+        }
+        console.log('LaunchAgent uninstalled.');
+        if (result.bootedOut) console.log('  bootout: ok');
+        if (result.removedPlist) console.log(`  removed: ${PLIST_PATH}`);
+      } catch (err) {
+        console.error(
+          `Uninstall failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('status')
+    .description('Show daemon status (process + LaunchAgent on macOS)')
+    .action(async () => {
+      const pid = resolveRunningPid();
+      if (pid) {
+        console.log(`Daemon process: running (PID: ${pid})`);
+      } else {
+        console.log('Daemon process: not running');
+      }
+
+      if (process.platform !== 'darwin') {
+        return;
+      }
+
+      try {
+        const s = launchdStatus();
+        console.log('');
+        console.log(`LaunchAgent (${LAUNCHD_LABEL}):`);
+        console.log(`  installed: ${s.installed ? 'yes' : 'no'}`);
+        console.log(`  loaded:    ${s.loaded ? 'yes' : 'no'}`);
+        if (s.loaded) {
+          console.log(`  pid:       ${s.pid ?? '(not running)'}`);
+          if (s.state) console.log(`  state:     ${s.state}`);
+          if (s.lastExitCode !== null) {
+            console.log(`  last exit: ${s.lastExitCode}`);
+          }
+        } else if (s.installed) {
+          console.log(`  note:      plist exists but not loaded — try 'cf daemon install'`);
+        } else if (s.raw) {
+          // Hide the noisy "Could not find" error when not installed.
+          if (!/Could not find specified service/i.test(s.raw)) {
+            console.log(`  detail:    ${s.raw.split('\n')[0]}`);
+          }
+        }
+      } catch (err) {
+        console.error(
+          `LaunchAgent status unavailable: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    });
+
+  daemon
+    .command('logs')
+    .description('Show recent daemon logs (LaunchAgent stdout/stderr)')
+    .option('-n, --lines <count>', 'Number of lines to show', '40')
+    .option('-f, --follow', 'Follow stderr log (Ctrl+C to exit)')
+    .action(async (opts) => {
+      const lines = parseInt(opts.lines, 10) || 40;
+
+      if (opts.follow) {
+        if (!fs.existsSync(STDERR_LOG)) {
+          console.error(`Log file not found: ${STDERR_LOG}`);
+          process.exitCode = 1;
+          return;
+        }
+        const child = spawn('tail', ['-f', '-n', String(lines), STDERR_LOG], {
+          stdio: 'inherit',
+        });
+        child.on('exit', (code) => {
+          process.exitCode = code ?? 0;
+        });
+        return;
+      }
+
+      const stdout = tailFile(STDOUT_LOG, lines);
+      const stderr = tailFile(STDERR_LOG, lines);
+
+      if (!stdout && !stderr) {
+        console.log('No LaunchAgent logs yet.');
+        console.log(`  expected: ${STDOUT_LOG}`);
+        console.log(`            ${STDERR_LOG}`);
+        return;
+      }
+
+      if (stdout) {
+        console.log(`=== ${STDOUT_LOG} (last ${lines} lines) ===`);
+        console.log(stdout.trimEnd());
+      }
+      if (stderr) {
+        if (stdout) console.log('');
+        console.log(`=== ${STDERR_LOG} (last ${lines} lines) ===`);
+        console.log(stderr.trimEnd());
+      }
+
+      // Show launchctl restart counter on darwin.
+      if (process.platform === 'darwin') {
+        try {
+          const s = launchdStatus();
+          if (s.loaded && s.raw) {
+            const exitsMatch = s.raw.match(/^\s*last exit code\s*=\s*(-?\d+)/mi);
+            if (exitsMatch) {
+              console.log('');
+              console.log(`launchd last exit code: ${exitsMatch[1]}`);
+            }
+          }
+        } catch {
+          // ignore
+        }
+      }
+    });
+}

package/src/cli/commands/executions.ts

@@ -0,0 +1,114 @@
+import type { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+export function registerExecutionsCommand(program: Command): void {
+  const cmd = program.command('executions').description('管理 Agent/Skill 执行文档');
+
+  // cf executions list — 列出所有执行文档
+  cmd
+    .command('list')
+    .description('列出所有执行文档')
+    .option('--limit <n>', '限制数量', '20')
+    .option('--date <date>', '按日期筛选（YYYY-MM-DD）')
+    .action(async (opts) => {
+      const baseDir = path.join(process.cwd(), '.claude-forge', 'executions', 'by-route');
+      if (!fs.existsSync(baseDir)) {
+        console.log('暂无执行文档。请先触发 Agent/Skill 执行。');
+        return;
+      }
+      const limit = parseInt(opts.limit) || 20;
+
+      // 列出 route 目录，按 mtime 倒序
+      const routes = fs.readdirSync(baseDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => ({
+          name: d.name,
+          mtime: fs.statSync(path.join(baseDir, d.name)).mtime,
+        }))
+        .sort((a, b) => b.mtime.getTime() - a.mtime.getTime())
+        .slice(0, limit);
+
+      console.log(`找到 ${routes.length} 个执行记录：\n`);
+      for (const r of routes) {
+        const overviewPath = path.join(baseDir, r.name, 'overview.md');
+        let summary = '(无 overview)';
+        if (fs.existsSync(overviewPath)) {
+          // 读 frontmatter 的 user_prompt 字段
+          const content = fs.readFileSync(overviewPath, 'utf-8').slice(0, 1000);
+          const m = content.match(/user_prompt:\s*["']?(.+?)["']?\n/);
+          if (m) summary = m[1].slice(0, 60);
+        }
+        const time = r.mtime.toISOString().slice(0, 19).replace('T', ' ');
+        console.log(`${time}  ${r.name.slice(0, 24)}  ${summary}`);
+      }
+    });
+
+  // cf executions open <route_id> — 用 IDE / 编辑器打开
+  cmd
+    .command('open <route_id>')
+    .description('打开指定执行的 overview 文档')
+    .action((routeId: string) => {
+      const baseDir = path.join(process.cwd(), '.claude-forge', 'executions', 'by-route');
+      if (!fs.existsSync(baseDir)) {
+        console.error('执行文档目录不存在。');
+        process.exit(1);
+      }
+      // 模糊匹配
+      const dirs = fs.readdirSync(baseDir).filter(d => d.includes(routeId));
+      if (dirs.length === 0) {
+        console.error(`未找到匹配的执行记录：${routeId}`);
+        process.exit(1);
+      }
+      const target = path.join(baseDir, dirs[0], 'overview.md');
+      if (!fs.existsSync(target)) {
+        console.error(`overview.md 不存在：${target}`);
+        process.exit(1);
+      }
+      // 用系统默认编辑器或 cat
+      const editor = process.env.EDITOR || process.env.VISUAL;
+      if (editor) {
+        execSync(`${editor} "${target}"`, { stdio: 'inherit' });
+      } else {
+        console.log(fs.readFileSync(target, 'utf-8'));
+      }
+    });
+
+  // cf executions clean — 清理旧文档
+  cmd
+    .command('clean')
+    .description('清理超过指定天数的执行文档')
+    .option('--before <days>', '清理 N 天前的文档', '30')
+    .option('--dry-run', '只显示将删除的文件，不实际删除')
+    .action(async (opts) => {
+      const baseDir = path.join(process.cwd(), '.claude-forge', 'executions', 'by-route');
+      if (!fs.existsSync(baseDir)) {
+        console.log('执行文档目录不存在，无需清理。');
+        return;
+      }
+      const days = parseInt(opts.before) || 30;
+      const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+      const toDelete: string[] = [];
+
+      for (const d of fs.readdirSync(baseDir, { withFileTypes: true })) {
+        if (!d.isDirectory()) continue;
+        const dirPath = path.join(baseDir, d.name);
+        const stat = fs.statSync(dirPath);
+        if (stat.mtime.getTime() < cutoff) {
+          toDelete.push(dirPath);
+        }
+      }
+
+      console.log(`将删除 ${toDelete.length} 个超过 ${days} 天的执行记录${opts.dryRun ? '（dry-run，不实际删除）' : ''}:`);
+      for (const p of toDelete) {
+        console.log(`  - ${path.basename(p)}`);
+        if (!opts.dryRun) {
+          fs.rmSync(p, { recursive: true, force: true });
+        }
+      }
+      if (!opts.dryRun && toDelete.length > 0) {
+        console.log(`已清理 ${toDelete.length} 个目录。`);
+      }
+    });
+}