claude-code-workflow 6.3.18 → 6.3.20

package/ccw/src/types/cli-settings.ts

@@ -0,0 +1,137 @@
+/**
+ * CLI Settings Type Definitions
+ * Supports Claude CLI --settings parameter format
+ */
+
+/**
+ * Claude CLI Settings 文件格式
+ * 对应 `claude --settings <file-or-json>` 参数
+ */
+export interface ClaudeCliSettings {
+  /** 环境变量配置 */
+  env: {
+    /** Anthropic API Token */
+    ANTHROPIC_AUTH_TOKEN?: string;
+    /** Anthropic API Base URL */
+    ANTHROPIC_BASE_URL?: string;
+    /** 禁用自动更新 */
+    DISABLE_AUTOUPDATER?: string;
+    /** 其他自定义环境变量 */
+    [key: string]: string | undefined;
+  };
+  /** 模型选择 */
+  model?: 'opus' | 'sonnet' | 'haiku' | string;
+  /** 是否包含 co-authored-by */
+  includeCoAuthoredBy?: boolean;
+}
+
+/**
+ * 端点 Settings 配置（带元数据）
+ */
+export interface EndpointSettings {
+  /** 端点唯一标识 */
+  id: string;
+  /** 端点显示名称 */
+  name: string;
+  /** 端点描述 */
+  description?: string;
+  /** Claude CLI Settings */
+  settings: ClaudeCliSettings;
+  /** 是否启用 */
+  enabled: boolean;
+  /** 创建时间 */
+  createdAt: string;
+  /** 更新时间 */
+  updatedAt: string;
+}
+
+/**
+ * Settings 列表响应
+ */
+export interface SettingsListResponse {
+  endpoints: EndpointSettings[];
+  total: number;
+}
+
+/**
+ * Settings 操作结果
+ */
+export interface SettingsOperationResult {
+  success: boolean;
+  message?: string;
+  endpoint?: EndpointSettings;
+  filePath?: string;
+}
+
+/**
+ * 创建/更新端点请求
+ */
+export interface SaveEndpointRequest {
+  id?: string;
+  name: string;
+  description?: string;
+  settings: ClaudeCliSettings;
+  enabled?: boolean;
+}
+
+/**
+ * 从 LiteLLM Provider 映射到 Claude CLI env
+ */
+export function mapProviderToClaudeEnv(provider: {
+  apiKey?: string;
+  apiBase?: string;
+}): ClaudeCliSettings['env'] {
+  const env: ClaudeCliSettings['env'] = {};
+
+  if (provider.apiKey) {
+    env.ANTHROPIC_AUTH_TOKEN = provider.apiKey;
+  }
+  if (provider.apiBase) {
+    env.ANTHROPIC_BASE_URL = provider.apiBase;
+  }
+  // 默认禁用自动更新
+  env.DISABLE_AUTOUPDATER = '1';
+
+  return env;
+}
+
+/**
+ * 创建默认 Settings
+ */
+export function createDefaultSettings(): ClaudeCliSettings {
+  return {
+    env: {
+      DISABLE_AUTOUPDATER: '1'
+    },
+    model: 'sonnet',
+    includeCoAuthoredBy: false
+  };
+}
+
+/**
+ * 验证 Settings 格式
+ */
+export function validateSettings(settings: unknown): settings is ClaudeCliSettings {
+  if (!settings || typeof settings !== 'object') {
+    return false;
+  }
+
+  const s = settings as Record<string, unknown>;
+
+  // env 必须存在且为对象
+  if (!s.env || typeof s.env !== 'object') {
+    return false;
+  }
+
+  // model 可选，但如果存在必须是字符串
+  if (s.model !== undefined && typeof s.model !== 'string') {
+    return false;
+  }
+
+  // includeCoAuthoredBy 可选，但如果存在必须是布尔值
+  if (s.includeCoAuthoredBy !== undefined && typeof s.includeCoAuthoredBy !== 'boolean') {
+    return false;
+  }
+
+  return true;
+}

package/ccw/src/types/litellm-api-config.ts

@@ -109,6 +109,9 @@ export interface ApiKeyEntry {
 
   /** Error message if unhealthy */
   lastError?: string;
+
+  /** Last recorded latency in milliseconds */
+  lastLatencyMs?: number;
 }
 
 /**
@@ -226,6 +229,9 @@ export interface ProviderCredential {
   /** Embedding models configured for this provider */
   embeddingModels?: ModelDefinition[];
 
+  /** Reranker models configured for this provider */
+  rerankerModels?: ModelDefinition[];
+
   /** Creation timestamp (ISO 8601) */
   createdAt: string;
 
@@ -350,6 +356,7 @@ export interface CodexLensEmbeddingRotation {
 /**
  * Generic embedding pool configuration (refactored from CodexLensEmbeddingRotation)
  * Supports automatic discovery of all providers offering a specific model
+ * @deprecated Use ModelPoolConfig instead
  */
 export interface EmbeddingPoolConfig {
   /** Whether embedding pool is enabled */
@@ -374,6 +381,50 @@ export interface EmbeddingPoolConfig {
   defaultMaxConcurrentPerKey: number;
 }
 
+/**
+ * Model type for pool configuration
+ */
+export type ModelPoolType = 'embedding' | 'llm' | 'reranker';
+
+/**
+ * Individual model pool configuration
+ * Supports embedding, LLM, and reranker models with high availability
+ */
+export interface ModelPoolConfig {
+  /** Unique identifier for this pool */
+  id: string;
+
+  /** Model type: embedding, llm, or reranker */
+  modelType: ModelPoolType;
+
+  /** Whether this pool is enabled */
+  enabled: boolean;
+
+  /** Target model name (e.g., "text-embedding-3-small", "gpt-4o") */
+  targetModel: string;
+
+  /** Selection strategy: round_robin, latency_aware, weighted_random */
+  strategy: 'round_robin' | 'latency_aware' | 'weighted_random';
+
+  /** Whether to automatically discover all providers offering targetModel */
+  autoDiscover: boolean;
+
+  /** Provider IDs to exclude from auto-discovery (optional) */
+  excludedProviderIds?: string[];
+
+  /** Default cooldown seconds for rate-limited endpoints (default: 60) */
+  defaultCooldown: number;
+
+  /** Default maximum concurrent requests per key (default: 4) */
+  defaultMaxConcurrentPerKey: number;
+
+  /** Optional display name for this pool */
+  name?: string;
+
+  /** Optional description */
+  description?: string;
+}
+
 /**
  * Complete LiteLLM API configuration
  * Root configuration object stored in JSON file
@@ -397,6 +448,9 @@ export interface LiteLLMApiConfig {
   /** CodexLens multi-provider embedding rotation config (deprecated, use embeddingPoolConfig) */
   codexlensEmbeddingRotation?: CodexLensEmbeddingRotation;
 
-  /** Generic embedding pool configuration with auto-discovery support */
+  /** Generic embedding pool configuration with auto-discovery support (deprecated, use modelPools) */
   embeddingPoolConfig?: EmbeddingPoolConfig;
+
+  /** Multi-model pool configurations (supports embedding, LLM, reranker) */
+  modelPools?: ModelPoolConfig[];
 }

package/ccw/src/utils/exec-constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Centralized timeout defaults for synchronous process execution.
+ *
+ * `execSync` blocks the Node.js event loop. Always provide a timeout so callers
+ * fail fast instead of hanging indefinitely when external tools stall.
+ *
+ * Guidance:
+ * - Use `GIT_QUICK` for lightweight git queries (rev-parse, status).
+ * - Use `GIT_DIFF` for diff-based queries.
+ * - Use `GIT_LOG` for log/history queries.
+ * - Use `PYTHON_VERSION` for `python --version` style probes.
+ * - Use `SYSTEM_INFO` for OS/hardware capability probes (wmic, nvidia-smi, which/where).
+ * - Use `PROCESS_SPAWN` for short-lived spawn-style operations.
+ * - Use `PACKAGE_INSTALL` for package manager operations that may take minutes.
+ */
+export const EXEC_TIMEOUTS = {
+  GIT_QUICK: 5_000,
+  GIT_DIFF: 10_000,
+  GIT_LOG: 15_000,
+  PYTHON_VERSION: 5_000,
+  SYSTEM_INFO: 10_000,
+  PROCESS_SPAWN: 30_000,
+  PACKAGE_INSTALL: 300_000,
+} as const;

package/ccw/src/utils/path-resolver.ts

@@ -23,6 +23,7 @@ export interface ValidatePathOptions {
 
 /**
  * Resolve a path, handling ~ for home directory
+ * Also handles Windows drive-relative paths (e.g., "D:path" -> "D:\path")
  * @param inputPath - Path to resolve
  * @returns Absolute path
  */
@@ -34,6 +35,17 @@ export function resolvePath(inputPath: string): string {
     return join(homedir(), inputPath.slice(1));
   }
 
+  // Handle Windows drive-relative paths (e.g., "D:path" without backslash)
+  // Pattern: single letter followed by colon, then immediately a non-slash character
+  // This converts "D:path" to "D:\path" to make it absolute
+  if (process.platform === 'win32' || /^[a-zA-Z]:/.test(inputPath)) {
+    const driveRelativeMatch = inputPath.match(/^([a-zA-Z]:)([^/\\].*)$/);
+    if (driveRelativeMatch) {
+      // Insert backslash after drive letter
+      inputPath = driveRelativeMatch[1] + '\\' + driveRelativeMatch[2];
+    }
+  }
+
   return resolve(inputPath);
 }
 
@@ -69,6 +81,21 @@ export function validatePath(inputPath: string, options: ValidatePathOptions = {
     return { valid: false, path: null, error: `Invalid path: ${message}` };
   }
 
+  // Check if within base directory when specified (pre-symlink resolution)
+  const resolvedBase = baseDir ? resolvePath(baseDir) : null;
+  if (resolvedBase) {
+    const relativePath = relative(resolvedBase, resolvedPath);
+
+    // Path traversal detection: relative path should not start with '..'
+    if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+      return {
+        valid: false,
+        path: null,
+        error: `Path must be within ${resolvedBase}`
+      };
+    }
+  }
+
   // Check if path exists when required
   if (mustExist && !existsSync(resolvedPath)) {
     return { valid: false, path: null, error: `Path does not exist: ${resolvedPath}` };
@@ -83,11 +110,30 @@ export function validatePath(inputPath: string, options: ValidatePathOptions = {
       const message = err instanceof Error ? err.message : String(err);
       return { valid: false, path: null, error: `Cannot resolve path: ${message}` };
     }
+  } else if (resolvedBase) {
+    // For non-existent paths, resolve the nearest existing ancestor to prevent symlink-based escapes
+    // (e.g., baseDir/link/newfile where baseDir/link is a symlink to a disallowed location).
+    let existingPath = resolvedPath;
+    while (!existsSync(existingPath)) {
+      const parent = resolve(existingPath, '..');
+      if (parent === existingPath) break;
+      existingPath = parent;
+    }
+
+    if (existsSync(existingPath)) {
+      try {
+        const realExisting = realpathSync(existingPath);
+        const remainder = relative(existingPath, resolvedPath);
+        realPath = remainder && remainder !== '.' ? join(realExisting, remainder) : realExisting;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { valid: false, path: null, error: `Cannot resolve path: ${message}` };
+      }
+    }
   }
 
-  // Check if within base directory when specified
-  if (baseDir) {
-    const resolvedBase = resolvePath(baseDir);
+  // Check if within base directory when specified (post-symlink resolution)
+  if (resolvedBase) {
     const relativePath = relative(resolvedBase, realPath);
 
     // Path traversal detection: relative path should not start with '..'

package/ccw/src/utils/path-validator.ts

@@ -7,7 +7,7 @@
  * Inspired by MCP filesystem server's security model.
  */
 
-import { resolve, isAbsolute, normalize, relative } from 'path';
+import { resolve, isAbsolute, normalize, relative, sep } from 'path';
 import { realpath, access } from 'fs/promises';
 import { constants } from 'fs';
 
@@ -42,6 +42,27 @@ export function normalizePath(p: string): string {
   return normalize(p).replace(/\\/g, '/');
 }
 
+function canonicalizeForComparison(p: string): string {
+  const base = getProjectRoot();
+  const absolute = isAbsolute(p) ? p : resolve(base, p);
+  let canonical = normalize(absolute);
+
+  // Remove trailing separators (except drive roots like C:\ and posix root /)
+  canonical = canonical.replace(/[\\/]+$/, '');
+  if (/^[a-zA-Z]:$/.test(canonical)) {
+    canonical += sep;
+  } else if (canonical === '') {
+    canonical = sep;
+  }
+
+  // Windows paths are case-insensitive.
+  if (process.platform === 'win32') {
+    canonical = canonical.toLowerCase();
+  }
+
+  return canonical;
+}
+
 /**
  * Check if path is within allowed directories
  */
@@ -49,12 +70,13 @@ export function isPathWithinAllowedDirectories(
   targetPath: string,
   allowedDirectories: string[]
 ): boolean {
-  const normalizedTarget = normalizePath(targetPath);
+  const canonicalTarget = canonicalizeForComparison(targetPath);
   return allowedDirectories.some(dir => {
-    const normalizedDir = normalizePath(dir);
-    // Check if path equals or starts with allowed directory
-    return normalizedTarget === normalizedDir ||
-           normalizedTarget.startsWith(normalizedDir + '/');
+    const canonicalDir = canonicalizeForComparison(dir);
+    if (canonicalTarget === canonicalDir) return true;
+
+    const boundary = canonicalDir.endsWith(sep) ? canonicalDir : canonicalDir + sep;
+    return canonicalTarget.startsWith(boundary);
   });
 }
 

package/ccw/src/utils/python-utils.ts

@@ -1,121 +1,140 @@
-/**
- * Python detection and version compatibility utilities
- * Shared module for consistent Python discovery across the application
- */
-
-import { execSync } from 'child_process';
-
-/**
- * Parse Python version string to major.minor numbers
- * @param versionStr - Version string like "Python 3.11.5"
- * @returns Object with major and minor version numbers, or null if parsing fails
- */
-export function parsePythonVersion(versionStr: string): { major: number; minor: number } | null {
-  const match = versionStr.match(/Python\s+(\d+)\.(\d+)/);
-  if (match) {
-    return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10) };
-  }
-  return null;
-}
-
-/**
- * Check if Python version is compatible with onnxruntime (3.9-3.12)
- * @param major - Major version number
- * @param minor - Minor version number
- * @returns true if compatible
- */
-export function isPythonVersionCompatible(major: number, minor: number): boolean {
-  // onnxruntime currently supports Python 3.9-3.12
-  return major === 3 && minor >= 9 && minor <= 12;
-}
-
-/**
- * Detect available Python 3 executable
- * Supports CCW_PYTHON environment variable for custom Python path
- * On Windows, uses py launcher to find compatible versions
- * @returns Python executable command
- */
-export function getSystemPython(): string {
-  // Check for user-specified Python via environment variable
-  const customPython = process.env.CCW_PYTHON;
-  if (customPython) {
-    try {
-      const version = execSync(`"${customPython}" --version 2>&1`, { encoding: 'utf8' });
-      if (version.includes('Python 3')) {
-        const parsed = parsePythonVersion(version);
-        if (parsed && !isPythonVersionCompatible(parsed.major, parsed.minor)) {
-          console.warn(`[Python] Warning: CCW_PYTHON points to Python ${parsed.major}.${parsed.minor}, which may not be compatible with onnxruntime (requires 3.9-3.12)`);
-        }
-        return `"${customPython}"`;
-      }
-    } catch {
-      console.warn(`[Python] Warning: CCW_PYTHON="${customPython}" is not a valid Python executable, falling back to system Python`);
-    }
-  }
-
-  // On Windows, try py launcher with specific versions first (3.12, 3.11, 3.10, 3.9)
-  if (process.platform === 'win32') {
-    const compatibleVersions = ['3.12', '3.11', '3.10', '3.9'];
-    for (const ver of compatibleVersions) {
-      try {
-        const version = execSync(`py -${ver} --version 2>&1`, { encoding: 'utf8' });
-        if (version.includes(`Python ${ver}`)) {
-          console.log(`[Python] Found compatible Python ${ver} via py launcher`);
-          return `py -${ver}`;
-        }
-      } catch {
-        // Version not installed, try next
-      }
-    }
-  }
-
-  const commands = process.platform === 'win32' ? ['python', 'py', 'python3'] : ['python3', 'python'];
-  let fallbackCmd: string | null = null;
-  let fallbackVersion: { major: number; minor: number } | null = null;
-
-  for (const cmd of commands) {
-    try {
-      const version = execSync(`${cmd} --version 2>&1`, { encoding: 'utf8' });
-      if (version.includes('Python 3')) {
-        const parsed = parsePythonVersion(version);
-        if (parsed) {
-          // Prefer compatible version (3.9-3.12)
-          if (isPythonVersionCompatible(parsed.major, parsed.minor)) {
-            return cmd;
-          }
-          // Keep track of first Python 3 found as fallback
-          if (!fallbackCmd) {
-            fallbackCmd = cmd;
-            fallbackVersion = parsed;
-          }
-        }
-      }
-    } catch {
-      // Try next command
-    }
-  }
-
-  // If no compatible version found, use fallback with warning
-  if (fallbackCmd && fallbackVersion) {
-    console.warn(`[Python] Warning: Only Python ${fallbackVersion.major}.${fallbackVersion.minor} found, which may not be compatible with onnxruntime (requires 3.9-3.12).`);
-    console.warn('[Python] To use a specific Python version, set CCW_PYTHON environment variable:');
-    console.warn('  Windows: set CCW_PYTHON=C:\\path\\to\\python.exe');
-    console.warn('  Unix: export CCW_PYTHON=/path/to/python3.11');
-    console.warn('[Python] Alternatively, use LiteLLM embedding backend which has no Python version restrictions.');
-    return fallbackCmd;
-  }
-
-  throw new Error('Python 3 not found. Please install Python 3.9-3.12 and ensure it is in PATH, or set CCW_PYTHON environment variable.');
-}
-
-/**
- * Get the Python command for pip operations (uses -m pip for reliability)
- * @returns Array of command arguments for spawn
- */
-export function getPipCommand(): { pythonCmd: string; pipArgs: string[] } {
-  const pythonCmd = getSystemPython();
-  return {
-    pythonCmd,
-    pipArgs: ['-m', 'pip']
-  };
-}
+/**
+ * Python detection and version compatibility utilities
+ * Shared module for consistent Python discovery across the application
+ */
+
+import { execSync } from 'child_process';
+import { EXEC_TIMEOUTS } from './exec-constants.js';
+
+function isExecTimeoutError(error: unknown): boolean {
+  const err = error as { code?: unknown; errno?: unknown; message?: unknown } | null;
+  const code = err?.code ?? err?.errno;
+  if (code === 'ETIMEDOUT') return true;
+  const message = typeof err?.message === 'string' ? err.message : '';
+  return message.includes('ETIMEDOUT');
+}
+
+/**
+ * Parse Python version string to major.minor numbers
+ * @param versionStr - Version string like "Python 3.11.5"
+ * @returns Object with major and minor version numbers, or null if parsing fails
+ */
+export function parsePythonVersion(versionStr: string): { major: number; minor: number } | null {
+  const match = versionStr.match(/Python\s+(\d+)\.(\d+)/);
+  if (match) {
+    return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10) };
+  }
+  return null;
+}
+
+/**
+ * Check if Python version is compatible with onnxruntime (3.9-3.12)
+ * @param major - Major version number
+ * @param minor - Minor version number
+ * @returns true if compatible
+ */
+export function isPythonVersionCompatible(major: number, minor: number): boolean {
+  // onnxruntime currently supports Python 3.9-3.12
+  return major === 3 && minor >= 9 && minor <= 12;
+}
+
+/**
+ * Detect available Python 3 executable
+ * Supports CCW_PYTHON environment variable for custom Python path
+ * On Windows, uses py launcher to find compatible versions
+ * @returns Python executable command
+ */
+export function getSystemPython(): string {
+  // Check for user-specified Python via environment variable
+  const customPython = process.env.CCW_PYTHON;
+  if (customPython) {
+    try {
+      const version = execSync(`"${customPython}" --version 2>&1`, { encoding: 'utf8', timeout: EXEC_TIMEOUTS.PYTHON_VERSION });
+      if (version.includes('Python 3')) {
+        const parsed = parsePythonVersion(version);
+        if (parsed && !isPythonVersionCompatible(parsed.major, parsed.minor)) {
+          console.warn(`[Python] Warning: CCW_PYTHON points to Python ${parsed.major}.${parsed.minor}, which may not be compatible with onnxruntime (requires 3.9-3.12)`);
+        }
+        return `"${customPython}"`;
+      }
+    } catch (err: unknown) {
+      if (isExecTimeoutError(err)) {
+        console.warn(`[Python] Warning: CCW_PYTHON version check timed out after ${EXEC_TIMEOUTS.PYTHON_VERSION}ms, falling back to system Python`);
+      } else {
+        console.warn(`[Python] Warning: CCW_PYTHON="${customPython}" is not a valid Python executable, falling back to system Python`);
+      }
+    }
+  }
+
+  // On Windows, try py launcher with specific versions first (3.12, 3.11, 3.10, 3.9)
+  if (process.platform === 'win32') {
+    const compatibleVersions = ['3.12', '3.11', '3.10', '3.9'];
+    for (const ver of compatibleVersions) {
+      try {
+        const version = execSync(`py -${ver} --version 2>&1`, { encoding: 'utf8', timeout: EXEC_TIMEOUTS.PYTHON_VERSION });
+        if (version.includes(`Python ${ver}`)) {
+          console.log(`[Python] Found compatible Python ${ver} via py launcher`);
+          return `py -${ver}`;
+        }
+      } catch (err: unknown) {
+        if (isExecTimeoutError(err)) {
+          console.warn(`[Python] Warning: py -${ver} version check timed out after ${EXEC_TIMEOUTS.PYTHON_VERSION}ms`);
+        }
+        // Version not installed, try next
+      }
+    }
+  }
+
+  const commands = process.platform === 'win32' ? ['python', 'py', 'python3'] : ['python3', 'python'];
+  let fallbackCmd: string | null = null;
+  let fallbackVersion: { major: number; minor: number } | null = null;
+
+  for (const cmd of commands) {
+    try {
+      const version = execSync(`${cmd} --version 2>&1`, { encoding: 'utf8', timeout: EXEC_TIMEOUTS.PYTHON_VERSION });
+      if (version.includes('Python 3')) {
+        const parsed = parsePythonVersion(version);
+        if (parsed) {
+          // Prefer compatible version (3.9-3.12)
+          if (isPythonVersionCompatible(parsed.major, parsed.minor)) {
+            return cmd;
+          }
+          // Keep track of first Python 3 found as fallback
+          if (!fallbackCmd) {
+            fallbackCmd = cmd;
+            fallbackVersion = parsed;
+          }
+        }
+      }
+    } catch (err: unknown) {
+      if (isExecTimeoutError(err)) {
+        console.warn(`[Python] Warning: ${cmd} --version timed out after ${EXEC_TIMEOUTS.PYTHON_VERSION}ms`);
+      }
+      // Try next command
+    }
+  }
+
+  // If no compatible version found, use fallback with warning
+  if (fallbackCmd && fallbackVersion) {
+    console.warn(`[Python] Warning: Only Python ${fallbackVersion.major}.${fallbackVersion.minor} found, which may not be compatible with onnxruntime (requires 3.9-3.12).`);
+    console.warn('[Python] To use a specific Python version, set CCW_PYTHON environment variable:');
+    console.warn('  Windows: set CCW_PYTHON=C:\\path\\to\\python.exe');
+    console.warn('  Unix: export CCW_PYTHON=/path/to/python3.11');
+    console.warn('[Python] Alternatively, use LiteLLM embedding backend which has no Python version restrictions.');
+    return fallbackCmd;
+  }
+
+  throw new Error('Python 3 not found. Please install Python 3.9-3.12 and ensure it is in PATH, or set CCW_PYTHON environment variable.');
+}
+
+/**
+ * Get the Python command for pip operations (uses -m pip for reliability)
+ * @returns Array of command arguments for spawn
+ */
+export function getPipCommand(): { pythonCmd: string; pipArgs: string[] } {
+  const pythonCmd = getSystemPython();
+  return {
+    pythonCmd,
+    pipArgs: ['-m', 'pip']
+  };
+}