spawn-cli 0.1.1__py3-none-any.whl

spawn_cli/ide/gemini_cli.py

@@ -0,0 +1,130 @@
+"""Google Gemini CLI IDE adapter: .gemini/skills, settings mcpServers, .geminiignore, GEMINI.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_gemini_mcp_entry(server: McpServer) -> dict:
+    transport = server.transport
+    entry: dict = {}
+    if transport.type == "stdio":
+        entry["command"] = transport.command
+        entry["args"] = list(transport.args)
+    elif transport.type == "streamable-http":
+        entry["httpUrl"] = transport.url or ""
+        if transport.headers:
+            entry["headers"] = {k: f"${{{v}}}" for k, v in transport.headers.items()}
+    elif transport.type == "sse":
+        entry["url"] = transport.url or ""
+        if transport.headers:
+            entry["headers"] = {k: f"${{{v}}}" for k, v in transport.headers.items()}
+    else:
+        entry["command"] = transport.command
+        entry["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 GeminiCliAdapter(IdeAdapter):
+    key = "gemini-cli"
+
+    def detect(self, target_root: Path) -> DetectResult:
+        used = (target_root / ".gemini").exists() or (target_root / "GEMINI.md").exists()
+        return DetectResult(
+            used_in_repo=used,
+            capabilities=IdeCapabilities(
+                skills="native",
+                mcp="project",
+                agent_ignore="native",
+                entry_point="gemini-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 / ".gemini" / "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]:
+        settings_path = target_root / ".gemini" / "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 {}
+        data.setdefault("mcpServers", {})
+        rendered_names = []
+        for server in normalized_mcp.servers:
+            data["mcpServers"][server.name] = _build_gemini_mcp_entry(server)
+            rendered_names.append(server.name)
+        settings_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:
+        settings_path = target_root / ".gemini" / "settings.json"
+        if not settings_path.exists():
+            return
+        data = json.loads(settings_path.read_text(encoding="utf-8"))
+        for name in rendered_mcp_names:
+            data.get("mcpServers", {}).pop(name, None)
+        settings_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 / ".geminiignore", globs)
+
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        remove_ignore_block(target_root / ".geminiignore", globs)
+
+    def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
+        ep = target_root / "GEMINI.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_standard_dotdir_skills_and_mcp(
+            target_root,
+            ".gemini",
+            allow_delete_entire=True,
+            unlink_settings_json_when_mcp_servers_empty=True,
+        )
+
+
+register(GeminiCliAdapter())
+
+__all__ = ["GeminiCliAdapter"]

spawn_cli/ide/github_copilot.py

@@ -0,0 +1,167 @@
+"""GitHub Copilot IDE adapter: .github/skills, .vscode/mcp.json (servers + inputs), dual entry points."""
+
+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 _env_input_id(server_name: str, var_name: str) -> str:
+    return f"{server_name}-{var_name.lower().replace('_', '-')}"
+
+
+def _build_vscode_mcp_entry(server: McpServer) -> tuple[dict, list[dict]]:
+    transport = server.transport
+    entry: dict = {}
+    inputs: list[dict] = []
+
+    if transport.type == "stdio":
+        entry["type"] = "stdio"
+        entry["command"] = transport.command
+        entry["args"] = list(transport.args)
+    else:
+        entry["type"] = transport.type
+        entry["url"] = transport.url
+
+    if server.env:
+        env_dict: dict[str, str] = {}
+        for var_name, var in server.env.items():
+            if var.secret:
+                input_id = _env_input_id(server.name, var_name)
+                env_dict[var_name] = f"${{input:{input_id}}}"
+                inputs.append(
+                    {
+                        "id": input_id,
+                        "type": "promptString",
+                        "description": var_name,
+                        "password": True,
+                    }
+                )
+            else:
+                env_dict[var_name] = var.value or f"${{{var_name}}}"
+        entry["env"] = env_dict
+
+    return entry, inputs
+
+
+def _input_belongs_to_server(inp_id: str, server_name: str) -> bool:
+    prefix = f"{server_name}-"
+    return inp_id.startswith(prefix)
+
+
+class GitHubCopilotAdapter(IdeAdapter):
+    key = "github-copilot"
+
+    def detect(self, target_root: Path) -> DetectResult:
+        used = (target_root / ".github").exists() or (target_root / ".vscode").exists()
+        return DetectResult(
+            used_in_repo=used,
+            capabilities=IdeCapabilities(
+                skills="native",
+                mcp="project",
+                agent_ignore="unsupported",
+                entry_point="copilot-instructions",
+            ),
+        )
+
+    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 / ".github" / "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 / ".vscode" / "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("servers", {})
+        data.setdefault("inputs", [])
+        if not isinstance(data["inputs"], list):
+            data["inputs"] = []
+        rendered_names = []
+        existing_ids = {inp["id"] for inp in data["inputs"] if isinstance(inp, dict) and "id" in inp}
+        for server in normalized_mcp.servers:
+            entry, new_inputs = _build_vscode_mcp_entry(server)
+            data["servers"][server.name] = entry
+            for inp in new_inputs:
+                if inp["id"] not in existing_ids:
+                    data["inputs"].append(inp)
+                    existing_ids.add(inp["id"])
+            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 / ".vscode" / "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("servers", {}).pop(name, None)
+        removed = set(rendered_mcp_names)
+        inputs_list = data.get("inputs", [])
+        if isinstance(inputs_list, list):
+            data["inputs"] = [
+                inp
+                for inp in inputs_list
+                if not isinstance(inp, dict)
+                or "id" not in inp
+                or not any(_input_belongs_to_server(str(inp["id"]), n) for n in removed)
+            ]
+        mcp_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def add_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+        warnings.warn(
+            "github-copilot: agent ignore is unsupported; "
+            "GitHub Copilot content exclusion does not apply to IDE Agent mode"
+        )
+
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+        warnings.warn("github-copilot: agent ignore is unsupported")
+
+    def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
+        ep1 = target_root / ".github" / "copilot-instructions.md"
+        ep2 = target_root / "AGENTS.md"
+        rewrite_managed_block(ep1, prompt)
+        rewrite_managed_block(ep2, prompt)
+        return ep1.relative_to(target_root).as_posix()
+
+    def finalize_repo_after_ide_removed(self, target_root: Path) -> None:
+        _vac.finalize_github_copilot_repo(target_root)
+
+
+register(GitHubCopilotAdapter())
+
+__all__ = ["GitHubCopilotAdapter"]

spawn_cli/ide/registry.py

@@ -0,0 +1,142 @@
+"""IDE adapter registry and abstract adapter interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+from spawn_cli.core.errors import SpawnError
+from spawn_cli.core.low_level import CANONICAL_IDE_KEYS
+from spawn_cli.ide._helpers import (
+    IGNORE_BLOCK_END,
+    IGNORE_BLOCK_START,
+    SPAWN_BLOCK_END,
+    SPAWN_BLOCK_START,
+    normalize_skill_name,
+    remove_ignore_block,
+    render_skill_md,
+    rewrite_ignore_block,
+    rewrite_managed_block,
+)
+from spawn_cli.models.mcp import NormalizedMcp
+from spawn_cli.models.skill import SkillMetadata
+
+
+@dataclass
+class IdeCapabilities:
+    skills: str  # native | project | entry-only | external | unsupported
+    mcp: str  # native | project | entry-only | external | unsupported
+    agent_ignore: str  # native | project | entry-only | external | unsupported
+    entry_point: str  # native | project | entry-only | external | unsupported
+
+    def to_dict(self) -> dict:
+        """Serialize to camelCase dict for YAML output."""
+        return {
+            "skills": self.skills,
+            "mcp": self.mcp,
+            "agentIgnore": self.agent_ignore,
+            "entryPoint": self.entry_point,
+        }
+
+
+@dataclass
+class DetectResult:
+    used_in_repo: bool
+    capabilities: IdeCapabilities
+
+
+class IdeAdapter(ABC):
+    key: str  # canonical key, defined on the class or instance
+
+    @abstractmethod
+    def detect(self, target_root: Path) -> DetectResult: ...
+
+    @abstractmethod
+    def add_skills(self, target_root: Path, skill_metadata: list[SkillMetadata]) -> list[dict]:
+        """Returns list of {skill: str, path: str} for ownership tracking."""
+        ...
+
+    @abstractmethod
+    def remove_skills(self, target_root: Path, rendered_paths: list[dict]) -> None: ...
+
+    @abstractmethod
+    def add_mcp(self, target_root: Path, normalized_mcp: NormalizedMcp) -> list[str]:
+        """Returns list of rendered server names."""
+        ...
+
+    @abstractmethod
+    def remove_mcp(self, target_root: Path, rendered_mcp_names: list[str]) -> None: ...
+
+    @abstractmethod
+    def add_agent_ignore(self, target_root: Path, globs: list[str]) -> None: ...
+
+    @abstractmethod
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None: ...
+
+    @abstractmethod
+    def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
+        """Returns rendered path or warning string."""
+        ...
+
+    def finalize_repo_after_ide_removed(self, target_root: Path) -> None:
+        """Vacancy-prune Spawn-owned repo-root directories after MCP/skills/ignore teardown."""
+        del target_root
+
+
+ALIASES: dict[str, str] = {
+    "claude": "claude-code",
+    "qwen": "qwen-code",
+    "gemini": "gemini-cli",
+    "copilot": "github-copilot",
+    "github": "github-copilot",
+}
+
+_registry: dict[str, IdeAdapter] = {}  # populated at module load by adapter modules
+
+
+def register(adapter: IdeAdapter) -> None:
+    """Register an adapter instance under its canonical key (must appear in CANONICAL_IDE_KEYS)."""
+    key = getattr(adapter, "key", None)
+    if key not in CANONICAL_IDE_KEYS:
+        raise SpawnError(f"Cannot register unknown IDE key: {key!r}")
+    _registry[key] = adapter
+
+
+def get(name: str) -> IdeAdapter:
+    """Resolve alias to canonical key to adapter. SpawnError on unknown."""
+    canonical = ALIASES.get(name, name)
+    if canonical not in _registry:
+        raise SpawnError(f"Unknown IDE: {name!r}")
+    return _registry[canonical]
+
+
+def supported_ide_keys() -> list[str]:
+    """Return the frozen ordered list from low_level (not dict iteration order)."""
+    return list(CANONICAL_IDE_KEYS)
+
+
+def detect_supported_ides(target_root: Path) -> dict[str, DetectResult]:
+    """Run detect() for every canonical IDE key in CANONICAL_IDE_KEYS order."""
+    return {key: get(key).detect(target_root) for key in CANONICAL_IDE_KEYS}
+
+
+__all__ = [
+    "ALIASES",
+    "DetectResult",
+    "IdeAdapter",
+    "IdeCapabilities",
+    "IGNORE_BLOCK_END",
+    "IGNORE_BLOCK_START",
+    "SPAWN_BLOCK_END",
+    "SPAWN_BLOCK_START",
+    "detect_supported_ides",
+    "get",
+    "normalize_skill_name",
+    "register",
+    "remove_ignore_block",
+    "render_skill_md",
+    "rewrite_ignore_block",
+    "rewrite_managed_block",
+    "supported_ide_keys",
+]

spawn_cli/ide/windsurf.py

@@ -0,0 +1,91 @@
+"""Windsurf IDE adapter: .windsurf/skills, .codeiumignore, AGENTS.md; MCP unsupported."""
+
+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,
+    rewrite_ignore_block,
+    remove_ignore_block,
+)
+from spawn_cli.models.mcp import NormalizedMcp
+from spawn_cli.models.skill import SkillMetadata
+
+
+class WindsurfAdapter(IdeAdapter):
+    key = "windsurf"
+
+    def detect(self, target_root: Path) -> DetectResult:
+        used = (target_root / ".windsurf").exists() or (target_root / ".codeiumignore").exists()
+        return DetectResult(
+            used_in_repo=used,
+            capabilities=IdeCapabilities(
+                skills="native",
+                mcp="unsupported",
+                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 / ".windsurf" / "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]:
+        del normalized_mcp
+        del target_root
+        warnings.warn(
+            "windsurf: Windsurf does not support project MCP config; "
+            "MCP is configured globally in Cascade"
+        )
+        return []
+
+    def remove_mcp(self, target_root: Path, rendered_mcp_names: list[str]) -> None:
+        del target_root, rendered_mcp_names
+        warnings.warn("windsurf: MCP is unsupported; nothing to remove")
+
+    def add_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_ignore_block(target_root / ".codeiumignore", globs)
+
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        remove_ignore_block(target_root / ".codeiumignore", globs)
+
+    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_standard_dotdir_skills_and_mcp(target_root, ".windsurf", allow_delete_entire=True)
+
+
+register(WindsurfAdapter())
+
+__all__ = ["WindsurfAdapter"]

spawn_cli/io/__init__.py

@@ -0,0 +1,21 @@
+from spawn_cli.io.json_io import load_json, save_json
+from spawn_cli.io.lock import spawn_lock
+from spawn_cli.io.paths import ensure_dir, safe_path, spawn_root
+from spawn_cli.io.text_io import read_lines, write_lines
+from spawn_cli.io.toml_io import load_toml, save_toml
+from spawn_cli.io.yaml_io import load_yaml, save_yaml
+
+__all__ = [
+    "ensure_dir",
+    "load_json",
+    "load_toml",
+    "load_yaml",
+    "read_lines",
+    "safe_path",
+    "save_json",
+    "save_toml",
+    "save_yaml",
+    "spawn_lock",
+    "spawn_root",
+    "write_lines",
+]

spawn_cli/io/json_io.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from spawn_cli.io.paths import ensure_dir
+
+
+def load_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    raw = path.read_text(encoding="utf-8")
+    if not raw.strip():
+        return {}
+    data = json.loads(raw)
+    return data if isinstance(data, dict) else {}
+
+
+def save_json(path: Path, data: dict, indent: int = 2) -> None:
+    ensure_dir(path.parent)
+    path.write_text(json.dumps(data, indent=indent, ensure_ascii=False) + "\n", encoding="utf-8")

spawn_cli/io/lock.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+
+from filelock import FileLock, Timeout
+
+from spawn_cli.errors import SpawnError
+from spawn_cli.io.paths import ensure_dir
+
+
+@contextmanager
+def spawn_lock(target_root: Path):
+    lock_path = target_root / "spawn" / ".metadata" / ".spawn.lock"
+    ensure_dir(lock_path.parent)
+    lock = FileLock(str(lock_path))
+    try:
+        lock.acquire(timeout=0)
+    except Timeout:
+        raise SpawnError("Операция в процессе (файл lock detected)") from None
+    try:
+        yield
+    finally:
+        lock.release()

spawn_cli/io/paths.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from spawn_cli.errors import SpawnError
+
+
+def ensure_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def safe_path(root: Path, rel: str) -> Path:
+    root_resolved = root.resolve()
+    candidate = (root_resolved / rel).resolve()
+    try:
+        candidate.relative_to(root_resolved)
+    except ValueError:
+        raise SpawnError(f"path escapes repository root: {rel!r}") from None
+    return candidate
+
+
+def spawn_root(target: Path) -> Path:
+    return target / "spawn"

spawn_cli/io/text_io.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from spawn_cli.io.paths import ensure_dir
+
+
+def read_lines(path: Path) -> list[str]:
+    if not path.is_file():
+        return []
+    return path.read_text(encoding="utf-8").splitlines()
+
+
+def write_lines(path: Path, lines: list[str]) -> None:
+    ensure_dir(path.parent)
+    path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")

spawn_cli/io/toml_io.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from spawn_cli.io.paths import ensure_dir
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import tomli_w
+
+
+def load_toml(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    raw = path.read_bytes()
+    data = tomllib.loads(raw.decode("utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+def save_toml(path: Path, data: dict) -> None:
+    ensure_dir(path.parent)
+    path.write_bytes(tomli_w.dumps(data).encode("utf-8"))