shikiru-cli 0.2.0__py3-none-any.whl

shikiru/workspace/messages.py

@@ -0,0 +1,107 @@
+"""Queues operator messages per role and delivers them into the next turn."""
+
+from __future__ import annotations
+
+from itertools import chain
+from typing import TYPE_CHECKING
+
+from shikiru.paths import MESSAGES_DIR_NAME, queued_messages_dir, run_dir, turns_dir
+from shikiru.private import make_private_dir, write_private_text
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from shikiru.domain.tasks import Role
+
+MESSAGE_NUMBER_WIDTH = 3
+MESSAGE_SUFFIX = ".md"
+MESSAGE_KEY_SEPARATOR = "-"
+PARTIAL_SUFFIX = ".partial"
+COMMAND_KEY_PREFIX = "c"
+
+
+class OperatorMessages:
+    """Files the Operator's messages under `runs/T/messages/<role>/NNN.md`."""
+
+    def __init__(self, project_root: Path) -> None:
+        """Queue messages under `project_root`'s run directories."""
+        self._project_root = project_root
+
+    def queue(self, task_id: str, role: Role, text: str, key: str) -> Path:
+        """Write `text` as the role's next numbered message and return its path.
+
+        The file name carries `key`; a message already filed under `key`, queued or delivered,
+        is returned instead of being written again, so a replayed request queues it once.
+        """
+        existing = self._find(task_id, key)
+        if existing is not None:
+            return existing
+        directory = queued_messages_dir(self._project_root, task_id, role.value)
+        make_private_dir(directory)
+        number = self._last_number(task_id) + 1
+        path = _message_path(directory, number, key)
+        _write_atomically(path, text)
+        return path
+
+    def deliver(self, task_id: str, role: Role, turn_dir: Path) -> list[Path]:
+        """Move the role's queued messages into `turn_dir/messages/` and return them in order."""
+        directory = queued_messages_dir(self._project_root, task_id, role.value)
+        queued = _messages(directory) if directory.is_dir() else []
+        if not queued:
+            return []
+        target = turn_dir / MESSAGES_DIR_NAME
+        make_private_dir(target)
+        return [path.rename(target / path.name) for path in queued]
+
+    def requeue(self, task_id: str, role: Role, turn_dir: Path) -> None:
+        """Return `turn_dir`'s delivered messages to the role's queue, ahead of newer ones.
+
+        Each message moves back under its own name, and numbers only grow, so the queue order is
+        the filing order; one that has not moved yet when the process dies is returned by the
+        next call, never lost.
+        """
+        delivered_dir = turn_dir / MESSAGES_DIR_NAME
+        delivered = _messages(delivered_dir) if delivered_dir.is_dir() else []
+        if not delivered:
+            return
+        directory = queued_messages_dir(self._project_root, task_id, role.value)
+        make_private_dir(directory)
+        for path in delivered:
+            path.rename(directory / path.name)
+        delivered_dir.rmdir()
+
+    def _filed(self, task_id: str, pattern: str = f"*{MESSAGE_SUFFIX}") -> Iterator[Path]:
+        queued = run_dir(self._project_root, task_id).glob(f"{MESSAGES_DIR_NAME}/*/{pattern}")
+        delivered = turns_dir(self._project_root, task_id).glob(f"*/{MESSAGES_DIR_NAME}/{pattern}")
+        return chain(queued, delivered)
+
+    def _last_number(self, task_id: str) -> int:
+        return max((_number(path) for path in self._filed(task_id)), default=0)
+
+    def _find(self, task_id: str, key: str) -> Path | None:
+        return next(self._filed(task_id, f"*{MESSAGE_KEY_SEPARATOR}{key}{MESSAGE_SUFFIX}"), None)
+
+
+def command_message_key(command_id: int) -> str:
+    """Return the message key that ties a filed message to the command that queued it."""
+    return f"{COMMAND_KEY_PREFIX}{command_id}"
+
+
+def _number(path: Path) -> int:
+    return int(path.stem.partition(MESSAGE_KEY_SEPARATOR)[0])
+
+
+def _write_atomically(path: Path, text: str) -> None:
+    partial = path.with_name(path.name + PARTIAL_SUFFIX)
+    write_private_text(partial, text)
+    partial.replace(path)
+
+
+def _messages(directory: Path) -> list[Path]:
+    return sorted(directory.glob(f"*{MESSAGE_SUFFIX}"))
+
+
+def _message_path(directory: Path, number: int, key: str) -> Path:
+    name = f"{number:0{MESSAGE_NUMBER_WIDTH}d}{MESSAGE_KEY_SEPARATOR}{key}{MESSAGE_SUFFIX}"
+    return directory / name

shikiru/workspace/reports.py

@@ -0,0 +1,145 @@
+"""Read validated reports from one completed turn directory."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+from pydantic import ValidationError
+
+from shikiru.domain.reports import (
+    COMMIT_SUBJECT_FIELD,
+    DECISION_ACCEPT,
+    HELPER_REPORT_FILENAME,
+    REPORT_DECISION_FIELD,
+    REPORT_FILENAME,
+    REPORT_KIND_FILENAME,
+    FeedbackVerdict,
+    PlanReport,
+    Report,
+    ReportKind,
+    Verdict,
+    model_for,
+)
+from shikiru.errors import ShikiruError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_REPORT_FILENAMES = (REPORT_FILENAME, HELPER_REPORT_FILENAME)
+ENGINE_VERDICT_FILENAME = "engine-verdict.json"
+LEGACY_COMMIT_SUBJECT = "chore: legacy report"
+
+
+class InvalidTurnReportError(ShikiruError):
+    """A turn report file exists but its kind, JSON or schema is invalid."""
+
+
+@dataclass(frozen=True)
+class LoadedReport:
+    """A validated report and the kind declared by its turn directory."""
+
+    kind: ReportKind
+    report: Report
+
+
+def load_turn_report(turn_dir: Path) -> LoadedReport | None:
+    """Load a valid report, return `None` only when no report files exist."""
+    kind_path = turn_dir / REPORT_KIND_FILENAME
+    kind = _read_kind(kind_path)
+    if kind is None:
+        if any(_file_exists(turn_dir / filename) for filename in _REPORT_FILENAMES):
+            message = f"report kind is missing: {kind_path}"
+            raise InvalidTurnReportError(message)
+        return None
+    model = model_for(kind)
+    invalid: InvalidTurnReportError | None = None
+    for filename in _REPORT_FILENAMES:
+        try:
+            report = _read_report(turn_dir / filename, model)
+        except InvalidTurnReportError as error:
+            if invalid is None:
+                invalid = error
+            continue
+        if report is not None:
+            return LoadedReport(kind=kind, report=report)
+    if invalid is not None:
+        raise invalid
+    return None
+
+
+def load_engine_verdict(turn_dir: Path) -> Verdict | None:
+    """Load the engine-computed verdict stored beside a turn's agent report."""
+    path = turn_dir / ENGINE_VERDICT_FILENAME
+    try:
+        text = path.read_text()
+    except FileNotFoundError:
+        return None
+    except (OSError, UnicodeError) as error:
+        message = f"cannot read engine verdict {path}: {error}"
+        raise InvalidTurnReportError(message) from error
+    model = (
+        FeedbackVerdict
+        if _read_kind(turn_dir / REPORT_KIND_FILENAME) is ReportKind.FEEDBACK_VERDICT
+        else Verdict
+    )
+    data = json.loads(text)
+    return cast("Verdict", _validate_stored_report(data, model))
+
+
+def _file_exists(path: Path) -> bool:
+    try:
+        path.stat()
+    except FileNotFoundError:
+        return False
+    except OSError as error:
+        message = f"cannot inspect report file {path}: {error}"
+        raise InvalidTurnReportError(message) from error
+    return True
+
+
+def _read_kind(path: Path) -> ReportKind | None:
+    try:
+        value = path.read_text().strip()
+    except FileNotFoundError:
+        return None
+    except (OSError, UnicodeError) as error:
+        message = f"cannot read report kind {path}: {error}"
+        raise InvalidTurnReportError(message) from error
+    try:
+        return ReportKind(value)
+    except ValueError as error:
+        message = f"invalid report kind in {path}: {value!r}"
+        raise InvalidTurnReportError(message) from error
+
+
+def _read_report(path: Path, model: type[Report]) -> Report | None:
+    try:
+        text = path.read_text()
+    except FileNotFoundError:
+        return None
+    except (OSError, UnicodeError) as error:
+        message = f"cannot read report {path}: {error}"
+        raise InvalidTurnReportError(message) from error
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as error:
+        message = f"invalid JSON in report {path}: {error}"
+        raise InvalidTurnReportError(message) from error
+    try:
+        return _validate_stored_report(data, model)
+    except ValidationError as error:
+        message = f"invalid report {path}: {error}"
+        raise InvalidTurnReportError(message) from error
+
+
+def _validate_stored_report(data: object, model: type[Report]) -> Report:
+    if not isinstance(data, dict) or COMMIT_SUBJECT_FIELD in data:
+        return model.model_validate(data)
+    fields = cast("dict[str, object]", data)
+    if model is PlanReport or (
+        model in (Verdict, FeedbackVerdict) and fields.get(REPORT_DECISION_FIELD) == DECISION_ACCEPT
+    ):
+        return model.model_validate({**fields, COMMIT_SUBJECT_FIELD: LEGACY_COMMIT_SUBJECT})
+    return model.model_validate(data)

shikiru/workspace/roots.py

@@ -0,0 +1,180 @@
+"""Task roots: one worktree of the project repository per task, and cleanup."""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+from typing import TYPE_CHECKING
+
+from shikiru.domain.tasks import RepoState
+from shikiru.errors import StaleTaskBranchError
+from shikiru.paths import EXCLUDE_LINE, run_dir, task_root
+from shikiru.private import make_private_dir
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from shikiru.config.settings import RepoConfig
+    from shikiru.workspace.base_refs import BaseRefs
+    from shikiru.workspace.caches import CacheCloner
+    from shikiru.workspace.git import Git
+
+BRANCH_PREFIX = "shikiru/"
+SEED_COMMIT_MESSAGE = "Carry over the tracker changes of the superseded task"
+__all__ = ["EXCLUDE_LINE", "TaskRootBuilder", "branch_name", "run_dir", "slugify", "task_root"]
+
+_SLUG_MAX_LENGTH = 40
+_SHORT_SHA = 10
+_NON_ALPHANUMERIC = re.compile(r"[^a-z0-9]+")
+GIT_LINK_NAME = ".git"
+_LOGGER = logging.getLogger(__name__)
+
+
+def slugify(title: str) -> str:
+    """Turn `title` into a stable, filesystem-safe branch slug.
+
+    Lowercases, replaces every run of non-alphanumeric characters with a single `-`, trims
+    leading and trailing `-`, and caps the result at `_SLUG_MAX_LENGTH` characters.
+    """
+    collapsed = _NON_ALPHANUMERIC.sub("-", title.lower()).strip("-")
+    return collapsed[:_SLUG_MAX_LENGTH].strip("-")
+
+
+def branch_name(task_id: str, title: str) -> str:
+    """Build the deterministic task branch name `shikiru/T-n-<slug>`."""
+    return f"{BRANCH_PREFIX}{task_id}-{slugify(title)}"
+
+
+class TaskRootBuilder:
+    """Builds and tears down `.shikiru/worktrees/T-n/` for a task."""
+
+    def __init__(
+        self,
+        git: Git,
+        project_root: Path,
+        repo: RepoConfig,
+        cache_cloner: CacheCloner,
+        base_refs: BaseRefs,
+        *,
+        trackers: Sequence[str],
+    ) -> None:
+        """Build task roots starting from the ref `base_refs` picks, cloning configured caches."""
+        self._git = git
+        self._project_root = project_root
+        self._repo = repo
+        self._trackers = trackers
+        self._cache_cloner = cache_cloner
+        self._base_refs = base_refs
+        self._warned_cow_unsupported = False
+
+    async def build(self, task_id: str, title: str, *, seed_branch: str | None = None) -> RepoState:
+        """Build (or reuse) `task_id`'s task root: one worktree of the project repository.
+
+        A new root of a replacement task gets, as its first commit, the tracker changes of
+        `seed_branch` (the superseded task's branch) and nothing else of it.
+
+        Idempotent: calling this again with the same arguments creates nothing twice, whether
+        the branch, the worktree or both already exist.
+        """
+        root = task_root(self._project_root, task_id)
+        make_private_dir(root.parent)
+        branch = branch_name(task_id, title)
+        project = self._project_root
+        repo = self._repo
+        base = repo.base if repo.base is not None else await self._git.current_branch(project)
+        base_ref = await self._base_refs.resolve(base)
+        base_sha = await self._git.rev_parse(project, base_ref)
+        await self._git.append_to_exclude(project, EXCLUDE_LINE)
+        if not await self._git.worktree_exists(project, root):
+            if await self._git.branch_exists(project, branch):
+                await self._require_fresh_branch(branch, base_sha)
+                await self._git.worktree_add_existing_branch(project, root, branch)
+            else:
+                await self._git.worktree_add(project, root, new_branch=branch, base=base_ref)
+                if seed_branch is not None:
+                    await self._seed_trackers(root, branch, base_ref, seed_branch)
+        if repo.caches:
+            clone_result = await self._cache_cloner.clone(
+                project, root, repo.caches, await self._git.ignored_paths(project)
+            )
+            if clone_result.warning is not None and not self._warned_cow_unsupported:
+                _LOGGER.warning("%s", clone_result.warning)
+                self._warned_cow_unsupported = True
+        return RepoState(base=base, base_ref=base_ref, base_sha=base_sha, branch=branch)
+
+    async def _require_fresh_branch(self, branch: str, base_sha: str) -> None:
+        if await self._git.rev_parse(self._project_root, branch) != base_sha:
+            message = (
+                f"branch {branch} already exists and is not at the base {base_sha[:_SHORT_SHA]}: "
+                f"it holds an earlier task's work; inspect it, then delete it "
+                f"(git branch -D {branch}) or rename it and submit the task again"
+            )
+            raise StaleTaskBranchError(message)
+
+    async def _seed_trackers(
+        self, root: Path, branch: str, base_ref: str, seed_branch: str
+    ) -> None:
+        project = self._project_root
+        if not self._trackers or not await self._git.branch_exists(project, seed_branch):
+            return
+        try:
+            patch = await self._git.diff_patch(
+                project, f"{base_ref}...{seed_branch}", self._trackers
+            )
+            if patch:
+                await self._git.apply_patch(root, patch)
+                await self._git.commit(root, SEED_COMMIT_MESSAGE)
+        except Exception:
+            await self._git.worktree_remove(project, root)
+            await self._git.delete_branch(project, branch)
+            raise
+
+    async def _holds_unintegrated_work(self, root: Path, repo: RepoState) -> bool:
+        if await self._git.worktree_removal_pending(self._project_root, root):
+            return False
+        if await self._git.head_branch(root) != repo.branch:
+            return True
+        return bool(await self._git.status_porcelain(root))
+
+    async def cleanup(
+        self,
+        task_id: str,
+        repo: RepoState | None,
+        *,
+        integrated: bool = False,
+        keep_work: bool = False,
+    ) -> Path | None:
+        """Remove the task's worktree, its merged branch, and last its task root.
+
+        The branch is merged when it is an ancestor of the local base or when the caller says
+        the task is `integrated` (a pull request merged on the remote leaves the local base
+        behind, and a squash leaves the branch out of its history). Idempotent and tolerant of
+        a worktree already removed. Never deletes an unmerged branch, never follows a symlink
+        out of the task root, and never erases unintegrated work: a worktree whose `HEAD` is off
+        the task branch, one with tracked or untracked changes (git-ignored files excepted) and
+        its branch stay, and so does a root that holds anything but the git link once its
+        worktree metadata is gone (git cannot tell what is uncommitted there); the kept task
+        root is returned. With `keep_work` the caller knows the branch holds commits that are
+        nowhere else: its worktree and branch stay. A removal that began (it passed those checks)
+        and was interrupted by a failure or timeout leaves a half-deleted worktree that the next
+        cleanup removes without taking the deletions for uncommitted work.
+        """
+        project = self._project_root
+        root = task_root(project, task_id)
+        if repo is not None:
+            if await self._git.worktree_exists(project, root):
+                if keep_work or await self._holds_unintegrated_work(root, repo):
+                    return root
+                await self._git.worktree_remove(project, root)
+            if await self._git.branch_exists(project, repo.branch) and (
+                integrated
+                or await self._git.merge_base_is_ancestor(project, repo.branch, repo.base)
+            ):
+                await self._git.delete_branch(project, repo.branch)
+        if root.exists():
+            if repo is not None and any(entry.name != GIT_LINK_NAME for entry in root.iterdir()):
+                return root
+            shutil.rmtree(root)
+        return None