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(prepare): sprite-gen prepare --request keeps the request's style

Soohong Kim3b9c55ff83f4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d83f6a4..b68e174 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
+- **Fix: `sprite-gen prepare --request` keeps the request's `style`.** The subcommand declared its own copy of prepare's options, with `--style` defaulting to the default style sentence and `--cell-size` to 256, so a flag nobody gave counted as given: the request's `style` was replaced by the default sentence under a note that `--style, --cell-size` were given both ways (`scripts/prepare_sprite_run.py` and `prepare.run` were right). The subcommand now takes prepare's own declaration (`prepare.add_arguments`), which also gives it `--directions` and `--mirror`, missing until now. A request with no style and no cell still gets the default sentence and 256. Test: `tests/gen/test_flags_over_spec.py` (through `sprite-gen prepare`: a request alone keeps its style and cell with no note, a given `--style` wins and says so, the subcommand takes every option prepare declares).
- **Behavior change: `pixel-draw` runs on your Claude subscription first, and on `ANTHROPIC_API_KEY` only without one** — the order `codex` and `grok` keep. When `claude auth status` says Claude Code is signed in with a subscription (`claude.ai` or `oauth_token`), every call — the drawings, the row repairs, the pick — goes through the unmodified `claude` binary in print mode, from an empty directory, with no tool, no session written and no CLAUDE.md, hook, skill, plugin or MCP server loaded, and costs nothing per call: `report.json` says `auth_source: claude-login`, each call's `mode` is `subscription` and its `cost_usd` `0`, its usage kept. The child never sees `ANTHROPIC_API_KEY`, which print mode would use instead of the login. Without a subscription login the run uses the key as before, billed per call and said on stderr; with neither it is refused naming both, before the run folder is made. A login that refuses a call, has expired or has reached its usage limit fails the call; the run never switches to the key on its own. `--batch` is the API's Message Batches and runs on the key even when signed in. An answer the binary continues past the output cap is read whole from every message, not from its `result`, which holds only the last part; one it cannot finish is read as `stop_reason: max_tokens`, so the one redraw one effort lower happens on either route. One call may take up to `SPRITE_GEN_CLAUDE_CALL_TIMEOUT_SECONDS` (1800). When candidates ask at once, none of their requests leaves before the billing line has been printed. `report.json`'s `auth_source` is what the calls ran on by their records, `mixed` (with `auth_sources`) for a run resumed under the other credential. A `--resume` that reads every call back no longer prints the billing line ([pixel-draw](docs/pixel-draw.md#which-credential-a-call-runs-on)).
- **Behavior change: every metered call says so on the terminal, and every report names what a call ran on.** How codex is signed in is one reading, `codex_provider.codex_login` (`codex login status`), for the default provider resolution, `gen --provider codex`, the codex facing check and `workflow`: a codex signed in with an API key used to run with no word about it and the workflow called it a subscription; it now prints the per-call charge line before `codex exec` runs, its report records `extra.auth_source: codex-api-key` (`codex-login` on ChatGPT), and `workflow` asks to confirm the API credit. A codex that is not signed in is refused with the reason before it runs. `gen-set` and `video-set` keep each item's output in its log, but a child's billing line and a default provider switch now also print on the terminal as they happen (`base.run_logged`), each `gen-set` row records `auth_source`, and each `video-set` clip result too. `sound` prints the same billing line as every other metered route (it printed its own) and its receipt records `auth_source`. One function reads a provider key from the environment (`base.env_api_key`: a key, none, or a refusal of an empty one) for Anthropic, OpenAI, xAI and ElevenLabs; one function says what to do when xAI rejects a credential (`xai.rejected_fix`), so `gen --provider grok` now gives the same `grok models` refresh as `video`. `workflow` probes a provider once for its images and videos (they share one credential) and asks the API-credit question by that provider's name rather than always about Grok video. Docs: the credential table in the README, grok's `XAI_API_KEY` route in the help and SKILL.md, the sound billing line, `SPRITE_GEN_GEN_TIMEOUT_SECONDS` and `SPRITE_GEN_CLAUDE_READ_TIMEOUT_SECONDS`, and `gen-set --provider` (`codex` or `grok`).
- **Tests** — `tests/gen/test_claude_login.py` (the login before the key, the key only without a login, neither refused naming both, a batch on the key without asking the login, an unreadable status refused rather than read as no login, the child's environment without a key or the calling session, a message mapped onto the binary's flags and stdin with its image and schema, the stream-json answer, a cut answer read as max_tokens, a refused or limited login an error and not a switch to the key, no result, a timeout and a missing binary), the subscription, batch and read-back cases in `tests/gen/test_pixel_draw.py`, and `gen.base.env_api_key` in `tests/gen/test_gen.py`; `tests/gen/test_codex_login.py` (ChatGPT, an API key and not signed in; the default resolution, `generate` and `workflow` read the same login; an API-key login announces the charge and records it), `base.run_logged` in `tests/gen/test_gen.py`, the ElevenLabs billing line and key refusals in `tests/audio/test_sound.py`.
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index e96dda7..0607f80 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -34,8 +34,6 @@ from sprite_gen.effects import recolor, shadow
from sprite_gen.scene import render, inspect_scene
from sprite_gen.serve import serve_compose, serve_curation
from sprite_gen.spec import migrate_breathe, migrate_request
-from sprite_gen.gen.prepare import BODY_PLAN_HELP, STYLE_DEFAULT, _outline_config
-from sprite_gen.spec.subject import SUBJECTS
from sprite_gen.workflow import guide, preferences
@@ -62,40 +60,6 @@ def _parse_grid(value: str) -> tuple[int, int]:
return int(cols), int(rows)
-def _add_prepare(p: argparse.ArgumentParser) -> None:
- p.add_argument("--out-dir", required=True, type=Path)
- p.add_argument("--character-id", required=True)
- p.add_argument("--base-image", type=Path)
- p.add_argument("--description", default="")
- p.add_argument("--style", default=STYLE_DEFAULT)
- p.add_argument("--subject", choices=SUBJECTS, default=None,
- help="what the run draws: character (default) or effect — "
- "sets validation defaults like the sparse-frame floor")
- p.add_argument("--cell-size", type=int, default=256)
- p.add_argument("--cell-width", type=int)
- p.add_argument("--cell-height", type=int)
- p.add_argument("--safe-margin", type=int, default=None, help="absolute px override; default is 9.4%% of the cell dimension, floored")
- p.add_argument("--chroma-key", default="auto", help="auto or #RRGGBB")
- p.add_argument("--fit-resample", choices=["lanczos", "nearest", "kcentroid"], default=None)
- p.add_argument("--fit-align-x", choices=["bbox-center", "centroid", "foot-centroid", "alpha-centroid"], default=None)
- p.add_argument("--fit-align-y", choices=["center", "bottom"], default=None)
- p.add_argument("--fit-ground-frames", action=argparse.BooleanOptionalAction, default=None)
- p.add_argument("--fit-pixel-unfake", action=argparse.BooleanOptionalAction, default=None)
- # 은퇴한 이름. 조용한 별칭으로 살려두지 않는다 — 두 이름이 공존하면 문서와 스크립트가
- # 갈라진다. 대신 무엇으로 바뀌었는지 말하며 죽는다 (숨은 인자라 --help 를 어지럽히지 않음).
- p.add_argument("--fit-pixel-perfect", "--no-fit-pixel-perfect", dest="_retired_pp",
- action="store_true", help=argparse.SUPPRESS)
- p.add_argument("--fit-logical-height", type=int, default=None)
- p.add_argument("--fit-palette-size", type=int, default=None)
- p.add_argument("--fit-detail-bias", action=argparse.BooleanOptionalAction, default=None)
- p.add_argument("--fit-outline", type=_outline_config, default=None, metavar="{on,off,STRENGTH}")
- p.add_argument("--fit-pitch-hint", type=int, default=None)
- p.add_argument("--body-plan", action="append", default=[], metavar="PLAN | FIGURE=PLAN", help=BODY_PLAN_HELP)
- p.add_argument("--request", type=Path)
- p.add_argument("--request-json")
- p.add_argument("--force", action="store_true")
-
-
def _add_extract(p: argparse.ArgumentParser) -> None:
p.add_argument("--run-dir", required=True, type=Path)
p.add_argument("--states", default="all")
@@ -258,7 +222,7 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
"scene-inspect": ("Measure scene loops, viewport clipping and repeated joins.", inspect_scene.add_arguments, inspect_scene.run),
"workflow": ("Resolve image/sprite choices, check access and guide the next conversation step.", guide.add_arguments, guide.run),
"defaults": ("Show, explicitly save or clear the defaults for each user workflow.", preferences.add_arguments, preferences.run),
- "prepare": ("Prepare a sprite-gen component-row run.", _add_prepare, prepare.run),
+ "prepare": ("Prepare a sprite-gen component-row run.", prepare.add_arguments, prepare.run),
"extract": ("Extract component-row sprite strips into clean RGBA frames.", _add_extract, extract.run),
"compose-atlas": (
"Compose component-row frames into a game atlas and runtime manifest.",
diff --git a/sprite_gen/gen/prepare.py b/sprite_gen/gen/prepare.py
index a3ddb96..1295fce 100644
--- a/sprite_gen/gen/prepare.py
+++ b/sprite_gen/gen/prepare.py
@@ -999,8 +999,10 @@ def _outline_config(value: str):
return strength
-def _build_parser() -> argparse.ArgumentParser:
- parser = argparse.ArgumentParser(description=__doc__)
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+ """prepare's arguments: one declaration for `sprite-gen prepare`, `scripts/prepare_sprite_run.py`
+ and `run(**kwargs)`. A flag the caller does not give stays None, so it never reads as given over
+ the key a request sets (`request_with_flags`)."""
parser.add_argument("--out-dir", required=True, type=Path)
parser.add_argument("--character-id", required=True)
parser.add_argument("--base-image", type=Path)
@@ -1033,6 +1035,11 @@ def _build_parser() -> argparse.ArgumentParser:
parser.add_argument("--request", type=Path)
parser.add_argument("--request-json")
parser.add_argument("--force", action="store_true")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ add_arguments(parser)
return parser
diff --git a/tests/gen/test_flags_over_spec.py b/tests/gen/test_flags_over_spec.py
index 1e683a9..3624616 100644
--- a/tests/gen/test_flags_over_spec.py
+++ b/tests/gen/test_flags_over_spec.py
@@ -11,6 +11,7 @@ from pathlib import Path
import pytest
+from sprite_gen import cli
from sprite_gen.gen import pixel_draw, prepare
from sprite_gen.gen.base import flags_over_spec
@@ -84,6 +85,36 @@ def test_a_request_alone_or_a_flag_alone_says_nothing_and_keeps_its_value(tmp_pa
assert "given both" not in capsys.readouterr().err
+def _sprite_gen_prepare(tmp_path: Path, request: dict, *flags: str) -> dict:
+ out = tmp_path / "run"
+ assert cli.main(["prepare", "--out-dir", str(out), "--character-id", "hero",
+ "--request-json", json.dumps(request), *flags]) == 0
+ return json.loads((out / "sprite-request.json").read_text(encoding="utf-8"))
+
+
+def test_sprite_gen_prepare_keeps_a_request_it_was_given_no_flag_for(tmp_path, capsys):
+ """`sprite-gen prepare` declared its own --style and --cell-size with defaults, so a request's style
+ was replaced by the default sentence under a note naming flags nobody gave."""
+ emitted = _sprite_gen_prepare(tmp_path, {"states": STATES, "style": "ink wash", "cell": {"size": 128}})
+ assert emitted["style"] == "ink wash" and emitted["cell"]["width"] == 128
+ assert "given both" not in capsys.readouterr().err
+
+
+def test_sprite_gen_prepare_lets_a_given_flag_win_and_says_so(tmp_path, capsys):
+ emitted = _sprite_gen_prepare(tmp_path, {"states": STATES, "style": "ink wash"}, "--style", "flat pixel")
+ assert emitted["style"] == "flat pixel"
+ assert "[prepare] --style given both as a flag and in --request-json: the flag wins" in capsys.readouterr().err
+
+
+def test_sprite_gen_prepare_takes_every_option_prepare_declares():
+ """One declaration: the subcommand had lost --directions and --mirror."""
+ def options(parser: argparse.ArgumentParser) -> set[str]:
+ return {o for action in parser._actions for o in action.option_strings}
+
+ sub = next(a for a in cli._build_parser()._actions if isinstance(a, argparse._SubParsersAction))
+ assert options(sub.choices["prepare"]) == options(prepare._build_parser())
+
+
def test_a_request_subject_is_carried_and_no_note_says_it_was_dropped(tmp_path, capsys):
"""prepare reads `subject` off the request; its note listed it among the keys it drops."""
emitted = _prepare(tmp_path, {"states": STATES, "subject": "effect"})