forkcell 0.1.0a0__py3-none-any.whl

forkcell/__init__.py

@@ -0,0 +1,7 @@
+"""ForkCell MVP package."""
+
+__version__ = "0.1.0a0"
+
+from forkcell.api import ForkCellClient, ForkCellCommandError, ForkCellSandbox
+
+__all__ = ["ForkCellClient", "ForkCellCommandError", "ForkCellSandbox", "__version__"]

forkcell/api.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+
+class ForkCellCommandError(RuntimeError):
+    def __init__(self, args: list[str], returncode: int, stdout: str, stderr: str) -> None:
+        self.args_list = args
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        super().__init__(
+            f"forkcell command failed ({returncode}): {' '.join(args)}\nstdout:\n{stdout}\nstderr:\n{stderr}"
+        )
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    args: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+    json: dict[str, Any]
+
+
+def _extract_json_object(text: str) -> dict[str, Any]:
+    decoder = json.JSONDecoder()
+    for index, char in enumerate(text):
+        if char != "{":
+            continue
+        try:
+            value, end = decoder.raw_decode(text[index:])
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict) and not text[index + end :].strip():
+            return value
+    raise ValueError("missing JSON object in command output")
+
+
+def _normalize_command(command: str | Iterable[str]) -> list[str]:
+    if isinstance(command, str):
+        return ["sh", "-lc", command]
+    return [str(part) for part in command]
+
+
+LEGACY_BACKEND_ALIASES = {
+    "openshell-native-overlay": "native-overlay",
+    "openshell-layer-clone": "layer-clone",
+    "openshell-volume": "volume-delta",
+}
+
+
+def _normalize_backend(backend: str) -> str:
+    return LEGACY_BACKEND_ALIASES.get(backend, backend)
+
+
+class ForkCellClient:
+    """Small Python facade for agent-style ForkCell workflows.
+
+    The facade intentionally shells out to `python -m forkcell.cli` so the API
+    and CLI share the same state, receipts, and review artifacts during the
+    current governed-runtime integration.
+    """
+
+    def __init__(
+        self,
+        *,
+        root: str | Path | None = None,
+        python: str | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        self.root = Path(root or Path.cwd()).resolve()
+        self.python = python or sys.executable
+        self.env = dict(os.environ)
+        if env:
+            self.env.update(env)
+
+    def cli(self, args: list[str], *, check: bool = True) -> CommandResult:
+        full_args = [self.python, "-m", "forkcell.cli", *args]
+        proc = subprocess.run(full_args, cwd=self.root, env=self.env, text=True, capture_output=True)
+        parsed: dict[str, Any] = {}
+        output = proc.stdout.strip()
+        if output:
+            try:
+                parsed = _extract_json_object(output)
+            except ValueError:
+                parsed = {}
+        if check and proc.returncode != 0:
+            raise ForkCellCommandError(full_args, proc.returncode, proc.stdout, proc.stderr)
+        return CommandResult(
+            args=full_args,
+            returncode=proc.returncode,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+            json=parsed,
+        )
+
+    def create_native_cell(
+        self,
+        *,
+        source: str | Path,
+        name: str | None = None,
+        backend: str = "native-overlay",
+    ) -> "ForkCellSandbox":
+        cell = name or f"fc-api-{uuid.uuid4().hex[:8]}"
+        self.cli(["native", "init", cell, "--from", str(Path(source).resolve())])
+        return ForkCellSandbox(client=self, name=cell, backend=_normalize_backend(backend))
+
+    def native_cell(self, name: str, *, backend: str = "native-overlay") -> "ForkCellSandbox":
+        return ForkCellSandbox(client=self, name=name, backend=_normalize_backend(backend))
+
+    def review_status(self) -> dict[str, Any]:
+        return self.cli(["review", "status", "--format", "json"]).json
+
+
+@dataclass
+class ForkCellSandbox:
+    client: ForkCellClient
+    name: str
+    backend: str = "native-overlay"
+    auto_delete: bool = True
+
+    def __post_init__(self) -> None:
+        self.backend = _normalize_backend(self.backend)
+
+    def __enter__(self) -> "ForkCellSandbox":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        if self.auto_delete:
+            self.delete(check=False)
+
+    def status(self) -> dict[str, Any]:
+        return self.client.cli(["native", "status", self.name]).json
+
+    def checkpoint(self, *, name: str | None = None) -> dict[str, Any]:
+        args = ["native", "checkpoint", self.name]
+        if name:
+            args.extend(["--name", name])
+        return self.client.cli(args).json
+
+    def restore(self, checkpoint: str | None = None) -> dict[str, Any]:
+        args = ["native", "restore", self.name]
+        if checkpoint:
+            args.append(checkpoint)
+        return self.client.cli(args).json
+
+    def run(
+        self,
+        command: str | Iterable[str],
+        *,
+        checkpoint_before: bool = False,
+        checkpoint_name: str | None = None,
+        restore_on_fail: bool = False,
+        policy: str | Path | None = None,
+        logs_since: str = "5m",
+    ) -> dict[str, Any]:
+        if self.backend == "native-overlay":
+            args = ["native", "run"]
+        elif self.backend == "layer-clone":
+            args = ["native", "run-layer"]
+        else:
+            args = ["run", self.name, "--backend", self.backend]
+        if checkpoint_before:
+            args.append("--checkpoint-before")
+        if checkpoint_name:
+            args.extend(["--checkpoint-name", checkpoint_name])
+        if restore_on_fail:
+            args.append("--restore-on-fail")
+        if policy:
+            args.extend(["--policy", str(policy)])
+        if logs_since:
+            args.extend(["--logs-since", logs_since])
+        if self.backend in {"native-overlay", "layer-clone"}:
+            args.append(self.name)
+        args.extend(["--", *_normalize_command(command)])
+        run = self.client.cli(args).json
+        receipt = Path(run.get("receipt", ""))
+        if receipt.exists():
+            return json.loads(receipt.read_text())
+        return run
+
+    def delete(self, *, check: bool = True) -> dict[str, Any]:
+        return self.client.cli(["native", "delete", self.name], check=check).json

forkcell/checkpoint.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import shlex
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class OpenShellRunner(Protocol):
+    def __call__(self, args: list[str], *, check: bool = False) -> Any:
+        ...
+
+
+@dataclass(frozen=True)
+class CheckpointArtifact:
+    path: Path
+    sha256: str
+    metrics: dict[str, Any]
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def artifact_name(checkpoint_id: str) -> str:
+    return f"{checkpoint_id}.tgz"
+
+
+def remote_path(workspace: str, name: str) -> str:
+    return f"{workspace.rstrip('/')}/{name}"
+
+
+class CheckpointProvider(Protocol):
+    provider_name: str
+
+    def create(self, *, cell_name: str, workspace: str, checkpoint_id: str) -> CheckpointArtifact:
+        ...
+
+    def restore(self, *, cell_name: str, workspace: str, artifact: Path) -> dict[str, Any]:
+        ...
+
+
+class OpenShellTarFullProvider:
+    """Portable baseline provider: full workspace tar over OpenShell upload/download."""
+
+    provider_name = "openshell-tar-full"
+
+    def __init__(self, *, openshell: OpenShellRunner, checkpoint_dir: Path) -> None:
+        self._openshell = openshell
+        self._checkpoint_dir = checkpoint_dir
+
+    def create(self, *, cell_name: str, workspace: str, checkpoint_id: str) -> CheckpointArtifact:
+        started = time.perf_counter()
+        before_stats = self._workspace_stats(cell_name, workspace)
+        remote_name = f".forkcell_{artifact_name(checkpoint_id)}"
+        remote_tar = remote_path(workspace, remote_name)
+        local_tar = self._checkpoint_dir / artifact_name(checkpoint_id)
+        local_tar.parent.mkdir(parents=True, exist_ok=True)
+
+        workspace_q = shlex.quote(workspace)
+        remote_name_q = shlex.quote(remote_name)
+        remote_tar_q = shlex.quote(remote_tar)
+        # GNU tar may return 1 when files change while archiving; keep that as degraded success.
+        tar_script = (
+            f"tar -C {workspace_q} --exclude {remote_name_q} -czf {remote_tar_q} .; "
+            "rc=$?; [ $rc -le 1 ] || exit $rc"
+        )
+        self._openshell(["sandbox", "exec", "--name", cell_name, "sh", "-lc", tar_script], check=True)
+        try:
+            self._openshell(["sandbox", "download", cell_name, remote_tar, str(local_tar)], check=True)
+        finally:
+            self._openshell(["sandbox", "exec", "--name", cell_name, "rm", "-f", remote_tar], check=False)
+
+        duration_ms = int(round((time.perf_counter() - started) * 1000))
+        metrics: dict[str, Any] = {
+            "provider": self.provider_name,
+            "operation": "checkpoint_create",
+            "duration_ms": duration_ms,
+            "workspace": workspace,
+            "workspace_file_count": before_stats.get("file_count"),
+            "workspace_bytes": before_stats.get("bytes"),
+            "artifact_bytes": local_tar.stat().st_size,
+            "local_artifact": str(local_tar),
+            "full_archive": True,
+        }
+        if before_stats.get("error"):
+            metrics["workspace_stats_error"] = before_stats["error"]
+        return CheckpointArtifact(path=local_tar, sha256=sha256_file(local_tar), metrics=metrics)
+
+    def restore(self, *, cell_name: str, workspace: str, artifact: Path) -> dict[str, Any]:
+        started = time.perf_counter()
+        if not artifact.exists():
+            raise FileNotFoundError(str(artifact))
+
+        remote_name = f".forkcell_restore_{artifact.name}"
+        remote_tar = remote_path(workspace, remote_name)
+        self._openshell(["sandbox", "upload", cell_name, str(artifact), remote_tar], check=True)
+
+        workspace_q = shlex.quote(workspace)
+        remote_name_q = shlex.quote(remote_name)
+        remote_tar_q = shlex.quote(remote_tar)
+        cleanup_script = (
+            f"set -e; mkdir -p {workspace_q}; "
+            f"find {workspace_q} -mindepth 1 -maxdepth 1 ! -name {remote_name_q} -exec rm -rf {{}} +; "
+            f"tar -C {workspace_q} -xzf {remote_tar_q}; rm -f {remote_tar_q}"
+        )
+        self._openshell(["sandbox", "exec", "--name", cell_name, "sh", "-lc", cleanup_script], check=True)
+
+        after_stats = self._workspace_stats(cell_name, workspace)
+        duration_ms = int(round((time.perf_counter() - started) * 1000))
+        metrics: dict[str, Any] = {
+            "provider": self.provider_name,
+            "operation": "checkpoint_restore",
+            "duration_ms": duration_ms,
+            "workspace": workspace,
+            "workspace_file_count_after": after_stats.get("file_count"),
+            "workspace_bytes_after": after_stats.get("bytes"),
+            "artifact_bytes": artifact.stat().st_size,
+            "local_artifact": str(artifact),
+            "full_archive": True,
+        }
+        if after_stats.get("error"):
+            metrics["workspace_stats_error"] = after_stats["error"]
+        return metrics
+
+    def _workspace_stats(self, cell_name: str, workspace: str) -> dict[str, Any]:
+        workspace_q = shlex.quote(workspace)
+        script = (
+            f"cd {workspace_q}; "
+            "files=$(find . -mindepth 1 -type f | wc -l | tr -d ' '); "
+            "bytes=$(find . -mindepth 1 -type f -exec wc -c {} + 2>/dev/null "
+            "| awk '{s += $1} END {print s + 0}'); "
+            "printf '{\"file_count\":%s,\"bytes\":%s}\\n' \"$files\" \"$bytes\""
+        )
+        result = self._openshell(["sandbox", "exec", "--name", cell_name, "sh", "-lc", script], check=False)
+        if result.returncode != 0:
+            return {"file_count": None, "bytes": None, "error": (result.stderr or result.stdout)[-500:]}
+        try:
+            return json.loads(result.stdout.strip().splitlines()[-1])
+        except Exception as exc:
+            return {"file_count": None, "bytes": None, "error": f"parse_failed: {exc}"}