@winspan/claude-forge 8.41.0 → 8.50.6

package/src/daemon/launchd/com.claude-forge.daemon.plist.template

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.claude-forge.daemon</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{NODE_PATH}}</string>
+        <string>{{DAEMON_PATH}}</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>{{HOME}}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+        <key>NODE_ENV</key>
+        <string>production</string>
+        <key>FORGE_DAEMON_FOREGROUND</key>
+        <string>1</string>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>{{HOME}}/.claude-forge/daemon-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{HOME}}/.claude-forge/daemon-stderr.log</string>
+</dict>
+</plist>

package/src/daemon/launchd-installer.ts

@@ -0,0 +1,260 @@
+/**
+ * macOS LaunchAgent integration for the Forge daemon.
+ *
+ * Renders the plist template, installs/uninstalls the LaunchAgent via launchctl,
+ * and reports status. Intended to give the daemon supervisor-grade auto-restart
+ * behavior on darwin without depending on systemd.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execSync, execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const LAUNCHD_LABEL = 'com.claude-forge.daemon';
+export const LAUNCH_AGENTS_DIR = path.join(os.homedir(), 'Library', 'LaunchAgents');
+export const PLIST_PATH = path.join(LAUNCH_AGENTS_DIR, `${LAUNCHD_LABEL}.plist`);
+
+export const TEMPLATE_PATH = path.resolve(
+  __dirname,
+  'launchd',
+  'com.claude-forge.daemon.plist.template'
+);
+
+export function ensureDarwin(): void {
+  if (process.platform !== 'darwin') {
+    throw new Error(
+      `LaunchAgent commands are only supported on macOS (current platform: ${process.platform}). ` +
+        `Use './scripts/dev-daemon.sh' or 'cf daemon start' on other platforms.`
+    );
+  }
+}
+
+export function getUid(): number {
+  if (typeof process.getuid === 'function') {
+    return process.getuid();
+  }
+  // Fallback: shell out (process.getuid is undefined on Windows but always defined on darwin).
+  return parseInt(execSync('id -u', { encoding: 'utf-8' }).trim(), 10);
+}
+
+export interface RenderOptions {
+  /**
+   * If true, points ProgramArguments at the local development build
+   * (`<repo>/dist/daemon/index.js` resolved from this module's location).
+   * Otherwise, resolves the daemon entry from the globally-installed package.
+   */
+  dev?: boolean;
+  /**
+   * Optional explicit path to the daemon entrypoint.
+   * Takes precedence over `dev`.
+   */
+  daemonPath?: string;
+  /**
+   * Optional explicit node path. Defaults to `process.execPath`.
+   */
+  nodePath?: string;
+}
+
+/**
+ * Resolve the path to `dist/daemon/index.js`.
+ *
+ * - In dev mode: resolves relative to this module (works in both src and dist).
+ * - In production mode: prefers a globally-installed `claude-forge` binary,
+ *   falling back to the path resolved from this module.
+ */
+export function resolveDaemonPath(opts: RenderOptions = {}): string {
+  if (opts.daemonPath) {
+    if (!fs.existsSync(opts.daemonPath)) {
+      throw new Error(`Provided daemon path does not exist: ${opts.daemonPath}`);
+    }
+    return opts.daemonPath;
+  }
+
+  // From `dist/daemon/launchd-installer.js` -> `dist/daemon/index.js`
+  // From `src/daemon/launchd-installer.ts` -> would resolve to src path; but we only ship dist.
+  const localGuess = path.resolve(__dirname, 'index.js');
+
+  if (opts.dev) {
+    if (!fs.existsSync(localGuess)) {
+      throw new Error(
+        `Local daemon entry not found at ${localGuess}. Run 'npm run build' first.`
+      );
+    }
+    return localGuess;
+  }
+
+  // Production mode: try to find global install via `which claude-forge`.
+  try {
+    const cliPath = execSync('command -v claude-forge', { encoding: 'utf-8' }).trim();
+    if (cliPath) {
+      const resolved = fs.realpathSync(cliPath);
+      // The CLI lives at <pkg>/dist/cli/index.js; daemon at <pkg>/dist/daemon/index.js.
+      const pkgRoot = path.resolve(path.dirname(resolved), '..');
+      const candidate = path.join(pkgRoot, 'daemon', 'index.js');
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  } catch {
+    // Ignore — fall through to local guess.
+  }
+
+  if (fs.existsSync(localGuess)) {
+    return localGuess;
+  }
+
+  throw new Error(
+    `Could not locate daemon entry. Install claude-forge globally (npm i -g @winspan/claude-forge) ` +
+      `or run with --dev after 'npm run build'.`
+  );
+}
+
+export function renderPlist(opts: RenderOptions = {}): string {
+  if (!fs.existsSync(TEMPLATE_PATH)) {
+    throw new Error(`plist template missing at ${TEMPLATE_PATH}. Did you run 'npm run build'?`);
+  }
+  const template = fs.readFileSync(TEMPLATE_PATH, 'utf-8');
+  const nodePath = opts.nodePath ?? process.execPath;
+  const daemonPath = resolveDaemonPath(opts);
+  const home = os.homedir();
+
+  return template
+    .replace(/{{NODE_PATH}}/g, nodePath)
+    .replace(/{{DAEMON_PATH}}/g, daemonPath)
+    .replace(/{{HOME}}/g, home);
+}
+
+function runLaunchctl(args: string[]): { stdout: string; stderr: string; code: number } {
+  try {
+    const stdout = execFileSync('launchctl', args, {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { stdout, stderr: '', code: 0 };
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { stdout?: Buffer; stderr?: Buffer; status?: number };
+    return {
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? e.message ?? '',
+      code: e.status ?? 1,
+    };
+  }
+}
+
+export interface InstallResult {
+  plistPath: string;
+  nodePath: string;
+  daemonPath: string;
+  reloaded: boolean;
+}
+
+export function install(opts: RenderOptions = {}): InstallResult {
+  ensureDarwin();
+  fs.mkdirSync(LAUNCH_AGENTS_DIR, { recursive: true });
+
+  const uid = getUid();
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+
+  // Idempotent: bootout existing service before re-installing.
+  let reloaded = false;
+  if (fs.existsSync(PLIST_PATH)) {
+    const r = runLaunchctl(['bootout', `gui/${uid}`, PLIST_PATH]);
+    if (r.code === 0 || /No such process|Could not find specified service/.test(r.stderr)) {
+      reloaded = true;
+    } else {
+      // Non-fatal; proceed and let bootstrap surface real errors.
+      reloaded = true;
+    }
+  }
+
+  const rendered = renderPlist(opts);
+  fs.writeFileSync(PLIST_PATH, rendered, { mode: 0o644 });
+
+  const bootstrap = runLaunchctl(['bootstrap', `gui/${uid}`, PLIST_PATH]);
+  if (bootstrap.code !== 0) {
+    throw new Error(
+      `launchctl bootstrap failed (exit ${bootstrap.code}): ${bootstrap.stderr.trim() || bootstrap.stdout.trim()}\n` +
+        `Service target: ${target}`
+    );
+  }
+
+  // Best-effort kickstart so the daemon comes up immediately.
+  runLaunchctl(['kickstart', '-k', target]);
+
+  // Read back rendered values to report.
+  const nodePath = opts.nodePath ?? process.execPath;
+  const daemonPath = resolveDaemonPath(opts);
+
+  return { plistPath: PLIST_PATH, nodePath, daemonPath, reloaded };
+}
+
+export interface UninstallResult {
+  removedPlist: boolean;
+  bootedOut: boolean;
+}
+
+export function uninstall(): UninstallResult {
+  ensureDarwin();
+  const uid = getUid();
+
+  let bootedOut = false;
+  if (fs.existsSync(PLIST_PATH)) {
+    const r = runLaunchctl(['bootout', `gui/${uid}`, PLIST_PATH]);
+    bootedOut =
+      r.code === 0 || /No such process|Could not find specified service/.test(r.stderr);
+  }
+
+  let removedPlist = false;
+  if (fs.existsSync(PLIST_PATH)) {
+    fs.unlinkSync(PLIST_PATH);
+    removedPlist = true;
+  }
+
+  return { bootedOut, removedPlist };
+}
+
+export interface LaunchdStatus {
+  installed: boolean;
+  loaded: boolean;
+  pid: number | null;
+  lastExitCode: number | null;
+  state: string | null;
+  raw: string;
+}
+
+export function status(): LaunchdStatus {
+  ensureDarwin();
+  const uid = getUid();
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+  const installed = fs.existsSync(PLIST_PATH);
+
+  const r = runLaunchctl(['print', target]);
+  if (r.code !== 0) {
+    return {
+      installed,
+      loaded: false,
+      pid: null,
+      lastExitCode: null,
+      state: null,
+      raw: r.stderr.trim() || r.stdout.trim(),
+    };
+  }
+
+  const out = r.stdout;
+  const pidMatch = out.match(/^\s*pid\s*=\s*(\d+)/m);
+  const stateMatch = out.match(/^\s*state\s*=\s*([\w-]+)/m);
+  const exitMatch = out.match(/^\s*last exit code\s*=\s*(-?\d+)/mi);
+
+  return {
+    installed,
+    loaded: true,
+    pid: pidMatch ? parseInt(pidMatch[1], 10) : null,
+    state: stateMatch ? stateMatch[1] : null,
+    lastExitCode: exitMatch ? parseInt(exitMatch[1], 10) : null,
+    raw: out,
+  };
+}

package/src/daemon/lifecycle.ts

@@ -0,0 +1,128 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { execSync, execFileSync } from 'child_process';
+import { logger } from '../core/utils/logger.js';
+import { FORGE_PATHS } from '../core/constants.js';
+
+const FORGE_HOME = FORGE_PATHS.home();
+const TOKEN_FILE = path.join(FORGE_HOME, 'daemon.token');
+const PID_FILE = path.join(FORGE_HOME, 'daemon.pid');
+
+export function writePidFile(): void {
+  if (!fs.existsSync(FORGE_HOME)) {
+    fs.mkdirSync(FORGE_HOME, { recursive: true });
+  }
+  fs.writeFileSync(PID_FILE, String(process.pid));
+}
+
+export function removePidFile(): void {
+  if (fs.existsSync(PID_FILE)) {
+    fs.unlinkSync(PID_FILE);
+  }
+}
+
+export function readPid(): number | null {
+  if (!fs.existsSync(PID_FILE)) {
+    return null;
+  }
+
+  try {
+    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim(), 10);
+
+    // 检查进程是否存活
+    try {
+      process.kill(pid, 0);
+      return pid;
+    } catch {
+      // 进程不存在，清理过期 PID 文件
+      removePidFile();
+      return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+export function isRunning(): boolean {
+  return readPid() !== null;
+}
+
+export function getSocketPath(): string {
+  return path.join(FORGE_HOME, 'daemon.sock');
+}
+
+export function cleanSocket(): void {
+  const socketPath = getSocketPath();
+  if (fs.existsSync(socketPath)) {
+    fs.unlinkSync(socketPath);
+  }
+}
+
+/** daemon 启动时生成随机 auth token，写入 chmod 600 文件 */
+export function writeAuthToken(): string {
+  const token = crypto.randomBytes(32).toString('hex');
+  if (!fs.existsSync(FORGE_HOME)) {
+    fs.mkdirSync(FORGE_HOME, { recursive: true });
+  }
+  fs.writeFileSync(TOKEN_FILE, token, { mode: 0o600 });
+  return token;
+}
+
+/** 读取当前 auth token */
+export function readAuthToken(): string | null {
+  if (!fs.existsSync(TOKEN_FILE)) return null;
+  try {
+    return fs.readFileSync(TOKEN_FILE, 'utf-8').trim();
+  } catch {
+    return null;
+  }
+}
+
+/** daemon 关闭时清理 token 文件 */
+export function removeAuthToken(): void {
+  if (fs.existsSync(TOKEN_FILE)) {
+    fs.unlinkSync(TOKEN_FILE);
+  }
+}
+
+/**
+ * Sync MCP registration token after daemon restart.
+ *
+ * Problem: Each daemon start generates a new token, but the MCP registration
+ * in Claude Code still has the old token → 401 → "Failed to connect".
+ *
+ * Solution: After writing the new token, re-register the MCP server with
+ * the updated Bearer header. This is a best-effort operation — if Claude CLI
+ * is not installed or registration fails, we log a warning and continue.
+ */
+export function syncMcpToken(token: string, port: number): void {
+  try {
+    execSync('command -v claude', { stdio: 'ignore' });
+  } catch {
+    return; // Claude CLI not installed, skip
+  }
+
+  try {
+    const checkOutput = execSync('claude mcp get claude-forge', {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8',
+    });
+    if (!checkOutput.includes('claude-forge')) return; // Not registered
+  } catch {
+    return; // Not registered, skip
+  }
+
+  const mcpUrl = `http://127.0.0.1:${port}/mcp`;
+  try {
+    execFileSync('claude', ['mcp', 'remove', 'claude-forge', '-s', 'user'], { stdio: 'ignore' });
+    execFileSync('claude', [
+      'mcp', 'add', '--transport', 'http', '-s', 'user',
+      'claude-forge', mcpUrl,
+      '-H', `Authorization: Bearer ${token}`,
+    ], { stdio: 'ignore' });
+    logger.info('[Lifecycle] MCP token synced successfully');
+  } catch (err) {
+    logger.warn(`[Lifecycle] MCP token sync failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+  }
+}

package/src/daemon/router.ts

@@ -0,0 +1,40 @@
+import type { ForgeEvent, HookResult } from '../core/types.js';
+import { isUserPromptSubmit, isPostToolUse, isStop } from '../core/types.js';
+import type { UserPromptHandler } from './handlers/user-prompt.js';
+import type { PostToolUseHandler } from './handlers/post-tool-use.js';
+import type { StopHandler } from './handlers/stop.js';
+import { logger } from '../core/utils/logger.js';
+import { formatError } from '../core/utils/format.js';
+import { truncateSessionId } from '../core/utils/session.js';
+
+export interface Handlers {
+  UserPromptSubmit: UserPromptHandler;
+  PostToolUse: PostToolUseHandler;
+  Stop: StopHandler;
+}
+
+/**
+ * Dispatch an event to the matching handler with hook-type narrowing.
+ *
+ * The narrow union (PreToolUseEvent / PostToolUseEvent / ...) is enforced at
+ * the handler entry, not at storage / wire level — so handlers can rely on
+ * required fields without `!` assertions.
+ *
+ * Error boundary: catches and logs handler errors to prevent daemon crashes.
+ */
+export async function routeEvent(event: ForgeEvent, handlers: Handlers): Promise<HookResult | void> {
+  try {
+    if (isUserPromptSubmit(event)) return await handlers.UserPromptSubmit.handle(event);
+    if (isPostToolUse(event)) return await handlers.PostToolUse.handle(event);
+    if (isStop(event)) return await handlers.Stop.handle(event);
+    // PreToolUse / Notification: handled inline in daemon/index.ts (no dedicated handler).
+  } catch (err) {
+    logger.error(
+      `[Router] Handler error for ${event.hook_type}: ${formatError(err)} ` +
+      `(session: ${truncateSessionId(event.session_id)})`
+    );
+
+    // Return safe default to prevent daemon crash
+    return { allow: true };
+  }
+}

package/src/daemon/server.ts

@@ -0,0 +1,209 @@
+import net from 'net';
+import fs from 'fs';
+import { EventParser } from './event-parser.js';
+import { logger } from '../core/utils/logger.js';
+import { formatError, truncateString } from '../core/utils/format.js';
+
+export interface HookResponse {
+  allow: boolean;
+  reason?: string;
+  additionalContext?: string;
+  systemMessage?: string;
+  hookSpecificOutput?: {
+    hookEventName: string;
+    permissionDecision: 'allow' | 'deny' | 'ask' | 'defer';
+    permissionDecisionReason?: string;
+  };
+}
+
+export type EventHandler = (
+  event: import('../core/types.js').ForgeEvent
+) => HookResponse | void | Promise<HookResponse | void>;
+
+export class SocketServer {
+  private server: net.Server;
+  private parser: EventParser;
+  private handler: EventHandler;
+  private authToken: string | null;
+  private static readonly MAX_BUFFER_SIZE = 512 * 1024; // 512KB
+
+  constructor(socketPath: string, handler: EventHandler, authToken?: string) {
+    this.parser = new EventParser();
+    this.handler = handler;
+    this.authToken = authToken ?? null;
+
+    this.server = net.createServer(this.handleConnection.bind(this));
+    this.server.listen(socketPath, () => {
+      // 限制 socket 文件仅当前用户可读写，防止同机其他用户注入伪造事件
+      try {
+        fs.chmodSync(socketPath, 0o600);
+      } catch (err) {
+        logger.warn(`[Socket] 设置权限失败：${formatError(err)}`);
+      }
+      logger.info(`Socket 服务器已监听：${socketPath}`);
+    });
+
+    this.server.on('error', (err) => {
+      logger.error(`Socket 服务器错误：${formatError(err)}`);
+    });
+  }
+
+  private handleConnection(socket: net.Socket): void {
+    let buffer = '';
+    let connectionTimeout: NodeJS.Timeout | null = null;
+
+    // 设置 10 秒超时，防止连接挂起
+    connectionTimeout = setTimeout(() => {
+      if (buffer.length > 0) {
+        logger.warn(`连接超时，数据不完整（${buffer.length} 字节）`);
+      }
+      socket.destroy();
+    }, 10000);
+
+    socket.on('data', async (chunk) => {
+      buffer += chunk.toString();
+
+      // 主动检查 buffer 大小，防止内存溢出
+      if (buffer.length > SocketServer.MAX_BUFFER_SIZE) {
+        logger.warn(`事件过大（${buffer.length} 字节），关闭连接`);
+        buffer = '';
+        if (connectionTimeout) clearTimeout(connectionTimeout);
+        socket.destroy();
+        return;
+      }
+
+      try {
+        // 认证检查：在 EventParser 之前提取 _auth 字段（zod 会剥离未知字段）
+        if (this.authToken) {
+          try {
+            const raw = JSON.parse(buffer);
+            if (raw._auth !== this.authToken) {
+              logger.warn('[Socket] 认证失败，关闭连接');
+              buffer = '';
+              if (connectionTimeout) clearTimeout(connectionTimeout);
+              socket.destroy();
+              return;
+            }
+          } catch {
+            // JSON 解析失败，交给下面的 EventParser 处理
+          }
+        }
+
+        const event = this.parser.parse(buffer);
+        buffer = '';
+        if (connectionTimeout) clearTimeout(connectionTimeout);
+
+        const result = await this.handler(event);
+
+        // 双向通信：如果 handler 返回了结果，写回给 hook 脚本
+        if (result) {
+          // 清理无意义内容，避免 Claude Code 注入干扰上下文
+          const cleaned = { ...result } as Record<string, unknown>;
+          if (cleaned['additionalContext'] && !this.isValidContent(cleaned['additionalContext'] as string)) {
+            delete cleaned['additionalContext'];
+          }
+          if (cleaned['systemMessage'] && !this.isValidContent(cleaned['systemMessage'] as string)) {
+            delete cleaned['systemMessage'];
+          }
+
+          const payload = JSON.stringify(cleaned);
+          socket.write(payload, () => socket.end());
+        } else {
+          socket.end();
+        }
+      } catch (err) {
+        // 区分"JSON 不完整"和"格式错误"
+        if (err instanceof SyntaxError) {
+          const trimmed = buffer.trim();
+          if (trimmed.startsWith('{') && !this.isCompleteJSON(trimmed)) {
+            // JSON 不完整，继续等待
+            logger.debug(`缓冲区不完整（${buffer.length} 字节），等待更多数据`);
+            return;
+          }
+        }
+
+        logger.error(`事件解析失败：${formatError(err)}`);
+        logger.debug(`无效缓冲区内容：${truncateString(buffer, 500)}`);
+        buffer = '';
+        if (connectionTimeout) clearTimeout(connectionTimeout);
+        socket.destroy();
+      }
+    });
+
+    socket.on('error', (err) => {
+      logger.debug(`Socket 连接错误：${formatError(err)}`);
+      if (connectionTimeout) clearTimeout(connectionTimeout);
+    });
+
+    socket.on('close', () => {
+      if (connectionTimeout) clearTimeout(connectionTimeout);
+    });
+  }
+
+  /**
+   * 判断内容是否有意义，过滤空字符串、纯标点/符号等
+   */
+  private isValidContent(content: string): boolean {
+    if (!content) return false;
+    const trimmed = content.trim();
+    if (trimmed.length === 0) return false;
+
+    const stripped = trimmed
+      .split('\n')
+      .map(line => line.replace(/^>\s*/, '').trim())
+      .join('\n')
+      .trim();
+
+    if (stripped.length === 0) return false;
+    if (!/[\p{L}\p{N}]/u.test(stripped)) return false;
+
+    return true;
+  }
+
+  /**
+   * 简单检查 JSON 是否完整（启发式方法）
+   */
+  private isCompleteJSON(str: string): boolean {
+    let braceCount = 0;
+    let bracketCount = 0;
+    let inString = false;
+    let escaped = false;
+
+    for (let i = 0; i < str.length; i++) {
+      const char = str[i];
+
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+
+      if (char === '\\') {
+        escaped = true;
+        continue;
+      }
+
+      if (char === '"') {
+        inString = !inString;
+        continue;
+      }
+
+      if (inString) continue;
+
+      if (char === '{') braceCount++;
+      else if (char === '}') braceCount--;
+      else if (char === '[') bracketCount++;
+      else if (char === ']') bracketCount--;
+    }
+
+    return braceCount === 0 && bracketCount === 0 && !inString;
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.server.close(() => {
+        logger.info('Socket 服务器已关闭');
+        resolve();
+      });
+    });
+  }
+}