"""The Rust `atlas` binary, fronted (D-263).

`tooling/atlas` was 24 lines of bash that built `server/target/debug/atlas` if
missing and `exec`'d it with every argument. So its verbs never existed in the
shell at all — they live in Rust, which is why this is a passthrough rather than
a port.

**The verbs are declared here even though the binary owns them.** That
duplication is deliberate: `reach atlas --help` has to be a complete index of
what exists, and an index that says "ask the binary" is not one. The cost is
that a subcommand added on the Rust side is invisible here until someone adds a
line — so `run()` also accepts anything, and an unknown verb reaches the binary
rather than being rejected by a list that has fallen behind.
"""

from __future__ import annotations

from tooling.core import config, console, process
from tooling.core.errors import ReachError

# What the binary offers today. Discovered from the wrapper's own usage text and
# from atlas-commit-and-sync, which calls three verbs the wrapper never
# documented — list-stations, wipe-system, commit-system, sync-wiki.
KNOWN_VERBS = (
    "stats",
    "show-system",
    "list-bodies",
    "list-stations",
    "populate",
    "commit-system",
    "wipe-system",
    "sync-wiki",
)


def binary_path():
    return config.path("server", "target", "debug", "atlas")


def run(*args: str, capture: bool = True) -> str:
    """Invoke the Rust atlas binary, building it first if it is absent."""
    binary = binary_path()
    if not binary.is_file():
        console.event("building the atlas binary (first run)", level="warn")
        build = process.run(
            ["cargo", "build", "--bin", "atlas"],
            cwd=config.path("server"),
            check=False,
            missing_fix="install Rust — make setup-rust",
        )
        if build.returncode != 0:
            raise ReachError(
                f"could not build the atlas binary\n{(build.stderr or '').strip()}",
                fix="cd server && cargo build --bin atlas — to see the full error",
                exit_code=build.returncode,
            )

    result = process.run([str(binary), *args], check=False, capture=capture)
    if result.returncode != 0:
        raise ReachError(
            f"atlas {' '.join(args)} exited {result.returncode}\n"
            + (result.stderr or "").strip(),
            fix=f"run `{binary} {' '.join(args)}` directly for the full output",
            exit_code=result.returncode,
        )
    return result.stdout or ""