forest-cli 0.1.0__py3-none-any.whl

forest/checkout.py

@@ -0,0 +1,992 @@
+"""Checkout workspace models and filesystem primitives."""
+
+from __future__ import annotations
+
+import fcntl
+import re
+import shutil
+import subprocess
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import yaml
+from pydantic import BaseModel, Field, model_validator
+
+from forest.config import (
+    ConfigError,
+    LocalConfig,
+    ProjectConfig,
+    load_config,
+    load_local_config_file,
+    save_config,
+    save_local_config_file,
+)
+from forest.fsutil import atomic_write
+
+
+class CheckoutError(Exception):
+    """Raised for checkout workspace loading or validation errors."""
+
+
+TOKEN_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+RESERVED_CHECKOUT_NAMES = frozenset({"create", "adopt", "list", "current", "remove"})
+RESERVED_REMOTE_NAMES = RESERVED_CHECKOUT_NAMES | frozenset({"add", "list", "show", "remove", "use", "set"})
+EMPTY_SYNC_STATE_TEXT = "[]\n"
+SECRET_REMOTE_URL_RE = re.compile(
+    r"(?i)(password|passwd|token|secret|credential|access[_-]?key|session[_-]?token|x-amz-signature)\s*="
+)
+WORKSPACE_GITIGNORE_PATTERNS = (
+    ".forest/HEAD",
+    ".forest/checkouts/*/local.yaml",
+    ".forest/checkouts/*/sync_state.json",
+    ".forest/checkouts/*/sync_state.json.lock",
+)
+LEGACY_GITIGNORE_PATTERNS = (
+    ".forest/local.yaml",
+    ".forest/sync_state.json",
+)
+FOREST_OWNED_GITIGNORE_LINES = frozenset(
+    {
+        ".forest/",
+        ".forest/*",
+        "!.forest/config.yaml",
+        "!.forest/checkouts/",
+        "!.forest/checkouts/*/",
+        "!.forest/checkouts/*/forest.yaml",
+        "forest.yaml",
+    }
+    | set(WORKSPACE_GITIGNORE_PATTERNS)
+    | set(LEGACY_GITIGNORE_PATTERNS)
+)
+
+
+def valid_token(name: str) -> bool:
+    """Return True when *name* is a strict path-safe token."""
+    return isinstance(name, str) and bool(name) and name not in {".", ".."} and TOKEN_RE.fullmatch(name) is not None
+
+
+def validate_token(
+    name: str,
+    *,
+    kind: str = "name",
+    reserved_names: set[str] | frozenset[str] = frozenset(),
+    existing_names: list[str] | tuple[str, ...] | set[str] | frozenset[str] = frozenset(),
+) -> str:
+    """Validate a path-safe token and reject case-insensitive collisions."""
+    if not valid_token(name):
+        raise CheckoutError(f"Invalid {kind} '{name}': use non-empty [A-Za-z0-9._-]+, not '.' or '..'.")
+
+    if name.lower() in {reserved.lower() for reserved in reserved_names}:
+        raise CheckoutError(f"Invalid {kind} '{name}': reserved word.")
+
+    existing_by_lower = {existing.lower(): existing for existing in existing_names}
+    collision = existing_by_lower.get(name.lower())
+    if collision is not None:
+        raise CheckoutError(f"Invalid {kind} '{name}': collides with existing {kind} '{collision}'.")
+
+    return name
+
+
+def validate_checkout_name(
+    name: str,
+    *,
+    existing_names: list[str] | tuple[str, ...] | set[str] | frozenset[str] = frozenset(),
+) -> str:
+    """Validate a checkout name using the workspace token rules."""
+    return validate_token(
+        name,
+        kind="checkout name",
+        reserved_names=RESERVED_CHECKOUT_NAMES,
+        existing_names=existing_names,
+    )
+
+
+def validate_remote_path(remote_path: str | Path) -> Path:
+    """Validate a workspace remote_path as a safe relative POSIX prefix."""
+    text = str(remote_path)
+    if (
+        not text
+        or text != text.strip()
+        or text.startswith("/")
+        or text.endswith("/")
+        or "//" in text
+        or "\\" in text
+        or "://" in text
+    ):
+        raise CheckoutError(f"Invalid remote_path '{text}': use a relative POSIX path with safe segments.")
+
+    parts = text.split("/")
+    for part in parts:
+        if not valid_token(part):
+            raise CheckoutError(f"Invalid remote_path '{text}': unsafe path segment '{part}'.")
+    return Path(*parts)
+
+
+def remote_url_has_secret_material(url: str) -> bool:
+    """Return True when a remote URL-like value contains credentials or token-like material."""
+    parsed = urlsplit(url)
+    if parsed.query:
+        return True
+    if parsed.scheme and (parsed.username is not None or parsed.password is not None):
+        return True
+    if re.match(r"^[^/@:]+:[^/@]+@[^:]+:.+", url):
+        return True
+    return SECRET_REMOTE_URL_RE.search(url) is not None
+
+
+def _is_relative_to(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+    except ValueError:
+        return False
+    return True
+
+
+def normalize_workspace_path(path: str | Path, workspace_root: str | Path, *, cwd: str | Path | None = None) -> Path:
+    """Resolve a path and store inside-workspace paths relative to the workspace root."""
+    workspace_root = Path(workspace_root).resolve(strict=False)
+    base = Path(cwd).resolve(strict=False) if cwd is not None else workspace_root
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = base / candidate
+    candidate = candidate.resolve(strict=False)
+
+    if _is_relative_to(candidate, workspace_root):
+        return candidate.relative_to(workspace_root)
+    return candidate
+
+
+def validate_workspace_data_path(path: str | Path, workspace_root: str | Path) -> Path:
+    """Return a resolved data path, rejecting paths under workspace .forest metadata."""
+    workspace_root = Path(workspace_root).resolve(strict=False)
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = workspace_root / candidate
+    candidate = candidate.resolve(strict=False)
+    forest_dir = (workspace_root / ".forest").resolve(strict=False)
+    if _is_relative_to(candidate, forest_dir):
+        raise CheckoutError("Data paths must not point inside .forest metadata.")
+    return candidate
+
+
+class CheckoutEntry(BaseModel):
+    """A registered checkout entry. Empty in workspace metadata v1."""
+
+    model_config = {"extra": "forbid"}
+
+
+class WorkspaceConfig(BaseModel):
+    """Workspace registry stored in .forest/config.yaml."""
+
+    version: int = 1
+    checkouts: dict[str, CheckoutEntry] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _validate_checkout_names(self) -> WorkspaceConfig:
+        seen: list[str] = []
+        for name in self.checkouts:
+            validate_checkout_name(name, existing_names=seen)
+            seen.append(name)
+        return self
+
+
+def _workspace_dir(workspace_root: str | Path) -> Path:
+    return Path(workspace_root) / ".forest"
+
+
+def workspace_config_path(workspace_root: str | Path) -> Path:
+    """Return the workspace registry path."""
+    return _workspace_dir(workspace_root) / "config.yaml"
+
+
+def checkout_dir(workspace_root: str | Path, checkout_name: str) -> Path:
+    """Return a checkout metadata directory path."""
+    return _workspace_dir(workspace_root) / "checkouts" / checkout_name
+
+
+def checkout_metadata_paths(workspace_root: str | Path, checkout_name: str) -> tuple[Path, Path, Path]:
+    """Return shared config, local config, and sync-state paths for a checkout."""
+    root = checkout_dir(workspace_root, checkout_name)
+    return root / "forest.yaml", root / "local.yaml", root / "sync_state.json"
+
+
+def load_workspace_config(workspace_root: str | Path) -> WorkspaceConfig:
+    """Load .forest/config.yaml from a workspace root."""
+    path = workspace_config_path(workspace_root)
+    data = _load_yaml_mapping(path, "Workspace config")
+
+    try:
+        return WorkspaceConfig(**data)
+    except Exception as exc:
+        raise CheckoutError(f"Invalid workspace config in {path}: {exc}") from None
+
+
+def _load_yaml_mapping(path: Path, label: str) -> dict[str, Any]:
+    if not path.exists():
+        raise CheckoutError(f"{label} not found: {path}")
+    try:
+        raw = path.read_text()
+    except OSError as exc:
+        raise CheckoutError(f"Cannot read {label.lower()} {path}: {exc}") from None
+
+    try:
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise CheckoutError(f"Invalid YAML in {path}: {exc}") from None
+
+    if data is None:
+        raise CheckoutError(f"{label} is empty: {path}")
+    if not isinstance(data, dict):
+        raise CheckoutError(f"Expected a dict in {path}, got {type(data).__name__}")
+    return data
+
+
+def _validate_workspace_shared_metadata(data: dict[str, Any], path: Path) -> None:
+    remotes = data.get("remotes", {})
+    if isinstance(remotes, dict):
+        seen_remotes: list[str] = []
+        for remote_name, remote_data in remotes.items():
+            validate_token(
+                str(remote_name),
+                kind="remote name",
+                reserved_names=RESERVED_REMOTE_NAMES,
+                existing_names=seen_remotes,
+            )
+            seen_remotes.append(str(remote_name))
+            if isinstance(remote_data, dict):
+                url = remote_data.get("url")
+                if isinstance(url, str) and remote_url_has_secret_material(url):
+                    raise CheckoutError(f"Invalid remote '{remote_name}' in {path}: URL contains credentials.")
+                endpoint = remote_data.get("endpoint")
+                if isinstance(endpoint, str) and remote_url_has_secret_material(endpoint):
+                    raise CheckoutError(f"Invalid remote '{remote_name}' in {path}: endpoint contains credentials.")
+
+    stages = data.get("stages", {})
+    if isinstance(stages, dict):
+        seen_stages: list[str] = []
+        for stage_name, stage_data in stages.items():
+            validate_token(
+                str(stage_name),
+                kind="stage name",
+                reserved_names=RESERVED_CHECKOUT_NAMES,
+                existing_names=seen_stages,
+            )
+            seen_stages.append(str(stage_name))
+            if isinstance(stage_data, dict) and stage_data.get("remote_path") is not None:
+                validate_remote_path(stage_data["remote_path"])
+
+
+def _load_workspace_shared_config(shared_path: Path) -> ProjectConfig:
+    data = _load_yaml_mapping(shared_path, "Configuration file")
+    _validate_workspace_shared_metadata(data, shared_path)
+    return _load_shared_config(shared_path)
+
+
+def _validate_legacy_remote_paths(config_path: Path) -> None:
+    data = _load_yaml_mapping(config_path, "Configuration file")
+    stages = data.get("stages", {})
+    if not isinstance(stages, dict):
+        return
+
+    for stage_name, stage_data in stages.items():
+        if not isinstance(stage_data, dict) or stage_data.get("remote_path") is None:
+            continue
+        try:
+            validate_remote_path(stage_data["remote_path"])
+        except CheckoutError as exc:
+            raise CheckoutError(f"Invalid remote_path for stage '{stage_name}' in {config_path}: {exc}") from None
+
+
+def _workspace_config_data(config: WorkspaceConfig) -> dict[str, object]:
+    return {
+        "version": config.version,
+        "checkouts": {name: {} for name in config.checkouts},
+    }
+
+
+def save_workspace_config(workspace_root: str | Path, config: WorkspaceConfig) -> None:
+    """Atomically save .forest/config.yaml for a workspace root."""
+    atomic_write(
+        workspace_config_path(workspace_root),
+        yaml.dump(_workspace_config_data(config), default_flow_style=False, sort_keys=False),
+    )
+
+
+def read_head(workspace_root: str | Path) -> str:
+    """Read the active checkout name from .forest/HEAD."""
+    path = _workspace_dir(workspace_root) / "HEAD"
+    if not path.exists():
+        raise CheckoutError(f"No active checkout: {path} does not exist.")
+    try:
+        raw = path.read_text()
+    except OSError as exc:
+        raise CheckoutError(f"Cannot read active checkout {path}: {exc}") from None
+
+    name = raw[:-1] if raw.endswith("\n") else raw
+    if "\n" in name:
+        raise CheckoutError(f"Invalid active checkout in {path}: expected exactly one checkout name line.")
+    return validate_checkout_name(name)
+
+
+def write_head(workspace_root: str | Path, checkout_name: str) -> None:
+    """Atomically write the active checkout name to .forest/HEAD."""
+    atomic_write(_workspace_dir(workspace_root) / "HEAD", validate_checkout_name(checkout_name) + "\n")
+
+
+def list_checkouts(workspace_root: str | Path) -> list[str]:
+    """Return registered checkout names after validating metadata directories exist."""
+    config = load_workspace_config(workspace_root)
+    names = sorted(config.checkouts)
+    for name in names:
+        if not checkout_dir(workspace_root, name).is_dir():
+            raise CheckoutError(f"Workspace checkout '{name}' is registered but its metadata directory is missing.")
+    return names
+
+
+def _minimal_shared_checkout_yaml(checkout_name: str) -> str:
+    return yaml.dump(
+        {"project": checkout_name, "remotes": {}, "stages": {}},
+        default_flow_style=False,
+        sort_keys=False,
+    )
+
+
+def ensure_checkout_local_files(workspace_root: str | Path, checkout_name: str) -> None:
+    """Create missing local-only checkout files without overwriting existing state."""
+    _shared_path, local_path, state_path = checkout_metadata_paths(workspace_root, checkout_name)
+    if not local_path.exists():
+        atomic_write(local_path, "")
+    if not state_path.exists():
+        atomic_write(state_path, EMPTY_SYNC_STATE_TEXT)
+
+
+def create_checkout(workspace_root: str | Path, checkout_name: str) -> None:
+    """Create checkout metadata, register it, and make it active."""
+    workspace_root = Path(workspace_root)
+    config_path = workspace_config_path(workspace_root)
+    registry = load_workspace_config(workspace_root) if config_path.exists() else WorkspaceConfig()
+
+    if checkout_name in registry.checkouts:
+        raise CheckoutError(f"Checkout '{checkout_name}' already exists. Run: forest checkout {checkout_name}")
+
+    validate_checkout_name(checkout_name, existing_names=list(registry.checkouts))
+    target_dir = checkout_dir(workspace_root, checkout_name)
+    if target_dir.exists() and any(target_dir.iterdir()):
+        raise CheckoutError(
+            f"Checkout metadata directory already exists and is not empty: {target_dir}. "
+            "Inspect or remove it before retrying."
+        )
+
+    target_existed = target_dir.exists()
+    config_text = _optional_text(config_path)
+    head_path = _workspace_dir(workspace_root) / "HEAD"
+    head_text = _optional_text(head_path)
+    gitignore_path = workspace_root / ".gitignore"
+    gitignore_text = _optional_text(gitignore_path)
+
+    try:
+        target_dir.mkdir(parents=True, exist_ok=True)
+        shared_path, local_path, state_path = checkout_metadata_paths(workspace_root, checkout_name)
+        atomic_write(shared_path, _minimal_shared_checkout_yaml(checkout_name))
+        atomic_write(local_path, "")
+        atomic_write(state_path, EMPTY_SYNC_STATE_TEXT)
+
+        registry.checkouts[checkout_name] = CheckoutEntry()
+        save_workspace_config(workspace_root, registry)
+        write_head(workspace_root, checkout_name)
+        ensure_workspace_gitignore(workspace_root, checkout_name)
+    except Exception:
+        if target_dir.exists():
+            if target_existed:
+                _empty_directory(target_dir)
+            else:
+                shutil.rmtree(target_dir)
+        _restore_optional_text(config_path, config_text)
+        _restore_optional_text(head_path, head_text)
+        _restore_optional_text(gitignore_path, gitignore_text)
+        raise
+
+
+def require_registered_checkout(workspace_root: Path, checkout_name: str) -> WorkspaceConfig:
+    """Return the registry after validating the checkout is registered and has metadata."""
+    registry = load_workspace_config(workspace_root)
+    if checkout_name not in registry.checkouts:
+        raise CheckoutError(f"Checkout '{checkout_name}' is not registered.")
+    if not checkout_dir(workspace_root, checkout_name).is_dir():
+        raise CheckoutError(f"Workspace checkout '{checkout_name}' metadata directory is missing.")
+    return registry
+
+
+def switch_checkout(workspace_root: str | Path, checkout_name: str) -> None:
+    """Switch active HEAD to an existing registered checkout."""
+    workspace_root = Path(workspace_root)
+    require_registered_checkout(workspace_root, checkout_name)
+
+    shared_path, local_path, _state_path = checkout_metadata_paths(workspace_root, checkout_name)
+    shared_config = _load_workspace_shared_config(shared_path)
+    ensure_checkout_local_files(workspace_root, checkout_name)
+    local_config = _load_checkout_local_config(local_path)
+    _validate_workspace_local_config(local_config, shared_config, workspace_root=workspace_root)
+    write_head(workspace_root, checkout_name)
+
+
+def remove_checkout(workspace_root: str | Path, checkout_name: str) -> bool:
+    """Remove registered checkout metadata only. Return True when HEAD was removed."""
+    workspace_root = Path(workspace_root)
+    registry = require_registered_checkout(workspace_root, checkout_name)
+    target_dir = checkout_dir(workspace_root, checkout_name)
+
+    head_path = _workspace_dir(workspace_root) / "HEAD"
+    active_name: str | None = None
+    if head_path.exists():
+        active_name = read_head(workspace_root)
+        if active_name not in registry.checkouts:
+            raise CheckoutError(f"Active checkout '{active_name}' is not registered in workspace config.")
+
+    del registry.checkouts[checkout_name]
+    save_workspace_config(workspace_root, registry)
+    shutil.rmtree(target_dir)
+    removed_head = active_name == checkout_name
+    if removed_head:
+        head_path.unlink(missing_ok=True)
+    return removed_head
+
+
+def _optional_text(path: Path) -> str | None:
+    return path.read_text() if path.exists() else None
+
+
+def _restore_optional_text(path: Path, text: str | None) -> None:
+    if text is None:
+        path.unlink(missing_ok=True)
+        return
+    atomic_write(path, text)
+
+
+def _empty_directory(path: Path) -> None:
+    if not path.exists():
+        return
+    for child in path.iterdir():
+        if child.is_dir():
+            shutil.rmtree(child)
+        else:
+            child.unlink()
+
+
+def _git_check_ignore(workspace_root: Path, rel_path: str) -> int:
+    try:
+        result = subprocess.run(
+            ["git", "check-ignore", "--no-index", "--quiet", "--", rel_path],
+            cwd=workspace_root,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise CheckoutError("gitignore assertion failed: git command not found") from exc
+    if result.returncode in {0, 1}:
+        return result.returncode
+    detail = result.stderr.strip() or result.stdout.strip() or f"git check-ignore exited {result.returncode}"
+    raise CheckoutError(f"gitignore assertion failed: {detail}")
+
+
+def _is_inside_git_worktree(workspace_root: Path) -> bool:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            cwd=workspace_root,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        return False
+    return result.returncode == 0 and result.stdout.strip() == "true"
+
+
+def _managed_gitignore_text(original_text: str, patterns: tuple[str, ...]) -> str:
+    lines = original_text.splitlines()
+    kept = [line for line in lines if line.strip() not in FOREST_OWNED_GITIGNORE_LINES]
+    kept.extend(patterns)
+    return "\n".join(kept).rstrip("\n") + "\n"
+
+
+def _ensure_gitignore(
+    root: Path,
+    *,
+    patterns: tuple[str, ...],
+    ignored_paths: tuple[str, ...],
+    tracked_paths: tuple[str, ...],
+) -> None:
+    gitignore_path = root / ".gitignore"
+    original_text = gitignore_path.read_text() if gitignore_path.exists() else ""
+    new_text = _managed_gitignore_text(original_text, patterns)
+    if new_text != original_text:
+        atomic_write(gitignore_path, new_text)
+
+    if not _is_inside_git_worktree(root):
+        return
+
+    for rel_path in ignored_paths:
+        if _git_check_ignore(root, rel_path) != 0:
+            raise CheckoutError(f"gitignore assertion failed: expected ignored local metadata: {rel_path}")
+
+    for rel_path in tracked_paths:
+        if _git_check_ignore(root, rel_path) == 0:
+            raise CheckoutError(f"gitignore assertion failed: shared metadata is ignored: {rel_path}")
+
+
+def ensure_workspace_gitignore(workspace_root: str | Path, checkout_name: str) -> None:
+    """Ensure workspace local-only metadata ignores and assert shared metadata is trackable."""
+    workspace_root = Path(workspace_root)
+    _ensure_gitignore(
+        workspace_root,
+        patterns=WORKSPACE_GITIGNORE_PATTERNS,
+        ignored_paths=(
+            ".forest/HEAD",
+            f".forest/checkouts/{checkout_name}/local.yaml",
+            f".forest/checkouts/{checkout_name}/sync_state.json",
+        ),
+        tracked_paths=(
+            ".forest/config.yaml",
+            f".forest/checkouts/{checkout_name}/forest.yaml",
+        ),
+    )
+
+
+def ensure_registry_gitignore(workspace_root: str | Path) -> None:
+    """Ensure local-only workspace ignores for a checkout-less registry (fresh init)."""
+    _ensure_gitignore(
+        Path(workspace_root),
+        patterns=WORKSPACE_GITIGNORE_PATTERNS,
+        ignored_paths=(".forest/HEAD",),
+        tracked_paths=(".forest/config.yaml",),
+    )
+
+
+def ensure_legacy_gitignore(project_root: str | Path) -> None:
+    """Ensure legacy local state ignores while keeping root forest.yaml trackable."""
+    project_root = Path(project_root)
+    _ensure_gitignore(
+        project_root,
+        patterns=LEGACY_GITIGNORE_PATTERNS,
+        ignored_paths=LEGACY_GITIGNORE_PATTERNS,
+        tracked_paths=("forest.yaml",),
+    )
+
+
+def _start_directory(start: str | Path) -> Path:
+    start_path = Path(start).resolve(strict=False)
+    return start_path.parent if start_path.is_file() else start_path
+
+
+def _find_boundary(start: str | Path) -> Path | None:
+    current = _start_directory(start)
+    while True:
+        if (current / ".forest").exists() or (current / ".git").exists():
+            return current
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def _find_legacy_config_without_boundary(start: str | Path) -> Path | None:
+    current = _start_directory(start)
+    while True:
+        config_path = current / "forest.yaml"
+        if config_path.exists():
+            return config_path
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def _find_legacy_root_for_adopt(start: str | Path) -> Path:
+    current = _start_directory(start)
+    boundary = _find_boundary(current)
+    while True:
+        if workspace_config_path(current).exists():
+            raise CheckoutError(f"Cannot adopt legacy config: checkout workspace already exists at {current}.")
+        if (current / "forest.yaml").exists():
+            return current
+        if current == boundary or current.parent == current:
+            break
+        current = current.parent
+
+    if boundary is None:
+        fallback = _find_legacy_config_without_boundary(start)
+        if fallback is not None:
+            return fallback.parent
+    elif workspace_config_path(boundary).exists():
+        raise CheckoutError(f"Cannot adopt legacy config: checkout workspace already exists at {boundary}.")
+
+    raise CheckoutError("No legacy forest.yaml to adopt.")
+
+
+def _validate_legacy_adopt_inputs(
+    legacy_config: ProjectConfig,
+    legacy_local: LocalConfig,
+) -> None:
+    seen_stages: list[str] = []
+    missing_paths: list[str] = []
+    for stage_name, stage_cfg in legacy_config.stages.items():
+        validate_token(
+            stage_name,
+            kind="stage name",
+            reserved_names=RESERVED_CHECKOUT_NAMES,
+            existing_names=seen_stages,
+        )
+        seen_stages.append(stage_name)
+        if stage_cfg.path is None:
+            missing_paths.append(stage_name)
+    if missing_paths:
+        joined = ", ".join(sorted(missing_paths))
+        raise CheckoutError(f"incomplete legacy metadata: stage path missing for {joined}.")
+
+    seen_remotes: list[str] = []
+    for remote_name in legacy_config.remotes:
+        validate_token(
+            remote_name,
+            kind="remote name",
+            reserved_names=RESERVED_CHECKOUT_NAMES,
+            existing_names=seen_remotes,
+        )
+        seen_remotes.append(remote_name)
+
+    if legacy_local.active_remote is not None and legacy_local.active_remote not in legacy_config.remotes:
+        raise CheckoutError(
+            f"incomplete legacy metadata: active remote '{legacy_local.active_remote}' is not in remotes."
+        )
+
+
+def _effective_local_stage_path(root: Path, path: Path | None) -> Path | None:
+    if path is None:
+        return None
+    candidate = path if path.is_absolute() else root / path
+    return candidate.resolve(strict=False)
+
+
+def _verify_adopted_checkout(
+    workspace_root: Path,
+    checkout_name: str,
+    legacy_config: ProjectConfig,
+    legacy_local: LocalConfig,
+) -> None:
+    merged, data_root, state_path = _resolve_workspace(workspace_root)
+    expected_state = checkout_dir(workspace_root, checkout_name) / "sync_state.json"
+    if data_root != workspace_root:
+        raise CheckoutError("adopt verify failed: workspace root changed.")
+    if state_path != expected_state:
+        raise CheckoutError("adopt verify failed: sync_state path changed.")
+    if merged.project != legacy_config.project:
+        raise CheckoutError("adopt verify failed: project name changed.")
+    if set(merged.stages) != set(legacy_config.stages):
+        raise CheckoutError("adopt verify failed: stage set changed.")
+    if merged.remotes != legacy_config.remotes:
+        raise CheckoutError("adopt verify failed: remote config changed.")
+    if merged.manifest != legacy_config.manifest:
+        raise CheckoutError("adopt verify failed: manifest config changed.")
+
+    local_config = _load_checkout_local_config(checkout_dir(workspace_root, checkout_name) / "local.yaml")
+    if local_config.active_remote != legacy_local.active_remote:
+        raise CheckoutError("adopt verify failed: active remote changed.")
+
+    _verify_adopted_stages(workspace_root, merged, legacy_config)
+
+
+def _verify_adopted_stages(
+    workspace_root: Path,
+    merged: ProjectConfig,
+    legacy_config: ProjectConfig,
+) -> None:
+    for stage_name, legacy_stage in legacy_config.stages.items():
+        merged_stage = merged.stages[stage_name]
+        if merged_stage.schema_ != legacy_stage.schema_:
+            raise CheckoutError(f"adopt verify failed: schema changed for stage '{stage_name}'.")
+        if merged_stage.sync_by != legacy_stage.sync_by:
+            raise CheckoutError(f"adopt verify failed: sync_by changed for stage '{stage_name}'.")
+        if legacy_stage.remote_path is not None and merged_stage.remote_path != legacy_stage.remote_path:
+            raise CheckoutError(f"adopt verify failed: remote_path changed for stage '{stage_name}'.")
+        expected_path = _effective_local_stage_path(workspace_root, legacy_stage.path)
+        if merged_stage.path != expected_path:
+            raise CheckoutError(f"adopt verify failed: local path changed for stage '{stage_name}'.")
+
+
+def _restore_adopt_staging(
+    *,
+    workspace_root: Path,
+    checkout_name: str,
+    target_existed: bool,
+    workspace_config_text: str | None,
+    head_text: str | None,
+    gitignore_text: str | None,
+    legacy_texts: dict[Path, str | None],
+) -> None:
+    target_dir = checkout_dir(workspace_root, checkout_name)
+    if target_dir.exists():
+        if target_existed:
+            _empty_directory(target_dir)
+        else:
+            shutil.rmtree(target_dir)
+    _restore_optional_text(workspace_config_path(workspace_root), workspace_config_text)
+    _restore_optional_text(_workspace_dir(workspace_root) / "HEAD", head_text)
+    _restore_optional_text(workspace_root / ".gitignore", gitignore_text)
+    for path, text in legacy_texts.items():
+        current = _optional_text(path)
+        if text is not None and current is None:
+            _restore_optional_text(path, text)
+
+
+def _assert_legacy_metadata_unchanged(legacy_texts: dict[Path, str | None]) -> None:
+    for path, expected in legacy_texts.items():
+        if _optional_text(path) != expected:
+            raise CheckoutError(f"legacy metadata changed during adopt, rerun: {path}")
+
+
+def adopt_checkout(start: str | Path, checkout_name: str) -> Path:
+    """Adopt legacy root metadata into a checkout via copy, build, verify, then delete-old."""
+    validate_checkout_name(checkout_name)
+    legacy_root = _find_legacy_root_for_adopt(start)
+    if workspace_config_path(legacy_root).exists():
+        raise CheckoutError(f"Cannot adopt legacy config: checkout workspace already exists at {legacy_root}.")
+
+    target_dir = checkout_dir(legacy_root, checkout_name)
+    if target_dir.exists() and any(target_dir.iterdir()):
+        raise CheckoutError(
+            f"Checkout metadata directory already exists and is not empty: {target_dir}. "
+            "Inspect or remove it before retrying."
+        )
+    target_existed = target_dir.exists()
+
+    root_config_path = legacy_root / "forest.yaml"
+    local_path = legacy_root / ".forest" / "local.yaml"
+    state_path = legacy_root / ".forest" / "sync_state.json"
+    if not root_config_path.exists():
+        raise CheckoutError("No legacy forest.yaml to adopt.")
+    if not local_path.exists() or not state_path.exists():
+        raise CheckoutError("incomplete legacy metadata: expected .forest/local.yaml and .forest/sync_state.json.")
+
+    try:
+        legacy_config = _load_shared_config(root_config_path)
+        legacy_local = _load_checkout_local_config(local_path)
+    except CheckoutError:
+        raise
+
+    _validate_legacy_adopt_inputs(legacy_config, legacy_local)
+
+    workspace_config_text = _optional_text(workspace_config_path(legacy_root))
+    head_text = _optional_text(_workspace_dir(legacy_root) / "HEAD")
+    gitignore_text = _optional_text(legacy_root / ".gitignore")
+    legacy_texts = {
+        root_config_path: _optional_text(root_config_path),
+        local_path: _optional_text(local_path),
+        state_path: _optional_text(state_path),
+    }
+
+    try:
+        target_dir.mkdir(parents=True, exist_ok=True)
+        shared_path, adopted_local_path, adopted_state_path = checkout_metadata_paths(legacy_root, checkout_name)
+        shutil.copy2(root_config_path, shared_path)
+        shutil.copy2(local_path, adopted_local_path)
+        shutil.copy2(state_path, adopted_state_path)
+
+        stage_paths = dict(legacy_local.stage_paths)
+        split_stages = {}
+        for stage_name, stage_cfg in legacy_config.stages.items():
+            if stage_cfg.path is None:
+                raise CheckoutError(f"incomplete legacy metadata: stage path missing for {stage_name}.")
+            stage_paths[stage_name] = stage_cfg.path
+            split_stages[stage_name] = stage_cfg.model_copy(update={"path": None})
+
+        shared_config = legacy_config.model_copy(update={"stages": split_stages}, deep=True)
+        split_local = legacy_local.model_copy(update={"stage_paths": stage_paths}, deep=True)
+        save_config(shared_config, shared_path, include_stage_paths=False)
+        save_local_config_file(split_local, adopted_local_path)
+        atomic_write(adopted_state_path, state_path.read_text())
+
+        registry = WorkspaceConfig(checkouts={checkout_name: CheckoutEntry()})
+        save_workspace_config(legacy_root, registry)
+        write_head(legacy_root, checkout_name)
+        ensure_workspace_gitignore(legacy_root, checkout_name)
+        _verify_adopted_checkout(legacy_root, checkout_name, legacy_config, legacy_local)
+        _assert_legacy_metadata_unchanged(legacy_texts)
+
+        root_config_path.unlink()
+        local_path.unlink()
+        state_path.unlink()
+
+        resolved, data_root, final_state_path = resolve_active_config(legacy_root)
+        if (
+            data_root != legacy_root
+            or final_state_path != adopted_state_path
+            or resolved.project != legacy_config.project
+        ):
+            raise CheckoutError("adopt verify failed after deleting legacy originals.")
+    except Exception:
+        _restore_adopt_staging(
+            workspace_root=legacy_root,
+            checkout_name=checkout_name,
+            target_existed=target_existed,
+            workspace_config_text=workspace_config_text,
+            head_text=head_text,
+            gitignore_text=gitignore_text,
+            legacy_texts=legacy_texts,
+        )
+        raise
+
+    return legacy_root
+
+
+def find_workspace_root(start: str | Path) -> Path | None:
+    """Find a workspace root without piercing a nearer .forest or .git boundary."""
+    boundary = _find_boundary(start)
+    if boundary is None:
+        return None
+
+    workspace_config = workspace_config_path(boundary)
+    legacy_config = boundary / "forest.yaml"
+    if workspace_config.exists() and legacy_config.exists():
+        raise CheckoutError(f"Ambiguous forest config: both {legacy_config} and {workspace_config} exist.")
+    if workspace_config.exists():
+        return boundary
+    return None
+
+
+def find_project_boundary(start: str | Path) -> Path:
+    """Find the nearest .forest/.git boundary, or use the start directory."""
+    boundary = _find_boundary(start)
+    return boundary if boundary is not None else _start_directory(start)
+
+
+def _load_checkout_local_config(local_path: Path) -> LocalConfig:
+    try:
+        return load_local_config_file(local_path)
+    except ConfigError as exc:
+        raise CheckoutError(str(exc)) from None
+
+
+def _load_shared_config(shared_path: Path) -> ProjectConfig:
+    try:
+        return load_config(shared_path)
+    except ConfigError as exc:
+        raise CheckoutError(str(exc)) from None
+
+
+def _validate_workspace_local_config(
+    local_config: LocalConfig,
+    shared_config: ProjectConfig,
+    *,
+    workspace_root: Path,
+) -> None:
+    if local_config.active_remote is not None:
+        validate_token(
+            local_config.active_remote,
+            kind="active_remote",
+            reserved_names=RESERVED_REMOTE_NAMES,
+        )
+
+    shared_stage_by_lower = {name.lower(): name for name in shared_config.stages}
+    seen_bindings: list[str] = []
+    for stage_name, stage_path in local_config.stage_paths.items():
+        validate_token(
+            stage_name,
+            kind="stage binding",
+            reserved_names=RESERVED_CHECKOUT_NAMES,
+            existing_names=seen_bindings,
+        )
+        seen_bindings.append(stage_name)
+        canonical_stage = shared_stage_by_lower.get(stage_name.lower())
+        if canonical_stage is not None and canonical_stage != stage_name:
+            raise CheckoutError(f"Invalid stage binding '{stage_name}': collides with stage name '{canonical_stage}'.")
+        validate_workspace_data_path(stage_path, workspace_root)
+
+
+def _inject_workspace_stage_paths(
+    config: ProjectConfig,
+    local_config: LocalConfig,
+    *,
+    workspace_root: Path,
+    checkout_name: str,
+) -> ProjectConfig:
+    stages = {}
+    for stage_name, stage in config.stages.items():
+        validate_token(stage_name, kind="stage name", reserved_names=RESERVED_CHECKOUT_NAMES)
+        local_path = local_config.stage_paths.get(stage_name)
+        injected_path = None
+        if local_path is not None:
+            injected_path = validate_workspace_data_path(local_path, workspace_root)
+
+        default_remote_path = Path(checkout_name) / stage_name
+        remote_path = validate_remote_path(stage.remote_path) if stage.remote_path is not None else default_remote_path
+        stages[stage_name] = stage.model_copy(update={"path": injected_path, "remote_path": remote_path})
+    return config.model_copy(update={"stages": stages}, deep=True)
+
+
+def _resolve_workspace(workspace_root: Path) -> tuple[ProjectConfig, Path, Path]:
+    registry = load_workspace_config(workspace_root)
+    checkout_name = read_head(workspace_root)
+    if checkout_name not in registry.checkouts:
+        raise CheckoutError(f"Active checkout '{checkout_name}' is not registered in workspace config.")
+
+    active_dir = checkout_dir(workspace_root, checkout_name)
+    if not active_dir.is_dir():
+        raise CheckoutError(f"Active checkout '{checkout_name}' metadata directory is missing.")
+
+    shared_config = _load_workspace_shared_config(active_dir / "forest.yaml")
+    local_config = _load_checkout_local_config(active_dir / "local.yaml")
+    _validate_workspace_local_config(local_config, shared_config, workspace_root=workspace_root)
+    merged = _inject_workspace_stage_paths(
+        shared_config,
+        local_config,
+        workspace_root=workspace_root,
+        checkout_name=checkout_name,
+    )
+    return merged, workspace_root, active_dir / "sync_state.json"
+
+
+def _resolve_legacy(config_path: Path) -> tuple[ProjectConfig, Path, Path]:
+    _validate_legacy_remote_paths(config_path)
+    config = _load_shared_config(config_path)
+    data_root = config_path.parent
+    return config, data_root, data_root / ".forest" / "sync_state.json"
+
+
+def resolve_active_config(start_cwd: str | Path) -> tuple[ProjectConfig, Path, Path]:
+    """Resolve active ProjectConfig, data root, and sync-state path.
+
+    Workspace mode merges local stage bindings on read. Legacy mode loads the
+    root forest.yaml unchanged when no workspace registry is present.
+    """
+    boundary = _find_boundary(start_cwd)
+    if boundary is not None:
+        workspace_config = workspace_config_path(boundary)
+        legacy_config = boundary / "forest.yaml"
+        if workspace_config.exists() and legacy_config.exists():
+            raise CheckoutError(f"Ambiguous forest config: both {legacy_config} and {workspace_config} exist.")
+        if workspace_config.exists():
+            return _resolve_workspace(boundary)
+        if legacy_config.exists():
+            return _resolve_legacy(legacy_config)
+    else:
+        fallback_legacy_config = _find_legacy_config_without_boundary(start_cwd)
+        if fallback_legacy_config is not None:
+            return _resolve_legacy(fallback_legacy_config)
+
+    raise CheckoutError("No forest project found. Run 'forest init' or create a checkout workspace.")
+
+
+@contextmanager
+def checkout_lock(state_path: str | Path) -> Iterator[None]:
+    """Acquire an exclusive per-checkout lock next to a sync_state.json file."""
+    state_path = Path(state_path)
+    lock_path = state_path.with_suffix(state_path.suffix + ".lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+") as handle:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)