@winspan/claude-forge 8.41.0 → 8.51.0

package/src/web/routes/ai.ts

@@ -0,0 +1,204 @@
+import type { Application } from 'express';
+import { ConfigManager } from '../../core/config.js';
+import { logger } from '../../core/utils/logger.js';
+import {
+  validateBaseUrl,
+  extractHostFromBaseUrl,
+  UPSTREAM_TIMEOUT_MS,
+} from '../ssrf-guard.js';
+import type { RouteContext } from './types.js';
+
+/**
+ * /api/ai/* and /api/config/ai — AI provider config + upstream connectivity.
+ *
+ * All outbound calls route through validateBaseUrl + redirect:'manual' so the
+ * daemon cannot be tricked into reaching internal hosts (SSRF guard).
+ */
+export function registerAIRoutes(app: Application, _ctx: RouteContext): void {
+  // GET /api/config/ai — read current AI config
+  app.get('/api/config/ai', (_req, res) => {
+    const configManager = new ConfigManager();
+    const config = configManager.get();
+
+    res.json({
+      api_key: config.ai.api_key || '',
+      base_url: config.ai.base_url || '',
+      model: config.ai.model,
+      provider: config.ai.provider,
+    });
+  });
+
+  // PUT /api/config/ai — update AI config
+  app.put('/api/config/ai', (req, res) => {
+    const { api_key, base_url, model, provider } = req.body ?? {};
+
+    try {
+      const configManager = new ConfigManager();
+      const config = configManager.get();
+
+      if (typeof api_key === 'string') config.ai.api_key = api_key;
+      if (typeof base_url === 'string') {
+        // Normalize http → https for upstream gateways that force HTTPS redirect
+        // (e.g. iflytek one.iflytek.com returns 302 and drops Authorization header)
+        let url = base_url.trim();
+        if (url.startsWith('http://')) url = 'https://' + url.slice('http://'.length);
+        config.ai.base_url = url;
+      }
+      if (typeof model === 'string') config.ai.model = model;
+      if (typeof provider === 'string') config.ai.provider = provider;
+
+      configManager.save();
+      logger.info('[Web] AI config updated');
+      res.json({ success: true });
+    } catch (err) {
+      logger.warn(`[Web] Failed to update AI config: ${err}`);
+      res.status(500).json({ error: String(err) });
+    }
+  });
+
+  // GET /api/ai/models — proxy to upstream /v1/models
+  app.get('/api/ai/models', async (req, res) => {
+    try {
+      const configManager = new ConfigManager();
+      const config = configManager.get();
+
+      const queryKey = typeof req.query.api_key === 'string' ? req.query.api_key : '';
+      const queryUrl = typeof req.query.base_url === 'string' ? req.query.base_url : '';
+      const apiKey = queryKey || config.ai.api_key;
+      let baseUrl = queryUrl || config.ai.base_url || 'https://api.anthropic.com';
+      if (baseUrl.startsWith('http://')) baseUrl = 'https://' + baseUrl.slice('http://'.length);
+
+      if (!apiKey) {
+        res.status(400).json({ error: 'API key not configured' });
+        return;
+      }
+
+      const configuredHost = extractHostFromBaseUrl(config.ai.base_url);
+      const validation = validateBaseUrl(baseUrl, configuredHost ? [configuredHost] : []);
+      if (!validation.ok) {
+        res.status(400).json({ error: validation.error });
+        return;
+      }
+
+      const modelsUrl = baseUrl.endsWith('/v1')
+        ? `${baseUrl}/models`
+        : `${baseUrl}/v1/models`;
+
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
+      let response: Response;
+      try {
+        response = await fetch(modelsUrl, {
+          redirect: 'manual',
+          signal: controller.signal,
+          headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'x-api-key': apiKey,
+          },
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+
+      if (response.status >= 300 && response.status < 400) {
+        res.status(400).json({
+          error: `Upstream tried to redirect (status ${response.status}); refusing to follow`,
+        });
+        return;
+      }
+
+      if (!response.ok) {
+        const text = await response.text();
+        logger.warn(`[Web] Upstream /v1/models failed: ${response.status} ${text}`);
+        res.status(response.status).json({ error: text });
+        return;
+      }
+
+      const data = await response.json();
+      res.json(data);
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        res.status(504).json({ error: `Upstream timeout (${UPSTREAM_TIMEOUT_MS}ms)` });
+        return;
+      }
+      logger.warn(`[Web] Failed to fetch models: ${err}`);
+      res.status(500).json({ error: String(err) });
+    }
+  });
+
+  // POST /api/ai/test — test AI connection using provided or saved config
+  app.post('/api/ai/test', async (req, res) => {
+    try {
+      const configManager = new ConfigManager();
+      const config = configManager.get();
+
+      const { api_key, base_url, model } = req.body ?? {};
+      const apiKey = (typeof api_key === 'string' && api_key) || config.ai.api_key;
+      let baseUrl = (typeof base_url === 'string' && base_url) || config.ai.base_url || 'https://api.anthropic.com';
+      const useModel = (typeof model === 'string' && model) || config.ai.model;
+      if (baseUrl.startsWith('http://')) baseUrl = 'https://' + baseUrl.slice('http://'.length);
+
+      if (!apiKey) {
+        res.status(400).json({ error: 'API key not configured' });
+        return;
+      }
+
+      const configuredHost = extractHostFromBaseUrl(config.ai.base_url);
+      const validation = validateBaseUrl(baseUrl, configuredHost ? [configuredHost] : []);
+      if (!validation.ok) {
+        res.status(400).json({ error: validation.error });
+        return;
+      }
+
+      const messagesUrl = baseUrl.endsWith('/v1')
+        ? `${baseUrl}/messages`
+        : `${baseUrl}/v1/messages`;
+
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
+      let response: Response;
+      try {
+        response = await fetch(messagesUrl, {
+          method: 'POST',
+          redirect: 'manual',
+          signal: controller.signal,
+          headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+          },
+          body: JSON.stringify({
+            model: useModel,
+            max_tokens: 10,
+            messages: [{ role: 'user', content: 'ping' }],
+          }),
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+
+      if (response.status >= 300 && response.status < 400) {
+        res.status(400).json({
+          error: `Upstream tried to redirect (status ${response.status}); refusing to follow`,
+        });
+        return;
+      }
+
+      if (!response.ok) {
+        const text = await response.text();
+        res.status(response.status).json({ error: text });
+        return;
+      }
+
+      const data = await response.json() as { model?: string };
+      res.json({ success: true, model: data.model || useModel });
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        res.status(504).json({ error: `Upstream timeout (${UPSTREAM_TIMEOUT_MS}ms)` });
+        return;
+      }
+      logger.warn(`[Web] AI connection test failed: ${err}`);
+      res.status(500).json({ error: String(err) });
+    }
+  });
+}

package/src/web/routes/auth.ts

@@ -0,0 +1,22 @@
+import type { Application } from 'express';
+import { readAuthToken } from '../auth-middleware.js';
+import type { RouteContext } from './types.js';
+
+/**
+ * Auth routes — localhost bootstrap endpoint that returns the daemon token.
+ *
+ * This endpoint is intentionally NOT protected by requireAuth: the token file
+ * on disk is chmod 600 (current user only), so anyone who can reach this
+ * endpoint already has access to the file. Protecting it would create a
+ * chicken-and-egg problem for the UI.
+ */
+export function registerAuthRoutes(app: Application, _ctx: RouteContext): void {
+  app.get('/api/auth/token', (_req, res) => {
+    const token = readAuthToken();
+    if (!token) {
+      res.status(404).json({ error: 'TOKEN_NOT_FOUND' });
+      return;
+    }
+    res.json({ token });
+  });
+}

package/src/web/routes/drift.ts

@@ -0,0 +1,25 @@
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+import { DriftDetector } from '../analytics/drift-detector.js';
+
+/**
+ * /api/drift/* — CLAUDE.md 漂移检测 API
+ *
+ * Provides compliance drift report comparing declared behavior
+ * in CLAUDE.md against actual event stream data.
+ */
+export function registerDriftRoutes(app: Application, ctx: RouteContext): void {
+  const { storage } = ctx;
+
+  app.get('/api/drift/report', (req, res) => {
+    const days = parseInt((req.query.days as string) || '7');
+    if (isNaN(days) || days < 1 || days > 90) {
+      res.status(400).json({ error: 'days must be between 1 and 90' });
+      return;
+    }
+
+    const detector = new DriftDetector(storage);
+    const report = detector.run(days);
+    res.json(report);
+  });
+}

package/src/web/routes/error-handler.ts

@@ -0,0 +1,120 @@
+import type { Request, Response, NextFunction } from 'express';
+import { logger } from '../../core/utils/logger.js';
+
+/**
+ * Error types for classification
+ */
+export enum ErrorType {
+  VALIDATION = 'validation',
+  NOT_FOUND = 'not_found',
+  UNAUTHORIZED = 'unauthorized',
+  FORBIDDEN = 'forbidden',
+  INTERNAL = 'internal',
+  BAD_REQUEST = 'bad_request',
+}
+
+/**
+ * Structured error response
+ */
+export interface ErrorResponse {
+  error: string;
+  type: ErrorType;
+  details?: unknown;
+  timestamp: string;
+}
+
+/**
+ * Custom error class with type information
+ */
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public type: ErrorType = ErrorType.INTERNAL,
+    public statusCode: number = 500,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+/**
+ * Global error handler middleware
+ */
+export function errorHandler(
+  err: Error | AppError,
+  req: Request,
+  res: Response,
+  _next: NextFunction,
+): void {
+  // Log error
+  const errorMessage = err.message;
+  const errorStack = err.stack;
+
+  logger.error(`[Web] ${req.method} ${req.path} - ${errorMessage}`);
+  if (errorStack) {
+    logger.error(`[Web] Stack trace: ${errorStack}`);
+  }
+
+  // Determine error type and status code
+  let statusCode = 500;
+  let errorType = ErrorType.INTERNAL;
+  let details: unknown = undefined;
+
+  if (err instanceof AppError) {
+    statusCode = err.statusCode;
+    errorType = err.type;
+    details = err.details;
+  } else if (err.name === 'ValidationError') {
+    statusCode = 400;
+    errorType = ErrorType.VALIDATION;
+  } else if (err.message.includes('not found')) {
+    statusCode = 404;
+    errorType = ErrorType.NOT_FOUND;
+  } else if (err.message.includes('unauthorized') || err.message.includes('authentication')) {
+    statusCode = 401;
+    errorType = ErrorType.UNAUTHORIZED;
+  } else if (err.message.includes('forbidden') || err.message.includes('permission')) {
+    statusCode = 403;
+    errorType = ErrorType.FORBIDDEN;
+  } else if (err.message.includes('Invalid') || err.message.includes('invalid')) {
+    statusCode = 400;
+    errorType = ErrorType.BAD_REQUEST;
+  }
+
+  // Send error response
+  const response: ErrorResponse = {
+    error: err.message,
+    type: errorType,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (details) {
+    response.details = details;
+  }
+
+  res.status(statusCode).json(response);
+}
+
+/**
+ * 404 handler for undefined routes
+ */
+export function notFoundHandler(req: Request, res: Response): void {
+  logger.warn(`[Web] 404 - ${req.method} ${req.path}`);
+  res.status(404).json({
+    error: `Route not found: ${req.method} ${req.path}`,
+    type: ErrorType.NOT_FOUND,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+/**
+ * Async route handler wrapper to catch errors
+ */
+export function asyncHandler(
+  fn: (req: Request, res: Response, next: NextFunction) => Promise<void>,
+) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}

package/src/web/routes/events.ts

@@ -0,0 +1,47 @@
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+
+/**
+ * /api/events — recent events list + SSE live stream.
+ *
+ * Note: /api/events/stream must be registered BEFORE `/api/events` handlers
+ * that might swallow it, but Express matches exact paths so order here is
+ * not actually load-bearing for correctness.
+ */
+export function registerEventsRoutes(app: Application, ctx: RouteContext): void {
+  const { storage } = ctx;
+
+  app.get('/api/events', (req, res) => {
+    const limit = parseInt(req.query.limit as string) || 50;
+    const projectPath = req.query.project as string | undefined;
+    const sessionId = req.query.session as string | undefined;
+    const events = storage.queryEvents({ project_path: projectPath, session_id: sessionId, limit });
+    res.json(events);
+  });
+
+  // SSE: real-time event stream
+  app.get('/api/events/stream', (req, res) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+    res.write('data: {"type":"connected"}\n\n');
+
+    const filterSession = req.query.session as string | undefined;
+    const filterProject = req.query.project as string | undefined;
+    const filterHook = req.query.hook as string | undefined;
+
+    const onEvent = (event: Record<string, unknown>) => {
+      if (filterSession && event.session_id !== filterSession) return;
+      if (filterProject && event.project_path !== filterProject) return;
+      if (filterHook && event.hook_type !== filterHook) return;
+      res.write(`data: ${JSON.stringify(event)}\n\n`);
+    };
+
+    storage.on('event', onEvent);
+    req.on('close', () => {
+      storage.removeListener('event', onEvent);
+    });
+  });
+}

package/src/web/routes/insights.ts

@@ -0,0 +1,43 @@
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+import {
+  AntiPatternDetector,
+  type AntiPattern,
+  type AntiPatternSeverity,
+} from '../analytics/anti-pattern-detector.js';
+
+/**
+ * /api/insights — 工作流反模式检测 API
+ *
+ * 扫描事件流，识别可操作的反模式（编辑循环 / 工具失败 / 无 commit / 事件爆量）。
+ */
+export function registerInsightsRoutes(app: Application, ctx: RouteContext): void {
+  const { storage } = ctx;
+
+  app.get('/api/insights', (req, res) => {
+    const raw = req.query.days;
+    const days = parseInt(typeof raw === 'string' ? raw : '7', 10);
+    if (Number.isNaN(days) || days < 1 || days > 90) {
+      res.status(400).json({ error: 'days must be between 1 and 90' });
+      return;
+    }
+
+    const detector = new AntiPatternDetector(storage);
+    const patterns = detector.detectAll(days);
+
+    const summary: Record<AntiPatternSeverity, number> & { total: number } = {
+      total: patterns.length,
+      critical: 0,
+      warn: 0,
+      info: 0,
+    };
+    for (const p of patterns) summary[p.severity] += 1;
+
+    res.json({
+      generatedAt: new Date().toISOString(),
+      windowDays: days,
+      summary,
+      patterns: patterns satisfies AntiPattern[],
+    });
+  });
+}

package/src/web/routes/patch.ts

@@ -0,0 +1,117 @@
+import type { Application } from 'express';
+import fs from 'fs';
+import path from 'path';
+import { ConfigManager } from '../../core/config.js';
+import { ClaudeProvider } from '../../core/ai/provider.js';
+import { logger } from '../../core/utils/logger.js';
+import type { RouteContext } from './types.js';
+import { resolvePatchTarget } from './types.js';
+
+/**
+ * /api/patch/* — AI-assisted patch preview + apply (with backup).
+ */
+export function registerPatchRoutes(app: Application, _ctx: RouteContext): void {
+  // POST /api/patch/preview — generate structured patch preview
+  app.post('/api/patch/preview', async (req, res) => {
+    const { targetType, targetName, recommendation, rationale } = req.body ?? {};
+    if (!targetType || !targetName || !recommendation) {
+      res.status(400).json({ error: 'targetType, targetName, and recommendation are required' });
+      return;
+    }
+
+    try {
+      const config = new ConfigManager().get();
+      const apiKey = config.ai.api_key || process.env.ANTHROPIC_API_KEY || '';
+      if (!apiKey) {
+        res.status(400).json({ error: 'AI API key not configured' });
+        return;
+      }
+
+      const { filePath } = resolvePatchTarget(targetType, targetName);
+      if (!fs.existsSync(filePath)) {
+        res.status(404).json({ error: `Target file not found: ${filePath}` });
+        return;
+      }
+
+      const currentContent = fs.readFileSync(filePath, 'utf-8');
+      const ai = new ClaudeProvider(apiKey, config.ai.model, config.ai.base_url);
+
+      const prompt = `You are a code/config optimization assistant. Given the current file content and a recommended change, generate the updated content.
+
+Current file (${targetType}/${targetName}):
+\`\`\`
+${currentContent}
+\`\`\`
+
+Recommendation: ${recommendation}
+${rationale ? `Rationale: ${rationale}` : ''}
+
+Return ONLY a JSON object with this exact structure (no markdown, no explanation):
+{
+  "summary": "brief description of what changed",
+  "afterContent": "the complete updated file content",
+  "risk": "low|medium|high"
+}`;
+
+      const response = await ai.complete(prompt, { maxTokens: 4096 });
+      const parsed = JSON.parse(response.trim());
+
+      res.json({
+        targetType,
+        targetName,
+        filePath,
+        before: currentContent,
+        after: parsed.afterContent,
+        summary: parsed.summary,
+        risk: parsed.risk || 'medium',
+        recommendation,
+        rationale: rationale || null,
+      });
+    } catch (err) {
+      logger.warn(`[Web] Patch preview failed: ${err}`);
+      res.status(500).json({ error: String(err) });
+    }
+  });
+
+  // POST /api/patch/apply — apply patch with backup
+  app.post('/api/patch/apply', (req, res) => {
+    const { targetType, targetName, afterContent } = req.body ?? {};
+    if (!targetType || !targetName || typeof afterContent !== 'string') {
+      res.status(400).json({ error: 'targetType, targetName, and afterContent are required' });
+      return;
+    }
+
+    try {
+      const { filePath, backupDir } = resolvePatchTarget(targetType, targetName);
+      if (!fs.existsSync(filePath)) {
+        res.status(404).json({ error: `Target file not found: ${filePath}` });
+        return;
+      }
+
+      // Create backup
+      if (!fs.existsSync(backupDir)) {
+        fs.mkdirSync(backupDir, { recursive: true });
+      }
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const backupName = `${targetName}_${timestamp}${path.extname(filePath)}`;
+      const backupPath = path.join(backupDir, backupName);
+      fs.copyFileSync(filePath, backupPath);
+
+      // Apply patch
+      fs.writeFileSync(filePath, afterContent, 'utf-8');
+
+      logger.info(`[Web] Patch applied to ${targetType}/${targetName}, backup: ${backupPath}`);
+      res.json({
+        success: true,
+        targetType,
+        targetName,
+        filePath,
+        backupPath,
+        timestamp,
+      });
+    } catch (err) {
+      logger.warn(`[Web] Patch apply failed: ${err}`);
+      res.status(500).json({ error: String(err) });
+    }
+  });
+}

package/src/web/routes/reports.ts

@@ -0,0 +1,34 @@
+/**
+ * /api/reports/weekly — Weekly work report
+ *
+ * Aggregates the last week's activity into a structured report. Supports
+ * both JSON (default) and Markdown output formats.
+ */
+
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+import { WeeklyReportGenerator } from '../analytics/weekly-report.js';
+
+export function registerReportsRoutes(app: Application, ctx: RouteContext): void {
+  const { storage, skillRegistry } = ctx;
+
+  app.get('/api/reports/weekly', (req, res) => {
+    const weekOffsetRaw = (req.query.weekOffset as string) ?? '0';
+    const weekOffset = Number.isFinite(Number(weekOffsetRaw)) ? Number(weekOffsetRaw) : 0;
+    const format = (req.query.format as string) === 'markdown' ? 'markdown' : 'json';
+
+    const generator = new WeeklyReportGenerator(storage, skillRegistry);
+    const report = generator.generate(weekOffset);
+
+    if (format === 'markdown') {
+      const md = generator.toMarkdown(report);
+      const filename = `weekly-report-w${report.week.isoWeekNumber}.md`;
+      res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+      res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
+      res.send(md);
+      return;
+    }
+
+    res.json(report);
+  });
+}

package/src/web/routes/rules.ts

@@ -0,0 +1,76 @@
+/**
+ * /api/rules/hit-rate — Rule hit-rate statistics
+ *
+ * Aggregates routing_events and skill_invocations to show:
+ *   - Agent delegation rate
+ *   - Skill invocation rate
+ *   - Per-skill breakdown
+ *   - Per-agent breakdown
+ *   - Never-triggered skills
+ *
+ * H1 refactor: pushed GROUP BY into SQL via storage.aggregateRoutingStats /
+ * aggregateSkillInvocationsBySkill — no more 100k-row JS scans.
+ */
+
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+
+function pct(num: number, denom: number): string {
+  if (denom <= 0) return '0%';
+  return `${(num / denom * 100).toFixed(1)}%`;
+}
+
+export function registerRulesRoutes(app: Application, ctx: RouteContext): void {
+  const { storage, skillRegistry } = ctx;
+
+  app.get('/api/rules/hit-rate', (req, res) => {
+    const days = Math.max(1, parseInt((req.query.days as string) || '7'));
+    const since = Date.now() - days * 24 * 3600 * 1000;
+    const sinceISO = new Date(since).toISOString();
+
+    // SQL-side aggregates (replaces 2 × 100k-row scans + JS reduce)
+    const routing = storage.aggregateRoutingStats({ since_ts: since });
+    const skillsAgg = storage.aggregateSkillInvocationsBySkill({ since });
+
+    const totalPrompts = routing.total;
+    const agentDelegations = routing.obeyed;
+
+    // Skills frequency (sorted by total desc — SQL ORDER BY total DESC)
+    const skillTotal = skillsAgg.reduce((acc, s) => acc + s.total, 0);
+    const skills = skillsAgg.map(s => ({
+      skill_id: s.skill_id,
+      total: s.total,
+      success: s.success,
+      failed: s.failed,
+      rate: pct(s.total, totalPrompts),
+    }));
+
+    // Agents breakdown (already obeyed=1, sorted by count desc in SQL)
+    const agents = routing.by_agent.map(a => ({
+      agent: a.agent,
+      count: a.count,
+      rate: pct(a.count, totalPrompts),
+    }));
+
+    // Never-triggered skills
+    const triggeredSkillIds = new Set(skillsAgg.map(s => s.skill_id));
+    const allSkillIds = skillRegistry
+      ? skillRegistry.getAll().map(s => s.id)
+      : [];
+    const neverTriggered = allSkillIds.filter(id => !triggeredSkillIds.has(id));
+
+    res.json({
+      period: { days, since: sinceISO },
+      summary: {
+        totalPrompts,
+        agentDelegations,
+        agentRate: pct(agentDelegations, totalPrompts),
+        skillInvocations: skillTotal,
+        skillRate: pct(skillTotal, totalPrompts),
+      },
+      skills,
+      agents,
+      neverTriggered,
+    });
+  });
+}