mad-cli 0.4.0__py3-none-any.whl

mad_cli/commands/versions.py

@@ -0,0 +1,61 @@
+"""``mad versions [INSTANCE]`` and ``mad update INSTANCE`` — versions and upgrades.
+
+Thin adapter over :mod:`mad_cli.core.usecases.versions`. ``versions`` renders, per
+instance, the pinned / installed / latest-on-PyPI versions and whether an update
+is available; ``update`` re-pins ``MAD_VERSION`` and rebuilds from scratch.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.table import Table
+
+from mad_cli.commands._adapt import resolve_or_die
+from mad_cli.core.usecases import versions as uc
+from mad_cli.core.usecases.errors import NotFoundError
+from mad_cli.ui.console import console, error, header, info, ok, run_step, warn
+
+
+def versions(
+    instance: str | None = typer.Argument(
+        None, help="Instance name (reports on every instance when omitted)."
+    ),
+) -> None:
+    """Show pinned / installed / latest versions and whether an update is available."""
+    try:
+        rows = uc.versions(instance)
+    except NotFoundError:
+        error(f"Instance {instance!r} not found. Run `mad list` to see available instances.")
+        raise typer.Exit(1) from None
+
+    if not rows:
+        info("No instances yet. Run `mad install` to create one.")
+        return
+
+    table = Table(title="mad versions")
+    table.add_column("Name", style="bold cyan", no_wrap=True)
+    table.add_column("Pinned")
+    table.add_column("Installed")
+    table.add_column("Latest on PyPI")
+    table.add_column("Update")
+    for row in rows:
+        label = f"{row.name} (legacy)" if row.legacy else row.name
+        table.add_row(label, row.pinned, row.installed, row.latest, row.update)
+    console.print(table)
+
+
+def update(
+    instance: str = typer.Argument(..., help="Instance name."),
+    version: str | None = typer.Option(
+        None, "--version", help="Version to pin (omit or blank to track latest)."
+    ),
+) -> None:
+    """Re-pin ``MAD_VERSION`` and rebuild the instance from scratch."""
+    inst = resolve_or_die(instance)
+    header(f"Updating {inst.name} → {version or 'latest'}")
+    res = run_step("Rebuilding image (no cache) and starting…", lambda: uc.update(inst, version))
+    if res.healthy:
+        ok(f"{inst.name} updated to {res.target}.")
+    else:
+        warn(f"{inst.name} rebuilt but is not healthy yet. Check `mad status` and `mad logs`.")
+        raise typer.Exit(1)

mad_cli/core/__init__.py

@@ -0,0 +1,4 @@
+"""Framework-free engine for mad-cli.
+
+Layering rule (CONTRACTS.md): nothing under ``mad_cli.core`` imports typer or rich.
+"""

mad_cli/core/claude_creds.py

@@ -0,0 +1,31 @@
+"""Claude OAuth credentials file (``claudeAiOauth`` format, ``chmod 600``).
+
+Ports ``write_claude_credentials`` from the reference ``configure.sh``: the file
+that the ``claude-code`` CLI reads from ``~/.claude/.credentials.json`` inside the
+container, so the agent authenticates without an interactive login.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def write_claude_credentials(claude_dir: Path, token: str) -> Path:
+    """Write ``claude_dir/.credentials.json`` and return its path.
+
+    The directory is created if needed and the file is ``chmod 600`` because it
+    holds a bearer token.
+    """
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    path = claude_dir / ".credentials.json"
+    payload = {
+        "claudeAiOauth": {
+            "accessToken": token,
+            "expiresAt": 9999999999999,
+            "scopes": ["user:inference", "user:profile"],
+        }
+    }
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    path.chmod(0o600)
+    return path

mad_cli/core/compose.py

@@ -0,0 +1,145 @@
+"""docker compose runner — the one module that shells out to Docker.
+
+Ports the lifecycle semantics of the reference ``start.sh``. Every invocation is
+scoped to the instance with ``-p mad-<name> -f <compose.yml> --env-file <.env>``
+so instances never collide. ``dry_run`` records the argv on
+:attr:`ComposeRunner.last_command` without executing anything, which is what the
+tests assert against.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+
+from mad_cli.core.instance import Instance
+
+
+class ComposeError(Exception):
+    """A docker compose invocation failed."""
+
+
+class ComposeRunner:
+    def __init__(self, instance: Instance, *, dry_run: bool = False) -> None:
+        self.instance = instance
+        self.dry_run = dry_run
+        self.last_command: list[str] | None = None
+
+    # ── argv construction ───────────────────────────────────────────────────
+    def _base(self) -> list[str]:
+        return [
+            "docker",
+            "compose",
+            "-p",
+            f"mad-{self.instance.name}",
+            "-f",
+            str(self.instance.compose_file),
+            "--env-file",
+            str(self.instance.env_file),
+        ]
+
+    def _run(
+        self,
+        args: list[str],
+        *,
+        capture: bool = False,
+        check: bool = True,
+    ) -> subprocess.CompletedProcess[str] | None:
+        cmd = self._base() + args
+        self.last_command = cmd
+        if self.dry_run:
+            return None
+        try:
+            completed = subprocess.run(cmd, capture_output=capture, text=True, check=False)
+        except OSError as exc:
+            raise ComposeError(f"failed to run {' '.join(cmd)}: {exc}") from exc
+        if check and completed.returncode != 0:
+            stderr = (completed.stderr or "").strip()
+            raise ComposeError(
+                f"`{' '.join(cmd)}` failed (exit {completed.returncode})"
+                + (f": {stderr}" if stderr else "")
+            )
+        return completed
+
+    # ── lifecycle ───────────────────────────────────────────────────────────
+    def up(self, build: bool = True, detach: bool = True) -> None:
+        args = ["up"]
+        if detach:
+            args.append("-d")
+        if build:
+            args.append("--build")
+        self._run(args)
+
+    def down(self) -> None:
+        self._run(["down"])
+
+    def restart(self) -> None:
+        """Stop then start (with a rebuild), matching ``start.sh restart``."""
+        self.down()
+        self.up()
+
+    def ps(self) -> str:
+        completed = self._run(["ps"], capture=True)
+        return "" if completed is None else (completed.stdout or "")
+
+    def logs(self, follow: bool = True) -> None:
+        args = ["logs"]
+        if follow:
+            args.append("-f")
+        args.append("mad")
+        # Interactive stream: no capture, and a Ctrl-C exit is not an error.
+        self._run(args, check=False)
+
+    def shell(self) -> None:
+        # Interactive: attaches the caller's TTY to `bash` in the service.
+        self._run(["exec", "mad", "bash"], check=False)
+
+    def config_check(self) -> None:
+        self._run(["config", "-q"])
+
+    def build(self, no_cache: bool = False) -> None:
+        args = ["build"]
+        if no_cache:
+            args.append("--no-cache")
+        self._run(args)
+
+    def exec(self, cmd: list[str], capture: bool = True) -> str:
+        completed = self._run(["exec", "mad", *cmd], capture=capture)
+        if completed is None:
+            return ""
+        return completed.stdout or "" if capture else ""
+
+    # ── health ──────────────────────────────────────────────────────────────
+    def wait_healthy(self, timeout_s: int = 180) -> bool:
+        """Poll ``docker inspect`` until the container reports ``healthy``.
+
+        Returns ``True`` as soon as the health status is ``healthy``; returns
+        ``False`` if the timeout elapses first. A ``dry_run`` runner reports
+        healthy immediately.
+        """
+        if self.dry_run:
+            return True
+        container = f"mad-{self.instance.name}"
+        interval = 2.0
+        deadline = time.monotonic() + timeout_s
+        while True:
+            if self._inspect_health(container) == "healthy":
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(interval)
+
+    @staticmethod
+    def _inspect_health(container: str) -> str | None:
+        try:
+            result = subprocess.run(
+                ["docker", "inspect", "--format", "{{.State.Health.Status}}", container],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError:
+            return None
+        if result.returncode != 0:
+            return None
+        return (result.stdout or "").strip()

mad_cli/core/docker_check.py

@@ -0,0 +1,89 @@
+"""Docker / daemon / compose-v2 detection and opt-in Linux install.
+
+Everything is probed through ``subprocess`` (not ``shutil.which``) so the whole
+module can be exercised in tests with a single ``subprocess.run`` double.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+
+
+@dataclass
+class DockerStatus:
+    docker_present: bool
+    daemon_running: bool
+    compose_v2: bool
+    version: str | None
+
+
+def _capture(cmd: list[str]) -> str | None:
+    """Run ``cmd``; return trimmed stdout on success, ``None`` otherwise."""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except (OSError, ValueError):
+        return None
+    if result.returncode != 0:
+        return None
+    return (result.stdout or "").strip()
+
+
+def _ok(cmd: list[str]) -> bool:
+    """Return ``True`` when ``cmd`` exits 0."""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except (OSError, ValueError):
+        return False
+    return result.returncode == 0
+
+
+def check_docker() -> DockerStatus:
+    """Probe for the docker binary, a running daemon and Compose v2."""
+    version = _capture(["docker", "--version"])
+    if version is None:
+        return DockerStatus(
+            docker_present=False,
+            daemon_running=False,
+            compose_v2=False,
+            version=None,
+        )
+    return DockerStatus(
+        docker_present=True,
+        daemon_running=_ok(["docker", "info"]),
+        compose_v2=_ok(["docker", "compose", "version"]),
+        version=version,
+    )
+
+
+def install_docker_linux(assume_yes: bool = False) -> bool:
+    """Install Docker on Linux via the official ``get.docker.com`` script.
+
+    Returns ``True`` on success. The interactive confirmation lives in the
+    command layer; ``assume_yes`` is accepted for symmetry and does not change
+    the (already opted-in) behaviour here. Never touches non-Linux hosts.
+    """
+    if platform.system() != "Linux":
+        return False
+    script_path = ""
+    try:
+        with urllib.request.urlopen("https://get.docker.com", timeout=30) as response:
+            script = response.read()
+        with tempfile.NamedTemporaryFile("wb", suffix=".sh", delete=False) as handle:
+            handle.write(script)
+            script_path = handle.name
+        subprocess.run(["sh", script_path], check=True)
+        subprocess.run(["sudo", "systemctl", "enable", "--now", "docker"], check=True)
+        user = os.environ.get("USER", "")
+        if user:
+            subprocess.run(["sudo", "usermod", "-aG", "docker", user], check=False)
+        return True
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return False
+    finally:
+        if script_path and os.path.exists(script_path):
+            os.unlink(script_path)

mad_cli/core/envfile.py

@@ -0,0 +1,140 @@
+""".env parser/writer that preserves comments, ordering and blank lines.
+
+A pure ``load`` then ``save`` round-trips the file byte-for-byte. Mutations
+(:meth:`EnvFile.set`, :meth:`EnvFile.unset`) touch only the affected line:
+``set`` rewrites an existing assignment in place or appends a new one at the
+end, and ``unset`` drops the assignment line, leaving every comment and blank
+line untouched.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class _Line:
+    """One physical line of the file.
+
+    ``kind`` is ``"kv"`` for an assignment, ``"comment"`` for a ``#`` line and
+    ``"blank"`` otherwise. ``text`` is the exact rendered line; ``key``/``value``
+    are populated only for ``kv`` lines.
+    """
+
+    kind: str
+    text: str
+    key: str | None = None
+    value: str | None = None
+
+
+def _parse_kv(line: str) -> tuple[str, str] | None:
+    """Return ``(key, value)`` if ``line`` is an assignment, else ``None``."""
+    stripped = line.lstrip()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if "=" not in stripped:
+        return None
+    key, _, value = stripped.partition("=")
+    if key.startswith("export "):
+        key = key[len("export ") :]
+    key = key.strip()
+    if not key:
+        return None
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        value = value[1:-1]
+    return key, value
+
+
+class EnvFile:
+    """Comment- and order-preserving representation of a ``.env`` file."""
+
+    path: Path | None
+
+    def __init__(self) -> None:
+        self.path = None
+        self._lines: list[_Line] = []
+        self._final_newline: bool = False
+
+    # ── constructors ────────────────────────────────────────────────────────
+    @classmethod
+    def load(cls, path: Path) -> EnvFile:
+        """Parse ``path`` tolerantly, preserving its exact layout."""
+        obj = cls()
+        obj.path = path
+        obj._parse(path.read_text(encoding="utf-8"))
+        return obj
+
+    @classmethod
+    def empty(cls) -> EnvFile:
+        """Return a fresh, path-less, empty env file."""
+        return cls()
+
+    def _parse(self, text: str) -> None:
+        self._lines = []
+        if text == "":
+            self._final_newline = False
+            return
+        self._final_newline = text.endswith("\n")
+        body = text[:-1] if self._final_newline else text
+        for raw in body.split("\n"):
+            parsed = _parse_kv(raw)
+            if parsed is not None:
+                key, value = parsed
+                self._lines.append(_Line("kv", raw, key=key, value=value))
+            elif raw.lstrip().startswith("#"):
+                self._lines.append(_Line("comment", raw))
+            else:
+                self._lines.append(_Line("blank", raw))
+
+    # ── accessors ───────────────────────────────────────────────────────────
+    def get(self, key: str) -> str | None:
+        """Return the value of ``key`` (first assignment wins), else ``None``."""
+        for line in self._lines:
+            if line.kind == "kv" and line.key == key:
+                return line.value
+        return None
+
+    def set(self, key: str, value: str) -> None:
+        """Set ``key`` to ``value``, rewriting in place or appending at the end."""
+        for line in self._lines:
+            if line.kind == "kv" and line.key == key:
+                line.value = value
+                line.text = f"{key}={value}"
+                return
+        self._lines.append(_Line("kv", f"{key}={value}", key=key, value=value))
+
+    def unset(self, key: str) -> None:
+        """Remove every assignment of ``key`` (no-op if absent)."""
+        self._lines = [line for line in self._lines if not (line.kind == "kv" and line.key == key)]
+
+    def add_comment(self, text: str) -> None:
+        """Append a comment line (used to leave documented, inactive references).
+
+        ``text`` is written verbatim; a leading ``#`` is added if missing. The
+        line is inert — it never shadows an assignment and :meth:`get`/:meth:`keys`
+        ignore it — so it round-trips as a plain reference in the generated file.
+        """
+        rendered = text if text.lstrip().startswith("#") else f"# {text}"
+        self._lines.append(_Line("comment", rendered))
+
+    def keys(self) -> list[str]:
+        """Return the assignment keys in file order."""
+        return [line.key for line in self._lines if line.kind == "kv" and line.key is not None]
+
+    # ── serialisation ───────────────────────────────────────────────────────
+    def render(self) -> str:
+        """Return the file contents as a single string."""
+        body = "\n".join(line.text for line in self._lines)
+        if self._final_newline:
+            return body + "\n"
+        return body
+
+    def save(self, path: Path | None = None) -> None:
+        """Write the file to ``path`` (or the loaded path) byte-stably."""
+        target = path or self.path
+        if target is None:
+            raise ValueError("no path to save to; pass an explicit path")
+        target.write_text(self.render(), encoding="utf-8")
+        self.path = target

mad_cli/core/instance.py

@@ -0,0 +1,110 @@
+"""Instance model and filesystem discovery.
+
+An *instance* is one mad-edge container plus its config directory
+(``compose.yml`` / ``.env`` / ``Dockerfile`` / ``entrypoint.sh``). The modern
+layout stores one instance per directory under ``config_root()/instances/``;
+the legacy single-instance layout kept those files directly at ``config_root()``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from mad_cli.core import paths
+from mad_cli.core.envfile import EnvFile
+
+
+class InstanceNotFoundError(Exception):
+    """Raised when a named instance does not exist under the config root."""
+
+
+@dataclass
+class Instance:
+    name: str
+    config_dir: Path
+    env: EnvFile
+    legacy: bool = False
+
+    @property
+    def host_port(self) -> int | None:
+        """Host port from ``MAD_HOST_PORT`` (``None`` if unset/non-numeric)."""
+        raw = self.env.get("MAD_HOST_PORT")
+        if not raw:
+            return None
+        try:
+            return int(raw)
+        except ValueError:
+            return None
+
+    @property
+    def data_path(self) -> Path | None:
+        """Host data root from ``MAD_DATA_PATH`` (``None`` if unset)."""
+        raw = self.env.get("MAD_DATA_PATH")
+        if not raw:
+            return None
+        return Path(raw)
+
+    @property
+    def version_pin(self) -> str | None:
+        """Pinned mad-edge version from ``MAD_VERSION`` ('' -> ``None``)."""
+        raw = self.env.get("MAD_VERSION")
+        if not raw:
+            return None
+        return raw
+
+    @property
+    def compose_file(self) -> Path:
+        return self.config_dir / "compose.yml"
+
+    @property
+    def env_file(self) -> Path:
+        return self.config_dir / ".env"
+
+
+def _load(config_dir: Path, name: str, *, legacy: bool) -> Instance:
+    env = EnvFile.load(config_dir / ".env")
+    return Instance(name=name, config_dir=config_dir, env=env, legacy=legacy)
+
+
+def discover_instances() -> list[Instance]:
+    """Return every configured instance.
+
+    Modern instances (``instances/<name>/.env``) come first, sorted by name; a
+    directory without a ``.env`` is ignored. A legacy top-level layout
+    (``config_root()/compose.yml`` + ``.env``) is appended with ``legacy=True``,
+    its name taken from ``MAD_INSTANCE`` (default ``"default"``).
+    """
+    found: list[Instance] = []
+
+    root = paths.instances_root()
+    if root.is_dir():
+        for child in sorted(root.iterdir(), key=lambda p: p.name):
+            if child.is_dir() and (child / ".env").is_file():
+                found.append(_load(child, child.name, legacy=False))
+
+    config_root = paths.config_root()
+    if (config_root / ".env").is_file() and (config_root / "compose.yml").is_file():
+        legacy = _load(config_root, "default", legacy=True)
+        name = legacy.env.get("MAD_INSTANCE")
+        if name:
+            legacy.name = name
+        found.append(legacy)
+
+    return found
+
+
+def get_instance(name: str) -> Instance:
+    """Return the instance called ``name`` or raise :class:`InstanceNotFoundError`."""
+    for instance in discover_instances():
+        if instance.name == name:
+            return instance
+    raise InstanceNotFoundError(name)
+
+
+def default_instance() -> Instance | None:
+    """Return the sole instance when exactly one exists, else ``None``."""
+    instances = discover_instances()
+    if len(instances) == 1:
+        return instances[0]
+    return None

mad_cli/core/keyspec.py

@@ -0,0 +1,98 @@
+"""Registry of the credentials / API keys an operator can store in ``.env``.
+
+Each :class:`KeySpec` maps one logical secret to the environment variable(s) it
+is written to. Some secrets fan out to several variables that must carry the
+same value (``github`` -> ``GITHUB_TOKEN`` + ``GH_TOKEN``); ``claude-oauth`` is
+special-cased because, besides landing in ``.env``, it is materialised into the
+container's Claude credentials file (see :mod:`mad_cli.core.claude_creds`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class KeySpec:
+    id: str
+    env_vars: tuple[str, ...]
+    prompt: str
+    secret: bool = True
+    help_url: str | None = None
+    writes_claude_credentials: bool = False
+
+
+BUILTIN_KEYS: dict[str, KeySpec] = {
+    "claude-oauth": KeySpec(
+        id="claude-oauth",
+        env_vars=("_CLAUDE_OAUTH_TOKEN",),
+        prompt="Claude OAuth token (run `claude setup-token` on a logged-in machine)",
+        help_url="https://docs.anthropic.com/en/docs/claude-code",
+        writes_claude_credentials=True,
+    ),
+    "anthropic": KeySpec(
+        id="anthropic",
+        env_vars=("ANTHROPIC_API_KEY",),
+        prompt="Anthropic API key (sk-ant-…)",
+        help_url="https://console.anthropic.com/settings/keys",
+    ),
+    "github": KeySpec(
+        id="github",
+        env_vars=("GITHUB_TOKEN", "GH_TOKEN"),
+        prompt="GitHub personal access token (ghp_…)",
+        help_url="https://github.com/settings/tokens",
+    ),
+    "deepseek": KeySpec(
+        id="deepseek",
+        env_vars=("DEEPSEEK_API_KEY",),
+        prompt="DeepSeek API key",
+        help_url="https://platform.deepseek.com/api_keys",
+    ),
+    "linear": KeySpec(
+        id="linear",
+        env_vars=("LINEAR_API_KEY",),
+        prompt="Linear API key",
+        help_url="https://linear.app/settings/api",
+    ),
+    "opencode": KeySpec(
+        id="opencode",
+        env_vars=("OPENCODE_API_KEY",),
+        prompt="OpenCode API key",
+        help_url="https://opencode.ai/docs",
+    ),
+}
+
+
+def mask(value: str) -> str:
+    """Return a display-safe masking of ``value``.
+
+    Long secrets keep a short prefix and suffix (``"sk-a…f3"``); anything short
+    enough that a prefix/suffix would leak most of it is fully hidden.
+    """
+    if not value:
+        return ""
+    if len(value) <= 8:
+        return "…"
+    return f"{value[:4]}…{value[-2:]}"
+
+
+# Substrings that mark an env key as holding a secret whose value must be masked
+# before it is shown to a human or returned over the API.
+_SECRET_HINTS = ("TOKEN", "KEY", "SECRET", "PASSWORD")
+
+
+def is_secret_key(key: str) -> bool:
+    """True if ``key`` looks like it holds a credential (masked on display)."""
+    upper = key.upper()
+    return any(hint in upper for hint in _SECRET_HINTS)
+
+
+def display_value(key: str, value: str, *, reveal: bool = False) -> str:
+    """Return ``value`` for display: masked when it looks secret, else verbatim.
+
+    ``reveal=True`` returns the raw value (the CLI ``--reveal`` path); the HTTP
+    API never passes it, so secret-looking values are always masked there.
+    """
+    if reveal or not value or not is_secret_key(key):
+        return value
+    return mask(value)