researchtree 1.0.0__py3-none-any.whl

researchtree/__init__.py

@@ -0,0 +1,13 @@
+"""ResearchTree: record experiments as a tree of Git branches and pull requests, and read it back as code."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("researchtree")
+except PackageNotFoundError:  # running from a source tree without installing
+    __version__ = "0.0.0"
+
+from .experiment.tracking import conclude, log, set  # noqa: E402, A004
+from .memory import from_data, load  # noqa: E402
+
+__all__ = ["__version__", "log", "set", "conclude", "load", "from_data"]

researchtree/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

researchtree/cli.py

@@ -0,0 +1,192 @@
+"""Command line entry point: serve / login / logout / open / memory / release."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+import threading
+import urllib.parse
+import webbrowser
+
+from . import __version__, git
+from .github import auth, tokens
+
+WEB_VIEWER = "https://darkpyonix.github.io/researchtree/"
+DEFAULT_PORT = 7337
+REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+
+
+def _repo_arg(value: str) -> str:
+    if not REPO_RE.match(value):
+        raise argparse.ArgumentTypeError("owner/name 형식이어야 합니다.")
+    return value
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    from .server import STATIC_DIR, make_server, url_of
+
+    repo = args.repo or git.origin_repo()
+    try:
+        httpd, app = make_server(repo, DEFAULT_PORT if args.port is None else args.port)
+    except OSError:
+        if args.port is not None:
+            print(f"포트 {args.port}을(를) 열 수 없습니다.", file=sys.stderr)
+            return 1
+        httpd, app = make_server(repo, 0)  # default port busy: pick a free one
+
+    url = url_of(app) + (f"?repo={urllib.parse.quote(repo, safe='/')}" if repo else "")
+    print(f"ResearchTree: {url}")
+    if repo:
+        print(f"기본 레포: {repo}")
+    if not (STATIC_DIR / "index.html").is_file():
+        print("주의: 뷰어 빌드 파일(static/)이 없습니다. README의 빌드 방법을 참고하세요.", file=sys.stderr)
+    print("종료하려면 Ctrl+C를 누르세요.")
+    if not args.no_browser:
+        threading.Timer(0.3, webbrowser.open, (url,)).start()
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\n종료합니다.")
+    finally:
+        httpd.server_close()
+    return 0
+
+
+def cmd_login(_: argparse.Namespace) -> int:
+    try:
+        auth.terminal_login()
+    except auth.AuthError as e:
+        print(f"로그인 실패: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\n취소했습니다.", file=sys.stderr)
+        return 130
+    return 0
+
+
+def cmd_logout(_: argparse.Namespace) -> int:
+    tokens.delete_token()
+    print("저장된 토큰을 삭제했습니다.")
+    if os.environ.get(tokens.ENV_TOKEN):
+        print(f"{tokens.ENV_TOKEN} 환경변수는 그대로 남아 있습니다.")
+    return 0
+
+
+def cmd_open(args: argparse.Namespace) -> int:
+    repo = args.repo or git.origin_repo()
+    if not repo:
+        print("현재 디렉토리에서 GitHub origin remote를 찾지 못했습니다. --repo owner/name을 지정하세요.", file=sys.stderr)
+        return 1
+    url = f"{WEB_VIEWER}?repo={urllib.parse.quote(repo, safe='/')}"
+    print(url)
+    webbrowser.open(url)
+    return 0
+
+
+def cmd_memory(args: argparse.Namespace) -> int:
+    """Print the research memory: the manifest, one island or experiment, alerts, or JSON."""
+    import json
+
+    from . import memory
+    from .github import api
+
+    try:
+        research = memory.load(args.repo)
+    except (ValueError, api.GitHubError) as e:
+        print(f"트리를 불러오지 못했습니다: {e}", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(research.to_dict(), ensure_ascii=False, indent=2))
+    elif args.check:
+        for alert in research.check():
+            print(alert)
+    elif args.name:
+        try:
+            print(research[args.name].describe())
+        except KeyError as e:
+            print(e, file=sys.stderr)
+            return 1
+    else:
+        print(research.manifest())
+    return 0
+
+
+def cmd_release(args: argparse.Namespace) -> int:
+    """Cut the next research version: plan by default, archive/tag/push/delete with --yes."""
+    from . import memory
+    from .experiment import release
+    from .github import api
+    from .memory.build import VERSION_RE, version_tag
+
+    g = release.Git()
+    if not g.ok("rev-parse", "--git-dir"):
+        print("git 저장소 안에서 실행하세요.", file=sys.stderr)
+        return 1
+    try:
+        research = memory.load(args.repo)
+        g.run("fetch", args.remote, "--prune", "--tags")
+        exists, merged = release.remote_checks(g, args.remote, research.root_branch)
+        steps = release.plan(research, exists=exists, merged=merged)
+        version = args.version or release.next_version(research)
+        if not VERSION_RE.match(version):
+            print(f"버전 이름은 v2, v2.1 같은 형식이어야 합니다: {version}", file=sys.stderr)
+            return 1
+        print(release.describe(steps, version_tag(research.root_branch, version)))
+        if not args.yes:
+            print("\n계획만 보여줬습니다. 실행하려면 --yes를 붙이세요.")
+            return 0
+        tag = release.execute(research, steps, version, git=g, remote=args.remote)
+    except (ValueError, api.GitHubError, release.ReleaseError) as e:
+        print(f"버전을 내지 못했습니다: {e}", file=sys.stderr)
+        return 1
+    print(f"완료: {tag}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="researchtree", description="Git 브랜치와 PR로 만드는 실험 트리 뷰어")
+    p.add_argument("--version", action="version", version=f"researchtree {__version__}")
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+
+    s = sub.add_parser("serve", help="로컬에서 뷰어를 띄운다")
+    s.add_argument("--repo", type=_repo_arg, help="처음 열 레포 (owner/name)")
+    s.add_argument("--port", type=int, help=f"포트 (기본 {DEFAULT_PORT})")
+    s.add_argument("--no-browser", action="store_true", help="브라우저를 열지 않는다")
+    s.set_defaults(func=cmd_serve)
+
+    sub.add_parser("login", help="터미널에서 GitHub Device Flow로 로그인한다").set_defaults(func=cmd_login)
+    sub.add_parser("logout", help="저장된 토큰을 삭제한다").set_defaults(func=cmd_logout)
+
+    o = sub.add_parser("open", help="현재 레포의 트리를 중앙 웹 뷰어에서 연다")
+    o.add_argument("--repo", type=_repo_arg, help="레포 (owner/name)")
+    o.set_defaults(func=cmd_open)
+
+    m = sub.add_parser("memory", help="PR 트리를 에이전트용 기억으로 출력한다 (요약 → 섬 → 실험)")
+    m.add_argument("name", nargs="?", help="버전(v3) 또는 실험 이름을 주면 그 카드만 출력")
+    m.add_argument("--repo", type=_repo_arg, help="레포 (owner/name)")
+    m.add_argument("--check", action="store_true", help="규칙 검사 결과(경고)만 출력")
+    m.add_argument("--json", action="store_true", help="트리 전체를 JSON으로 출력")
+    m.set_defaults(func=cmd_memory)
+
+    r = sub.add_parser("release", help="새 research 버전을 내고 끝난 실험 브랜치를 정리한다 (기본은 계획만 출력)")
+    r.add_argument("version", nargs="?", help="버전 이름 (기본: 마지막 버전의 다음 번호)")
+    r.add_argument("--repo", type=_repo_arg, help="레포 (owner/name)")
+    r.add_argument("--remote", default="origin", help="git remote (기본 origin)")
+    r.add_argument("--yes", action="store_true", help="계획대로 실행한다 (보관 머지, 태그, push, 브랜치 삭제)")
+    r.set_defaults(func=cmd_release)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

researchtree/experiment/__init__.py

@@ -0,0 +1 @@
+"""Experiment records: the PR body YAML block and the training-script API that writes it."""

researchtree/experiment/body.py

@@ -0,0 +1,266 @@
+"""Parse and losslessly rewrite the PR body YAML block. Same rules as `apps/core/src/prbody.ts`."""
+
+from __future__ import annotations
+
+import io
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+from ruamel.yaml.error import YAMLError
+
+STATUSES = ("running", "adopted", "rejected")
+
+# First ```yaml fenced block in the body. Opening and closing fences must each be on their own line.
+FENCE_RE = re.compile(r"^```ya?ml[ \t]*\r?\n(.*?)^```[ \t]*(?:\r?\n|$)", re.M | re.S)
+
+
+class PrBodyError(Exception):
+    pass
+
+
+@dataclass
+class ParsedBody:
+    meta: dict[str, Any]
+    has_block: bool
+    yaml: str
+    before: str
+    after: str
+    markdown: str
+    warnings: list[str] = field(default_factory=list)
+
+
+def _yaml() -> YAML:
+    y = YAML()  # round-trip: keeps comments and key order
+    y.preserve_quotes = True
+    y.width = 1 << 30  # never fold long lines (TS lineWidth: 0)
+    y.indent(mapping=2, sequence=4, offset=2)
+    y.allow_unicode = True
+    return y
+
+
+def _locate(body: str) -> tuple[int, int, str] | None:
+    m = FENCE_RE.search(body)
+    return (m.start(), m.end(), m.group(1)) if m else None
+
+
+def _join_markdown(before: str, after: str) -> str:
+    b, a = before.strip(), after.strip()
+    if b and a:
+        return f"{b}\n\n{a}"
+    return b or a
+
+
+def _to_plain(v: Any) -> Any:
+    if isinstance(v, dict):
+        return {str(k): _to_plain(x) for k, x in v.items()}
+    if isinstance(v, list):
+        return [_to_plain(x) for x in v]
+    if isinstance(v, bool):
+        return bool(v)
+    if isinstance(v, int):
+        return int(v)
+    if isinstance(v, float):
+        return float(v)
+    if isinstance(v, str):
+        return str(v)
+    return v
+
+
+def _js_str(v: Any) -> str:
+    """String conversion matching JS `String(v)`."""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, float):
+        if math.isfinite(v) and v == int(v):
+            return str(int(v))
+        return "NaN" if math.isnan(v) else ("Infinity" if v == math.inf else "-Infinity" if v == -math.inf else repr(v))
+    if isinstance(v, dict):
+        return "[object Object]"
+    if isinstance(v, list):
+        return ",".join("" if x is None else _js_str(x) for x in v)
+    return str(v)
+
+
+def _is_number(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _normalize_meta(raw: dict[str, Any], warnings: list[str]) -> dict[str, Any]:
+    """Type-check known fields. Invalid fields are dropped with a warning."""
+    meta = dict(raw)
+
+    def invalid() -> None:
+        if "invalid-field" not in warnings:
+            warnings.append("invalid-field")
+
+    for key in ("parent", "hypothesis", "change", "wandb"):
+        if meta.get(key) is not None and not isinstance(meta[key], str):
+            meta[key] = _js_str(meta[key])
+        if key in meta and meta[key] is None:
+            del meta[key]
+
+    if meta.get("status") is not None:
+        if meta["status"] not in STATUSES:
+            warnings.append("invalid-status")
+            del meta["status"]
+    else:
+        meta.pop("status", None)
+
+    if meta.get("metrics") is not None:
+        if not isinstance(meta["metrics"], dict):
+            invalid()
+            del meta["metrics"]
+        else:
+            clean: dict[str, Any] = {}
+            for k, v in meta["metrics"].items():
+                if _is_number(v) or isinstance(v, str):
+                    clean[k] = v
+                else:
+                    invalid()
+            meta["metrics"] = clean
+
+    if meta.get("tags") is not None:
+        tags = meta["tags"]
+        if isinstance(tags, list):
+            meta["tags"] = [_js_str(t) if t is not None else "null" for t in tags]
+        elif isinstance(tags, str):
+            meta["tags"] = [tags]
+        else:
+            invalid()
+            del meta["tags"]
+
+    return meta
+
+
+def parse(body: str | None) -> ParsedBody:
+    text = body or ""
+    loc = _locate(text)
+    if not loc:
+        return ParsedBody({}, False, "", text, "", text.strip(), ["no-yaml-block"])
+
+    start, end, raw = loc
+    before, after = text[:start], text[end:]
+    warnings: list[str] = []
+    meta: dict[str, Any] = {}
+
+    try:
+        value = _to_plain(_yaml().load(raw))
+    except YAMLError:
+        warnings.append("yaml-parse-error")
+    else:
+        if value is None:
+            meta = {}
+        elif isinstance(value, dict):
+            meta = _normalize_meta(value, warnings)
+        else:
+            warnings.append("yaml-parse-error")
+
+    if "yaml-parse-error" not in warnings and not meta.get("hypothesis"):
+        warnings.append("missing-hypothesis")
+
+    return ParsedBody(meta, True, raw, before, after, _join_markdown(before, after), warnings)
+
+
+def _fence(yaml_text: str) -> str:
+    y = yaml_text if yaml_text.endswith("\n") else yaml_text + "\n"
+    return "```yaml\n" + y + "```"
+
+
+def _dump(doc: Any) -> str:
+    buf = io.StringIO()
+    _yaml().dump(doc, buf)
+    return buf.getvalue()
+
+
+def update(body: str | None, patch: dict[str, Any]) -> str:
+    """
+    Modify only the YAML block and leave the rest of the body untouched. A None value deletes the field.
+    `metrics` is merged into the existing map (set a key to None to delete it).
+    A broken YAML block is never overwritten; PrBodyError is raised instead.
+    """
+    text = body or ""
+    loc = _locate(text)
+
+    doc: Any = CommentedMap()
+    if loc:
+        try:
+            doc = _yaml().load(loc[2])
+        except YAMLError as e:
+            raise PrBodyError("PR 본문의 YAML 블록을 파싱할 수 없어 수정하지 않았습니다.") from e
+    if doc is None:
+        doc = CommentedMap()
+    if not isinstance(doc, dict):
+        raise PrBodyError("PR 본문의 YAML 블록이 key: value 형식이 아닙니다.")
+
+    for key, value in patch.items():
+        if key == "metrics" and value is not None:
+            if not isinstance(doc.get("metrics"), dict):
+                doc["metrics"] = CommentedMap()
+            metrics = doc["metrics"]
+            for mk, mv in value.items():
+                if mv is None:
+                    metrics.pop(mk, None)
+                else:
+                    metrics[mk] = mv
+            continue
+        if value is None:
+            doc.pop(key, None)
+        else:
+            doc[key] = _to_yaml_node(value)
+
+    block = _fence(_dump(doc))
+    if not loc:
+        rest = text.lstrip()
+        return f"{block}\n\n{rest}" if rest else f"{block}\n"
+    start, end, _ = loc
+    trailing = "\n" if re.search(r"\r?\n$", text[start:end]) else ""
+    return text[:start] + block + trailing + text[end:]
+
+
+def _to_yaml_node(v: Any) -> Any:
+    if isinstance(v, dict) and not isinstance(v, CommentedMap):
+        m = CommentedMap()
+        for k, x in v.items():
+            m[k] = _to_yaml_node(x)
+        return m
+    if isinstance(v, (list, tuple)) and not isinstance(v, CommentedSeq):
+        return CommentedSeq(_to_yaml_node(x) for x in v)
+    return v
+
+
+def replace_markdown(body: str | None, markdown: str) -> str:
+    """Keep the YAML block and replace only the human-readable markdown."""
+    text = body or ""
+    loc = _locate(text)
+    md = markdown.strip()
+    if not loc:
+        return md
+    block = re.sub(r"\r?\n$", "", text[loc[0] : loc[1]])
+    return f"{block}\n\n{md}\n" if md else f"{block}\n"
+
+
+# Headings that mark the conclusion section, in any case: `## 결론` or `## Conclusion(s)`. Part of the
+# PR-body convention shared with the TypeScript implementation.
+CONCLUSION_RE = re.compile(r"^##[ \t]+(결론|conclusions?)[ \t]*\r?\n(.*?)(?=^##[ \t]|\Z)", re.M | re.S | re.I)
+
+
+def set_conclusion(body: str | None, conclusion: str, heading: str | None = "결론") -> str:
+    """Create or replace the conclusion section. An existing `## 결론` / `## Conclusion` section keeps
+    its heading and only its text changes; otherwise a new section with `heading` goes first."""
+    md = parse(body).markdown
+    m = CONCLUSION_RE.search(md)
+    if m:
+        nxt = md[: m.start()] + f"## {m.group(1)}\n{conclusion.strip()}\n\n" + md[m.end() :]
+    else:
+        nxt = f"## {heading or '결론'}\n{conclusion.strip()}\n\n" + md
+    return replace_markdown(body, nxt)
+
+
+def get_conclusion(body: str | None) -> str | None:
+    """Text of the conclusion section (`## 결론` or `## Conclusion`), or None."""
+    m = CONCLUSION_RE.search(parse(body).markdown)
+    return m.group(2).strip() if m else None

researchtree/experiment/release.py

@@ -0,0 +1,171 @@
+"""Cut a new research version and clean up finished experiment branches (docs/CONVENTIONS.md 1.4).
+
+Finished branches (PR merged or closed) are deleted when a version is cut. A branch already in the
+root branch is deleted as is. Any other branch is archived first so its history stays reachable:
+its commits are reverted on the branch (new commits, never a reset), the branch is merged into the
+root branch with --no-ff (a no-op for the code), then deleted. Branches with running descendants
+are kept for a later version: reverting a parent before its child lands would drop code the child
+builds on.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from typing import Callable, Iterable
+
+from ..memory.build import version_tag
+from ..memory.model import Experiment, Research
+
+DELETE = "delete"  # already in the root branch
+ARCHIVE = "archive"  # revert, merge into the root branch, delete
+KEEP = "keep"  # has running descendants
+
+
+class ReleaseError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Step:
+    action: str
+    branch: str
+    reason: str
+
+
+def next_version(research: Research) -> str:
+    """The major version after the latest: v3 -> v4, v2.1 -> v3; v1 when there are no versions."""
+    names = [v.name for v in research.versions if re.match(r"^v\d+", v.name)]
+    if not names:
+        return "v1"
+    return f"v{max(int(re.match(r'^v(\d+)', n).group(1)) for n in names) + 1}"  # type: ignore[union-attr]
+
+
+def plan(research: Research, *, exists: Callable[[str], bool], merged: Callable[[str], bool]) -> list[Step]:
+    """What to do with each finished experiment branch that still exists on the remote."""
+    steps: list[Step] = []
+    for e in research.experiments:
+        if not e.finished or not exists(e.branch):
+            continue
+        running = [d.name for d in _island_descendants(e) if not d.finished]
+        if running:
+            steps.append(Step(KEEP, e.branch, "진행 중인 자손: " + ", ".join(running)))
+        elif merged(e.branch):
+            steps.append(Step(DELETE, e.branch, f"이미 {research.root_branch}에 포함됨"))
+        else:
+            steps.append(Step(ARCHIVE, e.branch, f"커밋을 revert한 뒤 {research.root_branch}에 머지해 기록 보존"))
+    return steps
+
+
+def _island_descendants(e: Experiment) -> list[Experiment]:
+    """Experiments that build on this branch's code: its descendants on the same island. A later
+    version's island starts from the root branch, not from this branch, so the walk stops there."""
+    out: list[Experiment] = []
+    stack = [c for c in e.children if isinstance(c, Experiment)]
+    while stack:
+        n = stack.pop()
+        out.append(n)
+        stack.extend(c for c in n.children if isinstance(c, Experiment))
+    return out
+
+
+class Git:
+    """Strict git runner for one working tree: any failure raises ReleaseError."""
+
+    def __init__(self, cwd: str | None = None) -> None:
+        self.cwd = cwd
+
+    def run(self, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+        res = subprocess.run(["git", *args], cwd=self.cwd, capture_output=True, text=True, encoding="utf-8")
+        if check and res.returncode != 0:
+            raise ReleaseError(f"git {' '.join(args)} 실패: {(res.stderr or res.stdout).strip()}")
+        return res
+
+    def out(self, *args: str) -> str:
+        return self.run(*args).stdout.strip()
+
+    def ok(self, *args: str) -> bool:
+        return self.run(*args, check=False).returncode == 0
+
+
+def remote_checks(git: Git, remote: str, root: str) -> tuple[Callable[[str], bool], Callable[[str], bool]]:
+    """`exists(branch)` and `merged(branch)` against the fetched remote-tracking refs."""
+
+    def exists(branch: str) -> bool:
+        return git.ok("rev-parse", "--verify", "--quiet", f"refs/remotes/{remote}/{branch}")
+
+    def merged(branch: str) -> bool:
+        return git.ok("merge-base", "--is-ancestor", f"{remote}/{branch}", f"{remote}/{root}")
+
+    return exists, merged
+
+
+def _archive(git: Git, remote: str, root: str, branch: str) -> None:
+    git.run("switch", "-C", branch, f"{remote}/{branch}")
+    base = git.out("merge-base", root, branch)
+    commits = git.out("rev-list", f"{base}..{branch}")
+    if commits:
+        # One revert commit per experiment commit, newest first. Merge commits or conflicts make
+        # that fail; then one commit restores the fork point's content instead (still a revert:
+        # nothing is rewritten).
+        if not git.ok("revert", "--no-edit", f"{base}..{branch}"):
+            git.run("revert", "--abort", check=False)
+            git.run("read-tree", "--reset", "-u", base)
+            git.run("commit", "--allow-empty", "-m", f"Revert: Undo {branch} back to {base[:7]} for archiving")
+    if not git.ok("diff", "--quiet", base, branch):
+        raise ReleaseError(f"{branch}: revert 후에도 내용이 갈라진 지점과 다릅니다.")
+    git.run("switch", root)
+    git.run("merge", "--no-ff", branch, "-m", f"Chore: Archive {branch}")
+    if not git.ok("diff", "--quiet", "HEAD^1", "HEAD"):
+        raise ReleaseError(f"{branch}: 보관 머지가 {root}의 내용을 바꿨습니다.")
+
+
+def execute(
+    research: Research,
+    steps: Iterable[Step],
+    version: str,
+    *,
+    git: Git,
+    remote: str = "origin",
+    log: Callable[[str], None] = print,
+) -> str:
+    """Archive, tag `<root>/<version>`, push, delete. Returns the tag. The working tree must be clean."""
+    root = research.root_branch
+    tag = version_tag(root, version)
+    steps = list(steps)
+    if git.out("status", "--porcelain"):
+        raise ReleaseError("작업 트리가 깨끗하지 않습니다. 커밋하거나 stash한 뒤 다시 실행하세요.")
+    if git.ok("rev-parse", "--verify", "--quiet", f"refs/tags/{tag}"):
+        raise ReleaseError(f"태그 {tag}가 이미 있습니다.")
+
+    git.run("switch", root)
+    git.run("merge", "--ff-only", f"{remote}/{root}")
+    archived = [s.branch for s in steps if s.action == ARCHIVE]
+    for branch in archived:
+        log(f"보관 머지: {branch}")
+        _archive(git, remote, root, branch)
+
+    git.run("tag", "-a", tag, "-m", f"{root} {version}")
+    log(f"태그: {tag}")
+    git.run("push", remote, root, *archived, f"refs/tags/{tag}")
+
+    gone = [s.branch for s in steps if s.action in (DELETE, ARCHIVE)]
+    if gone:
+        git.run("push", remote, "--delete", *gone)
+        for branch in gone:
+            if git.ok("rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"):
+                git.run("branch", "-D", branch)
+        log("삭제: " + ", ".join(gone))
+    return tag
+
+
+def describe(steps: Iterable[Step], version_tag_name: str) -> str:
+    steps = list(steps)
+    label = {DELETE: "삭제", ARCHIVE: "보관 머지 후 삭제", KEEP: "보류"}
+    lines = [f"새 버전: {version_tag_name}"]
+    if not steps:
+        lines.append("정리할 브랜치가 없습니다.")
+    for s in steps:
+        lines.append(f"- [{label[s.action]}] {s.branch}: {s.reason}")
+    return "\n".join(lines)