mad-cli 0.4.0__py3-none-any.whl

mad_cli/core/usecases/install.py

@@ -0,0 +1,263 @@
+"""Install / reconfigure use case: params -> .env -> files -> dirs -> (start).
+
+The deterministic heart of ``mad install`` and ``POST /v1/instances``. Given a
+fully-resolved :class:`InstallParams` (the CLI does the interactive collection and
+Docker preflight; the API takes them from the request body), it assembles the
+``.env``, renders the instance files, creates the data directories (including
+``sessions/``), writes the Claude credentials file and, unless ``start`` is
+false, builds and starts the container. No prompting, no Docker preflight, no
+presentation — those belong to the adapters.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from mad_cli.core.claude_creds import write_claude_credentials
+from mad_cli.core.compose import ComposeRunner
+from mad_cli.core.envfile import EnvFile
+from mad_cli.core.instance import Instance
+from mad_cli.core.keyspec import BUILTIN_KEYS
+from mad_cli.core.paths import instance_dir
+from mad_cli.core.templates import EDGE_PACKAGE, RenderContext, write_instance_files
+from mad_cli.core.usecases.errors import ValidationError
+
+_NAME_RE = re.compile(r"[a-z0-9][a-z0-9-]*")
+# A custom extra key is written verbatim; it must look like a shell env-var name.
+_CUSTOM_KEY_RE = re.compile(r"[A-Z][A-Z0-9_]*")
+
+
+# ── validators (shared with the CLI's interactive prompts) ───────────────────
+def validate_name(value: str) -> str:
+    value = value.strip()
+    if not _NAME_RE.fullmatch(value):
+        raise ValidationError(
+            f"invalid instance name {value!r}: use lowercase letters, digits and "
+            "hyphens, starting with a letter or digit"
+        )
+    return value
+
+
+def validate_port(value: str) -> str:
+    try:
+        port = int(value)
+    except ValueError:
+        raise ValidationError(f"invalid port {value!r}: must be an integer") from None
+    if not 1 <= port <= 65535:
+        raise ValidationError(f"invalid 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 timeout {value!r}: must be an integer") from None
+    if seconds <= 0:
+        raise ValidationError(f"invalid timeout {value!r}: must be a positive integer")
+    return str(seconds)
+
+
+def validate_retention(value: str) -> str:
+    """A retention: a positive integer number of days, or empty (keep forever)."""
+    value = value.strip()
+    if not value:
+        return ""
+    try:
+        days = int(value)
+    except ValueError:
+        raise ValidationError(
+            f"invalid retention {value!r}: must be a positive integer of days, or empty"
+        ) from None
+    if days < 1:
+        raise ValidationError(
+            f"invalid retention {value!r}: must be >= 1 (or empty to keep forever)"
+        )
+    return str(days)
+
+
+def apply_extra_key(env: EnvFile, ident: str, value: str) -> list[str]:
+    """Write a builtin (fanned out) or custom extra key into ``env``.
+
+    Returns the env vars it touched. Rejects ``claude-oauth`` (it also
+    materialises the credentials file — set it as the dedicated Claude token) and
+    raises :class:`ValidationError` for an unknown id. The message is neutral; the
+    CLI adds its ``--claude-token`` hint before delegating here.
+    """
+    spec = BUILTIN_KEYS.get(ident)
+    if spec is not None:
+        if spec.writes_claude_credentials:
+            raise ValidationError(
+                f"{ident!r} cannot be set as an extra key; provide the Claude token directly."
+            )
+        for var in spec.env_vars:
+            env.set(var, value)
+        return list(spec.env_vars)
+    if _CUSTOM_KEY_RE.fullmatch(ident):
+        env.set(ident, value)
+        return [ident]
+    raise ValidationError(
+        f"unknown key {ident!r}: use a builtin id ({', '.join(BUILTIN_KEYS)}) "
+        "or an env-var name matching [A-Z][A-Z0-9_]*."
+    )
+
+
+@dataclass
+class InstallParams:
+    """Fully-resolved install inputs (post prompting / request parsing)."""
+
+    name: str
+    port: int
+    data_path: Path
+    timeout_s: int
+    github_token: str
+    puid: int
+    pgid: int
+    git_name: str = ""
+    git_email: str = ""
+    claude_token: str = ""
+    anthropic_api_key: str = ""
+    # Extra API keys as a flat {ENV_VAR: value} overlay (already fanned out by the
+    # adapter via :func:`apply_extra_key`); written verbatim after the base keys.
+    extra_env: dict[str, str] = field(default_factory=dict)
+    retention_days: str = ""  # "" = keep forever
+    mcp_allowed_hosts: str = ""  # "" = disabled
+    edge_package: str = EDGE_PACKAGE
+    edge_version: str = ""
+    start: bool = True
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    """Outcome of an install for the adapter to present."""
+
+    name: str
+    config_dir: Path
+    data_dir: Path
+    port: int
+    timeout_s: int
+    env: EnvFile
+    extra_key_vars: list[str]
+    claude_credentials_path: Path | None
+    claude_dir: Path
+    started: bool
+    healthy: bool | None
+    url: str | None
+
+
+def build_env(params: InstallParams) -> tuple[EnvFile, list[str]]:
+    """Assemble the ``.env`` for ``params``; return it and the extra-key vars.
+
+    Split out so it can be unit-tested and reused; validates the extra keys,
+    raising :class:`ValidationError` on a bad entry (before any file is written).
+    """
+    env = EnvFile.empty()
+    env.set("MAD_INSTANCE", params.name)
+    env.set("MAD_HOST_PORT", str(params.port))
+    env.set("MAD_VERSION", params.edge_version)
+    env.set("PUID", str(params.puid))
+    env.set("PGID", str(params.pgid))
+    env.set("MAD_DATA_PATH", str(params.data_path))
+    env.set("GITHUB_TOKEN", params.github_token)
+    env.set("GH_TOKEN", params.github_token)
+    env.set("GIT_AUTHOR_NAME", params.git_name)
+    env.set("GIT_AUTHOR_EMAIL", params.git_email)
+    env.set("GIT_COMMITTER_NAME", params.git_name)
+    env.set("GIT_COMMITTER_EMAIL", params.git_email)
+    env.set("MAD_AGENT_TIMEOUT_S", str(params.timeout_s))
+    env.set("_CLAUDE_OAUTH_TOKEN", params.claude_token)
+    if params.anthropic_api_key:
+        env.set("ANTHROPIC_API_KEY", params.anthropic_api_key)
+
+    extra_vars: list[str] = []
+    for var, value in params.extra_env.items():
+        env.set(var, value)
+        extra_vars.append(var)
+
+    # Session-log retention: a value activates it; otherwise a documented,
+    # inactive reference so the operator knows the knob exists (keep forever).
+    if params.retention_days:
+        env.set("MAD_SESSIONS_RETENTION_DAYS", params.retention_days)
+    else:
+        env.add_comment(
+            "MAD_SESSIONS_RETENTION_DAYS=  # session log retention in days; unset = keep forever"
+        )
+    # MCP DNS-rebinding protection: commented reference when left disabled.
+    if params.mcp_allowed_hosts:
+        env.set("MAD_MCP_ALLOWED_HOSTS", params.mcp_allowed_hosts)
+    else:
+        env.add_comment(
+            "MAD_MCP_ALLOWED_HOSTS=  # comma-separated allowed hosts; unset = protection disabled"
+        )
+    # SSE keep-alive heartbeat is never prompted — leave it as a reference knob.
+    if env.get("MAD_SSE_HEARTBEAT_S") is None:
+        env.add_comment("MAD_SSE_HEARTBEAT_S=  # SSE keep-alive heartbeat in seconds")
+    return env, extra_vars
+
+
+def install(params: InstallParams) -> InstallResult:
+    """Write an instance's files and data dirs, and optionally start it.
+
+    Validates ``params`` (name / port / timeout / retention) and the extra keys,
+    then renders the files, creates ``workspaces/`` ``sessions/`` ``aws/``
+    ``claude/`` under the data path, writes the Claude credentials when a token is
+    given and — unless ``params.start`` is false — builds and awaits health.
+    """
+    name = validate_name(params.name)
+    validate_port(str(params.port))
+    validate_timeout(str(params.timeout_s))
+    validate_retention(params.retention_days)
+
+    env, extra_vars = build_env(params)
+
+    ctx = RenderContext(
+        instance=name,
+        host_port=params.port,
+        data_path=params.data_path,
+        timeout_s=params.timeout_s,
+        puid=params.puid,
+        pgid=params.pgid,
+        edge_package=params.edge_package,
+        edge_version=params.edge_version,
+    )
+    config_dir = instance_dir(name)
+    write_instance_files(config_dir, ctx, env)
+
+    instance_data = params.data_path / name
+    (instance_data / "workspaces").mkdir(parents=True, exist_ok=True)
+    (instance_data / "sessions").mkdir(parents=True, exist_ok=True)
+    (instance_data / "aws").mkdir(parents=True, exist_ok=True)
+    claude_dir = instance_data / "claude"
+    creds: Path | None = None
+    if params.claude_token:
+        creds = write_claude_credentials(claude_dir, params.claude_token)
+    else:
+        claude_dir.mkdir(parents=True, exist_ok=True)
+
+    started = False
+    healthy: bool | None = None
+    url: str | None = None
+    if params.start:
+        instance = Instance(name=name, config_dir=config_dir, env=env)
+        runner = ComposeRunner(instance)
+        runner.up(build=True)
+        healthy = runner.wait_healthy()
+        started = True
+        url = f"http://localhost:{params.port}"
+
+    return InstallResult(
+        name=name,
+        config_dir=config_dir,
+        data_dir=params.data_path,
+        port=params.port,
+        timeout_s=params.timeout_s,
+        env=env,
+        extra_key_vars=extra_vars,
+        claude_credentials_path=creds,
+        claude_dir=claude_dir,
+        started=started,
+        healthy=healthy,
+        url=url,
+    )

mad_cli/core/usecases/instances.py

@@ -0,0 +1,156 @@
+"""Instance inventory use cases: resolve, list (with state/health) and info.
+
+Shared by ``mad list`` / ``mad info`` and the ``/v1/instances`` routes. The
+state/health probe is best-effort — Docker being unreachable degrades the row to
+``unknown``/``-`` rather than raising, so a listing always renders.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from mad_cli.core.compose import ComposeRunner
+from mad_cli.core.instance import (
+    Instance,
+    InstanceNotFoundError,
+    default_instance,
+    discover_instances,
+    get_instance,
+)
+from mad_cli.core.keyspec import display_value, is_secret_key
+from mad_cli.core.usecases.errors import AmbiguousInstanceError, NotFoundError
+
+
+def resolve_instance(name: str | None) -> Instance:
+    """Resolve ``name`` (or the sole instance) to an :class:`Instance`.
+
+    Raises :class:`NotFoundError` when a named instance is missing or none are
+    configured, and :class:`AmbiguousInstanceError` when several exist and none
+    was named. The messages are adapter-agnostic; the CLI appends its own hints.
+    """
+    if name is not None:
+        try:
+            return get_instance(name)
+        except InstanceNotFoundError as exc:
+            raise NotFoundError(f"instance {name!r} not found") from exc
+
+    single = default_instance()
+    if single is not None:
+        return single
+
+    instances = discover_instances()
+    if not instances:
+        raise NotFoundError("no instances configured")
+    names = ", ".join(sorted(inst.name for inst in instances))
+    raise AmbiguousInstanceError(f"multiple instances exist ({names}); name one")
+
+
+def state_health(instance: Instance) -> tuple[str, str]:
+    """Best-effort ``(state, health)`` parsed from ``docker compose ps``.
+
+    Health is read from the ``ps`` text rather than ``wait_healthy`` (which
+    blocks). A missing token degrades to ``"-"``; any failure to reach Docker
+    leaves state ``"unknown"`` so callers still render.
+    """
+    try:
+        out = ComposeRunner(instance).ps()
+    except Exception:  # docker missing/erroring — inventory must still render
+        return "unknown", "-"
+    if not isinstance(out, str):
+        return "unknown", "-"
+    lowered = out.lower()
+    state = "running" if "running" in lowered or " up " in f" {lowered} " else "stopped"
+    if "unhealthy" in lowered:
+        health = "unhealthy"
+    elif "healthy" in lowered:
+        health = "healthy"
+    else:
+        health = "-"
+    return state, health
+
+
+@dataclass(frozen=True)
+class InstanceSummary:
+    """One row of the instance inventory."""
+
+    name: str
+    legacy: bool
+    port: int | None
+    state: str
+    health: str
+    version: str  # the pinned MAD_VERSION, or "latest" when it tracks latest
+
+
+def list_instances() -> list[InstanceSummary]:
+    """Return a summary row per configured instance (state/health best-effort)."""
+    rows: list[InstanceSummary] = []
+    for inst in discover_instances():
+        state, health = state_health(inst)
+        rows.append(
+            InstanceSummary(
+                name=inst.name,
+                legacy=bool(getattr(inst, "legacy", False)),
+                port=inst.host_port,
+                state=state,
+                health=health,
+                version=inst.version_pin or "latest",
+            )
+        )
+    return rows
+
+
+@dataclass(frozen=True)
+class EnvItem:
+    """One ``.env`` assignment, tagged as secret-looking or not."""
+
+    key: str
+    value: str
+    secret: bool
+
+    def display(self, *, reveal: bool = False) -> str:
+        """The value as it should be shown (masked unless ``reveal``)."""
+        return display_value(self.key, self.value, reveal=reveal)
+
+
+@dataclass(frozen=True)
+class InstanceInfo:
+    """An instance's resolved paths plus its ``.env`` items."""
+
+    name: str
+    legacy: bool
+    config_dir: Path
+    compose_file: Path
+    data_path: Path | None
+    port: int | None
+    version: str | None
+    env: list[EnvItem]
+
+
+def _env_items(instance: Instance) -> list[EnvItem]:
+    env = instance.env
+    return [
+        EnvItem(key=key, value=env.get(key) or "", secret=is_secret_key(key))
+        for key in env.keys()  # noqa: SIM118 — EnvFile.keys() is its contract API
+    ]
+
+
+def instance_info(name: str) -> InstanceInfo:
+    """Return the resolved paths and ``.env`` items for the named instance.
+
+    Raises :class:`NotFoundError` when the instance does not exist.
+    """
+    try:
+        instance = get_instance(name)
+    except InstanceNotFoundError as exc:
+        raise NotFoundError(f"instance {name!r} not found") from exc
+    return InstanceInfo(
+        name=instance.name,
+        legacy=bool(getattr(instance, "legacy", False)),
+        config_dir=instance.config_dir,
+        compose_file=instance.compose_file,
+        data_path=instance.data_path,
+        port=instance.host_port,
+        version=instance.version_pin,
+        env=_env_items(instance),
+    )

mad_cli/core/usecases/keys.py

@@ -0,0 +1,169 @@
+"""Credential / API-key use cases: set / list / remove.
+
+A key is either a *builtin* from :data:`mad_cli.core.keyspec.BUILTIN_KEYS`
+(fanned out to one or more env vars, ``claude-oauth`` also materialising the
+container credentials file) or a raw *custom* ``[A-Z][A-Z0-9_]*`` variable.
+Values are always masked on read — a full secret is never returned.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from mad_cli.core.claude_creds import write_claude_credentials
+from mad_cli.core.instance import Instance
+from mad_cli.core.keyspec import BUILTIN_KEYS, KeySpec, is_secret_key, mask
+from mad_cli.core.usecases.errors import PreconditionError, ValidationError
+
+# A custom key is written verbatim; it must look like a shell env-var name.
+CUSTOM_KEY_RE = re.compile(r"[A-Z][A-Z0-9_]*")
+
+
+def _unknown_key_error(key: str) -> ValidationError:
+    return ValidationError(
+        f"Unknown key {key!r}: use a builtin id ({', '.join(BUILTIN_KEYS)}) "
+        "or an env-var name matching [A-Z][A-Z0-9_]*."
+    )
+
+
+def key_prompt(key: str) -> tuple[str, bool]:
+    """Return ``(prompt_text, secret)`` for interactively collecting ``key``.
+
+    Raises :class:`ValidationError` for an id that is neither a builtin nor a
+    valid custom variable, so an adapter never prompts for a bad key.
+    """
+    spec = BUILTIN_KEYS.get(key)
+    if spec is not None:
+        return spec.prompt, spec.secret
+    if CUSTOM_KEY_RE.fullmatch(key):
+        return f"Value for {key}", True
+    raise _unknown_key_error(key)
+
+
+@dataclass(frozen=True)
+class SetKeyResult:
+    id: str
+    env_vars: tuple[str, ...]
+    builtin: bool
+    credentials_path: Path | None  # set when the Claude credentials file was written
+
+
+def _claude_creds_path(instance: Instance) -> Path | None:
+    if instance.data_path is None:
+        return None
+    return instance.data_path / instance.name / "claude" / ".credentials.json"
+
+
+def _set_builtin(instance: Instance, spec: KeySpec, value: str) -> SetKeyResult:
+    for var in spec.env_vars:
+        instance.env.set(var, value)
+    instance.env.save()
+    creds: Path | None = None
+    if spec.writes_claude_credentials:
+        if instance.data_path is None:
+            raise PreconditionError(
+                "cannot write Claude credentials: MAD_DATA_PATH is not set for this instance"
+            )
+        creds = write_claude_credentials(instance.data_path / instance.name / "claude", value)
+    return SetKeyResult(id=spec.id, env_vars=spec.env_vars, builtin=True, credentials_path=creds)
+
+
+def set_key(instance: Instance, key: str, value: str) -> SetKeyResult:
+    """Store a builtin key (fanned out) or a custom variable.
+
+    Raises :class:`ValidationError` for an unknown id and
+    :class:`PreconditionError` when ``claude-oauth`` cannot write its credentials.
+    """
+    spec = BUILTIN_KEYS.get(key)
+    if spec is not None:
+        return _set_builtin(instance, spec, value)
+    if CUSTOM_KEY_RE.fullmatch(key):
+        instance.env.set(key, value)
+        instance.env.save()
+        return SetKeyResult(id=key, env_vars=(key,), builtin=False, credentials_path=None)
+    raise _unknown_key_error(key)
+
+
+@dataclass(frozen=True)
+class BuiltinKeyStatus:
+    id: str
+    env_vars: tuple[str, ...]
+    is_set: bool
+    masked: str  # masked value or "-"
+
+
+@dataclass(frozen=True)
+class CustomSecret:
+    key: str
+    masked: str
+
+
+@dataclass(frozen=True)
+class KeysView:
+    builtins: list[BuiltinKeyStatus]
+    custom: list[CustomSecret]
+
+
+def list_keys(instance: Instance) -> KeysView:
+    """Return the builtin key statuses (masked) plus any custom secret vars."""
+    env = instance.env
+    spec_vars = {var for spec in BUILTIN_KEYS.values() for var in spec.env_vars}
+
+    builtins: list[BuiltinKeyStatus] = []
+    for spec in BUILTIN_KEYS.values():
+        first = next((env.get(var) for var in spec.env_vars if env.get(var)), None)
+        builtins.append(
+            BuiltinKeyStatus(
+                id=spec.id,
+                env_vars=spec.env_vars,
+                is_set=first is not None,
+                masked=mask(first) if first else "-",
+            )
+        )
+
+    custom = [
+        CustomSecret(key=key, masked=mask(env.get(key) or "") if env.get(key) else "-")
+        for key in env.keys()  # noqa: SIM118 — EnvFile.keys() is its contract API
+        if key not in spec_vars and is_secret_key(key)
+    ]
+    return KeysView(builtins=builtins, custom=custom)
+
+
+@dataclass(frozen=True)
+class RemoveKeyResult:
+    id: str
+    env_vars: tuple[str, ...]
+    builtin: bool
+    existed: bool
+    credentials_left: Path | None  # claude-oauth: the on-disk file we left in place
+
+
+def remove_key(instance: Instance, key: str) -> RemoveKeyResult:
+    """Remove a builtin key's env vars (or a custom variable).
+
+    ``existed`` is False when nothing was set (a no-op the adapter reports). The
+    ``claude-oauth`` credentials file is intentionally left on disk.
+    """
+    spec = BUILTIN_KEYS.get(key)
+    if spec is not None:
+        present = [var for var in spec.env_vars if instance.env.get(var) is not None]
+        if not present:
+            return RemoveKeyResult(spec.id, spec.env_vars, True, False, None)
+        for var in spec.env_vars:
+            instance.env.unset(var)
+        instance.env.save()
+        left: Path | None = None
+        if spec.writes_claude_credentials:
+            creds = _claude_creds_path(instance)
+            if creds is not None and creds.exists():
+                left = creds
+        return RemoveKeyResult(spec.id, spec.env_vars, True, True, left)
+    if CUSTOM_KEY_RE.fullmatch(key):
+        if instance.env.get(key) is None:
+            return RemoveKeyResult(key, (key,), False, False, None)
+        instance.env.unset(key)
+        instance.env.save()
+        return RemoveKeyResult(key, (key,), False, True, None)
+    raise _unknown_key_error(key)

mad_cli/core/usecases/lifecycle.py

@@ -0,0 +1,76 @@
+"""Container lifecycle use cases: start / stop / restart / status.
+
+Each operates on an already-resolved :class:`Instance` (the adapter resolves via
+:func:`mad_cli.core.usecases.instances.resolve_instance`, mapping resolution
+failures to its own idiom). The interactive streams (``logs`` / ``shell``) stay in
+the CLI adapter — they attach the caller's TTY and have no HTTP equivalent.
+Everything here is synchronous; the build + health wait blocks in the MVP.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mad_cli.core.compose import ComposeRunner
+from mad_cli.core.instance import Instance
+
+
+def instance_url(instance: Instance) -> str | None:
+    port = instance.host_port
+    return f"http://localhost:{port}" if port is not None else None
+
+
+@dataclass(frozen=True)
+class StartResult:
+    instance: Instance
+    healthy: bool
+    url: str | None
+
+
+def start(instance: Instance) -> StartResult:
+    """Build if needed, start the instance, and await health."""
+    runner = ComposeRunner(instance)
+    runner.up(build=True)
+    healthy = runner.wait_healthy()
+    return StartResult(instance=instance, healthy=healthy, url=instance_url(instance))
+
+
+def stop(instance: Instance) -> None:
+    """Stop the instance and remove its containers."""
+    ComposeRunner(instance).down()
+
+
+def restart(instance: Instance) -> None:
+    """Restart the instance's containers (down, then up with a rebuild)."""
+    ComposeRunner(instance).restart()
+
+
+@dataclass(frozen=True)
+class StatusResult:
+    instance: Instance
+    ps_text: str
+    health: str  # healthy / unhealthy / running / not running
+    url: str | None
+
+
+def _status_health(ps_text: str) -> str:
+    lowered = ps_text.lower()
+    if "unhealthy" in lowered:
+        return "unhealthy"
+    if "healthy" in lowered:
+        return "healthy"
+    if "running" in lowered or " up " in f" {lowered} ":
+        return "running"
+    return "not running"
+
+
+def status(instance: Instance) -> StatusResult:
+    """Return the container state, a health summary and the instance URL."""
+    out = ComposeRunner(instance).ps()
+    ps_text = out if isinstance(out, str) else ""
+    return StatusResult(
+        instance=instance,
+        ps_text=ps_text,
+        health=_status_health(ps_text),
+        url=instance_url(instance),
+    )