devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/cloud/client_config.py

@@ -0,0 +1,472 @@
+"""Install DevTorch MCP client configuration for various editors.
+
+This module is shared by the ``devtorch cloud client-config`` CLI command and
+the legacy ``install-client-config.sh`` wrapper. It copies the right IDE
+template, substitutes org/repo/api-key/domain, and updates ``AGENTS.md`` with
+the required DevTorch governance instructions.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SUPPORTED_IDES = ["opencode", "claude", "cursor", "vscode", "stdio"]
+
+PLACEHOLDER_DOMAIN = "devtorch-mcp.YOUR-DOMAIN.com"
+
+# Files shipped with this package under devtorch_core/cloud/
+_PACKAGE_DIR = Path(__file__).resolve().parent
+CLIENT_CONFIG_DIR = _PACKAGE_DIR / "client_configs"
+BRIDGE_SCRIPT = _PACKAGE_DIR / "devtorch-mcp-bridge.js"
+
+AGENTS_MD_BLOCK = """## DevTorch — Reasoning Capture
+
+This project uses DevTorch for AI governance. These steps are mandatory for all agent actions.
+
+### At the start of every task
+
+Call `devtorch_context` (MCP tool) before reading files or writing code:
+- Tool: `devtorch_context`
+- Args: `{ "max_tokens": 2000 }`
+
+Use the returned context to understand prior decisions before proceeding.
+
+### Before writing or editing any code
+
+Call `devtorch_commit` before the first file write:
+- Tool: `devtorch_commit`
+- Args: `{ "message": "<what you decided and WHY — include alternatives considered>", "branch": "<optional branch name>" }`
+
+The message must explain the *why*, not just the *what*.
+"Added login endpoint" is not acceptable.
+"Chose JWT over sessions because the service is stateless" is.
+
+### When touching sensitive areas
+
+Call `devtorch_sensitivity_add` for auth, payments, database schema, secrets, PII, external APIs:
+- Tool: `devtorch_sensitivity_add`
+- Args: `{ "concept": "<auth|schema|payments|secrets|pii|api|security|config>", "signal": "<what this decision depends on / counterfactual text>", "confidence": 0.0–1.0, "disclosure": "PUBLIC|PROTECTED|PRIVATE" }`
+
+| Level | Use when |
+|---|---|
+| PUBLIC | General design decisions |
+| PROTECTED | Internal implementation, business logic |
+| PRIVATE | Credentials, PII, secrets |
+
+### If MCP tools fail
+
+If `devtorch_commit` or `devtorch_sensitivity_add` returns an MCP error (timeout, connection failure, or server error), the agent must fall back to the local CLI so the `.GCC/` audit trail is never lost:
+
+- `devtorch commit -m "<reasoning message>"`
+- `devtorch sensitivity add --source mcp-fallback --concept <concept> --confidence <confidence> --counterfactuals "<signal>" --message "<signal>" --disclosure <PUBLIC|PROTECTED|PRIVATE>`
+
+For IDEs using the DevTorch MCP bridge, this fallback is automatic.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def install_client_config(
+    ide: str,
+    org: str,
+    repo: str,
+    api_key: str,
+    domain: str | None = None,
+    project_root: str | Path | None = None,
+    use_env_key: bool = False,
+) -> dict[str, str | Path]:
+    """Install the DevTorch MCP client config and AGENTS.md for an IDE.
+
+    Args:
+        ide: Target IDE. One of ``opencode``, ``claude``, ``cursor``, ``vscode``,
+            ``stdio``.
+        org: DevTorch org ID.
+        repo: DevTorch repo ID.
+        api_key: API key created via ``devtorch cloud key create``.
+        domain: Cloudflare Worker domain. Defaults to ``DEVTORCH_MCP_DOMAIN``
+            env var, or ``devtorch-mcp.YOUR-DOMAIN.com`` as a placeholder.
+        project_root: Directory to install into. Defaults to the current working
+            directory.
+        use_env_key: For the ``claude``/``stdio`` targets, write
+            ``${DEVTORCH_API_KEY}`` instead of the literal key — Claude Code
+            expands env vars in ``.mcp.json``, so the secret never touches a
+            committable file. The user must export ``DEVTORCH_API_KEY``.
+
+    Returns:
+        A dict with ``url``, ``installed_file``, and ``domain``. May include
+        ``warning`` (placeholder domain) and ``secret_warning`` (literal key
+        written inside a git repo with no matching gitignore entry).
+    """
+    if ide not in SUPPORTED_IDES:
+        raise ValueError(
+            f"Unsupported IDE: {ide!r}. Supported: {', '.join(SUPPORTED_IDES)}"
+        )
+
+    domain = _resolve_domain(domain)
+    root = Path(project_root or ".").resolve()
+    url = f"https://{domain}/{org}/{repo}/sse"
+
+    if ide == "opencode":
+        target = root / "opencode.json"
+        _render_template(
+            CLIENT_CONFIG_DIR / ".opencode.json",
+            target,
+            domain=domain,
+            org=org,
+            repo=repo,
+            api_key=api_key,
+            project_root=root,
+            bridge_script=str(BRIDGE_SCRIPT),
+        )
+    elif ide == "claude":
+        target = _install_claude_mcp_json(
+            root, domain=domain, org=org, repo=repo, api_key=api_key,
+            use_env_key=use_env_key,
+        )
+    elif ide == "cursor":
+        target_dir = root / ".cursor"
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target = target_dir / "mcp.json"
+        _render_template(
+            CLIENT_CONFIG_DIR / ".cursor-mcp.json",
+            target,
+            domain=domain,
+            org=org,
+            repo=repo,
+            api_key=api_key,
+            project_root=root,
+        )
+    elif ide == "vscode":
+        target_dir = root / ".vscode"
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target = target_dir / "mcp.json"
+        _render_template(
+            CLIENT_CONFIG_DIR / ".vscode-mcp.json",
+            target,
+            domain=domain,
+            org=org,
+            repo=repo,
+            api_key=api_key,
+            project_root=root,
+            bridge_script=str(BRIDGE_SCRIPT),
+        )
+    elif ide == "stdio":
+        # stdio target is the same as claude for the bridge-based config.
+        target = _install_claude_mcp_json(
+            root, domain=domain, org=org, repo=repo, api_key=api_key,
+            use_env_key=use_env_key,
+        )
+    else:
+        # This branch is unreachable because of the earlier validation,
+        # but it keeps type checkers and linters happy.
+        raise ValueError(f"Unsupported IDE: {ide!r}")
+
+    _install_agents_md(root)
+
+    result: dict[str, str | Path] = {"url": url, "installed_file": target, "domain": domain}
+    if domain == PLACEHOLDER_DOMAIN:
+        result["warning"] = (
+            f"MCP domain is the placeholder '{PLACEHOLDER_DOMAIN}' — the server will "
+            "be listed but can never connect. Re-run with --domain <your-worker-domain> "
+            "or set DEVTORCH_MCP_DOMAIN."
+        )
+    if use_env_key and ide not in ("claude", "stdio"):
+        result["warning_use_env_key"] = (
+            f"--use-env-key only applies to the claude/stdio targets; the {ide} "
+            "config still contains the literal API key."
+        )
+    secret_warning = _committable_secret_warning(
+        root,
+        Path(target),
+        api_key,
+        suggest_env_key=ide in ("claude", "stdio") and not use_env_key,
+    )
+    if secret_warning:
+        result["secret_warning"] = secret_warning
+    return result
+
+
+def _find_git_root(path: Path) -> Path | None:
+    """Return the nearest ancestor (including *path*) containing .git."""
+    for candidate in (path, *path.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return None
+
+
+def _committable_secret_warning(
+    root: Path, target: Path, api_key: str, *, suggest_env_key: bool = True
+) -> str | None:
+    """
+    Return a warning when a literal API key was written into a file that git
+    could commit. This exact gap is how a live key was committed once.
+
+    ``git check-ignore`` is the authority when git is available (it evaluates
+    globs, anchoring, and negation correctly); a simple pattern match against
+    the top-level .gitignore is the fallback.
+    """
+    git_root = _find_git_root(root)
+    if git_root is None:
+        return None
+    try:
+        if api_key not in target.read_text(encoding="utf-8"):
+            return None
+    except OSError:
+        return None
+    try:
+        rel = target.relative_to(git_root).as_posix()
+    except ValueError:
+        rel = target.name
+    if _is_git_ignored(git_root, rel):
+        return None
+    hint = " (or re-run with --use-env-key)" if suggest_env_key else ""
+    return (
+        f"{rel} now contains your API key and is inside a git repository with no "
+        f"matching gitignore rule — add '{rel}' to .gitignore{hint} so the key "
+        "cannot be committed."
+    )
+
+
+def _is_git_ignored(git_root: Path, rel: str) -> bool:
+    import fnmatch
+    import subprocess
+
+    try:
+        proc = subprocess.run(
+            ["git", "-C", str(git_root), "check-ignore", "-q", rel],
+            capture_output=True,
+            timeout=5,
+        )
+        # 0 = ignored, 1 = not ignored; anything else means git could not
+        # answer (not a real repo, git missing) — fall through to heuristic.
+        if proc.returncode in (0, 1):
+            return proc.returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+    try:
+        lines = (git_root / ".gitignore").read_text(encoding="utf-8").splitlines()
+    except (FileNotFoundError, OSError):
+        return False
+    patterns = [
+        line.strip().lstrip("/").rstrip("/")
+        for line in lines
+        if line.strip() and not line.strip().startswith(("#", "!"))
+    ]
+    parts = rel.split("/")
+    candidates = {rel, parts[-1], *("/".join(parts[: i + 1]) for i in range(len(parts)))}
+    return any(fnmatch.fnmatch(c, pat) for c in candidates for pat in patterns)
+
+
+def _resolve_domain(domain: str | None) -> str:
+    if domain:
+        return _normalize_domain(domain)
+    env_domain = os.environ.get("DEVTORCH_MCP_DOMAIN", "").strip()
+    if env_domain:
+        return _normalize_domain(env_domain)
+    return PLACEHOLDER_DOMAIN
+
+
+def _normalize_domain(domain: str) -> str:
+    """
+    Accept a domain given with its scheme or a trailing slash.
+
+    The generated URL prepends ``https://`` to the domain, so a value like
+    ``https://devtorch-mcp.example.com`` would otherwise render as
+    ``https://https://...`` — which MCP bridges fail on with an opaque
+    "Connection closed" error.
+    """
+    domain = domain.strip()
+    for scheme in ("https://", "http://"):
+        if domain.lower().startswith(scheme):
+            domain = domain[len(scheme):]
+            break
+    return domain.rstrip("/")
+
+
+def _install_claude_mcp_json(
+    root: Path,
+    *,
+    domain: str,
+    org: str,
+    repo: str,
+    api_key: str,
+    use_env_key: bool = False,
+) -> Path:
+    """
+    Merge the DevTorch bridge server into <root>/.mcp.json.
+
+    Claude Code reads project-scope MCP servers only from .mcp.json at the
+    project root — a mcpServers key in .claude/settings.json is ignored.
+    Preserves other servers already in .mcp.json, overwrites the devtorch
+    entry (client-config is an explicit reconfiguration), and removes a
+    devtorch entry stranded in .claude/settings.json by older versions.
+    """
+    rendered = _render_text(
+        CLIENT_CONFIG_DIR / ".claude-stdio.json",
+        domain=domain,
+        org=org,
+        repo=repo,
+        api_key=api_key,
+        project_root=root,
+        bridge_script=str(BRIDGE_SCRIPT),
+    )
+    entry = json.loads(rendered)["mcpServers"]["devtorch"]
+    if use_env_key:
+        # Claude Code expands ${VAR} in .mcp.json env values, so the secret
+        # stays out of the file entirely; the user must export it.
+        entry["env"]["DEVTORCH_API_KEY"] = "${DEVTORCH_API_KEY}"
+
+    from devtorch_core.hooks.installer import (
+        _pop_legacy_settings_mcp_entry,
+        _read_json_dict_or_backup,
+    )
+
+    target = root / ".mcp.json"
+    existing: dict = {}
+    if target.exists():
+        existing = _read_json_dict_or_backup(target)
+    existing.setdefault("mcpServers", {})["devtorch"] = entry
+    target.write_text(json.dumps(existing, indent=2), encoding="utf-8")
+
+    _pop_legacy_settings_mcp_entry(root)
+    return target
+
+
+def _render_text(
+    template: Path,
+    *,
+    domain: str,
+    org: str,
+    repo: str,
+    api_key: str,
+    project_root: str | Path,
+    bridge_script: str | None = None,
+) -> str:
+    text = template.read_text(encoding="utf-8")
+    text = text.replace("devtorch-mcp.YOUR-DOMAIN.com", domain)
+    text = text.replace("YOUR_ORG", org)
+    text = text.replace("YOUR_REPO", repo)
+    text = text.replace("YOUR_API_KEY", api_key)
+    text = text.replace(
+        '"__PROJECT_ROOT__"',
+        json.dumps(str(project_root).replace("\\", "/")),
+    )
+    if bridge_script is not None:
+        text = text.replace(
+            "/ABSOLUTE/PATH/TO/deploy/cloudflare-worker/devtorch-mcp-bridge.js",
+            bridge_script,
+        )
+    return text
+
+
+def _render_template(
+    template: Path,
+    target: Path,
+    *,
+    domain: str,
+    org: str,
+    repo: str,
+    api_key: str,
+    project_root: str | Path,
+    bridge_script: str | None = None,
+) -> None:
+    target.write_text(
+        _render_text(
+            template,
+            domain=domain,
+            org=org,
+            repo=repo,
+            api_key=api_key,
+            project_root=project_root,
+            bridge_script=bridge_script,
+        ),
+        encoding="utf-8",
+    )
+
+
+# A DevTorch governance block at any heading level counts as "already
+# installed" — a project may promote the block to an H1 (as the DevTorch repo
+# itself does), and appending our H2 copy next to it would duplicate it.
+_DEVTORCH_HEADING_RE = re.compile(r"^#{1,6}\s+DevTorch\b", re.MULTILINE)
+
+
+def _install_agents_md(root: Path) -> tuple[str, Path]:
+    path = root / "AGENTS.md"
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        content = ""
+
+    if re.search(r"^## DevTorch", content, re.MULTILINE):
+        # Replace the H2 block we authored, preserving everything before and
+        # after. The block ends at the next H1/H2 heading or EOF — H3+
+        # headings are part of the block itself, but a coexisting customized
+        # H1 block must survive the replacement.
+        pattern = re.compile(
+            r"^## DevTorch.*?(?=^#{1,2} |\Z)", re.DOTALL | re.MULTILINE
+        )
+        new_content = pattern.sub(AGENTS_MD_BLOCK.rstrip() + "\n", content)
+        action = "Updated"
+    elif _DEVTORCH_HEADING_RE.search(content):
+        # Governance block exists at a heading level we didn't author (e.g.
+        # H1). Leave the customized block untouched.
+        return "Kept", path
+    else:
+        if content and not content.endswith("\n"):
+            content += "\n"
+        if content:
+            content += "\n"
+        new_content = content + AGENTS_MD_BLOCK.rstrip() + "\n"
+        action = "Installed"
+
+    path.write_text(new_content, encoding="utf-8")
+    return action, path
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point (used by the legacy bash wrapper)
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Legacy CLI entry point matching ``install-client-config.sh <ide> <org> <repo> <api-key>``."""
+    import sys
+
+    args = argv if argv is not None else sys.argv[1:]
+    if len(args) < 4:
+        print("Usage: install-client-config.sh <ide> <org> <repo> <api-key>")
+        print("  ide: opencode | claude | cursor | vscode | stdio")
+        return 1
+
+    ide, org, repo, api_key = args[:4]
+    try:
+        result = install_client_config(ide, org, repo, api_key)
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    print(f"Installed {result['installed_file']}")
+    print(f"DevTorch MCP URL: {result['url']}")
+    if "warning" in result:
+        print(f"WARNING: {result['warning']}", file=sys.stderr)
+    if "warning_use_env_key" in result:
+        print(f"WARNING: {result['warning_use_env_key']}", file=sys.stderr)
+    if "secret_warning" in result:
+        print(f"WARNING: {result['secret_warning']}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devtorch_core/cloud/client_configs/.claude-opencode-fallback.json

@@ -0,0 +1,8 @@
+{
+  "mcp": {
+    "devtorch": {
+      "command": "echo",
+      "args": ["OpenCode uses the SSE config in opencode.json for DevTorch"]
+    }
+  }
+}

devtorch_core/cloud/client_configs/.claude-stdio.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "devtorch": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/deploy/cloudflare-worker/devtorch-mcp-bridge.js"],
+      "env": {
+        "DEVTORCH_MCP_URL": "https://devtorch-mcp.YOUR-DOMAIN.com/YOUR_ORG/YOUR_REPO/sse",
+        "DEVTORCH_API_KEY": "YOUR_API_KEY",
+        "DEVTORCH_GCC_PATH": "__PROJECT_ROOT__"
+      }
+    }
+  }
+}

devtorch_core/cloud/client_configs/.cursor-mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "devtorch": {
+      "url": "https://devtorch-mcp.YOUR-DOMAIN.com/YOUR_ORG/YOUR_REPO/sse",
+      "headers": {
+        "X-DevTorch-Key": "YOUR_API_KEY"
+      },
+      "env": {
+        "DEVTORCH_GCC_PATH": "__PROJECT_ROOT__"
+      }
+    }
+  }
+}

devtorch_core/cloud/client_configs/.opencode-bridge.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "devtorch": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/deploy/cloudflare-worker/devtorch-mcp-bridge.js"],
+      "env": {
+        "DEVTORCH_MCP_URL": "https://devtorch-mcp.YOUR-DOMAIN.com/YOUR_ORG/YOUR_REPO/sse",
+        "DEVTORCH_API_KEY": "YOUR_API_KEY",
+        "DEVTORCH_GCC_PATH": "__PROJECT_ROOT__"
+      }
+    }
+  }
+}

devtorch_core/cloud/client_configs/.opencode.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "devtorch": {
+      "type": "local",
+      "enabled": true,
+      "command": ["node", "/ABSOLUTE/PATH/TO/deploy/cloudflare-worker/devtorch-mcp-bridge.js"],
+      "environment": {
+        "DEVTORCH_MCP_URL": "https://devtorch-mcp.YOUR-DOMAIN.com/YOUR_ORG/YOUR_REPO/sse",
+        "DEVTORCH_API_KEY": "YOUR_API_KEY",
+        "DEVTORCH_GCC_PATH": "__PROJECT_ROOT__"
+      }
+    }
+  }
+}

devtorch_core/cloud/client_configs/.vscode-mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "devtorch": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/deploy/cloudflare-worker/devtorch-mcp-bridge.js"],
+      "env": {
+        "DEVTORCH_MCP_URL": "https://devtorch-mcp.YOUR-DOMAIN.com/YOUR_ORG/YOUR_REPO/sse",
+        "DEVTORCH_API_KEY": "YOUR_API_KEY",
+        "DEVTORCH_GCC_PATH": "__PROJECT_ROOT__"
+      }
+    }
+  }
+}