codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/agent/custom_skills.py

@@ -0,0 +1,335 @@
+"""커스텀 스킬 — codex 와 같은 규칙으로 찾아 두 엔진에 싣는다 (이슈 #134).
+
+스킬 한 개는 `<이름>/SKILL.md` 파일 하나이고, 머리의 YAML frontmatter 에 `name` 과
+`description` 이 있다. codex 의 스킬 규격과 같다
+(https://developers.openai.com/codex/skills).
+
+**codex 네이티브 탐색은 쓸 수 없다.** codex 는 pod 가 아니라 centri 에서 돌아서
+`skills/list` 가 centri 의 파일시스템을 훑는다. 그래서 pod 가 codex 0.154.0 과 같은
+경로·scope 로 탐색하고, 목록은 프롬프트에 싣고 본문은 도구(`load_skill`)로 되불러
+준다 — codex 가 원래 하는 progressive disclosure 를 pod 가 대신 한다.
+
+탐색 순서가 곧 우선순위다. 같은 이름이 둘이면 앞의 것이 이긴다. centri 포털 스킬이
+로컬보다 앞이다(이슈 #182) — 포털이 정한 스킬을 사람이 같은 이름으로 덮지 못한다.
+
+| 위치 | scope |
+|---|---|
+| 동기화 디렉터리 `<codebuff 홈>/skills/<scope>/` — `user` `project` `team` `global` 순 | 그 scope |
+| 워크스페이스부터 git 루트까지 `.agents/skills` · `.codex/skills` | `repo` |
+| `~/.agents/skills` · `$CODEX_HOME/skills` (없으면 `~/.codex/skills`) | `user` |
+
+동기화 디렉터리는 `CODEBUFF_SKILLS_URL` 이 있을 때만 본다. 공유 키가 있는 pod 는 시크릿
+부트스트랩이 이 URL 을 채우고, `codebuff_core.managers.remote_skills` 가 centri 에서 받아
+그 디렉터리에 쓴다. URL 이 없는 로컬 개발에서는 예전처럼 사람이 만든 스킬만 본다.
+로컬 스킬 목록은 같은 클라이언트가 centri 에 보고한다(`local_report`).
+
+내장 스킬(패키지 옆 `skills/*.md`, scope `builtin`)은 위 탐색에 들지 않는다. codex 두 모드는
+`with_builtin` 으로 그 뒤에 붙여 쓴다 — 이름이 `_`/`-`·대소문자만 다르면 같은 스킬이고, 앞의
+커스텀(포털) 스킬이 이긴다 (이슈 #202, #219).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple
+
+import yaml
+
+from codebuff_core.legacy_paths import resolve_home
+
+from .._version import __version__
+
+# 이름 규칙·본문 상한·scope 는 동기화 클라이언트가 정본이다 — 받는 쪽과 읽는 쪽이 갈라지면
+# centri 에서 받은 스킬이 조용히 빠진다
+from codebuff_core.managers.remote_skills import (  # noqa: F401 — 여기서 다시 내보낸다
+    BODY_MAX_CHARS,
+    NAME_RE,
+    SKILL_FILE,
+    SYNC_SCOPES,
+)
+from codebuff_core.managers.remote_skills import (
+    DESCRIPTION_MAX_CHARS as _DESCRIPTION_MAX_CHARS,
+)
+from codebuff_core.managers.remote_skills import URL_ENV as SKILLS_URL_ENV
+
+logger = logging.getLogger(__name__)
+
+#: codex 의 스킬 목록 예산과 같다
+LIST_BUDGET_CHARS = 8_000
+#: 예산을 넘을 때 설명을 이 길이로 줄인다
+_SHORT_DESCRIPTION = 120
+_FRONTMATTER = re.compile(r"---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|$)(.*)", re.S)
+#: 패키지 옆 내장 스킬. 파일 이름이 `<stem>.md` 라 codex 규격(`<이름>/SKILL.md`)과 다르다
+BUILTIN_DIR = Path(__file__).parent / "skills"
+BUILTIN_SCOPE = "builtin"
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    scope: str
+    path: Path
+
+
+def sync_root() -> Path:
+    """centri 에서 받은 스킬을 두는 곳. 사람이 만든 스킬 디렉터리와 섞지 않는다."""
+    return resolve_home("skills")
+
+
+def _repo_dirs(workspace_root: str) -> List[Path]:
+    """워크스페이스부터 git 루트까지. git 저장소가 아니면 워크스페이스 하나다."""
+    start = Path(workspace_root).resolve()
+    chain = [start, *start.parents]
+    for i, d in enumerate(chain):
+        if (d / ".git").exists():
+            return chain[: i + 1]
+    return [start]
+
+
+def _sync_roots() -> List[Tuple[Path, str]]:
+    if not os.environ.get(SKILLS_URL_ENV):
+        return []
+    return [(sync_root() / scope, scope) for scope in SYNC_SCOPES]
+
+
+def _local_roots(workspace_root: str) -> List[Tuple[Path, str]]:
+    roots: List[Tuple[Path, str]] = []
+    for d in _repo_dirs(workspace_root):
+        roots.append((d / ".agents" / "skills", "repo"))
+        roots.append((d / ".codex" / "skills", "repo"))
+    home = Path(os.path.expanduser("~"))
+    codex_home = Path(os.environ.get("CODEX_HOME") or home / ".codex")
+    roots.append((home / ".agents" / "skills", "user"))
+    roots.append((codex_home / "skills", "user"))
+    return roots
+
+
+def _split(text: str) -> Tuple[Optional[dict], str]:
+    """frontmatter 와 본문을 가른다. frontmatter 가 없거나 깨졌으면 `(None, text)`.
+
+    경계는 `---` 만 있는 줄이다. 줄 안의 `---`(이름 `a---b`, 설명 속 구분선)는 경계가 아니다.
+    """
+    m = _FRONTMATTER.match(text)
+    if not m:
+        return None, text
+    try:
+        meta = yaml.safe_load(m.group(1))
+    except yaml.YAMLError:
+        return None, text
+    return (meta if isinstance(meta, dict) else None), m.group(2).strip()
+
+
+def _parse(path: Path, scope: str) -> Optional[Skill]:
+    try:
+        meta, _ = _split(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError) as e:
+        logger.warning("스킬을 읽지 못함 %s: %s", path, e)
+        return None
+    if not meta:
+        logger.warning("스킬 frontmatter 가 없거나 읽을 수 없어 뺌: %s", path)
+        return None
+    name = str(meta.get("name") or "").strip()
+    description = " ".join(str(meta.get("description") or "").split())
+    if not NAME_RE.match(name) or not description:
+        logger.warning("스킬 frontmatter 가 규격 밖이라 뺌: %s", path)
+        return None
+    return Skill(name, description[:_DESCRIPTION_MAX_CHARS], scope, path)
+
+
+def discover(workspace_root: str) -> List[Skill]:
+    """우선순위 순서의 스킬 목록. 같은 이름은 먼저 찾은 하나만 남긴다."""
+    return _scan(_sync_roots() + _local_roots(workspace_root))
+
+
+def skill_key(name: str) -> str:
+    """파일 stem(`data_loading`)과 frontmatter name(`data-loading`)을 같은 스킬로 본다."""
+    return name.strip().lower().replace("-", "").replace("_", "")
+
+
+def builtin() -> List[Skill]:
+    """내장 스킬 — frontmatter 규격(이름·설명)을 지킨 것만, 파일 이름 순서다."""
+    found = (_parse(p, BUILTIN_SCOPE) for p in sorted(BUILTIN_DIR.glob("*.md")))
+    return [s for s in found if s]
+
+
+def with_builtin(skills: List[Skill]) -> List[Skill]:
+    """커스텀 스킬 뒤에 그것에 재정의되지 않은 내장 스킬을 붙인다."""
+    keys = {skill_key(s.name) for s in skills}
+    return [*skills, *(b for b in builtin() if skill_key(b.name) not in keys)]
+
+
+def local_report(workspace_root: str) -> List[dict]:
+    """centri 에 보고하는 로컬 스킬 (이슈 #182). 본문은 싣지 않는다.
+
+    `shadowed` 는 같은 이름의 포털 스킬에 덮여 에이전트에 안 보인다는 뜻이다.
+    """
+    discovered = discover(workspace_root)
+    winners = {s.name: s.path for s in discovered}
+    local = [
+        {
+            "name": s.name,
+            "scope": s.scope,
+            "dir": str(s.path.parent.parent),
+            "description": s.description,
+            "sha256": hashlib.sha256(s.path.read_bytes()).hexdigest(),
+            "shadowed": winners.get(s.name) != s.path,
+        }
+        for s in _scan(_local_roots(workspace_root))
+    ]
+    return local + _builtin_report({skill_key(s.name) for s in discovered})
+
+
+def _builtin_report(custom_keys: set) -> List[dict]:
+    """내장 스킬은 본문(동적 치환 전 원문)과 codebuff 버전까지 싣는다 (이슈 #219).
+
+    centri 가 "같은 이름으로 재정의" 를 내장 본문으로 채워 시작하고, 버전이 섞인 pod 중
+    최신 버전 본문을 고르는 데 쓴다. `shadowed` 는 같은 이름의 커스텀 스킬이 이긴다는 뜻이다.
+    """
+    out = []
+    for s in builtin():
+        raw = s.path.read_bytes()
+        out.append(
+            {
+                "name": s.name,
+                "scope": BUILTIN_SCOPE,
+                "description": s.description,
+                "body": _split(raw.decode("utf-8"))[1],
+                "sha256": hashlib.sha256(raw).hexdigest(),
+                "shadowed": skill_key(s.name) in custom_keys,
+                "codebuff_version": __version__,
+            }
+        )
+    return out
+
+
+def _scan(roots: List[Tuple[Path, str]]) -> List[Skill]:
+    found: Dict[str, Skill] = {}
+    seen_dirs = set()
+    for root, scope in roots:
+        # 권한 없는 상위 디렉터리는 `is_dir()` 도 예외를 던진다. 스킬 하나가 안 보이는
+        # 것으로 끝나야지 에이전트 생성 전체가 죽으면 안 된다
+        try:
+            key = root.resolve()
+            if key in seen_dirs or not root.is_dir():
+                continue
+            seen_dirs.add(key)
+            paths = sorted(root.glob(f"*/{SKILL_FILE}"))
+        except OSError as e:
+            logger.warning("스킬 디렉터리를 읽지 못함 %s: %s", root, e)
+            continue
+        for path in paths:
+            skill = _parse(path, scope)
+            if skill and skill.name not in found:
+                found[skill.name] = skill
+    return list(found.values())
+
+
+def fingerprint(skills: List[Skill]) -> str:
+    """프롬프트에 굳는 목록이 바뀌었는지 가리는 값. 에이전트 그래프 캐시 키에 쓴다."""
+    return "\n".join(f"{s.scope}|{s.name}|{s.path}|{s.description}" for s in skills)
+
+
+def prompt_section(skills: List[Skill], tool_name: str) -> str:
+    """프롬프트에 싣는 목록. 스킬이 없으면 빈 문자열이다.
+
+    본문은 싣지 않는다. 목록이 `LIST_BUDGET_CHARS` 를 넘으면 설명을 줄이고, 그래도
+    넘치면 뒤쪽(우선순위가 낮은 것)을 뺀다.
+    """
+    return _section(skills, tool_name)[0]
+
+
+def omitted_count(skills: List[Skill]) -> int:
+    """목록 예산에 밀려 프롬프트에서 빠지는 스킬 수 — 설정 화면이 보여 준다."""
+    return _section(skills, "load_skill_tool")[1]
+
+
+def builtin_section(custom: List[Skill], tool_name: str) -> str:
+    """codex agent 모드 지시문의 내장 스킬 목록. `custom` 에 재정의된 것은 뺀다 (이슈 #219)."""
+    shown = with_builtin(custom)[len(custom) :]
+    if not shown:
+        return ""
+    header = (
+        "# Built-in Skills\n\n"
+        "codebuff 에 내장된 스킬이다. 작업이 아래 설명과 맞으면 "
+        f"`{tool_name}` 로 그 스킬 본문을 먼저 읽고 따른다.\n\n"
+    )
+    return _budgeted(header, shown, lambda s, d: f"- **{s.name}**: {d}")[0]
+
+
+def catalog(skills: List[Skill]) -> str:
+    """도구 설명에 싣는 `- 이름: 설명` 목록 — codex qa 모드 `load_skills` (이슈 #219)."""
+    return _budgeted("", skills, lambda s, d: f"- {s.name}: {d}")[0]
+
+
+def _section(skills: List[Skill], tool_name: str) -> Tuple[str, int]:
+    if not skills:
+        return "", 0
+    header = (
+        "# Custom Skills\n\n"
+        "사용자·팀이 추가한 스킬이다. 작업이 아래 설명과 맞으면 "
+        f"`{tool_name}` 로 그 스킬 본문을 먼저 읽고 따른다.\n\n"
+    )
+    return _budgeted(header, skills, lambda s, d: f"- **{s.name}** ({s.scope}): {d}")
+
+
+def _budgeted(
+    header: str, skills: List[Skill], fmt: Callable[[Skill, str], str]
+) -> Tuple[str, int]:
+    def line(s: Skill, limit: int) -> str:
+        desc = s.description
+        if len(desc) > limit:
+            desc = desc[: limit - 1] + "…"
+        return fmt(s, desc)
+
+    for limit in (_DESCRIPTION_MAX_CHARS, _SHORT_DESCRIPTION):
+        lines = [line(s, limit) for s in skills]
+        full = header + "\n".join(lines)
+        if len(full) <= LIST_BUDGET_CHARS:
+            return full, 0
+    reserve = len(_omitted_line(len(lines)))
+    kept: List[str] = []
+    for text in lines:
+        if len(header) + len("\n".join([*kept, text])) + reserve > LIST_BUDGET_CHARS:
+            break
+        kept.append(text)
+    omitted = len(lines) - len(kept)
+    return header + "\n".join(kept) + _omitted_line(omitted), omitted
+
+
+def _omitted_line(count: int) -> str:
+    return f"\n- … 목록 예산을 넘어 {count}개를 뺐다"
+
+
+def read_body(path: Path) -> str:
+    """frontmatter 를 뺀 본문. 상한을 넘으면 싣지 않고 오류 문장을 돌려준다."""
+    try:
+        _, body = _split(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError) as e:
+        return f"Error: 스킬 파일을 읽지 못했다 ({e})"
+    if len(body) > BODY_MAX_CHARS:
+        return (
+            f"Error: 스킬 본문이 {len(body)}자라 상한 {BODY_MAX_CHARS}자를 넘어 "
+            "싣지 않았다"
+        )
+    return body
+
+
+def load_body(name: str, skills: List[Skill]) -> str:
+    """이름으로 본문을 찾는다. 모르는 이름이면 가능한 이름을 알려 준다.
+
+    `_`/`-` 는 가리지 않는다 — 내장 스킬은 파일 stem 과 frontmatter name 이 다르다.
+    """
+    name = (name or "").strip()
+    if not NAME_RE.match(name):
+        return f"Error: 스킬 이름이 규격 밖이다: {name!r}"
+    for s in skills:
+        if skill_key(s.name) == skill_key(name):
+            return read_body(s.path)
+    available = ", ".join(s.name for s in skills) or "없음"
+    return f"Error: Unknown skill '{name}'. Available skills: {available}"

jupyter_ext/agent/file_diffs.py

@@ -0,0 +1,99 @@
+"""승인 없이 실행된 내장 파일 쓰기의 diff (이슈 #147).
+
+deepagents 의 `write_file`·`edit_file` 은 HITL 없이 디스크에 쓴다. 도구 시작 때 파일을
+읽어 두고 끝날 때 다시 읽어, 바뀐 것을 unified diff 로 돌려준다. 스트림 루프 두 곳
+(`AgentRunner.run` 과 resume 핸들러)이 같은 추적기를 쓴다.
+
+한계: 같은 파일을 병렬로 편집하면 먼저 끝난 쪽의 after 에 나중 것이 섞일 수 있다.
+"""
+
+from __future__ import annotations
+
+import difflib
+import os
+from typing import Any, Dict, Optional
+
+# 승인 카드(file_write)는 자기 diff 를 보이므로 여기서 다루지 않는다
+TRACKED_TOOLS = frozenset({"write_file", "edit_file"})
+MAX_BYTES = 1_000_000
+MAX_LINES = 400
+
+
+class FileDiffTracker:
+    def __init__(self, workspace_root: str):
+        self._root = os.path.realpath(workspace_root) if workspace_root else ""
+        self._pending: Dict[str, tuple] = {}
+
+    def _resolve(self, raw: Any) -> Optional[tuple]:
+        if not self._root or not isinstance(raw, str) or not raw:
+            return None
+        # virtual_mode: 앞의 "/" 는 작업공간 루트다
+        full = os.path.realpath(os.path.join(self._root, raw.lstrip("/")))
+        if full != self._root and not full.startswith(self._root + os.sep):
+            return None
+        return full, os.path.relpath(full, self._root)
+
+    @staticmethod
+    def _read(full: str) -> Optional[str]:
+        """없으면 "", 너무 크거나 바이너리거나 못 읽으면 None.
+
+        예외를 올리면 스트림 루프가 턴을 끊는다 — 디렉터리·권한 없는 파일은 도구가 오류를
+        돌려주고 모델이 이어 가야 할 상황이다.
+        """
+        if not os.path.lexists(full):
+            return ""
+        try:
+            if os.path.getsize(full) > MAX_BYTES:
+                return None
+            with open(full, encoding="utf-8", errors="replace") as f:
+                text = f.read()
+        except OSError:
+            return None
+        return None if "\x00" in text else text
+
+    def start(self, run_id: str, name: str, tool_input: Any) -> None:
+        if name not in TRACKED_TOOLS or not isinstance(tool_input, dict):
+            return
+        target = self._resolve(tool_input.get("file_path"))
+        # 디렉터리 등 일반 파일이 아니면 도구가 오류를 돌려준다 — 보일 diff 가 없다
+        if target is None or (
+            os.path.lexists(target[0]) and not os.path.isfile(target[0])
+        ):
+            return
+        self._pending[run_id] = (target[0], target[1], self._read(target[0]))
+
+    def end(self, run_id: str) -> Optional[Dict[str, Any]]:
+        entry = self._pending.pop(run_id, None)
+        if entry is None:
+            return None
+        full, rel, before = entry
+        after = self._read(full)
+        if before is None or after is None:
+            return {"path": rel, "skipped": True}
+        if before == after:
+            return None
+        lines = list(
+            difflib.unified_diff(
+                before.splitlines(), after.splitlines(), n=3, lineterm=""
+            )
+        )[2:]  # ---/+++ 헤더는 path 가 대신한다
+        if not lines:
+            # 끝 개행·줄끝(CRLF)만 바뀌면 줄 단위 diff 가 비는데, 빈 diff 는 "크거나
+            # 바이너리" 로 읽힌다
+            return None
+        added = sum(1 for ln in lines if ln.startswith("+"))
+        removed = sum(1 for ln in lines if ln.startswith("-"))
+        if len(lines) > MAX_LINES:
+            lines = lines[:MAX_LINES] + [f"… ({len(lines) - MAX_LINES}줄 더)"]
+        return {
+            "path": rel,
+            "diff": "\n".join(lines),
+            "added": added,
+            "removed": removed,
+        }
+
+    def discard(self, run_id: str) -> None:
+        self._pending.pop(run_id, None)
+
+    def clear(self) -> None:
+        self._pending.clear()

jupyter_ext/agent/git_history.py

@@ -0,0 +1,188 @@
+"""파일 하나의 git 이력과 두 시점 사이 diff (이슈 #153).
+
+파일 브라우저에서 우클릭한 파일의 커밋 목록을 주고, 커밋 두 개(`from`/`to`) 또는
+날짜 범위(`since`/`until`)로 고른 두 시점을 비교한다. git 호출은 `/diff`(이슈 #147) 와
+같은 `codex_slash._git` 이다 — argv 실행이라 셸을 거치지 않고, ref 는 `_commit_of` 가
+`--end-of-options` 로 받아 `--output=…` 같은 옵션 주입이 커밋 이름으로만 읽힌다.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import codex_slash
+from .codex_slash import _commit_of, _cut, _git, _GitError
+
+#: git 기본 `core.quotePath=true` 면 한글 경로가 "\355\225\234" 8진수로 나온다
+_QUOTE = ("-c", "core.quotePath=false")
+
+#: 커밋 목록 상한 — 오래된 파일이 탭을 멈추지 않게 한다
+LOG_LIMIT = 200
+
+#: 빈 트리 — `from` 이 없을 때(파일이 생긴 커밋) 전체를 추가 줄로 보인다
+_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+
+#: 브라우저가 시간대 오프셋을 붙여 보낸다. 오프셋이 없으면 서버 시간대로 해석돼 경계일이 흔들린다
+_ISO_WITH_OFFSET = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$"
+)
+
+#: 날짜는 committer 날짜(`%cI`) — 기간 비교의 `--before` 가 committer 기준이라 목록도 맞춘다
+_FORMAT = "%H%x00%cI%x00%an%x00%s"
+
+
+async def repo_of(abs_path: str) -> Tuple[str, str]:
+    """파일이 든 저장소의 최상위와, 그 기준 상대 경로(`/` 구분)."""
+    try:
+        top = (
+            await _git(os.path.dirname(abs_path), "rev-parse", "--show-toplevel")
+        ).strip()
+    except _GitError as e:
+        raise _GitError(f"git 저장소가 아닙니다. ({e})")
+    rel = os.path.relpath(os.path.realpath(abs_path), os.path.realpath(top))
+    return top, rel.replace(os.sep, "/")
+
+
+def _commit_row(line: str) -> Dict[str, str]:
+    sha, date, author, subject = (line.split("\0") + ["", "", ""])[:4]
+    return {"sha": sha, "date": date, "author": author, "subject": subject}
+
+
+async def _commit_info(top: str, sha: str) -> Dict[str, str]:
+    out = await _git(top, "log", "-1", f"--format={_FORMAT}", sha)
+    return _commit_row(out.rstrip("\n"))
+
+
+async def file_log(abs_path: str) -> Dict[str, Any]:
+    """파일을 바꾼 커밋, 최신 먼저. 추적하지 않는 파일이면 빈 목록이다."""
+    top, rel = await repo_of(abs_path)
+    out = await _git(
+        top, *_QUOTE, "log", f"-n{LOG_LIMIT}", f"--format={_FORMAT}", "--", rel
+    )
+    # splitlines 는 제목 안의 U+2028 같은 문자에서도 쪼갠다 — 레코드 구분은 \n 뿐이다
+    commits = [_commit_row(x) for x in out.split("\n") if x]
+    return {"path": rel, "commits": commits}
+
+
+def _project_notebook(text: str) -> Optional[str]:
+    """노트북을 셀 소스만 남긴 텍스트로. outputs·실행 카운트·metadata 는 뺀다.
+
+    빈 문자열(그 커밋에 파일이 없다)은 셀 0개다. 노트북 꼴이 아니면 None — 부르는 쪽이
+    원문으로 비교한다.
+    """
+    if not text:
+        return ""
+    parts: List[str] = []
+    try:
+        for cell in json.loads(text)["cells"]:
+            source = cell.get("source", "")
+            if isinstance(source, list):
+                source = "".join(source)
+            parts.append(f"# %% [{cell.get('cell_type', 'code')}]\n")
+            parts.append(
+                source if source.endswith("\n") or not source else source + "\n"
+            )
+    except (ValueError, KeyError, TypeError, AttributeError):
+        return None
+    return "".join(parts)
+
+
+async def _blob(top: str, sha: Optional[str], rel: str) -> str:
+    if not sha:
+        return ""
+    try:
+        return await _git(top, "show", f"{sha}:{rel}")
+    except _GitError as e:
+        # 그 커밋에 파일이 없을 때만 빈 파일이다. 타임아웃·손상은 그대로 올린다 —
+        # 삼키면 "전부 삭제됨" 가짜 diff 가 된다
+        if "does not exist in" in str(e) or "exists on disk, but not in" in str(e):
+            return ""
+        raise
+
+
+async def _notebook_diff(top: str, rel: str, old: Optional[str], new: str) -> str:
+    before, after = await _blob(top, old, rel), await _blob(top, new, rel)
+    pb, pa = _project_notebook(before), _project_notebook(after)
+    if pb is not None and pa is not None:
+        before, after = pb, pa
+    lines = difflib.unified_diff(
+        before.splitlines(keepends=True),
+        after.splitlines(keepends=True),
+        fromfile=f"a/{rel}" if old else "/dev/null",
+        tofile=f"b/{rel}",
+        n=3,
+    )
+    return "".join(x if x.endswith("\n") else x + "\n" for x in lines)
+
+
+async def file_diff(
+    abs_path: str, from_ref: Optional[str], to_ref: str
+) -> Dict[str, Any]:
+    """두 커밋 사이 파일 diff. `from_ref` 가 없으면 빈 파일과 비교한다."""
+    top, rel = await repo_of(abs_path)
+    new = await _commit_of(top, to_ref)
+    old = await _commit_of(top, from_ref) if from_ref else None
+    if rel.endswith(".ipynb"):
+        body = await _notebook_diff(top, rel, old, new)
+    else:
+        body = await _git(
+            top,
+            *_QUOTE,
+            "diff",
+            "--no-color",
+            "--no-ext-diff",
+            old or _EMPTY_TREE,
+            new,
+            "--",
+            rel,
+        )
+    body, cut = _cut(body.rstrip("\n"), codex_slash._DIFF_MAX_CHARS)
+    message = ""
+    if body and "\n@@ " not in body and "Binary files" in body:
+        body, message = "", "바이너리 파일이라 내용을 비교하지 않습니다."
+    elif not body:
+        message = "두 시점의 내용이 같습니다."
+    return {
+        "path": rel,
+        "diff": body,
+        "cut": cut,
+        "message": message,
+        "from": await _commit_info(top, old) if old else None,
+        "to": await _commit_info(top, new),
+    }
+
+
+async def _last_commit_before(top: str, rel: str, when: str) -> Optional[str]:
+    out = await _git(top, "log", "-1", "--format=%H", f"--before={when}", "--", rel)
+    return out.strip() or None
+
+
+async def file_diff_between_dates(
+    abs_path: str, since: str, until: str
+) -> Dict[str, Any]:
+    """`since` 직전 마지막 커밋과 `until` 까지 마지막 커밋을 비교한다 (committer 날짜)."""
+    for value in (since, until):
+        if not _ISO_WITH_OFFSET.match(value or ""):
+            raise _GitError(
+                f"날짜 형식이 아닙니다: {value} (YYYY-MM-DDTHH:MM:SS+09:00 꼴)"
+            )
+    top, rel = await repo_of(abs_path)
+    new = await _last_commit_before(top, rel, until)
+    if not new:
+        raise _GitError("종료일까지 이 파일의 커밋이 없습니다.")
+    old = await _last_commit_before(top, rel, since)
+    if old == new:
+        info = await _commit_info(top, new)
+        return {
+            "path": rel,
+            "diff": "",
+            "cut": False,
+            "message": "기간 안에 변경이 없습니다.",
+            "from": info,
+            "to": info,
+        }
+    return await file_diff(abs_path, old, new)