@winspan/claude-forge 8.53.2 → 8.54.4

package/src/core/utils/error-handler.ts

@@ -1,257 +0,0 @@
-/**
- * 友好的错误提示处理器
- *
- * 将技术性错误转换为用户友好的中文提示，并提供解决方案
- */
-
-import { logger } from './logger.js';
-import { DEFAULTS } from '../constants.js';
-import chalk from 'chalk';
-
-export interface ErrorSolution {
-  message: string;
-  solutions: string[];
-  technicalDetails?: string;
-}
-
-export class ErrorHandler {
-  /**
-   * 处理端口占用错误
-   */
-  static handlePortInUse(port: number, error: any): ErrorSolution {
-    return {
-      message: `端口 ${port} 已被占用`,
-      solutions: [
-        `查看占用进程：lsof -i :${port}`,
-        `结束占用进程：kill -9 $(lsof -ti :${port})`,
-        `修改配置文件 ~/.claude-forge/config.yaml 中的端口号`,
-        `如果是守护进程自己占用，运行：claude-forge daemon stop`
-      ],
-      technicalDetails: error.message
-    };
-  }
-
-  /**
-   * 处理权限错误
-   */
-  static handlePermissionError(path: string, error: any): ErrorSolution {
-    return {
-      message: `没有权限访问：${path}`,
-      solutions: [
-        `检查文件权限：ls -la ${path}`,
-        `修复权限：chmod 755 ${path}`,
-        `如果是目录，确保父目录也有执行权限`,
-        `检查是否被其他进程锁定`
-      ],
-      technicalDetails: error.message
-    };
-  }
-
-  /**
-   * 处理数据库错误
-   */
-  static handleDatabaseError(dbPath: string, error: any): ErrorSolution {
-    const isCorrupted = error.message?.includes('corrupt') || error.message?.includes('malformed');
-    const isLocked = error.message?.includes('locked') || error.message?.includes('SQLITE_BUSY');
-
-    if (isCorrupted) {
-      return {
-        message: `数据库文件损坏：${dbPath}`,
-        solutions: [
-          `备份当前数据库：cp ${dbPath} ${dbPath}.backup`,
-          `删除损坏的数据库：rm ${dbPath}`,
-          `重启守护进程会自动创建新数据库`,
-          `如需恢复数据，请联系技术支持`
-        ],
-        technicalDetails: error.message
-      };
-    }
-
-    if (isLocked) {
-      return {
-        message: `数据库被锁定：${dbPath}`,
-        solutions: [
-          `检查是否有其他守护进程在运行：ps aux | grep claude-forge`,
-          `结束其他进程：claude-forge daemon stop`,
-          `如果问题持续，删除锁文件：rm ${dbPath}-wal ${dbPath}-shm`,
-          `重启守护进程`
-        ],
-        technicalDetails: error.message
-      };
-    }
-
-    return {
-      message: `数据库错误：${dbPath}`,
-      solutions: [
-        `检查磁盘空间：df -h`,
-        `检查文件权限：ls -la ${dbPath}`,
-        `查看详细日志：tail -f ~/.claude-forge/daemon.log`,
-        `如果问题持续，尝试重建数据库`
-      ],
-      technicalDetails: error.message
-    };
-  }
-
-  /**
-   * 处理 API Key 缺失
-   */
-  static handleMissingApiKey(): ErrorSolution {
-    return {
-      message: 'Anthropic API Key 未配置',
-      solutions: [
-        `设置环境变量：export ANTHROPIC_API_KEY=your-key-here`,
-        `或在配置文件中设置：~/.claude-forge/config.yaml`,
-        `获取 API Key：https://console.anthropic.com/settings/keys`,
-        `注意：没有 API Key 时，AI 功能（分类器、质量检查、提炼）将被禁用`
-      ]
-    };
-  }
-
-  /**
-   * 处理 Socket 连接错误
-   */
-  static handleSocketError(socketPath: string, error: any): ErrorSolution {
-    const isNotFound = error.code === 'ENOENT';
-    const isConnectionRefused = error.code === 'ECONNREFUSED';
-
-    if (isNotFound) {
-      return {
-        message: `Socket 文件不存在：${socketPath}`,
-        solutions: [
-          `检查守护进程是否运行：claude-forge daemon status`,
-          `启动守护进程：claude-forge daemon start`,
-          `检查 socket 目录权限：ls -la $(dirname ${socketPath})`
-        ],
-        technicalDetails: error.message
-      };
-    }
-
-    if (isConnectionRefused) {
-      return {
-        message: `无法连接到守护进程`,
-        solutions: [
-          `守护进程可能已崩溃，查看日志：tail -f ~/.claude-forge/daemon.log`,
-          `重启守护进程：claude-forge daemon stop && claude-forge daemon start`,
-          `检查是否有僵尸进程：ps aux | grep claude-forge`
-        ],
-        technicalDetails: error.message
-      };
-    }
-
-    return {
-      message: `Socket 连接错误`,
-      solutions: [
-        `检查守护进程状态：claude-forge daemon status`,
-        `查看日志：tail -f ~/.claude-forge/daemon.log`,
-        `尝试重启：claude-forge daemon stop && claude-forge daemon start`
-      ],
-      technicalDetails: error.message
-    };
-  }
-
-  /**
-   * 处理文件系统错误
-   */
-  static handleFileSystemError(path: string, error: any): ErrorSolution {
-    const isNoSpace = error.code === 'ENOSPC';
-    const isNotFound = error.code === 'ENOENT';
-
-    if (isNoSpace) {
-      return {
-        message: `磁盘空间不足`,
-        solutions: [
-          `检查磁盘使用情况：df -h`,
-          `清理日志文件：rm ~/.claude-forge/daemon.log.old`,
-          `清理旧数据：sqlite3 ~/.claude-forge/data.db "DELETE FROM events WHERE timestamp < datetime('now', '-30 days')"`
-        ],
-        technicalDetails: error.message
-      };
-    }
-
-    if (isNotFound) {
-      return {
-        message: `文件或目录不存在：${path}`,
-        solutions: [
-          `检查路径是否正确`,
-          `创建必要的目录：mkdir -p $(dirname ${path})`,
-          `如果是配置文件，运行初始化：claude-forge init`
-        ],
-        technicalDetails: error.message
-      };
-    }
-
-    return {
-      message: `文件系统错误：${path}`,
-      solutions: [
-        `检查路径权限：ls -la ${path}`,
-        `检查磁盘状态：df -h`,
-        `查看系统日志：dmesg | tail`
-      ],
-      technicalDetails: error.message
-    };
-  }
-
-  /**
-   * 格式化并打印错误信息
-   */
-  static printError(solution: ErrorSolution): void {
-    console.error(chalk.red.bold('\n✗ 错误：') + chalk.red(solution.message));
-
-    if (solution.solutions.length > 0) {
-      console.error(chalk.yellow('\n💡 解决方案：'));
-      solution.solutions.forEach((s, i) => {
-        console.error(chalk.yellow(`  ${i + 1}. ${s}`));
-      });
-    }
-
-    if (solution.technicalDetails) {
-      console.error(chalk.gray('\n📋 技术细节：'));
-      console.error(chalk.gray(`  ${solution.technicalDetails}`));
-    }
-
-    console.error(''); // 空行
-  }
-
-  /**
-   * 统一的错误处理入口
-   */
-  static handle(error: any, context?: string): void {
-    logger.error(`[ErrorHandler] ${context || 'Unknown context'}: ${error.message || error}`);
-
-    let solution: ErrorSolution | null = null;
-
-    // 根据错误类型自动识别并生成解决方案
-    if (error.code === 'EADDRINUSE') {
-      const port = parseInt(error.message?.match(/:(\d+)/)?.[1] || String(DEFAULTS.WEB_PORT));
-      solution = this.handlePortInUse(port, error);
-    } else if (error.code === 'EACCES' || error.code === 'EPERM') {
-      const path = error.path || error.message?.match(/['"]([^'"]+)['"]/)?.[1] || 'unknown';
-      solution = this.handlePermissionError(path, error);
-    } else if (error.code === 'ENOENT') {
-      const path = error.path || error.message?.match(/['"]([^'"]+)['"]/)?.[1] || 'unknown';
-      solution = this.handleFileSystemError(path, error);
-    } else if (error.code === 'ENOSPC') {
-      solution = this.handleFileSystemError('', error);
-    } else if (error.message?.includes('SQLITE') || error.message?.includes('database')) {
-      const dbPath = error.message?.match(/['"]([^'"]+\.db)['"]/)?.[1] || '~/.claude-forge/data.db';
-      solution = this.handleDatabaseError(dbPath, error);
-    } else if (error.code === 'ECONNREFUSED' || error.code === 'ENOENT') {
-      const socketPath = error.path || '~/.claude-forge/daemon.sock';
-      solution = this.handleSocketError(socketPath, error);
-    } else {
-      // 通用错误
-      solution = {
-        message: error.message || '未知错误',
-        solutions: [
-          '查看详细日志：tail -f ~/.claude-forge/daemon.log',
-          '检查守护进程状态：claude-forge daemon status',
-          '尝试重启：claude-forge daemon stop && claude-forge daemon start',
-          '如果问题持续，请提交 Issue：https://github.com/anthropics/claude-forge/issues'
-        ],
-        technicalDetails: error.stack
-      };
-    }
-
-    this.printError(solution);
-  }
-}

package/src/core/utils/forge-resume-block.ts

@@ -1,74 +0,0 @@
-/**
- * 项目根目录 CLAUDE.md 中的「续接」状态摘要的统一落盘格式。
- *
- * - 写入：`buildForgeResumeEnvelope`（ResumeEngine）
- * - 剥离：`stripForgeResumeBlocks`（注入前清理、clearResumeBlock）
- * - 检测：`hasForgeResumeBlock`（含旧版 `<!-- forge:resume -->` 与新版 begin 标记）
- */
-import { randomUUID } from 'crypto';
-
-/** 旧版续接块（正文裸放，易被 HTML 注释子串破坏） */
-const LEGACY_RESUME_BLOCK_RE = /\n*<!-- forge:resume -->[\s\S]*?<!-- forge:end-resume -->\s*/g;
-
-/** forge:resume-begin / end 之间的 UUID（randomUUID 小写） */
-const RESUME_UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
-
-function scopedResumeBlockRe(): RegExp {
-  return new RegExp(
-    `\\n*<!-- forge:resume-begin:(${RESUME_UUID}) -->[\\s\\S]*?<!-- forge:resume-end:\\1 -->\\s*`,
-    'gi'
-  );
-}
-
-/**
- * 构造续接信封：外层用 UUID 配对注释定界，正文保存在兼容旧解析器的 fenced block 中。
- */
-export function buildForgeResumeEnvelope(innerUtf8Markdown: string): string {
-  const id = randomUUID();
-  const iso = new Date().toISOString();
-  const body = innerUtf8Markdown.trim();
-
-  return [
-    `<!-- forge:resume-begin:${id} -->`,
-    '```forge-resume-body',
-    body,
-    '```',
-    '',
-    `_生成时间: ${iso}_`,
-    `<!-- forge:resume-end:${id} -->`,
-  ].join('\n');
-}
-
-/** 是否包含旧版或新版续接块 */
-export function hasForgeResumeBlock(content: string): boolean {
-  return (
-    content.includes('<!-- forge:resume -->') ||
-    new RegExp(`<!-- forge:resume-begin:${RESUME_UUID} -->`).test(content)
-  );
-}
-
-/**
- * 移除全部续接块（新版 UUID 信封 + 旧版裸正文），并压缩多余空行。
- */
-export function stripForgeResumeBlocks(content: string): string {
-  let s = content.replace(scopedResumeBlockRe(), '\n');
-  s = s.replace(LEGACY_RESUME_BLOCK_RE, '\n');
-  s = s.replace(/\n{4,}/g, '\n\n\n');
-  return s.trimEnd();
-}
-
-export function decodeForgeResumeInnerFromClaudeMd(content: string): string {
-  const fencedMatch = content.match(/```forge-resume-body\n([\s\S]*?)\n```/);
-  if (fencedMatch) {
-    return fencedMatch[1].trim();
-  }
-
-  const scopedMatch = content.match(
-    new RegExp(`<!-- forge:resume-begin:${RESUME_UUID} -->\\n([\\s\\S]*?)\\n(?:_生成时间:[\\s\\S]*?)?<!-- forge:resume-end:${RESUME_UUID} -->`)
-  );
-  if (scopedMatch) {
-    return scopedMatch[1].trim();
-  }
-
-  return '';
-}

package/src/core/utils/format.ts

@@ -1,69 +0,0 @@
-/**
- * 通用格式化工具（日志、错误）
- */
-
-/**
- * 格式化错误对象为日志友好的字符串
- */
-export function formatError(error: unknown): string {
-  if (error instanceof Error) {
-    return `${error.name}: ${error.message}${error.stack ? '\n' + error.stack : ''}`;
-  }
-  if (typeof error === 'string') {
-    return error;
-  }
-  return JSON.stringify(error);
-}
-
-/**
- * 格式化错误对象为简短消息（不含堆栈）
- */
-export function formatErrorShort(error: unknown): string {
-  if (error instanceof Error) {
-    return `${error.name}: ${error.message}`;
-  }
-  if (typeof error === 'string') {
-    return error;
-  }
-  return String(error);
-}
-
-/**
- * 格式化日志上下文（添加时间戳和级别）
- */
-export function formatLogContext(level: string, message: string, context?: Record<string, unknown>): string {
-  const timestamp = new Date().toISOString();
-  const contextStr = context ? ` ${JSON.stringify(context)}` : '';
-  return `[${timestamp}] [${level.toUpperCase()}] ${message}${contextStr}`;
-}
-
-/**
- * 截断长字符串（用于日志显示）
- */
-export function truncateString(str: string, maxLength: number = 100): string {
-  if (!str) return '';
-  if (str.length <= maxLength) return str;
-  return str.slice(0, maxLength) + '...';
-}
-
-/**
- * 格式化 JSON 为紧凑格式（单行，无缩进）
- */
-export function formatCompactJson(obj: unknown): string {
-  try {
-    return JSON.stringify(obj);
-  } catch {
-    return String(obj);
-  }
-}
-
-/**
- * 格式化 JSON 为可读格式（多行，带缩进）
- */
-export function formatPrettyJson(obj: unknown): string {
-  try {
-    return JSON.stringify(obj, null, 2);
-  } catch {
-    return String(obj);
-  }
-}

package/src/core/utils/git.ts

@@ -1,23 +0,0 @@
-import { execSync } from 'node:child_process';
-
-/**
- * Walk up the directory tree from `start` using `git rev-parse --show-toplevel`
- * to find the git repository root.
- *
- * Fallback: returns `start` unchanged if:
- *   - `start` is not inside a git repository
- *   - the git command fails for any reason (git not on PATH, permission error, etc.)
- */
-export function resolveGitRoot(start: string = process.cwd()): string {
-  try {
-    const result = execSync('git rev-parse --show-toplevel', {
-      cwd: start,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-      .toString()
-      .trim();
-    return result || start;
-  } catch {
-    return start;
-  }
-}

package/src/core/utils/logger.ts

@@ -1,134 +0,0 @@
-/**
- * Simple logger writing to stderr (or file in daemon mode)
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-export enum LogLevel {
-  DEBUG = 0,
-  INFO = 1,
-  WARN = 2,
-  ERROR = 3,
-}
-
-/**
- * Parse log level from LOG_LEVEL env var.
- * Accepts: debug, info, warn, error (case-insensitive). Falls back to INFO.
- */
-function getLogLevelFromEnv(): LogLevel {
-  const envLevel = (process.env.LOG_LEVEL ?? '').toLowerCase();
-  const levelMap: Record<string, LogLevel> = {
-    debug: LogLevel.DEBUG,
-    info: LogLevel.INFO,
-    warn: LogLevel.WARN,
-    error: LogLevel.ERROR,
-  };
-  return levelMap[envLevel] ?? LogLevel.INFO;
-}
-
-let currentLevel: LogLevel = getLogLevelFromEnv();
-let logFilePath: string | null = null;
-let lastSizeCheck = 0;
-let cachedSize = 0;
-
-const MAX_SIZE = 10 * 1024 * 1024; // 10MB
-const MAX_FILES = 3;
-const SIZE_CHECK_INTERVAL = 60000; // Check size every 60s
-
-function timestamp(): string {
-  return new Date().toISOString();
-}
-
-function format(level: string, message: string): string {
-  return `[${timestamp()}] [${level}] ${message}`;
-}
-
-function rotateLogIfNeeded(): void {
-  if (!logFilePath || !fs.existsSync(logFilePath)) return;
-
-  // Cache size check to avoid frequent stat calls
-  const now = Date.now();
-  if (now - lastSizeCheck >= SIZE_CHECK_INTERVAL) {
-    const stats = fs.statSync(logFilePath);
-    cachedSize = stats.size;
-    lastSizeCheck = now;
-  }
-
-  // Check if rotation is needed
-  if (cachedSize < MAX_SIZE) return;
-
-  // Rotate: .log -> .log.1 -> .log.2 -> .log.3 (delete oldest)
-  try {
-    for (let i = MAX_FILES - 1; i >= 1; i--) {
-      const oldPath = `${logFilePath}.${i}`;
-      const newPath = `${logFilePath}.${i + 1}`;
-      if (fs.existsSync(oldPath)) {
-        if (i === MAX_FILES - 1) {
-          fs.unlinkSync(oldPath); // Delete oldest
-        } else {
-          fs.renameSync(oldPath, newPath);
-        }
-      }
-    }
-    fs.renameSync(logFilePath, `${logFilePath}.1`);
-    cachedSize = 0; // Reset cache after rotation
-    lastSizeCheck = 0; // Force recheck on next write
-  } catch (err) {
-    // If rotation fails, just continue (better than crashing)
-    console.error(`[Logger] Log rotation failed: ${err}`);
-  }
-}
-
-function write(level: LogLevel, levelName: string, message: string): void {
-  if (level < currentLevel) return;
-  const formatted = format(levelName, message);
-
-  if (logFilePath) {
-    rotateLogIfNeeded();
-    try {
-      fs.appendFileSync(logFilePath, formatted + '\n');
-      // Update cached size after write
-      cachedSize += formatted.length + 1;
-    } catch (err) {
-      // Fallback to stderr if file write fails
-      console.error(formatted);
-    }
-  } else {
-    console.error(formatted);
-  }
-}
-
-export const logger = {
-  debug(message: string): void {
-    write(LogLevel.DEBUG, 'DEBUG', message);
-  },
-
-  info(message: string): void {
-    write(LogLevel.INFO, 'INFO', message);
-  },
-
-  warn(message: string): void {
-    write(LogLevel.WARN, 'WARN', message);
-  },
-
-  error(message: string): void {
-    write(LogLevel.ERROR, 'ERROR', message);
-  },
-};
-
-export function setLogLevel(level: LogLevel): void {
-  currentLevel = level;
-}
-
-/**
- * Enable file logging (for daemon mode)
- * @param filePath Path to log file
- */
-export function enableFileLogging(filePath: string): void {
-  logFilePath = filePath;
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-}

package/src/core/utils/lru-cache.ts

@@ -1,54 +0,0 @@
-/**
- * Simple LRU cache for AI responses
- */
-
-export class LRUCache<K, V> {
-  private cache = new Map<K, V>();
-  private maxSize: number;
-
-  constructor(maxSize: number = 100) {
-    this.maxSize = maxSize;
-  }
-
-  get(key: K): V | undefined {
-    const value = this.cache.get(key);
-    if (value !== undefined) {
-      // Move to end (most recently used)
-      this.cache.delete(key);
-      this.cache.set(key, value);
-    }
-    return value;
-  }
-
-  set(key: K, value: V): void {
-    // Remove if exists (to update position)
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    }
-
-    // Add to end
-    this.cache.set(key, value);
-
-    // Evict oldest if over capacity
-    if (this.cache.size > this.maxSize) {
-      const firstKey = this.cache.keys().next().value as K;
-      this.cache.delete(firstKey);
-    }
-  }
-
-  has(key: K): boolean {
-    return this.cache.has(key);
-  }
-
-  delete(key: K): boolean {
-    return this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  size(): number {
-    return this.cache.size;
-  }
-}

package/src/core/utils/path.ts

@@ -1,19 +0,0 @@
-import { homedir } from 'node:os';
-import { relative } from 'node:path';
-
-/**
- * Expand ~ to the user's home directory
- */
-export function expandPath(p: string): string {
-  if (p.startsWith('~/') || p === '~') {
-    return homedir() + p.slice(1);
-  }
-  return p;
-}
-
-/**
- * Return path relative to cwd
- */
-export function relPath(p: string): string {
-  return relative(process.cwd(), p);
-}

package/src/core/utils/session.ts

@@ -1,26 +0,0 @@
-/**
- * Session ID 处理工具
- */
-
-/**
- * 截断 Session ID 到指定长度（用于日志显示）
- */
-export function truncateSessionId(sessionId: string, length: number = 8): string {
-  if (!sessionId) return 'unknown';
-  return sessionId.slice(0, length);
-}
-
-/**
- * 验证 Session ID 格式（UUID v4）
- */
-export function isValidSessionId(sessionId: string): boolean {
-  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-  return uuidV4Regex.test(sessionId);
-}
-
-/**
- * 生成短 Session ID（用于显示）
- */
-export function formatSessionId(sessionId: string): string {
-  return `session:${truncateSessionId(sessionId)}`;
-}

package/src/core/utils/time.ts

@@ -1,37 +0,0 @@
-/**
- * 时间戳归一化工具
- *
- * 统一处理 ISO 8601 时间戳的 Z 后缀问题，确保所有时间戳都带 Z。
- */
-
-/**
- * 归一化时间戳，确保带 Z 后缀
- */
-export function normalizeTimestamp(timestamp: string): string {
-  if (!timestamp) return new Date().toISOString();
-  return timestamp.endsWith('Z') ? timestamp : timestamp + 'Z';
-}
-
-/**
- * 将时间戳转换为 Unix 毫秒数
- */
-export function timestampToMs(timestamp: string): number {
-  return new Date(normalizeTimestamp(timestamp)).getTime();
-}
-
-/**
- * 计算两个时间戳之间的毫秒差
- */
-export function timeDiff(start: string, end: string): number {
-  return timestampToMs(end) - timestampToMs(start);
-}
-
-/**
- * 格式化时间差为人类可读格式
- */
-export function formatDuration(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-  if (ms < 3600000) return `${(ms / 60000).toFixed(1)}m`;
-  return `${(ms / 3600000).toFixed(1)}h`;
-}