gitwise-cli 0.24.2__py3-none-any.whl

gitwise/setup_agents/providers/__init__.py

@@ -0,0 +1,96 @@
+"""Provider registry: multi-agent tool support for setup-agents."""
+
+from pathlib import Path
+
+from gitwise.i18n import t
+from gitwise.setup_agents.plan_skills import _SKILLS
+from gitwise.setup_agents.providers.aider import ADAPTER as AIDER
+from gitwise.setup_agents.providers.base import AdapterConfig, AdapterContext
+from gitwise.setup_agents.providers.claude import ADAPTER as CLAUDE
+from gitwise.setup_agents.providers.codex import ADAPTER as CODEX
+from gitwise.setup_agents.providers.continue_adapter import ADAPTER as CONTINUE
+from gitwise.setup_agents.providers.cursor import ADAPTER as CURSOR
+from gitwise.setup_agents.providers.opencode import ADAPTER as OPENCODE
+from gitwise.setup_agents.providers.pi import ADAPTER as PI
+from gitwise.setup_agents.state import _AGENTS_MD, _detect_state, _gpg_ready
+
+ADAPTERS: dict[str, AdapterConfig] = {
+    "claude": CLAUDE,
+    "cursor": CURSOR,
+    "continue": CONTINUE,
+    "opencode": OPENCODE,
+    "codex": CODEX,
+    "aider": AIDER,
+    "pi": PI,
+}
+
+
+def list_adapters() -> list[str]:
+    return sorted(ADAPTERS.keys())
+
+
+def list_providers() -> list[str]:
+    return list_adapters()
+
+
+def resolve_adapter_selection(
+    names: list[str] | None,
+) -> tuple[list[AdapterConfig], list[str]]:
+    if not names:
+        return [], []
+    normalized = ["claude" if name == "claude-only" else name for name in names]
+    if "none" in normalized:
+        if len(normalized) > 1:
+            return [], [t("adapters_none_with_others")]
+        return [], []
+    resolved: list[AdapterConfig] = []
+    seen: set[str] = set()
+    errors: list[str] = []
+    for name in normalized:
+        if name in seen:
+            continue
+        seen.add(name)
+        cfg = ADAPTERS.get(name)
+        if cfg is None:
+            errors.append(t("unknown_adapter", name=name))
+        else:
+            resolved.append(cfg)
+    return resolved, errors
+
+
+def detect_global_skills(home: Path | None = None) -> frozenset[str]:
+    home_dir = home or Path.home()
+    return frozenset(
+        skill_name
+        for skill_name in _SKILLS
+        if (home_dir / ".claude" / "skills" / skill_name / "SKILL.md").exists()
+    )
+
+
+def plan_adapter_actions(
+    adapter_names: list[str] | None,
+    root: Path,
+    context: AdapterContext | None = None,
+) -> tuple[list[dict], list[str], list[str]]:
+    if not adapter_names:
+        return [], [], []
+    selected, errors = resolve_adapter_selection(adapter_names)
+    if errors:
+        return [], errors, []
+    if context is None:
+        state = _detect_state(root)
+        context = {
+            "state": state,
+            "canonical_doc_path": _AGENTS_MD,
+            "global_skills": detect_global_skills(),
+            "supports_symlinks": state["supports_symlinks"],
+            "gpg_ready": _gpg_ready(root),
+            "flags": {},
+        }
+    actions: list[dict] = []
+    warnings: list[str] = []
+    for cfg in selected:
+        adapter_actions, adapter_warnings = cfg.plan(root, context)
+        actions.extend(adapter_actions)
+        warnings.extend(adapter_warnings)
+    return actions, [], warnings

gitwise/setup_agents/providers/aider.py

@@ -0,0 +1,11 @@
+"""Aider provider — .aider.conf.yml + CONVENTIONS.md."""
+
+from gitwise.setup_agents.providers.base import AdapterConfig
+
+ADAPTER = AdapterConfig(
+    name="aider",
+    display_name="Aider",
+    config_paths=(".aider.conf.yml", "CONVENTIONS.md"),
+    template_paths=("aider.conf.yml.template", "CONVENTIONS.md.template"),
+    template_dir="share/aider",
+)

gitwise/setup_agents/providers/base.py

@@ -0,0 +1,79 @@
+"""Base types and planning behavior for the provider registry."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+from gitwise.i18n import t
+from gitwise.setup_agents.state import _classify_path
+from gitwise.setup_agents.types import ActionDict, StateDict
+
+
+class AdapterFlags(TypedDict, total=False):
+    no_symlinks: bool
+    replace_claude_with_symlink: bool
+    migrate_legacy_claude: bool
+    frozen_time: bool
+    no_git_files: bool
+    core_claude_planned: bool
+
+
+class AdapterContext(TypedDict):
+    state: StateDict
+    canonical_doc_path: str
+    global_skills: frozenset[str]
+    supports_symlinks: bool
+    gpg_ready: bool
+    flags: AdapterFlags
+
+
+class AdapterConfig:
+    def __init__(
+        self,
+        *,
+        name: str,
+        display_name: str,
+        config_paths: tuple[str, ...],
+        template_paths: tuple[str, ...],
+        template_dir: str,
+    ) -> None:
+        self.name = name
+        self.display_name = display_name
+        self.config_paths = config_paths
+        self.template_paths = template_paths
+        self.template_dir = template_dir
+
+    def _read_template(self, template_name: str) -> str:
+        from gitwise._paths import share_dir
+
+        template_dir_str = str(self.template_dir)
+        relative = (
+            template_dir_str.removeprefix("share/")
+            if template_dir_str.startswith("share/")
+            else template_dir_str
+        )
+        template_path = share_dir() / relative / template_name
+        if not template_path.exists():
+            raise FileNotFoundError(t("adapter_no_template", path=str(template_path)))
+        return template_path.read_text(encoding="utf-8")
+
+    def plan(self, root: Path, _context: AdapterContext) -> tuple[list[ActionDict], list[str]]:
+        actions: list[ActionDict] = []
+        warnings: list[str] = []
+        for config_path, template_path in zip(self.config_paths, self.template_paths, strict=True):
+            target_path = root / config_path
+            state = _classify_path(target_path)
+            if state == "absent":
+                content = self._read_template(template_path)
+                actions.append(
+                    {
+                        "action": "adapter-create",
+                        "file": config_path,
+                        "content": content,
+                        "adapter": self.display_name,
+                    }
+                )
+            else:
+                warnings.append(t("adapter_exists", adapter=self.display_name, file=config_path))
+        return actions, warnings

gitwise/setup_agents/providers/claude.py

@@ -0,0 +1,408 @@
+"""Claude provider wrapper for staged migration from plan.py."""
+
+import json
+import os
+import time
+from pathlib import Path
+
+from gitwise.i18n import t
+from gitwise.setup_agents.plan_skills import _read_template, plan_global_skills
+from gitwise.setup_agents.providers.base import AdapterConfig, AdapterContext
+from gitwise.setup_agents.state import (
+    _AGENTS_MD,
+    _CLAUDE_MD,
+    _files_equal,
+    _gpg_ready,
+    _has_marker,
+)
+from gitwise.setup_agents.types import ActionDict, StateDict
+
+
+class ClaudeAdapter(AdapterConfig):
+    def __init__(self) -> None:
+        super().__init__(
+            name="claude",
+            display_name="Claude",
+            config_paths=(),
+            template_paths=(),
+            template_dir="share/claude",
+        )
+
+    def plan_settings(self, root: Path) -> tuple[list[ActionDict], list[str]]:
+        settings_path = root / ".claude" / "settings.json"
+        settings_template: dict = json.loads(_read_template("settings.json.template"))
+        if settings_path.exists():
+            try:
+                existing_settings: dict = json.loads(settings_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                return [
+                    {
+                        "file": ".claude/settings.json",
+                        "action": "create",
+                        "data": settings_template,
+                    }
+                ], [t("invalid_json")]
+
+            existing_deny: list = existing_settings.get("permissions", {}).get("deny", [])
+            new_deny: list = settings_template.get("permissions", {}).get("deny", [])
+            merged_deny = list(dict.fromkeys(existing_deny + new_deny))
+            existing_settings.setdefault("permissions", {})["deny"] = merged_deny
+            gpg_rules = [r for r in merged_deny if "gpgsign" in r or "no-gpg-sign" in r]
+            warnings: list[str] = []
+            if not gpg_rules:
+                warnings.append(t("settings_sin_gpg_deny"))
+            return [
+                {
+                    "file": ".claude/settings.json",
+                    "action": "merge",
+                    "data": existing_settings,
+                }
+            ], warnings
+
+        return [
+            {
+                "file": ".claude/settings.json",
+                "action": "create",
+                "data": settings_template,
+            }
+        ], []
+
+    def pointer_template(self) -> str:
+        return t("conventions_heading") + t("conventions_pointer")
+
+    def compute_backup_path(self, path: Path) -> Path:
+        backup = path.with_suffix(".md.bak")
+        if backup.exists():
+            suffix = int(time.time())
+            backup = path.parent / f"{path.stem}.md.bak.{suffix}"
+        return backup
+
+    def build_template(self, root: Path) -> str:
+        raw = _read_template("CLAUDE.md.template")
+        if _gpg_ready(root):
+            return raw
+        return (
+            "\n".join(
+                line
+                for line in raw.splitlines()
+                if "GPG" not in line and "gpg-sign" not in line.lower()
+            )
+            + "\n"
+        )
+
+    def bucket1_no_agents(
+        self,
+        state: StateDict,
+        root: Path,
+        template: str,
+    ) -> tuple[int, list[ActionDict], list[str]]:
+        c_state = state["c_state"]
+        claude_md = root / _CLAUDE_MD
+        if c_state == "absent":
+            return 1, [{"file": _CLAUDE_MD, "action": "create", "content": template}], []
+        if c_state in ("symlink_valid", "regular"):
+            if _has_marker(claude_md):
+                return (
+                    1,
+                    [
+                        {
+                            "file": _CLAUDE_MD,
+                            "action": "skip",
+                            "reason": t("already_contains_conventions"),
+                        }
+                    ],
+                    [],
+                )
+            return 1, [{"file": _CLAUDE_MD, "action": "append", "content": template}], []
+        return 1, [], []
+
+    def bucket2_agents_no_claude(
+        self,
+        root: Path,
+        supports_symlinks: bool,
+        template: str,
+    ) -> tuple[int, list[ActionDict], list[str]]:
+        agents_actions: list[ActionDict] = []
+        agents_md = root / _AGENTS_MD
+        if not _has_marker(agents_md):
+            agents_actions.append({"file": _AGENTS_MD, "action": "append", "content": template})
+        if supports_symlinks:
+            claude_actions: list[ActionDict] = [
+                {"file": _CLAUDE_MD, "action": "symlink-create", "target_relative": _AGENTS_MD}
+            ]
+        else:
+            claude_actions = [
+                {"file": _CLAUDE_MD, "action": "create", "content": self.pointer_template()}
+            ]
+        return 2, agents_actions + claude_actions, []
+
+    def _migrate_legacy_claude_only(
+        self,
+        *,
+        root: Path,
+        state: StateDict,
+        template: str,
+        supports_symlinks: bool,
+    ) -> tuple[int, list[ActionDict], list[str]]:
+        claude_md = root / _CLAUDE_MD
+        c_state = state["c_state"]
+
+        if c_state == "regular":
+            try:
+                agents_content = claude_md.read_text(encoding="utf-8")
+            except OSError:
+                agents_content = template
+        else:
+            agents_content = template
+
+        agents_actions: list[ActionDict] = [
+            {
+                "file": _AGENTS_MD,
+                "action": "create",
+                "content": agents_content,
+            }
+        ]
+
+        if c_state == "absent":
+            if supports_symlinks:
+                return (
+                    2,
+                    agents_actions
+                    + [
+                        {
+                            "file": _CLAUDE_MD,
+                            "action": "symlink-create",
+                            "target_relative": _AGENTS_MD,
+                        }
+                    ],
+                    [],
+                )
+            return (
+                2,
+                agents_actions
+                + [
+                    {
+                        "file": _CLAUDE_MD,
+                        "action": "create",
+                        "content": self.pointer_template(),
+                    }
+                ],
+                [],
+            )
+
+        if c_state == "regular":
+            _bucket, replace_actions, replace_warnings = self.bucket4_replace(
+                agents_actions, claude_md
+            )
+            return 4, replace_actions, replace_warnings
+
+        _bucket, fallback_actions, fallback_warnings = self.bucket4_default(
+            state, claude_md, agents_actions
+        )
+        return 4, fallback_actions, fallback_warnings
+
+    def bucket4_default(
+        self,
+        state: StateDict,
+        claude_md: Path,
+        agents_actions: list[ActionDict],
+    ) -> tuple[int, list[ActionDict], list[str]]:
+        c_state = state["c_state"]
+        if c_state == "symlink_valid":
+            try:
+                link_target = os.readlink(claude_md)
+            except OSError:
+                link_target = ""
+            return (
+                4,
+                agents_actions,
+                [
+                    t(
+                        "claude_md_symlink_other",
+                        file=_CLAUDE_MD,
+                        existing=link_target,
+                        expected=_AGENTS_MD,
+                    )
+                ],
+            )
+        if c_state == "regular":
+            return 4, agents_actions, [t("claude_md_separate", c=_CLAUDE_MD, a=_AGENTS_MD)]
+        return 5, [], []
+
+    def bucket4_replace(
+        self,
+        agents_actions: list[ActionDict],
+        claude_md: Path,
+    ) -> tuple[int, list[ActionDict], list[str]]:
+        backup_path = self.compute_backup_path(claude_md)
+        return (
+            4,
+            agents_actions
+            + [
+                {
+                    "file": _CLAUDE_MD,
+                    "action": "claude-md-replace-with-symlink",
+                    "target_relative": _AGENTS_MD,
+                    "backup_path": str(backup_path),
+                }
+            ],
+            [
+                t(
+                    "claude_md_replaced",
+                    file=_CLAUDE_MD,
+                    target=_AGENTS_MD,
+                    backup=backup_path.name,
+                )
+            ],
+        )
+
+    def bucket3(
+        self,
+        state: StateDict,
+        claude_md: Path,
+        agents_md: Path,
+        agents_actions: list[ActionDict],
+    ) -> tuple[int, list[ActionDict], list[str]]:
+        c_state = state["c_state"]
+        if c_state == "symlink_valid":
+            try:
+                link_target = os.readlink(claude_md)
+            except OSError:
+                link_target = ""
+            points_to_agents = link_target == _AGENTS_MD or Path(
+                os.path.realpath(str(claude_md.parent / link_target))
+            ) == Path(os.path.realpath(str(agents_md)))
+            if points_to_agents:
+                return (
+                    3,
+                    agents_actions
+                    + [
+                        {
+                            "file": _CLAUDE_MD,
+                            "action": "symlink-skip",
+                            "reason": t("already_points_to_agents"),
+                        }
+                    ],
+                    [],
+                )
+        if c_state == "regular" and _files_equal(claude_md, agents_md):
+            return (
+                3,
+                agents_actions
+                + [
+                    {
+                        "file": _CLAUDE_MD,
+                        "action": "skip",
+                        "reason": t("claude_md_identical_content"),
+                    }
+                ],
+                [],
+            )
+        return self.bucket4_default(state, claude_md, agents_actions)
+
+    def resolve_canonical_doc(
+        self,
+        root: Path,
+        state: StateDict,
+        *,
+        no_symlinks: bool = False,
+        replace_claude_with_symlink: bool = False,
+        migrate_legacy_claude: bool = False,
+    ) -> tuple[int, list[ActionDict], list[str]]:
+        a_state = state["a_state"]
+        c_state = state["c_state"]
+        claude_md = root / _CLAUDE_MD
+        agents_md = root / _AGENTS_MD
+        supports_symlinks = state["supports_symlinks"] and not no_symlinks
+        template = self.build_template(root)
+
+        if a_state == "absent":
+            if migrate_legacy_claude:
+                return self._migrate_legacy_claude_only(
+                    root=root,
+                    state=state,
+                    template=template,
+                    supports_symlinks=supports_symlinks,
+                )
+            return self.bucket1_no_agents(state, root, template)
+
+        agents_actions: list[ActionDict] = []
+        if not _has_marker(agents_md):
+            agents_actions.append({"file": _AGENTS_MD, "action": "append", "content": template})
+
+        if c_state == "absent":
+            return self.bucket2_agents_no_claude(root, supports_symlinks, template)
+
+        if c_state in ("symlink_valid", "regular"):
+            if c_state == "regular" and (replace_claude_with_symlink or migrate_legacy_claude):
+                return self.bucket4_replace(agents_actions, claude_md)
+            return self.bucket3(state, claude_md, agents_md, agents_actions)
+
+        return 5, [], []
+
+    def plan_rules(self, root: Path) -> tuple[list[ActionDict], list[str]]:
+        rule_path = root / ".claude" / "rules" / "gitwise.md"
+        if rule_path.exists():
+            return [
+                {
+                    "file": ".claude/rules/gitwise.md",
+                    "action": "skip",
+                    "reason": t("already_exists"),
+                }
+            ], []
+        return [
+            {
+                "file": ".claude/rules/gitwise.md",
+                "action": "create",
+                "content": _read_template("rules/gitwise.md"),
+            }
+        ], []
+
+    def plan_snapshot(self, *, frozen_time: bool = False) -> list[ActionDict]:
+        return [
+            {"file": ".claude/git-snapshot.md", "action": "generate", "frozen_time": frozen_time}
+        ]
+
+    def plan_global(
+        self,
+        home: Path,
+        *,
+        no_skills: bool = False,
+    ) -> tuple[list[ActionDict], list[str], list[ActionDict]]:
+        actions: list[ActionDict] = []
+        warnings: list[str] = []
+
+        settings_actions, settings_warnings = self.plan_settings(home)
+        actions += settings_actions
+        warnings += settings_warnings
+
+        rules_actions, rules_warnings = self.plan_rules(home)
+        actions += rules_actions
+        warnings += rules_warnings
+
+        if not no_skills:
+            skills_actions, skills_warnings = plan_global_skills(home)
+            actions += skills_actions
+            warnings += skills_warnings
+
+        return actions, warnings, []
+
+    def plan(self, root: Path, context: AdapterContext) -> tuple[list[ActionDict], list[str]]:
+        if context["flags"].get("core_claude_planned", False):
+            return [], []
+        actions: list[ActionDict] = []
+        warnings: list[str] = []
+
+        settings_actions, settings_warnings = self.plan_settings(root)
+        rules_actions, rules_warnings = self.plan_rules(root)
+
+        actions += settings_actions
+        actions += rules_actions
+        actions += self.plan_snapshot(frozen_time=context["flags"].get("frozen_time", False))
+
+        warnings += settings_warnings
+        warnings += rules_warnings
+        return actions, warnings
+
+
+ADAPTER = ClaudeAdapter()

gitwise/setup_agents/providers/codex.py

@@ -0,0 +1,11 @@
+"""Codex (OpenAI) provider — .codex/agents/*.toml."""
+
+from gitwise.setup_agents.providers.base import AdapterConfig
+
+ADAPTER = AdapterConfig(
+    name="codex",
+    display_name="Codex",
+    config_paths=(".codex/agents/gitwise.toml",),
+    template_paths=("agents/gitwise.toml.template",),
+    template_dir="share/codex",
+)

gitwise/setup_agents/providers/continue_adapter.py

@@ -0,0 +1,11 @@
+"""Continue provider — .continue/rules/*.md."""
+
+from gitwise.setup_agents.providers.base import AdapterConfig
+
+ADAPTER = AdapterConfig(
+    name="continue",
+    display_name="Continue",
+    config_paths=(".continue/rules/gitwise.md",),
+    template_paths=("rules/gitwise.md.template",),
+    template_dir="share/continue",
+)

gitwise/setup_agents/providers/cursor.py

@@ -0,0 +1,11 @@
+"""Cursor provider — .cursor/rules/*.mdc (MDC format with YAML frontmatter)."""
+
+from gitwise.setup_agents.providers.base import AdapterConfig
+
+ADAPTER = AdapterConfig(
+    name="cursor",
+    display_name="Cursor",
+    config_paths=(".cursor/rules/gitwise.mdc",),
+    template_paths=("rules/gitwise.mdc.template",),
+    template_dir="share/cursor",
+)

gitwise/setup_agents/providers/opencode.py

@@ -0,0 +1,11 @@
+"""OpenCode provider — .opencode/agents/*.md."""
+
+from gitwise.setup_agents.providers.base import AdapterConfig
+
+ADAPTER = AdapterConfig(
+    name="opencode",
+    display_name="OpenCode",
+    config_paths=(".opencode/agents/gitwise.md",),
+    template_paths=("agents/gitwise.md.template",),
+    template_dir="share/opencode",
+)

gitwise/setup_agents/providers/pi.py

@@ -0,0 +1,11 @@
+"""Pi provider — .pi/agent/skills/gitwise.md."""
+
+from gitwise.setup_agents.providers.base import AdapterConfig
+
+ADAPTER = AdapterConfig(
+    name="pi",
+    display_name="Pi",
+    config_paths=(".pi/agent/skills/gitwise.md",),
+    template_paths=("skills/gitwise.md.template",),
+    template_dir="share/pi",
+)