"""Skill install, remove, and fork operations.

Handles filesystem operations for the hive skill CLI:
  - install_from_git:      git clone --depth=1 → copy to target directory
  - install_from_registry: resolve registry entry → delegate to install_from_git
  - remove_skill:          delete a skill from ~/.hive/skills/
  - fork_skill:            copy a skill to a new location with a new name
  - maybe_show_install_notice: one-time security notice on first install (NFR-5)
"""

from __future__ import annotations

import shutil
import subprocess
import tempfile
from pathlib import Path

from framework.skills.parser import ParsedSkill
from framework.skills.skill_errors import SkillError, SkillErrorCode

# Default install destination for user-scope skills + sentinel file for
# the one-time security notice on first install (NFR-5). Computed via
# helpers so HIVE_HOME (set by the desktop shell to a per-user dir)
# is honoured. ``framework.config.HIVE_HOME`` is module-global and
# resolved at first import — so a single call here is enough; we don't
# need to re-resolve on every access.
def _user_skills_dir() -> Path:
    from framework.config import HIVE_HOME

    return HIVE_HOME / "skills"


def _install_notice_sentinel() -> Path:
    from framework.config import HIVE_HOME

    return HIVE_HOME / ".install_notice_shown"

_INSTALL_NOTICE = """\
─────────────────────────────────────────────────────────────
  Security Notice: Installing Third-Party Skills
─────────────────────────────────────────────────────────────
  Skills are instructions executed by AI agents. A malicious
  skill can manipulate agent behavior, exfiltrate data, or
  cause unintended actions.

  Only install skills from sources you trust. Review the
  SKILL.md before running it in a production environment.

  This notice is shown once. Use 'hive skill doctor' to audit
  installed skills at any time.
─────────────────────────────────────────────────────────────
"""


def maybe_show_install_notice() -> None:
    """Print a one-time security notice before the first skill install (NFR-5).

    Touches a sentinel file in $HIVE_HOME after showing the notice so it is
    only displayed once across all future installs.
    """
    sentinel = _install_notice_sentinel()
    if sentinel.exists():
        return
    print(_INSTALL_NOTICE, flush=True)
    try:
        sentinel.parent.mkdir(parents=True, exist_ok=True)
        sentinel.touch()
    except OSError:
        pass  # If we can't write the sentinel, just show the notice every time


def install_from_git(
    git_url: str,
    skill_name: str,
    subdirectory: str | None = None,
    version: str | None = None,
    target_dir: Path | None = None,
) -> Path:
    """Install a skill from a git repository.

    Clones the repository with --depth=1 into a temporary directory, then
    copies the skill subdirectory (or repo root) to the target location.

    Args:
        git_url:     Git repository URL to clone.
        skill_name:  Name of the skill — used as the install directory name.
        subdirectory: Relative path within the repo to the skill directory.
                     If None, the repo root is treated as the skill directory.
        version:     Git ref to checkout (tag, branch, or commit). Defaults to
                     the remote's default branch.
        target_dir:  Where to install the skill. Defaults to
                     ~/.hive/skills/<skill_name>/.

    Returns:
        Path to the installed skill directory (the parent of SKILL.md).

    Raises:
        SkillError: On any failure (git not found, clone failed, SKILL.md missing).
    """
    if shutil.which("git") is None:
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"Cannot install '{skill_name}' from {git_url}",
            why="git is not installed or not on PATH.",
            fix="Install git (https://git-scm.com/) and retry.",
        )

    dest = (target_dir or _user_skills_dir()) / skill_name
    if dest.exists():
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"Cannot install '{skill_name}'",
            why=f"Directory already exists: {dest}",
            fix=f"Run 'hive skill remove {skill_name}' first, or use a different --name.",
        )

    tmp_dir = tempfile.mkdtemp(prefix="hive-skill-install-")
    try:
        _git_clone_shallow(git_url, Path(tmp_dir), version=version)

        # Locate the skill within the cloned repo
        source_dir = Path(tmp_dir) / subdirectory if subdirectory else Path(tmp_dir)
        skill_md = source_dir / "SKILL.md"
        if not skill_md.exists():
            raise SkillError(
                code=SkillErrorCode.SKILL_NOT_FOUND,
                what=f"No SKILL.md found in '{subdirectory or '/'}' of {git_url}",
                why="The expected SKILL.md file is not present at the given path.",
                fix=(
                    "Check the repository structure and use "
                    "'hive skill install --from <url>' with the correct subdirectory."
                ),
            )

        dest.parent.mkdir(parents=True, exist_ok=True)
        _copy_skill_dir(source_dir, dest)
        return dest

    except SkillError:
        raise
    except Exception as exc:
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"Failed to install '{skill_name}' from {git_url}",
            why=str(exc),
            fix="Check the URL, your network connection, and git configuration.",
        ) from exc
    finally:
        shutil.rmtree(tmp_dir, ignore_errors=True)


def install_from_registry(
    registry_entry: dict,
    target_dir: Path | None = None,
    version: str | None = None,
) -> Path:
    """Install a skill using a registry index entry.

    Resolves the git_url and subdirectory from the registry entry and
    delegates to install_from_git.

    Args:
        registry_entry: A skill entry dict from skill_index.json.
        target_dir:     Override install destination.
        version:        Override version (defaults to entry's 'version' field).

    Returns:
        Path to the installed skill directory.

    Raises:
        SkillError: If the registry entry is missing required fields or install fails.
    """
    name = registry_entry.get("name")
    git_url = registry_entry.get("git_url")

    if not name or not git_url:
        raise SkillError(
            code=SkillErrorCode.SKILL_NOT_FOUND,
            what="Incomplete registry entry — missing 'name' or 'git_url'.",
            why="The registry index entry does not contain all required fields.",
            fix="Report this issue to the registry maintainer.",
        )

    resolved_version = version or registry_entry.get("version")
    subdirectory = registry_entry.get("subdirectory")

    return install_from_git(
        git_url=git_url,
        skill_name=str(name),
        subdirectory=subdirectory,
        version=resolved_version,
        target_dir=target_dir,
    )


def remove_skill(name: str, skills_dir: Path | None = None) -> bool:
    """Remove an installed skill from the user skills directory.

    Args:
        name:       Skill directory name to remove.
        skills_dir: Override the search directory (default: ~/.hive/skills/).

    Returns:
        True if removed, False if not found.

    Raises:
        SkillError: If the directory exists but cannot be removed.
    """
    target = (skills_dir or _user_skills_dir()) / name
    if not target.exists():
        return False
    try:
        shutil.rmtree(target)
        return True
    except OSError as exc:
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"Failed to remove skill '{name}' at {target}",
            why=str(exc),
            fix="Check file permissions and try again.",
        ) from exc


def fork_skill(
    source: ParsedSkill,
    new_name: str,
    target_dir: Path,
) -> Path:
    """Create a local editable copy of a skill with a new name.

    Copies the skill's base directory to target_dir/new_name/ and rewrites
    the 'name' field in the copied SKILL.md frontmatter.

    Args:
        source:     The source skill to fork (from SkillDiscovery).
        new_name:   Name for the forked skill.
        target_dir: Parent directory for the fork (e.g. ~/.hive/skills/).

    Returns:
        Path to the forked skill directory.

    Raises:
        SkillError: If the target already exists or the copy fails.
    """
    dest = target_dir / new_name
    if dest.exists():
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"Cannot fork to '{dest}'",
            why="Target directory already exists.",
            fix=f"Choose a different --name or remove '{dest}' first.",
        )

    source_dir = Path(source.base_dir)
    try:
        dest.parent.mkdir(parents=True, exist_ok=True)
        _copy_skill_dir(source_dir, dest)
    except OSError as exc:
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"Failed to fork skill '{source.name}' to '{dest}'",
            why=str(exc),
            fix="Check file permissions and available disk space.",
        ) from exc

    # Rewrite the name in the forked SKILL.md via YAML round-trip (safe)
    forked_skill_md = dest / "SKILL.md"
    if forked_skill_md.exists():
        _rewrite_name_in_skill_md(forked_skill_md, new_name)

    return dest


# ---------------------------------------------------------------------------
# Internal helpers
# ---------------------------------------------------------------------------


def _git_clone_shallow(git_url: str, target: Path, version: str | None = None) -> None:
    """Clone a git repo at --depth=1 into target directory.

    Args:
        git_url: Repository URL.
        target:  Destination directory (will be created by git).
        version: Optional git ref (branch/tag) to clone.

    Raises:
        SkillError: If the clone fails.
    """
    cmd = ["git", "clone", "--depth=1"]
    if version:
        cmd += ["--branch", version]
    cmd += [git_url, str(target)]

    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=60,
        )
    except subprocess.TimeoutExpired:
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"git clone timed out for {git_url}",
            why="The clone operation took longer than 60 seconds.",
            fix="Check your network connection and retry.",
        ) from None
    except (FileNotFoundError, OSError) as exc:
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"Cannot run git for {git_url}",
            why=str(exc),
            fix="Ensure git is installed and on PATH.",
        ) from exc

    if result.returncode != 0:
        stderr = result.stderr.strip()
        raise SkillError(
            code=SkillErrorCode.SKILL_ACTIVATION_FAILED,
            what=f"git clone failed for {git_url}",
            why=stderr or f"git exited with code {result.returncode}",
            fix="Check the URL is correct and the repository is publicly accessible.",
        )


def _copy_skill_dir(src: Path, dst: Path) -> None:
    """Copy a skill directory, ignoring VCS and cache artifacts."""
    ignore = shutil.ignore_patterns(".git", "__pycache__", "*.pyc", ".venv", "venv", "node_modules")
    shutil.copytree(src, dst, ignore=ignore)


def _rewrite_name_in_skill_md(skill_md: Path, new_name: str) -> None:
    """Rewrite the 'name' field in a SKILL.md frontmatter via YAML round-trip.

    Parses the frontmatter with yaml.safe_load, updates 'name', re-serializes
    with yaml.dump, and reconstructs the file as:
        ---
        <yaml>
        ---
        <body>

    Falls back to no-op if the file can't be parsed (the copy is still usable).
    """
    import yaml

    try:
        content = skill_md.read_text(encoding="utf-8")
        parts = content.split("---", 2)
        if len(parts) < 3:
            return
        frontmatter = yaml.safe_load(parts[1].strip())
        if not isinstance(frontmatter, dict):
            return
        frontmatter["name"] = new_name
        new_yaml = yaml.dump(frontmatter, default_flow_style=False, allow_unicode=True)
        new_content = f"---\n{new_yaml}---\n{parts[2]}"
        skill_md.write_text(new_content, encoding="utf-8")
    except Exception:
        pass  # Degraded: forked copy works, name just isn't updated