okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/worktree/git_ops.py

@@ -0,0 +1,165 @@
+"""worktree 가 쓰는 git 명령 한 겹.
+
+`_git` 은 `check=False` 라서 호출부가 returncode 를 보고 판단한다. 이 층은
+okstra 의 규칙을 하나도 모른다 — 브랜치가 존재하는지, HEAD 가 무엇인지,
+머지가 충돌했는지 같은 git 사실만 답한다. okstra 가 무엇을 무시하기로 했는지는
+`cleanliness` 가, 무엇을 옮기기로 했는지는 `sync_config` 가 안다.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(cwd), *args],
+        capture_output=True, text=True, check=False,
+    )
+
+
+def _is_inside_non_main_worktree(project_root: Path) -> bool:
+    """True iff project_root is inside a git worktree that is NOT the
+    repository's main checkout. Detection rule: `--git-dir` (per-worktree
+    .git pointer) differs from `--git-common-dir` (shared object store).
+    """
+    common = _git(project_root, "rev-parse", "--git-common-dir")
+    per_tree = _git(project_root, "rev-parse", "--git-dir")
+    if common.returncode != 0 or per_tree.returncode != 0:
+        return False
+    common_abs = (project_root / common.stdout.strip()).resolve()
+    per_tree_abs = (project_root / per_tree.stdout.strip()).resolve()
+    return common_abs != per_tree_abs
+
+
+def is_git_work_tree(project_root: Path) -> bool:
+    """project_root 가 git work tree 내부인지 판정하는 public git-introspection seam.
+
+    git 미설치(FileNotFoundError) 를 포함한 모든 실패는 False — 호출자(migrate
+    등)가 non-git 레이아웃으로 안전하게 폴백할 수 있도록 한다. 과거 migrate.py
+    가 같은 판정을 자체 구현(`--show-toplevel`)했는데 이 seam 으로 통합한다."""
+    try:
+        res = _git(project_root, "rev-parse", "--is-inside-work-tree")
+    except (OSError, FileNotFoundError):
+        return False
+    return res.returncode == 0 and res.stdout.strip() == "true"
+
+
+def _branch_exists(project_root: Path, branch: str) -> bool:
+    res = _git(project_root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
+    return res.returncode == 0
+
+
+def _branch_checkout_path(project_root: Path, branch: str) -> str:
+    """The worktree that currently has *branch* checked out, or "" when none does.
+
+    `git branch -D` refuses to delete a checked-out branch, so an existing-branch
+    error that only recommends `-D` is unfollowable whenever the branch is the
+    main checkout's HEAD. Callers use this to name the extra step instead.
+    """
+    res = _git(project_root, "worktree", "list", "--porcelain")
+    if res.returncode != 0:
+        return ""
+    current = ""
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            current = line[len("worktree "):].strip()
+        elif line.strip() == f"branch refs/heads/{branch}":
+            return current
+    return ""
+
+
+def _branch_exists_message(project_root: Path, branch: str, kind: str) -> str:
+    """Existing-branch error text whose remedy is actually runnable."""
+    checkout = _branch_checkout_path(project_root, branch)
+    if checkout:
+        return (
+            f"{kind} worktree branch already exists: {branch}, and it is checked "
+            f"out at {checkout}. `git branch -D {branch}` will refuse while it is "
+            f"checked out — switch that checkout to another branch first "
+            f"(`git -C {checkout} switch <other-branch>`), then delete it, or "
+            "choose a different work-category before retrying."
+        )
+    return (
+        f"{kind} worktree branch already exists: {branch}. "
+        f"Delete it (`git branch -D {branch}`) or choose a different "
+        "work-category before retrying."
+    )
+
+
+def _head_sha(cwd: Path) -> str:
+    res = _git(cwd, "rev-parse", "HEAD")
+    if res.returncode != 0:
+        return ""
+    return res.stdout.strip()
+
+
+def _resolve_commit_sha(cwd: Path, ref: str) -> str:
+    """Resolve a user-supplied ref (branch, tag, short/long SHA) to a full
+    commit SHA in `cwd`. Returns empty string when the ref is not resolvable
+    so the caller can raise a contextual error.
+    """
+    res = _git(cwd, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+    if res.returncode != 0:
+        return ""
+    return res.stdout.strip()
+
+
+def main_worktree_path(project_root: Path) -> Path:
+    """Locate the repository's MAIN worktree (the original checkout).
+
+    `git worktree list --porcelain` lists worktrees in a stable order
+    where the first `worktree <path>` block is the main checkout.
+    Falls back to `project_root` if parsing fails — caller still gets
+    a working path, sync-dir links just point at the caller's tree
+    (the prior behaviour).
+    """
+    res = _git(project_root, "worktree", "list", "--porcelain")
+    if res.returncode != 0:
+        return project_root
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            return Path(line[len("worktree "):].strip())
+    return project_root
+
+
+def is_ancestor(cwd, commit: str, head: str) -> bool:
+    """True iff `commit` is an ancestor of `head` (both non-empty)."""
+    if not commit or not head:
+        return False
+    return _git(Path(cwd), "merge-base", "--is-ancestor", commit, head).returncode == 0
+
+
+class MergeError(RuntimeError):
+    """`git merge` 가 내용 충돌이 아닌 사유로 실패했을 때(추적되지 않은 파일
+    덮어쓰기, 진행 중인 머지 잔존, 없는 브랜치 등) 던진다. 충돌 파일이 0개인
+    실패를 '충돌'로 둔갑시키지 않고 git stderr 를 그대로 노출해 호출자가 올바른
+    복구 경로로 안내하도록 한다."""
+
+
+def merge_branch(cwd, branch: str, *, no_ff: bool) -> list[str] | None:
+    """`branch` 를 cwd 의 현재 HEAD 에 머지한다. 성공이면 None, 내용 충돌이면
+    abort 후 충돌 파일 목록을 반환한다(최소 1개). 충돌이 아닌 머지 실패는
+    MergeError 로 던진다 — 충돌 0개를 충돌로 보고하지 않기 위함. 호출자가 충돌
+    목록을 HandoffConflict/IntegrateError 등 적절한 예외로 변환한다 — 머지·
+    충돌감지·abort 시퀀스의 단일 지점."""
+    args = ["merge", "--no-ff", "--no-edit", branch] if no_ff \
+        else ["merge", "--no-edit", branch]
+    res = _git(Path(cwd), *args)
+    if res.returncode == 0:
+        return None
+    conflicts = _git(Path(cwd), "diff", "--name-only",
+                     "--diff-filter=U").stdout.split()
+    _git(Path(cwd), "merge", "--abort")
+    if not conflicts:
+        raise MergeError((res.stderr or res.stdout).strip()
+                         or f"git merge {branch} failed (exit={res.returncode})")
+    return conflicts
+
+
+def remove_worktree_force(cwd, worktree_path) -> subprocess.CompletedProcess:
+    """워크트리를 강제 제거한다. provision_*_worktree 가 워크트리에 .okstra·
+    synced 디렉터리/파일 symlink(untracked) 를 깔기 때문에 plain remove 는 그
+    잔여물 때문에 git 이 거부한다 — dirty 게이트로 실사용자 변경을 막은 뒤
+    --force 로 okstra 잔여물만 정리하는 단일 지점."""
+    return _git(Path(cwd), "worktree", "remove", "--force", str(worktree_path))

package/runtime/python/okstra_ctl/worktree/linking.py

@@ -0,0 +1,249 @@
+"""메인 체크아웃의 공유 상태를 새 worktree 안에 재현한다.
+
+`sync_config` 가 고른 목록을 실제로 심링크(또는 스냅샷 복사)하는 층이다. 방식이
+세 가지이고 이유가 각각 다르다 — 디렉터리 통째 심링크는 새로 생기는 최상위
+항목이 메인으로 가게 하고, 자식별 심링크는 git 이 심링크된 디렉터리를 파일
+하나로 보는 탓에 `.claude` 가 `?? .claude` 로 뜨는 것을 막으며, 스냅샷 복사는
+쓰기 핸들을 공유하지 않으려는 픽스처용이다.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+from pathlib import Path
+
+from ..seeding import (
+    SettingsLinkError,
+    ensure_project_settings_symlink,
+)
+from .sync_config import (
+    CHILD_LINKED_SYNC_DIRS,
+    _resolve_snapshot_files,
+    _resolve_sync_dirs,
+    _resolve_sync_files,
+)
+
+
+def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
+    """Symlink each configured dir from `source_root` (the MAIN
+    worktree) into the new worktree.
+
+    Skip rules:
+      - Source missing in `source_root` → silently skipped.
+      - Target path already exists in worktree (e.g. tracked content
+        checked out by `git worktree add`) → skipped to avoid clobbering
+        version-controlled files.
+      - Parent directories are created as needed for nested entries.
+
+    Entries listed in `CHILD_LINKED_SYNC_DIRS` are materialised as a real
+    directory of per-child symlinks instead (see that constant).
+
+    Returns a list of human-readable notes (one per linked entry) so the
+    caller can include them in the provisioning note.
+    """
+    notes: list[str] = []
+    for rel in _resolve_sync_dirs(source_root):
+        src = (source_root / rel).resolve()
+        if not src.exists():
+            continue
+        dst = worktree_path / rel
+        if dst.exists() or dst.is_symlink():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if rel in CHILD_LINKED_SYNC_DIRS and src.is_dir():
+            _link_dir_children(src, dst)
+            notes.append(rel)
+            continue
+        try:
+            os.symlink(src, dst)
+        except FileExistsError:
+            continue
+        notes.append(rel)
+    return notes
+
+
+def _link_dir_children(src: Path, dst: Path) -> None:
+    """Create `dst` as a real directory whose entries symlink to `src`'s
+    children, so git sees the same directory shape it sees in the main
+    checkout (`CHILD_LINKED_SYNC_DIRS`).
+
+    Each link points at the MAIN checkout's child rather than its resolved
+    target, so a child that is itself a symlink (e.g. `.claude/settings.local.json`
+    → `~/.okstra/templates/settings.local.json`) keeps following whatever the
+    main checkout currently points at. An unreadable source or a child that
+    cannot be linked degrades to "that child is absent in this worktree" —
+    provisioning is not worth failing over host config.
+    """
+    dst.mkdir(parents=True, exist_ok=True)
+    try:
+        children = sorted(src.iterdir())
+    except OSError:
+        return
+    for child in children:
+        link = dst / child.name
+        if link.exists() or link.is_symlink():
+            continue
+        try:
+            os.symlink(child, link)
+        except OSError:
+            continue
+
+
+def _link_sync_files(source_root: Path, worktree_path: Path) -> list[str]:
+    """File-level counterpart to `_link_sync_dirs` (FU-V2).
+
+    Same skip rules: missing source → skipped silently; pre-existing dst
+    (tracked content checked out by `git worktree add`) → skipped to avoid
+    clobbering. Symlinks (not copies) keep secrets out of duplicate files —
+    the link points back to the MAIN worktree's `.env` so rotating the file
+    there is reflected in every active task without re-provisioning.
+    """
+    notes: list[str] = []
+    for rel in _resolve_sync_files(source_root):
+        src = (source_root / rel).resolve()
+        if not src.exists() or not src.is_file():
+            continue
+        dst = worktree_path / rel
+        if dst.exists() or dst.is_symlink():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            os.symlink(src, dst)
+        except FileExistsError:
+            continue
+        notes.append(rel)
+    return notes
+
+
+def sync_file_key_names(source_root: Path) -> dict[str, list[str]]:
+    """공유되는 sync 파일마다 그 안의 **키 이름**만 모은다 (값은 절대 읽지 않는다).
+
+    `.env` 는 gitignore 대상이라 브랜치에 속하지 않고, `_link_sync_files` 가 메인
+    체크아웃의 것을 각 worktree 에 심링크로 건다. 값 회전은 그 설계가 노린 것이지만
+    **키 이름 변경**은 아직 옛 이름을 읽는 모든 브랜치를 한꺼번에 깨뜨린다 — 코드는
+    브랜치별로 격리되지만 `.env` 는 격리되지 않기 때문이다. 그 사고를 알아보려면
+    프로비저닝 시점의 이름 집합을 남겨야 한다.
+
+    `KEY=` 꼴이 아닌 파일은 빈 목록이 되어 드리프트 판정에서 자연히 빠진다 —
+    sync 파일 목록은 프로젝트가 바꿀 수 있으므로 `.env` 형식을 전제하지 않는다.
+    """
+    keys: dict[str, list[str]] = {}
+    for rel in _resolve_sync_files(source_root):
+        src = (source_root / rel).resolve()
+        if not src.is_file():
+            continue
+        try:
+            text = src.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        found = []
+        for line in text.splitlines():
+            stripped = line.strip().removeprefix("export ").lstrip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            name, separator, _ = stripped.partition("=")
+            name = name.strip()
+            if separator and name and all(
+                ch.isalnum() or ch == "_" for ch in name
+            ):
+                found.append(name)
+        keys[rel] = sorted(set(found))
+    return keys
+
+
+def describe_sync_key_drift(
+    recorded: object, current: dict[str, list[str]]
+) -> str:
+    """프로비저닝 때 기록한 키 이름 집합과 지금을 대조해 한 줄로 알린다.
+
+    기록이 없으면(그 전에 만들어진 worktree) 빈 문자열 — 알 수 없는 것을 사고로
+    보고하지 않는다. 차단이 아니라 알림인 이유는 키 추가가 정상 작업이기 때문이다.
+    """
+    if not isinstance(recorded, dict):
+        return ""
+    parts: list[str] = []
+    for rel in sorted(set(recorded) | set(current)):
+        before = set(recorded.get(rel) or [])
+        after = set(current.get(rel) or [])
+        removed = sorted(before - after)
+        added = sorted(after - before)
+        if not removed and not added:
+            continue
+        detail = []
+        if removed:
+            detail.append(f"gone: {', '.join(removed)}")
+        if added:
+            detail.append(f"new: {', '.join(added)}")
+        parts.append(f"{rel} ({'; '.join(detail)})")
+    if not parts:
+        return ""
+    return (
+        "shared-env drift — " + "; ".join(parts) + ". This file is symlinked "
+        "from the main checkout into every task worktree, so a renamed key "
+        "breaks every branch still reading the old name at once, and it shows "
+        "up as verifier sessions failing to boot while the executor passes. "
+        "Key names only; values are never recorded."
+    )
+
+
+def _seed_worktree_settings_symlink(worktree_path: Path) -> None:
+    """Seed `.claude/settings.local.json` in the worker worktree so dispatched
+    Claude / codex / antigravity sessions inherit the okstra read-only / write
+    allowlist. Mirrors the main-project seeding done in `run.py` — needed
+    because `_link_sync_dirs` skips `.claude/` whenever `git worktree add`
+    already materialised the directory (e.g. tracked `.claude/handoff-*.md`).
+    Failures degrade to stderr warning so worktree provisioning still
+    succeeds.
+    """
+    try:
+        link = ensure_project_settings_symlink(project_root=worktree_path)
+    except SettingsLinkError as exc:
+        print(
+            f"okstra-settings: failed to seed worker worktree symlink at "
+            f"{worktree_path / '.claude/settings.local.json'} — worker dispatch "
+            f"may be blocked by Claude Code permissions. ({exc})",
+            file=__import__("sys").stderr,
+        )
+        return
+    if link is None:
+        print(
+            "okstra-settings: ~/.okstra/templates/settings.local.json missing — "
+            "re-run 'npx okstra@latest install' (0.14.0+) to provision the "
+            "symlink target.",
+            file=__import__("sys").stderr,
+        )
+
+
+def _copy_snapshot_files(source_root: Path, worktree_path: Path) -> list[str]:
+    """Copy fixture files from MAIN → task worktree as read-only snapshots
+    (FU-V3).
+
+    Unlike `_link_sync_files`, this materialises a fresh on-disk copy and
+    chmods it to `0o444` so the verifier can read the same rows the
+    executor saw without sharing a writable handle that would corrupt the
+    main worktree's copy. Skip rules mirror the symlink helpers (missing
+    source → skipped silently; pre-existing dst → skipped to avoid
+    clobbering tracked content).
+    """
+    notes: list[str] = []
+    for rel in _resolve_snapshot_files(source_root):
+        src = (source_root / rel).resolve()
+        if not src.exists() or not src.is_file():
+            continue
+        dst = worktree_path / rel
+        if dst.exists() or dst.is_symlink():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)
+        try:
+            os.chmod(dst, stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH)
+        except OSError:
+            # chmod failure (exotic filesystems, root-squashed mounts) does
+            # not invalidate the snapshot itself — it just means the read-
+            # only contract is best-effort. Surface in notes so the operator
+            # can audit if a verifier later mutates the file.
+            notes.append(f"{rel} (rw-fallback)")
+            continue
+        notes.append(rel)
+    return notes

package/runtime/python/okstra_ctl/worktree/naming.py

@@ -0,0 +1,91 @@
+"""task-key 를 worktree 경로와 브랜치 이름으로 옮긴다.
+
+경로도 브랜치도 파일 시스템과 git 참조 양쪽에서 안전한 문자만 남겨야 하고,
+브랜치는 work-category 별 namespace 아래로 들어간다. 순수 문자열 계산이라
+디스크도 git 도 보지 않는다 — 그래서 provision 전에 미리 보여 줄 수 있다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from okstra_project.dirs import okstra_home
+
+from ..ids import _safe_fs_segment
+
+
+# Work-category → branch namespace (slash-prefixed). Mirrors the values
+# accepted by `--work-category` (bugfix / feature / refactor / ops /
+# improvement); `feature` and `improvement` share the `feature/` namespace,
+# and any unset/unrecognised category falls back to `task/`.
+_WORK_CATEGORY_NAMESPACE = {
+    "feature": "feature",
+    "improvement": "feature",
+    "bugfix": "fix",
+    "refactor": "refactor",
+    "ops": "ops",
+}
+
+
+def _safe_segment(value: str) -> str:
+    """Sanitise a single path/branch segment.
+
+    Forbidden chars (`/`, `:`, spaces, anything outside `[a-z0-9-]`)
+    are collapsed to `-`. Empty result becomes `_` so we never create
+    an empty path component. Delegates to the canonical slugifier in
+    `ids.py` to stay in lock-step with run-id / manifest segmentation.
+    """
+    return _safe_fs_segment(value)
+
+
+def _work_category_namespace(work_category: str) -> str:
+    key = (work_category or "").strip().lower()
+    return _WORK_CATEGORY_NAMESPACE.get(key, "task")
+
+
+def compute_worktree_path(
+    *,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+) -> Path:
+    """Pure path computation. One worktree dir per task-key, or per
+    `<task-key>/stage-<N>` when stage_number is given (implementation
+    stage isolation). Uses `OKSTRA_HOME` when set (test hook), else
+    `~/.okstra`."""
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
+    base = okstra_home()
+    path = (
+        base / "worktrees"
+        / _safe_segment(project_id)
+        / _safe_segment(task_group_segment)
+        / _safe_segment(task_id_segment)
+    )
+    if stage_number is not None:
+        path = path / f"stage-{stage_number}"
+    if group_id is not None:
+        path = path / f"group-{group_id}"
+    return path
+
+
+def compute_branch_name(
+    *,
+    work_category: str,
+    task_id_segment: str,
+    stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+) -> str:
+    """One branch per task-key as `<namespace>/<task-id>`, or
+    `<namespace>/<task-id>-s<N>` for an implementation stage worktree. The
+    namespace is a controlled constant so its slash is preserved; only the
+    task-id segment is sanitised."""
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
+    name = f"{_work_category_namespace(work_category)}/{_safe_segment(task_id_segment)}"
+    if stage_number is not None:
+        name = f"{name}-s{stage_number}"
+    if group_id is not None:
+        name = f"{name}-{group_id}"
+    return name