rig-cli 1.0.0__py3-none-any.whl

rig/core/identity.py

@@ -0,0 +1,141 @@
+"""Instance identity and filesystem path resolution."""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import re
+import stat
+import subprocess
+from pathlib import Path
+
+from rig.core.constants import DIR_MODE_PRIVATE, FILE_MODE_PRIVATE
+
+
+def instance_id(project: str, root: Path | str) -> str:
+    """Return a stable identifier unique to this project *and* this checkout path."""
+    canonical = str(Path(root).resolve())
+    digest = hashlib.sha256(canonical.encode()).hexdigest()[:8]
+    slug = re.sub(r"[^a-z0-9_-]+", "-", project.lower()).strip("-_") or "stack"
+    if not slug[0].isalnum():
+        slug = f"s{slug}"
+    return f"{slug}-{digest}"
+
+
+def get_state_home() -> Path:
+    """Return root directory for rig global state."""
+    override = os.environ.get("RIG_STATE_HOME")
+    if override:
+        return Path(override).expanduser().resolve()
+    xdg = os.environ.get("XDG_STATE_HOME")
+    if xdg:
+        return (Path(xdg).expanduser() / "rig").resolve()
+    return (Path.home() / ".local" / "state" / "rig").resolve()
+
+
+def get_instances_dir() -> Path:
+    """Return directory containing all machine-wide instance registries."""
+    return get_state_home() / "instances"
+
+
+def get_instance_dir(ident: str) -> Path:
+    """Return state directory path for a specific instance."""
+    return get_instances_dir() / ident
+
+
+def ensure_instance_dir(ident: str) -> Path:
+    """Create and secure owner-only state directory for an instance."""
+    inst_dir = get_instance_dir(ident)
+    inst_dir.mkdir(parents=True, mode=DIR_MODE_PRIVATE, exist_ok=True)
+    if stat.S_IMODE(inst_dir.stat().st_mode) != DIR_MODE_PRIVATE:
+        os.chmod(inst_dir, DIR_MODE_PRIVATE)
+    return inst_dir
+
+
+def get_boot_id() -> str:
+    """Return OS boot identifier to detect system reboots."""
+    linux_boot = Path("/proc/sys/kernel/random/boot_id")
+    if linux_boot.exists():
+        try:
+            return linux_boot.read_text().strip()
+        except OSError:
+            pass
+    try:
+        res = subprocess.run(
+            ["sysctl", "-n", "kern.boottime"],
+            capture_output=True,
+            text=True,
+            timeout=1.0,
+            check=False,
+        )
+        if res.returncode == 0 and res.stdout.strip():
+            return res.stdout.strip()
+    except (subprocess.SubprocessError, OSError):
+        pass
+    return "unknown"
+
+
+def is_locked(path: Path) -> bool:
+    """Return True if path is currently held under exclusive advisory lock."""
+    if not (target := Path(path)).exists():
+        return False
+    try:
+        fd = os.open(target, os.O_RDWR | os.O_CLOEXEC | os.O_NOFOLLOW, FILE_MODE_PRIVATE)
+    except OSError:
+        return False
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        fcntl.flock(fd, fcntl.LOCK_UN)
+    except (BlockingIOError, InterruptedError):
+        return True
+    else:
+        return False
+    finally:
+        os.close(fd)
+
+
+_PROJECT_CANDIDATES = (
+    "rig.json",
+    "scripts/rig.json",
+    ".config/rig.json",
+    "stack.json",
+    "scripts/stack.json",
+    ".config/stack.json",
+)
+
+
+def _has_root_marker(directory: Path) -> bool:
+    return any((directory / c).exists() for c in (*_PROJECT_CANDIDATES, ".git"))
+
+
+def find_project_root(start: Path | None = None) -> Path:
+    """Find project root by walking upward from current working directory."""
+    current = (start or Path.cwd()).resolve()
+    search_path = [current, *current.parents]
+    return next((p for p in search_path if _has_root_marker(p)), current)
+
+
+def find_default_manifest(root: Path) -> Path:
+    """Resolve default manifest path, checking rig.json then stack.json candidates."""
+    candidates = (root / rel for rel in _PROJECT_CANDIDATES)
+    return next((c for c in candidates if c.is_file()), root / _PROJECT_CANDIDATES[0])
+
+
+def _read_project_from_manifest(manifest_path: Path) -> str | None:
+    if not manifest_path.is_file():
+        return None
+    try:
+        data = json.loads(manifest_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    if isinstance(data, dict) and data.get("project"):
+        return str(data["project"])
+    return None
+
+
+def _get_project_name(root: Path) -> str:
+    root = Path(root).resolve()
+    names = (_read_project_from_manifest(root / rel) for rel in _PROJECT_CANDIDATES)
+    return next((name for name in names if name), root.name)

rig/core/locks.py

@@ -0,0 +1,112 @@
+"""Lifecycle mutex and runtime directory management."""
+
+from __future__ import annotations
+
+import contextlib
+import errno
+import fcntl
+import os
+import stat
+import time
+from pathlib import Path
+
+from rig.core.constants import (
+    DIR_MODE_PRIVATE,
+    FILE_MODE_PRIVATE,
+    LOCK_FILE_NAME,
+    LOCK_TIMEOUT_SECS,
+    LOG_DIR_NAME,
+    RUNTIME_DIR_NAME,
+)
+from rig.core.errors import RigError
+from rig.core.identity import _get_project_name, ensure_instance_dir, instance_id
+
+
+def ensure_runtime_dir(root: Path) -> Path:
+    """Ensure ``.local-run`` exists with private permissions."""
+    runtime = Path(root) / RUNTIME_DIR_NAME
+    if runtime.is_symlink():
+        raise RigError(f"{runtime} is a symlink; refusing to use it as a runtime directory")
+    runtime.mkdir(mode=DIR_MODE_PRIVATE, exist_ok=True)
+    info = runtime.lstat()
+    if not stat.S_ISDIR(info.st_mode):
+        raise RigError(f"{runtime} is not a directory")
+    if info.st_uid != os.getuid():
+        raise RigError(f"{runtime} is owned by another user")
+    if stat.S_IMODE(info.st_mode) != DIR_MODE_PRIVATE:
+        os.chmod(runtime, DIR_MODE_PRIVATE)
+    (runtime / LOG_DIR_NAME).mkdir(mode=DIR_MODE_PRIVATE, exist_ok=True)
+    (Path(root) / "data").mkdir(parents=True, exist_ok=True)
+    return runtime
+
+
+def _lock_path(target: Path | str, instance: str | None = None) -> Path:
+    if isinstance(target, str) and "/" not in target and "\\" not in target:
+        return ensure_instance_dir(target) / LOCK_FILE_NAME
+    if instance is not None:
+        return ensure_instance_dir(instance) / LOCK_FILE_NAME
+    root_path = Path(target).resolve()
+    proj = _get_project_name(root_path)
+    inst = instance_id(proj, root_path)
+    return ensure_instance_dir(inst) / LOCK_FILE_NAME
+
+
+def _validate_lock_fd(fd: int, path_obj: Path) -> None:
+    info = os.fstat(fd)
+    if not stat.S_ISREG(info.st_mode):
+        raise RigError(f"{path_obj} is not a regular file")
+    if info.st_uid != os.getuid():
+        raise RigError(f"{path_obj} is owned by another user")
+    if info.st_nlink != 1:
+        raise RigError(f"{path_obj} has {info.st_nlink} links; refusing to lock it")
+
+
+def _acquire_blocking(fd: int, path_obj: Path, timeout: float) -> None:
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except (BlockingIOError, InterruptedError):
+            pass
+        else:
+            return
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            msg = f"another stack command holds {path_obj}; timed out after {timeout:g}s"
+            raise TimeoutError(msg)
+        time.sleep(min(0.05, remaining))
+
+
+def _acquire_lock(fd: int, path_obj: Path, timeout: float) -> None:
+    if timeout <= 0:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except (BlockingIOError, InterruptedError):
+            raise BlockingIOError(f"{path_obj} is currently locked by another process") from None
+    else:
+        _acquire_blocking(fd, path_obj, timeout)
+
+
+def _open_lock_fd(path_obj: Path) -> int:
+    path_obj.parent.mkdir(parents=True, mode=DIR_MODE_PRIVATE, exist_ok=True)
+    try:
+        return os.open(
+            path_obj, os.O_CREAT | os.O_RDWR | os.O_CLOEXEC | os.O_NOFOLLOW, FILE_MODE_PRIVATE
+        )
+    except OSError as exc:
+        if exc.errno in (errno.ELOOP, errno.EMLINK):
+            raise RigError(f"{path_obj} is a symlink; refusing to lock it") from None
+        raise RigError(f"cannot open lock file {path_obj}: {exc}") from None
+
+
+@contextlib.contextmanager
+def exclusive_lock(path: Path, timeout: float = LOCK_TIMEOUT_SECS, blocking: bool = True):
+    """Hold an exclusive advisory lock on ``path`` or raise ``TimeoutError``."""
+    path_obj = Path(path)
+    fd = _open_lock_fd(path_obj)
+    try:
+        _validate_lock_fd(fd, path_obj)
+        _acquire_lock(fd, path_obj, timeout if blocking else 0.0)
+        yield fd
+    finally:
+        os.close(fd)

rig/core/state.py

@@ -0,0 +1,150 @@
+"""State file reading, atomic persistence, and redaction."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from rig.core.constants import (
+    REDACTED,
+    RUNTIME_DIR_NAME,
+    SECRET_NAME_PATTERN,
+    STATE_FILE_NAME,
+)
+from rig.core.identity import (
+    _get_project_name,
+    ensure_instance_dir,
+    get_instances_dir,
+    instance_id,
+)
+
+
+def empty_state() -> dict[str, Any]:
+    return {"generation": 0, "services": {}}
+
+
+def read_state(path: Path) -> dict[str, Any]:
+    """Return persisted state, or an empty stack when it is absent or unreadable."""
+    try:
+        state = json.loads(Path(path).read_text())
+    except (OSError, json.JSONDecodeError):
+        return empty_state()
+    if not isinstance(state, dict):
+        return empty_state()
+    state.setdefault("generation", 0)
+    services = state.get("services")
+    state["services"] = services if isinstance(services, dict) else {}
+    if "ports" in state and not isinstance(state["ports"], dict):
+        state["ports"] = {}
+    return state
+
+
+def resolve_state_file(path: Path) -> Path:
+    p = Path(path)
+    if p.is_symlink():
+        with contextlib.suppress(OSError):
+            return p.resolve()
+    return p
+
+
+def _write_temp_state(target_path: Path, state: Mapping[str, Any]) -> str:
+    target_path.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        dir=target_path.parent,
+        delete=False,
+        prefix=f".{target_path.name}.tmp.",
+    ) as handle:
+        json.dump(state, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+        return handle.name
+
+
+def write_state(path: Path, state: Mapping[str, Any]) -> None:
+    """Publish state atomically so no reader observes a partial generation."""
+    target_path = resolve_state_file(path)
+    tmp: str | None = None
+    try:
+        tmp = _write_temp_state(target_path, state)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, target_path)
+    except BaseException:
+        if tmp is not None:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+        raise
+
+
+def redact(value: Any) -> Any:
+    """Return ``value`` with secret-looking mapping entries masked."""
+    if isinstance(value, Mapping):
+        return {
+            k: REDACTED if isinstance(k, str) and SECRET_NAME_PATTERN.search(k) else redact(v)
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    return value
+
+
+def _relink_symlink(local_state: Path, target: Path) -> None:
+    with contextlib.suppress(OSError):
+        if local_state.resolve() != target.resolve():
+            local_state.unlink()
+            local_state.symlink_to(target)
+
+
+def _relink_file(local_state: Path, target: Path) -> None:
+    with contextlib.suppress(OSError):
+        if not target.exists():
+            shutil.copy2(local_state, target)
+        local_state.unlink()
+        local_state.symlink_to(target)
+
+
+def _sync_state_symlink(local_state: Path, authoritative_state: Path) -> None:
+    if local_state.is_symlink():
+        _relink_symlink(local_state, authoritative_state)
+    elif local_state.is_file():
+        _relink_file(local_state, authoritative_state)
+    elif not local_state.exists():
+        with contextlib.suppress(OSError):
+            local_state.symlink_to(authoritative_state)
+
+
+def _resolve_instance(target: str) -> Path | None:
+    instances_dir = get_instances_dir()
+    if not instances_dir.is_dir():
+        return None
+    direct = instances_dir / target
+    if direct.is_dir():
+        return direct
+    for item in instances_dir.iterdir():
+        sf = item / STATE_FILE_NAME
+        if item.is_dir() and sf.is_file() and read_state(sf).get("project") == target:
+            return item
+    return None
+
+
+def _state_path(root: Path | str, instance: str | None = None) -> Path:
+    if isinstance(root, str) and "/" not in root and "\\" not in root and instance is None:
+        inst_dir = _resolve_instance(root) or ensure_instance_dir(root)
+        return inst_dir / STATE_FILE_NAME
+    root_path = Path(root).resolve()
+    if instance is None:
+        instance = instance_id(_get_project_name(root_path), root_path)
+    inst_dir = ensure_instance_dir(instance)
+    authoritative_state = inst_dir / STATE_FILE_NAME
+
+    runtime = root_path / RUNTIME_DIR_NAME
+    if runtime.is_dir():
+        _sync_state_symlink(runtime / STATE_FILE_NAME, authoritative_state)
+    return authoritative_state

rig/core/terminal.py

@@ -0,0 +1,145 @@
+"""Terminal formatting, ANSI color support, and monospace table alignment."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import unicodedata
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+ANSI_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+
+
+def supports_color() -> bool:
+    """Return True if stdout supports ANSI escape sequences."""
+    if not sys.stdout.isatty():
+        return False
+    if os.environ.get("NO_COLOR"):
+        return False
+    return os.environ.get("TERM") != "dumb"
+
+
+@dataclass(frozen=True)
+class Theme:
+    """ANSI styling token container with automatic color suppression."""
+
+    r: str = ""
+    b: str = ""
+    d: str = ""
+    green: str = ""
+    red: str = ""
+    yellow: str = ""
+    cyan: str = ""
+    magenta: str = ""
+
+
+def get_theme(color: bool | None = None) -> Theme:
+    """Return active Theme instance with ANSI codes or empty strings."""
+    enabled = supports_color() if color is None else color
+    if not enabled:
+        return Theme()
+    return Theme(
+        r="\033[0m",
+        b="\033[1m",
+        d="\033[2m",
+        green="\033[32m",
+        red="\033[31m",
+        yellow="\033[33m",
+        cyan="\033[36m",
+        magenta="\033[35m",
+    )
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from text."""
+    return ANSI_RE.sub("", text)
+
+
+def visible_width(text: str) -> int:
+    """Return visual monospace column width of text, ignoring ANSI escape codes."""
+    clean = strip_ansi(text)
+    return sum(
+        2 if unicodedata.east_asian_width(c) in ("W", "F") else 0 if unicodedata.combining(c) else 1
+        for c in clean
+    )
+
+
+def pad_cell(text: str, width: int, align: str = "left") -> str:
+    """Pad text to visual width, preserving embedded ANSI escape sequences."""
+    pad = " " * max(0, width - visible_width(text))
+    return pad + text if align == "right" else text + pad
+
+
+def contract_path(path_str: str) -> str:
+    """Contract home directory path to ~ prefix."""
+    if not path_str or path_str == "n/a":
+        return path_str
+    home = os.path.expanduser("~")
+    return f"~{path_str[len(home) :]}" if path_str.startswith(home) else path_str
+
+
+MIN_ELLIPSIS_LEN = 4
+
+
+def middle_truncate(text: str, max_len: int) -> str:
+    """Truncate middle of text with ellipsis if exceeding max_len."""
+    if len(text) <= max_len:
+        return text
+    if max_len < MIN_ELLIPSIS_LEN:
+        return text[:max_len]
+    left = (max_len - 1) // 2
+    return f"{text[:left]}…{text[-(max_len - 1 - left) :]}"
+
+
+def format_table(
+    headers: Sequence[str],
+    rows: Sequence[Sequence[str]],
+    gutter: int = 4,
+) -> list[str]:
+    """Format tabular data with dynamically calculated column widths and alignment."""
+    th = get_theme()
+    cols = len(headers)
+    all_rows = [headers, *rows]
+    widths = [max(visible_width(r[i]) for r in all_rows) for i in range(cols)]
+    space = " " * gutter
+    hdr_line = space.join(pad_cell(f"{th.d}{h}{th.r}", widths[i]) for i, h in enumerate(headers))
+    div_line = f"{th.d}{'─' * (sum(widths) + gutter * (cols - 1))}{th.r}"
+    row_lines = [space.join(pad_cell(r[i], widths[i]) for i in range(cols)) for r in rows]
+    return [hdr_line, div_line, *row_lines]
+
+
+def highlight_log_line(line: str, th: Theme) -> str:
+    """Highlight log levels and dim timestamps in log lines without altering content."""
+    if not th.r:
+        return line
+    line = re.sub(
+        r"(\[(?:error|fatal|fail)\]|\b(?:ERROR|FATAL|CRITICAL)\b)",
+        f"{th.red}\\1{th.r}",
+        line,
+        flags=re.I,
+    )
+    line = re.sub(
+        r"(\[(?:warn|warning)\]|\b(?:WARN|WARNING)\b)",
+        f"{th.yellow}\\1{th.r}",
+        line,
+        flags=re.I,
+    )
+    line = re.sub(
+        r"(\[(?:info|notice)\]|\b(?:INFO|NOTICE)\b)",
+        f"{th.green}\\1{th.r}",
+        line,
+        flags=re.I,
+    )
+    line = re.sub(
+        r"(\[(?:debug|trace)\]|\b(?:DEBUG|TRACE)\b)",
+        f"{th.d}\\1{th.r}",
+        line,
+        flags=re.I,
+    )
+    return re.sub(
+        r"^(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?)",
+        f"{th.d}\\1{th.r}",
+        line,
+    )

rig/manifest/__init__.py

@@ -0,0 +1 @@
+"""Manifest loading, models, and detection heuristics for rig."""

rig/manifest/detector.py

@@ -0,0 +1,138 @@
+"""Compose service image detection and datastore classification heuristics."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+POSTGRES_IMAGES = ("postgres", "postgresql", "postgis", "timescaledb")
+POSTGRES_NAMES = ("db", "database", "postgres", "postgresql")
+REDIS_IMAGES = ("redis", "valkey")
+REDIS_NAMES = ("redis", "valkey", "cache")
+
+_IMAGE_KINDS = {
+    **dict.fromkeys(POSTGRES_IMAGES, "postgres"),
+    **dict.fromkeys(REDIS_IMAGES, "redis"),
+}
+_NAME_KINDS = {
+    **dict.fromkeys(POSTGRES_NAMES, "postgres"),
+    **dict.fromkeys(REDIS_NAMES, "redis"),
+}
+_PACKAGE_MANAGERS = (
+    ("pnpm-lock.yaml", "pnpm"),
+    ("yarn.lock", "yarn"),
+    ("bun.lockb", "bun"),
+)
+
+
+def _is_top_level_section(line: str) -> bool:
+    return bool(re.match(r"^[a-zA-Z0-9_-]+\s*:\s*$", line) and not line.startswith(" "))
+
+
+def _parse_service_header(line: str) -> str | None:
+    m = re.match(r"^ {2}([a-zA-Z0-9_-]+)\s*:\s*$", line)
+    return m.group(1) if m else None
+
+
+def _append_service_line(
+    services: dict[str, list[str]], current_svc: str | None, line: str
+) -> str | None:
+    svc_name = _parse_service_header(line)
+    if svc_name:
+        services[svc_name] = []
+        return svc_name
+    if current_svc and line.startswith(("   ", "\t")):
+        services[current_svc].append(line)
+    return current_svc
+
+
+def _extract_compose_services(content: str) -> dict[str, str]:
+    """Return each top-level Compose service name mapped to its own block."""
+    services: dict[str, list[str]] = {}
+    in_services = False
+    current_svc = None
+
+    for line in content.splitlines():
+        trimmed = line.strip()
+        if not trimmed or trimmed.startswith("#"):
+            continue
+        if re.match(r"^services\s*:\s*$", line):
+            in_services, current_svc = True, None
+            continue
+        if in_services and _is_top_level_section(line):
+            in_services, current_svc = False, None
+            continue
+        if in_services:
+            current_svc = _append_service_line(services, current_svc, line)
+
+    return {k: "\n".join(v).lower() for k, v in services.items()}
+
+
+def _compose_service_image(block: str) -> str | None:
+    """Return the image name declared in one Compose service block."""
+    match = re.search(r"^\s{2,}image\s*:\s*[\"']?([^\"'\s#]+)", block, re.MULTILINE)
+    if not match:
+        return None
+    reference = match.group(1)
+    return reference.rsplit("/", 1)[-1].split(":", 1)[0]
+
+
+def classify_compose_service(name: str, block: str) -> str | None:
+    """Return 'postgres', 'redis' or None for one Compose service."""
+    image = _compose_service_image(block)
+    return _IMAGE_KINDS.get(image) if image is not None else _NAME_KINDS.get(name.lower())
+
+
+def _find_fastapi_app(root: Path) -> str:
+    if (root / "app" / "main.py").is_file():
+        return "app.main:app"
+    return "src.main:app" if (root / "src" / "main.py").is_file() else "main:app"
+
+
+def detect_backend(
+    root: Path, native_services: dict[str, Any], base_services: dict[str, Any]
+) -> bool:
+    if (root / "manage.py").is_file():
+        native_services["backend"] = {
+            "type": "port",
+            "cwd": ".",
+            "command": ["python", "manage.py", "runserver", "127.0.0.1:{port}"],
+            "healthcheck_path": "/",
+            "description": "Django web application",
+        }
+        return True
+    if (root / "pyproject.toml").is_file() or (root / "requirements.txt").is_file():
+        spec: dict[str, Any] = {
+            "type": "fd",
+            "cwd": ".",
+            "python": sys.executable,
+            "app": _find_fastapi_app(root),
+            "healthcheck_path": "/healthz",
+            "description": "FastAPI / ASGI backend application",
+        }
+        if "postgres" in base_services:
+            spec["depends_on"] = ["postgres"]
+        native_services["backend"] = spec
+        return True
+    return False
+
+
+def detect_frontend(root: Path, native_services: dict[str, Any], has_backend: bool) -> None:
+    if not (root / "package.json").is_file():
+        return
+    pm = next(
+        (manager for lock, manager in _PACKAGE_MANAGERS if (root / lock).is_file()),
+        "npm",
+    )
+    spec: dict[str, Any] = {
+        "type": "port",
+        "cwd": ".",
+        "command": [pm, "run", "dev", "--", "--port", "{port}"],
+        "healthcheck_path": "/",
+        "description": "Frontend development server",
+    }
+    if has_backend:
+        spec["depends_on"] = ["backend"]
+    native_services["frontend"] = spec