okstra 0.34.1 → 0.36.0

package/runtime/python/okstra_ctl/run_context.py

@@ -50,6 +50,15 @@ def _task_lock_path(task_key: str) -> Path:
     return locks / f"{safe}.lock"
 
 
+def _consumers_lock_path(plan_task_key: str) -> Path:
+    """plan-task-key 별 consumers.jsonl append mutex."""
+    home = _okstra_home()
+    locks = home / ".locks"
+    locks.mkdir(parents=True, exist_ok=True)
+    safe = plan_task_key.replace("/", "_").replace(":", "_")
+    return locks / f"{safe}.consumers.lock"
+
+
 @contextmanager
 def task_mutex(task_key: str) -> Iterator[None]:
     """task-key per-process mutex. 동시 호출은 락 안에서 직렬화된다."""
@@ -63,6 +72,19 @@ def task_mutex(task_key: str) -> Iterator[None]:
             fcntl.flock(f.fileno(), fcntl.LOCK_UN)
 
 
+@contextmanager
+def consumers_mutex(plan_task_key: str) -> Iterator[None]:
+    """plan-task-key 별 consumers.jsonl append mutex."""
+    path = _consumers_lock_path(plan_task_key)
+    path.touch(exist_ok=True)
+    with path.open("r+") as f:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
 def _atomic_write_json(path: Path, payload: dict) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_suffix(path.suffix + ".tmp")

package/runtime/python/okstra_ctl/seeding.py

@@ -23,6 +23,14 @@ class SettingsLinkError(Exception):
     """`<project>/.claude/settings.local.json` symlink provisioning 실패."""
 
 
+class ClaudeMdLinkError(Exception):
+    """`<project>/.project-docs/okstra/CLAUDE.md` symlink or import-block provisioning 실패."""
+
+
+class AgentsMdLinkError(Exception):
+    """`<project>/AGENTS.md` symlink provisioning 실패."""
+
+
 def installed_version() -> str:
     """Read the version stamp written by `okstra install` to `~/.okstra/version`.
 
@@ -195,3 +203,181 @@ def _backup_and_replace(target: Path, template: Path) -> None:
         raise SettingsLinkError(
             f"failed to create symlink {target} -> {template} after backup: {exc}"
         ) from exc
+
+
+def installed_claude_md_template_path() -> Path:
+    """okstra install 이 만들어 둔 okstra.CLAUDE.md template 의 절대경로."""
+    return _okstra_home() / "templates" / "okstra.CLAUDE.md"
+
+
+_CLAUDE_MD_SYMLINK_REL = Path(".project-docs") / "okstra" / "CLAUDE.md"
+_CLAUDE_MD_IMPORT_LINE = "@.project-docs/okstra/CLAUDE.md"
+_CLAUDE_MD_MARKER_BEGIN = (
+    "<!-- okstra:claude-md:begin (managed by okstra setup — do not edit) -->"
+)
+_CLAUDE_MD_MARKER_END = "<!-- okstra:claude-md:end -->"
+
+
+def ensure_project_claude_md(*, project_root: Path) -> Optional[Path]:
+    """`<project_root>/.project-docs/okstra/CLAUDE.md` 를 `~/.okstra/templates/okstra.CLAUDE.md`
+    로 가리키는 symlink 로 provisioning 하고, `<project_root>/CLAUDE.md` 에
+    `@.project-docs/okstra/CLAUDE.md` import block 을 멱등하게 주입한다.
+
+    Claude Code 가 해당 프로젝트에서 host 세션으로 실행될 때
+    `<project_root>/CLAUDE.md` 가 자동 로드되므로, okstra 가 관리하는 본문
+    (slash command catalog, workflow guidance, ...) 도 같이 surface 된다.
+
+    반환값:
+      - symlink Path: 신규 생성됐거나 이미 올바른 target 을 가리키고 있을 때.
+      - None: install 이 아직 CLAUDE.md template 을 깔지 않았을 때 (구버전
+        okstra install). 상위에서 경고로 흘려보낸다.
+
+    상위 호출자는 `ClaudeMdLinkError` 만 처리하면 된다.
+    """
+    project_root = Path(project_root)
+    template = installed_claude_md_template_path()
+    if not template.exists():
+        return None
+
+    target = project_root / _CLAUDE_MD_SYMLINK_REL
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    if target.is_symlink():
+        try:
+            current = os.readlink(target)
+        except OSError as exc:
+            raise ClaudeMdLinkError(
+                f"failed to read existing symlink {target}: {exc}"
+            ) from exc
+        current_path = Path(current)
+        if current_path == template or (target.parent / current_path).resolve() == template.resolve():
+            _ensure_claude_md_import(project_root)
+            return target
+        _backup_and_replace_claude_md(target, template)
+        _ensure_claude_md_import(project_root)
+        return target
+
+    if target.exists():
+        _backup_and_replace_claude_md(target, template)
+        _ensure_claude_md_import(project_root)
+        return target
+
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise ClaudeMdLinkError(
+            f"failed to create symlink {target} -> {template}: {exc}"
+        ) from exc
+    _ensure_claude_md_import(project_root)
+    return target
+
+
+def _ensure_claude_md_import(project_root: Path) -> bool:
+    """`<project_root>/CLAUDE.md` 에 import block 이 없으면 append, 있으면 no-op.
+
+    반환: 새로 주입했을 때 True, 이미 있었을 때 False.
+    """
+    claude_md = project_root / "CLAUDE.md"
+    block = f"{_CLAUDE_MD_MARKER_BEGIN}\n{_CLAUDE_MD_IMPORT_LINE}\n{_CLAUDE_MD_MARKER_END}\n"
+
+    try:
+        existing = claude_md.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        try:
+            claude_md.write_text(block, encoding="utf-8")
+        except OSError as exc:
+            raise ClaudeMdLinkError(
+                f"failed to create {claude_md}: {exc}"
+            ) from exc
+        return True
+    except OSError as exc:
+        raise ClaudeMdLinkError(f"failed to read {claude_md}: {exc}") from exc
+
+    if _CLAUDE_MD_MARKER_BEGIN in existing and _CLAUDE_MD_MARKER_END in existing:
+        return False
+
+    separator = _block_separator_for(existing)
+    try:
+        claude_md.write_text(existing + separator + block, encoding="utf-8")
+    except OSError as exc:
+        raise ClaudeMdLinkError(f"failed to update {claude_md}: {exc}") from exc
+    return True
+
+
+def _block_separator_for(existing: str) -> str:
+    """기존 파일 끝과 import block 사이의 공백 결정 — 가독성 보장 목적."""
+    if not existing:
+        return ""
+    if existing.endswith("\n\n"):
+        return ""
+    if existing.endswith("\n"):
+        return "\n"
+    return "\n\n"
+
+
+def _backup_and_replace_claude_md(target: Path, template: Path) -> None:
+    """기존 파일/심볼릭링크를 timestamped backup 으로 옮기고 새 symlink 생성."""
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    backup = target.with_name(f"{target.name}.bak.{stamp}")
+    try:
+        target.rename(backup)
+    except OSError as exc:
+        raise ClaudeMdLinkError(
+            f"failed to back up existing {target} to {backup}: {exc}"
+        ) from exc
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise ClaudeMdLinkError(
+            f"failed to create symlink {target} -> {template} after backup: {exc}"
+        ) from exc
+
+
+def ensure_project_agents_md(*, project_root: Path) -> Optional[Path]:
+    """`<project_root>/AGENTS.md` 가 없을 때만 `~/.okstra/templates/okstra.CLAUDE.md`
+    로의 심링크로 생성한다.
+
+    AGENTS.md 는 codex / aider / 기타 agent 가 읽는 파일이고 @import 같은
+    부분 포함 메커니즘이 없어, 파일 전체 내용이 곧 agent 가 보는 콘텐츠가
+    된다. 그래서 CLAUDE.md (`@.project-docs/okstra/CLAUDE.md` 마커 블록
+    주입) 와 달리 "AGENTS.md 가 비어 있을 때만 만들고, 존재하면 절대
+    건드리지 않는" 정책을 사용한다 — 사용자가 직접 작성한 AGENTS.md 를
+    덮어쓰지 않는다.
+
+    반환값:
+      - target Path: 신규 심링크 생성, 또는 이미 우리 템플릿을 가리키고
+        있던 심링크가 idempotent 하게 확인된 경우.
+      - None: install 이 아직 CLAUDE.md template 을 깔지 않았거나,
+        AGENTS.md 가 이미 사용자 콘텐츠 (regular file) 거나 우리가
+        만들지 않은 다른 심링크로 존재하는 경우. 후자 두 케이스는
+        사용자의 의도로 간주하고 건드리지 않는다.
+
+    상위 호출자는 `AgentsMdLinkError` 만 처리하면 된다.
+    """
+    project_root = Path(project_root)
+    template = installed_claude_md_template_path()
+    if not template.exists():
+        return None
+
+    target = project_root / "AGENTS.md"
+
+    if target.is_symlink():
+        try:
+            current = os.readlink(target)
+        except OSError:
+            return None
+        current_path = Path(current)
+        if current_path == template or (target.parent / current_path).resolve() == template.resolve():
+            return target
+        return None  # foreign symlink — respect user
+
+    if target.exists():
+        return None  # regular file — respect user content
+
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise AgentsMdLinkError(
+            f"failed to create symlink {target} -> {template}: {exc}"
+        ) from exc
+    return target