@hunyed15/codecgc 0.1.0

package/geminimcp/src/geminimcp/server.py

@@ -0,0 +1,465 @@
+"""FastMCP server implementation for the Gemini MCP project."""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import subprocess
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Annotated, Any, Dict, Generator, List, Optional
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import BeforeValidator, Field
+import shutil
+
+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.
+BACKEND_PATH_HINTS = (
+    "apps/api/",
+    "server/",
+    "src/server/",
+    "src/services/",
+    "src/repositories/",
+    "backend/",
+)
+
+BACKEND_FILE_HINTS = (
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".cs",
+    ".rb",
+    ".php",
+    ".sql",
+)
+
+
+def _normalize_path_text(path_value: Path | str) -> str:
+    """Normalize a path-like value to a forward-slash string."""
+    return str(path_value).replace("\\", "/").strip()
+
+
+def _is_probably_backend_path(path_value: Path | str) -> bool:
+    """Best-effort check to keep frontend-only Gemini tasks away from backend files."""
+    normalized = _normalize_path_text(path_value).lower().lstrip("./")
+    if any(hint in normalized for hint in BACKEND_PATH_HINTS):
+        return True
+
+    suffix = Path(normalized).suffix.lower()
+    if suffix in BACKEND_FILE_HINTS:
+        return True
+
+    return False
+
+
+def _build_frontend_task_prompt(
+    task_summary: str,
+    target_paths: List[Path],
+    constraints: List[str],
+    acceptance_criteria: List[str],
+) -> str:
+    """Build a constrained prompt for frontend implementation tasks."""
+    lines = [
+        "You are implementing a frontend-only coding task.",
+        "Stay strictly within the provided target paths.",
+        "Do not edit backend files, API layers, repositories, or server logic.",
+        "Preserve the existing product structure unless the task explicitly requires otherwise.",
+        "Return a concise implementation summary, followed by risks if any remain.",
+        "",
+        "Task summary:",
+        task_summary.strip(),
+        "",
+        "Target paths:",
+    ]
+
+    lines.extend(f"- {_normalize_path_text(path)}" for path in target_paths)
+
+    if constraints:
+        lines.append("")
+        lines.append("Constraints:")
+        lines.extend(f"- {item.strip()}" for item in constraints if item.strip())
+
+    if acceptance_criteria:
+        lines.append("")
+        lines.append("Acceptance criteria:")
+        lines.extend(f"- {item.strip()}" for item in acceptance_criteria if item.strip())
+
+    return "\n".join(lines).strip()
+
+
+def _validate_frontend_target_paths(target_paths: List[Path]) -> tuple[bool, List[str], str]:
+    """Validate frontend task target paths and return policy check notes."""
+    if not target_paths:
+        return False, [], "The `target_paths` field must contain at least one file or directory."
+
+    normalized_paths = [_normalize_path_text(path) for path in target_paths]
+    backend_hits = [
+        path_text
+        for path_text in normalized_paths
+        if _is_probably_backend_path(path_text)
+    ]
+
+    policy_checks = [
+        "target_paths_present",
+        "frontend_scope_requested",
+    ]
+
+    if backend_hits:
+        return (
+            False,
+            policy_checks,
+            "The frontend executor refused backend-like paths: "
+            + ", ".join(backend_hits),
+        )
+
+    policy_checks.append("backend_boundary_check_passed")
+    return True, policy_checks, ""
+
+
+def run_shell_command(cmd: list[str], cwd: str | None = None) -> Generator[str, None, None]:
+    """Execute a command and stream its output line-by-line.
+
+    Args:
+        cmd: Command and arguments as a list (e.g., ["gemini", "-o", "stream-json", "--", "prompt"])
+        cwd: Working directory for the command
+
+    Yields:
+        Output lines from the command
+    """
+    popen_cmd = cmd
+
+    gemini_path = shutil.which("gemini") or cmd[0]
+    popen_cmd[0] = gemini_path
+
+    # if os.name == "nt" and gemini_path.lower().endswith((".cmd", ".bat")):
+    #     from subprocess import list2cmdline
+    #     popen_cmd = ["cmd.exe", "/s", "/c", list2cmdline(cmd)]
+
+    process = subprocess.Popen(
+        popen_cmd,
+        shell=False,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        universal_newlines=True,
+        encoding='utf-8',
+        cwd=cwd,
+    )
+
+    output_queue: queue.Queue[str | None] = queue.Queue()
+    GRACEFUL_SHUTDOWN_DELAY = 0.3
+
+    def is_turn_completed(line: str) -> bool:
+        """Check if the line indicates turn completion via JSON parsing."""
+        try:
+            data = json.loads(line)
+            return data.get("type") in {"turn.completed", "result"}
+        except (json.JSONDecodeError, AttributeError, TypeError):
+            return False
+
+    def read_output() -> None:
+        """Read process output in a separate thread."""
+        if process.stdout:
+            for line in iter(process.stdout.readline, ""):
+                stripped = line.strip()
+                output_queue.put(stripped)
+                if is_turn_completed(stripped):
+                    time.sleep(GRACEFUL_SHUTDOWN_DELAY)
+                    process.terminate()
+                    break
+            process.stdout.close()
+        output_queue.put(None)
+
+    thread = threading.Thread(target=read_output)
+    thread.start()
+
+    # Yield lines while process is running
+    while True:
+        try:
+            line = output_queue.get(timeout=0.5)
+            if line is None:
+                break
+            yield line
+        except queue.Empty:
+            if process.poll() is not None and not thread.is_alive():
+                break
+
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+    thread.join(timeout=5)
+
+    while not output_queue.empty():
+        try:
+            line = output_queue.get_nowait()
+            if line is not None:
+                yield line
+        except queue.Empty:
+            break
+
+
+def _execute_gemini_session(
+    *,
+    prompt: str,
+    cd: Path,
+    sandbox: bool,
+    session_id: str,
+    return_all_messages: bool,
+    model: str,
+) -> Dict[str, Any]:
+    """Execute Gemini CLI and return the parsed MCP response payload."""
+    if not cd.exists():
+        return {
+            "success": False,
+            "error": f"The workspace root directory `{cd.absolute().as_posix()}` does not exist. Please check the path and try again.",
+        }
+
+    if os.name == "nt":
+        prompt = windows_escape(prompt)
+
+    cmd = ["gemini", "--skip-trust", "--prompt", prompt, "-o", "stream-json"]
+
+    if sandbox:
+        cmd.extend(["--sandbox"])
+
+    if model:
+        cmd.extend(["--model", model])
+
+    if session_id:
+        cmd.extend(["--resume", session_id])
+
+    all_messages = []
+    agent_messages = ""
+    success = True
+    err_message = ""
+    thread_id: Optional[str] = None
+
+    for line in run_shell_command(cmd, cwd=cd.absolute().as_posix()):
+        try:
+            line_dict = json.loads(line.strip())
+            all_messages.append(line_dict)
+            item_type = line_dict.get("type", "")
+            item_role = line_dict.get("role", "")
+            if item_type == "message" and item_role == "assistant":
+                if (
+                    "The --prompt (-p) flag has been deprecated and will be removed in a future version. Please use a positional argument for your prompt. See gemini --help for more information.\n"
+                    in line_dict.get("content", "")
+                ):
+                    continue
+                agent_messages = agent_messages + line_dict.get("content", "")
+            if line_dict.get("session_id") is not None:
+                thread_id = line_dict.get("session_id")
+        except json.JSONDecodeError:
+            err_message += "\n\n[json decode error] " + line
+            continue
+        except Exception as error:
+            err_message += "\n\n[unexpected error] " + f"Unexpected error: {error}. Line: {line!r}"
+            break
+
+    if thread_id is None:
+        success = False
+        err_message = (
+            "Failed to get `SESSION_ID` from the gemini session. \n\n" + err_message
+        )
+
+    if success and len(agent_messages) == 0:
+        success = False
+        err_message = (
+            "Failed to retrieve `agent_messages` data from the Gemini session. This might be due to Gemini performing a tool call. You can continue using the `SESSION_ID` to proceed with the conversation. \n\n "
+            + err_message
+        )
+
+    if success:
+        result: Dict[str, Any] = {
+            "success": True,
+            "SESSION_ID": thread_id,
+            "agent_messages": agent_messages,
+        }
+    else:
+        result = {"success": False, "error": err_message}
+
+    if return_all_messages:
+        result["all_messages"] = all_messages
+
+    return result
+
+
+def windows_escape(prompt):
+    """
+    Windows 风格的字符串转义函数。
+    把常见特殊字符转义成 \\ 形式，适合命令行、JSON 或路径使用。
+    比如：\n 变成 \\n，" 变成 \\"。
+    """
+    # 先处理反斜杠，避免它干扰其他替换
+    result = prompt.replace("\\", "\\\\")
+    # 双引号，转义成 \"，防止字符串边界乱套
+    result = result.replace('"', '\\"')
+    # 换行符，Windows 常用 \r\n，但我们分开转义
+    result = result.replace("\n", "\\n")
+    result = result.replace("\r", "\\r")
+    # 制表符，空格的“超级版”
+    result = result.replace("\t", "\\t")
+    # 其他常见：退格符（像按了后退键）、换页符（打印机跳页用）
+    result = result.replace("\b", "\\b")
+    result = result.replace("\f", "\\f")
+    # 如果有单引号，也转义下（不过 Windows 命令行不那么严格，但保险起见）
+    result = result.replace("'", "\\'")
+
+    return result
+
+
+@mcp.tool(
+    name="gemini",
+    description="""
+    Invokes the Gemini CLI to execute AI-driven tasks, returning structured JSON events and a session identifier for conversation continuity. 
+    
+    **Return structure:**
+        - `success`: boolean indicating execution status
+        - `SESSION_ID`: unique identifier for resuming this conversation in future calls
+        - `agent_messages`: concatenated assistant response text
+        - `all_messages`: (optional) complete array of JSON events when `return_all_messages=True`
+        - `error`: error description when `success=False`
+
+    **Best practices:**
+        - Always capture and reuse `SESSION_ID` for multi-turn interactions
+        - Enable `sandbox` mode when file modifications should be isolated
+        - Use `return_all_messages` only when detailed execution traces are necessary (increases payload size)
+        - Only pass `model` when the user has explicitly requested a specific model
+    """,
+    meta={"version": "0.0.0", "author": "guda.studio"},
+)
+async def gemini(
+    PROMPT: Annotated[str, "Instruction for the task to send to gemini."],
+    cd: Annotated[Path, "Set the workspace root for gemini before executing the task."],
+    sandbox: Annotated[
+        bool,
+        Field(description="Run in sandbox mode. Defaults to `False`."),
+    ] = False,
+    SESSION_ID: Annotated[
+        str,
+        "Resume the specified session of the gemini. Defaults to empty string, start a new session.",
+    ] = "",
+    return_all_messages: Annotated[
+        bool,
+        "Return all messages (e.g. reasoning, tool calls, etc.) from the gemini session. Set to `False` by default, only the agent's final reply message is returned.",
+    ] = False,
+    model: Annotated[
+        str,
+        "The model to use for the gemini session. This parameter is strictly prohibited unless explicitly specified by the user.",
+    ] = "",
+) -> Dict[str, Any]:
+    """Execute a gemini CLI session and return the results."""
+    return _execute_gemini_session(
+        prompt=PROMPT,
+        cd=cd,
+        sandbox=sandbox,
+        session_id=SESSION_ID,
+        return_all_messages=return_all_messages,
+        model=model,
+    )
+
+
+@mcp.tool(
+    name="implement_frontend_task",
+    description="""
+    Executes a frontend-only implementation task via Gemini with extra policy checks.
+    Use this tool when Claude has already completed planning/design and needs Gemini to
+    perform the actual frontend code changes inside a constrained path set.
+    """,
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def implement_frontend_task(
+    task_id: Annotated[str, "Stable task identifier for audit and review."],
+    task_summary: Annotated[str, "Frontend implementation summary prepared by the orchestrator."],
+    target_paths: Annotated[
+        List[Path],
+        Field(
+            description="Frontend paths Gemini is allowed to touch for this task.",
+        ),
+    ],
+    constraints: Annotated[
+        List[str],
+        Field(
+            description="Non-negotiable implementation constraints for this frontend task.",
+        ),
+    ] = [],
+    acceptance_criteria: Annotated[
+        List[str],
+        Field(
+            description="Acceptance criteria the implementation should satisfy.",
+        ),
+    ] = [],
+    cd: Annotated[Path, "Workspace root for the frontend task."] = Path("."),
+    SESSION_ID: Annotated[
+        str,
+        "Resume the specified Gemini session. Empty string starts a new session.",
+    ] = "",
+    sandbox: Annotated[
+        bool,
+        Field(description="Run Gemini in sandbox mode. Defaults to `False`."),
+    ] = False,
+    return_all_messages: Annotated[
+        bool,
+        "Return full Gemini event logs for debugging. Defaults to `False`.",
+    ] = False,
+    model: Annotated[
+        str,
+        "Optional model override. Only use when explicitly requested by the user.",
+    ] = "",
+) -> Dict[str, Any]:
+    """Execute a frontend-only Gemini task with CodeCGC policy checks."""
+    valid, policy_checks, validation_error = _validate_frontend_target_paths(target_paths)
+    if not valid:
+        return {
+            "success": False,
+            "task_id": task_id,
+            "policy_checks": policy_checks,
+            "error": validation_error,
+        }
+
+    prompt = _build_frontend_task_prompt(
+        task_summary=task_summary,
+        target_paths=target_paths,
+        constraints=constraints,
+        acceptance_criteria=acceptance_criteria,
+    )
+    result = _execute_gemini_session(
+        prompt=prompt,
+        cd=cd,
+        sandbox=sandbox,
+        session_id=SESSION_ID,
+        return_all_messages=return_all_messages,
+        model=model,
+    )
+
+    if not result.get("success"):
+        result["task_id"] = task_id
+        result["policy_checks"] = policy_checks
+        return result
+
+    return {
+        "success": True,
+        "task_id": task_id,
+        "SESSION_ID": result["SESSION_ID"],
+        "summary": result["agent_messages"],
+        "agent_messages": result["agent_messages"],
+        "changed_files": [_normalize_path_text(path) for path in target_paths],
+        "policy_checks": policy_checks + ["frontend_executor_completed"],
+        "risks": [],
+        **({"all_messages": result["all_messages"]} if return_all_messages and "all_messages" in result else {}),
+    }
+
+
+def run() -> None:
+    """Start the MCP server over stdio transport."""
+    mcp.run(transport="stdio")

package/model-routing.yaml

@@ -0,0 +1,30 @@
+version: 1
+
+frontend_paths:
+  - "apps/web/**"
+  - "src/components/**"
+  - "src/pages/**"
+  - "src/app/**"
+  - "src/styles/**"
+  - "web/**"
+  - "frontend/**"
+
+backend_paths:
+  - "apps/api/**"
+  - "server/**"
+  - "src/server/**"
+  - "src/services/**"
+  - "src/repositories/**"
+  - "backend/**"
+
+shared_paths:
+  - "packages/shared/**"
+  - "src/shared/**"
+  - "src/lib/**"
+  - "src/types/**"
+
+rules:
+  frontend_executor: "geminimcp"
+  backend_executor: "codexmcp"
+  shared_policy: "split-first"
+  claude_role: "plan-review-accept-only"

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@hunyed15/codecgc",
+  "version": "0.1.0",
+  "description": "Claude-hosted multi-model workflow product shell for CodeCGC.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "cgc": "bin/cgc.js",
+    "cgc-install": "bin/cgc-install.js",
+    "cgc-status": "bin/cgc-status.js",
+    "cgc-doctor": "bin/cgc-doctor.js",
+    "cgc-package-audit": "bin/cgc-package-audit.js",
+    "cgc-external-audit": "bin/cgc-external-audit.js",
+    "cgc-release-readiness": "bin/cgc-release-readiness.js",
+    "cgc-lifecycle": "bin/cgc-lifecycle.js",
+    "cgc-history": "bin/cgc-history.js",
+    "cgc-entry": "bin/cgc-entry.js",
+    "cgc-plan": "bin/cgc-plan.js",
+    "cgc-build": "bin/cgc-build.js",
+    "cgc-fix": "bin/cgc-fix.js",
+    "cgc-test": "bin/cgc-test.js",
+    "cgc-review": "bin/cgc-review.js",
+    "cgc-route": "bin/cgc-route.js"
+  },
+  "scripts": {
+    "cgc:help": "node bin/cgc.js --help",
+    "cgc:status": "node bin/cgc-status.js --format summary",
+    "cgc:doctor": "node bin/cgc-doctor.js --format summary",
+    "cgc:package-audit": "node bin/cgc-package-audit.js --format summary",
+    "cgc:external-audit": "node bin/cgc-external-audit.js --format summary",
+    "cgc:release-readiness": "node bin/cgc-release-readiness.js --format summary",
+    "cgc:lifecycle": "node bin/cgc-lifecycle.js --format summary",
+    "cgc:history": "node bin/cgc-history.js --status open --last 10 --format summary",
+    "cgc:audit-historical-audits": "python scripts/audit_codecgc_historical_audits.py --format summary",
+    "cgc:audit-review-policy": "python scripts/audit_codecgc_review_policy.py --artifact-class all --format summary",
+    "cgc:refresh-review-policy": "python scripts/refresh_codecgc_review_policy.py --artifact-class all --write",
+    "cgc:pack-dry-run": "npm pack --dry-run"
+  },
+  "files": [
+    "bin/",
+    "scripts/*.py",
+    "scripts/README-codecgc-cli.md",
+    ".claude/hooks/route-edit.ps1",
+    "codecgc/cgc/",
+    "codecgc/cgc-arch/",
+    "codecgc/cgc-build/",
+    "codecgc/cgc-decide/",
+    "codecgc/cgc-fix/",
+    "codecgc/cgc-learn/",
+    "codecgc/cgc-onboard/",
+    "codecgc/cgc-plan/",
+    "codecgc/cgc-refactor/",
+    "codecgc/cgc-req/",
+    "codecgc/cgc-review/",
+    "codecgc/cgc-roadmap/",
+    "codecgc/cgc-test/",
+    "codecgc/reference/",
+    "codexmcp/pyproject.toml",
+    "codexmcp/README.md",
+    "codexmcp/LICENSE",
+    "codexmcp/src/codexmcp/",
+    "geminimcp/pyproject.toml",
+    "geminimcp/README.md",
+    "geminimcp/src/geminimcp/",
+    "requirements.txt",
+    "INSTALLATION.md",
+    "model-routing.yaml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "mcp",
+    "workflow",
+    "codex",
+    "gemini",
+    "multi-model"
+  ],
+  "homepage": "https://github.com/hunyed15/CodeCGC",
+  "bugs": {
+    "url": "https://github.com/hunyed15/CodeCGC/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hunyed15/CodeCGC.git"
+  }
+}

package/requirements.txt

@@ -0,0 +1 @@
+pyyaml>=6.0

package/scripts/README-codecgc-cli.md

@@ -0,0 +1,89 @@
+# CodeCGC CLI
+
+## 用途
+
+`codecgc_cli.py` 是 CodeCGC 的统一本地封装入口。
+
+相比逐个调用底层脚本，它更适合作为仓库维护和调试时的统一入口。
+
+## 常用命令
+
+单入口调度：
+
+```bash
+python scripts/codecgc_cli.py entry --request "新增一个登录页面，放在 src/components/LoginForm.tsx"
+python scripts/codecgc_cli.py entry --request "继续刚刚的工作"
+python scripts/codecgc_cli.py entry --request "现在下一步该做什么"
+python scripts/codecgc_cli.py entry --mode new --flow feature --slug demo-login-ui --summary "Demo login UI feature" --target-path src/components/LoginForm.tsx --kind frontend
+python scripts/codecgc_cli.py entry --mode continue --flow feature --slug 2026-05-01-demo-login-ui
+python scripts/codecgc_cli.py entry --mode explain --slug 2026-05-01-demo-login-ui
+python scripts/codecgc_cli.py entry --mode continue --latest
+python scripts/codecgc_cli.py entry --mode continue --slug 2026-05-01-demo-login-ui --auto-dispatch --dry-run
+```
+
+规划并补齐工作流骨架：
+
+```bash
+python scripts/codecgc_cli.py plan --flow feature --slug demo-login-ui --summary "Demo login UI feature" --target-path src/components/LoginForm.tsx --kind frontend
+python scripts/codecgc_cli.py plan --flow issue --slug demo-sync-bug --summary "Demo sync bug fix" --target-path backend/session/continue.py --kind backend
+```
+
+支持结构化 `plan` 输入：
+
+```bash
+python scripts/codecgc_cli.py plan --flow feature --slug demo-login-ui --summary "Demo login UI feature" --target-path src/components/LoginForm.tsx --kind frontend --goal "Allow users to sign in from a dedicated login form." --in-scope "Create the login form UI." --acceptance "Login form renders email and password fields."
+python scripts/codecgc_cli.py plan --flow issue --slug demo-sync-bug --summary "Demo sync bug fix" --target-path backend/src/sync.py --kind backend --symptom "Sync stops on malformed record." --expected "Valid records still sync." --actual "Whole batch stops." --root-cause "Validation aborts the batch loop." --preferred-fix "Catch per-record validation errors." --acceptance "Malformed records are skipped and logged."
+```
+
+也支持更丰富的规划结构：
+
+```bash
+python scripts/codecgc_cli.py plan --flow feature --slug demo-login-ui --summary "Demo login UI feature" --target-path src/components/LoginForm.tsx --kind frontend --goal "Allow users to sign in from a dedicated login form." --user-story "As a returning user, I want a focused login entry so I can sign in quickly." --context "This replaces an inline login panel on the landing page." --dependency "Auth API already exists." --assumption "No backend contract changes are needed." --validation "Render the form and submit against the existing auth endpoint." --rollback "Restore the previous inline login entry if the new screen fails review."
+```
+
+初始化工作流产物：
+
+```bash
+python scripts/codecgc_cli.py init --flow feature --slug demo-login-ui --summary "Demo login UI feature"
+```
+
+运行一个高层功能开发或问题修复步骤：
+
+```bash
+python scripts/codecgc_cli.py build --slug 2026-05-01-demo-login-ui --step-number 1 --dry-run
+python scripts/codecgc_cli.py fix --slug 2026-05-01-demo-sync-bug --step-number 1 --dry-run
+```
+
+精确执行一个步骤：
+
+```bash
+python scripts/codecgc_cli.py exec --flow feature --slug 2026-05-01-demo-login-ui --step-number 1 --dry-run
+```
+
+写回审核结果：
+
+```bash
+python scripts/codecgc_cli.py review --audit-file codecgc/execution/demo-login-ui-step-1.json --decision accepted
+```
+
+判断当前产物状态的下一步命令：
+
+```bash
+python scripts/codecgc_cli.py route --flow feature --slug 2026-05-01-demo-login-ui
+```
+
+## 说明
+
+优先把 `codecgc_cli.py` 当作维护和调试时的统一入口。
+如果你想用一个明显的开始/继续/解释入口，优先用 `entry`。
+日常工作流阶段优先使用 `plan/build/fix/review/route`。
+只有在需要更底层控制时，才直接使用 `init/exec`。
+
+`entry` 现已支持通过 `--request` 接收轻量意图优先请求。
+
+`plan` 现在也会返回可机读的 `planning_status`：
+
+- `ready-for-build`
+- `ready-for-fix`
+- `needs-clarification`
+- `needs-roadmap`