spawn-cli 0.1.1__py3-none-any.whl

spawn_cli/ide/_vacancy.py

@@ -0,0 +1,221 @@
+"""Detect vacant IDE-managed filesystem trees after teardown (skills/MCP removals)."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+
+def json_value_nonempty(v: object) -> bool:
+    """True if nested JSON-ish value carries user-visible substance."""
+    if v is None:
+        return False
+    if isinstance(v, dict):
+        return len(v) > 0
+    if isinstance(v, list):
+        return len(v) > 0
+    if isinstance(v, str):
+        return bool(v.strip())
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, (int, float)):
+        return v != 0
+    return True
+
+
+def mcp_json_mcp_servers_format_is_empty(path: Path) -> bool:
+    """True when path is Cursor or Claude-root style JSON ({mcpServers?: ...})."""
+    if not path.is_file():
+        return False
+    try:
+        raw = path.read_text(encoding="utf-8")
+        data = json.loads(raw)
+    except (OSError, json.JSONDecodeError):
+        return False
+    if not isinstance(data, dict):
+        return False
+    if data == {}:
+        return True
+    servers = data.get("mcpServers")
+    srv_empty = servers in (None, {}) or (isinstance(servers, dict) and len(servers) == 0)
+    if not srv_empty:
+        return False
+    for k, v in data.items():
+        if k != "mcpServers" and json_value_nonempty(v):
+            return False
+    return True
+
+
+def vscode_servers_mcp_json_is_empty(path: Path) -> bool:
+    """True when path is VS Code MCP format (`servers`, `inputs`). Used for .vscode/mcp.json."""
+    if not path.is_file():
+        return False
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    if not isinstance(data, dict):
+        return False
+    if data == {}:
+        return True
+    servers = data.get("servers")
+    srv_empty = servers in (None, {}) or (isinstance(servers, dict) and len(servers) == 0)
+    inputs = data.get("inputs")
+    inp_empty = inputs in (None, []) or (isinstance(inputs, list) and len(inputs) == 0)
+    if not (srv_empty and inp_empty):
+        return False
+    for k, v in data.items():
+        if k not in ("servers", "inputs") and json_value_nonempty(v):
+            return False
+    return True
+
+
+def dir_has_any_file(root: Path) -> bool:
+    """True if any regular file exists under root."""
+    if not root.is_dir():
+        return False
+    try:
+        for p in root.rglob("*"):
+            if p.is_file():
+                return True
+    except OSError:
+        return True
+    return False
+
+
+def prune_empty_directories_under(container: Path) -> None:
+    """Remove descendant directories bottom-up while empty (excluding container itself)."""
+    if not container.is_dir():
+        return
+    dirs = [p for p in container.rglob("*") if p.is_dir()]
+    dirs.sort(key=lambda p: len(p.parts), reverse=True)
+    for d in dirs:
+        try:
+            if not any(d.iterdir()):
+                d.rmdir()
+        except OSError:
+            pass
+
+
+def ide_dotdir_is_entirely_removable(root: Path, *, allow_delete_entire: bool) -> bool:
+    """
+    Whole-directory removal permitted only when enabled and container has zero files beneath.
+    """
+    if not allow_delete_entire or not root.exists():
+        return False
+    return not dir_has_any_file(root)
+
+
+def try_unlink_empty_mcp_mcp_servers(path: Path) -> None:
+    if mcp_json_mcp_servers_format_is_empty(path):
+        path.unlink(missing_ok=True)
+
+
+def try_unlink_empty_vscode_mcp(path: Path) -> None:
+    if vscode_servers_mcp_json_is_empty(path):
+        path.unlink(missing_ok=True)
+
+
+def finalize_standard_dotdir_skills_and_mcp(
+    target_root: Path,
+    rel_dir: str,
+    *,
+    allow_delete_entire: bool,
+    unlink_settings_json_when_mcp_servers_empty: bool = False,
+) -> None:
+    """Shared layout: IDE dotdir plus optional MCP JSON files."""
+    root = target_root / rel_dir
+    if not root.is_dir():
+        return
+    try_unlink_empty_mcp_mcp_servers(root / "mcp.json")
+    if unlink_settings_json_when_mcp_servers_empty:
+        sj = root / "settings.json"
+        if sj.is_file():
+            try_unlink_empty_mcp_mcp_servers(sj)
+    prune_empty_directories_under(root)
+    if ide_dotdir_is_entirely_removable(root, allow_delete_entire=allow_delete_entire):
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def claude_root_mcp_maybe_unlink(target_root: Path) -> None:
+    try_unlink_empty_mcp_mcp_servers(target_root / ".mcp.json")
+
+
+def claude_settings_maybe_unlink(path: Path) -> None:
+    if not path.is_file():
+        return
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return
+    if data == {}:
+        path.unlink(missing_ok=True)
+        return
+    if not isinstance(data, dict):
+        return
+    perm = data.get("permissions")
+    if isinstance(perm, dict) and perm.get("deny") == [] and set(data.keys()) == {"permissions"}:
+        if set(perm.keys()) <= {"deny"}:
+            path.unlink(missing_ok=True)
+
+
+def finalize_claude_repo(target_root: Path) -> None:
+    """Claude adapter: repo `.mcp.json`, `.claude/{skills,settings,...}`, drop `.claude` if vacant."""
+    claude_root_mcp_maybe_unlink(target_root)
+    settings = target_root / ".claude" / "settings.json"
+    claude_settings_maybe_unlink(settings)
+    finalize_standard_dotdir_skills_and_mcp(
+        target_root,
+        ".claude",
+        allow_delete_entire=True,
+        unlink_settings_json_when_mcp_servers_empty=False,
+    )
+
+
+def finalize_codex_repo(target_root: Path) -> None:
+    from spawn_cli.io.toml_io import load_toml
+
+    agents = target_root / ".agents"
+    codex_cfg = target_root / ".codex" / "config.toml"
+    if codex_cfg.is_file():
+        data = load_toml(codex_cfg)
+        if isinstance(data, dict) and (
+            data == {} or (set(data.keys()) <= {"mcp_servers"} and not data.get("mcp_servers"))
+        ):
+            codex_cfg.unlink(missing_ok=True)
+    prune_empty_directories_under(codex_cfg.parent)
+    prune_empty_directories_under(agents)
+    codex_root = target_root / ".codex"
+    try:
+        if codex_root.is_dir() and not any(codex_root.iterdir()):
+            codex_root.rmdir()
+    except OSError:
+        pass
+    if agents.is_dir() and not dir_has_any_file(agents):
+        shutil.rmtree(agents, ignore_errors=True)
+
+
+def finalize_github_copilot_repo(target_root: Path) -> None:
+    try_unlink_empty_vscode_mcp(target_root / ".vscode" / "mcp.json")
+    prune_empty_directories_under(target_root / ".github" / "skills")
+    sk = target_root / ".github" / "skills"
+    try:
+        if sk.is_dir() and not any(sk.iterdir()):
+            sk.rmdir()
+    except OSError:
+        pass
+
+
+__all__ = [
+    "dir_has_any_file",
+    "finalize_claude_repo",
+    "finalize_codex_repo",
+    "finalize_github_copilot_repo",
+    "finalize_standard_dotdir_skills_and_mcp",
+    "ide_dotdir_is_entirely_removable",
+    "json_value_nonempty",
+    "mcp_json_mcp_servers_format_is_empty",
+    "prune_empty_directories_under",
+    "vscode_servers_mcp_json_is_empty",
+]

spawn_cli/ide/claude_code.py

@@ -0,0 +1,145 @@
+"""Anthropic Claude Code IDE adapter: .claude/skills, root .mcp.json, settings permissions, CLAUDE.md."""
+
+from __future__ import annotations
+
+import json
+import warnings
+from pathlib import Path
+
+from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.registry import (
+    DetectResult,
+    IdeAdapter,
+    IdeCapabilities,
+    register,
+    normalize_skill_name,
+    render_skill_md,
+    rewrite_managed_block,
+)
+from spawn_cli.models.mcp import McpServer, NormalizedMcp
+from spawn_cli.models.skill import SkillMetadata
+
+
+def _build_generic_mcp_entry(server: McpServer) -> dict:
+    transport = server.transport
+    if transport.type == "stdio":
+        entry: dict = {"command": transport.command, "args": list(transport.args)}
+    elif transport.type in ("streamable-http", "sse"):
+        entry = {"type": transport.type, "url": transport.url}
+        if transport.headers:
+            entry["headers"] = {k: f"${{{v}}}" for k, v in transport.headers.items()}
+    else:
+        entry = {"command": transport.command, "args": list(transport.args)}
+    if server.env:
+        entry["env"] = {
+            k: f"${{{k}}}" if v.secret else v.value or f"${{{k}}}"
+            for k, v in server.env.items()
+        }
+    return entry
+
+
+class ClaudeCodeAdapter(IdeAdapter):
+    key = "claude-code"
+
+    def detect(self, target_root: Path) -> DetectResult:
+        used = (target_root / ".claude").exists() or (target_root / "CLAUDE.md").exists()
+        return DetectResult(
+            used_in_repo=used,
+            capabilities=IdeCapabilities(
+                skills="native",
+                mcp="project",
+                agent_ignore="project",
+                entry_point="claude-md",
+            ),
+        )
+
+    def add_skills(self, target_root: Path, skill_metadata: list[SkillMetadata]) -> list[dict]:
+        results = []
+        for skill in skill_metadata:
+            name = normalize_skill_name(skill.name)
+            skill_dir = target_root / ".claude" / "skills" / name
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            skill_path = skill_dir / "SKILL.md"
+            if skill_path.exists():
+                warnings.warn(f"Overwriting existing rendered skill: {skill_path}")
+            skill_path.write_text(render_skill_md(skill), encoding="utf-8")
+            rel = skill_path.relative_to(target_root).as_posix()
+            results.append({"skill": skill.name, "path": rel})
+        return results
+
+    def remove_skills(self, target_root: Path, rendered_paths: list[dict]) -> None:
+        for entry in rendered_paths:
+            p = target_root / entry["path"]
+            if p.exists():
+                p.unlink()
+            if p.parent.exists() and not any(p.parent.iterdir()):
+                p.parent.rmdir()
+
+    def add_mcp(self, target_root: Path, normalized_mcp: NormalizedMcp) -> list[str]:
+        mcp_path = target_root / ".mcp.json"
+        data = json.loads(mcp_path.read_text(encoding="utf-8")) if mcp_path.exists() else {}
+        data.setdefault("mcpServers", {})
+        rendered_names = []
+        for server in normalized_mcp.servers:
+            data["mcpServers"][server.name] = _build_generic_mcp_entry(server)
+            rendered_names.append(server.name)
+        mcp_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        return rendered_names
+
+    def remove_mcp(self, target_root: Path, rendered_mcp_names: list[str]) -> None:
+        mcp_path = target_root / ".mcp.json"
+        if not mcp_path.exists():
+            return
+        data = json.loads(mcp_path.read_text(encoding="utf-8"))
+        for name in rendered_mcp_names:
+            data.get("mcpServers", {}).pop(name, None)
+        mcp_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def add_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        settings_path = target_root / ".claude" / "settings.json"
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        data = json.loads(settings_path.read_text(encoding="utf-8")) if settings_path.exists() else {}
+        perms = data.setdefault("permissions", {})
+        deny = perms.setdefault("deny", [])
+        if not isinstance(deny, list):
+            deny_list: list = []
+            perms["deny"] = deny_list
+        else:
+            deny_list = deny
+        for glob in globs:
+            if glob not in deny_list:
+                deny_list.append(glob)
+        settings_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        settings_path = target_root / ".claude" / "settings.json"
+        if not settings_path.exists():
+            return
+        data = json.loads(settings_path.read_text(encoding="utf-8"))
+        perms = data.get("permissions")
+        if not isinstance(perms, dict):
+            return
+        deny = perms.get("deny")
+        if not isinstance(deny, list):
+            return
+        drop = set(globs)
+        perms["deny"] = [g for g in deny if g not in drop]
+        settings_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
+        ep = target_root / "CLAUDE.md"
+        if (target_root / ".claude" / "CLAUDE.md").exists():
+            warnings.warn(
+                "Claude Code: .claude/CLAUDE.md exists but Spawn writes to repo-root CLAUDE.md. "
+                "Update .claude/CLAUDE.md manually if needed."
+            )
+        rewrite_managed_block(ep, prompt)
+        return ep.relative_to(target_root).as_posix()
+
+    def finalize_repo_after_ide_removed(self, target_root: Path) -> None:
+        _vac.finalize_claude_repo(target_root)
+
+
+register(ClaudeCodeAdapter())
+
+__all__ = ["ClaudeCodeAdapter"]

spawn_cli/ide/codex.py

@@ -0,0 +1,120 @@
+"""OpenAI Codex IDE adapter: skills under .agents/, MCP in .codex/config.toml, AGENTS.md."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+
+from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.registry import (
+    DetectResult,
+    IdeAdapter,
+    IdeCapabilities,
+    register,
+    normalize_skill_name,
+    render_skill_md,
+    rewrite_managed_block,
+)
+from spawn_cli.io.toml_io import load_toml, save_toml
+from spawn_cli.models.mcp import McpServer, NormalizedMcp
+from spawn_cli.models.skill import SkillMetadata
+
+
+def _build_toml_server_entry(server: McpServer) -> dict:
+    transport = server.transport
+    entry: dict = {}
+    if transport.type == "stdio":
+        entry["command"] = transport.command
+        entry["args"] = list(transport.args)
+    else:
+        entry["url"] = transport.url
+    if server.env:
+        entry["env"] = {
+            k: f"${{{k}}}" if v.secret else (v.value or f"${{{k}}}")
+            for k, v in server.env.items()
+        }
+    return entry
+
+
+class CodexAdapter(IdeAdapter):
+    key = "codex"
+
+    def detect(self, target_root: Path) -> DetectResult:
+        used = (target_root / ".codex").exists() or (target_root / ".agents").exists()
+        return DetectResult(
+            used_in_repo=used,
+            capabilities=IdeCapabilities(
+                skills="native",
+                mcp="project",
+                agent_ignore="unsupported",
+                entry_point="agents-md",
+            ),
+        )
+
+    def add_skills(self, target_root: Path, skill_metadata: list[SkillMetadata]) -> list[dict]:
+        results = []
+        for skill in skill_metadata:
+            name = normalize_skill_name(skill.name)
+            skill_dir = target_root / ".agents" / "skills" / name
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            skill_path = skill_dir / "SKILL.md"
+            if skill_path.exists():
+                warnings.warn(f"Overwriting existing rendered skill: {skill_path}")
+            skill_path.write_text(render_skill_md(skill), encoding="utf-8")
+            rel = skill_path.relative_to(target_root).as_posix()
+            results.append({"skill": skill.name, "path": rel})
+        return results
+
+    def remove_skills(self, target_root: Path, rendered_paths: list[dict]) -> None:
+        for entry in rendered_paths:
+            p = target_root / entry["path"]
+            if p.exists():
+                p.unlink()
+            if p.parent.exists() and not any(p.parent.iterdir()):
+                p.parent.rmdir()
+
+    def add_mcp(self, target_root: Path, normalized_mcp: NormalizedMcp) -> list[str]:
+        config_path = target_root / ".codex" / "config.toml"
+        data = load_toml(config_path)
+        mcp_servers = data.setdefault("mcp_servers", {})
+        if not isinstance(mcp_servers, dict):
+            mcp_servers = {}
+            data["mcp_servers"] = mcp_servers
+        rendered_names = []
+        for server in normalized_mcp.servers:
+            mcp_servers[server.name] = _build_toml_server_entry(server)
+            rendered_names.append(server.name)
+        save_toml(config_path, data)
+        return rendered_names
+
+    def remove_mcp(self, target_root: Path, rendered_mcp_names: list[str]) -> None:
+        config_path = target_root / ".codex" / "config.toml"
+        if not config_path.is_file():
+            return
+        data = load_toml(config_path)
+        mcp_servers = data.get("mcp_servers")
+        if isinstance(mcp_servers, dict):
+            for name in rendered_mcp_names:
+                mcp_servers.pop(name, None)
+        save_toml(config_path, data)
+
+    def add_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+        warnings.warn("codex: agent ignore is unsupported; steer via AGENTS.md policy instead")
+
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+        warnings.warn("codex: agent ignore is unsupported")
+
+    def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
+        ep = target_root / "AGENTS.md"
+        rewrite_managed_block(ep, prompt)
+        return ep.relative_to(target_root).as_posix()
+
+    def finalize_repo_after_ide_removed(self, target_root: Path) -> None:
+        _vac.finalize_codex_repo(target_root)
+
+
+register(CodexAdapter())
+
+__all__ = ["CodexAdapter"]

spawn_cli/ide/cursor.py

@@ -0,0 +1,122 @@
+"""Cursor IDE adapter: skills, MCP, agent ignore, AGENTS.md."""
+
+from __future__ import annotations
+
+import json
+import warnings
+from pathlib import Path
+
+from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.registry import (
+    DetectResult,
+    IdeAdapter,
+    IdeCapabilities,
+    register,
+    normalize_skill_name,
+    render_skill_md,
+    rewrite_managed_block,
+    rewrite_ignore_block,
+    remove_ignore_block,
+)
+from spawn_cli.models.mcp import McpServer, NormalizedMcp
+from spawn_cli.models.skill import SkillMetadata
+
+
+def _build_mcp_server_entry(server: McpServer) -> dict:
+    """Convert McpServer to .cursor/mcp.json entry (mcpServers format)."""
+    transport = server.transport
+    if transport.type == "stdio":
+        entry: dict = {"command": transport.command, "args": transport.args}
+    elif transport.type in ("streamable-http", "sse"):
+        entry = {"type": transport.type, "url": transport.url}
+        if transport.headers:
+            entry["headers"] = {k: f"${{{v}}}" for k, v in transport.headers.items()}
+    else:
+        entry = {"command": transport.command, "args": transport.args}
+    if server.env:
+        entry["env"] = {
+            k: f"${{{k}}}" if v.secret else v.value or f"${{{k}}}"
+            for k, v in server.env.items()
+        }
+    return entry
+
+
+class CursorAdapter(IdeAdapter):
+    key = "cursor"
+
+    def detect(self, target_root: Path) -> DetectResult:
+        used = (target_root / ".cursor").exists()
+        return DetectResult(
+            used_in_repo=used,
+            capabilities=IdeCapabilities(
+                skills="native",
+                mcp="project",
+                agent_ignore="native",
+                entry_point="agents-md",
+            ),
+        )
+
+    def add_skills(self, target_root: Path, skill_metadata: list[SkillMetadata]) -> list[dict]:
+        results = []
+        for skill in skill_metadata:
+            name = normalize_skill_name(skill.name)
+            skill_dir = target_root / ".cursor" / "skills" / name
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            skill_path = skill_dir / "SKILL.md"
+            if skill_path.exists():
+                warnings.warn(f"Overwriting existing rendered skill: {skill_path}")
+            skill_path.write_text(render_skill_md(skill), encoding="utf-8")
+            rel = skill_path.relative_to(target_root).as_posix()
+            results.append({"skill": skill.name, "path": rel})
+        return results
+
+    def remove_skills(self, target_root: Path, rendered_paths: list[dict]) -> None:
+        for entry in rendered_paths:
+            p = target_root / entry["path"]
+            if p.exists():
+                p.unlink()
+            if p.parent.exists() and not any(p.parent.iterdir()):
+                p.parent.rmdir()
+
+    def add_mcp(self, target_root: Path, normalized_mcp: NormalizedMcp) -> list[str]:
+        """Merge Spawn-owned servers into .cursor/mcp.json (mcpServers format)."""
+        mcp_path = target_root / ".cursor" / "mcp.json"
+        mcp_path.parent.mkdir(parents=True, exist_ok=True)
+        data = json.loads(mcp_path.read_text(encoding="utf-8")) if mcp_path.exists() else {}
+        data.setdefault("mcpServers", {})
+        rendered_names = []
+        for server in normalized_mcp.servers:
+            entry = _build_mcp_server_entry(server)
+            data["mcpServers"][server.name] = entry
+            rendered_names.append(server.name)
+        mcp_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        return rendered_names
+
+    def remove_mcp(self, target_root: Path, rendered_mcp_names: list[str]) -> None:
+        """Remove named entries from .cursor/mcp.json."""
+        mcp_path = target_root / ".cursor" / "mcp.json"
+        if not mcp_path.exists():
+            return
+        data = json.loads(mcp_path.read_text(encoding="utf-8"))
+        for name in rendered_mcp_names:
+            data.get("mcpServers", {}).pop(name, None)
+        mcp_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def add_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_ignore_block(target_root / ".cursorignore", globs)
+
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        remove_ignore_block(target_root / ".cursorignore", globs)
+
+    def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
+        ep = target_root / "AGENTS.md"
+        rewrite_managed_block(ep, prompt)
+        return str(ep.relative_to(target_root))
+
+    def finalize_repo_after_ide_removed(self, target_root: Path) -> None:
+        _vac.finalize_standard_dotdir_skills_and_mcp(target_root, ".cursor", allow_delete_entire=True)
+
+
+register(CursorAdapter())
+
+__all__ = ["CursorAdapter"]