Skip to content

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.md
index 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`, the
atlas 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 is
named in the refusal by where it was found. Folders are compared by real path and file
identity (`runio.same_folder`, `runio.inside_folder`), so a link or a second spelling on a
case-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 folder
that 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 for
A consumer that only calls the manifest gate once but then reads the frame tree unguarded would
leave 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-process
re-entry is intentionally allowed so one interpreter can run prepare → extract → compose in
sequence.
diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.py
index 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 file
from (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 is
diff --git a/sprite_gen/spec/runio.py b/sprite_gen/spec/runio.py
index 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 enforced
instead 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-written
atlas/manifest/frame. `atomic_write_set()` extends the same mechanism to a
set 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 a
new 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 annotations
import atexit
import contextlib
+import errno
import json
import os
import secrets
+import stat
import sys
import tempfile
import 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 binary
runs many pipeline steps in one interpreter against the same run dir, and a
writer 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_FILENAME
if lock_path in _HELD_LOCKS:
return lock_path
while 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))
break
except 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_FILENAME
if lock_path not in _HELD_LOCKS:
return
try: