@hunyed15/codecgc 0.2.2 → 0.2.5

package/codecgc/templates/project/claude/hooks/edit-guard.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// CodeCGC Edit Guard — PreToolUse hook (Edit|Write|MultiEdit)
+// Routes file edits through model-routing.yaml policy.
+// Zero external dependencies. Never crashes (try/catch -> exit(0)).
+
+'use strict';
+
+try {
+  var fs = require('fs');
+  var path = require('path');
+
+  // ── Read stdin ──
+  var inputData = '';
+  if (!process.stdin.isTTY) {
+    inputData = fs.readFileSync(0, 'utf-8');
+  }
+  if (!inputData.trim()) {
+    process.exit(0);
+  }
+
+  var parsed = JSON.parse(inputData);
+  var toolInput = parsed.tool_input || parsed.input || parsed;
+  var toolName = (parsed.tool_name || '').trim();
+  var filePath = (toolInput.file_path || toolInput.path || '').trim();
+
+  if (!filePath) {
+    process.exit(0);
+  }
+
+  // ── Find routing file ──
+  var cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  var routingPath = path.join(cwd, 'model-routing.yaml');
+
+  if (!fs.existsSync(routingPath)) {
+    process.exit(0);
+  }
+
+  // ── Parse YAML (simple, handles model-routing.yaml structure) ──
+  var routingContent = fs.readFileSync(routingPath, 'utf-8');
+  var sections = parseSimpleYaml(routingContent);
+
+  // ── Classify path ──
+  var normalizedPath = normalizePath(filePath, cwd);
+  var owner = classifyPath(normalizedPath, sections);
+
+  // ── Decide ──
+  if (owner === 'orchestration' || owner === 'docs') {
+    process.exit(0);
+  }
+
+  var ownerLabel = owner || 'unknown';
+  var reason = 'CodeCGC: ' + ownerLabel + ' paths should be routed through /cgc (Codex for backend, Gemini for frontend).';
+  if (ownerLabel === 'unknown') {
+    reason = 'CodeCGC: path is not covered by model-routing.yaml. Add it to the appropriate section or route through /cgc.';
+  }
+  if (ownerLabel === 'shared') {
+    reason = 'CodeCGC: shared paths require split-first routing. Use /cgc to split into backend/frontend steps.';
+  }
+
+  console.log(JSON.stringify({
+    decision: 'deny',
+    reason: reason
+  }));
+} catch {
+  process.exit(0);
+}
+
+// ── Helpers ──
+
+function normalizePath(filePath, cwd) {
+  var p = filePath.replace(/\\/g, '/');
+  if (path.isAbsolute(filePath)) {
+    try {
+      p = path.relative(cwd, filePath).replace(/\\/g, '/');
+    } catch { /* keep original */ }
+  }
+  while (p.startsWith('./')) {
+    p = p.slice(2);
+  }
+  return p;
+}
+
+function parseSimpleYaml(content) {
+  var sections = {};
+  var currentKey = null;
+  var lines = content.split('\n');
+
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i];
+    // Skip empty lines and comments
+    if (!line.trim() || line.trim().charAt(0) === '#') continue;
+
+    // Top-level key (no leading whitespace, ends with :)
+    if (line.charAt(0) !== ' ' && line.charAt(0) !== '\t' && line.indexOf(':') > 0) {
+      currentKey = line.split(':')[0].trim();
+      if (!sections[currentKey]) sections[currentKey] = [];
+      continue;
+    }
+
+    if (!currentKey) continue;
+
+    var trimmed = line.trim();
+
+    // Nested key under current section (e.g. "frontend:" under "test_paths:")
+    // Check if line has indentation + is a key (contains : but is not a list item)
+    var indent = line.length - line.replace(/^(\s*)/, '').length;
+    if (indent > 0 && trimmed.indexOf(':') > 0 && trimmed.charAt(0) !== '-') {
+      var subKey = trimmed.split(':')[0].trim();
+      var compoundKey = currentKey + '_' + subKey;
+      if (!sections[compoundKey]) sections[compoundKey] = [];
+      // Point currentKey to compound key so subsequent list items go there
+      currentKey = compoundKey;
+      continue;
+    }
+
+    // List item (indented, starts with -)
+    if (trimmed.charAt(0) === '-') {
+      var value = trimmed.slice(1).trim();
+      // Strip quotes
+      if ((value.charAt(0) === '"' && value.charAt(value.length - 1) === '"')
+        || (value.charAt(0) === "'" && value.charAt(value.length - 1) === "'")) {
+        value = value.slice(1, -1);
+      }
+      if (value) {
+        sections[currentKey].push(value);
+      }
+    }
+  }
+
+  return sections;
+}
+
+function classifyPath(normalizedPath, sections) {
+  // Order matters: shared first, then orchestration, docs, tests, frontend, backend
+  var groups = [
+    ['shared', sections['shared_paths'] || []],
+    ['orchestration', sections['orchestration_paths'] || []],
+    ['docs', sections['docs_paths'] || []],
+    ['frontend-test', sections['test_paths_frontend'] || []],
+    ['backend-test', sections['test_paths_backend'] || []],
+    ['frontend', sections['frontend_paths'] || []],
+    ['backend', sections['backend_paths'] || []]
+  ];
+
+  for (var i = 0; i < groups.length; i++) {
+    var owner = groups[i][0];
+    var patterns = groups[i][1];
+    if (matchesAny(normalizedPath, patterns)) {
+      return owner;
+    }
+  }
+  return 'unknown';
+}
+
+function matchesAny(filePath, patterns) {
+  for (var i = 0; i < patterns.length; i++) {
+    if (globMatch(filePath, patterns[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function globMatch(filePath, pattern) {
+  var regex = globToRegex(pattern);
+  return regex.test(filePath);
+}
+
+function globToRegex(pattern) {
+  var regexStr = '^';
+  var i = 0;
+  while (i < pattern.length) {
+    var ch = pattern.charAt(i);
+    if (ch === '*' && i + 1 < pattern.length && pattern.charAt(i + 1) === '*') {
+      // ** matches everything
+      regexStr += '.*';
+      i += 2;
+      // skip trailing / if present
+      if (i < pattern.length && pattern.charAt(i) === '/') i++;
+    } else if (ch === '*') {
+      // * matches anything except /
+      regexStr += '[^/]*';
+      i++;
+    } else if (ch === '.') {
+      regexStr += '\\.';
+      i++;
+    } else {
+      regexStr += ch;
+      i++;
+    }
+  }
+  regexStr += '$';
+  return new RegExp(regexStr);
+}

package/codecgc/templates/project/claude/settings.local.json

@@ -3,10 +3,23 @@
     "allow": [
       "WebSearch",
       "Read(**)",
-      "Edit(**)",
-      "Update(**)",
-      "Write(**)",
-      "mcp__*",
+      "Edit(codecgc/**)",
+      "Edit(.claude/**)",
+      "Edit(.mcp.json)",
+      "Edit(model-routing.yaml)",
+      "Edit(README.md)",
+      "Edit(docs/**)",
+      "Edit(CHANGELOG.md)",
+      "Write(codecgc/**)",
+      "Write(.claude/**)",
+      "Write(.mcp.json)",
+      "Write(model-routing.yaml)",
+      "Write(README.md)",
+      "Write(docs/**)",
+      "Write(CHANGELOG.md)",
+      "mcp__codecgc__*",
+      "mcp__codex__*",
+      "mcp__gemini__*",
       "Bash(*)",
       "PowerShell(*)"
     ]

package/mcp/codexmcp/src/codexmcp/server.py

@@ -20,8 +20,10 @@ import shutil
 
 mcp = FastMCP("Codex MCP Server-from guda.studio")
 
+DEFAULT_CODEX_TIMEOUT_SECONDS = 600
+
 # Mirror of model-routing.yaml frontend_paths — keep these hints in sync with
-# route-edit.ps1 and geminimcp/server.py BACKEND_PATH_HINTS.
+# edit-guard.js and geminimcp/server.py BACKEND_PATH_HINTS.
 FRONTEND_PATH_HINTS = (
     "apps/web/",
     "src/components/",
@@ -177,7 +179,25 @@ def _validate_backend_target_paths(target_paths: List[Path]) -> tuple[bool, List
     return True, policy_checks, ""
 
 
-def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
+def _terminate_process_tree(process: subprocess.Popen[str]) -> None:
+    """Terminate a process and its children best-effort."""
+    if process.poll() is not None:
+        return
+
+    if os.name == "nt":
+        subprocess.run(
+            ["taskkill", "/PID", str(process.pid), "/T", "/F"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        return
+
+    process.kill()
+
+
+def run_shell_command(cmd: list[str], timeout_seconds: int = DEFAULT_CODEX_TIMEOUT_SECONDS) -> Generator[str, None, None]:
     """Execute a command and stream its output line-by-line.
 
     Args:
@@ -204,6 +224,8 @@ def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
 
     output_queue: queue.Queue[str | None] = queue.Queue()
     GRACEFUL_SHUTDOWN_DELAY = 0.3
+    started_at = time.monotonic()
+    timed_out = False
 
     def is_turn_completed(line: str) -> bool:
         """Check if the line indicates turn completion via JSON parsing."""
@@ -237,13 +259,17 @@ def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
                 break
             yield line
         except queue.Empty:
+            if timeout_seconds > 0 and time.monotonic() - started_at > timeout_seconds:
+                timed_out = True
+                _terminate_process_tree(process)
+                break
             if process.poll() is not None and not thread.is_alive():
                 break
 
     try:
         process.wait(timeout=5)
     except subprocess.TimeoutExpired:
-        process.kill()
+        _terminate_process_tree(process)
         process.wait()
     thread.join(timeout=5)
 
@@ -255,6 +281,13 @@ def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
         except queue.Empty:
             break
 
+    if timed_out:
+        raise TimeoutError(
+            f"Codex CLI timed out after {timeout_seconds} seconds. "
+            "This usually means the CLI was waiting for interactive approval, "
+            "network/authentication, or a long-running tool call."
+        )
+
 
 def _execute_codex_session(
     *,
@@ -268,6 +301,7 @@ def _execute_codex_session(
     model: str,
     yolo: bool,
     profile: str,
+    timeout_seconds: int = DEFAULT_CODEX_TIMEOUT_SECONDS,
 ) -> Dict[str, Any]:
     """Execute Codex CLI and return the parsed MCP response payload."""
     if not cd.exists():
@@ -310,7 +344,7 @@ def _execute_codex_session(
     err_message = ""
     thread_id: Optional[str] = None
 
-    for line in run_shell_command(cmd):
+    for line in run_shell_command(cmd, timeout_seconds):
         try:
             line_dict = json.loads(line.strip())
             all_messages.append(line_dict)

package/mcp/geminimcp/src/geminimcp/server.py

@@ -25,7 +25,7 @@ PROJECT_GEMINI_POLICY_RELATIVE_PATH = Path(".gemini") / "policies" / "codecgc-po
 mcp = FastMCP("Gemini MCP Server-from guda.studio")
 
 # Mirror of model-routing.yaml backend_paths — keep these hints in sync with
-# route-edit.ps1 and codexmcp/server.py FRONTEND_PATH_HINTS.
+# edit-guard.js and codexmcp/server.py FRONTEND_PATH_HINTS.
 BACKEND_PATH_HINTS = (
     "apps/api/",
     "server/",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunyed15/codecgc",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "Claude-hosted multi-model workflow product shell for CodeCGC.",
   "license": "MIT",
   "type": "commonjs",
@@ -10,6 +10,7 @@
     "cgc-init": "bin/cgc-init.js",
     "cgc-status": "bin/cgc-status.js",
     "cgc-doctor": "bin/cgc-doctor.js",
+    "cgc-explain": "bin/cgc-explain.js",
     "cgc-package-audit": "bin/cgc-package-audit.js",
     "cgc-external-audit": "bin/cgc-external-audit.js",
     "cgc-external-status": "bin/cgc-external-status.js",
@@ -47,7 +48,7 @@
     "scripts/codecgc_runtime/*.py",
     "scripts/postinstall_codecgc.js",
     "scripts/README-codecgc-cli.md",
-    ".claude/hooks/route-edit.ps1",
+    ".claude/hooks/edit-guard.js",
     "codecgc/cgc/",
     "codecgc/cgc-arch/",
     "codecgc/cgc-build/",

package/scripts/audit_codecgc_package_runtime.py

@@ -23,7 +23,7 @@ RUNTIME_ENTRYPOINTS = [
 ]
 
 RUNTIME_STATIC_REQUIREMENTS = [
-    ".claude/hooks/route-edit.ps1",
+    ".claude/hooks/edit-guard.js",
     "codecgc/templates/project/claude/settings.local.json",
     "codecgc/templates/project/codex/codecgcrc.json",
     "codecgc/templates/project/gemini/policies/codecgc-policy.toml",

package/scripts/codecgc_error_catalog.py

@@ -0,0 +1,172 @@
+"""Error code classification and explanation for CodeCGC.
+
+Provides human-readable explanations and actionable suggestions for common error scenarios.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+# Error code to explanation mapping
+ERROR_CATALOG: dict[str, dict[str, str]] = {
+    "executor-crash": {
+        "title": "执行器内部异常",
+        "description": "执行器脚本在运行过程中异常退出，未能完成任务。",
+        "common_causes": [
+            "执行器环境配置不完整（缺少依赖、路径错误）",
+            "执行器超时或资源不足",
+            "执行器内部代码错误",
+        ],
+        "suggestions": [
+            "运行 cgc-doctor 检查执行器环境配置",
+            "查看审计文件中的详细错误日志",
+            "如果持续失败，尝试重新安装：cgc-init",
+        ],
+    },
+    "executor-failure": {
+        "title": "执行器任务失败",
+        "description": "执行器正常运行，但任务执行失败（如代码生成失败、测试未通过）。",
+        "common_causes": [
+            "目标路径不存在或不可访问",
+            "任务契约与实际代码不匹配",
+            "执行器返回的结果格式不正确",
+        ],
+        "suggestions": [
+            "检查审计文件中的执行器输出",
+            "确认目标路径在工作区中存在",
+            "如果是路径问题，回到 cgc-plan 修正步骤契约",
+        ],
+    },
+    "scope-error": {
+        "title": "任务范围错误",
+        "description": "当前步骤包含多个执行器归属的路径，需要拆分。",
+        "common_causes": [
+            "一个步骤同时包含前端和后端路径",
+            "一个步骤包含 shared 或 unknown 路径",
+        ],
+        "suggestions": [
+            "运行 cgc-plan 查看拆分建议",
+            "按执行器归属（frontend/backend）拆分成独立步骤",
+            "shared 路径需要先明确归属或单独处理",
+        ],
+    },
+    "design-gap": {
+        "title": "设计缺口",
+        "description": "当前步骤引用的路径或配置在路由策略中未覆盖，或目标文件不存在。",
+        "common_causes": [
+            "目标路径在 model-routing.yaml 中未定义",
+            "目标文件在工作区中不存在",
+            "路由规则与实际项目结构不匹配",
+        ],
+        "suggestions": [
+            "检查 model-routing.yaml 是否覆盖目标路径",
+            "确认目标文件在工作区中存在",
+            "回到 cgc-plan 修正目标路径或步骤契约",
+        ],
+    },
+    "environment-or-tooling": {
+        "title": "环境或工具问题",
+        "description": "执行器环境、依赖或外部工具不可用。",
+        "common_causes": [
+            "执行器 CLI 未安装或不在 PATH 中",
+            "执行器超时（网络、认证、长时间运行）",
+            "缺少必需的依赖或配置文件",
+        ],
+        "suggestions": [
+            "运行 cgc-doctor 检查执行器可用性",
+            "检查网络连接和认证状态",
+            "确认执行器 CLI 已正确安装",
+        ],
+    },
+    "workflow-state": {
+        "title": "工作流状态不满足",
+        "description": "当前工作流状态不允许执行请求的操作。",
+        "common_causes": [
+            "尝试执行 build/fix/test，但工作流还在 needs-planning 状态",
+            "尝试 review，但没有可审核的执行结果",
+            "工作流已关闭，但尝试继续执行",
+        ],
+        "suggestions": [
+            "运行 cgc-route 查看当前工作流状态和推荐命令",
+            "按推荐命令顺序执行（plan → build/fix → review）",
+            "如果工作流已关闭，使用 /cgc 开始新的工作流",
+        ],
+    },
+    "returned-to-planning": {
+        "title": "返回规划阶段",
+        "description": "执行器发现问题，需要回到规划阶段修正。",
+        "common_causes": [
+            "任务范围需要拆分（scope-error）",
+            "目标路径或契约有设计缺口（design-gap）",
+        ],
+        "suggestions": [
+            "运行 cgc-plan 查看问题详情和修正建议",
+            "根据建议修正步骤契约或拆分步骤",
+            "修正后重新执行 build/fix",
+        ],
+    },
+}
+
+
+def explain_error(error_code: str) -> dict[str, Any]:
+    """Get explanation for an error code.
+
+    Args:
+        error_code: Error code from failure_type field
+
+    Returns:
+        Dict with title, description, common_causes, and suggestions
+    """
+    if error_code not in ERROR_CATALOG:
+        return {
+            "error_code": error_code,
+            "title": "未知错误类型",
+            "description": f"错误代码 '{error_code}' 未在错误分类表中定义。",
+            "common_causes": [],
+            "suggestions": [
+                "查看完整错误信息中的 error 和 next 字段",
+                "运行 cgc-doctor 检查环境配置",
+                "如果问题持续，请报告此错误代码",
+            ],
+        }
+
+    explanation = ERROR_CATALOG[error_code].copy()
+    explanation["error_code"] = error_code
+    return explanation
+
+
+def list_error_codes() -> list[str]:
+    """List all available error codes."""
+    return sorted(ERROR_CATALOG.keys())
+
+
+def format_explanation(explanation: dict[str, Any]) -> str:
+    """Format explanation as human-readable text.
+
+    Args:
+        explanation: Result from explain_error
+
+    Returns:
+        Formatted text block
+    """
+    lines = [
+        f"错误代码: {explanation['error_code']}",
+        f"标题: {explanation['title']}",
+        "",
+        "说明:",
+        explanation['description'],
+        "",
+    ]
+
+    if explanation.get("common_causes"):
+        lines.append("常见原因:")
+        for cause in explanation["common_causes"]:
+            lines.append(f"  - {cause}")
+        lines.append("")
+
+    if explanation.get("suggestions"):
+        lines.append("建议操作:")
+        for suggestion in explanation["suggestions"]:
+            lines.append(f"  - {suggestion}")
+
+    return "\n".join(lines)

package/scripts/codecgc_error_formatter.py

@@ -0,0 +1,124 @@
+"""Error formatting and leveling for CodeCGC output.
+
+Provides three-level error display:
+- summary: User-friendly Chinese message for non-technical users
+- detail: Technical context for developers
+- debug: Full logs and tracebacks for troubleshooting
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def format_error_output(
+    result: dict[str, Any],
+    *,
+    level: str = "summary",
+) -> dict[str, Any]:
+    """Format error output with appropriate detail level.
+
+    Args:
+        result: Raw result dict from workflow execution
+        level: Display level - "summary", "detail", or "debug"
+
+    Returns:
+        Formatted result with error_display field
+    """
+    if result.get("success"):
+        return result
+
+    error_display = _build_error_display(result, level)
+    formatted = result.copy()
+    formatted["error_display"] = error_display
+    formatted["error_level"] = level
+
+    return formatted
+
+
+def _build_error_display(result: dict[str, Any], level: str) -> dict[str, Any]:
+    """Build error display structure based on level."""
+    display: dict[str, Any] = {
+        "level": level,
+    }
+
+    # Summary level: user-friendly Chinese only
+    if level == "summary":
+        display["message"] = _extract_user_message(result)
+        display["suggestion"] = _extract_user_suggestion(result)
+        return display
+
+    # Detail level: add technical context
+    if level == "detail":
+        display["message"] = _extract_user_message(result)
+        display["suggestion"] = _extract_user_suggestion(result)
+        display["technical_error"] = result.get("error", "")
+        display["failure_type"] = result.get("failure_type", "")
+        display["state"] = result.get("state", "")
+        display["audit_path"] = result.get("audit_path", "")
+        return display
+
+    # Debug level: everything
+    if level == "debug":
+        display["message"] = _extract_user_message(result)
+        display["suggestion"] = _extract_user_suggestion(result)
+        display["technical_error"] = result.get("error", "")
+        display["failure_type"] = result.get("failure_type", "")
+        display["state"] = result.get("state", "")
+        display["audit_path"] = result.get("audit_path", "")
+        display["full_result"] = result
+        return display
+
+    # Fallback
+    display["message"] = _extract_user_message(result)
+    return display
+
+
+def _extract_user_message(result: dict[str, Any]) -> str:
+    """Extract user-friendly error message."""
+    # Check for human_error first (from Phase 1)
+    execution = result.get("execution", {})
+    if isinstance(execution, dict):
+        exec_result = execution.get("result", {})
+        if isinstance(exec_result, dict):
+            human_error = exec_result.get("human_error", "").strip()
+            if human_error:
+                return human_error
+
+    # Check for next field (from flow control)
+    next_msg = result.get("next", "").strip()
+    if next_msg:
+        return next_msg
+
+    # Check for error field
+    error_msg = result.get("error", "").strip()
+    if error_msg:
+        # If it looks technical, provide generic message
+        if "failed with exit code" in error_msg.lower() or "traceback" in error_msg.lower():
+            return "执行步骤失败。请查看详细信息或运行 cgc-doctor 检查环境。"
+        return error_msg
+
+    return "执行失败，未提供详细信息。"
+
+
+def _extract_user_suggestion(result: dict[str, Any]) -> str:
+    """Extract user-friendly suggestion."""
+    # Check for suggestion field (from Phase 1)
+    execution = result.get("execution", {})
+    if isinstance(execution, dict):
+        exec_result = execution.get("result", {})
+        if isinstance(exec_result, dict):
+            suggestion = exec_result.get("suggestion", "").strip()
+            if suggestion:
+                return suggestion
+
+    # Check for recommended_command
+    recommended = result.get("recommended_command", "").strip()
+    if recommended:
+        return f"建议运行: {recommended}"
+
+    # Check for next field that contains suggestions
+    next_msg = result.get("next", "").strip()
+    if next_msg and ("建议" in next_msg or "请" in next_msg or "运行" in next_msg):
+        return next_msg
+
+    return "请稍后重试，或运行 cgc-doctor 检查环境配置。"

package/scripts/codecgc_flow_control.py

@@ -108,6 +108,17 @@ def classify_execution_failure(execution: dict[str, Any]) -> tuple[str, str, str
             "当前步骤引用的目标路径在工作区中不存在，请先回到 cgc-plan 修正目标路径或步骤契约。",
         )
 
+    if "failed with exit code" in combined:
+        human = str(result.get("human_error", "")).strip()
+        suggestion = str(result.get("suggestion", "")).strip()
+        next_msg = human + "\n" + suggestion if human else "执行器内部异常，请稍后重试。如果持续失败，运行 cgc-doctor 检查环境。"
+        return (
+            "blocked",
+            "executor-crash",
+            "",
+            next_msg,
+        )
+
     if outcome == "blocked" or "timeout" in combined or "does not exist" in combined:
         return (
             "blocked",