mad-cli 0.4.0__py3-none-any.whl

mad_cli/core/usecases/service.py

@@ -0,0 +1,269 @@
+"""Service-mode use cases: the API token, the dedicated server venv and the
+systemd unit / launchd plist rendering.
+
+The base CLI is a two-dependency package, so ``mad serve`` / ``mad service`` must
+not assume the ``server`` extra is importable. When it is not, ``mad service
+install`` bootstraps a dedicated virtualenv under ``config_root()/server-venv`` and
+installs ``mad-cli[server]`` into it (pinned to the running CLI's version, or from
+a local wheel via ``--wheel``); the rendered unit/plist then points ``ExecStart``
+at ``<venv>/bin/mad serve``. When the extra *is* importable, the current
+interpreter's ``mad`` is used and no venv is created.
+
+Everything here is framework-free (no typer / rich / fastapi). Activating the unit
+(``systemctl`` / ``launchctl``) is the caller's business; this module only renders
+files and provisions the runtime.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import secrets
+import shlex
+import string
+import subprocess
+import sys
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from xml.sax.saxutils import escape as xml_escape
+
+from mad_cli import __version__
+from mad_cli.core.paths import config_root
+from mad_cli.core.usecases.errors import PreconditionError
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 7373
+LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
+
+LAUNCHD_LABEL = "com.mad-core.mad-cli"
+SYSTEMD_UNIT_NAME = "mad-cli.service"
+PLIST_NAME = f"{LAUNCHD_LABEL}.plist"
+
+_SERVER_MODULES = ("fastapi", "uvicorn")
+
+
+# ── API token ────────────────────────────────────────────────────────────────
+def api_token_path() -> Path:
+    """Path of the bearer token file (``config_root()/api-token``)."""
+    return config_root() / "api-token"
+
+
+def read_api_token() -> str | None:
+    """Return the stored bearer token, or ``None`` when it does not exist."""
+    path = api_token_path()
+    if not path.is_file():
+        return None
+    token = path.read_text(encoding="utf-8").strip()
+    return token or None
+
+
+def ensure_api_token() -> str:
+    """Return the bearer token, generating a fresh 0600 one on first use."""
+    existing = read_api_token()
+    if existing is not None:
+        return existing
+    token = secrets.token_urlsafe(32)
+    path = api_token_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(token + "\n", encoding="utf-8")
+    path.chmod(0o600)
+    return token
+
+
+# ── server-extra detection & the dedicated venv ──────────────────────────────
+def server_deps_available() -> bool:
+    """True when the ``server`` extra (fastapi + uvicorn) is importable here."""
+    return all(importlib.util.find_spec(mod) is not None for mod in _SERVER_MODULES)
+
+
+def server_venv_dir() -> Path:
+    """The dedicated server virtualenv directory (``config_root()/server-venv``)."""
+    return config_root() / "server-venv"
+
+
+def _venv_bin_dir(venv: Path) -> Path:
+    return venv / ("Scripts" if os.name == "nt" else "bin")
+
+
+def server_venv_mad() -> Path:
+    """The ``mad`` console script inside the dedicated server venv."""
+    exe = "mad.exe" if os.name == "nt" else "mad"
+    return _venv_bin_dir(server_venv_dir()) / exe
+
+
+def server_venv_exists() -> bool:
+    """True when the dedicated server venv has a usable ``mad`` binary."""
+    return server_venv_mad().exists()
+
+
+def _run(cmd: list[str]) -> None:
+    """Run ``cmd``; raise :class:`PreconditionError` with captured output on failure."""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except OSError as exc:
+        raise PreconditionError(f"failed to run {' '.join(cmd)}: {exc}") from exc
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        raise PreconditionError(
+            f"`{' '.join(cmd)}` failed (exit {result.returncode})"
+            + (f": {detail}" if detail else "")
+        )
+
+
+def bootstrap_server_venv(*, wheel: Path | None = None) -> Path:
+    """Create ``config_root()/server-venv`` and install ``mad-cli[server]`` into it.
+
+    From ``wheel`` (a local wheel/sdist, extras appended) when given — no network,
+    exact artifact — otherwise ``mad-cli[server]==<running version>`` from PyPI. A
+    PyPI failure raises :class:`PreconditionError` hinting at ``--wheel``.
+    """
+    venv_dir = server_venv_dir()
+    _run([sys.executable, "-m", "venv", str(venv_dir)])
+    pip = str(_venv_bin_dir(venv_dir) / ("pip.exe" if os.name == "nt" else "pip"))
+    target = f"{wheel}[server]" if wheel is not None else f"mad-cli[server]=={__version__}"
+    try:
+        _run([pip, "install", target])
+    except PreconditionError:
+        if wheel is None:
+            raise PreconditionError(
+                "could not install 'mad-cli[server]' from PyPI into the server venv; "
+                "retry with --wheel PATH pointing at a local wheel or sdist"
+            ) from None
+        raise
+    return venv_dir
+
+
+def server_venv_version() -> str | None:
+    """Return the ``mad_cli`` version installed in the server venv, or ``None``."""
+    python = _venv_bin_dir(server_venv_dir()) / ("python.exe" if os.name == "nt" else "python")
+    if not python.exists():
+        return None
+    try:
+        out = subprocess.run(
+            [str(python), "-c", "import mad_cli; print(mad_cli.__version__)"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if out.returncode != 0:
+        return None
+    return (out.stdout or "").strip() or None
+
+
+# ── launcher resolution ──────────────────────────────────────────────────────
+def _mad_launcher() -> list[str]:
+    """Robustly resolve the current interpreter's ``mad`` launcher argv.
+
+    Prefers the console script next to ``sys.executable`` (works inside a venv
+    regardless of ``PATH``), then ``PATH``, falling back to ``python -m mad_cli``.
+    """
+    import shutil
+
+    candidate = Path(sys.executable).with_name("mad.exe" if os.name == "nt" else "mad")
+    if candidate.exists():
+        return [str(candidate)]
+    found = shutil.which("mad")
+    if found:
+        return [found]
+    return [sys.executable, "-m", "mad_cli"]
+
+
+def ensure_server_runtime(*, wheel: Path | None = None) -> tuple[list[str], bool]:
+    """Return ``(mad launcher argv, bootstrapped)`` for a server-capable ``mad``.
+
+    With ``wheel`` given, or when the ``server`` extra is not importable in the
+    current interpreter, a dedicated venv is provisioned and its ``mad`` is
+    returned; otherwise the current interpreter's ``mad`` is used unchanged.
+    """
+    if wheel is None and server_deps_available():
+        return _mad_launcher(), False
+    bootstrap_server_venv(wheel=wheel)
+    return [str(server_venv_mad())], True
+
+
+def serve_argv(launcher: list[str], host: str, port: int) -> list[str]:
+    """Build the ``mad serve`` argv from a launcher and bind address."""
+    return [*launcher, "serve", "--host", host, "--port", str(port)]
+
+
+def is_loopback(host: str) -> bool:
+    """True when ``host`` binds only the loopback interface."""
+    return host in LOOPBACK_HOSTS
+
+
+# ── unit / plist rendering ───────────────────────────────────────────────────
+def _load_template(name: str) -> string.Template:
+    text = resources.files("mad_cli.templates").joinpath(name).read_text(encoding="utf-8")
+    return string.Template(text)
+
+
+def render_systemd_unit(*, exec_args: list[str], config_dir: Path) -> str:
+    """Render the systemd **user** unit. ``ExecStart`` is a single command line."""
+    return _load_template("mad-cli.service.tmpl").substitute(
+        exec_start=shlex.join(exec_args),
+        config_dir=str(config_dir),
+    )
+
+
+def render_launchd_plist(*, exec_args: list[str], config_dir: Path, log_path: Path) -> str:
+    """Render the launchd LaunchAgent plist (``ProgramArguments`` as a string array)."""
+    program_arguments = "\n".join(
+        f"        <string>{xml_escape(arg)}</string>" for arg in exec_args
+    )
+    return _load_template(f"{PLIST_NAME}.tmpl").substitute(
+        label=LAUNCHD_LABEL,
+        program_arguments=program_arguments,
+        config_dir=str(config_dir),
+        log_path=str(log_path),
+    )
+
+
+def systemd_unit_path() -> Path:
+    """Default install path of the systemd user unit."""
+    return Path.home() / ".config" / "systemd" / "user" / SYSTEMD_UNIT_NAME
+
+
+def launchd_plist_path() -> Path:
+    """Default install path of the launchd LaunchAgent plist."""
+    return Path.home() / "Library" / "LaunchAgents" / PLIST_NAME
+
+
+def default_log_path() -> Path:
+    """Default log file for the launchd service."""
+    return config_root() / "mad-cli.serve.log"
+
+
+@dataclass(frozen=True)
+class RenderedService:
+    platform: str  # "linux" | "darwin"
+    default_path: Path
+    content: str
+    exec_args: list[str]
+
+
+def render_service(
+    *,
+    platform: str,
+    exec_args: list[str],
+    config_dir: Path,
+) -> RenderedService:
+    """Render the platform's service file and report its default install path.
+
+    Raises :class:`PreconditionError` on an unsupported platform (only Linux
+    systemd-user and macOS launchd are supported).
+    """
+    if platform == "linux":
+        content = render_systemd_unit(exec_args=exec_args, config_dir=config_dir)
+        return RenderedService("linux", systemd_unit_path(), content, exec_args)
+    if platform == "darwin":
+        content = render_launchd_plist(
+            exec_args=exec_args, config_dir=config_dir, log_path=default_log_path()
+        )
+        return RenderedService("darwin", launchd_plist_path(), content, exec_args)
+    raise PreconditionError(
+        f"unsupported platform {platform!r}: `mad service` supports Linux (systemd) and macOS "
+        "(launchd) only. Use `mad serve` to run in the foreground."
+    )

mad_cli/core/usecases/versions.py

@@ -0,0 +1,126 @@
+"""Version-reporting and update use cases.
+
+``versions`` reports, per instance, the pinned / installed / latest-on-PyPI
+versions and whether an update is available. ``update`` re-pins ``MAD_VERSION``
+and rebuilds from scratch (synchronous in the MVP). Shared by ``mad versions`` /
+``mad update`` and the ``/v1/instances/{name}/versions`` + ``/update`` routes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mad_cli.core import pypi
+from mad_cli.core.compose import ComposeError, ComposeRunner
+from mad_cli.core.instance import Instance, InstanceNotFoundError, discover_instances, get_instance
+from mad_cli.core.templates import EDGE_PACKAGE
+from mad_cli.core.usecases.errors import NotFoundError
+
+NOT_RUNNING = "not running"
+UNKNOWN = "?"
+
+
+def _edge_package(instance: Instance) -> str:
+    """The PyPI package to check: ``MAD_EDGE_PACKAGE`` from the .env, else default."""
+    return instance.env.get("MAD_EDGE_PACKAGE") or EDGE_PACKAGE
+
+
+def _installed_version(instance: Instance) -> str:
+    """Version reported by ``mad`` inside the container, or ``"not running"``."""
+    try:
+        out = ComposeRunner(instance).exec(["python", "-c", "import mad; print(mad.__version__)"])
+    except ComposeError:
+        return NOT_RUNNING
+    return out.strip() or NOT_RUNNING
+
+
+def _version_tuple(version: str) -> tuple[int, ...]:
+    """Best-effort ordering tuple: each dotted segment's leading digit run."""
+    parts: list[int] = []
+    for chunk in version.split("."):
+        digits = ""
+        for char in chunk:
+            if char.isdigit():
+                digits += char
+            else:
+                break
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)
+
+
+def _update_status(installed: str, latest: str | None) -> str:
+    if latest is None or installed in (NOT_RUNNING, UNKNOWN):
+        return UNKNOWN
+    if _version_tuple(installed) >= _version_tuple(latest):
+        return "up to date"
+    return "update available"
+
+
+@dataclass(frozen=True)
+class VersionRow:
+    name: str
+    legacy: bool
+    pinned: str  # the pin, or "latest"
+    installed: str
+    latest: str  # latest on PyPI, or "?"
+    update: str  # up to date / update available / ?
+
+
+def versions(name: str | None) -> list[VersionRow]:
+    """Report version state for ``name`` (or every instance when ``None``).
+
+    Raises :class:`NotFoundError` for a named instance that does not exist; an
+    empty list means no instances are configured.
+    """
+    if name is not None:
+        try:
+            targets = [get_instance(name)]
+        except InstanceNotFoundError as exc:
+            raise NotFoundError(f"instance {name!r} not found") from exc
+    else:
+        targets = discover_instances()
+
+    rows: list[VersionRow] = []
+    latest_cache: dict[str, str | None] = {}
+    for inst in targets:
+        installed = _installed_version(inst)
+        package = _edge_package(inst)
+        if package not in latest_cache:
+            latest_cache[package] = pypi.latest_version(package)
+        latest = latest_cache[package]
+        rows.append(
+            VersionRow(
+                name=inst.name,
+                legacy=bool(getattr(inst, "legacy", False)),
+                pinned=inst.version_pin or "latest",
+                installed=installed,
+                latest=latest if latest is not None else UNKNOWN,
+                update=_update_status(installed, latest),
+            )
+        )
+    return rows
+
+
+@dataclass(frozen=True)
+class UpdateResult:
+    instance: Instance
+    target: str  # the pin applied, or "latest"
+    healthy: bool
+
+
+def update(instance: Instance, version: str | None) -> UpdateResult:
+    """Re-pin ``MAD_VERSION`` and rebuild the instance from scratch.
+
+    The returned ``healthy`` flag lets the adapter decide how to signal a
+    not-yet-healthy rebuild (the CLI exits non-zero; the API reports it in the
+    body).
+    """
+    pin = version or ""
+    instance.env.set("MAD_VERSION", pin)
+    instance.env.save(instance.env_file)
+
+    runner = ComposeRunner(instance)
+    runner.build(no_cache=True)
+    runner.up()
+    healthy = runner.wait_healthy()
+    return UpdateResult(instance=instance, target=pin or "latest", healthy=healthy)

mad_cli/server/__init__.py

@@ -0,0 +1,13 @@
+"""The optional local HTTP API (the ``server`` extra).
+
+Nothing here is imported by the base CLI (``mad_cli.app``); it is reached only via
+``mad serve`` behind an import guard, so ``pip install mad-cli`` never pulls in
+FastAPI/uvicorn. The routes are thin adapters over :mod:`mad_cli.core.usecases`,
+exactly like the Typer commands, so the CLI and the API can never drift.
+
+See :func:`mad_cli.server.app.create_app` for the FastAPI factory.
+"""
+
+from mad_cli.server.app import create_app
+
+__all__ = ["create_app"]

mad_cli/server/app.py

@@ -0,0 +1,260 @@
+"""FastAPI application factory for the v1 local API.
+
+Every ``/v1`` route is a thin adapter over :mod:`mad_cli.core.usecases` — the same
+functions the Typer commands call — guarded by the bearer-token dependency. The
+use-case error vocabulary is mapped to HTTP status codes by a single exception
+handler, so the routes stay declarative.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from mad_cli import __version__
+from mad_cli.core.envfile import EnvFile
+from mad_cli.core.instance import Instance, InstanceNotFoundError, get_instance
+from mad_cli.core.templates import EDGE_PACKAGE
+from mad_cli.core.usecases import adopt as uc_adopt
+from mad_cli.core.usecases import configvals as uc_config
+from mad_cli.core.usecases import install as uc_install
+from mad_cli.core.usecases import instances as uc_instances
+from mad_cli.core.usecases import keys as uc_keys
+from mad_cli.core.usecases import lifecycle as uc_lifecycle
+from mad_cli.core.usecases import versions as uc_versions
+from mad_cli.core.usecases.errors import NotFoundError, UseCaseError, http_status_for
+from mad_cli.server import models as m
+from mad_cli.server.auth import require_token
+
+
+def _host_id(getter_name: str) -> int:
+    getter = getattr(os, getter_name, None)
+    return getter() if getter is not None else 1000
+
+
+def _instance(name: str) -> Instance:
+    """Resolve a path ``{name}`` to an :class:`Instance` or raise 404 via the handler."""
+    try:
+        return get_instance(name)
+    except InstanceNotFoundError:
+        raise NotFoundError(f"instance {name!r} not found") from None
+
+
+def _build_router() -> APIRouter:
+    router = APIRouter(prefix="/v1", dependencies=[Depends(require_token)])
+
+    # ── instances ────────────────────────────────────────────────────────────
+    @router.get("/instances", response_model=list[m.InstanceSummaryModel], tags=["instances"])
+    def list_instances() -> list[m.InstanceSummaryModel]:
+        return [
+            m.InstanceSummaryModel(
+                name=row.name,
+                legacy=row.legacy,
+                port=row.port,
+                state=row.state,
+                health=row.health,
+                version=row.version,
+            )
+            for row in uc_instances.list_instances()
+        ]
+
+    @router.post(
+        "/instances",
+        response_model=m.InstallResponse,
+        status_code=201,
+        tags=["instances"],
+    )
+    def install_instance(req: m.InstallRequest) -> m.InstallResponse:
+        scratch = EnvFile.empty()
+        for ident, value in req.extra_keys.items():
+            uc_install.apply_extra_key(scratch, ident, value)
+        extra_env = {var: scratch.get(var) or "" for var in scratch.keys()}  # noqa: SIM118
+        params = uc_install.InstallParams(
+            name=req.name,
+            port=req.port,
+            data_path=Path(req.data_path),
+            timeout_s=req.timeout_s,
+            github_token=req.github_token,
+            puid=_host_id("getuid"),
+            pgid=_host_id("getgid"),
+            git_name=req.git_name,
+            git_email=req.git_email,
+            claude_token=req.claude_token,
+            anthropic_api_key=req.anthropic_api_key,
+            extra_env=extra_env,
+            retention_days=req.retention_days,
+            mcp_allowed_hosts=req.mcp_allowed_hosts,
+            edge_package=req.edge_package or EDGE_PACKAGE,
+            edge_version=req.edge_version,
+            start=req.start,
+        )
+        result = uc_install.install(params)
+        return m.InstallResponse(
+            name=result.name,
+            config_dir=str(result.config_dir),
+            data_dir=str(result.data_dir),
+            port=result.port,
+            started=result.started,
+            healthy=result.healthy,
+            url=result.url,
+        )
+
+    @router.get("/instances/{name}", response_model=m.InstanceInfoModel, tags=["instances"])
+    def instance_info(name: str) -> m.InstanceInfoModel:
+        info = uc_instances.instance_info(name)
+        return m.InstanceInfoModel(
+            name=info.name,
+            legacy=info.legacy,
+            config_dir=str(info.config_dir),
+            compose_file=str(info.compose_file),
+            data_path=str(info.data_path) if info.data_path else None,
+            port=info.port,
+            version=info.version,
+            env=[m.EnvItemModel(key=i.key, value=i.display(), secret=i.secret) for i in info.env],
+        )
+
+    # ── lifecycle ─────────────────────────────────────────────────────────────
+    @router.post("/instances/{name}/start", response_model=m.StartResponse, tags=["lifecycle"])
+    def start(name: str) -> m.StartResponse:
+        inst = _instance(name)
+        res = uc_lifecycle.start(inst)
+        return m.StartResponse(name=inst.name, healthy=res.healthy, url=res.url)
+
+    @router.post("/instances/{name}/stop", response_model=m.ActionResponse, tags=["lifecycle"])
+    def stop(name: str) -> m.ActionResponse:
+        inst = _instance(name)
+        uc_lifecycle.stop(inst)
+        return m.ActionResponse(name=inst.name, action="stop")
+
+    @router.post("/instances/{name}/restart", response_model=m.ActionResponse, tags=["lifecycle"])
+    def restart(name: str) -> m.ActionResponse:
+        inst = _instance(name)
+        uc_lifecycle.restart(inst)
+        return m.ActionResponse(name=inst.name, action="restart")
+
+    @router.get("/instances/{name}/status", response_model=m.StatusResponse, tags=["lifecycle"])
+    def status(name: str) -> m.StatusResponse:
+        inst = _instance(name)
+        res = uc_lifecycle.status(inst)
+        return m.StatusResponse(name=inst.name, health=res.health, url=res.url, ps=res.ps_text)
+
+    # ── config ────────────────────────────────────────────────────────────────
+    @router.get("/instances/{name}/config", response_model=list[m.EnvItemModel], tags=["config"])
+    def get_config(name: str) -> list[m.EnvItemModel]:
+        inst = _instance(name)
+        return [
+            m.EnvItemModel(key=i.key, value=i.display(), secret=i.secret)
+            for i in uc_config.list_config(inst)
+        ]
+
+    @router.put(
+        "/instances/{name}/config/{key}", response_model=m.SetConfigResponse, tags=["config"]
+    )
+    def set_config(name: str, key: str, body: m.SetConfigRequest) -> m.SetConfigResponse:
+        inst = _instance(name)
+        item, compose_baked = uc_config.set_config(inst, key, body.value)
+        return m.SetConfigResponse(
+            key=item.key, value=item.display(), secret=item.secret, compose_baked=compose_baked
+        )
+
+    @router.delete(
+        "/instances/{name}/config/{key}", response_model=m.ActionResponse, tags=["config"]
+    )
+    def unset_config(name: str, key: str) -> m.ActionResponse:
+        inst = _instance(name)
+        existed = uc_config.unset_config(inst, key)
+        if not existed:
+            raise NotFoundError(f"{key} is not set on {inst.name}")
+        return m.ActionResponse(name=inst.name, action=f"unset {key}")
+
+    # ── keys ──────────────────────────────────────────────────────────────────
+    @router.get("/instances/{name}/keys", response_model=m.KeysResponse, tags=["keys"])
+    def list_keys(name: str) -> m.KeysResponse:
+        inst = _instance(name)
+        view = uc_keys.list_keys(inst)
+        return m.KeysResponse(
+            builtins=[
+                m.BuiltinKeyModel(
+                    id=s.id, env_vars=list(s.env_vars), is_set=s.is_set, value=s.masked
+                )
+                for s in view.builtins
+            ],
+            custom=[m.CustomSecretModel(key=c.key, value=c.masked) for c in view.custom],
+        )
+
+    @router.put("/instances/{name}/keys/{key_id}", response_model=m.SetKeyResponse, tags=["keys"])
+    def set_key(name: str, key_id: str, body: m.SetKeyRequest) -> m.SetKeyResponse:
+        inst = _instance(name)
+        res = uc_keys.set_key(inst, key_id, body.value)
+        return m.SetKeyResponse(
+            id=res.id,
+            env_vars=list(res.env_vars),
+            builtin=res.builtin,
+            credentials_written=res.credentials_path is not None,
+        )
+
+    @router.delete(
+        "/instances/{name}/keys/{key_id}", response_model=m.ActionResponse, tags=["keys"]
+    )
+    def remove_key(name: str, key_id: str) -> m.ActionResponse:
+        inst = _instance(name)
+        res = uc_keys.remove_key(inst, key_id)
+        if not res.existed:
+            raise NotFoundError(f"{res.id} is not set on {inst.name}")
+        return m.ActionResponse(name=inst.name, action=f"remove {res.id}")
+
+    # ── versions ──────────────────────────────────────────────────────────────
+    @router.get("/instances/{name}/versions", response_model=m.VersionRowModel, tags=["versions"])
+    def versions(name: str) -> m.VersionRowModel:
+        rows = uc_versions.versions(name)
+        row = rows[0]
+        return m.VersionRowModel(
+            name=row.name,
+            legacy=row.legacy,
+            pinned=row.pinned,
+            installed=row.installed,
+            latest=row.latest,
+            update=row.update,
+        )
+
+    @router.post("/instances/{name}/update", response_model=m.UpdateResponse, tags=["versions"])
+    def update(name: str, body: m.UpdateRequest) -> m.UpdateResponse:
+        inst = _instance(name)
+        res = uc_versions.update(inst, body.version)
+        return m.UpdateResponse(name=inst.name, target=res.target, healthy=res.healthy)
+
+    # ── adopt ─────────────────────────────────────────────────────────────────
+    @router.post("/adopt", response_model=m.AdoptResponse, tags=["adopt"])
+    def adopt() -> m.AdoptResponse:
+        plan = uc_adopt.plan_adopt()
+        if plan is None:
+            return m.AdoptResponse(adopted=False)
+        uc_adopt.apply_adopt(plan)
+        return m.AdoptResponse(
+            adopted=True, name=plan.name, target=str(plan.target), moved=plan.movable
+        )
+
+    return router
+
+
+def create_app() -> FastAPI:
+    """Build the FastAPI application (the OpenAPI schema is generated from it)."""
+    app = FastAPI(
+        title="mad-cli local API",
+        version=__version__,
+        summary="Operator API mirroring the mad CLI (instances, lifecycle, config, keys).",
+    )
+
+    @app.exception_handler(UseCaseError)
+    async def _handle_usecase_error(request: Request, exc: UseCaseError) -> JSONResponse:
+        return JSONResponse(status_code=http_status_for(exc), content={"detail": str(exc)})
+
+    @app.get("/health", response_model=m.HealthResponse, tags=["meta"])
+    def health() -> m.HealthResponse:
+        return m.HealthResponse(status="ok", version=__version__)
+
+    app.include_router(_build_router())
+    return app