mad-cli 0.4.0__py3-none-any.whl

mad_cli/core/paths.py

@@ -0,0 +1,40 @@
+"""Config-directory resolution for mad-cli.
+
+All paths derive from :func:`config_root`, which honours the ``MAD_CLI_CONFIG_DIR``
+environment override and otherwise falls back to ``~/.config/mad``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+
+def config_root() -> Path:
+    """Return the mad-cli config root.
+
+    ``$MAD_CLI_CONFIG_DIR`` overrides the default ``~/.config/mad``.
+    """
+    override = os.environ.get("MAD_CLI_CONFIG_DIR")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".config" / "mad"
+
+
+def instances_root() -> Path:
+    """Return the directory that holds one sub-directory per instance."""
+    return config_root() / "instances"
+
+
+def instance_dir(name: str) -> Path:
+    """Return the config directory for ``name``.
+
+    The name must match ``[a-z0-9][a-z0-9-]*`` so it is safe to use as a
+    directory name, a Docker Compose project suffix and a container name.
+    """
+    if not _NAME_RE.match(name):
+        raise ValueError(f"invalid instance name {name!r}: must match [a-z0-9][a-z0-9-]*")
+    return instances_root() / name

mad_cli/core/profiles.py

@@ -0,0 +1,93 @@
+"""Named environment profiles — reusable sets of ``.env`` values.
+
+A *profile* is a named, reusable set of environment variables an operator can
+stamp onto instances. It carries **credentials and tuning**, never an instance's
+identity: the keys that name one specific instance (its port, data path, name,
+uid/gid and version pin — :data:`IDENTITY_KEYS`) are deliberately excluded, so a
+profile can be applied across many instances without collision.
+
+Profiles are stored one file per profile at ``config_root()/profiles/<name>.env``
+in the same :class:`~mad_cli.core.envfile.EnvFile` format as an instance's
+``.env``, ``chmod 600`` because they may hold secrets. The name follows the same
+rule as an instance name (``[a-z0-9][a-z0-9-]*``) so it is safe as a filename.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from mad_cli.core.envfile import EnvFile
+from mad_cli.core.paths import config_root
+
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+# Instance-identity keys a profile must never carry: each names one specific
+# instance, not the reusable credentials/tuning a profile is for. Excluded when
+# seeding a profile from an instance (`mad profiles create --from-instance`).
+IDENTITY_KEYS: tuple[str, ...] = (
+    "MAD_INSTANCE",
+    "MAD_HOST_PORT",
+    "PUID",
+    "PGID",
+    "MAD_DATA_PATH",
+    "MAD_VERSION",
+)
+
+
+class ProfileNotFoundError(Exception):
+    """Raised when a named profile does not exist under the config root."""
+
+
+def profiles_root() -> Path:
+    """Return the directory that holds one ``<name>.env`` file per profile."""
+    return config_root() / "profiles"
+
+
+def _validate_name(name: str) -> str:
+    """Return ``name`` if it is a valid profile name, else raise ``ValueError``."""
+    if not _NAME_RE.match(name):
+        raise ValueError(f"invalid profile name {name!r}: must match [a-z0-9][a-z0-9-]*")
+    return name
+
+
+def profile_path(name: str) -> Path:
+    """Return the storage path for profile ``name`` (validates the name)."""
+    return profiles_root() / f"{_validate_name(name)}.env"
+
+
+def list_profiles() -> list[str]:
+    """Return every stored profile name, sorted (empty when none exist)."""
+    root = profiles_root()
+    if not root.is_dir():
+        return []
+    return sorted(p.stem for p in root.iterdir() if p.is_file() and p.suffix == ".env")
+
+
+def load_profile(name: str) -> EnvFile:
+    """Load profile ``name`` or raise :class:`ProfileNotFoundError`."""
+    path = profile_path(name)
+    if not path.is_file():
+        raise ProfileNotFoundError(name)
+    return EnvFile.load(path)
+
+
+def save_profile(name: str, env: EnvFile) -> Path:
+    """Write ``env`` to profile ``name`` (``chmod 600``); return its path.
+
+    The ``profiles/`` directory is created if needed. The file may hold secrets,
+    so it is written with owner-only permissions.
+    """
+    path = profile_path(name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    env.save(path)
+    path.chmod(0o600)
+    return path
+
+
+def delete_profile(name: str) -> None:
+    """Delete profile ``name`` or raise :class:`ProfileNotFoundError`."""
+    path = profile_path(name)
+    if not path.is_file():
+        raise ProfileNotFoundError(name)
+    path.unlink()

mad_cli/core/pypi.py

@@ -0,0 +1,29 @@
+"""Latest-version lookup via the PyPI JSON API (urllib, stdlib only)."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+
+_PYPI_JSON = "https://pypi.org/pypi/{package}/json"
+
+
+def latest_version(package: str, timeout_s: float = 5.0) -> str | None:
+    """Return the latest published version of ``package`` on PyPI, or ``None``.
+
+    Any failure — unknown package (404), network error, timeout or malformed
+    payload — yields ``None`` rather than raising, so callers can degrade
+    gracefully when offline.
+    """
+    url = _PYPI_JSON.format(package=package)
+    try:
+        with urllib.request.urlopen(url, timeout=timeout_s) as response:
+            raw = response.read()
+        data = json.loads(raw)
+    except (OSError, ValueError):
+        return None
+    info = data.get("info") if isinstance(data, dict) else None
+    if not isinstance(info, dict):
+        return None
+    version = info.get("version")
+    return version if isinstance(version, str) else None

mad_cli/core/templates.py

@@ -0,0 +1,91 @@
+"""Instance file rendering (Dockerfile / compose.yml / entrypoint.sh / .env).
+
+Ports the ``write_dockerfile`` / ``write_compose`` / ``write_entrypoint`` heredocs
+from the reference ``configure.sh`` to packaged ``string.Template`` files. The one
+deliberate change: the pip package is parameterised via
+:attr:`RenderContext.edge_package` (default ``"mad-edge"``), and because
+``string.Template`` has no conditionals the container's start binary is resolved
+here in Python — ``mad-edge`` normally, but ``mad`` for the ``mad-bros`` package,
+which still installs the ``mad`` console script.
+"""
+
+from __future__ import annotations
+
+import string
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+from mad_cli.core.envfile import EnvFile
+
+EDGE_PACKAGE: str = "mad-edge"
+
+# Rendered output name -> packaged template name.
+_TEMPLATES: dict[str, str] = {
+    "Dockerfile": "Dockerfile.tmpl",
+    "compose.yml": "compose.yml.tmpl",
+    "entrypoint.sh": "entrypoint.sh.tmpl",
+}
+
+
+@dataclass
+class RenderContext:
+    instance: str
+    host_port: int
+    data_path: Path
+    timeout_s: int
+    puid: int
+    pgid: int
+    edge_package: str = EDGE_PACKAGE
+    edge_version: str = ""  # '' = latest
+
+
+def _entrypoint_binary(edge_package: str) -> str:
+    """Console script that starts the server for ``edge_package``.
+
+    ``mad-bros`` ships its server as the ``mad`` script; every other package
+    (``mad-edge`` and forks) exposes ``mad-edge``.
+    """
+    return "mad" if edge_package == "mad-bros" else "mad-edge"
+
+
+def _load_template(template_name: str) -> string.Template:
+    text = resources.files("mad_cli.templates").joinpath(template_name).read_text(encoding="utf-8")
+    return string.Template(text)
+
+
+def render_all(ctx: RenderContext) -> dict[str, str]:
+    """Render the three instance files from the packaged templates."""
+    version_spec = f"=={ctx.edge_version}" if ctx.edge_version else ""
+    mapping = {
+        "instance": ctx.instance,
+        "host_port": str(ctx.host_port),
+        "data_path": str(ctx.data_path),
+        "timeout_s": str(ctx.timeout_s),
+        "puid": str(ctx.puid),
+        "pgid": str(ctx.pgid),
+        "edge_package": ctx.edge_package,
+        "edge_version_spec": version_spec,
+        "image_tag": ctx.edge_version or "latest",
+        "edge_entrypoint": _entrypoint_binary(ctx.edge_package),
+    }
+    return {
+        out_name: _load_template(tmpl_name).substitute(mapping)
+        for out_name, tmpl_name in _TEMPLATES.items()
+    }
+
+
+def write_instance_files(target: Path, ctx: RenderContext, env: EnvFile) -> None:
+    """Render into ``target`` and save ``env`` as ``target/.env``.
+
+    ``entrypoint.sh`` is made executable (mode ``0o755``); the ``.env`` is written
+    through :meth:`EnvFile.save` so its comments and ordering survive.
+    """
+    target.mkdir(parents=True, exist_ok=True)
+    rendered = render_all(ctx)
+    (target / "Dockerfile").write_text(rendered["Dockerfile"], encoding="utf-8")
+    (target / "compose.yml").write_text(rendered["compose.yml"], encoding="utf-8")
+    entrypoint = target / "entrypoint.sh"
+    entrypoint.write_text(rendered["entrypoint.sh"], encoding="utf-8")
+    entrypoint.chmod(0o755)
+    env.save(target / ".env")

mad_cli/core/usecases/__init__.py

@@ -0,0 +1,11 @@
+"""Framework-free use-case layer — the shared core of the CLI and the HTTP API.
+
+Every operator capability lives here as a plain function that takes primitive
+inputs, drives :mod:`mad_cli.core`, and returns dataclasses (never ``typer``,
+``rich`` or ``fastapi`` objects). The Typer commands and the FastAPI routes are
+thin adapters over these functions, so the two surfaces can never drift.
+
+Expected, user-facing failures are raised as :class:`~mad_cli.core.usecases.errors.UseCaseError`
+subclasses; each adapter maps them to its own idiom (``typer.Exit(1)`` / an HTTP
+status code).
+"""

mad_cli/core/usecases/adopt.py

@@ -0,0 +1,55 @@
+"""Adopt use case: migrate the legacy single-instance layout into ``instances/``.
+
+The old layout kept ``compose.yml`` / ``.env`` / ``Dockerfile`` / ``entrypoint.sh``
+directly under the config root; the modern layout stores them per instance. Only
+those config files move — the instance's data (``MAD_DATA_PATH``) stays put.
+
+Planning and applying are split so the CLI can show the plan and ask for
+confirmation before anything moves; the API applies directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from mad_cli.core.instance import discover_instances
+from mad_cli.core.paths import instance_dir
+from mad_cli.core.usecases.errors import ValidationError
+
+# Config files that make up a legacy single-instance layout and move together.
+ADOPT_FILES = ("compose.yml", ".env", "Dockerfile", "entrypoint.sh")
+
+
+@dataclass(frozen=True)
+class AdoptPlan:
+    name: str
+    source: Path
+    target: Path
+    movable: list[str]
+
+
+def plan_adopt() -> AdoptPlan | None:
+    """Return the pending adoption, or ``None`` when there is no legacy layout.
+
+    Raises :class:`ValidationError` if the legacy instance name cannot be used as
+    a target directory.
+    """
+    legacy = next((i for i in discover_instances() if getattr(i, "legacy", False)), None)
+    if legacy is None:
+        return None
+    source = legacy.config_dir
+    try:
+        target = instance_dir(legacy.name)
+    except ValueError as exc:
+        raise ValidationError(f"cannot adopt {legacy.name!r}: {exc}") from exc
+    movable = [name for name in ADOPT_FILES if (source / name).exists()]
+    return AdoptPlan(name=legacy.name, source=source, target=target, movable=movable)
+
+
+def apply_adopt(plan: AdoptPlan) -> AdoptPlan:
+    """Move the planned config files into ``instances/<name>/``; return the plan."""
+    plan.target.mkdir(parents=True, exist_ok=True)
+    for name in plan.movable:
+        (plan.source / name).rename(plan.target / name)
+    return plan

mad_cli/core/usecases/configvals.py

@@ -0,0 +1,94 @@
+"""``.env`` editing use cases: get / set / unset with validation and masking.
+
+The general-purpose ``.env`` editor behind ``mad config`` and the
+``/v1/instances/{name}/config`` routes. Each takes an already-resolved
+:class:`Instance`. A handful of known keys are validated on write; compose-baked
+keys (host port / data bind) still write to ``.env`` but the adapter warns that a
+regenerate is required. Secret-looking values are masked on read via
+:class:`~mad_cli.core.usecases.instances.EnvItem`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from mad_cli.core.instance import Instance
+from mad_cli.core.keyspec import is_secret_key
+from mad_cli.core.usecases.errors import NotFoundError, ValidationError
+from mad_cli.core.usecases.instances import EnvItem
+
+# Keys whose value was rendered into compose.yml at install time.
+COMPOSE_KEYS: tuple[str, ...] = ("MAD_HOST_PORT", "MAD_DATA_PATH")
+
+
+def _validate_port(value: str) -> str:
+    try:
+        port = int(value)
+    except ValueError:
+        raise ValidationError(f"invalid MAD_HOST_PORT {value!r}: must be an integer") from None
+    if not 1 <= port <= 65535:
+        raise ValidationError(f"invalid MAD_HOST_PORT {value!r}: must be between 1 and 65535")
+    return str(port)
+
+
+def _validate_timeout(value: str) -> str:
+    try:
+        seconds = int(value)
+    except ValueError:
+        raise ValidationError(
+            f"invalid MAD_AGENT_TIMEOUT_S {value!r}: must be an integer"
+        ) from None
+    if seconds <= 0:
+        raise ValidationError(f"invalid MAD_AGENT_TIMEOUT_S {value!r}: must be a positive integer")
+    return str(seconds)
+
+
+_VALIDATORS: dict[str, Callable[[str], str]] = {
+    "MAD_HOST_PORT": _validate_port,
+    "MAD_AGENT_TIMEOUT_S": _validate_timeout,
+}
+
+
+def _item(key: str, value: str) -> EnvItem:
+    return EnvItem(key=key, value=value, secret=is_secret_key(key))
+
+
+def list_config(instance: Instance) -> list[EnvItem]:
+    """Return all ``.env`` items (values masked on display)."""
+    env = instance.env
+    return [_item(key, env.get(key) or "") for key in env.keys()]  # noqa: SIM118
+
+
+def get_config(instance: Instance, key: str) -> EnvItem:
+    """Return one ``.env`` item. Raises :class:`NotFoundError` when unset."""
+    value = instance.env.get(key)
+    if value is None:
+        raise NotFoundError(f"{key} is not set on {instance.name}")
+    return _item(key, value)
+
+
+def set_config(instance: Instance, key: str, value: str) -> tuple[EnvItem, bool]:
+    """Validate and write a ``.env`` value.
+
+    Returns ``(item, compose_baked)`` where ``compose_baked`` is True for keys
+    rendered into compose.yml at install time. Raises :class:`ValidationError` for
+    a bad known value.
+    """
+    validator = _VALIDATORS.get(key)
+    if validator is not None:
+        value = validator(value)
+    instance.env.set(key, value)
+    instance.env.save()
+    return _item(key, value), key in COMPOSE_KEYS
+
+
+def unset_config(instance: Instance, key: str) -> bool:
+    """Remove ``key`` from the instance's ``.env``.
+
+    Returns whether the key existed; False is a no-op the adapter reports.
+    """
+    if instance.env.get(key) is None:
+        return False
+    instance.env.unset(key)
+    instance.env.save()
+    return True

mad_cli/core/usecases/errors.py

@@ -0,0 +1,57 @@
+"""Expected, user-facing failures raised by the use-case layer.
+
+These are the vocabulary the adapters translate. The CLI turns any of them into
+an ``error(...)`` line plus ``typer.Exit(1)``; the HTTP API maps each subclass to
+a status code (see :data:`HTTP_STATUS`). They carry a human-readable message and
+never wrap a stack trace the operator should not see.
+"""
+
+from __future__ import annotations
+
+
+class UseCaseError(Exception):
+    """Base class for expected failures surfaced to the operator."""
+
+
+class ValidationError(UseCaseError, ValueError):
+    """An input was malformed or out of range (bad port, unknown key id, …).
+
+    Also a :class:`ValueError` so it satisfies the ``ui.prompts.ask`` validator
+    contract (raise ``ValueError`` to re-prompt): the same validators back the
+    interactive prompts and the non-interactive / HTTP paths.
+    """
+
+
+class NotFoundError(UseCaseError):
+    """A referenced instance, key or value does not exist."""
+
+
+class ConflictError(UseCaseError):
+    """The requested state clashes with what already exists (instance exists)."""
+
+
+class AmbiguousInstanceError(UseCaseError):
+    """No instance was named and the target could not be inferred (0 or >1)."""
+
+
+class PreconditionError(UseCaseError):
+    """A precondition is unmet (Docker missing, no data path, health failed)."""
+
+
+# Adapter hint: use-case error -> HTTP status. The CLI ignores this and exits 1.
+HTTP_STATUS: dict[type[UseCaseError], int] = {
+    ValidationError: 400,
+    NotFoundError: 404,
+    ConflictError: 409,
+    AmbiguousInstanceError: 409,
+    PreconditionError: 412,
+}
+
+
+def http_status_for(exc: UseCaseError) -> int:
+    """Return the HTTP status code for ``exc`` (500 if unmapped)."""
+    for cls in type(exc).__mro__:
+        status = HTTP_STATUS.get(cls)
+        if status is not None:
+            return status
+    return 500