Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(unpack-atlas): `sprite-gen unpack-atlas` never touches its inputs — an input and --out-dir that are one folder or lie one inside the other are refused by file identity before anything is made, and the run is staged and backed up in folders of its own, the only things it deletes besides the prior content it replaces
Soohong Kim17f749054e5e
diff --git a/docs/run-contract.md b/docs/run-contract.mdindex c4f774e..0d6a607 100644--- a/docs/run-contract.md+++ b/docs/run-contract.md@@ -146,8 +146,10 @@ not restate it elsewhere; point here..frames.sg-staging/ # transient: extract builds the new generation here, swapped into frames/ under publish_guard```Transient publish sidecars exist only during an extract/import commit: `.frames.sg-backup`-and `.extract-failure.sg-backup` (in-place rollback copies) and `.<name>.sg-rwlock` (in the-parent dir — the publish reader/writer lock). Their durability/concurrency boundary is §7.+and `.extract-failure.sg-backup` (extract's in-place rollback copies), an import's own+`.<name>.<pid>-<random>.sg-staging` (beside the run dir) and `.sg-backup.<pid>-<random>` (in it,+§4), and `.<name>.sg-rwlock` (in the parent dir — the publish reader/writer lock). Their+durability/concurrency boundary is §7.Rules the display depends on:@@ -391,6 +393,19 @@ A **failed or invalid** re-import (e.g. a bad `_refs` role) leaves the prior runsucceeds or rolls back). The publish holds the run-dir single-writer lock in placethroughout, so a concurrent **writer** cannot preempt (writer Isolation).+**An import never touches its inputs.** An input — `--pngs-dir`, `--atlas`, `--manifest`, or+the atlas a manifest names — 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. 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+the run dir and the prior content is moved aside into a backup folder of its own inside it+(`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.+> **Reader isolation (named strategy: reader/writer locking).** Every operation that> republishes frames — a `--force` re-import **and** a re-extract (`extract` builds into a> staging dir, then swaps `frames/` into place) — holds the run dir's *exclusive* publishdiff --git a/sprite_gen/effects/breathe.py b/sprite_gen/effects/breathe.pyindex 0a55607..539f929 100644--- a/sprite_gen/effects/breathe.py+++ b/sprite_gen/effects/breathe.py@@ -68,8 +68,6 @@ from __future__ import annotationsimport argparseimport jsonimport math-import os-import secretsimport shutilfrom pathlib import Path@@ -80,6 +78,7 @@ from sprite_gen.effects.anatomy import Anatomy, analyzefrom sprite_gen.curate.curation import (BREATHE_MODES, BREATHE_SMOOTH_DEPTH, BREATHE_SMOOTH_DEPTH_X,BREATHE_SMOOTH_SHAPE, normalize_transform, state_breathe)from sprite_gen.frames.extract import solid_alpha_bbox+from sprite_gen.spec.runio import inside_folder, new_stage, same_folder# 강체 경계에서 변형 강도가 0 이 되기까지의 테이퍼 반폭 (콘텐츠 높이 비율).# 이 테이퍼가 이음매를 없앤다 — 경계에서 강도가 계단이 아니라 경사로 떨어진다.@@ -938,31 +937,6 @@ def _cells(text: str) -> list[int]:raise argparse.ArgumentTypeError(f"cell numbers separated by commas, not {text!r}")-def _same(a: Path, b: Path) -> bool:- """같은 폴더인가 — 장치·inode 로 본다. 링크로 돌아 들어와도, 대소문자를 가리지 않는 볼륨에서 철자만- 달라도 같은 폴더다."""- return a.exists() and b.exists() and a.samefile(b)---def _inside(path: Path, folder: Path) -> bool:- """`path` 가 `folder` 안에 드는가 — 조상 가운데 `folder` 와 같은 폴더가 있다. `path` 는 아직 없어도 된다."""- return any(_same(parent, folder) for parent in path.parents)---def _new_stage(out: Path) -> Path:- """`out` 옆에 이 실행만의 빈 임시 폴더 — 같은 볼륨이라 다 쓴 뒤 rename 한 번으로 내놓는다. 이름이 이미- 있으면(원본이든 다른 실행의 것이든) 그 폴더는 건드리지 않고 다른 이름을 고른다. mkdtemp(0700)가 아니라- mkdir 이라 내놓은 out 이 보통 폴더 권한을 갖는다."""- for _ in range(100):- stage = out.parent / f".{out.name}.{os.getpid()}-{secrets.token_hex(4)}.partial"- try:- stage.mkdir()- except FileExistsError:- continue- return stage- raise SystemExit(f"breathe: {out.parent} 에 임시 폴더 이름을 못 골랐다")--def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("frames", help="folder of the loop's frames (*.png, played in name order)")parser.add_argument("out", help="new folder for the breathing frames (same names) and breathe.json")@@ -1033,11 +1007,11 @@ def run(*, frames: str, out: str, mode: str | None = None, depth: float | None =raise SystemExit(f"breathe: {src_dir} 에 PNG 프레임이 없다")# 무엇을 만들거나 지우기 전에 — 실경로와 폴더 동일성으로 본다(링크, 철자).src_real, out_real = src_dir.resolve(), out_dir.resolve()- if _same(out_real, src_real):+ if same_folder(out_real, src_real):raise SystemExit("breathe: out 이 frames 와 같은 폴더다 — 원본 프레임 위에 덮어쓰지 않는다")- if _inside(out_real, src_real):+ if inside_folder(out_real, src_real):raise SystemExit(f"breathe: out 이 frames 안에 있다 ({out_real}) — 원본 폴더 안에는 쓰지 않는다")- if _inside(src_real, out_real):+ if inside_folder(src_real, out_real):raise SystemExit(f"breathe: frames 가 out 안에 있다 ({src_real}) — 원본이 든 폴더에 내놓지 않는다")if out_real.exists() and not out_real.is_dir():raise SystemExit(f"breathe: {out_dir} 는 폴더가 아니다")@@ -1055,7 +1029,7 @@ def run(*, frames: str, out: str, mode: str | None = None, depth: float | None =# 실행들은 각자의 임시 폴더에 쓰고, rename 이 먼저 닿은 쪽이 내놓는다(늦은 쪽은 차 있는 out 에서 멈춘다).# 지우는 것은 이 실행의 임시 폴더뿐이고, 원본 폴더에는 아무것도 쓰지 않는다.out_real.parent.mkdir(parents=True, exist_ok=True)- stage = _new_stage(out_real)+ stage = new_stage(out_real, ".partial")try:for path, frame in zip(paths, baked):frame.save(stage / path.name)diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.pyindex 4859ada..8985c81 100644--- a/sprite_gen/frames/unpack_atlas.py+++ b/sprite_gen/frames/unpack_atlas.py@@ -30,7 +30,7 @@ import argparseimport jsonimport shutilfrom pathlib import Path-from typing import Any+from typing import Any, Callablefrom PIL import Image@@ -41,8 +41,11 @@ from sprite_gen.spec.runio import (acquire_run_dir_lock,atomic_save_image,atomic_write_text,+ inside_folder,+ new_stage,publish_guard,relative_posix,+ same_folder,)from sprite_gen.frames.segment import mask_componentsfrom sprite_gen.util.console import utf8_streams@@ -204,7 +207,11 @@ def write_run(meta: dict[str, Any],layout_source: str,provenance: dict[str, Any],+ run_dir: Path | None = None,) -> dict[str, Any]:+ """Write the run's files into `out_dir`, a staging folder when `run_dir` names the run dir they are+ published into: the run carries that name and path, never the staging folder's."""+ run_dir = run_dir or out_dircell_w, cell_h = cellframes_root = out_dir / "frames"frames_root.mkdir(parents=True, exist_ok=True)@@ -240,7 +247,7 @@ def write_run("version": 1,"kind": "sprite-gen-request","engine": "component-row",- "character": {"id": out_dir.name, "description": f"unpacked from atlas ({layout_source})"},+ "character": {"id": run_dir.name, "description": f"unpacked from atlas ({layout_source})"},"cell": {"shape": "rect" if cell_w != cell_h else "square", "width": cell_w, "height": cell_h, "size": cell_w, "safe_margin": 0},"chroma_key": provenance.get("chroma_key", {"name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255]}),"states": request_states,@@ -248,7 +255,7 @@ def write_run(atomic_write_text(out_dir / "sprite-request.json", json.dumps(request, ensure_ascii=False, indent=2) + "\n")atomic_write_text(frames_root / "frames-manifest.json",- json.dumps({"ok": True, "engine": "component-row", "run_dir": str(out_dir), "cell": request["cell"], "rows": manifest_rows, "errors": [], "warnings": []}, ensure_ascii=False, indent=2) + "\n",+ json.dumps({"ok": True, "engine": "component-row", "run_dir": str(run_dir), "cell": request["cell"], "rows": manifest_rows, "errors": [], "warnings": []}, ensure_ascii=False, indent=2) + "\n",)source_doc = {"version": 1,@@ -267,7 +274,7 @@ def import_pngs(out_dir: Path, png_paths: list[Path], state_name: str, labels: ldef import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str, Any] | None = None,- base_src: Path | None = None) -> dict[str, Any]:+ base_src: Path | None = None, run_dir: Path | None = None) -> dict[str, Any]:"""Import separate PNGs as one or more curator rows (states).groups: [{"name": str, "paths": [Path], "labels": [str], "refs": [Path]}] —@@ -279,7 +286,10 @@ def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str생성 재료 `<role>-<name>.png` → `references/imported/<state>/` (상태별 생성 재료칩). 역할(anchor/basis/guide) 해석은 serve_curation `_state_refs` 가 파일명에서단독 수행한다 (여긴 파일명 보존 복사만 — 역할 파싱 SSoT 이원화 금지).++ `run_dir` 는 out_dir(스테이징)을 내놓을 런 폴더 — 런은 그 이름과 경로를 단다, 스테이징 폴더의 것이 아니라."""+ run_dir = run_dir or out_dirloaded: list[tuple[dict[str, Any], list[Image.Image]]] = []cell_w = 0cell_h = 0@@ -337,7 +347,7 @@ def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str"version": 1,"kind": "sprite-gen-request","engine": "component-row",- "character": {"id": out_dir.name, "description": f"imported PNG set from {first_dir}"},+ "character": {"id": run_dir.name, "description": f"imported PNG set from {first_dir}"},"cell": {"shape": "square" if cell_w == cell_h else "rect", "width": cell_w, "height": cell_h, "size": cell_w, "safe_margin": 0},"chroma_key": {"name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255]},"states": request_states,@@ -347,7 +357,7 @@ def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[stratomic_write_text(out_dir / "sprite-request.json", json.dumps(request, ensure_ascii=False, indent=2) + "\n")atomic_write_text(out_dir / "frames" / "frames-manifest.json",- json.dumps({"ok": True, "engine": "component-row", "run_dir": str(out_dir), "cell": request["cell"],+ json.dumps({"ok": True, "engine": "component-row", "run_dir": str(run_dir), "cell": request["cell"],"rows": manifest_rows, "errors": [], "warnings": []}, ensure_ascii=False, indent=2) + "\n",)atomic_write_text(@@ -363,17 +373,47 @@ 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 _new_staging(out_dir: Path) -> Path:- """A fresh empty staging dir beside out_dir. The run is built here first, then- published atomically, so a failed/partial build never touches the prior run."""- staging = out_dir.parent / f".{out_dir.name}.sg-staging"- if staging.exists():- shutil.rmtree(staging)- staging.mkdir(parents=True)- return staging+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."""+ for flag, given in inputs.items():+ if given is None:+ continue+ path = Path(given).expanduser().resolve()+ 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)")+ if inside_folder(out_dir, path):+ raise SystemExit(f"--out-dir lies inside {flag}: {out_dir} (a run is never written into its input)")+++def _build_and_publish(out_dir: Path, build: Callable[[Path], dict[str, Any]]) -> dict[str, Any]:+ """Make the run dir, take its single-writer lock, build the run into a staging folder of this+ run's own beside it (`.<out>.<pid>-<random>.sg-staging`, a new name, so a folder of the old fixed+ name — an input or another run's — is never touched), then publish it over out_dir. A failed or+ invalid build leaves the prior run intact; the staging folder is the only thing beside out_dir the+ run deletes. Called once every input is read and checked, so a refusal has made nothing."""+ try:+ out_dir.mkdir(parents=True, exist_ok=True)+ except OSError as exc:+ raise SystemExit(f"cannot create run dir next to the input: {out_dir}\n {exc}\n pass --out-dir <writable path> to choose another location")+ acquire_run_dir_lock(out_dir, "unpack_atlas_run")+ staging = new_stage(out_dir, ".sg-staging")+ try:+ result = build(staging)+ _publish_run(staging, out_dir)+ finally:+ shutil.rmtree(staging, ignore_errors=True)+ return result-_PUBLISH_BACKUP = ".sg-backup"+_PUBLISH_BACKUP = "sg-backup" # the in-place backup is `.sg-backup.<pid>-<random>` (runio.new_stage)def _publish_run(staging: Path, out_dir: Path) -> None:@@ -385,16 +425,15 @@ def _publish_run(staging: Path, out_dir: Path) -> None:concurrent writer's `acquire_run_dir_lock(out_dir)` always finds the held lock andblocks (runio single-writer contract holds across the whole publish). On an I/O failurethe swap rolls back to the prior run byte-intact (Atomicity: succeed or roll back).+ The backup is a new folder of this publish's own, so a `.sg-backup` already in the prior run+ is prior content like any other: moved aside, restored by a rollback, replaced on success.Called only after a successful build."""- reserved = {LOCK_FILENAME, _PUBLISH_BACKUP}- backup = out_dir / _PUBLISH_BACKUP# publish_guard (exclusive) blocks concurrent readers (serve_curation read_guard) for# the whole swap, so a serving /api/run never observes the half-published state# (reader isolation — a reader sees the complete prior run or the complete new run).with publish_guard(out_dir):- if backup.exists():- shutil.rmtree(backup)- backup.mkdir()+ backup = new_stage(out_dir / _PUBLISH_BACKUP, "")+ reserved = {LOCK_FILENAME, backup.name}moved: list[str] = []phase1_done = Falsetry:@@ -456,14 +495,11 @@ def _run(args: argparse.Namespace):out_dir = base.parent / f"{base.stem}-curator"else:raise SystemExit("need one of --pngs-dir / --atlas / --manifest (or pass --out-dir)")+ out_dir = out_dir.resolve() # a link publishes where it points; inputs are compared with the real run dir+ _refuse_overlap({"--pngs-dir": args.pngs_dir, "--atlas": args.atlas, "--manifest": args.manifest}, out_dir)if out_dir.exists() and any(out_dir.iterdir()) and not args.force:raise SystemExit(f"out-dir not empty: {out_dir} (use --force)")- try:- out_dir.mkdir(parents=True, exist_ok=True)- except OSError as exc:- raise SystemExit(f"cannot create run dir next to the input: {out_dir}\n {exc}\n pass --out-dir <writable path> to choose another location")- acquire_run_dir_lock(out_dir, "unpack_atlas_run")# --pngs-dir: import a folder of separate PNGs (e.g. a furniture set).# 하위폴더가 있으면 각 하위폴더가 큐레이터 줄(state) 하나가 된다 —@@ -536,12 +572,8 @@ def _run(args: argparse.Namespace):# 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# invalid) leaves the prior run intact — never clear-then-fail.- staging = _new_staging(out_dir)- try:- result = import_png_groups(staging, groups, iso, base_src=base_src)- _publish_run(staging, out_dir)- finally:- shutil.rmtree(staging, ignore_errors=True)+ result = _build_and_publish(+ out_dir, lambda staging: import_png_groups(staging, groups, iso, base_src=base_src, run_dir=out_dir))result["ok"] = Trueresult["out_dir"] = str(out_dir)print(json.dumps(result, ensure_ascii=False, indent=2))@@ -586,14 +618,13 @@ def _run(args: argparse.Namespace):states[i]["name"] = nameprovenance["atlas"] = str(atlas_path)+ if not args.atlas:+ _refuse_overlap({"the atlas the manifest names": Path(atlas_path)}, out_dir)# atomic rebuild (see --pngs-dir): atlas/layout resolution above is read-only; build# into staging, then publish over out_dir so a failed rebuild leaves the prior run intact.- staging = _new_staging(out_dir)- try:- result = write_run(staging, atlas, states, cell, meta, layout_source, provenance)- _publish_run(staging, out_dir)- finally:- shutil.rmtree(staging, ignore_errors=True)+ result = _build_and_publish(+ out_dir, lambda staging: write_run(staging, atlas, states, cell, meta, layout_source, provenance,+ run_dir=out_dir))result["ok"] = Trueresult["out_dir"] = str(out_dir)print(json.dumps(result, ensure_ascii=False, indent=2))diff --git a/sprite_gen/spec/runio.py b/sprite_gen/spec/runio.pyindex a17155a..bf4b35f 100644--- a/sprite_gen/spec/runio.py+++ b/sprite_gen/spec/runio.py@@ -15,6 +15,10 @@ example Claude Code and the Codex app driving the skill in parallel):atlas/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+ 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 curationsurface writes it with the same atomic replace, and the compose scripts read one@@ -33,6 +37,7 @@ import atexitimport contextlibimport jsonimport os+import secretsimport sysimport tempfileimport time@@ -137,6 +142,31 @@ def relative_posix(path: PurePath, start: PurePath) -> str:return path.relative_to(start).as_posix()+def same_folder(a: Path, b: Path) -> bool:+ """같은 폴더(또는 파일)인가 — 장치·inode 로 본다. 링크로 돌아 들어와도, 대소문자를 가리지 않는 볼륨에서 철자만+ 달라도 같다. 둘 중 하나가 아직 없으면 같지 않다."""+ return a.exists() and b.exists() and a.samefile(b)+++def inside_folder(path: Path, folder: Path) -> bool:+ """`path` 가 `folder` 안에 드는가 — 조상 가운데 `folder` 와 같은 폴더가 있다. `path` 는 아직 없어도 된다."""+ return any(same_folder(parent, folder) for parent in path.parents)+++def new_stage(out: Path, suffix: str) -> Path:+ """`out` 옆에 이 실행만의 빈 임시 폴더 `.<out>.<pid>-<random><suffix>` — 같은 볼륨이라 다 쓴 뒤 rename 으로+ 내놓는다. 이름이 이미 있으면(입력이든 다른 실행의 것이든) 그 폴더는 건드리지 않고 다른 이름을 고른다.+ mkdtemp(0700)가 아니라 mkdir 이라 내놓은 폴더가 보통 폴더 권한을 갖는다."""+ for _ in range(100):+ stage = out.parent / f".{out.name}.{os.getpid()}-{secrets.token_hex(4)}{suffix}"+ try:+ stage.mkdir()+ except FileExistsError:+ continue+ return stage+ raise SystemExit(f"{out.parent}: no free name for a staging folder beside {out.name}")++def _pid_alive(pid: int) -> bool:try:os.kill(pid, 0)