devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/integrations/mcp/util.py

@@ -0,0 +1,303 @@
+"""Shared helpers for MCP tool handlers."""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+import sys
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+from mcp.types import TextContent
+
+logger = logging.getLogger(__name__)
+
+_CLI_TIMEOUT_SECONDS = 120
+CLI_TIMEOUT_SECONDS = _CLI_TIMEOUT_SECONDS
+_GIT_APPLY_TIMEOUT_SECONDS = 120
+_CLI_OUTPUT_LIMIT = 20_000
+
+
+def read_log_file(path: str | None) -> str:
+    """Best-effort read of a persisted stdout/stderr log."""
+    if not path:
+        return ""
+    try:
+        return Path(path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def optional_string_list_argument(arguments: dict, name: str) -> tuple[list[str], list[TextContent] | None]:
+    value = arguments.get(name)
+    if value is None:
+        return [], None
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        return [], error_text(f"{name} must be a string array", code="invalid_arguments", argument=name)
+    return value, None
+
+
+def json_text(payload: dict[str, object]) -> list[TextContent]:
+    return [TextContent(type="text", text=json.dumps(payload, indent=2))]
+
+
+def error_text(message: str, *, code: str = "error", **details: object) -> list[TextContent]:
+    return json_text({"ok": False, "error": message, "code": code, **details})
+
+
+def annotate_stale(contents: list[TextContent], coordinator: object) -> list[TextContent]:
+    """Attach top-level stale/sync metadata when a freshness wait timed out."""
+    text = contents[0].text if contents else ""
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        return contents
+    if not isinstance(payload, dict):
+        return contents
+    status = coordinator.status()  # type: ignore[attr-defined]
+    payload["stale"] = True
+    payload["fresh"] = False
+    existing_sync = payload.get("sync")
+    sync_base = existing_sync if isinstance(existing_sync, dict) else {}
+    payload["sync"] = {
+        **sync_base,
+        "pending": list(getattr(status, "pending", []) or []),
+        "state": getattr(status, "state", "pending"),
+        "fresh": False,
+    }
+    return json_text(payload)
+
+
+async def with_codeintel_freshness(
+    root: Path,
+    produce: Callable[[], Awaitable[list[TextContent]]],
+    *,
+    timeout: float = 2.0,
+) -> list[TextContent]:
+    """Await pending sync, run ``produce``, and annotate stale responses."""
+    import asyncio
+
+    from devcouncil.codeintel.sync import get_sync_coordinator
+
+    coordinator = get_sync_coordinator(root)
+    fresh = await asyncio.to_thread(coordinator.wait_until_fresh, timeout=timeout)
+    contents = await produce()
+    if not fresh and contents:
+        return annotate_stale(contents, coordinator)
+    return contents
+
+
+def normalize_arguments(arguments: object) -> dict:
+    return arguments if isinstance(arguments, dict) else {}
+
+
+def int_argument(arguments: dict, name: str, default: int, *, minimum: int, maximum: int) -> int:
+    value = arguments.get(name, default)
+    if not isinstance(value, int) or isinstance(value, bool):
+        value = default
+    return max(minimum, min(value, maximum))
+
+
+def optional_string_argument(arguments: dict, name: str) -> str | None:
+    value = arguments.get(name)
+    if value is None:
+        return None
+    return value if isinstance(value, str) else ""
+
+
+def optional_bool_argument(arguments: dict, name: str) -> tuple[bool | None, list[TextContent] | None]:
+    """Return ``(value, None)`` when absent/valid, or ``(None, error)`` when malformed.
+
+    Absent → ``(None, None)`` so callers can apply their own default.
+    """
+    if name not in arguments or arguments.get(name) is None:
+        return None, None
+    value = arguments.get(name)
+    if not isinstance(value, bool):
+        return None, error_text(f"{name} must be a boolean", code="invalid_arguments", argument=name)
+    return value, None
+
+
+def required_string_argument(arguments: dict, name: str) -> tuple[str | None, list[TextContent] | None]:
+    value = arguments.get(name)
+    if value is None or value == "":
+        return None, error_text(f"Missing {name}", code="missing_argument", argument=name)
+    if not isinstance(value, str):
+        return None, error_text(f"{name} must be a string", code="invalid_arguments", argument=name)
+    return value, None
+
+
+def truncate_text(value: str | bytes | None, limit: int = _CLI_OUTPUT_LIMIT) -> tuple[str, bool]:
+    if value is None:
+        return "", False
+    if isinstance(value, bytes):
+        value = value.decode("utf-8", errors="replace")
+    if len(value) <= limit:
+        return value, False
+    marker = f"\n...[truncated to {limit} characters]"
+    return value[:limit] + marker, True
+
+
+def is_git_repo(root: Path) -> bool:
+    try:
+        from devcouncil.utils.proc import run_git
+
+        result = run_git(["rev-parse", "--is-inside-work-tree"], cwd=root)
+        return result.returncode == 0 and result.stdout.strip() == "true"
+    except Exception as exc:
+        logger.debug("git work-tree check failed for %s: %s", root, exc)
+        return False
+
+
+def within_root(root: Path, rel_or_abs: str) -> Path | None:
+    raw = rel_or_abs.strip().strip('"').replace("\\", "/")
+    try:
+        candidate = Path(raw)
+        resolved = candidate.resolve() if candidate.is_absolute() else (root / raw).resolve()
+        resolved.relative_to(root.resolve())
+        return resolved
+    except (OSError, ValueError):
+        return None
+
+
+def diff_target_paths(unified_diff: str) -> list[str]:
+    targets: list[str] = []
+    seen: set[str] = set()
+
+    def _clean(token: str) -> str | None:
+        token = token.strip()
+        if len(token) >= 2 and token.startswith('"') and token.endswith('"'):
+            try:
+                token = token[1:-1].encode("utf-8").decode("unicode_escape")
+            except Exception:
+                token = token[1:-1]
+        if not token or token == "/dev/null":
+            return None
+        if token[:2] in ("a/", "b/"):
+            token = token[2:]
+        return token or None
+
+    def _add(path: str | None) -> None:
+        if path and path not in seen:
+            seen.add(path)
+            targets.append(path)
+
+    for line in unified_diff.splitlines():
+        if line.startswith("--- ") or line.startswith("+++ "):
+            _add(_clean(line[4:]))
+        elif line.startswith(("rename from ", "rename to ", "copy from ", "copy to ")):
+            _add(_clean(line.split(" ", 2)[2]))
+        elif line.startswith("diff --git "):
+            parts = line[len("diff --git "):].split()
+            if len(parts) == 2:
+                _add(_clean(parts[0]))
+                _add(_clean(parts[1]))
+    return targets
+
+
+def lease_ttl_seconds(root: Path) -> int:
+    try:
+        from devcouncil.app.config import load_config
+
+        return max(0, int(load_config(root).execution.lease_ttl_seconds))
+    except Exception as exc:
+        logger.debug("Could not load lease_ttl_seconds for %s: %s", root, exc)
+        return 1800
+
+
+def allowed_next_tools(status: str, has_blocking_gaps: bool) -> list[str]:
+    if status == "verified":
+        return ["devcouncil_release_task"]
+    if status in {"done", "cancelled"}:
+        return []
+    if status in {"running", "blocked"} or has_blocking_gaps:
+        return [
+            "devcouncil_read_file",
+            "devcouncil_get_evidence",
+            "devcouncil_get_diff",
+            "devcouncil_run_command",
+            "devcouncil_apply_patch",
+            "devcouncil_write_file",
+            "devcouncil_update_task_scope",
+            "devcouncil_verify_task",
+        ]
+    return [
+        "devcouncil_checkout_task",
+        "devcouncil_read_file",
+        "devcouncil_get_diff",
+    ]
+
+
+def parse_cli_json(result: dict[str, object]) -> tuple[dict | None, list[TextContent] | None]:
+    """Parse JSON stdout from a CLI subprocess, even when exit code is non-zero."""
+    stdout = str(result.get("stdout") or "").strip()
+    if stdout:
+        try:
+            return json.loads(stdout), None
+        except json.JSONDecodeError:
+            pass
+    if not result.get("ok"):
+        stderr = str(result.get("stderr") or "CLI command failed")
+        return None, error_text(stderr, code="cli_failed")
+    return None, error_text("CLI command returned invalid JSON", code="cli_parse_error")
+
+
+def run_cli_command(args: list[str], root: Path) -> dict[str, object]:
+    command = [sys.executable, "-m", "devcouncil", *args, "--project-root", str(root)]
+    try:
+        result = subprocess.run(
+            command,
+            cwd=root,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=_CLI_TIMEOUT_SECONDS,
+        )
+        stdout, stdout_truncated = truncate_text(result.stdout)
+        stderr, stderr_truncated = truncate_text(result.stderr)
+        return {
+            "ok": result.returncode == 0,
+            "returncode": result.returncode,
+            "stdout": stdout,
+            "stderr": stderr,
+            "stdout_truncated": stdout_truncated,
+            "stderr_truncated": stderr_truncated,
+            "timed_out": False,
+        }
+    except subprocess.TimeoutExpired as exc:
+        stdout, stdout_truncated = truncate_text(exc.output)
+        stderr, stderr_truncated = truncate_text(exc.stderr)
+        return {
+            "ok": False,
+            "returncode": None,
+            "stdout": stdout,
+            "stderr": stderr,
+            "stdout_truncated": stdout_truncated,
+            "stderr_truncated": stderr_truncated,
+            "timed_out": True,
+            "timeout_seconds": _CLI_TIMEOUT_SECONDS,
+        }
+
+
+GIT_APPLY_TIMEOUT_SECONDS = _GIT_APPLY_TIMEOUT_SECONDS
+
+
+def is_secret_path(root: Path, rel_or_abs: str) -> bool:
+    """True when a path matches a protected secret/credential glob."""
+    from devcouncil.execution.policy_engine import SECRET_PATH_PATTERNS
+    import fnmatch as _fnmatch
+
+    normalized = rel_or_abs.strip().strip('"').replace("\\", "/")
+    try:
+        candidate = Path(normalized)
+        if candidate.is_absolute():
+            resolved = candidate.resolve()
+            try:
+                normalized = resolved.relative_to(root.resolve()).as_posix()
+            except ValueError:
+                normalized = resolved.as_posix()
+    except OSError:
+        pass
+    return any(_fnmatch.fnmatch(normalized, pattern) for pattern in SECRET_PATH_PATTERNS)

package/src/devcouncil/integrations/setup.py

@@ -0,0 +1,152 @@
+"""Integration doctor and optional companion setup helpers."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.executors.agent_registry import (
+    VALID_INPUT_MODES,
+    load_agent_profiles,
+    load_cli_agent_specs,
+)
+from devcouncil.integrations.clients.common import _config_path, _load_raw_config, _save_raw_config
+from devcouncil.utils.fsio import atomic_write_text
+
+console = Console()
+
+
+def build_integrations_doctor_table(root: Path) -> Table:
+    """Build the integration doctor table (PATH probes + config presence)."""
+    table = Table(title="DevCouncil Integration Doctor")
+    table.add_column("Integration", style="cyan", no_wrap=True)
+    table.add_column("Status")
+    table.add_column("Notes", overflow="fold")
+
+    checks = [
+        ("Agent Flow", "agent-flow-app", "Optional live/replay visualizer for trace JSONL."),
+        ("code-review-graph", "code-review-graph", "Optional structural graph context adapter."),
+        ("Claude Code", "claude", "Optional MCP client and native hook runtime for pre-tool-use enforcement."),
+        ("Codex CLI", "codex", "Optional MCP client, headless executor companion, and native hook runtime."),
+        ("Gemini CLI (deprecated)", "gemini", "Deprecated — migrate to Google Antigravity CLI (dev integrate antigravity --apply)."),
+        ("Cursor", "cursor-agent", "Optional MCP client, agent/cursor-agent executor, and native hooks."),
+        ("Grok Build", "grok", "Optional MCP client, grok headless executor, and native hooks."),
+        ("OpenCode", "opencode", "Optional MCP client and headless coding-agent executor."),
+        ("Google Antigravity CLI", "agy", "Optional Antigravity CLI companion and headless coding-agent executor."),
+        ("Warp / Oz", "oz", "Optional Warp/Oz CLI companion and agent executor."),
+        ("Aider", "aider", "Optional headless executor via `dev run --executor aider` (no MCP)."),
+    ]
+    for label, executable, notes in checks:
+        found = shutil.which(executable)
+        table.add_row(label, "[green]OK[/green]" if found else "[yellow]Missing[/yellow]", found or notes)
+
+    profiles = load_agent_profiles(root)
+    for name, spec in load_cli_agent_specs(root).items():
+        if spec.built_in:
+            continue
+        found = shutil.which(spec.executable)
+        mode_ok = spec.input_mode in VALID_INPUT_MODES
+        profile_ok = spec.default_profile in profiles
+        status = "[green]OK[/green]" if found and mode_ok and profile_ok else "[red]Invalid[/red]"
+        if not found:
+            status = "[yellow]Missing[/yellow]"
+        details = found or f"{spec.executable} not found on PATH"
+        if not mode_ok:
+            details = f"invalid input_mode={spec.input_mode}"
+        if not profile_ok:
+            details = f"{details}; missing profile={spec.default_profile}"
+        table.add_row(f"CLI agent: {name}", status, details)
+
+    config = _config_path(root)
+    table.add_row(
+        "DevCouncil config",
+        "[green]OK[/green]" if config.exists() else "[red]Missing[/red]",
+        str(config) if config.exists() else "Run dev init first.",
+    )
+    return table
+
+
+def apply_agent_flow_setup(root: Path) -> Path:
+    """Record Agent Flow trace integration in config and write docs stub."""
+    trace_path = root / ".devcouncil" / "logs" / "traces.jsonl"
+    config = _load_raw_config(root)
+    integrations = config.setdefault("integrations", {})
+    integrations["agent_flow"] = {
+        "enabled": True,
+        "trace_path": str(trace_path),
+        "mode": "jsonl",
+    }
+    _save_raw_config(root, config)
+    docs_dir = root / ".devcouncil" / "integrations"
+    docs_dir.mkdir(parents=True, exist_ok=True)
+    doc_path = docs_dir / "agent-flow.md"
+    doc_path.write_text(
+        "\n".join([
+            "# Agent Flow",
+            "",
+            f"DevCouncil writes trace events to `{trace_path}`.",
+            "",
+            "Local replay:",
+            "",
+            "```bash",
+            "dev trace tail --follow",
+            "```",
+            "",
+            "External visualizers can watch the JSONL file directly. DevCouncil does not modify global editor or Claude Code settings from this setup command.",
+            "",
+        ]),
+        encoding="utf-8",
+    )
+    return trace_path
+
+
+def apply_code_review_graph_setup(root: Path) -> tuple[str | None, Path, bool]:
+    """Record code-review-graph integration, ensure ignore file, and write docs stub."""
+    executable = shutil.which("code-review-graph")
+    ignore_path = root / ".code-review-graphignore"
+    created = False
+    if not ignore_path.exists():
+        # Guarded by exists(): a torn write here would never be repaired, so write atomically.
+        atomic_write_text(
+            ignore_path,
+            "\n".join([
+                ".devcouncil/**",
+                ".git/**",
+                ".venv/**",
+                "dist/**",
+                "node_modules/**",
+                "",
+            ]),
+        )
+        created = True
+
+    config = _load_raw_config(root)
+    integrations = config.setdefault("integrations", {})
+    integrations["code_review_graph"] = {
+        "enabled": True,
+        "command": "code-review-graph",
+        "optional": True,
+    }
+    _save_raw_config(root, config)
+    docs_dir = root / ".devcouncil" / "integrations"
+    docs_dir.mkdir(parents=True, exist_ok=True)
+    (docs_dir / "code-review-graph.md").write_text(
+        "\n".join([
+            "# code-review-graph",
+            "",
+            "Install and build the graph outside DevCouncil:",
+            "",
+            "```bash",
+            "pipx install code-review-graph",
+            "code-review-graph build",
+            "```",
+            "",
+            "DevCouncil uses this as an optional context adapter for mapping, prompts, verification traces, and MCP graph context.",
+            "",
+        ]),
+        encoding="utf-8",
+    )
+    return executable, ignore_path, created

package/src/devcouncil/knowledge/fetch.py

@@ -208,7 +208,11 @@ def _clone_git(url: str) -> FetchedBundle:
             ["git", "clone", "--depth", "1", url, str(target)],
             capture_output=True,
             text=True,
+            timeout=600,  # network clone; generous, but a stalled remote must not hang fetch
         )
+    except subprocess.TimeoutExpired as exc:
+        shutil.rmtree(parent, ignore_errors=True)
+        raise RuntimeError(f"git clone of {url!r} timed out after 600s") from exc
     except OSError as exc:  # pragma: no cover - git present but unexecutable
         shutil.rmtree(parent, ignore_errors=True)
         raise RuntimeError(f"git clone failed to start: {exc}") from exc

package/src/devcouncil/knowledge/knowledge_select.py

@@ -0,0 +1,38 @@
+"""Goal-driven knowledge source selection shared by CLI and MCP."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def select_knowledge_payload(root: Path, goal: str) -> dict[str, object]:
+    """Return MCP/CLI-compatible knowledge selection for ``goal``."""
+    from devcouncil.knowledge.resource_discovery import knowledge_settings
+    from devcouncil.knowledge.sources import render_knowledge_preamble, select_knowledge_sources
+
+    try:
+        directory, design_always = knowledge_settings(root)
+        if directory is None:
+            sources = []
+        else:
+            sources = select_knowledge_sources(
+                goal, root, directory=directory, design_always=design_always
+            )
+        preamble = render_knowledge_preamble(sources)
+        return {
+            "ok": True,
+            "goal": goal,
+            "sources": [
+                {"name": source.name, "kind": source.kind, "description": source.description}
+                for source in sources
+            ],
+            "preamble": preamble,
+        }
+    except Exception as exc:
+        return {
+            "ok": True,
+            "goal": goal,
+            "sources": [],
+            "preamble": "",
+            "note": f"knowledge unavailable: {exc}",
+        }

package/src/devcouncil/knowledge/okf.py

@@ -22,6 +22,7 @@ from typing import Any
 from pydantic import BaseModel, Field
 
 from devcouncil.knowledge.frontmatter import build_frontmatter_markdown, split_frontmatter
+from devcouncil.utils.fsio import atomic_write_text
 
 # Markdown inline links: [text](target). We only resolve relative, non-anchor, non-URL
 # targets into intra-bundle edges; external resources live in the `resource` field.
@@ -179,7 +180,7 @@ def write_bundle(bundle: OKFBundle, bundle_dir: Path) -> list[Path]:
             continue
         target = bundle_dir / doc.rel_path
         target.parent.mkdir(parents=True, exist_ok=True)
-        target.write_text(doc.to_markdown(), encoding="utf-8")
+        atomic_write_text(target, doc.to_markdown())
         written.append(target)
     return written
 

package/src/devcouncil/knowledge/resource_discovery.py

@@ -0,0 +1,40 @@
+"""Knowledge source discovery for MCP resources and OKF selection."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from urllib.parse import quote
+
+logger = logging.getLogger(__name__)
+
+
+def knowledge_source_uri(kind: str, name: str) -> str:
+    """Stable, parseable resource URI for one ingested knowledge source."""
+    return f"devcouncil://knowledge/{kind}/{quote(name, safe='')}"
+
+
+def knowledge_settings(root: Path) -> tuple[str | None, bool]:
+    """Resolve (directory, design_always) for knowledge exposure from project config."""
+    try:
+        from devcouncil.app.config import load_config
+
+        cfg = load_config(root).knowledge
+        return (None if not cfg.enabled else cfg.directory), cfg.design_always
+    except Exception as exc:
+        logger.debug("Could not load knowledge settings for %s: %s", root, exc)
+        return ".devcouncil/knowledge", True
+
+
+def discover_knowledge_sources(root: Path) -> list:
+    """Best-effort enumeration of ingested OKF/design knowledge for the project."""
+    try:
+        from devcouncil.knowledge.sources import discover_knowledge_sources as _discover
+
+        directory, design_always = knowledge_settings(root)
+        if directory is None:
+            return []
+        return _discover(root, directory=directory, design_always=design_always)
+    except Exception as exc:
+        logger.debug("Knowledge source discovery failed for %s: %s", root, exc)
+        return []