gitwise-cli 0.24.2__py3-none-any.whl

gitwise/setup_agents/plan.py

@@ -0,0 +1,254 @@
+"""Planning phase for setup-agents: action generation without side effects."""
+
+from pathlib import Path
+
+from gitwise.i18n import t
+from gitwise.setup_agents.plan_gitfiles import (
+    gitattributes_block_basic,
+    gitattributes_block_extended,
+    gitignore_block_basic,
+    gitignore_block_extended,
+    plan_managed_block,
+)
+from gitwise.setup_agents.plan_skills import (
+    _SKILLS,
+    _read_skill_template,
+    plan_skills,
+)
+from gitwise.setup_agents.providers import detect_global_skills
+from gitwise.setup_agents.providers.claude import ADAPTER as CLAUDE_PROVIDER
+from gitwise.setup_agents.state import (
+    _detect_state,
+)
+from gitwise.setup_agents.types import StateDict
+
+
+def _snapshot_file_for_state(*, has_agents_layout: bool) -> str:
+    if has_agents_layout:
+        return ".agents/git-snapshot.md"
+    return ".claude/git-snapshot.md"
+
+
+def _is_clean_repo_for_canonical_default(
+    *,
+    state: StateDict,
+    migrate_legacy_claude: bool,
+    force_claude_core: bool,
+) -> bool:
+    if migrate_legacy_claude or force_claude_core:
+        return False
+    return state["a_state"] == "absent" and state["c_state"] == "absent"
+
+
+def _plan_canonical_skills(root: Path) -> list[dict]:
+    actions: list[dict] = []
+    for skill in _SKILLS:
+        skill_dir = root / ".agents" / "skills" / skill
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_dir.exists():
+            actions.append({"file": f".agents/skills/{skill}", "action": "mkdir"})
+        if skill_file.exists():
+            actions.append(
+                {
+                    "file": f".agents/skills/{skill}/SKILL.md",
+                    "action": "skip",
+                    "reason": t("already_exists"),
+                }
+            )
+        else:
+            actions.append(
+                {
+                    "file": f".agents/skills/{skill}/SKILL.md",
+                    "action": "create",
+                    "content": _read_skill_template(skill),
+                }
+            )
+    return actions
+
+
+def _legacy_skill_warnings(root: Path) -> list[str]:
+    warnings: list[str] = []
+    legacy_dir = root / ".claude" / "commands"
+    for skill in _SKILLS:
+        if (legacy_dir / f"{skill}.md").exists():
+            warnings.append(t("legacy_commands", skill=skill))
+    return warnings
+
+
+def _plan_settings_json(root: Path) -> tuple[list[dict], list[str]]:
+    return CLAUDE_PROVIDER.plan_settings(root)
+
+
+def _plan_rules(root: Path) -> tuple[list[dict], list[str]]:
+    return CLAUDE_PROVIDER.plan_rules(root)
+
+
+def _plan_actions_global(
+    home: Path,
+    no_skills: bool = False,
+) -> tuple[list[dict], list[str], list[dict]]:
+    return CLAUDE_PROVIDER.plan_global(home, no_skills=no_skills)
+
+
+def _bucket1_no_agents(
+    state: StateDict,
+    root: Path,
+    template: str,
+) -> tuple[int, list[dict], list[str]]:
+    return CLAUDE_PROVIDER.bucket1_no_agents(state, root, template)
+
+
+def _bucket2_agents_no_claude(
+    _state: StateDict,
+    root: Path,
+    supports_symlinks: bool,
+    template: str,
+) -> tuple[int, list[dict], list[str]]:
+    return CLAUDE_PROVIDER.bucket2_agents_no_claude(root, supports_symlinks, template)
+
+
+def _bucket3(
+    state: StateDict,
+    claude_md: Path,
+    agents_md: Path,
+    agents_actions: list[dict],
+) -> tuple[int, list[dict], list[str]]:
+    return CLAUDE_PROVIDER.bucket3(state, claude_md, agents_md, agents_actions)
+
+
+def _bucket4_default(
+    state: StateDict,
+    claude_md: Path,
+    agents_actions: list[dict],
+) -> tuple[int, list[dict], list[str]]:
+    return CLAUDE_PROVIDER.bucket4_default(state, claude_md, agents_actions)
+
+
+def _bucket4_replace(
+    agents_actions: list[dict],
+    claude_md: Path,
+) -> tuple[int, list[dict], list[str]]:
+    return CLAUDE_PROVIDER.bucket4_replace(agents_actions, claude_md)
+
+
+def _resolve_canonical_doc(
+    root: Path,
+    state: StateDict,
+    no_symlinks: bool = False,
+    replace_claude_with_symlink: bool = False,
+    migrate_legacy_claude: bool = False,
+) -> tuple[int, list[dict], list[str]]:
+    return CLAUDE_PROVIDER.resolve_canonical_doc(
+        root,
+        state,
+        no_symlinks=no_symlinks,
+        replace_claude_with_symlink=replace_claude_with_symlink,
+        migrate_legacy_claude=migrate_legacy_claude,
+    )
+
+
+def _plan_actions(
+    root: Path,
+    no_symlinks: bool = False,
+    replace_claude_with_symlink: bool = False,
+    migrate_legacy_claude: bool = False,
+    force_claude_core: bool = False,
+    no_git_files: bool = False,
+    frozen_time: bool = False,
+) -> tuple[list[dict], list[str], list[dict], int, StateDict]:
+    state = _detect_state(root)
+    if state["errors"]:
+        err_actions: list[dict] = [
+            {"file": "", "action": "error", "reason": r} for r in state["errors"]
+        ]
+        return [], [], err_actions, 5, state
+
+    canonical_clean = _is_clean_repo_for_canonical_default(
+        state=state,
+        migrate_legacy_claude=migrate_legacy_claude,
+        force_claude_core=force_claude_core,
+    )
+
+    global_skills = detect_global_skills()
+
+    if canonical_clean:
+        bucket = 1
+        doc_actions = [
+            {
+                "file": "AGENTS.md",
+                "action": "create",
+                "content": CLAUDE_PROVIDER.build_template(root),
+            }
+        ]
+        doc_warnings: list[str] = []
+        settings_actions: list[dict] = []
+        settings_warnings: list[str] = []
+        skills_actions = _plan_canonical_skills(root)
+        skills_warnings = [t("skill_globally_available", skill=skill) for skill in global_skills]
+        skills_warnings += _legacy_skill_warnings(root)
+        rules_actions: list[dict] = []
+        rules_warnings: list[str] = []
+        has_agents_layout = True
+    else:
+        bucket, doc_actions, doc_warnings = _resolve_canonical_doc(
+            root,
+            state,
+            no_symlinks=no_symlinks,
+            replace_claude_with_symlink=replace_claude_with_symlink,
+            migrate_legacy_claude=migrate_legacy_claude,
+        )
+        settings_actions, settings_warnings = _plan_settings_json(root)
+        has_agents_layout = state["agents_dir"] or migrate_legacy_claude
+        skills_actions, skills_warnings = plan_skills(
+            root,
+            state,
+            global_skills=global_skills,
+            force_agents_layout=has_agents_layout,
+        )
+        rules_actions, rules_warnings = _plan_rules(root)
+
+    has_agents_md = state["a_state"] != "absent" or canonical_clean
+    has_agents_dir = has_agents_layout
+
+    git_file_actions: list[dict] = []
+    git_file_warnings: list[str] = []
+    if not no_git_files and bucket != 5:
+        if has_agents_md or has_agents_dir:
+            gi_block = gitignore_block_extended(has_agents_md, has_agents_dir=has_agents_dir)
+            ga_block = gitattributes_block_extended(has_agents_md, has_agents_dir)
+        else:
+            gi_block = gitignore_block_basic()
+            ga_block = gitattributes_block_basic()
+
+        gi_actions, gi_warnings = plan_managed_block(root / ".gitignore", gi_block, ".gitignore")
+        ga_actions, ga_warnings = plan_managed_block(
+            root / ".gitattributes", ga_block, ".gitattributes"
+        )
+        git_file_actions = gi_actions + ga_actions
+        git_file_warnings = gi_warnings + ga_warnings
+
+    actions = (
+        doc_actions
+        + settings_actions
+        + skills_actions
+        + rules_actions
+        + git_file_actions
+        + [
+            {
+                "file": _snapshot_file_for_state(has_agents_layout=has_agents_layout),
+                "action": "generate",
+                "frozen_time": frozen_time,
+            }
+        ]
+    )
+    warnings = (
+        doc_warnings
+        + settings_warnings
+        + skills_warnings
+        + rules_warnings
+        + git_file_warnings
+        + state["rules_warnings"]
+    )
+    if migrate_legacy_claude:
+        warnings.append(t("legacy_migration_mode"))
+    return actions, warnings, [], bucket, state

gitwise/setup_agents/plan_gitfiles.py

@@ -0,0 +1,167 @@
+"""Managed gitignore/gitattributes blocks for setup-agents."""
+
+from pathlib import Path
+
+from gitwise.i18n import t
+
+_MANAGED_MARKER_START = "# >>> gitwise managed (do not edit between markers) >>>"
+_MANAGED_MARKER_END = "# <<< gitwise managed <<<"
+
+
+def _snapshot_path_for_block(*, has_agents_dir: bool) -> str:
+    if has_agents_dir:
+        return ".agents/git-snapshot.md"
+    return ".claude/git-snapshot.md"
+
+
+def gitignore_block_basic() -> str:
+    lines = [
+        _MANAGED_MARKER_START,
+        "# Claude Code local/personal files (do not commit)",
+        ".claude/settings.local.json",
+        ".claude/.credentials.json",
+        "# Snapshot regenerated each gitwise run (timestamps change)",
+        _snapshot_path_for_block(has_agents_dir=False),
+        "# Backups from gitwise setup-agents",
+        "*.bak",
+        "CLAUDE.md.bak*",
+        _MANAGED_MARKER_END,
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def gitignore_block_extended(has_agents_md: bool, has_agents_dir: bool = False) -> str:
+    lines = [
+        _MANAGED_MARKER_START,
+        "# Claude Code local/personal files (do not commit)",
+        ".claude/settings.local.json",
+        ".claude/.credentials.json",
+        "# Snapshot regenerated each gitwise run (timestamps change)",
+        _snapshot_path_for_block(has_agents_dir=has_agents_dir),
+        "# Backups from gitwise setup-agents",
+        "*.bak",
+        "CLAUDE.md.bak*",
+    ]
+    if has_agents_md:
+        lines.append("AGENTS.md.bak*")
+    lines.append(_MANAGED_MARKER_END)
+    return "\n".join(lines) + "\n"
+
+
+def gitattributes_block_basic() -> str:
+    lines = [
+        _MANAGED_MARKER_START,
+        "# Generated snapshot: use local version on merge",
+        f"{_snapshot_path_for_block(has_agents_dir=False)} merge=ours linguist-generated=true",
+        "# Convention files: force LF for cross-platform consistency",
+        "CLAUDE.md text=auto eol=lf",
+        ".claude/skills/**/SKILL.md text=auto eol=lf",
+        _MANAGED_MARKER_END,
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def gitattributes_block_extended(has_agents_md: bool, has_agents_dir: bool) -> str:
+    lines = [
+        _MANAGED_MARKER_START,
+        "# Generated snapshot: use local version on merge",
+        f"{_snapshot_path_for_block(has_agents_dir=has_agents_dir)} merge=ours linguist-generated=true",
+        "# Convention files: force LF for cross-platform consistency",
+        "CLAUDE.md text=auto eol=lf",
+    ]
+    if has_agents_md:
+        lines.append("AGENTS.md text=auto eol=lf")
+    lines.append(".claude/skills/**/SKILL.md text=auto eol=lf")
+    if has_agents_dir:
+        lines.append(".agents/skills/**/SKILL.md text=auto eol=lf")
+    lines.append(_MANAGED_MARKER_END)
+    return "\n".join(lines) + "\n"
+
+
+def _gitattributes_conflicts(existing_text: str, desired_block: str) -> list[str]:
+    block_start = existing_text.find(_MANAGED_MARKER_START)
+    outside_text = existing_text[:block_start] if block_start != -1 else existing_text
+
+    def _parse(text: str) -> dict[str, str]:
+        result: dict[str, str] = {}
+        for line in text.splitlines():
+            s = line.strip()
+            if not s or s.startswith("#"):
+                continue
+            parts = s.split(None, 1)
+            if len(parts) > 1:
+                result[parts[0]] = s
+        return result
+
+    outside = _parse(outside_text)
+    block = _parse(desired_block)
+    warnings: list[str] = []
+    for pattern, block_line in block.items():
+        if pattern in outside and outside[pattern] != block_line:
+            warnings.append(
+                t(
+                    "gitattributes_conflict",
+                    pattern=pattern,
+                    existing=outside[pattern],
+                    desired=block_line,
+                )
+            )
+    return warnings
+
+
+def plan_managed_block(
+    path: Path, desired_block: str, file_key: str
+) -> tuple[list[dict], list[str]]:
+    if not path.exists():
+        return [
+            {
+                "file": file_key,
+                "action": "managed-block-create",
+                "content": desired_block,
+                "_path": str(path),
+            }
+        ], []
+
+    try:
+        current = path.read_text(encoding="utf-8")
+    except OSError:
+        return [], []
+
+    conflict_warnings = (
+        _gitattributes_conflicts(current, desired_block) if file_key == ".gitattributes" else []
+    )
+
+    if _MANAGED_MARKER_START not in current:
+        return [
+            {
+                "file": file_key,
+                "action": "managed-block-create",
+                "content": desired_block,
+                "_path": str(path),
+                "_append": True,
+            }
+        ], conflict_warnings
+
+    start_idx = current.index(_MANAGED_MARKER_START)
+    end_marker_idx = current.find(_MANAGED_MARKER_END, start_idx)
+    if end_marker_idx == -1:
+        return [], [t("managed_block_unclosed", file=file_key)] + conflict_warnings
+
+    end_idx = end_marker_idx + len(_MANAGED_MARKER_END)
+    existing_block = current[start_idx:end_idx]
+
+    if existing_block.rstrip() == desired_block.rstrip():
+        return [
+            {"file": file_key, "action": "managed-block-skip", "_path": str(path)}
+        ], conflict_warnings
+
+    return [
+        {
+            "file": file_key,
+            "action": "managed-block-replace",
+            "content": desired_block,
+            "_path": str(path),
+            "_start_idx": start_idx,
+            "_end_idx": end_idx,
+        }
+    ], conflict_warnings

gitwise/setup_agents/plan_skills.py

@@ -0,0 +1,256 @@
+"""Unified skills planning for setup-agents (local + global)."""
+
+import os
+from pathlib import Path
+
+from gitwise._paths import share_dir as _share_dir
+from gitwise.i18n import t
+from gitwise.setup_agents.state import _classify_path
+from gitwise.setup_agents.types import StateDict
+
+_SHARE_CLAUDE_DIR = _share_dir() / "claude"
+_SHARE_AGENTS_DIR = _share_dir() / "agents"
+_SKILLS: tuple[str, ...] = ("git-audit", "git-clean", "git-optimize")
+
+
+def _read_template(name: str) -> str:
+    path = _SHARE_CLAUDE_DIR / name
+    if not path.is_file():
+        raise FileNotFoundError(t("template_not_found", path=str(path)))
+    return path.read_text(encoding="utf-8")
+
+
+def _read_skill_template(skill: str) -> str:
+    candidates = (
+        _SHARE_AGENTS_DIR / "skills" / skill / "SKILL.md",
+        _SHARE_CLAUDE_DIR / "skills" / skill / "SKILL.md",
+    )
+    for path in candidates:
+        if path.is_file():
+            return path.read_text(encoding="utf-8")
+    raise FileNotFoundError(
+        t("template_not_found", path=str(_SHARE_AGENTS_DIR / "skills" / skill / "SKILL.md"))
+    )
+
+
+def _plan_single_skill(
+    *,
+    skill: str,
+    root: Path,
+    has_agents_dir: bool,
+    global_skills: frozenset[str],
+    force_agents_layout: bool,
+    check_global_available: bool,
+    symlink_mismatch_key: str,
+    symlink_broken_key: str,
+    dir_regular_with_agents_key: str,
+) -> tuple[list[dict], list[str]]:
+    actions: list[dict] = []
+    warnings: list[str] = []
+
+    agents_skills_dir = root / ".agents" / "skills"
+    claude_skills = root / ".claude" / "skills"
+    claude_skill = claude_skills / skill
+    skill_file = f".claude/skills/{skill}/SKILL.md"
+    c_skill_state = _classify_path(claude_skill)
+
+    if has_agents_dir or force_agents_layout:
+        agents_skill = agents_skills_dir / skill
+        target_rel = os.path.relpath(str(agents_skill), str(claude_skill.parent))
+
+        if c_skill_state == "absent":
+            if skill in global_skills:
+                if check_global_available:
+                    warnings.append(t("skill_globally_available", skill=skill))
+            else:
+                if not agents_skill.exists():
+                    actions.append({"file": f".agents/skills/{skill}", "action": "mkdir"})
+                actions.append(
+                    {
+                        "file": f".claude/skills/{skill}",
+                        "action": "symlink-create",
+                        "target_relative": target_rel,
+                    }
+                )
+                actions.append(
+                    {
+                        "file": skill_file,
+                        "action": "create",
+                        "content": _read_skill_template(skill),
+                    }
+                )
+        elif c_skill_state == "symlink_valid":
+            try:
+                existing_target = os.readlink(str(claude_skill))
+            except OSError:
+                existing_target = ""
+            if existing_target == target_rel:
+                if (claude_skill / "SKILL.md").exists():
+                    actions.append(
+                        {"file": skill_file, "action": "skip", "reason": t("already_exists")}
+                    )
+                else:
+                    actions.append(
+                        {
+                            "file": skill_file,
+                            "action": "create",
+                            "content": _read_skill_template(skill),
+                        }
+                    )
+            else:
+                warnings.append(
+                    t(
+                        symlink_mismatch_key,
+                        skill=skill,
+                        existing=existing_target,
+                        expected=target_rel,
+                    )
+                )
+        elif c_skill_state == "symlink_broken":
+            warnings.append(t(symlink_broken_key, skill=skill))
+        else:
+            if check_global_available and agents_skill.exists():
+                warnings.append(t("skill_conflict_dir_agents", skill=skill))
+                actions.append(
+                    {"file": skill_file, "action": "skip", "reason": t("conflict_dir_agents")}
+                )
+            elif check_global_available and not agents_skill.exists():
+                actions.append(
+                    {
+                        "file": f".claude/skills/{skill}",
+                        "action": "skill-migrate-to-agents",
+                        "target_relative": target_rel,
+                        "agents_skill": str(agents_skill),
+                    }
+                )
+            else:
+                warnings.append(t(dir_regular_with_agents_key, skill=skill))
+                if (claude_skill / "SKILL.md").exists():
+                    actions.append(
+                        {"file": skill_file, "action": "skip", "reason": t("already_exists")}
+                    )
+                else:
+                    actions.append(
+                        {
+                            "file": skill_file,
+                            "action": "create",
+                            "content": _read_skill_template(skill),
+                        }
+                    )
+    else:
+        if skill in global_skills and not (claude_skill / "SKILL.md").exists():
+            warnings.append(t("skill_globally_available", skill=skill))
+            actions.append(
+                {"file": skill_file, "action": "skip", "reason": t("installed_globally")}
+            )
+        elif (claude_skill / "SKILL.md").exists():
+            actions.append({"file": skill_file, "action": "skip", "reason": t("already_exists")})
+        else:
+            actions.append(
+                {
+                    "file": skill_file,
+                    "action": "create",
+                    "content": _read_skill_template(skill),
+                }
+            )
+
+    return actions, warnings
+
+
+def plan_skills(
+    root: Path,
+    state: StateDict,
+    global_skills: frozenset[str] = frozenset(),
+    force_agents_layout: bool = False,
+) -> tuple[list[dict], list[str]]:
+    actions: list[dict] = []
+    warnings: list[str] = []
+
+    claude_skills = root / ".claude" / "skills"
+    skills_state = state["skills_state"]
+    has_agents_dir = state["agents_dir"] or force_agents_layout
+
+    if skills_state == "symlink_valid":
+        for skill in _SKILLS:
+            skill_file = f".claude/skills/{skill}/SKILL.md"
+            if skill in global_skills:
+                actions.append(
+                    {"file": skill_file, "action": "skip", "reason": t("installed_globally")}
+                )
+            elif (claude_skills / skill / "SKILL.md").exists():
+                actions.append(
+                    {"file": skill_file, "action": "skip", "reason": t("already_exists")}
+                )
+            else:
+                actions.append(
+                    {
+                        "file": skill_file,
+                        "action": "create",
+                        "content": _read_skill_template(skill),
+                    }
+                )
+    else:
+        for skill in _SKILLS:
+            sk_actions, sk_warnings = _plan_single_skill(
+                skill=skill,
+                root=root,
+                has_agents_dir=has_agents_dir,
+                global_skills=global_skills,
+                force_agents_layout=force_agents_layout,
+                check_global_available=False,
+                symlink_mismatch_key="skill_symlink_diferente",
+                symlink_broken_key="skill_symlink_broken",
+                dir_regular_with_agents_key="skill_dir_regular_with_agents",
+            )
+            actions += sk_actions
+            warnings += sk_warnings
+
+    legacy_dir = root / ".claude" / "commands"
+    for skill in _SKILLS:
+        if (legacy_dir / f"{skill}.md").exists():
+            warnings.append(t("legacy_commands", skill=skill))
+
+    return actions, warnings
+
+
+def plan_global_skills(home: Path) -> tuple[list[dict], list[str]]:
+    actions: list[dict] = []
+    warnings: list[str] = []
+
+    agents_dir = home / ".agents"
+    has_agents_dir = agents_dir.is_dir() and not agents_dir.is_symlink()
+    claude_skills = home / ".claude" / "skills"
+    claude_skills_state = _classify_path(claude_skills)
+
+    if claude_skills_state == "symlink_valid":
+        for skill in _SKILLS:
+            skill_file = f".claude/skills/{skill}/SKILL.md"
+            if (claude_skills / skill / "SKILL.md").exists():
+                actions.append(
+                    {"file": skill_file, "action": "skip", "reason": t("already_exists")}
+                )
+            else:
+                actions.append(
+                    {
+                        "file": skill_file,
+                        "action": "create",
+                        "content": _read_template(f"skills/{skill}/SKILL.md"),
+                    }
+                )
+    else:
+        for skill in _SKILLS:
+            sk_actions, sk_warnings = _plan_single_skill(
+                skill=skill,
+                root=home,
+                has_agents_dir=has_agents_dir,
+                global_skills=frozenset(),
+                force_agents_layout=False,
+                check_global_available=True,
+                symlink_mismatch_key="global_skill_symlink_diferente",
+                symlink_broken_key="global_skill_symlink_broken",
+                dir_regular_with_agents_key="skill_dir_regular_with_agents",
+            )
+            actions += sk_actions
+            warnings += sk_warnings
+
+    return actions, warnings