"""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.

The build-if-missing and invoke machinery moved to `core.process.cargo_binary`
once `generate-brands` and `generate-corporations` turned out to be the same
24 lines of bash. Three copies of one idea is a substrate.
"""

from __future__ import annotations

from tooling.core import process

# What the binary offers today. Discovered from the wrapper's own usage text and
# from atlas-commit-and-sync, which calls four 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 run(*args: str, capture: bool = True) -> str:
    """Invoke the Rust atlas binary, building it first if it is absent."""
    return process.cargo_binary("atlas", *args, capture=capture)