aisc-cli 0.1.0__py3-none-any.whl

aisc/adapters/docker_sdk_backed.py

@@ -0,0 +1,274 @@
+"""PERF P4 (D-13): SDK-backed Docker executor for the command layer.
+
+The runtime/provider/services command layer used to hardcode
+``RealDockerExecutor`` — every Docker call inside each aisc.exe invocation
+was a ``docker.exe`` subprocess chain (info → ps → inspect → exec). On weak
+machines each docker.exe cold start costs 100-300ms × 5-6 calls per tick.
+
+``SdkBackedDockerExecutor`` implements the same ``DockerExecutor`` protocol
+with the HOT-READ face served over the docker SDK's named-pipe/unix-socket
+HTTP client (in-process, zero subprocesses):
+
+- ``preflight()`` — SDK ping first, CLI fallback (reason vocabulary kept)
+- ``inspect_container(name)`` — SDK inspect; NotFound maps to the CLI's
+  "No such object" stderr semantics the callers pattern-match
+- ``run_captured`` for the three hot argv shapes:
+  * ``ps -a --filter label=... --format <template>`` — SDK containers.list
+    + a mini renderer for the templates we ship (``ID``/``Names``/``Image``/
+    ``Status``/``Label "k"`` tokens only — anything else falls back to CLI)
+  * ``exec <name> <cmd...>`` (no flags) — exec_create/start/inspect
+  * ``inspect <name>``
+- everything else (run/build/start/stop/rm/pull/... and all streaming /
+  interactive methods) delegates verbatim to an inner ``RealDockerExecutor``
+  — low-frequency control operations where the CLI's behavior is battle-
+  tested (buildx flags, process groups, etc.).
+
+Failure semantics: ANY SDK exception on a mapped path falls back to the CLI
+invocation — worst case = today's behavior, never worse.
+``AISC_DOCKER_EXECUTOR=cli`` restores the pure-CLI executor globally.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+from aisc.domain.models import DockerPreflightResult, ProcessResult
+
+# Templates the ps renderer understands — every token must be one of
+# ID / Names / Image / Status / Label "k". Anything else → CLI fallback.
+_PS_TOKEN = re.compile(r'\{\{\.(ID|Names|Image|Status|Label "([^"]+)")\}\}')
+
+
+def _render_ps_line(template: str, c: Any) -> Optional[str]:
+    """Render one docker-ps line for a SDK container object.
+
+    ``Status`` synthesizes the CLI's human form ("Up"/"Exited") — the only
+    property consumers rely on is ``startswith("Up")`` (runtime.py
+    ``_docker_status_to_state``)."""
+    out: List[str] = []
+    pos = 0
+    for m in _PS_TOKEN.finditer(template):
+        out.append(template[pos : m.start()])
+        label_key = m.group(2)
+        try:
+            if label_key is not None:
+                labels = c.attrs.get("Labels")
+                if labels is None:
+                    labels = c.attrs.get("Config", {}).get("Labels", {})
+                out.append(str(labels.get(label_key, "")))
+            elif m.group(1) == "Status":
+                # containers.list() is backed by /containers/json, where State
+                # is a string ("running"/"paused"/"exited"), unlike inspect.
+                state = c.attrs.get("State", "")
+                running = (
+                    bool(state.get("Running"))
+                    if isinstance(state, dict)
+                    else str(state).lower() in {"running", "paused"}
+                )
+                out.append("Up" if running else "Exited")
+            elif m.group(1) == "ID":
+                out.append(str(c.id)[:12])
+            elif m.group(1) == "Names":
+                names = list(c.attrs.get("Names") or [])
+                if names:
+                    rendered = ",".join(name.lstrip("/") for name in names)
+                else:
+                    rendered = str(c.name).lstrip("/")
+                out.append(rendered)
+            elif m.group(1) == "Image":
+                # Avoid `c.image`: it triggers an extra image inspect. Sparse
+                # list payloads expose Image directly; inspect payloads expose
+                # Config.Image, so support both shapes without extra calls.
+                image = c.attrs.get("Config", {}).get("Image")
+                if image is None:
+                    image = c.attrs.get("Image", "")
+                out.append(str(image))
+            else:
+                return None  # unreachable; keeps the checker honest
+        except Exception:  # noqa: BLE001 — unexpected shape: bail to CLI
+            return None
+        pos = m.end()
+    out.append(template[pos:])
+    return "".join(out)
+
+
+class SdkBackedDockerExecutor:
+    """DockerExecutor protocol with the hot-read face on the SDK."""
+
+    def __init__(self, client: Any = None):
+        self._client = client
+        from aisc.adapters.docker_ import RealDockerExecutor
+
+        self._cli = RealDockerExecutor()
+
+    # -- SDK client ------------------------------------------------------
+
+    def _sdk(self) -> Any:
+        if self._client is None:
+            from aisc.adapters.docker_gateway import _default_client
+
+            self._client = _default_client()
+        return self._client
+
+    # -- structured hot ops ----------------------------------------------
+
+    def preflight(self) -> DockerPreflightResult:
+        try:
+            self._sdk().ping()
+            return DockerPreflightResult(
+                docker_path="(sdk)", available=True, reason="ok"
+            )
+        except Exception:  # noqa: BLE001 — SDK unusable: CLI may still be
+            return self._cli.preflight()
+
+    def inspect_container(self, container_name: str) -> ProcessResult:
+        try:
+            data = self._sdk().api.inspect_container(container_name)
+            return ProcessResult(
+                stdout=json.dumps([data]), stderr="", exit_code=0
+            )
+        except Exception as exc:  # noqa: BLE001
+            import docker.errors
+
+            if isinstance(exc, docker.errors.NotFound):
+                return ProcessResult(
+                    stdout="",
+                    stderr=f"Error: No such object: {container_name}",
+                    exit_code=1,
+                )
+            # Transient/unknown: CLI fallback preserves today's semantics.
+            return self._cli.inspect_container(container_name)
+
+    # -- free argv: map the three hot shapes, CLI for the rest ------------
+
+    def run_captured(
+        self,
+        docker_argv: List[str],
+        *,
+        timeout: Optional[float] = None,
+        input_text: Optional[str] = None,
+    ) -> ProcessResult:
+        try:
+            if docker_argv and docker_argv[0] == "ps":
+                # ps is read-only and does not consume stdin; SDK execution can
+                # preserve this shape even when the caller sets a CLI timeout.
+                mapped = self._run_ps(docker_argv)
+                if mapped is not None:
+                    return mapped
+            elif (
+                docker_argv
+                and docker_argv[0] == "exec"
+                # exec is the only hot shape where the CLI timeout/input
+                # semantics differ materially from the mapped SDK call. Never
+                # silently drop either argument.
+                and timeout is None
+                and input_text is None
+            ):
+                mapped = self._run_exec(docker_argv)
+                if mapped is not None:
+                    return mapped
+            elif docker_argv and docker_argv[0] == "inspect" and len(docker_argv) == 2:
+                return self.inspect_container(docker_argv[1])
+        except Exception:  # noqa: BLE001 — any mapping trouble: CLI path
+            pass
+        return self._cli.run_captured(
+            docker_argv, timeout=timeout, input_text=input_text
+        )
+
+    def _run_ps(self, argv: List[str]) -> Optional[ProcessResult]:
+        filters: Dict[str, List[str]] = {}
+        template: Optional[str] = None
+        all_flag = False
+        i = 1
+        while i < len(argv):
+            a = argv[i]
+            if a in ("-a", "--all"):
+                all_flag = True
+            elif a == "--filter" and i + 1 < len(argv):
+                f = argv[i + 1]
+                if not f.startswith("label="):
+                    return None  # non-label filters unmapped → CLI
+                filters.setdefault("label", []).append(f[len("label=") :])
+                i += 1
+            elif a == "--format" and i + 1 < len(argv):
+                template = argv[i + 1]
+                i += 1
+            elif a.startswith("-"):
+                return None  # unknown flag → CLI
+            i += 1
+        if template is None:
+            return None
+        # Docker's format language is larger than the field set mapped here.
+        # Reject any unknown field token before fetching so a new caller shape
+        # falls back to CLI instead of rendering the template literally.
+        if "{{" in _PS_TOKEN.sub("", template):
+            return None
+        # sparse=True keeps this as one /containers/json request. The default
+        # list() call performs an additional container inspect per row.
+        containers = self._sdk().containers.list(
+            all=all_flag, filters=filters or None, sparse=True
+        )
+        lines = []
+        for c in containers:
+            line = _render_ps_line(template, c)
+            if line is None:
+                return None
+            lines.append(line)
+        return ProcessResult(stdout="\n".join(lines), stderr="", exit_code=0)
+
+    def _run_exec(self, argv: List[str]) -> Optional[ProcessResult]:
+        # Plain `exec <name> <cmd...>` only — flags (-e/-u/-w/...) between
+        # "exec" and the container name are unmapped (the command TAIL may
+        # contain anything, including dash-prefixed tool args like --json).
+        if len(argv) < 3 or argv[1].startswith("-"):
+            return None
+        container_name, cmd = argv[1], argv[2:]
+        api = self._sdk().api
+        exec_id = api.exec_create(container_name, cmd, stdout=True, stderr=True)
+        # demux=True is required for CLI parity: without it docker-py merges the
+        # multiplexed stdout/stderr stream and JSON consumers can silently see
+        # warnings/error frames mixed into stdout.
+        result = api.exec_start(exec_id, socket=False, tty=False, demux=True)
+        if not (isinstance(result, tuple) and len(result) == 2):
+            return None
+        raw_stdout, raw_stderr = result
+
+        def _decode(value: Any) -> str:
+            if value is None:
+                return ""
+            if isinstance(value, bytes):
+                return value.decode("utf-8", "replace")
+            if isinstance(value, str):
+                return value
+            return None  # type: ignore[return-value]
+
+        stdout = _decode(raw_stdout)
+        stderr = _decode(raw_stderr)
+        if stdout is None or stderr is None:
+            return None
+        info = api.exec_inspect(exec_id)
+        return ProcessResult(
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=int(info.get("ExitCode", 0) or 0),
+        )
+
+    # -- everything else: verbatim CLI delegation --------------------------
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__.get("_cli"), name)
+
+
+def default_executor() -> Any:
+    """Command-layer executor factory (PERF P4).
+
+    ``AISC_DOCKER_EXECUTOR=cli`` restores the pure-CLI executor; tests pass
+    their own ``executor`` as before (the factory only feeds the ``or``
+    default)."""
+    if os.environ.get("AISC_DOCKER_EXECUTOR", "").lower() == "cli":
+        from aisc.adapters.docker_ import RealDockerExecutor
+
+        return RealDockerExecutor()
+    return SdkBackedDockerExecutor()

aisc/adapters/maintenance_lock.py

@@ -0,0 +1,97 @@
+"""Docker maintenance lock (A0 / docker-ownership-foundation).
+
+Cross-process lock serializing host-level Docker resource mutations:
+installer scan/cleanup/rebuild, ``aisc build`` writes to the default
+workstation tag, runtime create/start resolving the default tag to an
+image ID, and reconcile's removal critical sections
+(docker-resource-lifecycle 02-domain-contract.md §4.1,
+05-cross-plan-coordination.md §4).
+
+FROZEN LOCK ORDER (violating it deadlocks — enforced by convention and
+reviewed in tests/docs, not by the runtime):
+
+    docker-maintenance.lock  ->  workspace lock  ->  registry transaction
+
+The lock file lives at ``<data-root>/state/locks/docker-maintenance.lock``
+via the frozen DataRootStore layout (domain/data_root.py LOCKS_SUBDIR —
+the plans' ``<data-root>/locks/`` notation resolves to this contract
+path; consumers never concatenate paths themselves).
+
+The acquisition timeout must outlast the longest legitimate holder (a
+no-cache workstation rebuild takes minutes); callers may lower it when
+they know the contention window is short.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+from aisc.adapters.data_root_store import SCOPE_SHARED, DataRootStore
+from aisc.domain.data_root import ERR_LOCK_TIMEOUT
+
+#: Lock name; ``DataRootStore.lock_path_for`` turns this into
+#: ``state/locks/docker-maintenance.lock`` under the shared scope.
+MAINTENANCE_LOCK_NAME = "docker-maintenance"
+
+#: Stable error code surfaced when acquisition times out.
+ERR_MAINTENANCE_LOCK_TIMEOUT = "AISC_ERR_MAINTENANCE_LOCK_TIMEOUT"
+
+#: Default acquisition timeout (seconds) — sized to survive a no-cache
+#: rebuild holding the lock, not just metadata mutations.
+MAINTENANCE_LOCK_TIMEOUT = 300.0
+
+
+@contextmanager
+def docker_maintenance_lock(
+    store: DataRootStore,
+    timeout: float = MAINTENANCE_LOCK_TIMEOUT,
+) -> Iterator[None]:
+    """Hold the Docker maintenance lock.
+
+    Raises ``CliError(ERR_MAINTENANCE_LOCK_TIMEOUT)`` on timeout — the
+    caller must NOT proceed to mutate Docker resources without the lock
+    (fail-closed). Acquire this BEFORE any workspace/registry lock.
+    """
+    with store.lock(
+        MAINTENANCE_LOCK_NAME,
+        timeout,
+        scope=SCOPE_SHARED,
+        error_code=ERR_MAINTENANCE_LOCK_TIMEOUT,
+    ):
+        yield
+
+
+def maintenance_lock_path(store: DataRootStore):
+    """Canonical lock file path (contract: ``state/locks/<name>.lock``)."""
+    return store.lock_path_for(MAINTENANCE_LOCK_NAME, scope=SCOPE_SHARED)
+
+
+@contextmanager
+def docker_maintenance_lock_at_root(
+    data_root,
+    timeout: float = MAINTENANCE_LOCK_TIMEOUT,
+) -> Iterator[None]:
+    """Same lock, addressed by the data ROOT directly (installer-side
+    callers have no workspace to resolve a store with). Identical file —
+    both entries serialize against each other."""
+    from aisc.adapters.data_root_store import file_lock
+    from aisc.domain.data_root import LOCKS_SUBDIR
+
+    lock_path = Path(str(data_root)).joinpath(*LOCKS_SUBDIR.split("/")) / (
+        MAINTENANCE_LOCK_NAME + ".lock"
+    )
+    with file_lock(lock_path, timeout, error_code=ERR_MAINTENANCE_LOCK_TIMEOUT):
+        yield
+
+
+# Re-exported for callers that construct their own timeout errors.
+__all__ = [
+    "MAINTENANCE_LOCK_NAME",
+    "MAINTENANCE_LOCK_TIMEOUT",
+    "ERR_MAINTENANCE_LOCK_TIMEOUT",
+    "ERR_LOCK_TIMEOUT",
+    "docker_maintenance_lock",
+    "maintenance_lock_path",
+]

aisc/adapters/state_file.py

@@ -0,0 +1,184 @@
+"""State file adapter — read/write ``.aisc/state.env`` for container discovery.
+
+Provides atomic writes via temp-file + rename. Only allows known safe keys.
+Preserves existing keys, comments, and blank lines where practical.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# Known safe keys — only these may be written to state.env.
+# Container-name keys (CONTAINER_NAME, IMAGE) live in containers.json now;
+# state.env retains only boolean flag keys.
+_KNOWN_KEYS = frozenset({
+    "DO_RUN",
+    "PROXY_ENABLED",
+})
+
+# Regex for valid key names: uppercase alphanumeric + underscore, starts with letter
+_VALID_KEY_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+# Shell metacharacters / injection characters rejected from all values
+_SHELL_META_RE = re.compile(r'[\r\n\0`$\'";&|<>]')
+
+# Boolean flags
+_BOOL_VALUES = frozenset({"0", "1"})
+
+
+def _validate_value(key: str, value: str) -> None:
+    """Validate *value* against field-specific rules plus shell-metacharacter ban.
+
+    Raises ValueError with a descriptive message on any violation.
+    """
+    if not value:
+        return
+
+    # --- shell metacharacter / whitespace / control check (all keys) ---
+    if _SHELL_META_RE.search(value) or " " in value or "\t" in value:
+        raise ValueError(
+            f"State value for '{key}' contains prohibited characters "
+            f"(shell metacharacters, whitespace, or control chars)"
+        )
+
+    # --- field-specific checks ---
+    if key in ("DO_RUN", "PROXY_ENABLED"):
+        if value not in _BOOL_VALUES:
+            raise ValueError(
+                f"{key} must be 0 or 1, got: {value!r}"
+            )
+
+
+def _parse_state_file(path: Path) -> List[Tuple[str, Optional[str], Optional[str]]]:
+    """Parse state.env into (key, value, raw_comment) triples.
+
+    Returns a list of (key, value, comment) where:
+    - key: the KEY name (empty string for comment/blank lines)
+    - value: the value after '=' (None for comments)
+    - comment: full raw line text for comments/blanks (None for key=value lines)
+
+    Duplicate keys use deterministic **last-wins** semantics (consistent with
+    shell ``source`` / ``set -a`` behaviour).
+    """
+    entries: List[Tuple[str, Optional[str], Optional[str]]] = []
+    if not path.is_file():
+        return entries
+
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            stripped = line.rstrip("\n\r")
+            # Comments and blank lines preserved as-is
+            if not stripped or stripped.startswith("#"):
+                entries.append(("", None, stripped))
+                continue
+            # Parse KEY=VALUE
+            if "=" in stripped:
+                key, _, value = stripped.partition("=")
+                key = key.strip()
+                if _VALID_KEY_RE.match(key):
+                    # Last-wins: replace previous entry for same key
+                    for i in range(len(entries) - 1, -1, -1):
+                        if entries[i][0] == key:
+                            entries[i] = (key, value, None)
+                            break
+                    else:
+                        entries.append((key, value, None))
+                else:
+                    # Malformed key — preserve as comment to avoid corruption
+                    entries.append(("", None, stripped))
+            else:
+                # Line without '=' — treat as comment
+                entries.append(("", None, stripped))
+    return entries
+
+
+def read_state_key(root: Path, key: str) -> Optional[str]:
+    """Read a single key from ``<root>/state.env`` (Stage 7: *root* is the
+    state directory itself — data-root ``workspaces/<hash>/runtime`` or the
+    legacy ``<workspace>/.aisc``; resolved by callers, never appended here).
+
+    Returns the value string, or ``None`` if the key or file is absent.
+    Duplicate keys resolve to last occurrence (shell-consistent).
+    """
+    state_path = root / "state.env"
+    entries = _parse_state_file(state_path)
+    # Walk backwards to find last occurrence (last-wins)
+    for entry_key, value, _comment in reversed(entries):
+        if entry_key == key:
+            return value
+    return None
+
+
+def write_state_keys(root: Path, updates: Dict[str, str]) -> None:
+    """Atomically write key=value pairs into ``<root>/.aisc/state.env``.
+
+    Preserves existing keys and comments. Only writes keys that are in
+    ``_KNOWN_KEYS``.  Raises ``ValueError`` for unknown keys or values
+    containing ``\\r``, ``\\n``, or NUL.  Silently skips keys with empty values.
+
+    Uses temp-file + rename for atomicity.
+    Errors during write do not corrupt the existing file.
+    """
+    for k in updates:
+        if k not in _KNOWN_KEYS:
+            raise ValueError(
+                f"Unknown state key '{k}'. Allowed: {sorted(_KNOWN_KEYS)}"
+            )
+
+    # Validate values before touching filesystem
+    for k, v in updates.items():
+        _validate_value(k, v)
+
+    state_dir = root  # Stage 7: root IS the state directory
+    state_dir.mkdir(parents=True, exist_ok=True)
+
+    state_path = state_dir / "state.env"
+
+    # Read existing entries
+    existing = _parse_state_file(state_path) if state_path.is_file() else []
+
+    # Build merged: last-wins for duplicate keys, update existing, keep others
+    new_entries: List[Tuple[str, Optional[str], Optional[str]]] = []
+    seen_keys: set = set()
+
+    for entry_key, value, comment in existing:
+        if entry_key and entry_key in updates:
+            new_val = updates[entry_key]
+            if new_val:
+                new_entries.append((entry_key, new_val, None))
+            else:
+                new_entries.append((entry_key, value, None))
+            seen_keys.add(entry_key)
+        else:
+            new_entries.append((entry_key, value, comment))
+
+    # Append any new keys not already present
+    for k, v in updates.items():
+        if k not in seen_keys and v:
+            new_entries.append((k, v, None))
+
+    # Write atomically via temp file
+    fd, tmp_path = tempfile.mkstemp(
+        prefix=".state_", dir=str(state_dir), text=True
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            for entry_key, value, comment in new_entries:
+                if comment is not None:
+                    f.write(comment + "\n")
+                elif entry_key:
+                    f.write(f"{entry_key}={value}\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_path, str(state_path))
+    except Exception:
+        # Clean up temp file on failure
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise

aisc/adapters/system.py

@@ -0,0 +1,101 @@
+"""System / process adapter — narrow interface for command execution."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Protocol, List, Optional, runtime_checkable
+
+from aisc.domain.models import ProcessResult
+
+
+@runtime_checkable
+class ProcessRunner(Protocol):
+    """Protocol for running subprocess commands (testable via injection)."""
+
+    def run(
+        self,
+        argv: List[str],
+        timeout: Optional[float] = None,
+    ) -> ProcessResult:
+        """Execute *argv* and return a ``ProcessResult``."""
+        ...
+
+
+class RealProcessRunner:
+    """Real subprocess runner — shell=False, text capture, timeout support.
+
+    Uses ``encoding='utf-8'``, ``errors='replace'``.
+    Catches ``FileNotFoundError`` → ``command_not_found``.
+    Catches generic ``OSError`` → ``command_not_found`` (e.g. permission,
+    broken symlink).
+    ``subprocess.TimeoutExpired`` → ``timed_out``.
+    """
+
+    def run(
+        self,
+        argv: List[str],
+        timeout: Optional[float] = None,
+    ) -> ProcessResult:
+        """Execute *argv* in a subprocess."""
+        try:
+            proc = subprocess.run(
+                argv,
+                capture_output=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=timeout,
+            )
+            return ProcessResult(
+                stdout=proc.stdout or "",
+                stderr=proc.stderr or "",
+                exit_code=proc.returncode,
+            )
+        except FileNotFoundError:
+            return ProcessResult(
+                stdout="",
+                stderr=f"command not found: {argv[0] if argv else ''}",
+                exit_code=-1,
+                command_not_found=True,
+            )
+        except subprocess.TimeoutExpired:
+            return ProcessResult(
+                stdout="",
+                stderr="command timed out",
+                exit_code=-1,
+                timed_out=True,
+            )
+        except OSError as exc:
+            return ProcessResult(
+                stdout="",
+                stderr=f"command error: {exc}",
+                exit_code=-1,
+                command_not_found=True,
+            )
+
+    def run_streaming(
+        self,
+        argv: List[str],
+        timeout: Optional[float] = None,
+    ) -> ProcessResult:
+        """Execute an interactive command with inherited terminal streams."""
+        try:
+            proc = subprocess.run(argv, timeout=timeout)
+            return ProcessResult(exit_code=proc.returncode)
+        except FileNotFoundError:
+            return ProcessResult(
+                stderr=f"command not found: {argv[0] if argv else ''}",
+                exit_code=-1,
+                command_not_found=True,
+            )
+        except subprocess.TimeoutExpired:
+            return ProcessResult(
+                stderr="command timed out",
+                exit_code=-1,
+                timed_out=True,
+            )
+        except OSError as exc:
+            return ProcessResult(
+                stderr=f"command error: {exc}",
+                exit_code=-1,
+                command_not_found=True,
+            )