multi-forge 0.2.0__py3-none-any.whl

forge/session/prev_sessions.py

@@ -0,0 +1,128 @@
+"""Path layout for resume/fork context files (prev_sessions).
+
+Centralizes the on-disk layout so process_handoff, SessionManager, fork paths,
+and GC stay in sync.
+
+Layout::
+
+    <forge_root>/.forge/prev_sessions/
+    +-- <parent>/
+        +-- generated.md          # Strategy output (regeneratable cache)
+        +-- children/
+            +-- <child>.md        # Per-child authoritative context (durable)
+
+The split exists so that regenerating the parent cache (re-running resume
+against the same parent) never disturbs an existing child file. Once
+``children/<child>.md`` exists, it is the authoritative context that gets
+appended to the child session's system prompt.
+
+Legacy note: pre-0.2.0, this was a single flat
+``<forge_root>/.forge/prev_sessions/<parent>.md`` (parent-scoped, overwritten
+by every resume/fork). New code never reads or writes the flat layout. GC
+treats any remaining flat ``*.md`` files at the top level of
+``prev_sessions/`` as orphans (see ``iter_legacy_flat_files``).
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Iterator
+from pathlib import Path
+
+PREV_SESSIONS_DIR = "prev_sessions"
+GENERATED_FILENAME = "generated.md"
+CHILDREN_DIR = "children"
+
+
+def prev_sessions_root(forge_root: Path) -> Path:
+    return forge_root / ".forge" / PREV_SESSIONS_DIR
+
+
+def parent_dir(forge_root: Path, parent_name: str) -> Path:
+    return prev_sessions_root(forge_root) / parent_name
+
+
+def generated_path(forge_root: Path, parent_name: str) -> Path:
+    return parent_dir(forge_root, parent_name) / GENERATED_FILENAME
+
+
+def children_dir(forge_root: Path, parent_name: str) -> Path:
+    return parent_dir(forge_root, parent_name) / CHILDREN_DIR
+
+
+def child_path(forge_root: Path, parent_name: str, child_name: str) -> Path:
+    return children_dir(forge_root, parent_name) / f"{child_name}.md"
+
+
+def generated_path_rel(parent_name: str) -> str:
+    """Return the forge-root-relative path to ``generated.md``."""
+    return f".forge/{PREV_SESSIONS_DIR}/{parent_name}/{GENERATED_FILENAME}"
+
+
+def child_path_rel(parent_name: str, child_name: str) -> str:
+    """Return the forge-root-relative path to ``children/<child>.md``."""
+    return f".forge/{PREV_SESSIONS_DIR}/{parent_name}/{CHILDREN_DIR}/{child_name}.md"
+
+
+def ensure_child(forge_root: Path, parent_name: str, child_name: str) -> Path:
+    """Create ``children/<child>.md`` as a copy of ``generated.md`` if absent.
+
+    Idempotent: if the child file already exists (user has curated it, or it
+    was created by a previous resume), leave it alone. This is the durability
+    guarantee: once a child file exists, regenerating the parent cache does
+    not affect it.
+
+    Raises ``FileNotFoundError`` if neither the child file nor the parent
+    cache exists -- the caller is responsible for running ``process_handoff``
+    first.
+    """
+    target = child_path(forge_root, parent_name, child_name)
+    if target.exists():
+        return target
+
+    source = generated_path(forge_root, parent_name)
+    if not source.is_file():
+        raise FileNotFoundError(
+            f"Cannot copy parent cache to child: {source} does not exist. " "Run process_handoff() first."
+        )
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(source, target)
+    return target
+
+
+def iter_parents(forge_root: Path) -> Iterator[Path]:
+    """Yield each ``<parent>/`` directory under ``prev_sessions/``.
+
+    Skips legacy flat ``.md`` files at the top level (see
+    ``iter_legacy_flat_files``).
+    """
+    root = prev_sessions_root(forge_root)
+    if not root.is_dir():
+        return
+    for entry in root.iterdir():
+        if entry.is_dir():
+            yield entry
+
+
+def iter_children(forge_root: Path, parent_name: str) -> Iterator[Path]:
+    """Yield each ``<child>.md`` under ``<parent>/children/``."""
+    target = children_dir(forge_root, parent_name)
+    if not target.is_dir():
+        return
+    for entry in target.iterdir():
+        if entry.is_file() and entry.suffix == ".md":
+            yield entry
+
+
+def iter_legacy_flat_files(forge_root: Path) -> Iterator[Path]:
+    """Yield top-level ``<parent>.md`` files (legacy pre-0.2.0 layout).
+
+    These are orphan candidates for GC; new code never writes here.
+    """
+    root = prev_sessions_root(forge_root)
+    if not root.is_dir():
+        return
+    for entry in root.iterdir():
+        if entry.is_file() and entry.suffix == ".md":
+            yield entry

forge/session/store.py

@@ -0,0 +1,431 @@
+"""Per-session manifest storage.
+
+Path: <forge_root>/.forge/sessions/<session_name>/forge.session.json
+
+Schema: v1 only (no migration).
+
+Session manifests are treated as a strict contract:
+- No schema migration
+- No unknown field preservation
+- Invalid manifests fail fast on read
+
+Writes always produce schema v1.
+
+Invariant: session names are globally unique across all worktrees (enforced by
+IndexStore.add_session). The directory name IS the session name.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import fields, is_dataclass
+from pathlib import Path
+from typing import Any, Callable, get_origin, get_type_hints
+
+import dacite
+
+from forge.core.state import atomic_write_json, now_iso
+from forge.core.state.lock import file_lock_for_target
+from forge.core.typing_helpers import unwrap_optional
+
+from .exceptions import (
+    ManifestCorruptedError,
+    ManifestValidationError,
+    SessionFileNotFoundError,
+)
+from .models import SCHEMA_VERSION, SessionState, session_state_to_dict
+from .validation import validate_name
+
+_SUPPORTED_SCHEMA_VERSIONS = {1}
+
+MANIFEST_FILENAME = "forge.session.json"
+MANIFEST_DIR = ".forge"
+SESSIONS_DIR = "sessions"
+
+HOOK_LOCK_TIMEOUT_S = 0.2
+CLI_LOCK_TIMEOUT_S = 5.0
+
+
+# --- Free functions — use these for path construction everywhere (avoid drift) ---
+
+
+def get_sessions_dir(forge_root: str | Path) -> Path:
+    """Return the sessions directory for a Forge project.
+
+    Returns: <forge_root>/.forge/sessions/
+    """
+    return Path(forge_root) / MANIFEST_DIR / SESSIONS_DIR
+
+
+def get_manifest_path(forge_root: str | Path, session_name: str) -> Path:
+    """Return the manifest path for a specific session.
+
+    Returns: <forge_root>/.forge/sessions/<session_name>/forge.session.json
+    """
+    return Path(forge_root) / MANIFEST_DIR / SESSIONS_DIR / session_name / MANIFEST_FILENAME
+
+
+class SessionStore:
+    """Read/write session state to per-session manifest directory.
+
+    Each session has its own directory under <forge_root>/.forge/sessions/<name>/.
+    Multiple sessions can coexist in the same Forge project.
+    """
+
+    def __init__(self, forge_root: str, session_name: str) -> None:
+        """Initialize store for a specific session in a Forge project.
+
+        Args:
+            forge_root: Absolute path to the Forge project root (where .forge/ lives).
+            session_name: Session name (must be valid per validate_name).
+        """
+        self._forge_root = Path(forge_root).resolve()
+        self._session_name = session_name
+        self._manifest_path = get_manifest_path(self._forge_root, session_name)
+
+    @property
+    def manifest_path(self) -> Path:
+        """Return the full path to the manifest file."""
+        return self._manifest_path
+
+    @property
+    def forge_root(self) -> Path:
+        """Return the Forge project root."""
+        return self._forge_root
+
+    @property
+    def worktree_path(self) -> Path:
+        """Deprecated alias for forge_root (kept for transition)."""
+        return self._forge_root
+
+    @property
+    def session_name(self) -> str:
+        """Return the session name."""
+        return self._session_name
+
+    @property
+    def session_dir(self) -> Path:
+        """Return the session directory (parent of manifest file)."""
+        return self._manifest_path.parent
+
+    def exists(self) -> bool:
+        """Check if a manifest exists in this worktree."""
+        return self._manifest_path.is_file()
+
+    def read_raw(self) -> dict[str, Any] | None:
+        """Read manifest as raw JSON dict, skipping validation/deserialization.
+
+        For best-effort field extraction when full parsing fails (e.g. force-delete
+        needs confirmed.claude_session_id from a schema-mismatched manifest).
+
+        Returns None if the file doesn't exist or isn't valid JSON.
+        """
+        if not self.exists():
+            return None
+        try:
+            with open(self._manifest_path, encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def read(self) -> SessionState:
+        """Read and parse the session manifest.
+
+        Schema v1 only. No migration, no unknown field preservation.
+
+        Raises:
+            SessionFileNotFoundError: If manifest doesn't exist.
+            ManifestCorruptedError: If manifest cannot be parsed.
+            ManifestValidationError: If manifest is missing required fields.
+        """
+        if not self.exists():
+            raise SessionFileNotFoundError(str(self._manifest_path))
+
+        try:
+            with open(self._manifest_path, encoding="utf-8") as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ManifestCorruptedError(str(self._manifest_path), f"invalid JSON: {e}")
+        except OSError as e:
+            raise ManifestCorruptedError(str(self._manifest_path), f"read error: {e}")
+
+        self._validate_data(data)
+
+        try:
+            manifest = dacite.from_dict(
+                data_class=SessionState,
+                data=data,
+                config=dacite.Config(strict=True),
+            )
+        except (dacite.DaciteError, TypeError, KeyError, ValueError) as e:
+            raise ManifestCorruptedError(str(self._manifest_path), f"deserialization error: {e}")
+
+        return manifest
+
+    def write(self, manifest: SessionState) -> None:
+        """Write the session manifest atomically under lock.
+
+        Uses atomic write pattern via core.state.atomic_write_json.
+        Creates session directory if it doesn't exist.
+        Acquires the same file lock as update() to prevent CLI write + hook
+        update lost-update races (D10).
+
+        Args:
+            manifest: The manifest to write.
+
+        Raises:
+            InvalidSessionNameError: If manifest name is invalid.
+        """
+        self.session_dir.mkdir(parents=True, exist_ok=True)
+
+        with file_lock_for_target(target_path=self._manifest_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            self._write_unlocked(manifest)
+
+    def _write_unlocked(self, manifest: SessionState) -> None:
+        """Write manifest without acquiring lock (caller must hold it)."""
+        validate_name(manifest.name)
+
+        # Enforce invariant: directory name == manifest name (Issue A).
+        if manifest.name != self._session_name:
+            raise ValueError(
+                f"Manifest name '{manifest.name}' does not match store session "
+                f"name '{self._session_name}'. This would create a directory/name mismatch."
+            )
+
+        data = session_state_to_dict(manifest)
+        data["schema_version"] = SCHEMA_VERSION
+        atomic_write_json(self._manifest_path, data)
+
+    def delete(self) -> bool:
+        """Delete the session directory and its contents.
+
+        Uses shutil.rmtree since the session directory is entirely session-owned.
+        Leaves the parent sessions/ directory in place even if empty (D12).
+
+        Returns:
+            True if directory was removed, False if it didn't exist.
+        """
+        session_dir = self.session_dir
+        if session_dir.is_dir():
+            shutil.rmtree(session_dir, ignore_errors=True)
+            return True
+        return False
+
+    def update_last_accessed(self) -> SessionState:
+        """Update last_accessed_at timestamp and return updated manifest."""
+
+        return self.update(
+            timeout_s=CLI_LOCK_TIMEOUT_S,
+            mutate=lambda m: setattr(m, "last_accessed_at", now_iso()),
+        )
+
+    def update(self, *, timeout_s: float, mutate: Callable[[SessionState], None]) -> SessionState:
+        """Update a manifest via a locked read-modify-write cycle.
+
+        This prevents lost updates when multiple processes (CLI + hooks) mutate
+        different sections of the manifest concurrently.
+
+        Args:
+            timeout_s: How long to wait for the manifest lock.
+            mutate: Callback that mutates the loaded manifest in-place.
+
+        Returns:
+            The updated manifest after persistence.
+
+        Raises:
+            FileLockTimeoutError: If lock cannot be acquired within timeout.
+            SessionFileNotFoundError / ManifestCorruptedError / ManifestValidationError: On read failures.
+            InvalidSessionNameError: On write failures.
+        """
+
+        with file_lock_for_target(target_path=self._manifest_path, timeout_s=timeout_s):
+            manifest = self.read()
+            mutate(manifest)
+            self._write_unlocked(manifest)
+            return manifest
+
+    def _validate_data(self, data: dict[str, Any]) -> None:
+        """Validate required fields for schema v1.
+
+        The manifest is treated as a strict contract:
+        - schema_version must be supported
+        - required fields must be present
+        - overrides must target valid SessionIntent fields only
+
+        Raises:
+            ManifestCorruptedError: If schema version is unsupported or types are invalid.
+            ManifestValidationError: If required fields are missing.
+        """
+        missing: list[str] = []
+
+        # Check schema version
+        if "schema_version" not in data:
+            missing.append("schema_version")
+        elif data["schema_version"] not in _SUPPORTED_SCHEMA_VERSIONS:
+            raise ManifestCorruptedError(
+                str(self._manifest_path),
+                f"incompatible schema version {data['schema_version']} "
+                f"(this Forge expects {sorted(_SUPPORTED_SCHEMA_VERSIONS)}). "
+                f"Delete this session and recreate it.",
+            )
+
+        # Overrides are required (empty dict allowed)
+        if "overrides" not in data:
+            missing.append("overrides")
+        elif not isinstance(data["overrides"], dict):
+            raise ManifestCorruptedError(str(self._manifest_path), "overrides must be an object")
+
+        if "name" not in data:
+            missing.append("name")
+
+        if "created_at" not in data:
+            missing.append("created_at")
+        if "last_accessed_at" not in data:
+            missing.append("last_accessed_at")
+
+        if "intent" not in data:
+            missing.append("intent")
+            intent: dict[str, Any] = {}
+        else:
+            intent_obj = data.get("intent")
+            if intent_obj is None or not isinstance(intent_obj, dict):
+                raise ManifestCorruptedError(str(self._manifest_path), "intent must be an object")
+            intent = intent_obj
+        # Check intent.proxy fields (optional; but if present must be complete)
+        proxy = intent.get("proxy")
+        if proxy is not None:
+            if not isinstance(proxy, dict):
+                raise ManifestCorruptedError(str(self._manifest_path), "intent.proxy must be an object")
+
+            if "template" not in proxy:
+                missing.append("intent.proxy.template")
+            if "base_url" not in proxy:
+                missing.append("intent.proxy.base_url")
+
+        # Strict overrides schema: keys must be valid SessionIntent paths
+        overrides = data.get("overrides")
+        if isinstance(overrides, dict):
+            _validate_overrides_schema(overrides, str(self._manifest_path))
+
+        # Optional: confirmed.started_with_proxy (B2.1.6)
+        confirmed = data.get("confirmed", {})
+        started_with_proxy = confirmed.get("started_with_proxy")
+        if started_with_proxy is not None:
+            if not isinstance(started_with_proxy, dict):
+                raise ManifestCorruptedError(
+                    str(self._manifest_path),
+                    "confirmed.started_with_proxy must be an object",
+                )
+
+            base_url = started_with_proxy.get("base_url")
+            if not isinstance(base_url, str) or not base_url:
+                raise ManifestCorruptedError(
+                    str(self._manifest_path),
+                    "confirmed.started_with_proxy.base_url is required",
+                )
+
+            proxy_id = started_with_proxy.get("proxy_id")
+            if proxy_id is not None and not isinstance(proxy_id, str):
+                raise ManifestCorruptedError(
+                    str(self._manifest_path),
+                    "confirmed.started_with_proxy.proxy_id must be a string",
+                )
+
+            template = started_with_proxy.get("template")
+            if template is not None and not isinstance(template, str):
+                raise ManifestCorruptedError(
+                    str(self._manifest_path),
+                    "confirmed.started_with_proxy.template must be a string",
+                )
+
+            port = started_with_proxy.get("port")
+            if port is not None and not isinstance(port, int):
+                raise ManifestCorruptedError(
+                    str(self._manifest_path),
+                    "confirmed.started_with_proxy.port must be an integer",
+                )
+
+        if missing:
+            raise ManifestValidationError(str(self._manifest_path), missing)
+
+
+def _is_dict_type(tp: Any) -> bool:
+    """Check if a type annotation is a dict type (dict, Dict, dict[...])."""
+    return get_origin(tp) is dict or tp is dict
+
+
+def _collect_dataclass_field_names(cls: type[Any]) -> set[str]:
+    return {f.name for f in fields(cls) if not f.name.startswith("_")}
+
+
+def _collect_dataclass_field_types(cls: type[Any]) -> dict[str, Any]:
+    # Use get_type_hints so forward refs and Optional are resolved.
+    return get_type_hints(cls)
+
+
+def _validate_overrides_schema(overrides: dict[str, Any], manifest_path: str) -> None:
+    """Validate that override keys target only real SessionIntent fields.
+
+    SessionState.overrides is a dict, so dacite cannot enforce its schema.
+    We validate it manually against the SessionIntent dataclass structure.
+
+    Rules:
+    - No unknown keys at any level
+    - No `custom` namespace
+    - Only nested dataclass fields may contain nested dict overrides
+    """
+    from .models import SessionIntent
+
+    _validate_overrides_dict_against_dataclass(
+        overrides=overrides,
+        cls=SessionIntent,
+        path_prefix="overrides",
+        manifest_path=manifest_path,
+    )
+
+
+def _validate_overrides_dict_against_dataclass(
+    overrides: dict[str, Any],
+    cls: Any,
+    path_prefix: str,
+    manifest_path: str,
+) -> None:
+    if not is_dataclass(cls):
+        raise ManifestCorruptedError(manifest_path, f"internal error: {cls} is not a dataclass")
+
+    if not isinstance(cls, type):
+        raise ManifestCorruptedError(manifest_path, f"internal error: {cls} is not a type")
+
+    valid_fields = _collect_dataclass_field_names(cls)
+    type_hints = _collect_dataclass_field_types(cls)
+
+    for key, value in overrides.items():
+        if key == "custom":
+            raise ManifestCorruptedError(manifest_path, "overrides.custom is not supported")
+
+        if key not in valid_fields:
+            raise ManifestCorruptedError(manifest_path, f"unknown override key: {path_prefix}.{key}")
+
+        field_type = type_hints.get(key)
+        if field_type is None:
+            # Should not happen for normal dataclasses; treat as schema error.
+            raise ManifestCorruptedError(manifest_path, f"missing type hint for {path_prefix}.{key}")
+
+        actual_type = unwrap_optional(field_type)
+
+        # Nested dict overrides are only allowed for nested dataclasses or dict-typed fields.
+        if isinstance(value, dict):
+            if is_dataclass(actual_type):
+                _validate_overrides_dict_against_dataclass(
+                    overrides=value,
+                    cls=actual_type,
+                    path_prefix=f"{path_prefix}.{key}",
+                    manifest_path=manifest_path,
+                )
+            elif not _is_dict_type(actual_type):
+                raise ManifestCorruptedError(
+                    manifest_path,
+                    f"{path_prefix}.{key} does not support nested override keys",
+                )
+            # else: dict-typed field — accept any dict value without schema validation

forge/session/validation.py

@@ -0,0 +1,47 @@
+"""Session name validation."""
+
+from __future__ import annotations
+
+import re
+
+from .exceptions import InvalidSessionNameError
+
+# Constants
+MIN_NAME_LENGTH = 2
+MAX_NAME_LENGTH = 64
+
+# Regex: lowercase alphanumeric, hyphens allowed in middle, no consecutive hyphens
+# Must start and end with alphanumeric
+_NAME_PATTERN = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+
+
+def validate_name(name: str) -> None:
+    """Validate a session name.
+
+    Raises:
+        InvalidSessionNameError: If name is invalid, with specific reason.
+
+    Rules:
+        - Length: 2-64 characters
+        - Characters: lowercase alphanumeric + hyphens
+        - Must start with alphanumeric
+        - Must end with alphanumeric
+        - No consecutive hyphens
+
+    Examples:
+        Valid: "auth-feature", "bugfix-123", "a1"
+        Invalid: "-invalid", "invalid-", "in--valid", "UPPERCASE"
+    """
+    if len(name) < MIN_NAME_LENGTH:
+        raise InvalidSessionNameError(f"name must be at least {MIN_NAME_LENGTH} characters")
+
+    if len(name) > MAX_NAME_LENGTH:
+        raise InvalidSessionNameError(f"name must be at most {MAX_NAME_LENGTH} characters")
+
+    if not _NAME_PATTERN.match(name):
+        raise InvalidSessionNameError(
+            "name must be lowercase alphanumeric with hyphens, starting and ending with alphanumeric"
+        )
+
+    if "--" in name:
+        raise InvalidSessionNameError("name cannot contain consecutive hyphens")

forge/session/worktree/__init__.py

@@ -0,0 +1,65 @@
+"""Git worktree utilities for session isolation.
+
+This module provides functions for creating, configuring, and cleaning up
+git worktrees for Forge sessions. Each session can have its own worktree,
+enabling parallel work without manifest conflicts.
+
+Key safety features:
+- Never overwrites tracked files during config copy
+- Never deletes tracked files during cleanup
+- Uses refs/heads/ for branch checks (avoids tag false positives)
+- Validates explicit --branch names
+"""
+
+from .cleanup import (
+    CleanupResult,
+    cleanup_worktree,
+    delete_branch,
+    is_worktree_dirty,
+    remove_config_files,
+    remove_worktree,
+)
+from .config_copy import (
+    ConfigCopyResult,
+    DEFAULT_CONFIG_ALLOWLIST,
+    copy_runtime_config,
+    get_copied_config_files,
+    is_file_tracked,
+)
+from .create import (
+    WorktreeResult,
+    branch_exists,
+    create_worktree,
+    find_git_binary,
+    get_main_repo_root,
+    get_repo_root,
+    resolve_worktree_path,
+    sanitize_branch_name,
+    validate_branch_name,
+)
+
+__all__ = [
+    # create.py
+    "WorktreeResult",
+    "find_git_binary",
+    "get_repo_root",
+    "get_main_repo_root",
+    "branch_exists",
+    "validate_branch_name",
+    "sanitize_branch_name",
+    "resolve_worktree_path",
+    "create_worktree",
+    # config_copy.py
+    "ConfigCopyResult",
+    "DEFAULT_CONFIG_ALLOWLIST",
+    "is_file_tracked",
+    "copy_runtime_config",
+    "get_copied_config_files",
+    # cleanup.py
+    "CleanupResult",
+    "is_worktree_dirty",
+    "remove_config_files",
+    "remove_worktree",
+    "delete_branch",
+    "cleanup_worktree",
+]