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): what `sprite-gen unpack-atlas` finds in --pngs-dir is an input as well — every frame, _base image, _refs PNG and meta.json it reads, and every folder it reads one from, is compared with the run dir by real path and file identity once all of it is found, so a link there into --out-dir, or a linked group folder that holds it, is refused before anything is made, --force or not

Soohong Kim2217bb60ff6d
diff --git a/docs/run-contract.md b/docs/run-contract.md
index 0d6a607..7e31422 100644
--- a/docs/run-contract.md
+++ b/docs/run-contract.md
@@ -393,10 +393,13 @@ A **failed or invalid** re-import (e.g. a bad `_refs` role) leaves the prior run
succeeds or rolls back). The publish holds the run-dir single-writer lock in place
throughout, 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
+**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
+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
the run dir and the prior content is moved aside into a backup folder of its own inside it
diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.py
index 8985c81..3959557 100644
--- a/sprite_gen/frames/unpack_atlas.py
+++ b/sprite_gen/frames/unpack_atlas.py
@@ -393,6 +393,15 @@ def _refuse_overlap(inputs: dict[str, Path | None], out_dir: Path) -> None:
raise SystemExit(f"--out-dir lies inside {flag}: {out_dir} (a run is never written into its input)")
+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."""
+ 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)}
+
+
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
@@ -569,6 +578,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.
+ _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
# invalid) leaves the prior run intact — never clear-then-fail.