#!/usr/bin/env python3
"""Interactive project setup for the ContextGuard plugin.

The wizard applies only project-local, opt-in settings. It can run interactively
in a terminal, or non-interactively with --yes/--plan for Claude Code skills and
CI tests.
"""
from __future__ import annotations

import argparse
import copy
import datetime as _dt
import json
import os
import re
import shlex
import shutil
import stat
import subprocess
import sys
import uuid
from dataclasses import dataclass
from pathlib import Path
from typing import Any

try:
    import fcntl
except ImportError:  # pragma: no cover - setup already requires POSIX no-follow file ops.
    fcntl = None

SETTINGS_REL = Path(".claude/settings.json")

RECOMMENDED_DENIES = [
    "Read(./node_modules/**)",
    "Read(./dist/**)",
    "Read(./build/**)",
    "Read(./coverage/**)",
    "Read(./logs/**)",
    "Read(./tmp/**)",
    "Read(./target/**)",
    "Read(./.next/**)",
    "Read(./.venv/**)",
    "Read(./vendor/**)",
    "Read(./.context-guard/**)",
    "Read(./.claude-token-optimizer/**)",
    "Read(./.env)",
    "Read(./.env.*)",
    "Read(./.npmrc)",
    "Read(./.pypirc)",
    "Read(./.netrc)",
    "Read(~/.ssh/**)",
    "Read(~/.aws/**)",
    "Read(~/.gnupg/**)",
    "Read(~/.kube/**)",
    "Read(~/.docker/**)",
]
HELPER_STATUSLINE = "context-guard-statusline-merged"
HELPER_REWRITE_BASH = "context-guard-rewrite-bash"
HELPER_GUARD_READ = "context-guard-guard-read"
HELPER_FAILED_NUDGE = "context-guard-failed-nudge"
HELPER_DIET = "context-guard-diet"
HELPER_EQUIVALENT_BASENAMES = {
    "context-guard-rewrite-bash": {
        "context-guard-rewrite-bash",
        "claude-token-rewrite-bash",
        "rewrite_bash_for_token_budget.py",
    },
    "context-guard-guard-read": {
        "context-guard-guard-read",
        "claude-token-guard-read",
        "guard_large_read.py",
    },
    "context-guard-failed-nudge": {
        "context-guard-failed-nudge",
        "claude-token-failed-nudge",
        "failed_attempt_nudge.py",
    },
    "context-guard-statusline-merged": {
        "context-guard-statusline-merged",
        "claude-token-statusline-merged",
        "statusline_merged.sh",
    },
    "context-guard-statusline": {
        "context-guard-statusline",
        "claude-token-statusline",
        "statusline.sh",
    },
}
DEFAULT_MODEL = "sonnet"
DEFAULT_EFFORT = "medium"
DEFAULT_FAILED_ATTEMPT_NUDGE = True
DEFAULT_POST_SETUP_SCAN_TOP = 5
POST_SETUP_SCAN_TIMEOUT_SECONDS = 20
PRIVATE_DIR_MODE = stat.S_IRWXU
ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
    "tmp": Path("/private/tmp"),
    "var": Path("/private/var"),
}


@dataclass
class Choices:
    denies: bool = True
    statusline: bool = True
    bash_hook: bool = True
    read_guard: bool = True
    model_defaults: bool = True
    # 동일 Bash 명령이 두 번 연속 실패하면 /clear 권유 — recommended setup 기본 ON.
    failed_attempt_nudge: bool = DEFAULT_FAILED_ATTEMPT_NUDGE


@dataclass
class SetupResult:
    root: Path
    settings_path: Path
    scope: str
    changed: bool
    applied: bool
    apply_requested: bool
    choices: Choices
    actions: list[str]
    backup_path: Path | None = None
    rollback_id: str | None = None
    rollback_path: Path | None = None
    warnings: list[str] | None = None
    diet_scan: dict[str, Any] | None = None
    # Per-agent cross-agent plan; None preserves the legacy Claude-only payload
    # shape for callers that never engage the adapter registry.
    adapter_plan: list[dict[str, Any]] | None = None

    def as_dict(self) -> dict[str, Any]:
        return {
            "root": str(self.root),
            "settings_path": str(self.settings_path),
            "scope": self.scope,
            "changed": self.changed,
            "applied": self.applied,
            "apply_requested": self.apply_requested,
            "backup_path": str(self.backup_path) if self.backup_path else None,
            "rollback_id": self.rollback_id,
            "rollback_path": str(self.rollback_path) if self.rollback_path else None,
            "warnings": self.warnings or [],
            "choices": self.choices.__dict__,
            "actions": self.actions,
            "diet_scan": self.diet_scan,
            "adapter_plan": self.adapter_plan,
        }


# --- Cross-agent adapter registry & dry-run setup planner --------------------
#
# ContextGuard's helpers speak plain JSON over stdin/stdout, so the same
# guardrails can be wired into more than just Claude Code. This registry maps
# known coding agents to a *capability class* that describes HOW ContextGuard
# can integrate with each one, and the planner renders a per-agent setup plan.
#
# The planner stays conservative and Claude-compatible:
# - Only the Claude native-plugin path writes hook settings (the legacy default).
# - Repo-rule agents get an idempotent advisory rule block, opt-in via --with-init.
# - native-skill / report-only agents are never written to; they are reported.
# It never sends work to external providers and never promises token/cost savings.

ADAPTER_RULE_BLOCK_BEGIN = "<!-- contextguard:begin -->"
ADAPTER_RULE_BLOCK_END = "<!-- contextguard:end -->"
CODEX_SKILL_REL = ".agents/skills/context-guard/SKILL.md"
CODEX_SKILL_MARKER_BEGIN = "<!-- contextguard:codex-skill:begin -->"
CODEX_SKILL_MARKER_END = "<!-- contextguard:codex-skill:end -->"


class CapabilityClass:
    """How ContextGuard can integrate with a given agent."""

    NATIVE_PLUGIN = "native-plugin"  # writes native hook settings (Claude Code)
    NATIVE_SKILL = "native-skill"    # invokable skills/commands; no auto-written hooks
    REPO_RULE = "repo-rule"          # reads a repo rule file (AGENTS.md, GEMINI.md, ...)
    REPORT_ONLY = "report-only"      # no integration surface; advisory reporting only


@dataclass(frozen=True)
class AgentAdapter:
    """One known coding agent and how ContextGuard wires into it."""

    key: str
    display_name: str
    capability: str
    summary: str
    settings_rel: str | None = None
    rule_file: str | None = None
    project_skill_rel: str | None = None
    detect: tuple[str, ...] = ()


AGENT_ADAPTERS: tuple[AgentAdapter, ...] = (
    AgentAdapter(
        key="claude",
        display_name="Claude Code",
        capability=CapabilityClass.NATIVE_PLUGIN,
        summary="Installs project-local hooks, denies, and statusline in .claude/settings.json.",
        settings_rel=str(SETTINGS_REL),
        rule_file="CLAUDE.md",
        detect=(".claude",),
    ),
    AgentAdapter(
        key="codex",
        display_name="OpenAI Codex CLI",
        capability=CapabilityClass.REPO_RULE,
        summary="Reads AGENTS.md; add an advisory ContextGuard rule block with --with-init and optional project skill with --with-skill.",
        rule_file="AGENTS.md",
        project_skill_rel=CODEX_SKILL_REL,
        detect=("AGENTS.md", ".codex"),
    ),
    AgentAdapter(
        key="gemini",
        display_name="Gemini CLI",
        capability=CapabilityClass.REPO_RULE,
        summary="Reads GEMINI.md; add an advisory ContextGuard rule block with --with-init.",
        rule_file="GEMINI.md",
        detect=("GEMINI.md", ".gemini"),
    ),
    AgentAdapter(
        key="cursor",
        display_name="Cursor",
        capability=CapabilityClass.REPO_RULE,
        summary="Reads project rules; add an advisory ContextGuard block with --with-init.",
        rule_file=".cursorrules",
        detect=(".cursor", ".cursorrules"),
    ),
    AgentAdapter(
        key="windsurf",
        display_name="Windsurf",
        capability=CapabilityClass.REPO_RULE,
        summary="Reads project rules; add an advisory ContextGuard block with --with-init.",
        rule_file=".windsurf/rules/contextguard.md",
        detect=(".windsurf", ".windsurfrules"),
    ),
    AgentAdapter(
        key="cline",
        display_name="Cline",
        capability=CapabilityClass.REPO_RULE,
        summary="Reads project rules; add an advisory ContextGuard block with --with-init.",
        rule_file=".clinerules",
        detect=(".clinerules", ".cline"),
    ),
    AgentAdapter(
        key="copilot",
        display_name="GitHub Copilot Coding Agent",
        capability=CapabilityClass.REPO_RULE,
        summary="Reads repository instructions; add an advisory ContextGuard block with --with-init.",
        rule_file=".github/copilot-instructions.md",
        detect=(".github/copilot-instructions.md",),
    ),
    AgentAdapter(
        key="opencode",
        display_name="OpenCode",
        capability=CapabilityClass.NATIVE_SKILL,
        summary="Expose ContextGuard helpers as OpenCode commands/rules manually; no hooks are auto-written.",
        detect=("opencode.json", ".opencode"),
    ),
    AgentAdapter(
        key="forgecode",
        display_name="ForgeCode",
        capability=CapabilityClass.REPORT_ONLY,
        summary="No automated setup surface yet; run ContextGuard helpers from the shell and keep evidence local.",
        detect=(".forgecode", "forgecode.json"),
    ),
    AgentAdapter(
        key="generic",
        display_name="Other / unknown agent",
        capability=CapabilityClass.REPORT_ONLY,
        summary="No automated setup surface; run ContextGuard helpers from the shell as needed.",
    ),
)


def adapter_registry() -> dict[str, AgentAdapter]:
    """Return the adapter registry keyed by adapter key."""
    return {adapter.key: adapter for adapter in AGENT_ADAPTERS}


def adapter_registry_payload() -> list[dict[str, Any]]:
    """JSON-friendly view of the adapter registry for --list-adapters."""
    return [
        {
            "key": adapter.key,
            "display_name": adapter.display_name,
            "capability": adapter.capability,
            "summary": adapter.summary,
            "settings_rel": adapter.settings_rel,
            "rule_file": adapter.rule_file,
            "project_skill_rel": adapter.project_skill_rel,
            "detect": list(adapter.detect),
        }
        for adapter in AGENT_ADAPTERS
    ]


def detect_agents(root: Path) -> list[str]:
    """Return adapter keys whose detection markers exist under root."""
    found: list[str] = []
    for adapter in AGENT_ADAPTERS:
        for rel in adapter.detect:
            if (root / rel).exists():
                found.append(adapter.key)
                break
    return found


def resolve_target_adapters(root: Path, only: list[str] | None) -> list[AgentAdapter]:
    """Pick the adapters to plan/apply.

    Default keeps Claude compatibility: Claude is always targeted, plus any other
    agent detected in the repo. ``--only`` restricts to an explicit, validated set
    so a user can, for example, set up only Codex without touching Claude.
    """
    registry = adapter_registry()
    if only:
        keys: list[str] = []
        for raw in only:
            for part in str(raw).split(","):
                key = part.strip().lower()
                if not key:
                    continue
                if key not in registry:
                    known = ", ".join(sorted(registry))
                    raise SystemExit(f"Unknown adapter key: {key!r}. Known adapters: {known}.")
                if key not in keys:
                    keys.append(key)
        return [registry[key] for key in keys]
    detected = set(detect_agents(root))
    keys = ["claude"] + [
        adapter.key
        for adapter in AGENT_ADAPTERS
        if adapter.key not in ("claude", "generic") and adapter.key in detected
    ]
    return [registry[key] for key in keys]


def render_repo_rule_block() -> str:
    """Advisory rule block written into repo-rule files. No savings guarantees."""
    return "\n".join([
        ADAPTER_RULE_BLOCK_BEGIN,
        "## ContextGuard (advisory)",
        "",
        "This repository uses ContextGuard helpers to keep agent context focused.",
        "These guardrails are advisory and do not guarantee any token or cost savings.",
        "",
        "- Prefer reading symbols over whole large files.",
        "- Store large logs as local artifacts and query only the parts you need.",
        "- Trim or summarize noisy command output instead of pasting it whole.",
        "- Treat reported byte reductions as proxy evidence, not proof of savings.",
        "- Keep provider caches and semantic caches opt-in; verify cache hits before claiming savings.",
        "",
        "See the ContextGuard README for the helper commands.",
        ADAPTER_RULE_BLOCK_END,
    ])


def render_codex_skill() -> str:
    """Render the optional project-local Codex skill for ContextGuard."""
    return "\n".join([
        "---",
        "name: context-guard",
        "description: Use ContextGuard helpers to keep Codex context focused with local-first setup, audit, trimming, and artifact commands.",
        "---",
        "",
        CODEX_SKILL_MARKER_BEGIN,
        "# ContextGuard for Codex",
        "",
        "Use this skill when a task would otherwise paste large files, long logs, or repeated setup context into Codex.",
        "",
        "## Progressive disclosure",
        "- Prefer `context-guard audit . --json` or `context-guard diet scan . --json` before broad repo reads.",
        "- Use `context-guard pack` for a small, prioritized local context pack.",
        "- Use `context-guard artifact` for large logs, then query only the relevant slices.",
        "- Use `context-guard trim-output` or `context-guard sanitize-output` before sharing noisy command output.",
        "",
        "## Setup",
        "- Project activation: `context-guard setup --agent codex --scope project --with-init --with-skill --yes`.",
        "- Plan first: `context-guard setup --agent codex --scope project --with-init --with-skill --plan`.",
        "- If `context-guard` is not on PATH, install it explicitly or run via `npx @ictechgy/context-guard`.",
        "",
        "Do not claim fixed token or cost savings from these helpers; treat byte reductions as local proxy evidence only.",
        CODEX_SKILL_MARKER_END,
        "",
    ])


def _read_rule_file_text(path: Path) -> str | None:
    """Best-effort no-follow read; only a missing file is treated as absent.

    Unreadable, symlinked, directory, or otherwise unsafe targets must not be
    collapsed into "missing"; doing so could overwrite user-owned instruction
    files. Callers that want a non-throwing view should use
    ``_rule_file_state`` and skip unsafe targets explicitly.
    """
    try:
        return _read_text_no_follow(path)
    except FileNotFoundError:
        return None


def _rule_file_state(path: Path) -> dict[str, Any]:
    """Return a non-throwing state for project rule/skill files."""
    try:
        st = os.lstat(path)
    except FileNotFoundError:
        return {"status": "missing", "text": None, "reason": None}
    except OSError as exc:
        return {"status": "unsafe", "text": None, "reason": f"could not inspect rule file: {exc.__class__.__name__}"}
    if stat.S_ISLNK(st.st_mode):
        return {"status": "unsafe", "text": None, "reason": f"refused to read symlinked rule file: {path.name}"}
    if stat.S_ISDIR(st.st_mode):
        return {"status": "directory", "text": None, "reason": f"refused to replace directory rule target: {path.name}"}
    try:
        text = _read_text_no_follow(path)
    except OSError as exc:
        return {
            "status": "unsafe",
            "text": None,
            "reason": f"could not read rule file without following symlinks: {exc.__class__.__name__}",
        }
    return {"status": "file", "text": text, "reason": None}


def repo_rule_block_present(path: Path) -> bool:
    """True when the advisory ContextGuard block already exists in the rule file."""
    state = _rule_file_state(path)
    return state["status"] == "file" and ADAPTER_RULE_BLOCK_BEGIN in str(state.get("text") or "")


def write_repo_rule_init(path: Path) -> dict[str, Any]:
    """Idempotently append the advisory ContextGuard block to a repo rule file.

    Returns a status dict: ``applied`` (block written), ``exists`` (already
    present), or ``skipped`` (refused, e.g. symlinked target) with a reason.
    """
    state = _rule_file_state(path)
    if state["status"] not in {"missing", "file"}:
        return {"status": "skipped", "reason": state.get("reason") or f"refused unsafe rule target: {path.name}"}
    existing = state.get("text")
    if existing is not None and ADAPTER_RULE_BLOCK_BEGIN in existing:
        return {"status": "exists"}
    block = render_repo_rule_block()
    if existing:
        new_text = existing.rstrip("\n") + "\n\n" + block + "\n"
        mode = existing_mode_or_default(path, 0o644)
    else:
        new_text = block + "\n"
        mode = 0o644
    try:
        atomic_write(path, new_text, mode, dir_mode=0o755)
    except OSError as exc:
        return {"status": "skipped", "reason": f"could not write repo rule file {path.name}: {exc.__class__.__name__}"}
    return {"status": "applied"}


def codex_skill_status(path: Path) -> str:
    state = _rule_file_state(path)
    if state["status"] == "missing":
        return "missing"
    if state["status"] != "file":
        return "unsafe"
    text = str(state.get("text") or "")
    if text == render_codex_skill():
        return "exists"
    if CODEX_SKILL_MARKER_BEGIN in text and CODEX_SKILL_MARKER_END in text:
        return "update-needed"
    return "foreign"


def write_codex_project_skill(path: Path) -> dict[str, Any]:
    """Idempotently create/update the project-local Codex ContextGuard skill."""
    state = _rule_file_state(path)
    if state["status"] not in {"missing", "file"}:
        return {"status": "skipped", "reason": state.get("reason") or f"refused unsafe skill target: {path.name}"}
    status = codex_skill_status(path)
    if status == "exists":
        return {"status": "exists"}
    if status == "foreign":
        return {
            "status": "skipped",
            "reason": f"refused to overwrite non-ContextGuard Codex skill file: {path}",
        }
    try:
        atomic_write(path, render_codex_skill(), 0o644, dir_mode=0o755)
    except OSError as exc:
        return {"status": "skipped", "reason": f"could not write Codex skill file {path}: {exc.__class__.__name__}"}
    return {"status": "updated" if status == "update-needed" else "applied"}


def adapter_rule_path(root: Path, adapter: AgentAdapter) -> Path | None:
    """Resolve a repo-rule adapter's write target.

    Most adapters have a stable file target. Cline is deliberately flexible:
    existing projects commonly use `.clinerules` as a file, while some may use a
    directory-style rules surface. Pick a file when `.clinerules` is absent or a
    file; use a nested advisory file only when `.clinerules` already exists as a
    real directory. This avoids crashing or replacing a user-owned file-form rule.
    """
    if adapter.rule_file is None:
        return None
    if adapter.key == "cline":
        base = root / ".clinerules"
        if base.exists() and base.is_dir() and not base.is_symlink():
            return base / "contextguard.md"
        return base
    return root / adapter.rule_file


def build_adapter_plan(
    root: Path,
    targets: list[AgentAdapter],
    *,
    scope: str,
    claude_actions: list[str],
    claude_changed: bool,
    claude_applied: bool,
    with_init: bool,
    with_skill: bool,
    applied: bool,
) -> list[dict[str, Any]]:
    """Render a per-adapter plan, performing safe repo-rule writes when applied.

    Only repo-rule adapters write, and only when both ``with_init`` and ``applied``
    are set. Native-plugin entries mirror the Claude settings result; native-skill
    and report-only entries are advisory and never write.
    """
    detected = set(detect_agents(root))
    plan: list[dict[str, Any]] = []
    for adapter in targets:
        entry: dict[str, Any] = {
            "key": adapter.key,
            "display_name": adapter.display_name,
            "capability": adapter.capability,
            "scope": scope,
            "detected": adapter.key in detected,
            "summary": adapter.summary,
            "writable": False,
            "status": "report-only",
            "planned_actions": [],
            "applied_actions": [],
            "unsupported_reason": None,
        }
        if scope == "user" and adapter.key != "claude":
            entry["status"] = "unsupported"
            entry["writable"] = False
            entry["unsupported_reason"] = (
                f"user-scope activation for {adapter.display_name} is not implemented/verified yet; "
                "use --scope project or run the helper commands manually."
            )
            entry["planned_actions"] = [entry["unsupported_reason"]]
            plan.append(entry)
            continue
        if adapter.capability == CapabilityClass.NATIVE_PLUGIN:
            entry["writable"] = True
            if adapter.settings_rel:
                entry["settings_path"] = str(root / adapter.settings_rel)
            entry["planned_actions"] = list(claude_actions)
            if claude_applied and claude_changed:
                entry["status"] = "applied"
            elif claude_changed:
                entry["status"] = "planned"
            else:
                entry["status"] = "unchanged"
        elif adapter.capability == CapabilityClass.REPO_RULE:
            entry["writable"] = True
            rule_path = adapter_rule_path(root, adapter)
            entry["rule_file"] = str(rule_path.relative_to(root)) if rule_path else adapter.rule_file
            if rule_path is not None and repo_rule_block_present(rule_path):
                entry["status"] = "exists"
                entry["planned_actions"] = [f"advisory ContextGuard rules already present in {entry['rule_file']}"]
            elif not with_init:
                entry["status"] = "planned"
                entry["planned_actions"] = [f"run with --with-init to add advisory ContextGuard rules to {entry['rule_file']}"]
            elif not applied:
                entry["status"] = "planned"
                entry["planned_actions"] = [f"would add advisory ContextGuard rules to {entry['rule_file']}"]
            elif rule_path is not None:
                result = write_repo_rule_init(rule_path)
                entry["status"] = result["status"]
                if result["status"] == "applied":
                    entry["applied_actions"] = [f"wrote advisory ContextGuard rules to {entry['rule_file']}"]
                    entry["planned_actions"] = list(entry["applied_actions"])
                elif result["status"] == "exists":
                    entry["planned_actions"] = [f"advisory ContextGuard rules already present in {entry['rule_file']}"]
                else:
                    entry["planned_actions"] = [result.get("reason", "skipped")]
            if adapter.key == "codex" and adapter.project_skill_rel:
                skill_path = root / adapter.project_skill_rel
                entry["project_skill_file"] = adapter.project_skill_rel
                skill_state = codex_skill_status(skill_path)
                entry["project_skill_status"] = skill_state
                if skill_state == "exists":
                    entry["planned_actions"].append(
                        f"project Codex skill already present in {adapter.project_skill_rel}"
                    )
                elif skill_state == "unsafe":
                    entry["planned_actions"].append(
                        f"refused unsafe project Codex skill target at {adapter.project_skill_rel}"
                    )
                elif not with_skill:
                    entry["planned_actions"].append(
                        f"run with --with-skill to generate project Codex skill at {adapter.project_skill_rel}"
                    )
                elif not applied:
                    entry["planned_actions"].append(
                        f"would generate project Codex skill at {adapter.project_skill_rel}"
                    )
                else:
                    skill_result = write_codex_project_skill(skill_path)
                    entry["project_skill_status"] = skill_result["status"]
                    if skill_result["status"] in {"applied", "updated"}:
                        action = f"wrote project Codex skill to {adapter.project_skill_rel}"
                        entry["applied_actions"].append(action)
                        entry["planned_actions"].append(action)
                        if entry["status"] in {"planned", "exists", "unchanged"}:
                            entry["status"] = "applied"
                    elif skill_result["status"] == "exists":
                        entry["planned_actions"].append(
                            f"project Codex skill already present in {adapter.project_skill_rel}"
                        )
                    else:
                        entry["planned_actions"].append(skill_result.get("reason", "skipped"))
        elif adapter.capability == CapabilityClass.NATIVE_SKILL:
            entry["planned_actions"] = [adapter.summary]
        else:  # REPORT_ONLY
            entry["planned_actions"] = [adapter.summary]
        plan.append(entry)
    return plan


class AtomicWriteDurabilityError(OSError):
    """Raised after rename when the new file exists but directory durability is uncertain."""


def find_project_root(start: Path | None = None) -> Path:
    current = (start or Path.cwd()).expanduser().resolve()
    if current.is_file():
        current = current.parent
    for candidate in [current, *current.parents]:
        if (candidate / ".git").exists():
            return candidate
    return current


def resolve_setup_root(raw_root: str | None) -> Path:
    if raw_root is None:
        return find_project_root()
    root = Path(raw_root).expanduser().resolve()
    if not root.exists():
        raise SystemExit(f"Project root does not exist: {root}")
    return root.parent if root.is_file() else root


def normalize_scope(raw_scope: str | None) -> str:
    scope = str(raw_scope or "project").strip().lower()
    if scope == "global":
        return "user"
    if scope not in {"project", "user"}:
        raise SystemExit("Unknown setup scope: {!r}. Known scopes: project, user.".format(raw_scope))
    return scope


def resolve_scope_root(raw_root: str | None, scope: str) -> Path:
    if scope == "project":
        return resolve_setup_root(raw_root)
    home = Path.home().expanduser().resolve()
    if home == Path(home.anchor or "/"):
        raise SystemExit("Refusing user-scope setup because HOME resolves to a filesystem root.")
    if not home.exists() or not home.is_dir():
        raise SystemExit(f"Refusing user-scope setup because HOME is not a directory: {home}")
    return home


def explicit_agent_selection(args: argparse.Namespace) -> list[str] | None:
    values: list[str] = []
    for attr in ("agent", "only"):
        raw_values = getattr(args, attr, None)
        if not raw_values:
            continue
        for raw in raw_values:
            for part in str(raw).split(","):
                key = part.strip()
                if key:
                    values.append(key)
    return values or None


def validate_settings_target(root: Path, settings_path: Path, *, allow_home_settings: bool) -> None:
    root = root.resolve()
    home_settings = Path.home().expanduser().resolve() / SETTINGS_REL
    if settings_path.expanduser().resolve() == home_settings and not allow_home_settings:
        raise SystemExit(
            "Refusing to modify global ~/.claude/settings.json. Run from a project directory, "
            "pass --root <project>, or use --allow-home-settings if you intentionally want this."
        )
    claude_dir = root / ".claude"
    if claude_dir.exists() and claude_dir.is_symlink():
        raise SystemExit(f"Refusing to use symlinked Claude settings directory: {claude_dir}")
    if settings_path.exists() and settings_path.is_symlink():
        raise SystemExit(f"Refusing to write through symlinked settings file: {settings_path}")
    if claude_dir.exists():
        try:
            claude_dir.resolve().relative_to(root)
        except ValueError as exc:
            raise SystemExit(f"Claude settings directory resolves outside project root: {claude_dir}") from exc


def _base_open_flags() -> int:
    flags = os.O_RDONLY
    if hasattr(os, "O_CLOEXEC"):
        flags |= os.O_CLOEXEC
    return flags


def _no_follow_flag() -> int:
    if hasattr(os, "O_NOFOLLOW"):
        return os.O_NOFOLLOW
    raise OSError("platform does not support no-follow file opens")


def no_follow_file_ops_supported() -> bool:
    return (
        hasattr(os, "O_NOFOLLOW")
        and os.open in os.supports_dir_fd
        and os.mkdir in os.supports_dir_fd
        and os.rename in os.supports_dir_fd
        and os.unlink in os.supports_dir_fd
    )


def require_no_follow_file_ops_supported() -> None:
    if not no_follow_file_ops_supported() or fcntl is None:
        raise SystemExit(
            "Setup requires POSIX no-follow file operations for safe project-local settings writes; "
            "this platform is not supported yet."
        )


def _directory_flag() -> int:
    return getattr(os, "O_DIRECTORY", 0)


def _normalized_link_target(parent: Path, raw_target: str) -> Path:
    target = Path(raw_target)
    if not target.is_absolute():
        target = parent / target
    return Path(os.path.normpath(str(target)))


def _normalize_allowed_first_absolute_symlink(path: Path) -> Path:
    """Rewrite narrow platform-owned absolute aliases before no-follow traversal."""
    if not path.is_absolute() or len(path.parts) < 2:
        return path
    first = path.parts[1]
    expected = ALLOWED_FIRST_ABSOLUTE_SYMLINKS.get(first)
    if expected is None:
        return path
    link = Path(path.anchor) / first
    try:
        if not stat.S_ISLNK(os.lstat(link).st_mode):
            return path
        if _normalized_link_target(Path(path.anchor), os.readlink(link)) != expected:
            return path
    except OSError:
        return path
    return expected.joinpath(*path.parts[2:])


def _open_directory_at(dir_fd: int, component: str, path: Path) -> int:
    flags = _base_open_flags() | _directory_flag() | _no_follow_flag()
    fd = os.open(component, flags, dir_fd=dir_fd)
    try:
        if not stat.S_ISDIR(os.fstat(fd).st_mode):
            raise OSError(f"not a directory: {path}")
        return fd
    except Exception:
        os.close(fd)
        raise


def _mkdir_directory_entry_at(dir_fd: int, component: str, mode: int) -> None:
    # mkdir modes are still filtered through umask.  Run only the mkdir in an
    # isolated child process with umask 0 so the parent process umask never
    # changes, then the parent immediately reopens with O_NOFOLLOW.
    helper = (
        "import os, sys\n"
        "dir_fd = int(sys.argv[1])\n"
        "component = sys.argv[2]\n"
        "mode = int(sys.argv[3], 8)\n"
        "os.umask(0)\n"
        "os.mkdir(component, mode, dir_fd=dir_fd)\n"
    )
    proc = subprocess.run(
        [sys.executable, "-I", "-c", helper, str(dir_fd), component, oct(mode)],
        text=True,
        capture_output=True,
        pass_fds=(dir_fd,),
    )
    if proc.returncode != 0:
        detail = (proc.stderr or proc.stdout).strip().splitlines()[-1:] or [f"exit {proc.returncode}"]
        raise OSError(f"could not create directory component safely: {component}: {detail[0]}")


def _open_regular_no_symlink(path: Path) -> int:
    if os.open not in os.supports_dir_fd:
        raise OSError("platform does not support directory-relative no-follow opens")
    path = _normalize_allowed_first_absolute_symlink(path)
    components = list(path.parts)
    if path.is_absolute() and components:
        components = components[1:]
    if not components:
        raise OSError(f"not a regular file: {path}")

    root = path.anchor if path.is_absolute() else "."
    dir_fd = os.open(root or ".", _base_open_flags() | _directory_flag())
    try:
        for component in components[:-1]:
            next_fd = _open_directory_at(dir_fd, component, path)
            os.close(dir_fd)
            dir_fd = next_fd

        fd = os.open(components[-1], _base_open_flags() | _no_follow_flag(), dir_fd=dir_fd)
        try:
            if not stat.S_ISREG(os.fstat(fd).st_mode):
                raise OSError(f"not a regular file: {path}")
            return fd
        except Exception:
            os.close(fd)
            raise
    finally:
        os.close(dir_fd)


def _ensure_directory_no_symlink(path: Path, mode: int | None = None, *, parents_mode: int | None = None) -> int:
    if os.mkdir not in os.supports_dir_fd:
        raise OSError("platform does not support directory-relative directory creation")
    path = _normalize_allowed_first_absolute_symlink(path)
    components = list(path.parts)
    if path.is_absolute() and components:
        components = components[1:]
    root = path.anchor if path.is_absolute() else "."
    dir_fd = os.open(root or ".", _base_open_flags() | _directory_flag())
    try:
        for index, component in enumerate(components):
            created = False
            mkdir_mode = (
                mode
                if mode is not None and index == len(components) - 1
                else (parents_mode if parents_mode is not None else PRIVATE_DIR_MODE)
            )
            try:
                next_fd = _open_directory_at(dir_fd, component, path)
            except FileNotFoundError:
                _mkdir_directory_entry_at(dir_fd, component, mkdir_mode)
                next_fd = _open_directory_at(dir_fd, component, path)
                created = True
            if created and hasattr(os, "fchmod"):
                os.fchmod(next_fd, mkdir_mode)
            os.close(dir_fd)
            dir_fd = next_fd
        return dir_fd
    except Exception:
        os.close(dir_fd)
        raise


def _read_text_no_follow(path: Path) -> str:
    fd = _open_regular_no_symlink(path)
    try:
        with os.fdopen(fd, "r", encoding="utf-8") as handle:
            fd = -1
            return handle.read()
    finally:
        if fd != -1:
            os.close(fd)


def _read_optional_text_no_follow(path: Path) -> str | None:
    try:
        return _read_text_no_follow(path)
    except FileNotFoundError:
        return None
    except OSError as exc:
        raise SystemExit(f"Could not read {path} without following symlinks: {exc}") from exc


def _parse_json_object_text(text: str | None, path: Path) -> dict[str, Any]:
    if text is None:
        return {}
    try:
        data = json.loads(text)
    except json.JSONDecodeError as exc:
        raise SystemExit(f"Invalid JSON in {path}: line {exc.lineno}: {exc.msg}") from exc
    if not isinstance(data, dict):
        raise SystemExit(f"Settings file must contain a JSON object: {path}")
    return data


def load_json_object(path: Path) -> dict[str, Any]:
    return _parse_json_object_text(_read_optional_text_no_follow(path), path)


def ensure_permissions(settings: dict[str, Any], actions: list[str]) -> None:
    permissions = settings.get("permissions")
    if permissions is None:
        permissions = {}
        settings["permissions"] = permissions
    if not isinstance(permissions, dict):
        raise SystemExit("Refusing to replace non-object settings.permissions; repair it manually first.")
    deny = permissions.get("deny")
    if deny is None:
        deny = []
        permissions["deny"] = deny
    if not isinstance(deny, list):
        raise SystemExit("Refusing to replace non-list settings.permissions.deny; repair it manually first.")
    added = 0
    for rule in RECOMMENDED_DENIES:
        if rule not in deny:
            deny.append(rule)
            added += 1
    if added:
        actions.append(f"added {added} permissions.deny rules for bulky/sensitive paths")


def command_values(value: Any) -> list[str]:
    found: list[str] = []
    if isinstance(value, dict):
        for key, item in value.items():
            if key == "command" and isinstance(item, str):
                found.append(item)
            found.extend(command_values(item))
    elif isinstance(value, list):
        for item in value:
            found.extend(command_values(item))
    return found


def matcher_covers(existing: Any, desired: str) -> bool:
    if not isinstance(existing, str):
        return False
    parts = {part.strip().lower() for part in existing.split("|") if part.strip()}
    return not parts or "*" in parts or desired.lower() in parts


def helper_argv(helper_name: str, kit_script: str, *, shell: str | None = None) -> list[str]:
    """Return argv for a bundled helper without invoking a shell."""
    script_dir = Path(__file__).resolve().parent
    colocated = script_dir / helper_name
    if colocated.exists() and os.access(colocated, os.X_OK):
        return [str(colocated)]
    repo_plugin = script_dir.parent / "plugins" / "context-guard" / "bin" / helper_name
    if repo_plugin.exists() and os.access(repo_plugin, os.X_OK):
        return [str(repo_plugin)]
    kit_path = script_dir / kit_script
    if kit_path.exists():
        prefix = [shell] if shell else [sys.executable]
        return [*prefix, str(kit_path)]
    found = shutil.which(helper_name)
    if found:
        return [str(Path(found).resolve())]
    raise SystemExit(
        f"Could not resolve required helper {helper_name!r}; install the plugin or run from a checked-out repository."
    )


def helper_command(helper_name: str, kit_script: str, *, shell: str | None = None) -> str:
    """hook 에 기록할 단일 셸 명령 문자열을 반환한다.

    경로에 공백이나 셸 메타문자가 들어와도 안전하도록 모든 분기에서 `shlex.join` 으로
    quote 한다. PATH 에서 찾은 helper 도 절대 경로로 고정해 hook hijacking 을 막는다.
    """
    argv = helper_argv(helper_name, kit_script, shell=shell)
    return shlex.join(argv)


def statusline_setting() -> dict[str, str]:
    return {"type": "command", "command": helper_command(HELPER_STATUSLINE, "statusline_merged.sh", shell="bash")}


def bash_hook_setting() -> dict[str, Any]:
    return {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": helper_command(HELPER_REWRITE_BASH, "rewrite_bash_for_token_budget.py")}],
    }


def read_hook_setting() -> dict[str, Any]:
    return {
        "matcher": "Read",
        "hooks": [{"type": "command", "command": helper_command(HELPER_GUARD_READ, "guard_large_read.py")}],
    }


def failed_nudge_setting() -> dict[str, Any]:
    return {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": helper_command(HELPER_FAILED_NUDGE, "failed_attempt_nudge.py")}],
    }


def command_matches(existing: str, desired: str) -> bool:
    if existing == desired:
        return True
    try:
        existing_parts = shlex.split(existing) if existing else []
        desired_parts = shlex.split(desired) if desired else []
    except ValueError:
        return False
    return bool(existing_parts and desired_parts and existing_parts == desired_parts)


def command_helper_basenames(command: str) -> set[str]:
    try:
        parts = shlex.split(command) if command else []
    except ValueError:
        return set()
    if not parts:
        return set()
    index = 0
    if os.path.basename(parts[index]) == "env":
        index += 1
        while index < len(parts) and "=" in parts[index] and not parts[index].startswith("-"):
            index += 1
    if index >= len(parts):
        return set()
    head = os.path.basename(parts[index])
    interpreter_heads = {"bash", "sh"}
    if re.fullmatch(r"python(?:\d+(?:\.\d+)?)?", head):
        interpreter_heads.add(head)
    if head in interpreter_heads:
        for token_index in range(index + 1, len(parts)):
            token = parts[token_index]
            if token == "-c":
                if token_index + 1 < len(parts):
                    return command_helper_basenames(parts[token_index + 1])
                return set()
            if token.startswith("-"):
                continue
            return {os.path.basename(token)}
        return set()
    return {head}


def equivalent_helper_basenames(command: str) -> set[str]:
    bases = command_helper_basenames(command)
    equivalents = set(bases)
    for base in bases:
        equivalents.update(HELPER_EQUIVALENT_BASENAMES.get(base, ()))
    return equivalents


def command_matches_existing_or_equivalent(existing: str, desired: str) -> bool:
    if command_matches(existing, desired):
        return True
    desired_helpers = equivalent_helper_basenames(desired)
    if not desired_helpers:
        return False
    return bool(command_helper_basenames(existing) & desired_helpers)


def canonicalize_equivalent_command(value: Any, desired: str) -> tuple[bool, bool]:
    """Return (found_equivalent, changed), rewriting legacy/bare helpers to desired.

    Older project settings may contain bare `claude-token-*` hook commands from
    the pre-ContextGuard plugin. Treating those as equivalent for deduplication
    is useful, but preserving them can leave Claude Code hooks pointing at a
    command that no longer exists on PATH. When a matching command field is
    found, pin it to the current canonical helper command instead.
    """
    found = False
    changed = False
    if isinstance(value, dict):
        for key, item in value.items():
            if key == "command" and isinstance(item, str) and command_matches_existing_or_equivalent(item, desired):
                found = True
                if not command_matches(item, desired):
                    value[key] = desired
                    changed = True
                continue
            child_found, child_changed = canonicalize_equivalent_command(item, desired)
            found = found or child_found
            changed = changed or child_changed
    elif isinstance(value, list):
        for item in value:
            child_found, child_changed = canonicalize_equivalent_command(item, desired)
            found = found or child_found
            changed = changed or child_changed
    return found, changed


def has_hook_command(pre_tool_use: list[Any], matcher: str, command: str) -> bool:
    for entry in pre_tool_use:
        if not isinstance(entry, dict) or not matcher_covers(entry.get("matcher"), matcher):
            continue
        if any(command_matches_existing_or_equivalent(value, command) for value in command_values(entry)):
            return True
    return False


def ensure_pre_tool_hook(settings: dict[str, Any], hook: dict[str, Any], command: str, label: str, actions: list[str]) -> None:
    _ensure_tool_hook(settings, hook, command, label, actions, event="PreToolUse")


def ensure_post_tool_hook(settings: dict[str, Any], hook: dict[str, Any], command: str, label: str, actions: list[str]) -> None:
    _ensure_tool_hook(settings, hook, command, label, actions, event="PostToolUse")


def _ensure_tool_hook(
    settings: dict[str, Any],
    hook: dict[str, Any],
    command: str,
    label: str,
    actions: list[str],
    *,
    event: str,
) -> None:
    hooks = settings.get("hooks")
    if hooks is None:
        hooks = {}
        settings["hooks"] = hooks
    if not isinstance(hooks, dict):
        raise SystemExit("Refusing to replace non-object settings.hooks; repair it manually first.")
    bucket = hooks.get(event)
    if bucket is None:
        bucket = []
        hooks[event] = bucket
    if not isinstance(bucket, list):
        raise SystemExit(f"Refusing to replace non-list settings.hooks.{event}; repair it manually first.")
    matcher = str(hook.get("matcher") or "")
    found_any = False
    changed_any = False
    for entry in bucket:
        if not isinstance(entry, dict) or not matcher_covers(entry.get("matcher"), matcher):
            continue
        found, changed = canonicalize_equivalent_command(entry, command)
        found_any = found_any or found
        changed_any = changed_any or changed
    if found_any:
        if changed_any:
            actions.append(f"migrated {label} hook to {command}")
        return
    bucket.append(copy.deepcopy(hook))
    actions.append(f"enabled {label} hook via {command}")


def summarize_diet_report(report: dict[str, Any]) -> dict[str, Any]:
    if not isinstance(report, dict):
        raise ValueError("report must be an object")
    raw_findings = report.get("findings", [])
    if not isinstance(raw_findings, list):
        raise ValueError("findings must be a list")
    findings: list[dict[str, Any]] = []
    for finding in raw_findings:
        if not isinstance(finding, dict):
            raise ValueError("findings must contain objects")
        findings.append(finding)

    counts = {"high": 0, "medium": 0, "low": 0}
    for finding in findings:
        severity = str(finding.get("severity", "")).lower()
        if severity in counts:
            counts[severity] += 1
    top_findings = []
    for finding in findings[:DEFAULT_POST_SETUP_SCAN_TOP]:
        top_findings.append({
            "severity": finding.get("severity"),
            "id": finding.get("id"),
            "path": finding.get("path"),
            "message": finding.get("message"),
            "action": finding.get("action"),
        })
    raw_finding_count = report.get("finding_count", len(findings))
    try:
        finding_count = int(raw_finding_count)
    except (TypeError, ValueError) as exc:
        raise ValueError("finding_count must be an integer") from exc
    return {
        "status": "completed",
        "finding_count": finding_count,
        "severity_counts": counts,
        "top_findings": top_findings,
    }


def run_post_setup_diet_scan(root: Path) -> dict[str, Any]:
    argv = [
        *helper_argv(HELPER_DIET, "context_guard_diet.py"),
        "scan",
        str(root),
        "--json",
        "--top",
        str(DEFAULT_POST_SETUP_SCAN_TOP),
    ]
    try:
        proc = subprocess.run(
            argv,
            text=True,
            capture_output=True,
            check=False,
            timeout=POST_SETUP_SCAN_TIMEOUT_SECONDS,
        )
    except subprocess.TimeoutExpired:
        return {"status": "failed", "reason": "timeout", "timeout_seconds": POST_SETUP_SCAN_TIMEOUT_SECONDS}
    except UnicodeError:
        return {"status": "failed", "reason": "decode-error"}
    except OSError as exc:
        return {"status": "failed", "reason": exc.__class__.__name__}
    if proc.returncode != 0:
        return {"status": "failed", "reason": "nonzero-exit", "returncode": proc.returncode}
    try:
        report = json.loads(proc.stdout)
    except json.JSONDecodeError:
        return {"status": "failed", "reason": "invalid-json"}
    try:
        return summarize_diet_report(report)
    except ValueError:
        return {"status": "failed", "reason": "invalid-report"}


def apply_choices(settings: dict[str, Any], choices: Choices) -> list[str]:
    actions: list[str] = []
    if choices.model_defaults:
        if not settings.get("model"):
            settings["model"] = DEFAULT_MODEL
            actions.append(f"set default model to {DEFAULT_MODEL}")
        if not settings.get("effortLevel"):
            settings["effortLevel"] = DEFAULT_EFFORT
            actions.append(f"set default effortLevel to {DEFAULT_EFFORT}")
    if choices.statusline:
        statusline = statusline_setting()
        if "statusLine" not in settings:
            settings["statusLine"] = statusline
            actions.append("enabled token statusline")
        elif settings.get("statusLine") != statusline:
            actions.append("kept existing statusLine; add context-guard-statusline-merged manually if desired")
    if choices.denies:
        ensure_permissions(settings, actions)
    if choices.bash_hook:
        bash_hook = bash_hook_setting()
        bash_command = bash_hook["hooks"][0]["command"]
        ensure_pre_tool_hook(settings, bash_hook, bash_command, "Bash trim/sanitize", actions)
    if choices.read_guard:
        read_hook = read_hook_setting()
        read_command = read_hook["hooks"][0]["command"]
        ensure_pre_tool_hook(settings, read_hook, read_command, "large Read guard", actions)
    if choices.failed_attempt_nudge:
        nudge_hook = failed_nudge_setting()
        nudge_command = nudge_hook["hooks"][0]["command"]
        ensure_post_tool_hook(settings, nudge_hook, nudge_command, "failed-attempt /clear nudge", actions)
    return actions


def atomic_write(path: Path, text: str, mode: int = 0o600, *, dir_mode: int = PRIVATE_DIR_MODE) -> None:
    if os.rename not in os.supports_dir_fd or os.unlink not in os.supports_dir_fd:
        raise OSError("platform does not support directory-relative atomic writes")
    parent_fd = _ensure_directory_no_symlink(path.parent, dir_mode, parents_mode=dir_mode)
    tmp_name = f".{path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp"
    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | _no_follow_flag()
    fd = os.open(tmp_name, flags, mode, dir_fd=parent_fd)
    try:
        if hasattr(os, "fchmod"):
            os.fchmod(fd, mode)
        with os.fdopen(fd, "w", encoding="utf-8") as f:
            fd = -1
            f.write(text)
            f.flush()
            os.fsync(f.fileno())
        os.fsync(parent_fd)
        os.rename(tmp_name, path.name, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
        try:
            os.fsync(parent_fd)
        except OSError as exc:
            raise AtomicWriteDurabilityError(
                f"write committed but parent directory durability is uncertain: {path}"
            ) from exc
    finally:
        if fd != -1:
            os.close(fd)
        try:
            os.unlink(tmp_name, dir_fd=parent_fd)
        except FileNotFoundError:
            pass
        os.close(parent_fd)


def existing_mode_or_default(path: Path, default: int = 0o600) -> int:
    try:
        fd = _open_regular_no_symlink(path)
    except FileNotFoundError:
        return default
    except OSError:
        return default
    try:
        return os.fstat(fd).st_mode & 0o777
    finally:
        os.close(fd)


def backup_existing(path: Path) -> Path | None:
    try:
        text = _read_text_no_follow(path)
    except FileNotFoundError:
        return None
    mode = existing_mode_or_default(path, 0o600)
    stamp = _dt.datetime.now().strftime("%Y%m%d%H%M%S%f")
    backup = path.with_name(f"{path.name}.bak-{stamp}-{uuid.uuid4().hex[:8]}")
    atomic_write(backup, text, mode)
    return backup


def write_rollback_record(
    *,
    root: Path,
    scope: str,
    settings_path: Path,
    backup_path: Path | None,
    original_existed: bool,
) -> tuple[str | None, Path | None]:
    """Record a minimal rollback handle for user-scope writes.

    Project-scope setup keeps the legacy backup-only behavior. User-scope setup
    can affect many future projects, so every write gets a local rollback record
    under the user's ContextGuard state directory.
    """
    if scope != "user":
        return None, None
    rollback_id = _dt.datetime.now().strftime("%Y%m%d%H%M%S") + "-" + uuid.uuid4().hex[:8]
    rollback_dir = root / ".context-guard" / "rollback"
    rollback_path = rollback_dir / f"{rollback_id}.json"
    record = {
        "schema_version": "contextguard.rollback.v1",
        "rollback_id": rollback_id,
        "created_at": _dt.datetime.now(_dt.UTC).isoformat().replace("+00:00", "Z"),
        "scope": scope,
        "target_path": str(settings_path),
        "backup_path": str(backup_path) if backup_path else None,
        "original_existed": original_existed,
        "restore": (
            f"cp {shlex.quote(str(backup_path))} {shlex.quote(str(settings_path))}"
            if backup_path
            else f"rm -f {shlex.quote(str(settings_path))}"
        ),
    }
    atomic_write(rollback_path, json.dumps(record, indent=2, sort_keys=True) + "\n", 0o600)
    return rollback_id, rollback_path


def acquire_settings_lock(path: Path) -> int:
    """Take an exclusive project-local settings lock without following links."""
    if fcntl is None:
        raise OSError("platform does not support advisory file locks")
    parent_fd = _ensure_directory_no_symlink(path.parent, PRIVATE_DIR_MODE)
    lock_name = f".{path.name}.lock"
    flags = os.O_CREAT | os.O_RDWR | _no_follow_flag()
    if hasattr(os, "O_CLOEXEC"):
        flags |= os.O_CLOEXEC
    try:
        fd = os.open(lock_name, flags, 0o600, dir_fd=parent_fd)
    finally:
        os.close(parent_fd)
    try:
        st = os.fstat(fd)
        if not stat.S_ISREG(st.st_mode):
            raise OSError(f"settings lock is not a regular file: {path.with_name(lock_name)}")
        if hasattr(os, "fchmod"):
            os.fchmod(fd, 0o600)
        fcntl.flock(fd, fcntl.LOCK_EX)
        return fd
    except Exception:
        os.close(fd)
        raise


def release_settings_lock(fd: int) -> None:
    try:
        if fcntl is not None:
            fcntl.flock(fd, fcntl.LOCK_UN)
    finally:
        os.close(fd)


def prompt_bool(question: str, default: bool) -> bool:
    suffix = "Y/n" if default else "y/N"
    while True:
        answer = input(f"{question} [{suffix}] ").strip().lower()
        if not answer:
            return default
        if answer in {"y", "yes"}:
            return True
        if answer in {"n", "no"}:
            return False
        print("Please answer y or n.")


def interactive_choices(defaults: Choices) -> Choices:
    print("ContextGuard setup wizard")
    print("Project-local changes only. Existing settings are merged, not replaced.\n")
    choices = Choices(
        denies=prompt_bool("Add deny rules for bulky/sensitive paths?", defaults.denies),
        statusline=prompt_bool("Enable token/cost statusline?", defaults.statusline),
        bash_hook=prompt_bool("Enable Bash output trim + grep/diff sanitizer hook?", defaults.bash_hook),
        read_guard=prompt_bool("Enable large Read guard?", defaults.read_guard),
        model_defaults=prompt_bool("Set missing defaults to model=sonnet and effortLevel=medium?", defaults.model_defaults),
        failed_attempt_nudge=prompt_bool(
            "Enable failed-attempt /clear nudge? (PostToolUse hook on Bash; recommended default)",
            defaults.failed_attempt_nudge,
        ),
    )
    return choices


def choices_from_args(args: argparse.Namespace) -> Choices:
    return Choices(
        denies=not args.no_denies,
        statusline=not args.no_statusline,
        bash_hook=not args.no_bash_hook,
        read_guard=not args.no_read_guard,
        model_defaults=not args.no_model_defaults,
        failed_attempt_nudge=(
            DEFAULT_FAILED_ATTEMPT_NUDGE
            if args.failed_attempt_nudge is None
            else args.failed_attempt_nudge
        ),
    )


def render_text(result: SetupResult) -> str:
    mode = "applied" if result.applied else ("apply requested; no writes" if result.apply_requested else "plan only")
    lines = [
        f"ContextGuard setup ({mode})",
        f"scope={result.scope}",
        f"root={result.root}",
        f"settings={result.settings_path}",
    ]
    if result.backup_path:
        lines.append(f"backup={result.backup_path}")
    if result.rollback_path:
        lines.append(f"rollback={result.rollback_path}")
    for warning in result.warnings or []:
        lines.append(f"warning={warning}")
    if result.diet_scan:
        scan = result.diet_scan
        lines.append("post-setup diet scan:")
        if scan.get("status") == "completed":
            counts = scan.get("severity_counts", {})
            lines.append(
                "- "
                f"findings={scan.get('finding_count', 0)} "
                f"high={counts.get('high', 0)} medium={counts.get('medium', 0)} low={counts.get('low', 0)}"
            )
            for finding in scan.get("top_findings", []):
                lines.append(f"- [{str(finding.get('severity', '')).upper()}] {finding.get('id')} @ {finding.get('path')}")
        else:
            lines.append(f"- skipped/failed: {scan.get('reason', scan.get('status', 'unknown'))}")
    lines.append("actions:")
    if result.actions:
        lines.extend(f"- {action}" for action in result.actions)
    else:
        lines.append("- no settings changes needed")
    # Only surface the cross-agent section when a non-Claude adapter is engaged,
    # keeping the default Claude-only text output unchanged.
    extra_adapters = [entry for entry in (result.adapter_plan or []) if entry.get("key") != "claude"]
    if extra_adapters:
        lines.append("cross-agent adapters:")
        for entry in result.adapter_plan or []:
            lines.append(f"- {entry['key']} [{entry['capability']}] status={entry['status']}")
            for action in entry.get("planned_actions", []):
                lines.append(f"  - {action}")
    if result.apply_requested and not result.applied:
        lines.append("No supported writes were applied.")
    elif not result.applied:
        lines.append("Run with --yes to apply the selected plan non-interactively.")
    return "\n".join(lines) + "\n"


def run(args: argparse.Namespace) -> SetupResult:
    require_no_follow_file_ops_supported()
    scope = normalize_scope(getattr(args, "scope", "project"))
    root = resolve_scope_root(args.root, scope)
    settings_path = root / SETTINGS_REL
    warnings: list[str] = []
    if scope == "user":
        warnings.append(
            "user-scope setup can affect future projects; writes require --yes and explicit --agent/--only selection"
        )

    # Cross-agent targets. Default keeps Claude compatibility (Claude is always
    # targeted plus any detected agent); --only narrows to an explicit set.
    selected_agents = explicit_agent_selection(args)
    targets = resolve_target_adapters(root, selected_agents)
    claude_targeted = any(adapter.key == "claude" for adapter in targets)

    if claude_targeted:
        validate_settings_target(root, settings_path, allow_home_settings=(args.allow_home_settings or scope == "user"))
        original_text = _read_optional_text_no_follow(settings_path)
        original = _parse_json_object_text(original_text, settings_path)
        settings = json.loads(json.dumps(original))
    else:
        original_text = None
        original = {}
        settings = {}

    choices = choices_from_args(args)
    interactive = (
        sys.stdin.isatty()
        and not args.yes
        and not args.plan
        and not args.dry_run
        and claude_targeted
    )
    if interactive:
        choices = interactive_choices(choices)

    actions = apply_choices(settings, choices) if claude_targeted else []
    changed = (settings != original) if claude_targeted else False

    apply_requested = bool(args.yes and not args.dry_run and not args.plan)
    if scope == "user" and apply_requested and not selected_agents:
        raise SystemExit(
            "Refusing user-scope writes without an explicit agent. "
            "Pass --agent claude (or another specific adapter) with --scope user."
        )
    if interactive and changed:
        preview = SetupResult(
            root=root,
            settings_path=settings_path,
            scope=scope,
            changed=changed,
            applied=False,
            apply_requested=False,
            choices=choices,
            actions=actions,
            warnings=warnings,
        )
        print("\n" + render_text(preview))
        prompt_scope = "user-level" if scope == "user" else "project-local"
        apply_requested = prompt_bool(f"Apply these {prompt_scope} changes now?", True)
        if scope == "user" and apply_requested and not selected_agents:
            raise SystemExit(
                "Refusing user-scope writes without an explicit agent. "
                "Pass --agent claude (or another specific adapter) with --scope user."
            )

    backup_path = None
    rollback_id = None
    rollback_path = None
    claude_settings_written = False
    if claude_targeted and apply_requested and changed:
        if scope == "user" and original_text is not None and args.no_backup:
            raise SystemExit("Refusing --no-backup for user-scope changes to existing Claude settings.")
        lock_fd = acquire_settings_lock(settings_path)
        try:
            current_text = _read_optional_text_no_follow(settings_path)
            if current_text != original_text:
                raise SystemExit(
                    f"Settings changed while setup was preparing changes; re-run setup to merge latest file: {settings_path}"
                )
            if original_text is not None and not args.no_backup and settings != original:
                backup_path = backup_existing(settings_path)
            if settings != original:
                rollback_id, rollback_path = write_rollback_record(
                    root=root,
                    scope=scope,
                    settings_path=settings_path,
                    backup_path=backup_path,
                    original_existed=(original_text is not None),
                )
                atomic_write(
                    settings_path,
                    json.dumps(settings, indent=2, sort_keys=True) + "\n",
                    existing_mode_or_default(settings_path, 0o600),
                )
                claude_settings_written = True
        finally:
            release_settings_lock(lock_fd)

    # Build the per-adapter plan; repo-rule writes happen here only when both
    # --with-init and an applying run (--yes) are in effect.
    adapter_plan = build_adapter_plan(
        root,
        targets,
        scope=scope,
        claude_actions=actions,
        claude_changed=changed,
        claude_applied=(claude_targeted and apply_requested),
        with_init=bool(getattr(args, "with_init", False)),
        with_skill=bool(getattr(args, "with_skill", False)),
        applied=apply_requested,
    )
    # Surface any repo-rule writes in the top-level actions for visibility. Claude
    # actions are already in ``actions``; only adapter-side writes are appended.
    for entry in adapter_plan:
        actions.extend(entry.get("applied_actions", []))
    adapter_writes = any(entry.get("applied_actions") for entry in adapter_plan)
    applied = bool(claude_settings_written or adapter_writes)

    diet_scan = None
    if (applied or (apply_requested and claude_targeted)) and not getattr(args, "no_diet_scan", False):
        diet_scan = run_post_setup_diet_scan(root)

    return SetupResult(
        root=root,
        settings_path=settings_path,
        scope=scope,
        changed=changed,
        applied=applied,
        apply_requested=apply_requested,
        choices=choices,
        actions=actions,
        backup_path=backup_path,
        rollback_id=rollback_id,
        rollback_path=rollback_path,
        warnings=warnings,
        diet_scan=diet_scan,
        adapter_plan=adapter_plan,
    )


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Interactively configure ContextGuard project settings.")
    parser.add_argument("--root", default=None, help="project root to configure (default: nearest git root, else current directory)")
    parser.add_argument(
        "--scope",
        choices=("project", "user", "global"),
        default="project",
        help="setup scope: project-local by default; user/global targets only known user-level paths and requires explicit --agent for writes",
    )
    parser.add_argument(
        "--allow-home-settings",
        action="store_true",
        help="deprecated compatibility alias for user-level Claude settings; prefer --scope user --agent claude",
    )
    parser.add_argument("--yes", action="store_true", help="apply the recommended/selected setup without prompts")
    parser.add_argument("--plan", action="store_true", help="show the setup plan without writing files")
    parser.add_argument("--dry-run", action="store_true", help="alias for --plan")
    parser.add_argument("--json", action="store_true", help="print machine-readable result")
    parser.add_argument("--no-backup", action="store_true", help="do not create .bak-* before modifying existing settings")
    parser.add_argument("--no-denies", action="store_true", help="skip recommended permissions.deny rules")
    parser.add_argument("--no-statusline", action="store_true", help="skip token statusline")
    parser.add_argument("--no-bash-hook", action="store_true", help="skip Bash trim/sanitize hook")
    parser.add_argument("--no-read-guard", action="store_true", help="skip large Read guard hook")
    parser.add_argument("--no-model-defaults", action="store_true", help="skip model/effort defaults")
    parser.add_argument("--no-diet-scan", action="store_true", help="skip the read-only diet scan summary after applying setup")
    parser.add_argument(
        "--agent",
        action="append",
        default=None,
        metavar="ADAPTER",
        help="adapter key(s) to configure; comma-separated or repeatable. Alias for --only.",
    )
    parser.add_argument(
        "--only",
        action="append",
        default=None,
        metavar="ADAPTER",
        help="restrict cross-agent setup/plan to adapter key(s); comma-separated or repeatable "
        "(e.g. --only codex,gemini). Default: claude plus any detected agents.",
    )
    parser.add_argument(
        "--with-init",
        dest="with_init",
        action="store_true",
        help="also write advisory ContextGuard rule files for repo-rule agents (AGENTS.md, GEMINI.md, .cursorrules, etc.) "
        "when applying; safe and idempotent.",
    )
    parser.add_argument(
        "--with-skill",
        dest="with_skill",
        action="store_true",
        help="also generate optional project-local skill files where supported, currently Codex .agents/skills/context-guard/SKILL.md.",
    )
    parser.add_argument(
        "--list-adapters",
        dest="list_adapters",
        action="store_true",
        help="print the cross-agent adapter registry and exit",
    )
    nudge_group = parser.add_mutually_exclusive_group()
    nudge_group.add_argument(
        "--failed-attempt-nudge",
        dest="failed_attempt_nudge",
        action="store_true",
        default=None,
        help="enable PostToolUse Bash hook that suggests /clear when the same command fails twice in a row (recommended default)",
    )
    nudge_group.add_argument(
        "--no-failed-attempt-nudge",
        dest="failed_attempt_nudge",
        action="store_false",
        default=None,
        help="skip the failed-attempt /clear nudge hook",
    )
    return parser


def main() -> int:
    parser = build_parser()
    args = parser.parse_args()
    if args.dry_run:
        args.plan = True
    if getattr(args, "list_adapters", False):
        payload = adapter_registry_payload()
        if args.json:
            print(json.dumps({"adapters": payload}, indent=2, sort_keys=True))
        else:
            print("ContextGuard cross-agent adapters:")
            for item in payload:
                print(f"- {item['key']} [{item['capability']}] {item['display_name']}: {item['summary']}")
        return 0
    # Safety default for non-interactive Claude Code Bash calls: do not write
    # unless --yes is explicit.
    if not sys.stdin.isatty() and not args.yes:
        args.plan = True
    result = run(args)
    if args.json:
        print(json.dumps(result.as_dict(), indent=2, sort_keys=True))
    else:
        print(render_text(result))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
