devcouncil 0.3.1 → 0.4.1

package/src/devcouncil/codeintel/debug/broker.py

@@ -0,0 +1,114 @@
+"""Loopback JSON broker that keeps CLI debug sessions alive across invocations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import secrets
+import socketserver
+from pathlib import Path
+from typing import Any
+
+from devcouncil.codeintel.debug.session import get_debug_manager
+
+
+class BrokerServer(socketserver.ThreadingTCPServer):
+    allow_reuse_address = False
+    daemon_threads = True
+
+    def __init__(self, root: Path, token: str):
+        super().__init__(("127.0.0.1", 0), BrokerHandler)
+        self.root = root
+        self.token = token
+
+
+class BrokerHandler(socketserver.StreamRequestHandler):
+    def handle(self) -> None:
+        try:
+            request = json.loads(self.rfile.readline(4 * 1024 * 1024).decode("utf-8"))
+            if request.get("token") != self.server.token:  # type: ignore[attr-defined]
+                raise PermissionError("invalid debug broker token")
+            result = dispatch(self.server.root, str(request.get("action", "")), dict(request.get("params") or {}))  # type: ignore[attr-defined]
+            response = {"ok": True, "result": result}
+        except Exception as exc:
+            response = {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
+        self.wfile.write((json.dumps(response, default=str) + "\n").encode("utf-8"))
+
+
+def dispatch(root: Path, action: str, params: dict[str, Any]) -> Any:
+    manager = get_debug_manager()
+    if action == "ping":
+        return {"pid": os.getpid(), "sessions": manager.list()}
+    if action == "start":
+        session = manager.start(
+            root,
+            [str(value) for value in params["adapter_command"]],
+            request=str(params.get("request", "launch")),
+            arguments=dict(params.get("arguments") or {}),
+            initial_breakpoints={
+                str(source): [int(line) for line in lines]
+                for source, lines in dict(params.get("initial_breakpoints") or {}).items()
+            },
+            timeout=float(params.get("timeout", 30.0)),
+        )
+        return session.as_dict()
+    if action == "list":
+        return manager.list()
+    if action == "breakpoints":
+        return manager.set_breakpoints(str(params["session_id"]), str(params["source"]), params.get("lines") or [])
+    if action == "control":
+        return manager.control(
+            str(params["session_id"]),
+            str(params["debug_action"]),
+            thread_id=int(params["thread_id"]) if params.get("thread_id") is not None else None,
+        )
+    if action == "inspect":
+        return manager.inspect(str(params["session_id"]), str(params["operation"]), dict(params.get("arguments") or {}))
+    if action == "evaluate":
+        return manager.evaluate(
+            str(params["session_id"]),
+            str(params["expression"]),
+            frame_id=int(params["frame_id"]) if params.get("frame_id") is not None else None,
+            allow_side_effects=bool(params.get("allow_side_effects")),
+        )
+    if action == "capture_stack":
+        return manager.capture_stack(str(params["session_id"]), thread_id=int(params["thread_id"]))
+    if action == "stop":
+        manager.stop(str(params["session_id"]), terminate_debuggee=bool(params.get("terminate_debuggee", True)))
+        return {"stopped": params["session_id"]}
+    raise ValueError(f"unknown broker action: {action}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", type=Path, required=True)
+    ns = parser.parse_args()
+    root = ns.root.expanduser().resolve()
+    credential = secrets.token_urlsafe(32)
+    server = BrokerServer(root, credential)
+    state_path = root / ".devcouncil" / "codeintel" / "debug-broker.json"
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    state_path.write_text(json.dumps({
+        "pid": os.getpid(),
+        "host": "127.0.0.1",
+        "port": server.server_address[1],
+        "token": credential,
+    }), encoding="utf-8")
+    try:
+        state_path.chmod(0o600)
+    except OSError:
+        pass
+    try:
+        server.serve_forever(poll_interval=0.25)
+    finally:
+        server.server_close()
+        try:
+            state_path.unlink()
+        except OSError:
+            pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/devcouncil/codeintel/debug/broker_client.py

@@ -0,0 +1,61 @@
+"""Client/startup helper for the persistent local debug broker."""
+
+from __future__ import annotations
+
+import json
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+class DebugBrokerClient:
+    def __init__(self, root: Path):
+        self.root = root.expanduser().resolve()
+        self.state_path = self.root / ".devcouncil" / "codeintel" / "debug-broker.json"
+
+    def ensure_started(self, *, timeout: float = 5.0) -> None:
+        try:
+            self.call("ping", timeout=0.5)
+            return
+        except Exception:
+            pass
+        try:
+            self.state_path.unlink()
+        except OSError:
+            pass
+        subprocess.Popen(
+            [sys.executable, "-m", "devcouncil.codeintel.debug.broker", "--root", str(self.root)],
+            cwd=self.root,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            try:
+                self.call("ping", timeout=0.5)
+                return
+            except Exception:
+                time.sleep(0.05)
+        raise TimeoutError("debug broker did not start")
+
+    def call(self, action: str, params: dict[str, Any] | None = None, *, timeout: float = 30.0) -> Any:
+        state = json.loads(self.state_path.read_text(encoding="utf-8"))
+        request = json.dumps({"token": state["token"], "action": action, "params": params or {}}) + "\n"
+        with socket.create_connection((str(state["host"]), int(state["port"])), timeout=timeout) as sock:
+            sock.sendall(request.encode("utf-8"))
+            sock.settimeout(timeout)
+            chunks = bytearray()
+            while not chunks.endswith(b"\n"):
+                chunk = sock.recv(65536)
+                if not chunk:
+                    break
+                chunks.extend(chunk)
+        response = json.loads(bytes(chunks).decode("utf-8"))
+        if not response.get("ok"):
+            raise RuntimeError(str(response.get("error") or "debug broker request failed"))
+        return response.get("result")

package/src/devcouncil/codeintel/debug/consent.py

@@ -0,0 +1,36 @@
+"""Explicit one-time debugger consent stored in project configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+def debug_consent_enabled(root: Path) -> bool:
+    try:
+        from devcouncil.app.config import load_config
+
+        return bool(load_config(root).code_intelligence.debug.auto_discover)
+    except (FileNotFoundError, ValueError):
+        return False
+
+
+def set_debug_consent(root: Path, enabled: bool = True) -> Path:
+    path = root.expanduser().resolve() / ".devcouncil" / "config.yaml"
+    if not path.is_file():
+        raise FileNotFoundError(f"Config not found at {path}. Run 'dev init' first.")
+    raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    codeintel = raw.setdefault("code_intelligence", {})
+    debug = codeintel.setdefault("debug", {})
+    debug["auto_discover"] = bool(enabled)
+    path.write_text(yaml.safe_dump(raw, sort_keys=False), encoding="utf-8")
+    return path
+
+
+def require_debug_consent(root: Path) -> None:
+    if not debug_consent_enabled(root):
+        raise PermissionError(
+            "Debugger discovery/execution is disabled. Run `dev debug discover --consent` "
+            "or set code_intelligence.debug.auto_discover: true."
+        )

package/src/devcouncil/codeintel/debug/discovery.py

@@ -0,0 +1,132 @@
+"""Side-effect-free discovery of installed Debug Adapter Protocol adapters."""
+
+from __future__ import annotations
+
+import importlib.util
+import importlib.metadata
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from devcouncil.codeintel.debug.fingerprint import executable_hash
+
+
+@dataclass(frozen=True)
+class AdapterInfo:
+    id: str
+    name: str
+    command: tuple[str, ...]
+    path: str
+    executable_hash: str
+    version: str = ""
+    transport: str = "stdio"
+    languages: tuple[str, ...] = ()
+    requests: tuple[str, ...] = ("launch", "attach")
+
+    def as_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["command"] = list(self.command)
+        data["languages"] = list(self.languages)
+        data["requests"] = list(self.requests)
+        return data
+
+
+_EXECUTABLES = (
+    ("lldb-dap", "LLDB DAP", ("c", "cpp", "objective-c", "swift", "rust"), ("--version",)),
+    ("codelldb", "CodeLLDB", ("c", "cpp", "objective-c", "swift", "rust"), ("--version",)),
+    ("dlv", "Delve", ("go",), ("version",)),
+    ("netcoredbg", ".NET Core Debugger", ("csharp", "vbnet"), ("--version",)),
+    ("js-debug-adapter", "JavaScript Debugger", ("javascript", "typescript"), ("--version",)),
+    ("node-debug2", "Node Debug2", ("javascript", "typescript"), ("--version",)),
+    ("php-debug-adapter", "PHP Debug Adapter", ("php",), ("--version",)),
+)
+
+
+def _command_version(command: tuple[str, ...]) -> str:
+    """Run an adapter's non-mutating version command with a strict bound."""
+    try:
+        completed = subprocess.run(
+            list(command),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            timeout=2.0,
+            check=False,
+            text=True,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    lines = [line.strip() for line in completed.stdout.splitlines() if line.strip()]
+    return lines[0][:256] if lines else ""
+
+
+def discover_adapters() -> list[AdapterInfo]:
+    adapters: list[AdapterInfo] = []
+    if importlib.util.find_spec("debugpy") is not None:
+        # Preserve the virtual-environment interpreter path. Resolving its
+        # symlink can escape the environment that actually contains debugpy.
+        path = str(Path(sys.executable).absolute())
+        try:
+            version = importlib.metadata.version("debugpy")
+        except importlib.metadata.PackageNotFoundError:
+            version = ""
+        adapters.append(AdapterInfo(
+            id="debugpy",
+            name="Python debugpy",
+            command=(path, "-m", "debugpy.adapter"),
+            path=path,
+            executable_hash=executable_hash(path),
+            version=version,
+            languages=("python",),
+        ))
+    configured_node = os.environ.get("DEVCOUNCIL_NODE_DEBUG2_PATH")
+    node = shutil.which("node")
+    if configured_node and node:
+        adapter_path = str(Path(configured_node).expanduser().resolve())
+        if Path(adapter_path).is_file():
+            adapters.append(AdapterInfo(
+                id="node-debug2",
+                name="Node Debug2",
+                command=(str(Path(node).resolve()), adapter_path),
+                path=adapter_path,
+                executable_hash=executable_hash(adapter_path),
+                version=os.environ.get("DEVCOUNCIL_NODE_DEBUG2_VERSION", ""),
+                languages=("javascript", "typescript"),
+            ))
+    for executable, name, languages, version_args in _EXECUTABLES:
+        resolved = shutil.which(executable)
+        if resolved:
+            path = str(Path(resolved).resolve())
+            adapters.append(AdapterInfo(
+                id=executable,
+                name=name,
+                command=(path,),
+                path=path,
+                executable_hash=executable_hash(path),
+                version=_command_version((path, *version_args)),
+                languages=languages,
+            ))
+    return adapters
+
+
+def adapter_by_id(adapter_id: str) -> AdapterInfo | None:
+    return next((adapter for adapter in discover_adapters() if adapter.id == adapter_id), None)
+
+
+def adapter_by_command(command: tuple[str, ...] | list[str]) -> AdapterInfo | None:
+    if not command:
+        return None
+    executable = str(Path(command[0]).expanduser().resolve())
+    return next(
+        (
+            adapter
+            for adapter in discover_adapters()
+            if str(Path(adapter.command[0]).expanduser().resolve()) == executable
+            and tuple(command[1:]) == adapter.command[1:]
+        ),
+        None,
+    )

package/src/devcouncil/codeintel/debug/fingerprint.py

@@ -0,0 +1,85 @@
+"""Source, build, and executable fingerprints for runtime evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+from pathlib import Path
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def executable_hash(path: str | Path) -> str:
+    try:
+        return _sha256(Path(path).resolve().read_bytes())
+    except OSError:
+        return ""
+
+
+_GIT_TIMEOUT_SECONDS = 15.0
+_FALLBACK_SKIP_PARTS = frozenset({
+    ".git", ".devcouncil", "node_modules", "vendor", ".venv", "venv",
+    "dist", "build", "target", "__pycache__",
+})
+
+
+def source_fingerprint(root: Path) -> str:
+    root = root.expanduser().resolve()
+    head = b""
+    dirty = b""
+    try:
+        head = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"],
+            cwd=root,
+            stderr=subprocess.DEVNULL,
+            timeout=_GIT_TIMEOUT_SECONDS,
+        )
+        dirty = subprocess.check_output(
+            ["git", "diff", "--no-ext-diff", "--binary", "HEAD"],
+            cwd=root,
+            stderr=subprocess.DEVNULL,
+            timeout=_GIT_TIMEOUT_SECONDS,
+        )
+        untracked = subprocess.check_output(
+            ["git", "ls-files", "--others", "--exclude-standard", "-z"],
+            cwd=root,
+            stderr=subprocess.DEVNULL,
+            timeout=_GIT_TIMEOUT_SECONDS,
+        )
+        for raw_path in sorted(value for value in untracked.split(b"\0") if value):
+            path = root / raw_path.decode("utf-8", errors="surrogateescape")
+            try:
+                dirty += b"\0untracked:" + raw_path + b"\0" + _sha256(path.read_bytes()).encode()
+            except OSError:
+                continue
+    except (OSError, subprocess.SubprocessError):
+        for path in sorted(root.rglob("*")):
+            if not path.is_file() or _FALLBACK_SKIP_PARTS.intersection(path.parts):
+                continue
+            try:
+                stat = path.stat()
+                dirty += f"{path.relative_to(root).as_posix()}\0{stat.st_size}\0{stat.st_mtime_ns}\n".encode()
+            except OSError:
+                continue
+    return _sha256(head + b"\0" + dirty)
+
+
+def build_fingerprint(root: Path, executable: str | Path = "") -> str:
+    parts = [source_fingerprint(root).encode()]
+    for rel in (
+        ".devcouncil/config.yaml",
+        "pyproject.toml",
+        "package.json",
+        "Cargo.toml",
+        "go.mod",
+        "CMakeLists.txt",
+    ):
+        try:
+            parts.append((root / rel).read_bytes())
+        except OSError:
+            pass
+    if executable:
+        parts.append(executable_hash(executable).encode())
+    return _sha256(b"\0".join(parts))

package/src/devcouncil/codeintel/debug/protocol.py

@@ -0,0 +1,259 @@
+"""Capability-negotiated Debug Adapter Protocol client."""
+
+from __future__ import annotations
+
+import json
+import queue
+import socket
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, BinaryIO, Sequence, cast
+
+
+class DAPError(RuntimeError):
+    pass
+
+
+def encode_message(message: dict[str, Any]) -> bytes:
+    body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    return f"Content-Length: {len(body)}\r\n\r\n".encode("ascii") + body
+
+
+def read_message(stream: BinaryIO) -> dict[str, Any] | None:
+    headers: dict[str, str] = {}
+    while True:
+        line = stream.readline()
+        if not line:
+            return None
+        if line in {b"\r\n", b"\n"}:
+            break
+        key, _, value = line.decode("ascii", errors="replace").partition(":")
+        headers[key.strip().lower()] = value.strip()
+    try:
+        length = int(headers["content-length"])
+    except (KeyError, ValueError) as exc:
+        raise DAPError("DAP message is missing a valid Content-Length header") from exc
+    body = stream.read(length)
+    if len(body) != length:
+        raise DAPError("DAP stream ended mid-message")
+    parsed = json.loads(body.decode("utf-8"))
+    if not isinstance(parsed, dict):
+        raise DAPError("DAP message body must be an object")
+    return parsed
+
+
+@dataclass
+class PendingRequest:
+    sequence: int
+    responses: "queue.Queue[dict[str, Any]]"
+
+
+class DAPClient:
+    def __init__(
+        self,
+        reader: BinaryIO,
+        writer: BinaryIO,
+        *,
+        process: subprocess.Popen[bytes] | None = None,
+        sock: socket.socket | None = None,
+    ):
+        self.reader = reader
+        self.writer = writer
+        self.process = process
+        self.sock = sock
+        self.capabilities: dict[str, Any] = {}
+        self._sequence = 0
+        self._write_lock = threading.Lock()
+        self._pending: dict[int, queue.Queue[dict[str, Any]]] = {}
+        self._events: "queue.Queue[dict[str, Any]]" = queue.Queue()
+        self._closed = threading.Event()
+        self._reader_thread = threading.Thread(target=self._read_loop, name="devcouncil-dap-reader", daemon=True)
+        self._reader_thread.start()
+
+    @classmethod
+    def start_stdio(cls, command: Sequence[str], *, cwd: str | None = None) -> "DAPClient":
+        process = subprocess.Popen(
+            list(command),
+            cwd=cwd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+        )
+        if process.stdin is None or process.stdout is None:
+            process.kill()
+            raise DAPError("debug adapter did not expose stdio pipes")
+        return cls(cast(BinaryIO, process.stdout), cast(BinaryIO, process.stdin), process=process)
+
+    @classmethod
+    def connect_tcp(cls, host: str, port: int, *, timeout: float = 10.0) -> "DAPClient":
+        sock = socket.create_connection((host, port), timeout=timeout)
+        reader = sock.makefile("rb")
+        writer = sock.makefile("wb")
+        return cls(reader, writer, sock=sock)
+
+    def begin_request(self, command: str, arguments: dict[str, Any] | None = None) -> PendingRequest:
+        with self._write_lock:
+            self._sequence += 1
+            sequence = self._sequence
+            responses: "queue.Queue[dict[str, Any]]" = queue.Queue(maxsize=1)
+            self._pending[sequence] = responses
+            message = {
+                "seq": sequence,
+                "type": "request",
+                "command": command,
+                "arguments": arguments or {},
+            }
+            self.writer.write(encode_message(message))
+            self.writer.flush()
+        return PendingRequest(sequence, responses)
+
+    def wait_response(self, pending: PendingRequest, *, timeout: float = 15.0) -> dict[str, Any]:
+        try:
+            response = pending.responses.get(timeout=timeout)
+        except queue.Empty as exc:
+            self._pending.pop(pending.sequence, None)
+            raise TimeoutError(f"DAP request {pending.sequence} timed out") from exc
+        if not response.get("success", False):
+            message = response.get("message") or response.get("body", {}).get("error", {}).get("format")
+            raise DAPError(str(message or "debug adapter rejected request"))
+        return dict(response.get("body") or {})
+
+    def request(self, command: str, arguments: dict[str, Any] | None = None, *, timeout: float = 15.0) -> dict[str, Any]:
+        return self.wait_response(self.begin_request(command, arguments), timeout=timeout)
+
+    def initialize(self, *, client_name: str = "DevCouncil", adapter_id: str = "devcouncil") -> dict[str, Any]:
+        self.capabilities = self.request("initialize", {
+            "clientID": "devcouncil",
+            "clientName": client_name,
+            "adapterID": adapter_id,
+            "pathFormat": "path",
+            "linesStartAt1": True,
+            "columnsStartAt1": True,
+            "supportsVariableType": True,
+            "supportsVariablePaging": True,
+            "supportsRunInTerminalRequest": False,
+        })
+        return self.capabilities
+
+    def wait_event(
+        self,
+        event: str | None = None,
+        *,
+        timeout: float = 15.0,
+        fail_on: PendingRequest | None = None,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        deadline_items: list[dict[str, Any]] = []
+        while True:
+            if fail_on is not None:
+                try:
+                    response = fail_on.responses.get_nowait()
+                except queue.Empty:
+                    pass
+                else:
+                    fail_on.responses.put(response)
+                    if not response.get("success", False):
+                        self.wait_response(fail_on, timeout=0)
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                for item in deadline_items:
+                    self._events.put(item)
+                raise TimeoutError(f"DAP event {event or '*'} timed out")
+            try:
+                message = self._events.get(timeout=min(0.05, remaining) if fail_on is not None else remaining)
+            except queue.Empty as exc:
+                if fail_on is not None:
+                    continue
+                for item in deadline_items:
+                    self._events.put(item)
+                raise TimeoutError(f"DAP event {event or '*'} timed out") from exc
+            if event is None or message.get("event") == event:
+                for item in deadline_items:
+                    self._events.put(item)
+                return message
+            deadline_items.append(message)
+
+    def evaluate(
+        self,
+        expression: str,
+        *,
+        frame_id: int | None = None,
+        context: str = "repl",
+        allow_side_effects: bool = False,
+    ) -> dict[str, Any]:
+        if not allow_side_effects:
+            raise PermissionError("DAP evaluate may execute code; set allow_side_effects=True explicitly")
+        arguments: dict[str, Any] = {"expression": expression, "context": context}
+        if frame_id is not None:
+            arguments["frameId"] = frame_id
+        return self.request("evaluate", arguments)
+
+    def close(self) -> None:
+        if self._closed.is_set():
+            return
+        self._closed.set()
+        if self.sock is not None:
+            try:
+                self.sock.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+        try:
+            self.writer.close()
+        except OSError:
+            pass
+        try:
+            self.reader.close()
+        except OSError:
+            pass
+        if self.sock is not None:
+            self.sock.close()
+        if self.process is not None and self.process.poll() is None:
+            self.process.terminate()
+            try:
+                self.process.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+
+    def _read_loop(self) -> None:
+        try:
+            while not self._closed.is_set():
+                message = read_message(self.reader)
+                if message is None:
+                    break
+                message_type = message.get("type")
+                if message_type == "response":
+                    request_seq = int(message.get("request_seq", -1))
+                    responses = self._pending.pop(request_seq, None)
+                    if responses is not None:
+                        responses.put(message)
+                elif message_type == "event":
+                    self._events.put(message)
+                elif message_type == "request":
+                    self._respond_unsupported(message)
+        except Exception as exc:
+            error = {
+                "type": "response",
+                "success": False,
+                "message": f"DAP transport failed: {type(exc).__name__}: {exc}",
+            }
+            for responses in list(self._pending.values()):
+                responses.put(error)
+            self._pending.clear()
+        finally:
+            self._closed.set()
+
+    def _respond_unsupported(self, request: dict[str, Any]) -> None:
+        with self._write_lock:
+            self._sequence += 1
+            response = {
+                "seq": self._sequence,
+                "type": "response",
+                "request_seq": request.get("seq"),
+                "success": False,
+                "command": request.get("command"),
+                "message": "DevCouncil does not support this reverse request",
+            }
+            self.writer.write(encode_message(response))
+            self.writer.flush()