Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(unpack-atlas): an input is followed the way the system opens it — every link and folder its path looks up, a folder a later .. leaves again included, is compared with the run dir (runio.follow_path), so a path through anything inside --out-dir is refused by that entry before anything is made, --force or not, a link loop is refused by name, and a path that only passes through the run dir itself still runs; and every writer's run-dir lock is the entry .sprite-gen.lock itself — a link or a folder there is refused, never followed, read or removed, so reclaiming a stale lock deletes only a stale lock file
Soohong Kimd033962f4b82
diff --git a/docs/run-contract.md b/docs/run-contract.mdindex 7e31422..2752ef5 100644--- a/docs/run-contract.md+++ b/docs/run-contract.md@@ -396,9 +396,16 @@ throughout, so a concurrent **writer** cannot preempt (writer Isolation).**An import never touches its inputs.** An input — `--pngs-dir`, `--atlas`, `--manifest`, theatlas a manifest names, and what the import reads in `--pngs-dir` (every frame, `_base` image,`_refs` PNG and `meta.json`, and every folder it reads one from), any of which may be a link — that-is the run dir, lies inside it, or holds it is refused before anything is made, with or without-`--force`: a publish replaces the run dir's whole prior content, and the run would otherwise be-written into its input. What is found in `--pngs-dir` is checked once all of it is found and is+is the run dir, lies inside it, goes through anything inside it, or holds it is refused before+anything is made, with or without `--force`: a publish replaces the run dir's whole prior content+entry by entry — a link as a link, so a path that goes through one breaks — and the run would+otherwise be written into its input. An input is followed the way the system opens it+(`runio.follow_path`): its path as given, made absolute but never resolved or folded, one entry at+a time — every link (a Windows directory junction counts as one) and every folder it looks up,+including a folder that a later `..` leaves again. The refusal names the first entry it goes+through inside the run dir, and a link loop is refused by name. A path that only passes through the+run dir itself (`run/../incoming`) is not refused: the run dir stays where it is while its content+is replaced. What is found in `--pngs-dir` is checked once all of it is found and isnamed in the refusal by where it was found. Folders are compared by real path and fileidentity (`runio.same_folder`, `runio.inside_folder`), so a link or a second spelling on acase-insensitive volume is the same folder. The run is built in a staging folder of its own beside@@ -406,8 +413,11 @@ the run dir and the prior content is moved aside into a backup folder of its own(`runio.new_stage`: `.<name>.<pid>-<random>.sg-staging`, `.sg-backup.<pid>-<random>`). A folderthat already has a staging or backup name, an input's or anyone else's, is never reused or removed:besides those two folders the run deletes only the prior content it replaces, and a failed publish-puts every prior file back. The run carries the run dir's name (`character.id`) and path-(`frames-manifest.json` `run_dir`), never the staging folder's.+puts every prior file back. The run dir's single-writer lock is the entry `.sprite-gen.lock` itself+(`runio.acquire_run_dir_lock`, every writer): a link or a folder at that name is refused by name and+never followed, read or removed, so reclaiming a stale lock deletes only a stale lock file. The run+carries the run dir's name (`character.id`) and path (`frames-manifest.json` `run_dir`), never the+staging folder's.> **Reader isolation (named strategy: reader/writer locking).** Every operation that> republishes frames — a `--force` re-import **and** a re-extract (`extract` builds into a@@ -554,7 +564,8 @@ boundary of the run-dir's atomicity and concurrency guarantees. What is **in forA consumer that only calls the manifest gate once but then reads the frame tree unguarded wouldleave a TOCTOU window; the full read must be inside the strategy.- **Cross-process single-writer.** `.sprite-gen.lock` blocks a second **process** from writing- the same run dir; the pipeline's **one worker owns one character folder** rule (§2, SKILL.md)+ the same run dir (a link or a folder at that name is refused, never followed: §4); the pipeline's+ **one worker owns one character folder** rule (§2, SKILL.md)is what excludes concurrent writers on the same run dir in the first place. Same-processre-entry is intentionally allowed so one interpreter can run prepare → extract → compose insequence.diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.pyindex 3959557..375d912 100644--- a/sprite_gen/frames/unpack_atlas.py+++ b/sprite_gen/frames/unpack_atlas.py@@ -41,6 +41,7 @@ from sprite_gen.spec.runio import (acquire_run_dir_lock,atomic_save_image,atomic_write_text,+ follow_path,inside_folder,new_stage,publish_guard,@@ -373,22 +374,40 @@ def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str"base_source": base_out_name, "imported_refs": imported_refs_manifest}+def _follow(flag: str, given: Path) -> tuple[list[Path], Path]:+ """`runio.follow_path` of an input: every entry its path looks up and the real path it reaches. A path that+ cannot be followed (a link loop) is refused by name before anything is made."""+ try:+ return follow_path(given)+ except OSError as exc:+ raise SystemExit(f"{flag} cannot be followed: {exc.filename}: {exc.strerror}") from None++def _refuse_overlap(inputs: dict[str, Path | None], out_dir: Path) -> None:"""An input is never written, moved or deleted. Refused before anything is made: an input that is- the run dir (the run would replace it), lies inside it (a --force publish moves the run dir's prior- content aside and deletes it), or holds it (the run would be written into the input). Read by real- path and file identity, so a link, or a second spelling on a case-insensitive volume, is the same- folder."""+ the run dir (the run would replace it), lies inside it or goes through anything inside it (a --force+ publish moves the run dir's prior content aside and deletes it entry by entry — a link as a link, so a+ path through it breaks), or holds it (the run would be written into the input). An input is followed+ the way the system opens it (`runio.follow_path`): every link and folder its path looks up, a folder a+ later `..` leaves again included. Read by real path and file identity, so a link, or a second spelling+ on a case-insensitive volume, is the same folder."""+ looked_at: set[Path] = set()for flag, given in inputs.items():if given is None:continue- path = Path(given).expanduser().resolve()+ looked, path = _follow(flag, Path(given).expanduser())if same_folder(path, out_dir):kind = "folder" if path.is_dir() else "file"raise SystemExit(f"{flag} and --out-dir are the same {kind}: {path} (an input is never overwritten)")if inside_folder(path, out_dir):raise SystemExit(f"{flag} lies inside --out-dir: {path} ""(--force replaces the run dir's content, never an input)")+ fresh = [entry for entry in looked if entry not in looked_at]+ looked_at.update(fresh)+ through = next((entry for entry in fresh if inside_folder(entry, out_dir)), None)+ if through is not None:+ raise SystemExit(f"{flag} goes through {through}, inside --out-dir "+ "(--force replaces the run dir's content, never an input)")if inside_folder(out_dir, path):raise SystemExit(f"--out-dir lies inside {flag}: {out_dir} (a run is never written into its input)")@@ -396,7 +415,8 @@ def _refuse_overlap(inputs: dict[str, Path | None], out_dir: Path) -> None:def _found_inputs(src: Path, groups: list[dict[str, Any]], *files: Path | None) -> dict[str, Path]:"""What an import reads in its --pngs-dir `src`, named by where it was found there: every folder it reads a filefrom (a group folder, `_base`, `_refs`), then every file it reads (a frame, a `_refs` PNG, and `files`: the- `_base` image and meta.json when it reads them). Any of them may be a link, and lead into the run dir."""+ `_base` image and meta.json when it reads them). Any of them may be a link, and lead into the run dir or+ through it."""read = [p for g in groups for p in (*g["paths"], *g["refs"])] + [p for p in files if p is not None]folders = [f for f in dict.fromkeys(p.parent for p in read) if f != src]return {f"{relative_posix(p, src)} in --pngs-dir": p for p in (*folders, *read)}@@ -494,13 +514,13 @@ def _run(args: argparse.Namespace):out_dir = args.out_dir.expanduser().resolve()else:if args.pngs_dir:- base = args.pngs_dir.expanduser().resolve()+ _, base = _follow("--pngs-dir", args.pngs_dir.expanduser())out_dir = base.parent / f"{base.name}-curator"elif args.atlas:- base = args.atlas.expanduser().resolve()+ _, base = _follow("--atlas", args.atlas.expanduser())out_dir = base.parent / f"{base.stem}-curator"elif args.manifest:- base = args.manifest.expanduser().resolve()+ _, base = _follow("--manifest", args.manifest.expanduser())out_dir = base.parent / f"{base.stem}-curator"else:raise SystemExit("need one of --pngs-dir / --atlas / --manifest (or pass --out-dir)")@@ -578,8 +598,9 @@ def _run(args: argparse.Namespace):if bad_refs:raise SystemExit("invalid _refs role prefix — expected anchor-/basis-/guide-<name>.png, got: "+ ", ".join(bad_refs))- # what the import found in --pngs-dir is an input too: a link there may lead into --out-dir, whose prior- # content --force deletes. Compared with the run dir once all of it is found, before the run dir is made.+ # what the import found in --pngs-dir is an input too: a link there may lead into --out-dir or through it,+ # whose prior content --force deletes. Compared with the run dir once all of it is found, before the run dir+ # is made._refuse_overlap(_found_inputs(src, groups, base_src, meta_path if meta_path.is_file() else None), out_dir)# atomic rebuild: all validation above ran before any mutation; build into a# staging dir, then publish over out_dir. A --force re-import that fails (or isdiff --git a/sprite_gen/spec/runio.py b/sprite_gen/spec/runio.pyindex bf4b35f..38d7ffe 100644--- a/sprite_gen/spec/runio.py+++ b/sprite_gen/spec/runio.py@@ -9,15 +9,18 @@ example Claude Code and the Codex app driving the skill in parallel):two workers writing one character folder; this makes the rule enforcedinstead of documentation-only. Writers (extract / compose / export / unpack,and the webview's compose/export subprocesses through them) fail loudly with- the holder's pid instead of silently interleaving output files.+ the holder's pid instead of silently interleaving output files. The lock is+ the entry `.sprite-gen.lock` itself: a link or a folder at that name is refused,+ never followed, read or removed.- `atomic_write_text()` / `atomic_save_image()` — temp file in the target dir+ `os.replace`, so a concurrent reader never observes a half-writtenatlas/manifest/frame. `atomic_write_set()` extends the same mechanism to aset of files that only makes sense published together (a sheet, its manifest,and the report naming it).-- `same_folder()` / `inside_folder()` / `new_stage()` — a writer never writes- into, moves or deletes its inputs: inputs and outputs are compared by real- path and file identity before anything is made, and a staging folder is a+- `same_folder()` / `inside_folder()` / `follow_path()` / `new_stage()` — a writer+ never writes into, moves or deletes its inputs: inputs and outputs are compared+ by real path and file identity before anything is made — an input by every+ entry its path looks up, not only by where it ends — and a staging folder is anew one of the run's own, the only thing beside the output a run deletes.`curation.json` is intentionally NOT under this pipeline write lock: the curation@@ -35,9 +38,11 @@ from __future__ import annotationsimport atexitimport contextlib+import errnoimport jsonimport osimport secrets+import statimport sysimport tempfileimport time@@ -153,6 +158,58 @@ def inside_folder(path: Path, folder: Path) -> bool:return any(same_folder(parent, folder) for parent in path.parents)+_MAX_LINKS = 40 # 이보다 많은 링크를 지나면 고리다 (리눅스 커널의 한도, macOS 는 32)+# Windows 디렉터리 junction 의 표시 — os.lstat 은 3.8 부터 symlink 와 junction 을 따라가지 않고 그 자체를 열고,+# os.readlink 는 3.8 부터 junction 이 가리키는 경로를 돌려준다. 그래서 junction 도 링크로 따라간다.+_JUNCTION = getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", None)+++def _is_link(entry: os.stat_result) -> bool:+ return stat.S_ISLNK(entry.st_mode) or (+ _JUNCTION is not None and getattr(entry, "st_reparse_tag", None) == _JUNCTION)+++def follow_path(path: Path) -> tuple[list[Path], Path]:+ """`path` 를 운영체제가 열 때처럼 한 칸씩 따라간다. 찾아본 항목 전부(링크와 폴더, 각각 실경로 부모 + 이름 —+ 뒤의 `..` 로 다시 나오는 폴더도)와 닿은 실경로를 돌려준다. 받은 경로는 절대화만 한다(resolve·normpath 로 `..`+ 를 글자째 접으면 링크 뒤의 `..` 가 다른 폴더를 가리킨다). 상대 링크는 링크가 놓인 실폴더에서 읽고, `..` 는+ 지금까지 닿은 실폴더의 부모로 간다. 없는 칸에서 멈추면 남은 칸을 붙여 돌려준다 — 읽는 쪽이 그 자리에서+ 실패한다. 링크를 `_MAX_LINKS` 번 넘게 지나면 고리라 OSError(ELOOP)."""+ path = Path(path)+ if not path.is_absolute():+ path = Path.cwd() / path+ reached = Path(path.anchor)+ todo = list(reversed(path.parts[1:]))+ looked: list[Path] = []+ links = 0+ while todo:+ name = todo.pop()+ if name in ("", "."):+ continue+ if name == "..":+ reached = reached.parent+ continue+ entry = reached / name+ looked.append(entry)+ try:+ found = os.lstat(entry)+ except OSError:+ return looked, entry.joinpath(*reversed(todo))+ if not _is_link(found):+ reached = entry+ continue+ links += 1+ if links > _MAX_LINKS:+ raise OSError(errno.ELOOP, os.strerror(errno.ELOOP), str(path))+ target = Path(os.readlink(entry))+ if target.is_absolute():+ reached = Path(target.anchor)+ todo.extend(reversed(target.parts[1:]))+ else:+ todo.extend(reversed(target.parts))+ return looked, reached++def new_stage(out: Path, suffix: str) -> Path:"""`out` 옆에 이 실행만의 빈 임시 폴더 `.<out>.<pid>-<random><suffix>` — 같은 볼륨이라 다 쓴 뒤 rename 으로내놓는다. 이름이 이미 있으면(입력이든 다른 실행의 것이든) 그 폴더는 건드리지 않고 다른 이름을 고른다.@@ -185,6 +242,10 @@ def acquire_run_dir_lock(run_dir: Path, owner: str) -> Path:A lock whose pid is dead — or unreadable and older than STALE_LOCK_SECONDS —is reclaimed, so a killed run never wedges the run dir.+ The lock is the entry at that name in the run dir itself, never resolved:+ a link or a folder there is refused before anything is read, and is never+ followed or removed — reclaiming it would delete whatever it points to.+Re-entry from the same process is allowed: the MCP server / freeze binaryruns many pipeline steps in one interpreter against the same run dir, and awriter must never block itself.@@ -192,14 +253,23 @@ def acquire_run_dir_lock(run_dir: Path, owner: str) -> Path:Release runs via atexit (normal return, SystemExit, KeyboardInterrupt).A SIGKILL'd holder is covered by the dead-pid reclaim above."""- lock_path = (run_dir / LOCK_FILENAME).resolve()+ lock_path = Path(run_dir).resolve() / LOCK_FILENAMEif lock_path in _HELD_LOCKS:return lock_pathwhile True:try:- fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)+ fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY) # never follows a link at the name (open(2))breakexcept FileExistsError:+ try:+ regular = stat.S_ISREG(os.lstat(lock_path).st_mode)+ except FileNotFoundError:+ continue # holder released it between our checks; retry the create+ if not regular:+ raise SystemExit(+ f"run dir lock {lock_path} is not a lock file (a link or a folder)\n"+ f" sprite-gen never follows or removes it; move it away if no sprite-gen process is running"+ )holder: dict = {}try:holder = json.loads(lock_path.read_text(encoding="utf-8"))@@ -253,7 +323,7 @@ def release_run_dir_lock(run_dir: Path) -> None:재추출이 산 pid 락에 막힌다. 락은 세션 리스가 아니라 작업 단위 writer-writer상호배제고, 원자성은 스테이징 통짜 스왑이 보장하므로 작업이 끝나면 놓는 게맞다. atexit 핸들러는 남아 있어도 멱등이다 (unlink 실패 무시 + discard)."""- lock_path = (Path(run_dir).resolve() / LOCK_FILENAME).resolve()+ lock_path = Path(run_dir).resolve() / LOCK_FILENAMEif lock_path not in _HELD_LOCKS:returntry: