rig-cli 1.0.0__py3-none-any.whl

rig/compose/docker.py

@@ -0,0 +1,117 @@
+"""Plain Docker container queries and lifecycle supervision."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Mapping
+from typing import Any
+
+from rig.compose.client import run_docker
+from rig.compose.context import INHERIT_DOCKER_HOST, record_compose_env, record_docker_endpoint
+from rig.core.errors import RigError
+
+DOCKER_ABSENT_MARKERS = ("no such object", "no such container")
+
+
+def docker_label_container_ids(record: Mapping[str, Any]) -> list[str] | None:
+    """Return the container IDs Compose labelled with this record's project and service."""
+    context, docker_host = record_docker_endpoint(record)
+    filters = [
+        "--filter",
+        f"label=com.docker.compose.project={record.get('instance')}",
+        "--filter",
+        f"label=com.docker.compose.service={record.get('compose_service')}",
+    ]
+    try:
+        res = run_docker(
+            ["ps", "-q", "-a", *filters],
+            context,
+            docker_host=docker_host,
+            env=record_compose_env(record),
+        )
+    except RigError:
+        return None
+    if res.returncode != 0:
+        return None
+    return [line.strip() for line in res.stdout.splitlines() if line.strip()]
+
+
+def docker_reports_no_such_object(probe: subprocess.CompletedProcess) -> bool:
+    answer = f"{probe.stderr or ''}\n{probe.stdout or ''}".lower()
+    return any(m in answer for m in DOCKER_ABSENT_MARKERS)
+
+
+def docker_container_status(
+    container: str,
+    context: Any = None,
+    *args: Any,
+    **kwargs: Any,
+) -> str:
+    p = list(args)
+    docker_host = p.pop(0) if p else kwargs.get("docker_host", INHERIT_DOCKER_HOST)
+    env = p.pop(0) if p else kwargs.get("env")
+    try:
+        cmd = ["inspect", "--format", "{{.State.Status}}", str(container)]
+        probe = run_docker(cmd, context, docker_host=docker_host, env=env)
+    except RigError:
+        return "error"
+    if probe.returncode != 0:
+        return "absent" if docker_reports_no_such_object(probe) else "error"
+    return "alive" if probe.stdout.strip().lower() in ("running", "restarting") else "stopped"
+
+
+def docker_record_targets(record: Mapping[str, Any]) -> tuple[list[str], bool]:
+    ids = docker_label_container_ids(record)
+    targets = list(ids or [])
+    recorded = str(record.get("container") or "")
+    if recorded and not any(recorded.startswith(f) or f.startswith(recorded) for f in targets):
+        targets.insert(0, recorded)
+    return targets, ids is not None
+
+
+def docker_record_status(record: Mapping[str, Any]) -> str:
+    targets, answered = docker_record_targets(record)
+    if not targets:
+        return "absent" if answered else "error"
+    ctx, host = record_docker_endpoint(record)
+    cenv = record_compose_env(record)
+    states = [docker_container_status(t, ctx, host, cenv) for t in targets]
+    return next(
+        (s for s in ("alive", "stopped", "error") if s in states),
+        "absent" if answered else "error",
+    )
+
+
+def _stop_target(
+    target: str,
+    endpoint: tuple[Any, Any, Any],
+    remove: bool,
+) -> bool:
+    ctx, host, cenv = endpoint
+    cmds = [["stop", target]]
+    if remove:
+        cmds.append(["rm", "-f", target])
+    for args in cmds:
+        try:
+            res = run_docker(args, ctx, docker_host=host, env=cenv)
+        except RigError:
+            return False
+        if res.returncode == 0:
+            continue
+        if docker_reports_no_such_object(res):
+            break
+        return False
+    return True
+
+
+def docker_record_stop(record: Mapping[str, Any], remove: bool) -> str:
+    targets, answered = docker_record_targets(record)
+    if not targets:
+        return "stale" if answered else "failed"
+    ctx, host = record_docker_endpoint(record)
+    cenv = record_compose_env(record)
+    endpoint = (ctx, host, cenv)
+    for t in targets:
+        if not _stop_target(t, endpoint, remove):
+            return "failed"
+    return "failed" if not answered else "terminated"

rig/compose/starter.py

@@ -0,0 +1,145 @@
+"""Compose service startup and container tracking."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from rig.compose.client import run_compose
+from rig.compose.context import resolve_current_docker_context
+from rig.compose.discovery import (
+    INTERRUPTION_EXCEPTIONS,
+    discover_container_and_port,
+    handle_compose_interruption,
+    init_compose_record,
+    stranded_error,
+)
+from rig.core.constants import DOCKER_CLIENT_ENV_PASSTHROUGH, EXIT_OP_FAILED
+from rig.core.errors import RigError
+
+
+def _inherit_docker_client_env(cmd_env: dict[str, str]) -> None:
+    cmd_env.update(
+        (name, os.environ[name])
+        for name in DOCKER_CLIENT_ENV_PASSTHROUGH
+        if name not in cmd_env and name in os.environ
+    )
+
+
+def _resolve_compose_endpoints(
+    service: Any, env: Mapping[str, str] | None
+) -> tuple[dict[str, str] | None, str | None, str | None]:
+    docker_host = os.environ.get("DOCKER_HOST")
+    cmd_env = dict(env) if env is not None else None
+    if cmd_env is not None:
+        _inherit_docker_client_env(cmd_env)
+    docker_context = service.docker_context or os.environ.get("DOCKER_CONTEXT") or None
+    if docker_context is None and not docker_host:
+        docker_context = resolve_current_docker_context(cmd_env)
+    if docker_context:
+        docker_host = None
+    return cmd_env, docker_context, docker_host
+
+
+def _run_cleanup_step(
+    target: tuple[str, Path, Path, str],
+    endpoint: tuple[str | None, dict[str, str] | None, str | None],
+    action: list[str],
+) -> bool | None:
+    instance, root, cfile, _ = target
+    ctx, env, host = endpoint
+    try:
+        res = run_compose(
+            instance, root, cfile, action, ctx, timeout=30.0, env=env, docker_host=host
+        )
+    except INTERRUPTION_EXCEPTIONS:
+        return None
+    else:
+        return res.returncode == 0
+
+
+def _cleanup_compose(
+    target: tuple[str, Path, Path, str],
+    endpoint: tuple[str | None, dict[str, str] | None, str | None],
+) -> bool:
+    removed = True
+    for args in (["stop", target[3]], ["rm", "-f", target[3]]):
+        ok = _run_cleanup_step(target, endpoint, args)
+        if ok is None:
+            return False
+        if not ok:
+            removed = False
+    return removed
+
+
+def _run_compose_up(
+    info: tuple[Any, dict[str, Any]],
+    compose_fn: Any,
+    handlers: tuple[Any, Any],
+) -> None:
+    service, record = info
+    fail_fn, cleanup_fn = handlers
+    try:
+        res = compose_fn(["up", "-d", "--no-deps", "--wait", str(service.compose_service)])
+    except (RigError, OSError) as exc:
+        if not cleanup_fn():
+            msg = f"compose could not start {service.name!r}: {exc}"
+            raise stranded_error(msg, record) from exc
+        raise
+    except INTERRUPTION_EXCEPTIONS as exc:
+        handle_compose_interruption(exc, info, cleanup_fn, "the start of")
+    if res.returncode != 0:
+        err = res.stderr.strip() or res.stdout.strip()
+        raise fail_fn(f"compose could not start {service.name!r}: {err}")
+
+
+def _run_discovery_phase(
+    service: Any,
+    record: dict[str, Any],
+    helpers: tuple[Any, Any, Any],
+) -> None:
+    compose_fn, fail_fn, cleanup_fn = helpers
+    try:
+        discover_container_and_port(service, record, (compose_fn, fail_fn))
+    except RigError:
+        raise
+    except INTERRUPTION_EXCEPTIONS as exc:
+        handle_compose_interruption(exc, (service, record), cleanup_fn, "discovery for")
+
+
+def _start_compose_service(
+    service: Any, root: Path, instance: str, *args: Any, **kwargs: Any
+) -> dict[str, Any]:
+    env = args[0] if args else kwargs.get("env")
+    cfile = Path(root) / str(service.compose_file)
+    cmd_env, ctx, host = _resolve_compose_endpoints(service, env)
+    record = init_compose_record(service, instance, (cfile, ctx, host, cmd_env))
+
+    target = (instance, Path(root), cfile, str(service.compose_service))
+    endpoint = (ctx, cmd_env, host)
+
+    def _compose(compose_args: list[str], timeout: float = 180.0):
+        return run_compose(
+            instance,
+            Path(root),
+            cfile,
+            compose_args,
+            ctx,
+            timeout=timeout,
+            env=cmd_env,
+            docker_host=host,
+        )
+
+    def _cleanup() -> bool:
+        return _cleanup_compose(target, endpoint)
+
+    def _fail(msg: str) -> RigError:
+        if _cleanup():
+            return RigError(msg, code="E_COMPOSE_FAILED", exit_code=EXIT_OP_FAILED)
+        return stranded_error(msg, record)
+
+    _run_compose_up((service, record), _compose, (_fail, _cleanup))
+    _run_discovery_phase(service, record, (_compose, _fail, _cleanup))
+    return record

rig/compose/stopper.py

@@ -0,0 +1,71 @@
+"""Compose service stop and teardown."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from rig.compose import client
+from rig.compose.context import record_compose_env, record_docker_endpoint
+from rig.compose.docker import docker_record_stop
+from rig.compose.supervisor import compose_record_status
+from rig.core.errors import RigError
+
+
+def _run_compose_teardown(
+    target: tuple[str, Path, Path],
+    args: list[str],
+    endpoint: tuple[str | None, Any, Any],
+) -> bool:
+    instance, root, compose_file = target
+    ctx_name, docker_host, compose_env = endpoint
+    try:
+        res = client.run_compose(
+            instance,
+            root,
+            compose_file,
+            args,
+            ctx_name,
+            env=compose_env,
+            docker_host=docker_host,
+        )
+    except RigError:
+        return False
+    else:
+        return res.returncode == 0
+
+
+def _teardown_services(
+    target: tuple[str, Path, Path, str],
+    endpoint: tuple[str | None, Any, Any],
+    remove: bool,
+) -> bool:
+    instance, root, compose_file, compose_service = target
+    cmds = [["stop", compose_service]]
+    if remove:
+        cmds.append(["rm", "-f", compose_service])
+    tup = (instance, root, compose_file)
+    return all(_run_compose_teardown(tup, cmd, endpoint) for cmd in cmds)
+
+
+def compose_stop_record(record: Mapping[str, Any], root: Path, remove: bool = True) -> str:
+    status = compose_record_status(record, root)
+    if status in ("absent", "error"):
+        return "stale" if status == "absent" else "failed"
+    if not client.compose_file_present(record, root):
+        return docker_record_stop(record, remove)
+
+    target = (
+        str(record["instance"]),
+        Path(root),
+        Path(str(record["compose_file"])),
+        str(record["compose_service"]),
+    )
+    docker_context, docker_host = record_docker_endpoint(record)
+    endpoint = (docker_context, docker_host, record_compose_env(record))
+    should_remove = remove or not record.get("container")
+
+    if _teardown_services(target, endpoint, should_remove):
+        return "terminated"
+    return docker_record_stop(record, remove)

rig/compose/supervisor.py

@@ -0,0 +1,78 @@
+"""Docker container lifecycle supervision, status queries, and reclamation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from rig.compose.client import compose_file_present, run_compose
+from rig.compose.context import record_compose_env, record_docker_endpoint
+from rig.compose.docker import (
+    docker_container_status,
+    docker_record_status,
+)
+from rig.core.errors import RigError
+
+
+def _check_compose_ps(record: Mapping[str, Any], root: Path) -> list[str] | None:
+    context, docker_host = record_docker_endpoint(record)
+    compose_env = record_compose_env(record)
+    try:
+        res = run_compose(
+            str(record["instance"]),
+            Path(root),
+            Path(record["compose_file"]),
+            ["ps", "-q", "-a", str(record["compose_service"])],
+            context,
+            timeout=60.0,
+            env=compose_env,
+            docker_host=docker_host,
+        )
+        if res.returncode == 0:
+            return [line.strip() for line in res.stdout.splitlines() if line.strip()]
+    except RigError:
+        pass
+    return None
+
+
+def _has_compose_metadata(record: Mapping[str, Any]) -> bool:
+    return bool(
+        record.get("instance") and record.get("compose_file") and record.get("compose_service")
+    )
+
+
+def _evaluate_container_states(
+    ids: list[str], recorded: str, endpoint: tuple[Any, Any, Any]
+) -> str:
+    ctx, host, cenv = endpoint
+    states = [docker_container_status(found, ctx, host, cenv) for found in ids]
+    if recorded and not any(recorded.startswith(f) or f.startswith(recorded) for f in ids):
+        states.append(docker_container_status(recorded, ctx, host, cenv))
+    return next((state for state in ("alive", "stopped") if state in states), "error")
+
+
+def compose_record_status(record: Mapping[str, Any], root: Path) -> str:
+    """Return 'alive', 'stopped', 'absent', or 'error' for one compose record."""
+    if not _has_compose_metadata(record):
+        return "absent"
+    ids = _check_compose_ps(record, root) if compose_file_present(record, root) else None
+    if ids is None:
+        return docker_record_status(record)
+
+    context, docker_host = record_docker_endpoint(record)
+    compose_env = record_compose_env(record)
+    recorded = str(record.get("container") or "")
+    if not ids:
+        return (
+            docker_container_status(recorded, context, docker_host, compose_env)
+            if recorded
+            else "absent"
+        )
+
+    return _evaluate_container_states(ids, recorded, (context, docker_host, compose_env))
+
+
+def compose_record_alive(record: Mapping[str, Any], root: Path) -> bool:
+    """Return ``True`` when the recorded container is still running under this instance."""
+    return compose_record_status(record, root) == "alive"

rig/core/__init__.py

@@ -0,0 +1 @@
+"""Core primitives, constants, locks, and state for rig."""

rig/core/constants.py

@@ -0,0 +1,65 @@
+"""Constants and exit codes for rig."""
+
+from __future__ import annotations
+
+import re
+
+RUNTIME_DIR_NAME = ".local-run"
+__version__ = "1.0.0"
+LOCK_FILE_NAME = "checkout.lock"
+STATE_FILE_NAME = "state.json"
+LOG_DIR_NAME = "logs"
+DIR_MODE_PRIVATE = 0o700
+FILE_MODE_PRIVATE = 0o600
+
+LOCK_TIMEOUT_SECS = 10.0
+HEALTH_TIMEOUT_SECS = 45.0
+TEARDOWN_TIMEOUT_SECS = 5.0
+PORT_RELEASE_TIMEOUT_SECS = 5.0
+PORT_RETRY_ATTEMPTS = 3
+PORT_MIN = 1
+PORT_MAX = 65535
+COMPOSE_UP_TIMEOUT_SECS = 180.0
+COMPOSE_DISCOVERY_TIMEOUT_SECS = 60.0
+COMPOSE_TEARDOWN_TIMEOUT_SECS = 30.0
+DEFAULT_STARTUP_WAIT_SECS = 0.3
+
+SERVICE_TYPES = ("fd", "port", "compose")
+SCOPES = ("full", "local", "backend", "ui")
+
+BASE_ENV_ALLOWLIST = (
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TERM",
+    "TMPDIR",
+    "TZ",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+)
+
+DOCKER_CLIENT_ENV_PASSTHROUGH = (
+    "DOCKER_CONFIG",
+    "DOCKER_CERT_PATH",
+    "DOCKER_TLS_VERIFY",
+)
+
+SECRET_NAME_PATTERN = re.compile(
+    r"TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|_KEY$|^KEY$|APIKEY|PRIVATE",
+    re.IGNORECASE,
+)
+REDACTED = "***"
+
+EXIT_OK = 0
+EXIT_OP_FAILED = 1
+EXIT_USAGE = 2
+EXIT_MUTEX_CONFLICT = 3
+EXIT_NOT_FOUND = 4
+EXIT_REFUSED = 5
+EXIT_EXTERNAL_TOOL = 6
+EXIT_INTERRUPTED = 130

rig/core/env.py

@@ -0,0 +1,83 @@
+"""Environment variable allowlisting and placeholder formatting."""
+
+from __future__ import annotations
+
+import os
+import string
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from rig.core.constants import BASE_ENV_ALLOWLIST
+from rig.core.errors import RigError
+
+
+class _StrictValues(dict):
+    def __missing__(self, key):
+        raise RigError(f"unknown placeholder {{{key}}}")
+
+
+_FORMATTER = string.Formatter()
+
+
+def render(value: Any, values: Mapping[str, Any]) -> Any:
+    """Substitute ``{name}`` placeholders in strings, lists and mappings."""
+    strict = _StrictValues(values)
+    if isinstance(value, str):
+        try:
+            return _FORMATTER.vformat(value, (), strict)
+        except (IndexError, KeyError) as exc:
+            raise RigError(f"cannot render {value!r}: {exc}") from None
+    if isinstance(value, list):
+        return [render(item, values) for item in value]
+    if isinstance(value, Mapping):
+        return {key: render(item, values) for key, item in value.items()}
+    return value
+
+
+_MIN_QUOTED_LEN = 2
+
+
+def _strip_env_quotes(item: str) -> str:
+    if len(item) >= _MIN_QUOTED_LEN and item[0] == item[-1] and item[0] in "\"'":
+        return item[1:-1]
+    return item
+
+
+def parse_env_file(path: Path) -> dict[str, str]:
+    """Return ``KEY=VALUE`` pairs from a dotenv-style file, ignoring comments."""
+    values: dict[str, str] = {}
+    try:
+        text = Path(path).read_text()
+    except OSError:
+        return values
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, _, raw = stripped.partition("=")
+        key = key.strip()
+        if key.startswith("export "):
+            key = key[len("export ") :].strip()
+        values[key] = _strip_env_quotes(raw.strip())
+    return values
+
+
+def build_service_env(
+    declared: Mapping[str, Any],
+    *args: Any,
+    **kwargs: Any,
+) -> dict[str, str]:
+    """Compose a service environment from an allowlist, env files and manifest values."""
+    params = list(args)
+    inherit: Sequence[str] = params.pop(0) if params else kwargs.get("inherit", ())
+    root: Path = params.pop(0) if params else kwargs.get("root", Path.cwd())
+    values: Mapping[str, Any] = params.pop(0) if params else kwargs.get("values", {})
+    env_files: Sequence[str] = params.pop(0) if params else kwargs.get("env_files", ())
+
+    env = {name: os.environ[name] for name in (*BASE_ENV_ALLOWLIST, *inherit) if name in os.environ}
+    for relative in env_files:
+        env.update(parse_env_file(Path(root) / relative))
+    merged = {**values, "root": str(root)}
+    env.update((str(key), str(render(raw, merged))) for key, raw in declared.items())
+    return env

rig/core/errors.py

@@ -0,0 +1,74 @@
+"""Exceptions and JSON error formatting for rig."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rig.core.constants import EXIT_OP_FAILED, EXIT_USAGE
+
+
+class RigError(RuntimeError):
+    """A rig operation cannot proceed safely."""
+
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code: str = str(kwargs.get("code", "E_GENERIC"))
+        self.exit_code: int = int(kwargs.get("exit_code", EXIT_OP_FAILED))
+        self.hint: str | None = kwargs.get("hint")
+        self.headline: str | None = kwargs.get("headline")
+        self.context: str | None = kwargs.get("context")
+        self.details: dict[str, Any] = kwargs.get("details") or {}
+
+
+StackError = RigError
+
+
+def format_human_error(exc: RigError, th: Any) -> str:
+    """Format a RigError into a high-signal human structured error card."""
+    headline = exc.headline or exc.message
+    lines = [f"  {th.red}✖ {headline}{th.r}"]
+    if exc.context:
+        for cl in exc.context.splitlines():
+            lines.append(f"    {th.d}{cl}{th.r}")
+    elif exc.headline and exc.headline != exc.message:
+        lines.append(f"    {th.d}{exc.message}{th.r}")
+    if exc.hint:
+        lines.append(f"    {th.cyan}Hint:{th.r} {exc.hint}  {th.d}[{exc.code}]{th.r}")
+    else:
+        lines.append(f"    {th.d}[{exc.code}]{th.r}")
+    return "\n".join(lines) + "\n"
+
+
+def manifest_error(message: str, *, hint: str | None = None) -> RigError:
+    """Return the error for a manifest that cannot be used as written."""
+    return RigError(message, code="E_USAGE", exit_code=EXIT_USAGE, hint=hint)
+
+
+def print_json_envelope(command: str, data: Any, ok: bool | None = None) -> None:
+    """Output envelope for structured JSON responses."""
+    if ok is None:
+        ok = bool(data["ok"]) if isinstance(data, dict) and "ok" in data else True
+    envelope = {
+        "schema": f"rig.{command}/1",
+        "ok": ok,
+        "data": data,
+    }
+    print(json.dumps(envelope, indent=2))
+
+
+def print_json_error(exc: RigError, command: str = "error") -> None:
+    """Output envelope for structured JSON errors."""
+    envelope = {
+        "schema": "rig.error/1",
+        "ok": False,
+        "error": {
+            "code": exc.code,
+            "exit_code": exc.exit_code,
+            "message": exc.message,
+            "hint": exc.hint,
+            "details": exc.details,
+        },
+    }
+    print(json.dumps(envelope, indent=2))