Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

gen-set: a row is finished only when its report reads back; pipelines are catalog objects

Soohong Kim5fceef694fc1
diff --git a/docs/README.md b/docs/README.md
index 9a9eee2..8774b6c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -30,7 +30,7 @@ flowchart LR
| **A · atlas rows** — one still becomes a runtime sprite sheet | [run-contract.md](run-contract.md) | `prepare` → `gen` / `gen-set` → `extract` → `curation` → `compose-atlas` |
| **B · video → loop** — one still becomes transparent motion loops | [video-pipeline.md](video-pipeline.md) | `video-canvas` → `video` → `video-frames` → `video-loop`, `video-set` |
| **C · utilities** — imported images in, clean cuts out | [sheet-slicing.md](sheet-slicing.md) | `cutout`, `slice-sheet`, `unpack-atlas` |
-| **D · post-processing** — finished sheets, refined | [recolor.md](recolor.md) | `recolor`, `compose-layers`, breathing (compose), `export-pngs`, `export-aseprite` |
+| **D · post-processing** — finished sheets, refined | [recolor.md](recolor.md) | `recolor`, `recolor-palette`, `compose-layers`, breathing (compose), `export-pngs`, `export-aseprite` |
`sprite-gen --help` prints the same four pipelines and every verb grouped by domain; the
grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.py
index b35792f..e82718a 100644
--- a/sprite_gen/_modules.py
+++ b/sprite_gen/_modules.py
@@ -67,6 +67,20 @@ DOMAIN_ORDER = [d for d, _ in DOMAINS]
DOMAIN_TITLE = dict(DOMAINS)
+# The four pipelines — first-class objects. The CLI help, the docs index and the README
+# pipeline table are checked against THIS list; a verb named here must exist as a verb.
+PIPELINES: list[dict[str, object]] = [
+ {"key": "A", "name": "atlas rows", "verbs": ["prepare", "gen", "gen-set", "extract", "curation", "compose-atlas"],
+ "chain": "prepare → gen (or gen-set) → extract → curation → compose-atlas", "doc": "docs/run-contract.md"},
+ {"key": "B", "name": "video → loop", "verbs": ["video-canvas", "video", "video-frames", "video-loop", "video-set"],
+ "chain": "video-canvas → video → video-frames → video-loop, or video-set", "doc": "docs/video-pipeline.md"},
+ {"key": "C", "name": "utilities", "verbs": ["cutout", "slice-sheet", "unpack-atlas"],
+ "chain": "cutout · slice-sheet · unpack-atlas (each stands alone)", "doc": "docs/sheet-slicing.md"},
+ {"key": "D", "name": "post-processing", "verbs": ["recolor", "recolor-palette", "compose-layers", "export-pngs", "export-aseprite"],
+ "chain": "recolor · compose-layers · export-pngs · export-aseprite", "doc": "docs/recolor.md"},
+]
+
+
def domain_of(module_path: str) -> str:
"""Domain of a fully-qualified module path (`sprite_gen.video.loop` → `video`).
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index 039bdfc..3db04f3 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -369,18 +369,11 @@ def command_domains() -> dict[str, list[str]]:
return {d: verbs for d, verbs in groups.items() if verbs}
-PIPELINES = (
- ("A atlas rows", "prepare → gen (or gen-set) → extract → curation → compose-atlas", "docs/run-contract.md"),
- ("B video → loop", "video-canvas → video → video-frames → video-loop, or video-set", "docs/video-pipeline.md"),
- ("C utilities", "cutout · slice-sheet · unpack-atlas (each stands alone)", "docs/sheet-slicing.md"),
- ("D post-processing", "recolor · compose-layers · migrate-breathe · export-*", "docs/recolor.md"),
-)
-
-
def _help_description() -> str:
lines = ["sprite-gen — 2D sprite pipelines as one CLI. Every verb works alone or as a pipeline stage.", "", "pipelines:"]
- for label, chain, doc in PIPELINES:
- lines.append(f" {label:<20} {chain} ({doc})")
+ for pipe in _modules.PIPELINES: # the catalog, not a copy of it
+ label = f"{pipe['key']} {pipe['name']}"
+ lines.append(f" {label:<20} {pipe['chain']} ({pipe['doc']})")
lines += ["", "tools by domain:"]
width = max(len(v) for v in COMMANDS)
for domain, verbs in command_domains().items():
diff --git a/sprite_gen/gen/gen_set.py b/sprite_gen/gen/gen_set.py
index 78e5f67..8e96cdd 100644
--- a/sprite_gen/gen/gen_set.py
+++ b/sprite_gen/gen/gen_set.py
@@ -72,6 +72,20 @@ def _stages(request: dict[str, Any], states: list[str]) -> list[list[str]]:
return [stage for stage in (first, second) if stage]
+def read_report(report: Path) -> tuple[dict[str, Any] | None, str | None]:
+ """Parse a row's gen report. Returns (report, None) or (None, why) — a missing,
+ unreadable or provider-less report is never treated as a finished row."""
+ if not report.is_file():
+ return None, "report missing"
+ try:
+ data = json.loads(report.read_text(encoding="utf-8"))
+ except (OSError, ValueError) as exc:
+ return None, f"report unreadable ({exc.__class__.__name__})"
+ if not isinstance(data, dict) or not data.get("provider"):
+ return None, "report has no provider — not a finished gen report"
+ return data, None
+
+
def run_gen_cli(prompt_file: Path, out: Path, refs: list[Path], report: Path, *, provider: str | None, model: str | None, log: Path) -> int:
import subprocess
@@ -111,10 +125,15 @@ def run_item(
raise SystemExit(f"prompt missing: {prompt_file} — run `sprite-gen prepare` first")
if not guide.is_file():
raise SystemExit(f"layout guide missing: {guide} — run `sprite-gen prepare` first")
- if out.is_file() and report.is_file() and not force:
- result["reused"] = True
- result["ok"] = True
- return result
+ if out.is_file() and not force:
+ prior, why = read_report(report)
+ if prior is not None:
+ result["reused"] = True
+ result["provider"] = prior.get("provider")
+ result["provider_resolved_from"] = prior.get("provider_resolved_from")
+ result["ok"] = True
+ return result
+ result["regenerated_because"] = why # the row image exists but its report does not prove it — generate again, say why
identity = anchor_mod.identity_ref(run_dir, state, request, quiet=True)
refs = [identity, guide]
result["refs"] = [str(r) for r in refs]
@@ -123,7 +142,12 @@ def run_item(
if rc != 0 or not out.is_file():
tail = log.read_text(encoding="utf-8", errors="replace").strip().splitlines()[-3:] if log.exists() else []
raise SystemExit(f"gen exited {rc}; " + (" | ".join(tail) if tail else f"see {log}"))
- gen_report = json.loads(report.read_text(encoding="utf-8")) if report.is_file() else {}
+ gen_report, why = read_report(report)
+ if gen_report is None:
+ for partial in (out, report):
+ if partial.exists():
+ partial.unlink()
+ raise SystemExit(f"gen exited 0 but its {why}; the row and the report were removed so the next run regenerates")
result["provider"] = gen_report.get("provider")
result["provider_resolved_from"] = gen_report.get("provider_resolved_from")
if gen_report.get("provider_fallback"):
diff --git a/tests/gen/test_gen_set.py b/tests/gen/test_gen_set.py
index 1cf84fe..e51201c 100644
--- a/tests/gen/test_gen_set.py
+++ b/tests/gen/test_gen_set.py
@@ -141,3 +141,38 @@ def test_run_gen_cli_invokes_the_cli_gen_verb(tmp_path: Path, monkeypatch) -> No
cmd = captured["cmd"]
assert cmd[1:4] == ["-m", "sprite_gen.cli", "gen"]
assert cmd.count("--ref") == 2 and "--provider" in cmd and "--model" not in cmd
+
+
+def _broken_report_runner(record: list | None = None):
+ def runner(prompt_file: Path, out: Path, refs: list[Path], report: Path, *, provider, model, log) -> int:
+ if record is not None:
+ record.append(out.name)
+ log.write_text("fake gen\n", encoding="utf-8")
+ Image.new("RGB", (256, 64), (255, 0, 255)).save(out)
+ report.write_text("{not json", encoding="utf-8")
+ return 0
+ return runner
+
+
+def test_gen_set_broken_report_is_a_named_failure_and_never_reused(tmp_path: Path) -> None:
+ """Validator finding 2026-09-09: a PNG plus an unreadable report used to crash the batch
+ (JSONDecodeError, no table) and the next run reused the row on file existence alone."""
+ run_dir = _prepare(tmp_path)
+ first = gen_set.run_set(run_dir=run_dir, states=["idle"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_broken_report_runner())
+ assert first["failed"] == ["idle"] and "report unreadable" in first["items"][0]["error"]
+ assert not (run_dir / "raw" / "idle.png").exists(), "no half state: the unproven row is removed"
+ assert "FAIL: gen exited 0 but its report unreadable" in (run_dir / "reports" / "gen-set" / "table.md").read_text()
+ # second run must generate again, not reuse
+ calls: list = []
+ second = gen_set.run_set(run_dir=run_dir, states=["idle"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_fake_runner(record=calls))
+ assert calls == [("idle.png", ["base-source.png", "idle.png"], "codex")] and second["ok"] == 1 and second["items"][0].get("reused") is None
+
+
+def test_gen_set_row_without_a_real_report_is_regenerated_with_a_reason(tmp_path: Path) -> None:
+ run_dir = _prepare(tmp_path)
+ (run_dir / "raw").mkdir(exist_ok=True)
+ Image.new("RGB", (256, 64), (255, 0, 255)).save(run_dir / "raw" / "walk.png") # a row image from nowhere, no report
+ calls: list = []
+ payload = gen_set.run_set(run_dir=run_dir, states=["walk"], provider="codex", model=None, concurrency=1, force=False, gen_runner=_fake_runner(record=calls))
+ item = payload["items"][0]
+ assert len(calls) == 1 and item["ok"] and item.get("reused") is None and item["regenerated_because"] == "report missing"
diff --git a/tests/packaging/test_cli_taxonomy.py b/tests/packaging/test_cli_taxonomy.py
index 87403d0..1698ce2 100644
--- a/tests/packaging/test_cli_taxonomy.py
+++ b/tests/packaging/test_cli_taxonomy.py
@@ -40,4 +40,30 @@ def test_help_lists_each_verb_once_under_its_domain() -> None:
assert f"[{domain}]" in out
for verb in verbs:
assert len(re.findall(rf"(?m)^\s+{re.escape(verb)}\s{{2,}}", out)) == 1, verb
- assert "pipelines:" in out and "A atlas rows" in out and "B video" in out
+ for pipe in _modules.PIPELINES:
+ assert f"{pipe['key']} {pipe['name']}" in out and str(pipe["doc"]) in out
+
+
+def test_pipeline_catalog_names_real_verbs_and_docs() -> None:
+ """Validator finding 2026-09-09: the pipeline list was a hand-written tuple in cli.py.
+ It is now a catalog in _modules; every verb it names is a real verb, every doc exists,
+ and both README pipeline tables mention each pipeline's doc."""
+ from pathlib import Path
+
+ root = Path(cli.__file__).resolve().parents[1]
+ keys = [p["key"] for p in _modules.PIPELINES]
+ assert keys == ["A", "B", "C", "D"]
+ for pipe in _modules.PIPELINES:
+ for verb in pipe["verbs"]:
+ assert verb in cli.COMMANDS, (pipe["key"], verb)
+ assert (root / str(pipe["doc"])).is_file(), pipe["doc"]
+ index = (root / "docs" / "README.md").read_text(encoding="utf-8")
+ readme = (root / "README.md").read_text(encoding="utf-8")
+ for pipe in _modules.PIPELINES:
+ doc_name = str(pipe["doc"]).split("/")[-1]
+ row = next((l for l in index.splitlines() if l.startswith(f"| **{pipe['key']} ·")), None)
+ assert row is not None, f"docs/README.md has no pipeline row for {pipe['key']}"
+ assert doc_name in row, (pipe["key"], "entry doc missing from its index row")
+ for verb in pipe["verbs"]:
+ assert f"`{verb}`" in row, (pipe["key"], verb, "missing from the index pipeline row")
+ assert any(l.startswith(f"| **{pipe['key']} ·") and doc_name in l for l in readme.splitlines()), (pipe["key"], "README pipeline row")