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.mdindex 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; thegrouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.pyindex 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.pyindex 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.pyindex 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 whyidentity = 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.pyindex 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) -> Nocmd = 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.pyindex 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 outfor 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")