#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "typer>=0.12,<1",
#   "questionary>=2.0,<3",
#   "rich>=13,<15",
# ]
# ///
#
# agent-container — interactive wizard + CLI for agent-container containers.
#
# ============================================================================
# This script is the SINGLE SOURCE OF TRUTH for the agent-container on-disk contract.
# Everything below — container naming (agent-container-<name>), the port hash
# (2200 + sum-of-char-codes mod 100), the per-name state files
# ($XDG_STATE_HOME/agent-container/<name>.port), the env-file resolution order
# (./.env -> ~/.config/agent-container/<name>.env -> ~/.config/agent-container/.env), and
# the hosts.conf KEY=VALUE format (FOO_HOST / FOO_PORT) — is defined here and
# only here. The shell completions read the same state files directly; keep
# them in step with the constants in this file.
# ============================================================================
#
# hosts.conf handling: this tool parses hosts.conf line-by-line and NEVER
# executes/sources it. Quoting and unquoted trailing `# comment`s are handled
# like bash `source`, but values containing `$` or backticks are taken
# literally (no expansion), with a one-time warning.

from __future__ import annotations

import json
import os
import re
import shutil
import signal
import socket
import subprocess
import sys
import termios
from pathlib import Path
from typing import List

import questionary
import typer
from rich.console import Console
from rich.table import Table

# --- constants ---------------------------------------------------------------

IMAGE_NAME = "localhost/agent-container:latest"
CONTAINER_PREFIX = "agent-container-"
PORT_BASE = 2200
PORT_RANGE = 100  # 2200..2299

STATE_DIR = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local/state") / "agent-container"
CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "agent-container"
HOSTS_CONF = CONFIG_DIR / "hosts.conf"

def _is_repo_checkout(base: "Path") -> bool:
    """Best-effort test that `base` is an agent-container checkout.

    Keyed on `completions/agent-container.bash` (plus a Dockerfile for the build
    context): a repo-specific sentinel rather than the generic `Dockerfile` +
    `completions/` dir pair, which is common to unrelated trees. Requiring the
    exact file _completion_script reads (bin/agent-container: REPO_ROOT/completions/
    agent-container.<shell>) also makes the marker and that consumed path the same
    invariant — a recognized checkout can never then serve stale package data.
    This is a heuristic, not a guaranteed false-positive-free identifier.
    """
    return (base / "Dockerfile").is_file() and (base / "completions" / "agent-container.bash").is_file()


def _find_repo_root() -> "Path | None":
    """Locate the repo checkout in a way that survives a non-editable install.

    A wheel copies this module into site-packages, so Path(__file__) no longer
    points inside the repo. Resolution order:
      1. AGENT_CONTAINER_REPO (explicit operator override): trusted only when it
         satisfies the checkout marker (see _is_repo_checkout); a wrong/typo'd
         path yields None rather than a bogus root (build then dies actionably).
      2. Walk up from this file, then from cwd, looking for a dir that matches
         the marker.
    Returns None when no checkout is reachable — client subcommands still work
    (completions falls back to bundled package data; build fails actionably).
    Note: this cannot die here — it runs at import, before Fatal/die exist.
    """
    env = os.environ.get("AGENT_CONTAINER_REPO")
    if env:
        base = Path(env).expanduser().resolve()
        return base if _is_repo_checkout(base) else None
    here = Path(__file__).resolve()
    for base in here.parents:
        if _is_repo_checkout(base):
            return base
    for base in (Path.cwd(), *Path.cwd().parents):
        if _is_repo_checkout(base):
            return base
    return None


REPO_ROOT = _find_repo_root()

NAME_RE = re.compile(r"[a-z0-9][a-z0-9_-]*")
# ssh argv injection guard: a user/host that begins with '-' would be parsed
# by ssh as an option (e.g. -oProxyCommand=...). Conservative charsets that
# can never start with '-'.
SSH_USER_RE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9._-]*")
SSH_HOST_RE = re.compile(r"[A-Za-z0-9_\[][A-Za-z0-9.:_\]-]*")
# tmux window name: embedded in the ssh remote command (attach --window), so it
# is charset-validated. Matches the entrypoint / agent-container window charset.
WINDOW_RE = re.compile(r"[A-Za-z0-9._-]+")

console = Console()


def eprint(msg: str) -> None:
    # Plain stderr writer; rich would mangle "[agent-container]" as markup and wrap lines.
    print(msg, file=sys.stderr)


class Fatal(Exception):
    """Fatal error; CLI exits 1, wizard prints and returns to the menu."""


def die(msg: str) -> "typer.NoReturn":  # cli() turns Fatal into exit 1
    raise Fatal(msg)


# --- pure helpers ------------------------------------------------------------


def validate_name(name: str) -> str:
    """Validate the container short-name charset: ^[a-z0-9][a-z0-9_-]*$.

    >>> validate_name("acme")
    'acme'
    >>> validate_name("my-box")
    'my-box'
    >>> validate_name("Bad")
    Traceback (most recent call last):
    ...
    Fatal: invalid <name> 'Bad'; must match [a-z0-9][a-z0-9_-]*
    """
    if not name:
        die("missing required <name> argument")
    if not NAME_RE.fullmatch(name):
        die(f"invalid <name> '{name}'; must match [a-z0-9][a-z0-9_-]*")
    return name


def container_name(name: str) -> str:
    """
    >>> container_name("acme")
    'agent-container-acme'
    """
    return f"{CONTAINER_PREFIX}{name}"


def volume_name(name: str) -> str:
    """
    >>> volume_name("acme")
    'agent-container-acme-workspace'
    """
    return f"{CONTAINER_PREFIX}{name}-workspace"


def claude_volume_name(name: str) -> str:
    """
    >>> claude_volume_name("acme")
    'agent-container-acme-claude'
    """
    return f"{CONTAINER_PREFIX}{name}-claude"


def codex_volume_name(name: str) -> str:
    """
    >>> codex_volume_name("acme")
    'agent-container-acme-codex'
    """
    return f"{CONTAINER_PREFIX}{name}-codex"


def pi_volume_name(name: str) -> str:
    """
    >>> pi_volume_name("acme")
    'agent-container-acme-pi'
    """
    return f"{CONTAINER_PREFIX}{name}-pi"


def shellenv_volume_name(name: str) -> str:
    """
    >>> shellenv_volume_name("acme")
    'agent-container-acme-shellenv'
    """
    return f"{CONTAINER_PREFIX}{name}-shellenv"


def tmux_volume_name(name: str) -> str:
    """Persists ~/.config/tmux (tmux.conf + tpm plugins) across down/up.

    >>> tmux_volume_name("acme")
    'agent-container-acme-tmux'
    """
    return f"{CONTAINER_PREFIX}{name}-tmux"


def all_volume_mounts(name: str) -> list[str]:
    """The six per-container '-v' volume args, in the canonical fixed order
    (workspace, claude, codex, pi, shellenv, tmux). pi-coding-agent's
    config/auth dir is ~/.pi (verified from
    the package: piConfig.configDir='.pi', getAgentDir()->~/.pi/agent).

    >>> all_volume_mounts("acme")
    ['agent-container-acme-workspace:/workspace', 'agent-container-acme-claude:/home/dev/.claude', 'agent-container-acme-codex:/home/dev/.codex', 'agent-container-acme-pi:/home/dev/.pi', 'agent-container-acme-shellenv:/home/dev/.agent-container', 'agent-container-acme-tmux:/home/dev/.config/tmux']
    """
    return [
        f"{volume_name(name)}:/workspace",
        f"{claude_volume_name(name)}:/home/dev/.claude",
        f"{codex_volume_name(name)}:/home/dev/.codex",
        f"{pi_volume_name(name)}:/home/dev/.pi",
        f"{shellenv_volume_name(name)}:/home/dev/.agent-container",
        f"{tmux_volume_name(name)}:/home/dev/.config/tmux",
    ]


def per_container_volumes(name: str) -> list[str]:
    """All per-container volume NAMES, canonical order; used by --purge.

    >>> per_container_volumes("acme")
    ['agent-container-acme-workspace', 'agent-container-acme-claude', 'agent-container-acme-codex', 'agent-container-acme-pi', 'agent-container-acme-shellenv', 'agent-container-acme-tmux']
    """
    return [
        volume_name(name),
        claude_volume_name(name),
        codex_volume_name(name),
        pi_volume_name(name),
        shellenv_volume_name(name),
        tmux_volume_name(name),
    ]


def resolve_bind_mount(spec: str) -> str:
    """Resolve a '--mount HOSTDIR[:CONTAINERPATH]' spec into an absolute,
    read-write '-v' value.

    HOSTDIR is resolved to an absolute real path (Path.resolve()) and must be
    an existing directory. CONTAINERPATH defaults to /workspace/<basename>; if
    given explicitly it must be absolute. No secret/env value ever reaches argv.

    Lima prerequisite: the host dir must sit under a path the Lima VM exposes
    WRITABLE (set `writable: true` on the relevant mount and restart Lima),
    otherwise the bind is read-only inside the VM.
    """
    host, sep, container = spec.partition(":")
    if not host:
        die(f"--mount: empty host directory in '{spec}'")
    p = Path(host)
    if not p.is_dir():
        die(f"--mount: host path '{host}' does not exist or is not a directory")
    abs_host = str(p.resolve())
    if sep:  # an explicit ':' was present
        if not container:
            die(f"--mount: empty container path in '{spec}'")
        if not container.startswith("/"):
            die(f"--mount: container path '{container}' must be absolute")
    else:
        container = f"/workspace/{Path(abs_host).name}"
    return f"{abs_host}:{container}"


def port_for_name(name: str) -> int:
    """Deterministic port: PORT_BASE + (sum of char codes mod PORT_RANGE).

    Name charset is ASCII-only (enforced by NAME_RE), so ord() matches
    bash's printf '%d' "'c" exactly.

    >>> port_for_name("acme")
    2206
    >>> port_for_name("my-box")
    2204
    """
    return PORT_BASE + (sum(ord(c) for c in name) % PORT_RANGE)


def name_to_key(name: str) -> str:
    """hosts.conf key prefix: hyphens -> underscores, uppercased.

    >>> name_to_key("my-box")
    'MY_BOX'
    >>> name_to_key("acme")
    'ACME'
    """
    return name.replace("-", "_").upper()


def resolve_ssh_user(override: str | None = None) -> str:
    """SSH user from --user / AGENT_CONTAINER_USER / 'dev', charset-checked so it can
    never be parsed by ssh as an option.

    >>> resolve_ssh_user("dev")
    'dev'
    >>> resolve_ssh_user("-oProxyCommand=x")
    Traceback (most recent call last):
    ...
    Fatal: invalid ssh user '-oProxyCommand=x'
    """
    user = override or os.environ.get("AGENT_CONTAINER_USER") or "dev"
    if not SSH_USER_RE.fullmatch(user):
        die(f"invalid ssh user '{user}'")
    return user


def validate_window(window: str) -> str:
    """tmux window name guard: it is embedded in the ssh remote shell command,
    so reject anything outside the safe charset before building it.

    >>> validate_window("agents")
    'agents'
    >>> validate_window("a; rm -rf ~")
    Traceback (most recent call last):
    ...
    Fatal: invalid tmux window 'a; rm -rf ~'; must match [A-Za-z0-9._-]+
    """
    if not WINDOW_RE.fullmatch(window):
        die(f"invalid tmux window '{window}'; must match [A-Za-z0-9._-]+")
    return window


def parse_kv_config(text: str) -> dict[str, str]:
    """Literal KEY=VALUE parser for hosts.conf. Never executes the file.

    Skips blank lines and # comments, strips an optional leading 'export ',
    splits on the first '=', honours one pair of matching quotes, and — like
    bash `source` — drops unquoted trailing ' # comment's (a '#' only starts
    a comment when preceded by whitespace; 'A=#lit' keeps the '#').

    >>> parse_kv_config("# c\\n\\nA=1\\nexport B='two'\\nC=\\"three\\"\\nD=a=b\\n")
    {'A': '1', 'B': 'two', 'C': 'three', 'D': 'a=b'}
    >>> parse_kv_config('H=vps.example.com # primary box\\nQ="a # b" # c\\nR=#lit\\n')
    {'H': 'vps.example.com', 'Q': 'a # b', 'R': '#lit'}
    """
    out: dict[str, str] = {}
    for line in text.splitlines():
        line = line.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        if line.startswith("export "):
            line = line[len("export "):].lstrip()
        key, _, value = line.partition("=")
        key = key.strip()
        value = value.strip()
        if value[:1] in ("'", '"'):
            # Quoted: take up to the matching close quote; anything after it
            # (e.g. a trailing comment) is ignored, as bash would.
            closing = value.find(value[0], 1)
            if closing != -1:
                value = value[1:closing]
        else:
            m = re.search(r"\s#", value)
            if m:
                value = value[: m.start()].rstrip()
        if key:
            out[key] = value
    return out


def env_file_candidates(name: str, cwd: Path) -> list[Path]:
    """Env-file resolution order (./.env, then per-name, then shared default).

    >>> [str(p) for p in env_file_candidates("acme", Path("/w"))][0]
    '/w/.env'
    """
    return [cwd / ".env", CONFIG_DIR / f"{name}.env", CONFIG_DIR / ".env"]


def resolve_env_file(name: str) -> Path | None:
    # Secret hygiene: only existence checks; contents are never read.
    for candidate in env_file_candidates(name, Path.cwd()):
        if candidate.is_file():
            return candidate
    return None


def state_file(name: str) -> Path:
    return STATE_DIR / f"{name}.port"


# --- runtime -----------------------------------------------------------------

_hosts_warned = False

# Captured at startup so an abnormal ssh exit can't leave the terminal raw.
try:
    _ORIG_TERMIOS = termios.tcgetattr(sys.stdin.fileno()) if sys.stdin.isatty() else None
except Exception:
    _ORIG_TERMIOS = None


def detect_runtime() -> str:
    """Resolve the container runtime.

    AGENT_CONTAINER_RUNTIME (validated docker|podman, must be on PATH) always wins.
    Otherwise the default is platform-aware: on macOS the operator runs Lima +
    docker-cli, so prefer docker then podman; on Linux (the VPS) prefer podman
    then docker. Dies if neither is installed.
    """
    forced = os.environ.get("AGENT_CONTAINER_RUNTIME")
    if forced:
        if forced not in ("podman", "docker"):
            die(f"AGENT_CONTAINER_RUNTIME must be 'docker' or 'podman', got: {forced}")
        if not shutil.which(forced):
            die(f"AGENT_CONTAINER_RUNTIME={forced} but '{forced}' is not on PATH")
        return forced
    order = ("docker", "podman") if sys.platform.startswith("darwin") else ("podman", "docker")
    for rt in order:
        if shutil.which(rt):
            return rt
    die("neither 'podman' nor 'docker' on PATH (install one, or set AGENT_CONTAINER_RUNTIME)")


def query(argv: list[str]) -> subprocess.CompletedProcess:
    return subprocess.run(argv, capture_output=True, text=True)


def container_running(rt: str, cname: str) -> bool:
    r = query([rt, "ps", "--filter", f"name=^{cname}$", "--format", "{{.Names}}"])
    return cname in r.stdout.splitlines()  # exact match, mirrors grep -qx


def container_exists(rt: str, cname: str) -> bool:
    r = query([rt, "ps", "-a", "--filter", f"name=^{cname}$", "--format", "{{.Names}}"])
    return cname in r.stdout.splitlines()


def ps_agent_container(rt: str, include_stopped: bool = False) -> list[tuple[str, str, str, str]]:
    """(cname, image, status, uptime) rows for agent-container-* containers.

    Go-template + tab split, not --format json: podman and docker JSON
    shapes are incompatible, the template output is not.
    """
    argv = [rt, "ps"] + (["-a"] if include_stopped else [])
    argv += ["--format", "{{.Names}}\t{{.Image}}\t{{.Status}}\t{{.RunningFor}}"]
    rows = []
    for line in query(argv).stdout.splitlines():
        parts = line.split("\t")
        if len(parts) == 4 and parts[0].startswith(CONTAINER_PREFIX):
            rows.append((parts[0], parts[1], parts[2], parts[3]))
    return rows


def image_exists(rt: str, tag: str) -> bool:
    # `image inspect` works on both podman and docker (podman's `image exists` does not).
    return query([rt, "image", "inspect", tag]).returncode == 0


def port_free(port: int) -> bool:
    # Wildcard bind: `-p {port}:22` publishes on ALL interfaces (parity with
    # agent-container), so probe what will actually be bound, not just loopback.
    try:
        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
            s.bind(("", port))
        return True
    except OSError:
        return False


def write_state(name: str, port: int) -> None:
    STATE_DIR.mkdir(parents=True, exist_ok=True)
    state_file(name).write_text(f"{port}\n")


def read_state_port(name: str) -> str | None:
    f = state_file(name)
    if not f.is_file():
        return None
    return f.read_text().strip() or None


def clear_state(name: str) -> None:
    state_file(name).unlink(missing_ok=True)


def load_hosts_conf() -> dict[str, str]:
    global _hosts_warned
    if not HOSTS_CONF.is_file():
        return {}
    conf = parse_kv_config(HOSTS_CONF.read_text())
    if not _hosts_warned and any("$" in v or "`" in v for v in conf.values()):
        eprint(
            "[agent-container] WARNING: hosts.conf contains '$' or '`' values; "
            "agent-container does not perform shell expansion (agent-container does)."
        )
        _hosts_warned = True
    return conf


def hosts_entry(name: str) -> tuple[str, str] | None:
    """(host, port) from hosts.conf, or None unless BOTH keys are present."""
    conf = load_hosts_conf()
    key = name_to_key(name)
    host, port = conf.get(f"{key}_HOST"), conf.get(f"{key}_PORT")
    if host and port:
        return host, port
    return None


def quadlet_active(name: str) -> bool:
    # Best-effort probe; systemctl is absent on macOS — ignore all failures.
    if not shutil.which("systemctl"):
        return False
    try:
        r = query(["systemctl", "--user", "is-active", f"{container_name(name)}.service"])
        return r.returncode == 0 and r.stdout.strip() == "active"
    except Exception:
        return False


def is_tty() -> bool:
    return sys.stdin.isatty() and sys.stdout.isatty()


# --- commands ----------------------------------------------------------------


def log(msg: str) -> None:
    eprint(f"[agent-container] {msg}")


def warn(msg: str) -> None:
    eprint(f"[agent-container] WARNING: {msg}")


def hint(cmd: str) -> None:
    console.print(f"hint: {cmd}", style="dim")


def do_build(tag: str, context: "Path | None" = None) -> None:
    # `build` is the one subcommand that needs a repo checkout: a docker build
    # context IS a checkout. Resolve it explicitly (a PyPI install has REPO_ROOT
    # is None) and fail actionably rather than with a traceback.
    ctx = context
    if ctx is None:
        env = os.environ.get("AGENT_CONTAINER_REPO")
        if env:
            base = Path(env).expanduser().resolve()
            if not _is_repo_checkout(base):
                die(
                    f"AGENT_CONTAINER_REPO={env} is not an agent-container checkout "
                    "(missing Dockerfile/completions/agent-container.bash)"
                )
            ctx = base
        else:
            ctx = REPO_ROOT
    if ctx is None:
        die(
            "no repo checkout for the docker build context; run from a checkout, "
            "set AGENT_CONTAINER_REPO=<checkout>, or pass --context <dir>"
        )
    rt = detect_runtime()
    log(f"building image '{tag}' with {rt} from {ctx}")
    # Inherited stdio: layer progress must stream, never capture.
    rc = subprocess.run([rt, "build", "-t", tag, str(ctx)]).returncode
    if rc != 0:
        die(f"build failed (exit {rc})")


def launch_container(rt: str, name: str, env_file: Path, mounts: list[str] | None = None) -> None:
    """Build and run the container start argv.

    `mounts` are already-resolved '<abs-host>:<container>' bind specs (from
    resolve_bind_mount); they are appended after the standard per-container
    volumes and before --restart.
    """
    cname, vname, port = container_name(name), volume_name(name), port_for_name(name)
    if not port_free(port):
        die(
            f"port {port} is already in use (port = 2200 + name hash; "
            f"collisions are possible). Stop whatever holds it (agent-container list) "
            f"or pick a different name."
        )
    log(f"name={name} port={port} env-file={env_file}")
    log(f"image={IMAGE_NAME} volume={vname}")
    argv = [
        rt, "run", "-d",
        "--name", cname,
        "--env-file", str(env_file),
        # Publishes sshd on ALL host interfaces (remote hosts.conf attach needs
        # it). Firewall the VPS.
        "-p", f"{port}:22",
    ]
    # Standard per-container volumes (canonical order), then optional binds.
    for vol in all_volume_mounts(name):
        argv += ["-v", vol]
    for m in (mounts or []):
        argv += ["-v", m]
    argv += ["--restart", "unless-stopped", IMAGE_NAME]
    r = query(argv)
    if r.returncode != 0:
        die(f"{rt} run failed: {r.stderr.strip()}")
    write_state(name, port)
    log(f"started {cname}; attach with: agent-container attach {name}")
    log(f"or directly: ssh dev@localhost -p {port} -t tmux attach -t main")


def do_up(name: str, env_file_override: Path | None = None, mounts: list[str] | None = None) -> None:
    validate_name(name)
    # Resolve binds up front so a bad --mount aborts before any runtime call.
    resolved_mounts = [resolve_bind_mount(m) for m in (mounts or [])]
    rt = detect_runtime()
    cname = container_name(name)

    if container_running(rt, cname):
        port = read_state_port(name)
        log(f"container {cname} already running" + (f" on port {port}" if port else ""))
        log(f"attach with: agent-container attach {name}")
        return

    if container_exists(rt, cname):
        die(f"container {cname} exists but is not running. Run: agent-container down {name}")

    env_file = env_file_override or resolve_env_file(name)
    if env_file is None:
        cands = ", ".join(str(c) for c in env_file_candidates(name, Path.cwd()))
        die(f"no .env found. Looked in: {cands}")

    if not image_exists(rt, IMAGE_NAME):
        die(f"image {IMAGE_NAME} not found; run: agent-container build")

    launch_container(rt, name, env_file, resolved_mounts)


def down_container(rt: str, name: str, purge: bool) -> None:
    cname = container_name(name)
    if container_exists(rt, cname):
        log(f"stopping {cname}")
        query([rt, "stop", cname])
        log(f"removing {cname}")
        query([rt, "rm", "-f", cname])
    else:
        log(f"no container named {cname}")

    # --purge drops ALL per-container volumes (workspace + claude + codex + pi +
    # shellenv + tmux), tolerating absence; plain down preserves every one of them.
    vols = per_container_volumes(name)
    if purge:
        for vname in vols:
            log(f"purging volume {vname}")
            if query([rt, "volume", "rm", vname]).returncode != 0:
                warn(f"volume {vname} not removed (in use or absent)")
    else:
        log(f"volumes preserved (use --purge to remove): {', '.join(vols)}")

    clear_state(name)


def cli_down(name: str, purge: bool, yes: bool) -> None:
    validate_name(name)
    rt = detect_runtime()

    if quadlet_active(name):
        warn(
            f"systemd user unit {container_name(name)}.service is active; "
            f"systemd will restart the container after removal. Manage it via Quadlet instead."
        )
        if not yes:
            eprint("[agent-container] re-run with -y/--yes to proceed despite the active unit")
            raise typer.Exit(2)

    if not yes:
        if not is_tty():
            eprint("[agent-container] refusing destructive 'down' without -y/--yes on a non-TTY")
            raise typer.Exit(2)
        what = f"stop and remove {container_name(name)}"
        if purge:
            what += f" and DELETE all per-container volumes ({', '.join(per_container_volumes(name))})"
        if not questionary.confirm(f"{what}?", default=False).ask():
            log("aborted")
            return

    down_container(rt, name, purge)


def gather_rows(rt: str) -> list[dict[str, object]]:
    rows: list[dict[str, object]] = []
    running_short: set[str] = set()
    for cname, image, status, uptime in ps_agent_container(rt):
        short = cname[len(CONTAINER_PREFIX):]
        running_short.add(short)
        rows.append({
            "name": cname,
            "port": read_state_port(short) or "?",
            "image": image,
            "status": status,
            "uptime": uptime,
            "stale": False,
        })
    # Orphaned state files: a <name>.port with no running container.
    if STATE_DIR.is_dir():
        for f in sorted(STATE_DIR.glob("*.port")):
            short = f.stem
            if short in running_short:
                continue
            rows.append({
                "name": container_name(short),
                "port": read_state_port(short) or "?",
                "image": "-",
                "status": "stale",
                "uptime": "-",
                "stale": True,
            })
    return rows


def do_list(as_json: bool) -> None:
    rt = detect_runtime()
    rows = gather_rows(rt)
    if as_json:
        print(json.dumps(rows, indent=2))
        return
    table = Table(show_header=True, header_style="bold", box=None, pad_edge=False)
    for col in ("NAME", "PORT", "IMAGE", "STATUS", "UPTIME"):
        table.add_column(col)
    for row in rows:
        style = "dim" if row["stale"] else None
        table.add_row(
            str(row["name"]), str(row["port"]), str(row["image"]),
            str(row["status"]), str(row["uptime"]), style=style,
        )
    console.print(table)


def ssh_argv(user: str, host: str, port: str | int, window: str | None = None) -> list[str]:
    # The one true attach command; argv list, never a shell string. Without a
    # window the argv is unchanged (agent-container parity). With one, the remote
    # command is a SINGLE compound string that selects the window (tolerating
    # its absence) THEN attaches — select-window works on a detached session.
    base = ["ssh", f"{user}@{host}", "-p", str(port), "-t"]
    if window:
        return base + [
            f"tmux select-window -t main:{window} 2>/dev/null; exec tmux attach -t main"
        ]
    return base + ["tmux", "attach", "-t", "main"]


def tmux_nest_warning() -> str | None:
    if os.environ.get("TMUX"):
        return "already inside tmux; detach the INNER session with Ctrl-B Ctrl-B d"
    return None


def resolve_attach_target(
    name: str,
    mode: str,  # "auto" | "local" | "remote"
    user_override: str | None = None,
    host_override: str | None = None,
) -> tuple[str, str, str, str]:
    """Returns (user, host, port, kind). kind is 'local' or 'remote'."""
    # Case-insensitive like agent-container: 'My-Box' resolves the same
    # MY_BOX_* keys (and the same lowercase state file agent-container writes).
    name = validate_name(name.lower())
    user = resolve_ssh_user(user_override)
    if host_override is not None and not SSH_HOST_RE.fullmatch(host_override):
        die(f"invalid ssh host '{host_override}'")
    key = name_to_key(name)

    if mode == "remote" and not HOSTS_CONF.is_file():
        die(f"no hosts config at {HOSTS_CONF} — create it (see docs/agent-container-hosts.example)")

    entry = hosts_entry(name)
    if mode == "remote" or (mode == "auto" and entry is not None):
        if entry is None:
            die(f"no host configured for {name} — add {key}_HOST and {key}_PORT to {HOSTS_CONF}")
        host, port = entry
        return user, host_override or host, port, "remote"

    port = read_state_port(name)
    if port is None:
        if mode == "local":
            die(
                f"no local state for {name} at {state_file(name)} — is the container "
                f"running? (try: agent-container up {name})"
            )
        die(
            f"no attach target for {name}; checked {HOSTS_CONF} "
            f"(no {key}_HOST/{key}_PORT) and {state_file(name)}"
        )
    host = host_override or os.environ.get("AGENT_CONTAINER_HOST") or "localhost"
    return user, host, port, "local"


def cli_attach(
    name: str,
    mode: str,
    user_override: str | None,
    host_override: str | None,
    window: str | None = None,
) -> None:
    # Validate the window BEFORE resolving/building the command (it is embedded
    # in the remote shell string).
    if window:
        validate_window(window)
    user, host, port, _ = resolve_attach_target(name, mode, user_override, host_override)
    if w := tmux_nest_warning():
        warn(w)  # CLI mode: warn and proceed
    session = f'"main"' + (f', window "{window}"' if window else "")
    eprint(f"agent-container: {user}@{host}:{port} (tmux session {session})")
    sys.stdout.flush()
    sys.stderr.flush()
    # Full handover: the process is replaced; signals, SIGWINCH, TTY ownership
    # and the exit code belong to ssh — identical to bash `exec ssh`.
    os.execvp("ssh", ssh_argv(user, host, port, window))


def _child_default_sigint() -> None:
    # SIG_IGN survives exec; without this reset a child spawned while the
    # parent shields itself from Ctrl-C would ignore SIGINT too.
    signal.signal(signal.SIGINT, signal.SIG_DFL)


def wizard_handover(
    user: str,
    host: str,
    port: str,
    logs_hint: str = "agent-container logs <name>",
    window: str | None = None,
) -> None:
    """Attach without killing the wizard: inherited-stdio subprocess + cleanup."""
    target = f"{user}@{host}:{port}"
    session = f'"main"' + (f', window "{window}"' if window else "")
    eprint(f"agent-container: {target} (tmux session {session})")
    sys.stdout.flush()
    sys.stderr.flush()
    old_int = signal.signal(signal.SIGINT, signal.SIG_IGN)  # Ctrl-C goes to ssh only
    try:
        rc = subprocess.run(
            ssh_argv(user, host, port, window), preexec_fn=_child_default_sigint
        ).returncode
    finally:
        signal.signal(signal.SIGINT, old_int)
        if _ORIG_TERMIOS is not None:
            try:
                termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, _ORIG_TERMIOS)
            except Exception:
                pass
    if rc == 0:
        console.print(
            f"Detached — tmux session 'main' is still running on {target}; agents keep working."
        )
    elif rc == 255:
        warn(f"ssh could not connect to {target}; check hosts.conf or the container state.")
    else:
        warn(
            f"remote command failed (exit {rc}); likely 'tmux attach' found no session "
            f"'main'. Check the entrypoint via: {logs_hint}"
        )


def do_logs(name: str, follow: bool) -> int:
    validate_name(name)
    rt = detect_runtime()
    argv = [rt, "logs"] + (["-f"] if follow else []) + [container_name(name)]
    try:
        return subprocess.run(argv).returncode  # inherited stdio
    except KeyboardInterrupt:
        return 130


# --- wizard ------------------------------------------------------------------
# Lifecycle pickers (start/stop/purge/logs) list LOCAL containers only;
# remote (hosts.conf) targets appear exclusively in the Attach picker.


def _validate_wiz_name(text: str):  # questionary validator: True or error string
    return True if NAME_RE.fullmatch(text) else "must match [a-z0-9][a-z0-9_-]*"


def _short(cname: str) -> str:
    return cname[len(CONTAINER_PREFIX):]


def wiz_build(rt: str) -> None:
    tag = questionary.text("image tag", default=IMAGE_NAME).ask()
    if not tag:
        return
    do_build(tag)
    hint("agent-container build" + (f" {tag}" if tag != IMAGE_NAME else ""))


def wiz_up(rt: str) -> None:
    name = questionary.text("container name", validate=_validate_wiz_name).ask()
    if not name:
        return
    cname = container_name(name)

    if container_running(rt, cname):
        port = read_state_port(name)
        log(f"container {cname} already running" + (f" on port {port}" if port else ""))
        return
    if container_exists(rt, cname):
        log(f"container {cname} exists but is stopped — remove it first (Stop / remove)")
        return

    env_file = resolve_env_file(name)
    if env_file is None:
        eprint("[agent-container] no env file found; looked in:")
        for c in env_file_candidates(name, Path.cwd()):
            eprint(f"  {c}")
        target = CONFIG_DIR / f"{name}.env"
        if questionary.confirm(f"create/edit {target} in $EDITOR now?", default=True).ask():
            CONFIG_DIR.mkdir(parents=True, exist_ok=True)
            # $EDITOR gets the path only; agent-container never reads env contents.
            subprocess.run([os.environ.get("EDITOR") or "vi", str(target)])
            env_file = resolve_env_file(name)
        if env_file is None:
            log("still no env file; not starting")
            return

    if not image_exists(rt, IMAGE_NAME):
        if not questionary.confirm(f"image {IMAGE_NAME} is missing — build it now?", default=True).ask():
            return
        do_build(IMAGE_NAME)
        if not image_exists(rt, IMAGE_NAME):
            log("image still missing; not starting")
            return

    # Optional single host-dir bind (empty = none). Resolved now so a bad path
    # surfaces before the confirmation card; Fatal returns to the menu.
    mounts: list[str] = []
    mount_dir = questionary.text(
        "host directory to mount read-write (empty = none)", default=""
    ).ask()
    if mount_dir:
        mounts = [resolve_bind_mount(mount_dir)]

    card = Table(show_header=False, box=None, pad_edge=False)
    card.add_column(style="bold")
    card.add_column()
    card.add_row("env-file", str(env_file))  # path only, never contents
    card.add_row("port", str(port_for_name(name)))
    card.add_row("volumes", ", ".join(per_container_volumes(name)))
    if mounts:
        card.add_row("bind", mounts[0])
    card.add_row("image", IMAGE_NAME)
    console.print(card)

    if not questionary.confirm(f"start {cname}?", default=True).ask():
        return
    launch_container(rt, name, env_file, mounts)  # port pre-check + actionable abort inside
    hint(f"agent-container up {name}" + (f" --mount {mount_dir}" if mounts else ""))


def wiz_attach(rt: str) -> None:
    choices: list[questionary.Choice] = []
    for cname, _image, _status, _uptime in ps_agent_container(rt):
        short = _short(cname)
        port = read_state_port(short) or "?"
        choices.append(questionary.Choice(f"{short}  [local :{port}]", value=("local", short, "", "")))
    conf = load_hosts_conf()
    for key in sorted(conf):
        if not key.endswith("_HOST"):
            continue
        base = key[: -len("_HOST")]
        host, port = conf[key], conf.get(f"{base}_PORT")
        if not (host and port):
            continue
        rname = base.lower()  # round-trips through name_to_key for the hint
        choices.append(
            questionary.Choice(f"{rname}  [remote {host}:{port}]", value=("remote", rname, host, port))
        )
    if not choices:
        log("nothing to attach to: no running local containers and no hosts.conf entries")
        return

    sel = questionary.select("attach to", choices=choices).ask()
    if sel is None:
        return
    if w := tmux_nest_warning():
        warn(w)
        if not questionary.confirm("continue attaching?", default=True).ask():
            return

    # Optional window to select before attaching (empty = session default).
    # Validated now so a bad name aborts back to the menu (Fatal is caught there).
    window = questionary.text("window to select (empty = default)", default="").ask() or None
    if window:
        validate_window(window)

    kind, name, host, port = sel
    user = resolve_ssh_user()
    if kind == "local":
        port = read_state_port(name)
        if port is None:  # TOCTOU: state file vanished since the picker rendered
            warn(f"state file for {name} disappeared; is the container still up?")
            return
        host = os.environ.get("AGENT_CONTAINER_HOST") or "localhost"
    wizard_handover(user, host, port, logs_hint=f"agent-container logs {name}", window=window)
    hint(f"agent-container attach {name} --{kind}" + (f" --window {window}" if window else ""))


def wiz_logs(rt: str) -> None:
    rows = ps_agent_container(rt)
    if not rows:
        log("no running agent-container containers")
        return
    sel = questionary.select("logs for", choices=[_short(r[0]) for r in rows]).ask()
    if sel is None:
        return
    log("streaming logs — Ctrl-C returns to the menu")
    old_int = signal.signal(signal.SIGINT, signal.SIG_IGN)  # Ctrl-C stops the tail only
    try:
        subprocess.run([rt, "logs", "-f", container_name(sel)], preexec_fn=_child_default_sigint)
    finally:
        signal.signal(signal.SIGINT, old_int)
    hint(f"agent-container logs {sel}")


def wiz_down(rt: str) -> None:
    rows = ps_agent_container(rt, include_stopped=True)
    if not rows:
        log("no agent-container containers (running or stopped)")
        return
    choices = []
    for cname, _image, status, _uptime in rows:
        short = _short(cname)
        label = f"{short}  [exited]" if status.lower().startswith("exited") else short
        choices.append(questionary.Choice(label, value=short))
    sel = questionary.select("stop / remove", choices=choices).ask()
    if sel is None:
        return
    cname = container_name(sel)

    if not container_exists(rt, cname):  # TOCTOU re-verify
        warn(f"container {cname} no longer exists")
        return
    if quadlet_active(sel):
        warn(
            f"systemd user unit {cname}.service is active; systemd will restart "
            f"the container after removal. Manage it via Quadlet instead."
        )
        if not questionary.confirm("proceed anyway?", default=False).ask():
            return
    if not questionary.confirm(f"stop and remove {cname}?", default=False).ask():
        log("aborted")
        return

    purge = False
    vols = per_container_volumes(sel)
    if questionary.confirm(
        f"also delete ALL per-container volumes ({', '.join(vols)})?", default=False
    ).ask():
        typed = questionary.text(f"type the container name ({cname}) to confirm volume deletion").ask()
        if typed == cname:
            purge = True
        else:
            log("name mismatch — volumes will be preserved")
    down_container(rt, sel, purge)  # reports preserved vs purged, clears state
    hint(f"agent-container down {sel}" + (" --purge" if purge else ""))


def _volume_names(rt: str) -> list[str]:
    out = query([rt, "volume", "ls", "--format", "{{.Name}}"]).stdout.splitlines()
    return [v for v in out if re.fullmatch(re.escape(CONTAINER_PREFIX) + r".+-workspace", v)]


def wiz_purge_volume(rt: str) -> None:
    containers = {row[0] for row in ps_agent_container(rt, include_stopped=True)}
    orphans = []
    for vol in _volume_names(rt):
        short = vol[len(CONTAINER_PREFIX): -len("-workspace")]
        if container_name(short) not in containers:
            orphans.append(vol)
    if not orphans:
        log("no orphaned agent-container volumes")
        return
    sel = questionary.select("purge orphaned volume", choices=orphans).ask()
    if sel is None:
        return
    typed = questionary.text(f"type the volume name ({sel}) to confirm deletion").ask()
    if typed != sel:
        log("name mismatch — nothing removed")
        return
    if sel not in _volume_names(rt):  # TOCTOU re-verify
        warn(f"volume {sel} no longer exists")
        return
    if query([rt, "volume", "rm", sel]).returncode != 0:
        warn(f"volume {sel} not removed (in use)")
    else:
        log(f"volume {sel} purged")
    hint(f"{rt} volume rm {sel}")


_MENU: list[tuple[str, "object"]] = [
    ("Provision (build image)", wiz_build),
    ("Start a container", wiz_up),
    ("Attach", wiz_attach),
    ("Logs", wiz_logs),
    ("Stop / remove", wiz_down),
    ("Purge orphaned volume", wiz_purge_volume),
    ("Quit", None),
]


def wizard_loop() -> int:
    if not is_tty():
        eprint("[agent-container] no TTY; interactive wizard unavailable. Use subcommands (agent-container --help).")
        return 2
    try:
        rt = detect_runtime()
    except Fatal as e:
        eprint(f"[agent-container] FATAL: {e}")
        return 1
    actions = dict(_MENU)
    while True:
        try:
            running = len(ps_agent_container(rt))
            hosts = "present" if HOSTS_CONF.is_file() else "absent"
            console.print(
                f"runtime: {rt} | running local containers: {running} | hosts.conf: {hosts}",
                style="dim",
            )
            choice = questionary.select("agent-container — what now?", choices=[t for t, _ in _MENU]).ask()
            if choice is None or choice == "Quit":
                return 0
            try:
                actions[choice](rt)
            except Fatal as e:
                eprint(f"[agent-container] ERROR: {e}")  # back to the menu, not exit
        except (KeyboardInterrupt, EOFError):
            return 0


# --- entry -------------------------------------------------------------------

app = typer.Typer(
    add_completion=False,
    no_args_is_help=False,
    pretty_exceptions_enable=False,
    help="Interactive wizard + CLI for agent-container containers.",
)


def fatal_exit(e: Fatal) -> "typer.NoReturn":
    eprint(f"[agent-container] FATAL: {e}")
    raise typer.Exit(1)


def run_self_test() -> int:
    import doctest

    failures, tests = doctest.testmod(
        sys.modules[__name__], optionflags=doctest.IGNORE_EXCEPTION_DETAIL
    )
    # Hard-coded port corpus: pins the deterministic port hash against regressions.
    corpus = {
        "acme": 2206,
        "blog": 2220,
        "scratch": 2244,
        "my-box": 2204,
        "a": 2297,
        "devbox123": 2298,
    }
    bad = {n: (port_for_name(n), want) for n, want in corpus.items() if port_for_name(n) != want}
    keys_ok = name_to_key("my-box") == "MY_BOX" and name_to_key("acme") == "ACME"
    ok = failures == 0 and not bad and keys_ok
    print(f"doctests: {tests - failures}/{tests} passed")
    print(f"port corpus: {'ok' if not bad else f'MISMATCH {bad}'}")
    print(f"key derivation: {'ok' if keys_ok else 'MISMATCH'}")
    print("self-test:", "PASS" if ok else "FAIL")
    return 0 if ok else 1


@app.command()
def build(
    tag: str = typer.Argument(IMAGE_NAME, help="Image tag to build."),
    context: Path | None = typer.Option(
        None,
        "--context",
        help="Docker build context (repo checkout). Defaults to AGENT_CONTAINER_REPO "
        "or the auto-detected checkout; required when installed from PyPI.",
    ),
) -> None:
    """Build the image from a repo checkout (streams build output)."""
    do_build(tag, context)


@app.command()
def up(
    name: str = typer.Argument(..., help="Container short name (agent-container-<name>)."),
    env_file: Path | None = typer.Option(
        None, "--env-file", help="Bypass env-file resolution; path must exist."
    ),
    mount: List[str] = typer.Option(
        None,
        "--mount",
        help="Bind-mount a host dir read-write (repeatable): HOSTDIR[:CONTAINERPATH]. "
        "Default CONTAINERPATH is /workspace/<basename>. Lima: host dir must be "
        "under a writable Lima mount.",
    ),
) -> None:
    """Start container agent-container-NAME (detached)."""
    if env_file is not None and not env_file.is_file():
        raise typer.BadParameter(f"--env-file {env_file} does not exist")
    do_up(name, env_file, mount or [])


@app.command()
def down(
    name: str = typer.Argument(..., help="Container short name."),
    purge: bool = typer.Option(False, "--purge", help="Also delete the workspace volume."),
    yes: bool = typer.Option(False, "-y", "--yes", help="Skip confirmation."),
) -> None:
    """Stop and remove container agent-container-NAME."""
    cli_down(name, purge, yes)


@app.command()
def purge(
    name: str = typer.Argument(..., help="Container short name."),
    yes: bool = typer.Option(False, "-y", "--yes", help="Skip confirmation."),
) -> None:
    """Sugar for: down NAME --purge."""
    cli_down(name, purge=True, yes=yes)


@app.command(name="list")
def list_cmd(
    as_json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
) -> None:
    """List running agent-container containers (plus stale state files)."""
    do_list(as_json)


@app.command()
def attach(
    name: str = typer.Argument(..., help="Container short name."),
    local: bool = typer.Option(False, "--local", help="Force local target (state file)."),
    remote: bool = typer.Option(False, "--remote", help="Force remote target (hosts.conf)."),
    user: str | None = typer.Option(None, "--user", help="SSH user (default: AGENT_CONTAINER_USER or dev)."),
    host: str | None = typer.Option(None, "--host", help="Override the resolved host."),
    window: str | None = typer.Option(
        None, "--window", "-w", help="Select tmux window NAME (session 'main') before attaching."
    ),
) -> None:
    """ssh + tmux attach to container NAME (local state file or hosts.conf)."""
    if local and remote:
        raise typer.BadParameter("--local and --remote are mutually exclusive")
    mode = "local" if local else ("remote" if remote else "auto")
    cli_attach(name, mode, user, host, window)


@app.command()
def logs(
    name: str = typer.Argument(..., help="Container short name."),
    no_follow: bool = typer.Option(False, "--no-follow", help="Print logs without following."),
) -> None:
    """Tail container logs."""
    raise typer.Exit(do_logs(name, follow=not no_follow))


@app.command()
def menu() -> None:
    """Interactive wizard (same as bare agent-container)."""
    raise typer.Exit(wizard_loop())


def _completion_script(shell: str) -> str:
    """Return the bash/zsh completion script text.

    Prefers the on-disk checkout (dev / `uv run --script`, where REPO_ROOT
    resolves via the __file__ marker); falls back to the completions bundled as
    package data in a non-editable PyPI install (where REPO_ROOT is None).
    """
    if REPO_ROOT is not None:
        p = REPO_ROOT / "completions" / f"agent-container.{shell}"
        if p.is_file():
            return p.read_text()
    try:
        import importlib.resources as ir

        res = ir.files("agent_container").joinpath(f"completions/agent-container.{shell}")
        if res.is_file():
            return res.read_text()
    except (ModuleNotFoundError, ImportError, FileNotFoundError, TypeError, AttributeError):
        pass
    die(f"completion script for '{shell}' not found (need a checkout or an installed package)")


@app.command()
def completions(
    # Optional + manual validation so a bad/missing shell routes through die()
    # (exit 1, '[agent-container] FATAL:' style), not Typer's exit-2 required-arg error.
    shell: str = typer.Argument("", help="Shell to emit completion for: bash or zsh."),
) -> None:
    """Print the completion script for bash or zsh (from a checkout or package data)."""
    if shell not in ("bash", "zsh"):
        die("usage: agent-container completions <bash|zsh>")
    sys.stdout.write(_completion_script(shell))


@app.callback(invoke_without_command=True)
def main(
    ctx: typer.Context,
    self_test: bool = typer.Option(False, "--self-test", help="Run doctests + port-hash corpus checks."),
) -> None:
    if self_test:
        raise typer.Exit(run_self_test())
    if ctx.invoked_subcommand is None:
        raise typer.Exit(wizard_loop())


def cli() -> None:
    """Console-script entry point for `uv tool install` (see pyproject.toml).

    uv's generated launcher does `from agent_container import cli; sys.exit(cli())`,
    so the Fatal -> exit-1 handling that used to live only in the __main__ guard
    is hoisted here. NOT named `main` — that is already the Typer @app.callback.
    """
    try:
        app()
    except Fatal as e:
        eprint(f"[agent-container] FATAL: {e}")
        sys.exit(1)


if __name__ == "__main__":
    cli()
