@winspan/claude-forge 8.39.0 → 8.50.6

package/src/web/routes/drift.ts

@@ -0,0 +1,25 @@
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+import { DriftDetector } from '../../daemon/services/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 '../../daemon/services/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 '../../daemon/services/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,101 @@
+/**
+ * /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
+ */
+
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+
+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();
+
+    // Query routing events
+    const routingEvents = storage.queryRoutingEvents({ since_ts: since, limit: 100000 });
+    const totalPrompts = routingEvents.length;
+
+    // Agent delegations: obeyed=1 means the routing was followed
+    const agentDelegations = routingEvents.filter(e => e.obeyed === 1).length;
+    const agentRate = totalPrompts > 0
+      ? `${(agentDelegations / totalPrompts * 100).toFixed(1)}%`
+      : '0%';
+
+    // Skill invocations
+    const skillInvocations = storage.querySkillInvocations({ since, limit: 100000 });
+    const skillTotal = skillInvocations.length;
+    const skillRate = totalPrompts > 0
+      ? `${(skillTotal / totalPrompts * 100).toFixed(1)}%`
+      : '0%';
+
+    // Per-skill aggregation
+    const skillMap = new Map<string, { total: number; success: number; failed: number }>();
+    for (const inv of skillInvocations) {
+      const cur = skillMap.get(inv.skill_id) || { total: 0, success: 0, failed: 0 };
+      cur.total++;
+      if (inv.success === 1) cur.success++;
+      else cur.failed++;
+      skillMap.set(inv.skill_id, cur);
+    }
+
+    const skills = Array.from(skillMap.entries())
+      .map(([skill_id, s]) => ({
+        skill_id,
+        total: s.total,
+        success: s.success,
+        failed: s.failed,
+        rate: totalPrompts > 0
+          ? `${(s.total / totalPrompts * 100).toFixed(1)}%`
+          : '0%',
+      }))
+      .sort((a, b) => b.total - a.total);
+
+    // Per-agent aggregation (only obeyed delegations)
+    const agentMap = new Map<string, number>();
+    for (const e of routingEvents) {
+      if (e.obeyed === 1 && e.routed_to_name) {
+        agentMap.set(e.routed_to_name, (agentMap.get(e.routed_to_name) || 0) + 1);
+      }
+    }
+
+    const agents = Array.from(agentMap.entries())
+      .map(([agent, count]) => ({
+        agent,
+        count,
+        rate: totalPrompts > 0
+          ? `${(count / totalPrompts * 100).toFixed(1)}%`
+          : '0%',
+      }))
+      .sort((a, b) => b.count - a.count);
+
+    // Never-triggered skills
+    const allSkillIds = skillRegistry
+      ? skillRegistry.getAll().map(s => s.id)
+      : [];
+    const triggeredSkillIds = new Set(skillMap.keys());
+    const neverTriggered = allSkillIds.filter(id => !triggeredSkillIds.has(id));
+
+    res.json({
+      period: { days, since: sinceISO },
+      summary: {
+        totalPrompts,
+        agentDelegations,
+        agentRate,
+        skillInvocations: skillTotal,
+        skillRate,
+      },
+      skills,
+      agents,
+      neverTriggered,
+    });
+  });
+}