rig-cli 1.0.0__py3-none-any.whl

rig/manifest/inspect.py

@@ -0,0 +1,18 @@
+"""Binary executable resolution utilities."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+def _resolve_executable(spec: str, cwd: Path) -> Path | None:
+    """Return the file a spawn would execute for ``spec``, or None when absent."""
+    if os.sep in spec:
+        candidate = Path(spec)
+        if not candidate.is_absolute():
+            candidate = cwd / candidate
+        return candidate if candidate.is_file() else None
+    found = shutil.which(spec)
+    return Path(found) if found else None

rig/manifest/loader.py

@@ -0,0 +1,146 @@
+"""Manifest parsing and loading for rig."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from rig.core.constants import EXIT_USAGE
+from rig.core.errors import RigError, manifest_error
+from rig.manifest.models import Manifest, Service
+from rig.manifest.parser import _parse_service, _validate_service_integrity
+
+
+def _load_raw_json(path: Path) -> dict[str, Any]:
+    try:
+        raw = json.loads(Path(path).read_text())
+    except OSError:
+        raise RigError(
+            f"manifest not found: {path}",
+            code="E_USAGE",
+            exit_code=EXIT_USAGE,
+            headline="No manifest found in this directory",
+            context=f"rig looked for 'rig.json' or 'stack.json' at:\n{path}",
+            hint="Run 'rig init' to scaffold a new manifest, or pass '--manifest <path>'",
+        ) from None
+    except json.JSONDecodeError as exc:
+        raise manifest_error(f"manifest {path} is not valid JSON: {exc}") from None
+    if not isinstance(raw, dict):
+        raise manifest_error(f"manifest {path} must be a JSON object")
+    if not isinstance(raw.get("project"), str) or not raw.get("project"):
+        raise manifest_error(f"manifest {path} must declare a non-empty 'project'")
+    return raw
+
+
+def _build_mode_services(raw_modes: Any) -> dict[str, dict[str, Service]]:
+    if raw_modes is None:
+        return {}
+    if not isinstance(raw_modes, dict):
+        raise manifest_error("'modes' must be a JSON object")
+    modes: dict[str, dict[str, Service]] = {}
+    for mode_name, mode_obj in raw_modes.items():
+        if not isinstance(mode_obj, dict) or not isinstance(mode_obj.get("services"), dict):
+            raise manifest_error(f"mode {mode_name!r} must declare a 'services' object")
+        modes[mode_name] = {
+            sname: _parse_service(sname, spec) for sname, spec in mode_obj["services"].items()
+        }
+    return modes
+
+
+def _register_service_aliases(
+    item: tuple[str, Service], services: dict[str, Service], derived: dict[str, list[str]]
+) -> None:
+    sname, service = item
+    derived[sname] = [sname]
+    for alias in service.aliases:
+        if not isinstance(alias, str) or not alias:
+            raise manifest_error(f"service {sname!r} has invalid alias {alias!r}")
+        if alias in services and alias != sname:
+            raise manifest_error(f"alias {alias!r} for service {sname!r} conflicts with another")
+        derived[alias] = [sname]
+
+
+def _validate_scope_members(scope: str, members: list[str], known: set[str]) -> None:
+    for m in members:
+        if m not in known:
+            raise manifest_error(f"scope {scope!r} names unknown service {m!r}")
+
+
+def _parse_explicit_scopes(
+    scopes_raw: Any, initial_services: dict[str, Service]
+) -> dict[str, list[str]]:
+    if scopes_raw is None:
+        return {}
+    if not isinstance(scopes_raw, dict):
+        raise manifest_error("'scopes' must be a JSON object")
+    explicit: dict[str, list[str]] = {}
+    known = set(initial_services)
+    for scope, members in scopes_raw.items():
+        if not isinstance(members, list) or not all(isinstance(m, str) for m in members):
+            raise manifest_error(f"scope {scope!r} must be a list of string service names")
+        _validate_scope_members(scope, members, known)
+        explicit[scope] = list(members)
+    return explicit
+
+
+def _derive_scopes(
+    services: dict[str, Service], raw: Any
+) -> tuple[dict[str, list[str]], dict[str, list[str]]]:
+    derived: dict[str, list[str]] = {"full": list(services), "local": list(services)}
+    for item in services.items():
+        _register_service_aliases(item, services, derived)
+    explicit = _parse_explicit_scopes(raw, services)
+    derived.update(explicit)
+    return derived, explicit
+
+
+def _validate_raw_services(path: Path, declared: Any, raw_modes: Any) -> None:
+    if declared is not None and not isinstance(declared, dict):
+        raise manifest_error(f"manifest {path} 'services' must be a JSON object")
+    if not declared and not raw_modes:
+        raise manifest_error(f"manifest {path} must declare at least one service")
+
+
+def _resolve_initial_mode(
+    modes: dict[str, dict[str, Service]], default_mode: str | None
+) -> tuple[str | None, str | None]:
+    if default_mode and default_mode not in modes:
+        known = list(modes.keys())
+        raise manifest_error(f"default_mode {default_mode!r} not declared in modes: {known}")
+    init_mode = default_mode or next(iter(modes), None)
+    return default_mode, init_mode
+
+
+def load_manifest(path: Path) -> Manifest:
+    """Read and validate a stack manifest."""
+    path = Path(path)
+    raw = _load_raw_json(path)
+    declared, raw_modes = raw.get("services"), raw.get("modes")
+    _validate_raw_services(path, declared, raw_modes)
+
+    base = {name: _parse_service(name, spec) for name, spec in (declared or {}).items()}
+    modes = _build_mode_services(raw_modes)
+    default_mode, init_mode = _resolve_initial_mode(modes, raw.get("default_mode"))
+
+    services = {**base, **(modes[init_mode] if init_mode else {})}
+    _validate_service_integrity(services)
+    scopes, explicit_scopes = _derive_scopes(services, raw.get("scopes"))
+
+    manifest = Manifest(
+        project=raw["project"],
+        services=services,
+        scopes=scopes,
+        path=path,
+        base_services=base,
+        modes=modes,
+        default_mode=default_mode,
+        active_mode=init_mode,
+        explicit_scopes=explicit_scopes,
+    )
+    for m_name in modes:
+        manifest.for_mode(m_name)
+    if not modes:
+        for scope in scopes:
+            manifest.resolve_scope(scope)
+    return manifest

rig/manifest/models.py

@@ -0,0 +1,129 @@
+"""Data models for rig service and manifest declarations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from rig.core.constants import HEALTH_TIMEOUT_SECS
+from rig.core.errors import manifest_error
+
+
+@dataclass
+class Service:
+    name: str
+    type: str
+    cwd: str = "."
+    command: list[str] = field(default_factory=list)
+    aliases: list[str] = field(default_factory=list)
+    app: str | None = None
+    factory: bool = False
+    python: str | None = None
+    env: dict[str, Any] = field(default_factory=dict)
+    inherit: list[str] = field(default_factory=list)
+    env_files: list[str] = field(default_factory=list)
+    healthcheck_path: str | None = None
+    healthcheck_timeout: float = HEALTH_TIMEOUT_SECS
+    depends_on: list[str] = field(default_factory=list)
+    compose_file: str | None = None
+    compose_service: str | None = None
+    compose_port: int | None = None
+    docker_context: str | None = None
+    description: str = ""
+    preferred_port: int | None = None
+
+
+@dataclass
+class Manifest:
+    project: str
+    services: dict[str, Service]
+    scopes: dict[str, list[str]]
+    path: Path
+    base_services: dict[str, Service] = field(default_factory=dict)
+    modes: dict[str, dict[str, Service]] = field(default_factory=dict)
+    default_mode: str | None = None
+    active_mode: str | None = None
+    explicit_scopes: dict[str, list[str]] = field(default_factory=dict)
+
+    def resolve_services(self, names: Iterable[str]) -> list[str]:
+        """Return the given services plus their transitive dependencies, in start order."""
+        ordered: list[str] = []
+        for name in names:
+            self._visit(name, ordered, set())
+        return ordered
+
+    def resolve_scope(self, scope: str) -> list[str]:
+        """Return the scope's services plus their transitive dependencies, in start order."""
+        return self.resolve_services(self._members(scope))
+
+    def teardown_scope(self, scope: str) -> list[str]:
+        """Return only the scope's declared services, in reverse start order."""
+        declared = set(self._members(scope))
+        return [name for name in reversed(self.resolve_scope(scope)) if name in declared]
+
+    def dependents(self, name: str) -> list[str]:
+        return [other for other, service in self.services.items() if name in service.depends_on]
+
+    def _members(self, scope: str) -> list[str]:
+        if scope not in self.scopes:
+            known = ", ".join(sorted(self.scopes))
+            raise manifest_error(f"unknown scope {scope!r}; manifest declares {known}")
+        return list(self.scopes[scope])
+
+    def _visit(self, name: str, ordered: list[str], seen: set[str]) -> None:
+        if name in ordered:
+            return
+        if name in seen:
+            raise manifest_error(f"dependency cycle through service {name!r}")
+        seen.add(name)
+        for dependency in self.services[name].depends_on:
+            self._visit(dependency, ordered, seen)
+        ordered.append(name)
+
+    def _build_derived_scopes(self, mode_services: dict[str, Service]) -> dict[str, list[str]]:
+        derived: dict[str, list[str]] = {
+            "full": list(mode_services.keys()),
+            "local": list(mode_services.keys()),
+        }
+        derived.update(
+            {
+                alias: [name]
+                for name, service in mode_services.items()
+                for alias in (name, *service.aliases)
+            }
+        )
+        derived.update(
+            {
+                scope: selected
+                for scope, members in self.explicit_scopes.items()
+                if (selected := [member for member in members if member in mode_services])
+            }
+        )
+        return derived
+
+    def for_mode(self, mode_name: str | None = None) -> Manifest:
+        if not self.modes:
+            return self
+        target_mode = mode_name or self.default_mode or next(iter(self.modes.keys()))
+        if target_mode not in self.modes:
+            known = ", ".join(sorted(self.modes.keys()))
+            raise manifest_error(f"unknown mode {target_mode!r}; manifest declares modes: {known}")
+        mode_services = {**self.base_services, **self.modes[target_mode]}
+        derived_scopes = self._build_derived_scopes(mode_services)
+
+        m = Manifest(
+            project=self.project,
+            services=mode_services,
+            scopes=derived_scopes,
+            path=self.path,
+            base_services=self.base_services,
+            modes=self.modes,
+            default_mode=self.default_mode,
+            active_mode=target_mode,
+            explicit_scopes=self.explicit_scopes,
+        )
+        for scope in derived_scopes:
+            m.resolve_scope(scope)
+        return m

rig/manifest/parser.py

@@ -0,0 +1,123 @@
+"""Service specification parsing and integrity validation."""
+
+from __future__ import annotations
+
+import math
+import shlex
+from collections.abc import Mapping
+from typing import Any
+
+from rig.core.constants import PORT_MAX, PORT_MIN, SERVICE_TYPES
+from rig.core.errors import manifest_error
+from rig.manifest.models import Service
+
+
+def _validate_spec_types(name: str, spec: dict[str, Any]) -> None:
+    kind = spec.get("type")
+    if kind not in SERVICE_TYPES:
+        raise manifest_error(
+            f"service {name!r} has unknown type {kind!r}; expected one of {SERVICE_TYPES}"
+        )
+    for key in ("env_files", "depends_on", "aliases", "inherit"):
+        if key in spec and (
+            not isinstance(spec[key], list) or not all(isinstance(i, str) for i in spec[key])
+        ):
+            raise manifest_error(f"service {name!r} {key!r} must be a list of strings")
+    if "env" in spec and (
+        not isinstance(spec["env"], dict) or not all(isinstance(k, str) for k in spec["env"])
+    ):
+        raise manifest_error(
+            f"service {name!r} 'env' must be a JSON object mapping strings to values"
+        )
+    if "cwd" in spec and not isinstance(spec["cwd"], str):
+        raise manifest_error(f"service {name!r} 'cwd' must be a string")
+
+
+def _validate_spec_health(name: str, spec: dict[str, Any]) -> None:
+    if "health" in spec:
+        if "healthcheck_path" in spec and spec["health"] != spec["healthcheck_path"]:
+            raise manifest_error(
+                f"service {name!r} defines conflicting 'health' and 'healthcheck_path'"
+            )
+        spec["healthcheck_path"] = spec.pop("health")
+    t = spec.get("healthcheck_timeout")
+    if "healthcheck_timeout" in spec and (
+        isinstance(t, bool) or not isinstance(t, (int, float)) or not math.isfinite(t) or t <= 0
+    ):
+        raise manifest_error(
+            f"service {name!r} 'healthcheck_timeout' must be a positive finite number"
+        )
+    if "healthcheck_path" in spec and spec["healthcheck_path"] is not None:
+        hp = spec["healthcheck_path"]
+        if not isinstance(hp, str) or not hp or not hp.startswith("/"):
+            raise manifest_error(
+                f"service {name!r} 'healthcheck_path' must be a non-empty string starting with '/'"
+            )
+
+
+def _parse_command_string(name: str, cmd_str: str) -> list[str]:
+    clean = cmd_str.strip()
+    if not clean or "\0" in clean:
+        raise manifest_error(f"service {name!r} 'command' cannot be empty or contain NUL")
+    try:
+        tokens = shlex.split(clean, comments=False, posix=True)
+    except ValueError as exc:
+        raise manifest_error(f"service {name!r} invalid command syntax: {exc}") from None
+    if not tokens:
+        raise manifest_error(f"service {name!r} 'command' cannot be empty")
+    return tokens
+
+
+def _validate_spec_command(name: str, spec: dict[str, Any]) -> None:
+    raw_cmd = spec.get("command")
+    if isinstance(raw_cmd, str):
+        spec["command"] = _parse_command_string(name, raw_cmd)
+    elif isinstance(raw_cmd, list):
+        if not all(isinstance(t, str) for t in raw_cmd):
+            raise manifest_error(f"service {name!r} 'command' must be a list of strings")
+    elif raw_cmd is not None:
+        raise manifest_error(f"service {name!r} 'command' must be a string or list of strings")
+
+
+def _validate_spec_port(name: str, spec: dict[str, Any]) -> None:
+    if "port" in spec and "preferred_port" not in spec:
+        spec["preferred_port"] = spec.pop("port")
+    if "preferred_port" in spec and spec["preferred_port"] is not None:
+        p = spec["preferred_port"]
+        if isinstance(p, bool) or not isinstance(p, int) or not (PORT_MIN <= p <= PORT_MAX):
+            raise manifest_error(
+                f"service {name!r} 'preferred_port' must be an integer between 1 and {PORT_MAX}"
+            )
+
+
+def _parse_service(name: str, raw_spec: Any) -> Service:
+    if not isinstance(raw_spec, dict):
+        raise manifest_error(f"service {name!r} must be a JSON object")
+    spec = dict(raw_spec)
+    _validate_spec_types(name, spec)
+    _validate_spec_health(name, spec)
+    _validate_spec_command(name, spec)
+    _validate_spec_port(name, spec)
+
+    known = {f.name for f in Service.__dataclass_fields__.values()} - {"name"}
+    unknown = set(spec) - known
+    if unknown:
+        raise manifest_error(f"service {name!r} has unknown keys: {sorted(unknown)}")
+    return Service(name=name, **spec)
+
+
+def _check_dependencies(name: str, service: Service, services: Mapping[str, Service]) -> None:
+    for dependency in service.depends_on:
+        if dependency not in services:
+            raise manifest_error(f"service {name!r} depends on unknown service {dependency!r}")
+
+
+def _validate_service_integrity(services: Mapping[str, Service]) -> None:
+    for name, service in services.items():
+        _check_dependencies(name, service, services)
+        if service.type == "fd" and not (service.command or service.app):
+            raise manifest_error(f"service {name!r} needs a 'command' or an 'app'")
+        if service.type == "port" and not service.command:
+            raise manifest_error(f"service {name!r} needs a 'command'")
+        if service.type == "compose" and not (service.compose_file and service.compose_service):
+            raise manifest_error(f"service {name!r} needs 'compose_file' and 'compose_service'")

rig/manifest/schema.py

@@ -0,0 +1,89 @@
+"""JSON schema generation and CLI handler for rig manifests."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rig.core.constants import EXIT_OK
+from rig.core.errors import print_json_envelope
+
+
+def get_rig_schema() -> dict[str, Any]:
+    return {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "RigManifest",
+        "description": "Schema for rig.json (v2) developer environment supervisor manifests.",
+        "type": "object",
+        "required": ["project"],
+        "properties": {
+            "$schema": {"type": "string"},
+            "project": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
+            "default_mode": {"type": "string"},
+            "services": {
+                "type": "object",
+                "additionalProperties": {"$ref": "#/definitions/Service"},
+            },
+            "modes": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "object",
+                    "required": ["services"],
+                    "properties": {
+                        "services": {
+                            "type": "object",
+                            "additionalProperties": {"$ref": "#/definitions/Service"},
+                        }
+                    },
+                },
+            },
+            "scopes": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                },
+            },
+        },
+        "definitions": {
+            "Service": {
+                "type": "object",
+                "required": ["type"],
+                "properties": {
+                    "type": {"type": "string", "enum": ["fd", "port", "compose"]},
+                    "cwd": {"type": "string", "default": "."},
+                    "command": {
+                        "oneOf": [
+                            {"type": "string"},
+                            {"type": "array", "items": {"type": "string"}},
+                        ]
+                    },
+                    "aliases": {"type": "array", "items": {"type": "string"}},
+                    "app": {"type": "string"},
+                    "factory": {"type": "boolean", "default": False},
+                    "python": {"type": "string"},
+                    "env": {"type": "object"},
+                    "inherit": {"type": "array", "items": {"type": "string"}},
+                    "env_files": {"type": "array", "items": {"type": "string"}},
+                    "healthcheck_path": {"type": "string"},
+                    "healthcheck_timeout": {"type": "number", "default": 45.0},
+                    "depends_on": {"type": "array", "items": {"type": "string"}},
+                    "compose_file": {"type": "string"},
+                    "compose_service": {"type": "string"},
+                    "compose_port": {"type": "integer"},
+                    "docker_context": {"type": "string"},
+                    "description": {"type": "string"},
+                    "preferred_port": {"type": "integer"},
+                },
+            }
+        },
+    }
+
+
+def cmd_schema(as_json: bool = False) -> int:
+    schema = get_rig_schema()
+    if as_json:
+        print_json_envelope("schema", schema)
+    else:
+        print(json.dumps(schema, indent=2))
+    return EXIT_OK

rig/net/__init__.py

@@ -0,0 +1 @@
+"""Networking, port management, and health checks for rig."""

rig/net/health.py

@@ -0,0 +1,76 @@
+"""Health check HTTP polling without external proxies or redirects."""
+
+from __future__ import annotations
+
+import os
+import time
+import urllib.error
+import urllib.request
+
+from rig.core.constants import HEALTH_TIMEOUT_SECS
+from rig.net.probe import port_listener_matches
+
+HTTP_STATUS_OK = 200
+HTTP_STATUS_REDIRECT = 300
+
+
+class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+def _health_opener() -> urllib.request.OpenerDirector:
+    return urllib.request.build_opener(urllib.request.ProxyHandler({}), _RefuseRedirects())
+
+
+def _pid_is_running(pid: int | None) -> bool:
+    if pid is None:
+        return True
+    try:
+        os.kill(pid, 0)
+    except (ProcessLookupError, PermissionError):
+        return False
+    else:
+        return True
+
+
+def _check_http_response(
+    opener: urllib.request.OpenerDirector,
+    url: str,
+    target: tuple[int, int | None, int | None, float],
+) -> bool:
+    port, pid, pgid, timeout = target
+    try:
+        with opener.open(url, timeout=min(2.0, max(0.2, timeout))) as response:
+            if HTTP_STATUS_OK <= response.status < HTTP_STATUS_REDIRECT:
+                if pid is None and pgid is None:
+                    return True
+                if _pid_is_running(pid) and port_listener_matches(port, pgid=pgid, pid=pid):
+                    return True
+    except (urllib.error.URLError, OSError, ValueError):
+        pass
+    return False
+
+
+def wait_for_http(
+    port: int,
+    path: str,
+    timeout: float | tuple[float, int | None, int | None] = HEALTH_TIMEOUT_SECS,
+) -> bool:
+    """Poll ``http://127.0.0.1:<port><path>`` until it answers 2xx or deadline passes."""
+    t_val = timeout[0] if isinstance(timeout, tuple) else float(timeout)
+    pid = timeout[1] if isinstance(timeout, tuple) else None
+    pgid = timeout[2] if isinstance(timeout, tuple) else None
+    opener = _health_opener()
+    clean_path = path if path.startswith("/") else f"/{path}"
+    url = f"http://127.0.0.1:{port}{clean_path}"
+    target = (port, pid, pgid, t_val)
+    deadline = time.monotonic() + t_val
+    while True:
+        if pid is not None and not _pid_is_running(pid):
+            return False
+        if _check_http_response(opener, url, target):
+            return True
+        if time.monotonic() >= deadline:
+            return False
+        time.sleep(0.15)