mycode-coding-agent 0.1.0__py3-none-any.whl

mycode/persistence/filesystem.py

@@ -0,0 +1,291 @@
+from collections.abc import Mapping
+import json
+import os
+from pathlib import Path
+import stat
+import tempfile
+from typing import Literal
+
+
+TrailingRecordPolicy = Literal["error", "ignore", "truncate"]
+
+
+class FilesystemStorageError(RuntimeError):
+    pass
+
+
+class StorageBoundaryError(FilesystemStorageError):
+    pass
+
+
+class JsonSnapshotError(FilesystemStorageError):
+    pass
+
+
+class JsonLinesError(FilesystemStorageError):
+    pass
+
+
+class JsonLinesCorruptionError(JsonLinesError):
+    pass
+
+
+def ensure_storage_directory(root: str | Path, path: str | Path) -> Path:
+    resolved_root = Path(root).resolve(strict=False)
+    resolved_root.mkdir(parents=True, exist_ok=True)
+    raw = Path(path)
+    requested = raw if raw.is_absolute() else resolved_root / raw
+    if requested.resolve(strict=False) == resolved_root:
+        if not resolved_root.is_dir():
+            raise StorageBoundaryError(
+                f"Storage root is not a directory: {resolved_root}"
+            )
+        return resolved_root
+    candidate = _bounded_path(resolved_root, path)
+    _reject_symlink_components(resolved_root, candidate)
+    candidate.mkdir(parents=True, exist_ok=True)
+    _reject_symlink_components(resolved_root, candidate)
+    if not candidate.is_dir():
+        raise StorageBoundaryError(f"Storage path is not a directory: {candidate}")
+    return candidate
+
+
+def write_json_snapshot(
+    root: str | Path,
+    path: str | Path,
+    payload: Mapping[str, object],
+) -> None:
+    target = _prepare_file_path(root, path)
+    try:
+        content = (
+            json.dumps(
+                dict(payload),
+                ensure_ascii=False,
+                allow_nan=False,
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n"
+        ).encode("utf-8")
+    except (TypeError, ValueError) as error:
+        raise JsonSnapshotError("JSON snapshot payload is not serializable.") from error
+    _atomic_write(target, content)
+
+
+def read_json_snapshot(root: str | Path, path: str | Path) -> dict[str, object]:
+    target = _bounded_file_path(root, path, allow_missing=True)
+    try:
+        payload = json.loads(target.read_text(encoding="utf-8"))
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise JsonSnapshotError(f"Invalid JSON snapshot: {target}") from error
+    except OSError as error:
+        raise JsonSnapshotError(f"Could not read JSON snapshot: {target}") from error
+    if not isinstance(payload, dict):
+        raise JsonSnapshotError(f"JSON snapshot must contain an object: {target}")
+    return payload
+
+
+def append_jsonl_record(
+    root: str | Path,
+    path: str | Path,
+    record: Mapping[str, object],
+) -> None:
+    target = _prepare_file_path(root, path)
+    try:
+        content = (
+            json.dumps(
+                dict(record),
+                ensure_ascii=False,
+                allow_nan=False,
+                separators=(",", ":"),
+                sort_keys=True,
+            )
+            + "\n"
+        ).encode("utf-8")
+    except (TypeError, ValueError) as error:
+        raise JsonLinesError("JSONL record is not serializable.") from error
+
+    flags = os.O_APPEND | os.O_CREAT | os.O_WRONLY
+    if hasattr(os, "O_BINARY"):
+        flags |= os.O_BINARY
+    try:
+        descriptor = os.open(target, flags, 0o600)
+        try:
+            view = memoryview(content)
+            while view:
+                written = os.write(descriptor, view)
+                if written <= 0:
+                    raise OSError("append made no progress")
+                view = view[written:]
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+    except OSError as error:
+        raise JsonLinesError(f"Could not append JSONL record: {target}") from error
+
+
+def read_jsonl_records(
+    root: str | Path,
+    path: str | Path,
+    *,
+    trailing_record: TrailingRecordPolicy = "error",
+) -> list[dict[str, object]]:
+    if trailing_record not in {"error", "ignore", "truncate"}:
+        raise ValueError("trailing_record must be 'error', 'ignore', or 'truncate'.")
+    target = _bounded_file_path(root, path, allow_missing=True)
+    try:
+        content = target.read_bytes()
+    except OSError as error:
+        raise JsonLinesError(f"Could not read JSONL file: {target}") from error
+
+    lines = content.splitlines(keepends=True)
+    has_unterminated_tail = bool(content) and not content.endswith(b"\n")
+    records: list[dict[str, object]] = []
+    offset = 0
+    for index, raw_line in enumerate(lines):
+        line_number = index + 1
+        try:
+            decoded = raw_line.rstrip(b"\r\n").decode("utf-8")
+            record = json.loads(decoded)
+        except (UnicodeError, json.JSONDecodeError, ValueError) as error:
+            is_trailing = index == len(lines) - 1
+            is_recoverable_tail = is_trailing and has_unterminated_tail
+            if not is_recoverable_tail or trailing_record == "error":
+                location = "trailing" if is_trailing else "middle"
+                raise JsonLinesCorruptionError(
+                    f"Invalid {location} JSONL record at line {line_number}: {target}"
+                ) from error
+            if trailing_record == "truncate":
+                _truncate_file(target, offset)
+            break
+        if not isinstance(record, dict):
+            raise JsonLinesCorruptionError(
+                f"JSONL record at line {line_number} must be an object: {target}"
+            )
+        records.append(record)
+        offset += len(raw_line)
+    return records
+
+
+def prepare_jsonl_for_append(root: str | Path, path: str | Path) -> list[dict[str, object]]:
+    """Normalize under exclusive ownership and return the records already parsed."""
+    records = read_jsonl_records(root, path, trailing_record="truncate")
+    target = _bounded_file_path(root, path)
+    try:
+        with target.open("r+b") as stream:
+            stream.seek(0, os.SEEK_END)
+            if stream.tell():
+                stream.seek(-1, os.SEEK_END)
+                if stream.read(1) != b"\n":
+                    stream.write(b"\n")
+                    stream.flush()
+                    os.fsync(stream.fileno())
+    except OSError as error:
+        raise JsonLinesError("Could not prepare JSONL for append.") from error
+    return records
+
+
+def _prepare_file_path(root: str | Path, path: str | Path) -> Path:
+    resolved_root = Path(root).resolve(strict=False)
+    resolved_root.mkdir(parents=True, exist_ok=True)
+    target = _bounded_path(resolved_root, path)
+    ensure_storage_directory(resolved_root, target.parent)
+    return _bounded_file_path(resolved_root, target, allow_missing=True)
+
+
+def _bounded_file_path(
+    root: str | Path,
+    path: str | Path,
+    *,
+    allow_missing: bool = False,
+) -> Path:
+    resolved_root = Path(root).resolve(strict=False)
+    target = _bounded_path(resolved_root, path)
+    _reject_symlink_components(resolved_root, target)
+    if target.is_symlink():
+        raise StorageBoundaryError(f"Storage file cannot be a symlink: {target}")
+    if not allow_missing and not target.is_file():
+        raise JsonSnapshotError(f"Storage file does not exist: {target}")
+    if target.exists() and not target.is_file():
+        raise StorageBoundaryError(f"Storage path is not a file: {target}")
+    return target
+
+
+def _bounded_path(root: Path, path: str | Path) -> Path:
+    raw = Path(path)
+    if ".." in raw.parts:
+        raise StorageBoundaryError(f"Storage path contains traversal: {raw}")
+    candidate = raw if raw.is_absolute() else root / raw
+    resolved = candidate.resolve(strict=False)
+    if resolved == root or not resolved.is_relative_to(root):
+        raise StorageBoundaryError(f"Storage path escapes its root: {candidate}")
+    return candidate
+
+
+def validate_storage_path(root: str | Path, path: str | Path) -> Path:
+    """Check existing components without creating or resolving away links."""
+    boundary = Path(root).resolve(strict=False)
+    candidate = _bounded_path(boundary, path)
+    _reject_symlink_components(boundary, candidate)
+    return candidate
+
+
+def _reject_symlink_components(root: Path, candidate: Path) -> None:
+    try:
+        relative = candidate.relative_to(root)
+    except ValueError as error:
+        raise StorageBoundaryError(
+            f"Storage path escapes its root: {candidate}"
+        ) from error
+    current = root
+    for part in relative.parts:
+        current = current / part
+        try:
+            info = current.lstat()
+        except FileNotFoundError:
+            continue
+        if current.is_symlink() or getattr(info, "st_file_attributes", 0) & getattr(
+            stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0,
+        ):
+            raise StorageBoundaryError(
+                f"Storage path contains a symlink below its root: {current}"
+            )
+
+
+def _atomic_write(path: Path, content: bytes) -> None:
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary:
+            temporary.write(content)
+            temporary.flush()
+            os.fsync(temporary.fileno())
+            temporary_path = Path(temporary.name)
+        os.replace(temporary_path, path)
+    except OSError as error:
+        raise JsonSnapshotError(
+            f"Could not atomically write JSON snapshot: {path}"
+        ) from error
+    finally:
+        if temporary_path is not None:
+            try:
+                temporary_path.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def _truncate_file(path: Path, size: int) -> None:
+    try:
+        with path.open("r+b") as stream:
+            stream.truncate(size)
+            stream.flush()
+            os.fsync(stream.fileno())
+    except OSError as error:
+        raise JsonLinesError(
+            f"Could not truncate trailing JSONL record: {path}"
+        ) from error

mycode/persistence/project_storage.py

@@ -0,0 +1,208 @@
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import re
+
+from mycode.persistence.filesystem import (
+    JsonSnapshotError,
+    StorageBoundaryError,
+    ensure_storage_directory,
+    read_json_snapshot,
+    write_json_snapshot,
+    validate_storage_path,
+)
+from mycode.project import ProjectIdentity
+
+
+PROJECT_METADATA_VERSION = 1
+PROJECT_HASH_LENGTH = 12
+MAX_PROJECT_BASENAME_CHARS = 80
+PROJECT_COMPONENT_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+WINDOWS_RESERVED_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"COM{number}" for number in range(1, 10)}
+    | {f"LPT{number}" for number in range(1, 10)}
+)
+
+
+class ProjectStorageError(RuntimeError):
+    pass
+
+
+class ProjectMetadataError(ProjectStorageError):
+    pass
+
+
+@dataclass(frozen=True)
+class SessionStorageLayout:
+    root: Path
+    transcript_path: Path
+    meta_path: Path
+    compact_path: Path
+    artifacts_directory: Path
+    subagents_directory: Path
+    lock_path: Path
+
+    def subagent_log_path(self, run_id: str) -> Path:
+        validate_storage_component(run_id, field_name="run_id")
+        return self.subagents_directory / f"{run_id}.jsonl"
+
+
+@dataclass(frozen=True)
+class ProjectStorage:
+    identity: ProjectIdentity
+    projects_root: Path
+    project_directory: Path
+    metadata_path: Path
+    sessions_directory: Path
+    locks_directory: Path
+
+    @classmethod
+    def open(
+        cls,
+        identity: ProjectIdentity,
+        *,
+        projects_root: str | Path | None = None,
+    ) -> "ProjectStorage":
+        _validate_project_identity(identity)
+        root = Path(
+            default_projects_root() if projects_root is None else projects_root
+        ).resolve(strict=False)
+        root.mkdir(parents=True, exist_ok=True)
+        directory_name = project_directory_name(identity)
+        try:
+            project_directory = ensure_storage_directory(root, directory_name)
+            metadata_path = project_directory / "project.json"
+            sessions_directory = project_directory / "sessions"
+            locks_directory = project_directory / "locks"
+            storage = cls(
+                identity=identity,
+                projects_root=root,
+                project_directory=project_directory,
+                metadata_path=metadata_path,
+                sessions_directory=sessions_directory,
+                locks_directory=locks_directory,
+            )
+            storage._ensure_metadata()
+            ensure_storage_directory(project_directory, sessions_directory)
+            ensure_storage_directory(project_directory, locks_directory)
+            return storage
+        except (OSError, JsonSnapshotError, StorageBoundaryError) as error:
+            raise ProjectStorageError(
+                f"Could not open project storage for {identity.workspace_root}"
+            ) from error
+
+    def session(
+        self,
+        session_id: str,
+        *,
+        create: bool = False,
+    ) -> SessionStorageLayout:
+        validate_storage_component(session_id, field_name="session_id")
+        session_root = self.sessions_directory / session_id
+        try:
+            # Check the project entry before using it as the narrower boundary.
+            validate_storage_path(self.projects_root, self.project_directory)
+            validate_storage_path(self.project_directory, session_root)
+            validate_storage_path(self.project_directory, self.locks_directory)
+            if create:
+                session_root = ensure_storage_directory(
+                    self.project_directory,
+                    session_root,
+                )
+                artifacts = ensure_storage_directory(session_root, "artifacts")
+                subagents = ensure_storage_directory(session_root, "subagents")
+            else:
+                if session_root.is_symlink():
+                    raise StorageBoundaryError(
+                        f"Session directory cannot be a symlink: {session_root}"
+                    )
+                resolved = session_root.resolve(strict=False)
+                if not resolved.is_relative_to(self.sessions_directory):
+                    raise StorageBoundaryError(
+                        f"Session directory escapes project storage: {session_root}"
+                    )
+                artifacts = session_root / "artifacts"
+                subagents = session_root / "subagents"
+            for target in (artifacts, subagents):
+                validate_storage_path(self.project_directory, target)
+        except (OSError, StorageBoundaryError) as error:
+            raise ProjectStorageError(
+                f"Could not resolve session storage for {session_id!r}"
+            ) from error
+        return SessionStorageLayout(
+            root=session_root,
+            transcript_path=session_root / "transcript.jsonl",
+            meta_path=session_root / "meta.json",
+            compact_path=session_root / "compact.json",
+            artifacts_directory=artifacts,
+            subagents_directory=subagents,
+            lock_path=self.locks_directory / f"{session_id}.lock",
+        )
+
+    def _ensure_metadata(self) -> None:
+        expected = {
+            "version": PROJECT_METADATA_VERSION,
+            "project_key": self.identity.key,
+            "workspace_root": str(self.identity.workspace_root),
+        }
+        if not self.metadata_path.exists():
+            write_json_snapshot(
+                self.project_directory,
+                self.metadata_path,
+                expected,
+            )
+            return
+        actual = read_json_snapshot(self.project_directory, self.metadata_path)
+        if actual != expected:
+            raise ProjectMetadataError(
+                "Project metadata does not match the canonical workspace: "
+                f"{self.metadata_path}"
+            )
+
+
+def default_projects_root() -> Path:
+    return Path.home() / ".mycode" / "projects"
+
+
+def project_directory_name(identity: ProjectIdentity) -> str:
+    _validate_project_identity(identity)
+    basename = identity.workspace_root.name or "workspace"
+    safe_basename = _safe_project_basename(basename)
+    return f"{safe_basename}-{identity.key[:PROJECT_HASH_LENGTH]}"
+
+
+def _safe_project_basename(value: str) -> str:
+    cleaned = "".join(
+        "-" if character in '<>:"/\\|?*' or ord(character) < 32 else character
+        for character in value
+    )
+    cleaned = re.sub(r"-+", "-", cleaned).strip(" .-_")
+    cleaned = cleaned[:MAX_PROJECT_BASENAME_CHARS].rstrip(" .") or "workspace"
+    if cleaned.partition(".")[0].upper() in WINDOWS_RESERVED_NAMES:
+        cleaned = f"workspace-{cleaned}"
+    return cleaned
+
+
+def _validate_project_identity(identity: ProjectIdentity) -> None:
+    if len(identity.key) != 64 or any(
+        character not in "0123456789abcdef" for character in identity.key
+    ):
+        raise ProjectStorageError("ProjectIdentity.key must be a lowercase SHA-256.")
+    canonical = ProjectIdentity.from_workspace(identity.workspace_root)
+    if canonical != identity:
+        raise ProjectStorageError(
+            "ProjectIdentity does not match its canonical workspace path."
+        )
+
+
+def validate_storage_component(value: str, *, field_name: str) -> None:
+    """Validate a Session or SubAgent ID using the shared portable path rules."""
+    if (
+        not PROJECT_COMPONENT_PATTERN.fullmatch(value)
+        or value in {".", ".."}
+        or value.rstrip(" .") != value
+        or value.partition(".")[0].upper() in WINDOWS_RESERVED_NAMES
+        or os.path.isabs(value)
+    ):
+        raise ProjectStorageError(f"Invalid {field_name}: {value!r}")

mycode/persistence/session_lock.py

@@ -0,0 +1,138 @@
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+import errno
+import os
+from pathlib import Path
+import time
+from typing import BinaryIO
+
+
+DEFAULT_SESSION_LOCK_TIMEOUT_SECONDS = 30.0
+DEFAULT_SESSION_LOCK_POLL_SECONDS = 0.05
+
+
+class SessionLockError(RuntimeError):
+    pass
+
+
+class SessionLockTimeoutError(SessionLockError):
+    pass
+
+
+@dataclass(frozen=True)
+class SessionLifecycleLock:
+    """Exclusive OS lock held for the complete lifetime of one session owner."""
+
+    path: Path
+    timeout_seconds: float = DEFAULT_SESSION_LOCK_TIMEOUT_SECONDS
+    poll_seconds: float = DEFAULT_SESSION_LOCK_POLL_SECONDS
+
+    def __post_init__(self) -> None:
+        if self.timeout_seconds < 0:
+            raise ValueError("timeout_seconds must be at least 0.")
+        if self.poll_seconds <= 0:
+            raise ValueError("poll_seconds must be above 0.")
+        raw_path = Path(self.path)
+        if raw_path.is_symlink():
+            raise SessionLockError("Session lifecycle lock file cannot be a symlink.")
+        object.__setattr__(
+            self,
+            "path",
+            raw_path.parent.resolve(strict=False) / raw_path.name,
+        )
+
+    @contextmanager
+    def acquire(self) -> Iterator[None]:
+        with _acquire_lifecycle_lock(
+            self.path,
+            timeout_seconds=self.timeout_seconds,
+            poll_seconds=self.poll_seconds,
+        ):
+            yield
+
+
+@contextmanager
+def _acquire_lifecycle_lock(
+    path: Path,
+    *,
+    timeout_seconds: float,
+    poll_seconds: float,
+) -> Iterator[None]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.is_symlink():
+        raise SessionLockError("Session lifecycle lock file cannot be a symlink.")
+    with path.open("a+b") as stream:
+        _ensure_lock_byte(stream)
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            try:
+                _lock_stream(stream)
+                break
+            except OSError as error:
+                if not _is_lock_contention(error):
+                    raise SessionLockError(
+                        f"Failed to acquire session lifecycle lock: {path}"
+                    ) from error
+                if time.monotonic() >= deadline:
+                    raise SessionLockTimeoutError(
+                        "Timed out waiting for another session lifecycle owner to finish."
+                    ) from error
+                time.sleep(
+                    min(
+                        poll_seconds,
+                        max(0.0, deadline - time.monotonic()),
+                    )
+                )
+
+        try:
+            yield
+        finally:
+            try:
+                _unlock_stream(stream)
+            except OSError as error:
+                raise SessionLockError(
+                    f"Failed to release session lifecycle lock: {path}"
+                ) from error
+
+
+def _ensure_lock_byte(stream: BinaryIO) -> None:
+    stream.seek(0, os.SEEK_END)
+    if stream.tell() == 0:
+        stream.write(b"\0")
+        stream.flush()
+        os.fsync(stream.fileno())
+
+
+def _lock_stream(stream: BinaryIO) -> None:
+    stream.seek(0)
+    if os.name == "nt":
+        import msvcrt
+
+        msvcrt.locking(stream.fileno(), msvcrt.LK_NBLCK, 1)
+        return
+
+    import fcntl
+
+    fcntl.flock(stream.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+
+def _unlock_stream(stream: BinaryIO) -> None:
+    stream.seek(0)
+    if os.name == "nt":
+        import msvcrt
+
+        msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
+        return
+
+    import fcntl
+
+    fcntl.flock(stream.fileno(), fcntl.LOCK_UN)
+
+
+def _is_lock_contention(error: OSError) -> bool:
+    return error.errno in {
+        errno.EACCES,
+        errno.EAGAIN,
+        errno.EDEADLK,
+    } or getattr(error, "winerror", None) in {33, 36}