flywheel-bootstrap-staging 0.1.9.202601271835__py3-none-any.whl

bootstrap/__init__.py

@@ -0,0 +1,3 @@
+"""Bootstrap package."""
+
+__all__ = []

bootstrap/__main__.py

@@ -0,0 +1,48 @@
+"""CLI entry point for the bootstrap flow.
+
+Usage (placeholder):
+    python -m bootstrap --run-id <id> --token <token> --config /path/to/config.toml
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from bootstrap.orchestrator import BootstrapOrchestrator, build_config
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Flywheel BYOC bootstrapper")
+    parser.add_argument(
+        "--run-id",
+        help="Run identifier issued by the Flywheel backend (falls back to FLYWHEEL_RUN_ID)",
+        default=None,
+    )
+    parser.add_argument(
+        "--token",
+        help="Capability token for authenticating to the backend (or FLYWHEEL_RUN_TOKEN)",
+        default=None,
+    )
+    parser.add_argument(
+        "--server",
+        help="Backend base URL (default: http://localhost:8000 or FLYWHEEL_SERVER)",
+        default=None,
+    )
+    parser.add_argument(
+        "--config",
+        help="Path to the Codex config.toml file",
+        required=True,
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv or sys.argv[1:])
+    config = build_config(args)
+    orchestrator = BootstrapOrchestrator(config)
+    return orchestrator.run()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bootstrap/artifacts.py

@@ -0,0 +1,101 @@
+"""Artifact manifest helpers."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Mapping, Sequence
+
+logger = logging.getLogger(__name__)
+
+
+class ManifestStatus(Enum):
+    """Outcome of reading the artifact manifest."""
+
+    MISSING = "missing"
+    VALID = "valid"
+    MALFORMED = "malformed"
+
+
+@dataclass
+class ManifestResult:
+    """Result of reading the artifact manifest, with diagnostic info."""
+
+    status: ManifestStatus
+    artifacts: Sequence[Mapping[str, object]]
+    error: str | None = None
+
+
+def read_manifest(manifest_path: Path) -> ManifestResult:
+    """Load artifact entries from the manifest path.
+
+    Tolerant of common LLM output variations:
+    - A well-formed JSON list is returned as-is.
+    - A dict wrapping a list (e.g. ``{"artifacts": [...]}``) is unwrapped.
+    - A single artifact dict is wrapped in a list.
+    - Truncated / invalid JSON is reported as malformed.
+    - Non-dict, non-list scalars are reported as malformed.
+
+    Returns a ``ManifestResult`` carrying the parsed artifacts, the outcome
+    status, and an optional human-readable error description for feedback.
+    """
+    if not manifest_path.exists():
+        return ManifestResult(status=ManifestStatus.MISSING, artifacts=[])
+    raw = manifest_path.read_text(encoding="utf-8")
+    if not raw.strip():
+        msg = "artifact manifest file is empty"
+        logger.warning("%s: %s", msg, manifest_path)
+        return ManifestResult(status=ManifestStatus.MALFORMED, artifacts=[], error=msg)
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        msg = f"artifact manifest contains invalid JSON: {exc}"
+        logger.warning("%s: %s", msg, manifest_path)
+        return ManifestResult(status=ManifestStatus.MALFORMED, artifacts=[], error=msg)
+    return _coerce_manifest(data, manifest_path)
+
+
+def _coerce_manifest(data: object, manifest_path: Path) -> ManifestResult:
+    """Best-effort coercion of parsed JSON into a list of artifact dicts."""
+    if isinstance(data, list):
+        return ManifestResult(status=ManifestStatus.VALID, artifacts=data)
+    if isinstance(data, dict):
+        return _unwrap_dict(data, manifest_path)
+    msg = f"artifact manifest is a {type(data).__name__}, expected a JSON list"
+    logger.warning("%s: %s", msg, manifest_path)
+    return ManifestResult(status=ManifestStatus.MALFORMED, artifacts=[], error=msg)
+
+
+def _unwrap_dict(data: dict[str, object], manifest_path: Path) -> ManifestResult:
+    """Extract an artifact list from a dict, or treat it as a single artifact."""
+    # If the dict itself looks like an artifact, treat it as one.
+    # Check this BEFORE scanning for nested lists — a single artifact dict
+    # like {"artifact_type": "text", "payload": {"items": [...]}} must not
+    # have its nested list mistakenly extracted.
+    if "artifact_type" in data:
+        msg = "artifact manifest is a single artifact dict, wrapping in list"
+        logger.warning("%s: %s", msg, manifest_path)
+        return ManifestResult(
+            status=ManifestStatus.MALFORMED, artifacts=[data], error=msg
+        )
+    # Prefer the "artifacts" key if present and is a list.
+    if "artifacts" in data and isinstance(data["artifacts"], list):
+        msg = "artifact manifest wrapped in dict with 'artifacts' key, unwrapping"
+        logger.warning("%s: %s", msg, manifest_path)
+        return ManifestResult(
+            status=ManifestStatus.MALFORMED, artifacts=data["artifacts"], error=msg
+        )
+    # Fall back to the first value that is a list.
+    for key, value in data.items():
+        if isinstance(value, list):
+            msg = f"artifact manifest wrapped in dict with '{key}' key, unwrapping"
+            logger.warning("%s: %s", msg, manifest_path)
+            return ManifestResult(
+                status=ManifestStatus.MALFORMED, artifacts=value, error=msg
+            )
+    msg = "artifact manifest is a dict with no recognisable artifact data"
+    logger.warning("%s: %s", msg, manifest_path)
+    return ManifestResult(status=ManifestStatus.MALFORMED, artifacts=[], error=msg)

bootstrap/config_loader.py

@@ -0,0 +1,122 @@
+"""Codex config parsing helpers (skeleton)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+import tomllib
+
+
+@dataclass
+class UserConfig:
+    """Parsed subset of Codex config relevant to bootstrap."""
+
+    raw: Mapping[str, Any]
+    working_dir: Path | None
+    sandbox_mode: str | None
+    approval_policy: str | None
+    oss_provider: str | None
+    writable_roots: tuple[Path, ...]
+    workspace_instructions: str
+    instructions_source: str
+    warnings: tuple[str, ...] = ()
+
+
+def load_codex_config(path: Path) -> UserConfig:
+    """Load and extract relevant fields from the user's Codex config."""
+
+    with path.open("rb") as fp:
+        data = tomllib.load(fp)
+
+    flywheel_raw = data.get("flywheel")
+    flywheel_section: Mapping[str, Any] = (
+        flywheel_raw if isinstance(flywheel_raw, Mapping) else {}
+    )
+
+    inline_instructions = _get_str(flywheel_section, "workspace_instructions")
+    instructions_file = _get_path(flywheel_section, "workspace_instructions_file", path)
+
+    warnings: list[str] = []
+    if instructions_file is not None and inline_instructions:
+        warnings.append(
+            "workspace_instructions ignored because workspace_instructions_file is set"
+        )
+
+    if instructions_file is not None:
+        try:
+            instructions_text = instructions_file.read_text(encoding="utf-8").strip()
+        except FileNotFoundError as exc:
+            raise SystemExit(
+                f"workspace_instructions_file not found: {instructions_file}"
+            ) from exc
+        if not instructions_text:
+            raise SystemExit(
+                f"workspace_instructions_file is empty: {instructions_file}"
+            )
+        source = "file"
+    else:
+        instructions_text = inline_instructions.strip() if inline_instructions else ""
+        source = "inline"
+
+    if not instructions_text:
+        raise SystemExit(
+            "workspace instructions are required; set [flywheel].workspace_instructions "
+            "or [flywheel].workspace_instructions_file"
+        )
+
+    # Best-effort extraction; Codex config schema may evolve.
+    working_dir = _get_path(data, "cd") or _get_path(data, "workspace_dir")
+    sandbox_mode = (
+        data.get("sandbox_mode") if isinstance(data.get("sandbox_mode"), str) else None
+    )
+    approval_policy = (
+        data.get("approval_policy")
+        if isinstance(data.get("approval_policy"), str)
+        else None
+    )
+    oss_provider = (
+        data.get("oss_provider") if isinstance(data.get("oss_provider"), str) else None
+    )
+
+    writable_roots: tuple[Path, ...] = tuple()
+    sandbox_write = data.get("sandbox_workspace_write")
+    if isinstance(sandbox_write, dict):
+        roots = sandbox_write.get("writable_roots")
+        if isinstance(roots, list):
+            writable_roots = tuple(
+                Path(str(r)).expanduser().resolve() for r in roots if isinstance(r, str)
+            )
+
+    return UserConfig(
+        raw=data,
+        working_dir=working_dir,
+        sandbox_mode=sandbox_mode,
+        approval_policy=approval_policy,
+        oss_provider=oss_provider,
+        writable_roots=writable_roots,
+        workspace_instructions=instructions_text,
+        instructions_source=source,
+        warnings=tuple(warnings),
+    )
+
+
+def _get_path(
+    data: Mapping[str, Any], key: str, relative_to: Path | None = None
+) -> Path | None:
+    value = data.get(key)
+    if isinstance(value, str) and value:
+        path = Path(value).expanduser()
+        if not path.is_absolute() and relative_to is not None:
+            path = (relative_to.parent / path).resolve()
+        else:
+            path = path.resolve()
+        return path
+    return None
+
+
+def _get_str(data: Mapping[str, Any], key: str) -> str | None:
+    value = data.get(key)
+    if isinstance(value, str) and value:
+        return value
+    return None

bootstrap/constants.py

@@ -0,0 +1,20 @@
+"""Shared constants for the bootstrap flow."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+DEFAULT_SERVER_URL = "http://localhost:8000"
+DEFAULT_RUN_ROOT = Path.home() / ".flywheel" / "runs"
+DEFAULT_ARTIFACT_MANIFEST = "flywheel_artifacts.json"
+HEARTBEAT_INTERVAL_SECONDS = 30
+MAX_ARTIFACT_RETRIES = 2
+
+# Environment variables that let the backend command override defaults.
+ENV_SERVER_URL = "FLYWHEEL_SERVER"
+ENV_RUN_ID = "FLYWHEEL_RUN_ID"
+ENV_RUN_TOKEN = "FLYWHEEL_RUN_TOKEN"
+
+# Codex download
+DEFAULT_CODEX_VERSION = None  # latest
+CODEX_RELEASE_BASE = "https://github.com/openai/codex/releases/latest/download"

bootstrap/git_ops.py

@@ -0,0 +1,324 @@
+"""Git operations for code persistence.
+
+This module handles:
+- Cloning repositories with authentication
+- Branch creation and checkout
+- Committing and pushing changes
+
+IMPORTANT: The GitHub token is used for git operations via HTTPS.
+It should never be exposed to the AI model - only the harness uses it.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from bootstrap.payload import RepoContext
+
+
+@dataclass
+class GitConfig:
+    """Configuration for git operations."""
+
+    workspace: Path
+    repo_context: RepoContext
+    github_token: str
+    log_fn: Callable[[str, str], None] | None = None
+
+    def log(self, level: str, message: str) -> None:
+        """Log a message using the provided log function."""
+        if self.log_fn:
+            self.log_fn(level, message)
+        else:
+            print(f"[git:{level}] {message}", file=sys.stderr)
+
+
+def _run_git(
+    args: list[str],
+    cwd: Path,
+    env: dict[str, str] | None = None,
+    capture_output: bool = True,
+) -> subprocess.CompletedProcess:
+    """Run a git command and return the result."""
+    import os
+
+    full_env = os.environ.copy()
+    if env:
+        full_env.update(env)
+
+    return subprocess.run(
+        ["git"] + args,
+        cwd=cwd,
+        capture_output=capture_output,
+        text=True,
+        env=full_env,
+    )
+
+
+def setup_git_credentials(config: GitConfig) -> bool:
+    """Configure git to use the GitHub token for authentication.
+
+    Uses the credential helper to store the token temporarily.
+    The token is only valid for 1 hour.
+
+    Returns:
+        True if setup succeeded, False otherwise.
+    """
+    workspace = config.workspace
+    token = config.github_token
+
+    # Configure git to use the token via credential helper
+    # We use a simple approach: configure the remote URL with the token embedded
+    # This is safe because the workspace is ephemeral and the token is short-lived
+
+    # First, configure git user for commits
+    result = _run_git(
+        ["config", "user.email", "flywheel@example.com"],
+        cwd=workspace,
+    )
+    if result.returncode != 0:
+        config.log("warning", f"Failed to set git email: {result.stderr}")
+
+    result = _run_git(
+        ["config", "user.name", "Flywheel"],
+        cwd=workspace,
+    )
+    if result.returncode != 0:
+        config.log("warning", f"Failed to set git name: {result.stderr}")
+
+    # Configure credential helper to cache the token
+    # We use the 'store' helper with a file in the workspace
+    credential_file = workspace / ".git-credentials"
+    repo_url = config.repo_context.repo_url
+
+    # Write credentials in the format expected by git-credential-store
+    # https://x-access-token:TOKEN@github.com
+    if "github.com" in repo_url:
+        credential_line = f"https://x-access-token:{token}@github.com\n"
+        try:
+            credential_file.write_text(credential_line)
+            credential_file.chmod(0o600)  # Restrict permissions
+
+            result = _run_git(
+                ["config", "credential.helper", f"store --file={credential_file}"],
+                cwd=workspace,
+            )
+            if result.returncode != 0:
+                config.log(
+                    "warning", f"Failed to set credential helper: {result.stderr}"
+                )
+                return False
+
+            config.log("info", "Git credentials configured")
+            return True
+        except Exception as e:
+            config.log("error", f"Failed to write credentials: {e}")
+            return False
+
+    return False
+
+
+def clone_repository(config: GitConfig) -> bool:
+    """Clone the repository to the workspace.
+
+    Returns:
+        True if clone succeeded, False otherwise.
+    """
+    repo = config.repo_context
+    workspace = config.workspace
+    token = config.github_token
+
+    # Build authenticated URL
+    # Format: https://x-access-token:TOKEN@github.com/owner/repo.git
+    auth_url = repo.repo_url.replace(
+        "https://github.com", f"https://x-access-token:{token}@github.com"
+    )
+
+    config.log("info", f"Cloning repository {repo.repo_owner}/{repo.repo_name}")
+
+    # Clone to a temp directory first, then move contents to workspace
+    # This handles the case where workspace might have existing content
+    result = _run_git(
+        ["clone", "--depth=1", "-b", repo.base_branch, auth_url, "."],
+        cwd=workspace,
+    )
+
+    if result.returncode != 0:
+        config.log("error", f"Failed to clone repository: {result.stderr}")
+        return False
+
+    config.log("info", "Repository cloned successfully")
+    return True
+
+
+def setup_branch(config: GitConfig) -> bool:
+    """Create or checkout the experiment branch.
+
+    If the branch already exists on remote, we check it out.
+    Otherwise, we create it from the base branch.
+
+    Returns:
+        True if branch setup succeeded, False otherwise.
+    """
+    repo = config.repo_context
+    workspace = config.workspace
+
+    branch_name = repo.branch_name
+    base_branch = repo.base_branch
+
+    # Fetch all branches
+    result = _run_git(["fetch", "--all"], cwd=workspace)
+    if result.returncode != 0:
+        config.log("warning", f"Failed to fetch: {result.stderr}")
+
+    # Check if branch exists on remote
+    result = _run_git(
+        ["ls-remote", "--heads", "origin", branch_name],
+        cwd=workspace,
+    )
+
+    if result.returncode == 0 and branch_name in result.stdout:
+        # Branch exists, check it out
+        config.log("info", f"Checking out existing branch: {branch_name}")
+        result = _run_git(
+            ["checkout", "-B", branch_name, f"origin/{branch_name}"],
+            cwd=workspace,
+        )
+    else:
+        # Branch doesn't exist, create from base
+        config.log("info", f"Creating new branch: {branch_name} from {base_branch}")
+        result = _run_git(
+            ["checkout", "-b", branch_name],
+            cwd=workspace,
+        )
+
+    if result.returncode != 0:
+        config.log("error", f"Failed to setup branch: {result.stderr}")
+        return False
+
+    config.log("info", f"Branch {branch_name} is ready")
+    return True
+
+
+def commit_changes(config: GitConfig, message: str) -> bool:
+    """Commit any changes in the workspace.
+
+    Returns:
+        True if commit succeeded (or no changes to commit), False on error.
+    """
+    workspace = config.workspace
+
+    # Check if there are any changes
+    result = _run_git(["status", "--porcelain"], cwd=workspace)
+    if result.returncode != 0:
+        config.log("error", f"Failed to check status: {result.stderr}")
+        return False
+
+    if not result.stdout.strip():
+        config.log("info", "No changes to commit")
+        return True
+
+    # Stage all changes
+    result = _run_git(["add", "-A"], cwd=workspace)
+    if result.returncode != 0:
+        config.log("error", f"Failed to stage changes: {result.stderr}")
+        return False
+
+    # Commit
+    result = _run_git(
+        ["commit", "-m", message],
+        cwd=workspace,
+    )
+    if result.returncode != 0:
+        config.log("error", f"Failed to commit: {result.stderr}")
+        return False
+
+    config.log("info", f"Changes committed: {message}")
+    return True
+
+
+def push_changes(config: GitConfig) -> bool:
+    """Push committed changes to the remote.
+
+    Returns:
+        True if push succeeded, False otherwise.
+    """
+    workspace = config.workspace
+    branch_name = config.repo_context.branch_name
+
+    config.log("info", f"Pushing to origin/{branch_name}")
+
+    result = _run_git(
+        ["push", "-u", "origin", branch_name],
+        cwd=workspace,
+    )
+
+    if result.returncode != 0:
+        config.log("error", f"Failed to push: {result.stderr}")
+        return False
+
+    config.log("info", "Push successful")
+    return True
+
+
+def get_head_sha(workspace: Path) -> str | None:
+    """Get the SHA of the current HEAD commit.
+
+    Returns:
+        The commit SHA or None if not a git repo.
+    """
+    result = _run_git(["rev-parse", "HEAD"], cwd=workspace)
+    if result.returncode == 0:
+        return result.stdout.strip()
+    return None
+
+
+def initialize_repo(config: GitConfig) -> bool:
+    """Initialize a fresh repository for the experiment.
+
+    This is the main entry point for setting up code persistence.
+    It handles:
+    1. Cloning the repository
+    2. Setting up git credentials
+    3. Creating/checking out the branch
+
+    Returns:
+        True if initialization succeeded, False otherwise.
+    """
+    if not clone_repository(config):
+        return False
+
+    if not setup_git_credentials(config):
+        return False
+
+    if not setup_branch(config):
+        return False
+
+    return True
+
+
+def finalize_repo(config: GitConfig, run_id: str) -> bool:
+    """Finalize the repository after the experiment completes.
+
+    This commits and pushes any changes made during the run.
+
+    Args:
+        config: Git configuration
+        run_id: The run ID for the commit message
+
+    Returns:
+        True if finalization succeeded, False otherwise.
+    """
+    commit_message = f"Flywheel experiment run: {run_id}"
+
+    if not commit_changes(config, commit_message):
+        return False
+
+    if not push_changes(config):
+        return False
+
+    return True