spawn-cli 0.1.1__py3-none-any.whl

spawn_cli/core/scripts.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+
+from spawn_cli.core.errors import SpawnError, SpawnWarning
+from spawn_cli.io.yaml_io import load_yaml
+from spawn_cli.models.config import ExtensionConfig
+from spawn_cli.models.config import SourceYaml as SY
+
+SCRIPT_ENV_VARS = (
+    "SPAWN_EXT_NAME",
+    "SPAWN_EXT_PATH",
+    "SPAWN_EXT_VERSION",
+    "SPAWN_TARGET_VERSION",
+    "SPAWN_TARGET_ROOT",
+)
+
+
+def _extend_dir(target_root: Path, extension: str) -> Path:
+    return target_root / "spawn" / ".extend" / extension
+
+
+def _ext_layout_root(target_root: Path, extension: str, override: Path | None) -> Path:
+    if override is not None:
+        return override
+    return _extend_dir(target_root, extension)
+
+
+def _core_version(target_root: Path) -> str:
+    raw = load_yaml(target_root / "spawn" / ".core" / "config.yaml")
+    if not raw or not raw.get("version"):
+        return "0.0.0"
+    return str(raw["version"])
+
+
+def _setup_script_path(ext_layout: Path, setup_filename: str) -> Path:
+    return ext_layout / "setup" / setup_filename
+
+
+def _extension_config_at(ext_layout: Path) -> ExtensionConfig:
+    raw = load_yaml(ext_layout / "config.yaml")
+    if not raw:
+        raise SpawnError("missing extension config.yaml for script run")
+    return ExtensionConfig.model_validate(raw)
+
+
+def _installed_source_version(target_root: Path, extension: str) -> str | None:
+    p = _extend_dir(target_root, extension) / "source.yaml"
+    if not p.is_file():
+        return None
+    raw = load_yaml(p)
+    if not raw:
+        return None
+    sy = SY.model_validate(raw)
+    return sy.installed.version
+
+
+def _run_script(
+    target_root: Path,
+    extension: str,
+    script_filename: str,
+    *,
+    ext_layout: Path,
+    blocking: bool,
+) -> subprocess.CompletedProcess[str]:
+    script_path = _setup_script_path(ext_layout, script_filename)
+    if not script_path.is_file():
+        raise SpawnError(f"setup script missing: {script_path}")
+    cfg = _extension_config_at(ext_layout)
+    ext_ver = cfg.version
+    tgt_ver = _core_version(target_root)
+    src_ver = _installed_source_version(target_root, extension) or ext_ver
+    env = os.environ.copy()
+    env["SPAWN_TARGET_ROOT"] = str(target_root.resolve())
+    env["SPAWN_EXT_NAME"] = extension
+    env["SPAWN_EXT_PATH"] = str(ext_layout.resolve())
+    env["SPAWN_EXT_VERSION"] = ext_ver
+    env["SPAWN_TARGET_VERSION"] = tgt_ver
+    proc = subprocess.run(
+        [sys.executable, str(script_path)],
+        cwd=str(target_root),
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        msg = f"Setup script {script_filename!r} exited with status {proc.returncode}"
+        if proc.stderr.strip():
+            msg = f"{msg}: {proc.stderr.strip()}"
+        if blocking:
+            raise SpawnError(msg)
+        warnings.warn(msg, SpawnWarning)
+    return proc
+
+
+def run_before_install_scripts(target_root: Path, extension: str, *, ext_layout: Path | None = None) -> None:
+    layout = _ext_layout_root(target_root, extension, ext_layout)
+    cfg = _extension_config_at(layout)
+    if not cfg.setup or not cfg.setup.before_install:
+        return
+    _run_script(
+        target_root,
+        extension,
+        cfg.setup.before_install,
+        ext_layout=layout,
+        blocking=True,
+    )
+
+
+def run_after_install_scripts(target_root: Path, extension: str, *, ext_layout: Path | None = None) -> None:
+    layout = _ext_layout_root(target_root, extension, ext_layout)
+    cfg = _extension_config_at(layout)
+    if not cfg.setup or not cfg.setup.after_install:
+        return
+    _run_script(
+        target_root,
+        extension,
+        cfg.setup.after_install,
+        ext_layout=layout,
+        blocking=False,
+    )
+
+
+def run_before_uninstall_scripts(target_root: Path, extension: str, *, ext_layout: Path | None = None) -> None:
+    layout = _ext_layout_root(target_root, extension, ext_layout)
+    cfg = _extension_config_at(layout)
+    if not cfg.setup:
+        return
+    if not cfg.setup.before_uninstall:
+        return
+    _run_script(
+        target_root,
+        extension,
+        cfg.setup.before_uninstall,
+        ext_layout=layout,
+        blocking=True,
+    )
+
+
+def run_after_uninstall_scripts(target_root: Path, extension: str, *, ext_layout: Path | None = None) -> None:
+    layout = _ext_layout_root(target_root, extension, ext_layout)
+    if not layout.is_dir():
+        return
+    cfg = _extension_config_at(layout)
+    if not cfg.setup or not cfg.setup.after_uninstall:
+        return
+    _run_script(
+        target_root,
+        extension,
+        cfg.setup.after_uninstall,
+        ext_layout=layout,
+        blocking=False,
+    )
+
+
+@dataclass
+class AfterUninstallSnapshot:
+    script_path: Path | None
+    ext_version: str
+
+
+def snapshot_after_uninstall_script(ext_dir: Path, cfg: ExtensionConfig) -> AfterUninstallSnapshot:
+    if not cfg.setup or not cfg.setup.after_uninstall:
+        return AfterUninstallSnapshot(None, cfg.version)
+    src = ext_dir / "setup" / cfg.setup.after_uninstall
+    if not src.is_file():
+        return AfterUninstallSnapshot(None, cfg.version)
+    td = Path(tempfile.mkdtemp(prefix="spawn-after-uninstall-"))
+    dst = td / src.name
+    shutil.copy2(src, dst)
+    return AfterUninstallSnapshot(dst, cfg.version)
+
+
+def run_after_uninstall_from_snapshot(
+    target_root: Path, extension: str, snap: AfterUninstallSnapshot
+) -> None:
+    if snap.script_path is None:
+        return
+    ghost_ext = _extend_dir(target_root, extension)
+    env = os.environ.copy()
+    env["SPAWN_TARGET_ROOT"] = str(target_root.resolve())
+    env["SPAWN_EXT_NAME"] = extension
+    env["SPAWN_EXT_PATH"] = str(ghost_ext.resolve())
+    env["SPAWN_EXT_VERSION"] = snap.ext_version
+    env["SPAWN_TARGET_VERSION"] = _core_version(target_root)
+    proc = subprocess.run(
+        [sys.executable, str(snap.script_path)],
+        cwd=str(target_root),
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        msg = f"After-uninstall script exited with status {proc.returncode}"
+        if proc.stderr.strip():
+            msg = f"{msg}: {proc.stderr.strip()}"
+        warnings.warn(msg, SpawnWarning)
+
+
+def run_healthcheck_scripts(target_root: Path, extension: str, *, ext_layout: Path | None = None) -> bool:
+    layout = _ext_layout_root(target_root, extension, ext_layout)
+    cfg = _extension_config_at(layout)
+    if not cfg.setup or not cfg.setup.healthcheck:
+        return True
+    proc = subprocess.run(
+        [
+            sys.executable,
+            str(_setup_script_path(layout, cfg.setup.healthcheck)),
+        ],
+        cwd=str(target_root),
+        env={
+            **os.environ,
+            "SPAWN_TARGET_ROOT": str(target_root.resolve()),
+            "SPAWN_EXT_NAME": extension,
+            "SPAWN_EXT_PATH": str(layout.resolve()),
+            "SPAWN_EXT_VERSION": cfg.version,
+            "SPAWN_TARGET_VERSION": _core_version(target_root),
+        },
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return proc.returncode == 0
+
+
+__all__ = [
+    "AfterUninstallSnapshot",
+    "SCRIPT_ENV_VARS",
+    "_run_script",
+    "run_after_install_scripts",
+    "run_after_uninstall_scripts",
+    "run_before_install_scripts",
+    "run_before_uninstall_scripts",
+    "run_after_uninstall_from_snapshot",
+    "run_healthcheck_scripts",
+    "snapshot_after_uninstall_script",
+]

spawn_cli/errors.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class SpawnError(Exception):
+    """Raised on errors that stop the command before mutation."""
+
+
+class SpawnWarning(UserWarning):
+    """Raised (or printed) for recoverable inconsistencies."""

spawn_cli/ide/__init__.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from . import registry  # noqa: F401
+from . import _stub  # noqa: F401 — load stubs before concrete adapters
+from . import cursor  # noqa: F401
+from . import claude_code  # noqa: F401
+from . import codex  # noqa: F401
+from . import gemini_cli  # noqa: F401
+from . import github_copilot  # noqa: F401
+from . import windsurf  # noqa: F401
+from ._stub import StubAdapter
+from .claude_code import ClaudeCodeAdapter
+from .codex import CodexAdapter
+from .cursor import CursorAdapter
+from .gemini_cli import GeminiCliAdapter
+from .github_copilot import GitHubCopilotAdapter
+from .windsurf import WindsurfAdapter
+from .registry import (
+    ALIASES,
+    IGNORE_BLOCK_END,
+    IGNORE_BLOCK_START,
+    SPAWN_BLOCK_END,
+    SPAWN_BLOCK_START,
+    DetectResult,
+    IdeAdapter,
+    IdeCapabilities,
+    detect_supported_ides,
+    get,
+    normalize_skill_name,
+    register,
+    remove_ignore_block,
+    render_skill_md,
+    rewrite_ignore_block,
+    rewrite_managed_block,
+    supported_ide_keys,
+)
+
+__all__ = [
+    "ALIASES",
+    "ClaudeCodeAdapter",
+    "CodexAdapter",
+    "CursorAdapter",
+    "GeminiCliAdapter",
+    "GitHubCopilotAdapter",
+    "DetectResult",
+    "IGNORE_BLOCK_END",
+    "IGNORE_BLOCK_START",
+    "IdeAdapter",
+    "IdeCapabilities",
+    "SPAWN_BLOCK_END",
+    "SPAWN_BLOCK_START",
+    "StubAdapter",
+    "WindsurfAdapter",
+    "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/_helpers.py

@@ -0,0 +1,168 @@
+"""Shared IDE adapter rendering helpers."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from spawn_cli.core.low_level import _norm_read_path, normalize_skill_name
+from spawn_cli.models.skill import SkillFileRef, SkillMetadata
+
+SPAWN_BLOCK_START = "<!-- spawn:start -->"
+SPAWN_BLOCK_END = "<!-- spawn:end -->"
+
+IGNORE_BLOCK_START = "# spawn:start"
+IGNORE_BLOCK_END = "# spawn:end"
+
+_NAV_YAML_FILE = "spawn/navigation.yaml"
+_NAV_YAML_DESCRIPTION = "Merged Spawn navigation (read-required, read-contextual)."
+
+
+def _mandatory_reads_for_render(skill: SkillMetadata) -> list[SkillFileRef]:
+    """Build mandatory list with spawn/navigation.yaml deduped and last."""
+    nav_key = _norm_read_path(_NAV_YAML_FILE)
+    nav_ref: SkillFileRef | None = None
+    others: list[SkillFileRef] = []
+    for ref in skill.required_read:
+        if _norm_read_path(ref.file) == nav_key:
+            if nav_ref is None:
+                nav_ref = ref
+        else:
+            others.append(ref)
+    if nav_ref is None:
+        nav_ref = SkillFileRef(file=_NAV_YAML_FILE, description=_NAV_YAML_DESCRIPTION)
+    return others + [nav_ref]
+
+
+def render_skill_md(skill: SkillMetadata) -> str:
+    """Render normalized skill to Markdown with frontmatter, skill body,
+    mandatory reads (navigation path last), and contextual reads."""
+    lines = [
+        "---",
+        f"name: {skill.name}",
+        f"description: {skill.description}",
+        "---",
+        "",
+        skill.content,
+        "",
+        "Mandatory reads:",
+    ]
+    for ref in _mandatory_reads_for_render(skill):
+        lines += [f"- `{ref.file}` - {ref.description}"]
+    lines += [""]
+    if skill.auto_read:
+        lines += ["Contextual reads:"]
+        for ref in skill.auto_read:
+            lines += [f"- `{ref.file}` - {ref.description}"]
+        lines += [""]
+    return "\n".join(lines)
+
+
+def rewrite_managed_block(file_path: Path, prompt: str) -> None:
+    """Read file (or empty string), replace/insert spawn block, write back."""
+    content = file_path.read_text(encoding="utf-8") if file_path.exists() else ""
+    block = f"{SPAWN_BLOCK_START}\n{prompt}\n{SPAWN_BLOCK_END}"
+    if SPAWN_BLOCK_START in content:
+        content = re.sub(
+            rf"{re.escape(SPAWN_BLOCK_START)}.*?{re.escape(SPAWN_BLOCK_END)}",
+            block,
+            content,
+            flags=re.DOTALL,
+        )
+    else:
+        content = block + "\n" + content
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text(content, encoding="utf-8")
+
+
+def _partition_ignore_block(lines: list[str]) -> tuple[list[str], list[str], list[str]]:
+    start_idx: int | None = None
+    end_idx: int | None = None
+    for i, ln in enumerate(lines):
+        if ln.strip() == IGNORE_BLOCK_START:
+            start_idx = i
+            break
+    if start_idx is None:
+        return lines[:], [], []
+    for j in range(start_idx + 1, len(lines)):
+        if lines[j].strip() == IGNORE_BLOCK_END:
+            end_idx = j
+            break
+    if end_idx is None:
+        return lines[:start_idx], lines[start_idx + 1 :], []
+    return lines[:start_idx], lines[start_idx + 1 : end_idx], lines[end_idx + 1 :]
+
+
+def rewrite_ignore_block(file_path: Path, globs: list[str]) -> None:
+    """Merge Spawn-owned globs into a text ignore file using # spawn:start / # spawn:end."""
+    raw_lines = (
+        file_path.read_text(encoding="utf-8").splitlines(True)
+        if file_path.exists()
+        else []
+    )
+    before, _inner, after = _partition_ignore_block(raw_lines)
+    body_lines = [g.strip() + "\n" for g in globs if g.strip()]
+    block_lines = (
+        [IGNORE_BLOCK_START + "\n"]
+        + body_lines
+        + [IGNORE_BLOCK_END + "\n"]
+    )
+    new_lines = before + block_lines + after
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text("".join(new_lines), encoding="utf-8")
+
+
+def remove_ignore_block(file_path: Path, globs: list[str]) -> None:
+    """Remove Spawn-managed ignore lines or the whole managed block.
+
+    If ``globs`` is empty, removes the entire ``# spawn:start`` … ``# spawn:end`` block.
+    If ``globs`` is non-empty, removes only inner lines whose stripped text matches
+    an entry in ``globs``; preserves other inner lines and all content outside the block.
+    If no inner lines remain, the block markers are removed as well.
+    """
+    if not file_path.exists():
+        return
+    raw_lines = file_path.read_text(encoding="utf-8").splitlines(True)
+    start_idx: int | None = None
+    end_idx: int | None = None
+    for i, ln in enumerate(raw_lines):
+        if ln.strip() == IGNORE_BLOCK_START:
+            start_idx = i
+            break
+    if start_idx is None:
+        return
+    for j in range(start_idx + 1, len(raw_lines)):
+        if raw_lines[j].strip() == IGNORE_BLOCK_END:
+            end_idx = j
+            break
+    if end_idx is None:
+        return
+
+    before = raw_lines[:start_idx]
+    inner = raw_lines[start_idx + 1 : end_idx]
+    after = raw_lines[end_idx + 1 :]
+
+    if not globs:
+        file_path.write_text("".join(before + after), encoding="utf-8")
+        return
+
+    drop = {g.strip() for g in globs if g.strip()}
+    kept = [ln for ln in inner if ln.strip() not in drop]
+    if not kept:
+        file_path.write_text("".join(before + after), encoding="utf-8")
+    else:
+        block_lines = [IGNORE_BLOCK_START + "\n"] + kept + [IGNORE_BLOCK_END + "\n"]
+        file_path.write_text("".join(before + block_lines + after), encoding="utf-8")
+
+
+__all__ = [
+    "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",
+]

spawn_cli/ide/_stub.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+
+from .registry import DetectResult, IdeAdapter, IdeCapabilities, register
+from spawn_cli.models.mcp import NormalizedMcp
+from spawn_cli.models.skill import SkillMetadata
+
+
+class StubAdapter(IdeAdapter):
+    def __init__(self, key: str, caps: IdeCapabilities) -> None:
+        self.key = key
+        self._caps = caps
+
+    def detect(self, target_root: Path) -> DetectResult:
+        del target_root
+        return DetectResult(used_in_repo=False, capabilities=self._caps)
+
+    def add_skills(self, target_root: Path, skill_metadata: list[SkillMetadata]) -> list[dict]:
+        del target_root, skill_metadata
+        warnings.warn(f"{self.key}: skill rendering not yet implemented")
+        return []
+
+    def remove_skills(self, target_root: Path, rendered_paths: list[dict]) -> None:
+        del target_root, rendered_paths
+        warnings.warn(f"{self.key}: skill removal not yet implemented")
+
+    def add_mcp(self, target_root: Path, normalized_mcp: NormalizedMcp) -> list[str]:
+        del target_root, normalized_mcp
+        warnings.warn(f"{self.key}: MCP rendering not yet implemented")
+        return []
+
+    def remove_mcp(self, target_root: Path, rendered_mcp_names: list[str]) -> None:
+        del target_root, rendered_mcp_names
+        warnings.warn(f"{self.key}: MCP removal not yet implemented")
+
+    def add_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+        warnings.warn(f"{self.key}: agent ignore not yet implemented")
+
+    def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+        warnings.warn(f"{self.key}: agent ignore removal not yet implemented")
+
+    def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
+        del target_root, prompt
+        warnings.warn(f"{self.key}: entry point not yet implemented")
+        return ""
+
+
+_STUBS: list[tuple[str, IdeCapabilities]] = [
+    ("qoder", IdeCapabilities("native", "project", "project", "agents-md")),
+    ("qwen-code", IdeCapabilities("native", "project", "project", "qwen-md")),
+    ("aider", IdeCapabilities("entry-only", "unsupported", "project", "conventions-md")),
+    ("zed", IdeCapabilities("unsupported", "project", "unsupported", "agents-md")),
+    ("devin", IdeCapabilities("native", "project", "unsupported", "agents-md")),
+]
+
+for _key, _caps in _STUBS:
+    register(StubAdapter(_key, _caps))
+
+__all__ = ["StubAdapter"]