Skip to content

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

22.0 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""A call that names no provider runs on codex. When codex cannot run — no login, or the codex usage of the
account used up — it turns into what the user chose for that (`sprite-gen defaults save --codex-unavailable`,
SPRITE_GEN_CODEX_UNAVAILABLE): `ask` (the default) ends with one question and nothing generated, `grok` and
`openai` run with the switch said on stderr and kept in the report. A named `--provider` runs as named. A batch
verb whose child asked stops with the same question. A guided request asks the choice once and saves it.

Nothing is generated or billed here: codex's answers are the messages its source writes for its usage-limit errors
(docs/gen.md "When codex cannot run"), synthesized; OpenAI's transport is fake; grok is a painter.
"""
from __future__ import annotations

import base64
import io
import json
import os
import subprocess
import sys
import urllib.request
from pathlib import Path
from types import SimpleNamespace

import pytest
from PIL import Image

from conftest import REPO_ROOT, run_script
from http_answer import Answer
from sprite_gen import gen
from sprite_gen.cli import _build_parser
from sprite_gen.gen import base, codex_provider
from sprite_gen.video import batch
from sprite_gen.workflow import guide, preferences

# What `codex exec --json` says when the codex usage of the account is used up, as codex-rs writes it (2026-10-16):
# the Display text of the three errors codex itself classes as its usage limit, each sentence as codex's own unit
# tests pin it (codex-rs/protocol/src/error_tests.rs at rust-v0.160.1 and rust-v0.153.4).
USAGE_LIMIT_SAID = [
    # 0.160.1 writes the apostrophe as U+2019 ...
    "You’ve hit your usage limit. Upgrade to Pro (https://chatgpt.com/explore/pro), visit "
    "https://chatgpt.com/codex/settings/usage to purchase more credits or try again later.",
    # ... and 0.153.4 as an ASCII one
    "You've hit your usage limit. Try again later.",
    "Your workspace is out of credits. Ask your workspace owner to refill in order to continue.",
    "You hit your spend cap set in your workspace. Increase your spend cap to continue.",
    "Quota exceeded. Check your plan and billing details.",
    "To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus.",
]
NOT_SIGNED_IN = "codex not logged in (codex login status exit 1)"


def _cli(*args: str, env: dict[str, str] | None = None) -> subprocess.CompletedProcess[str]:
    return subprocess.run([sys.executable, "-m", "sprite_gen.cli", *args], capture_output=True,
                          encoding="utf-8", env=env, cwd=REPO_ROOT)


def _without_codex(tmp_path: Path) -> dict[str, str]:
    """The environment with a PATH that holds no `codex` (its login cannot be asked), and no Grok login or API key
    anywhere: a call that went on to another provider instead of asking would fail here, never reach one."""
    for name in ("no-codex-bin", "no-grok-home"):
        (tmp_path / name).mkdir(exist_ok=True)
    env = {key: value for key, value in os.environ.items() if key not in ("XAI_API_KEY", "OPENAI_API_KEY")}
    return {**env, "PATH": str(tmp_path / "no-codex-bin"), "GROK_HOME": str(tmp_path / "no-grok-home")}


def _choose(choice: str) -> dict:
    return preferences.save_settings(None, {}, general={"codex_unavailable": choice},
                                     expected_revision=preferences.read_settings()["revision"])


@pytest.fixture
def codex(monkeypatch, tmp_path):
    """codex signed in with ChatGPT, whose `codex exec` ends the way `state["said"]` says, as codex prints it."""
    home = tmp_path / "codex-home"
    home.mkdir()
    monkeypatch.setenv("CODEX_HOME", str(home))
    state = {"said": USAGE_LIMIT_SAID[0], "execs": 0}

    def run(cmd, **kwargs):
        if list(cmd[1:3]) == ["login", "status"]:
            return SimpleNamespace(returncode=0, stdout="Logged in using ChatGPT", stderr="")
        assert cmd[1] == "exec", cmd
        state["execs"] += 1
        said = json.dumps(state["said"], ensure_ascii=False)
        stdout = "\n".join(['{"type":"thread.started","thread_id":"t-1"}', '{"type":"turn.started"}',
                            f'{{"type":"error","message":{said}}}',
                            f'{{"type":"turn.failed","error":{{"message":{said}}}}}'])
        return SimpleNamespace(returncode=1, stdout=stdout, stderr="")

    monkeypatch.setattr(codex_provider.subprocess, "run", run)
    return state


class _Painter:
    """A provider that draws a plain PNG: grok, wherever it is reached."""

    transparency = base.TRANSPARENCY_CHROMA

    def __init__(self, name: str) -> None:
        self.name = name

    def generate(self, request, workdir):
        Image.new("RGB", (8, 8), (200, 40, 40)).save(request.raw)
        return base.ProviderRun(provider=self.name, elapsed_seconds=0.1, model=request.model)


@pytest.fixture
def made(monkeypatch):
    """The providers a call builds, in order: codex and openai are the real adapters, grok a painter."""
    names: list[str] = []
    real = gen._make_provider

    def make(name, *, keep_session):
        names.append(name)
        return _Painter(name) if name == "grok" else real(name, keep_session=keep_session)

    monkeypatch.setattr(gen, "_make_provider", make)
    return names


@pytest.fixture
def openai_api(monkeypatch):
    """OPENAI_API_KEY set and the Images endpoint answered offline: every request is kept, none leaves."""
    from sprite_gen.gen import openai_provider

    monkeypatch.setenv("OPENAI_API_KEY", "synthetic-key")
    png = io.BytesIO()
    Image.new("RGB", (8, 8), (30, 90, 200)).save(png, format="PNG")
    calls: list[urllib.request.Request] = []

    def answer(request, *, timeout):
        calls.append(request)
        return Answer({"data": [{"b64_json": base64.b64encode(png.getvalue()).decode()}]})

    monkeypatch.setattr(openai_provider.urllib.request, "urlopen", answer)
    return calls


def _codex_down(monkeypatch, reason: str = NOT_SIGNED_IN) -> None:
    monkeypatch.setattr(gen, "_codex_available", lambda: (False, reason))


# --- ask: the question, nothing generated ---------------------------------------------------------------------


def test_no_codex_login_and_nothing_chosen_ends_with_the_question_and_draws_nothing(tmp_path):
    out, report = tmp_path / "out.png", tmp_path / "out.json"
    run = _cli("gen", "--prompt", "a red apple", "--out", str(out), "--report", str(report),
               env=_without_codex(tmp_path))
    assert run.returncode == base.CODEX_UNAVAILABLE_EXIT == 75, run.stderr
    assert run.stdout == ""
    assert [line for line in run.stderr.splitlines() if line.startswith(base.CODEX_UNAVAILABLE_ASK)] != []
    question = base.asked_codex_unavailable(run.stderr)
    assert question["cause"] == "login" and question["reason"] == "codex CLI not found on PATH"
    assert question["choices"] == {"openai": "--provider openai", "grok": "--provider grok", "stop": None}
    assert list(question["choices"]) == ["openai", "grok", "stop"]  # the line's order: dict == does not see it
    assert "OpenAI API" in question["question"] and "Grok" in question["question"] and "stop" in question["question"]
    assert not out.exists() and not report.exists()


@pytest.mark.parametrize("said", USAGE_LIMIT_SAID, ids=["0.160.1", "0.153.4", "workspace-credits", "spend-cap",
                                                         "quota-exceeded", "usage-not-included"])
def test_codex_usage_used_up_and_nothing_chosen_asks_the_same_question(tmp_path, codex, made, said, capsys):
    codex["said"] = said
    with pytest.raises(base.CodexUnavailableAsk) as asked:
        gen.run(prompt="a red apple", out=tmp_path / "out.png", report=tmp_path / "out.json")
    assert asked.value.code == base.CODEX_UNAVAILABLE_EXIT and codex["execs"] == 1 and made == ["codex"]
    question = base.asked_codex_unavailable(capsys.readouterr().err)
    assert question == asked.value.question
    assert question["cause"] == "usage-limit" and question["reason"] == said
    assert not (tmp_path / "out.png").exists() and not (tmp_path / "out.json").exists()


def test_a_codex_failure_that_is_not_its_usage_limit_is_a_failure_not_a_question(tmp_path, codex, made):
    _choose("grok")
    codex["said"] = "The model is not supported."
    with pytest.raises(SystemExit) as failed:
        gen.run(prompt="a red apple", out=tmp_path / "out.png")
    assert not isinstance(failed.value, base.CodexUnavailableAsk)
    assert "The model is not supported." in str(failed.value.code)
    assert made == ["codex"]  # the choice is for codex that cannot run, not for any failure


def test_the_usage_limit_is_read_only_from_codexs_own_sentences():
    for said in USAGE_LIMIT_SAID:
        assert codex_provider.usage_limit(["Model metadata for `x` not found.", said]) == said
        # remote compaction puts its own words before the message
        assert codex_provider.usage_limit([f"Error running remote compact task: {said}"]) is not None
    for other in ("The model is not supported.", "Selected model is at capacity. Please try a different model.",
                  "usage limit", "exceeded retry limit, last status: 429 Too Many Requests"):
        assert codex_provider.usage_limit([other]) is None


# --- grok and openai: run, said and reported ------------------------------------------------------------------


def test_saved_grok_runs_grok_and_says_whose_choice_it_was(tmp_path, monkeypatch, made, capsys):
    _choose("grok")
    _codex_down(monkeypatch)
    report = tmp_path / "out.json"
    assert gen.run(prompt="a red apple", out=tmp_path / "out.png", report=report) == 0
    assert made == ["grok"]
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider"] == "grok" and payload["provider_resolved_from"] == "fallback-from-codex"
    assert payload["provider_fallback"] == {"from": "codex", "to": "grok", "cause": "login", "reason": NOT_SIGNED_IN,
                                            "default_source": "hard-default", "chosen_by": "saved"}
    err = capsys.readouterr().err
    switch = [line for line in err.splitlines() if base.PROVIDER_SWITCH_WORDS in line]
    assert len(switch) == 1 and "'grok'" in switch[0] and "saved" in switch[0] and NOT_SIGNED_IN in switch[0]
    assert base.CODEX_UNAVAILABLE_ASK not in err


def test_saved_openai_runs_the_api_with_its_charge_line_and_reports_the_choice(tmp_path, monkeypatch, made,
                                                                               openai_api, capsys):
    _choose("openai")
    _codex_down(monkeypatch)
    report = tmp_path / "out.json"
    assert gen.run(prompt="a red apple", out=tmp_path / "out.png", report=report) == 0
    assert made == ["openai"] and len(openai_api) == 1
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider"] == "openai"
    assert payload["provider_fallback"]["to"] == "openai" and payload["provider_fallback"]["chosen_by"] == "saved"
    err = capsys.readouterr().err.splitlines()
    assert len([line for line in err if base.API_CHARGE_WORDS in line and "OPENAI_API_KEY" in line]) == 1
    assert len([line for line in err if base.PROVIDER_SWITCH_WORDS in line and "'openai'" in line]) == 1


def test_codex_usage_used_up_with_saved_grok_runs_grok_after_codex(tmp_path, codex, made, capsys):
    _choose("grok")
    report = tmp_path / "out.json"
    assert gen.run(prompt="a red apple", out=tmp_path / "out.png", report=report) == 0
    assert made == ["codex", "grok"] and codex["execs"] == 1
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider"] == "grok" and payload["provider_resolved_from"] == "fallback-from-codex"
    assert payload["provider_fallback"] == {"from": "codex", "to": "grok", "cause": "usage-limit",
                                            "reason": USAGE_LIMIT_SAID[0], "default_source": "hard-default",
                                            "chosen_by": "saved"}
    assert "'grok'" in capsys.readouterr().err


def test_the_environment_answers_before_the_saved_choice(monkeypatch, capsys):
    _choose("grok")
    _codex_down(monkeypatch)
    monkeypatch.setenv(gen.CODEX_UNAVAILABLE_ENV, "ask")
    with pytest.raises(base.CodexUnavailableAsk):
        gen.resolve_default_provider()
    monkeypatch.setenv(gen.CODEX_UNAVAILABLE_ENV, "openai")
    provider, fallback = gen.resolve_default_provider()
    assert provider == "openai" and fallback["chosen_by"] == gen.CODEX_UNAVAILABLE_ENV
    monkeypatch.setenv(gen.CODEX_UNAVAILABLE_ENV, "gemini")
    with pytest.raises(SystemExit, match=gen.CODEX_UNAVAILABLE_ENV):
        gen.resolve_default_provider()


def test_a_codex_that_can_run_reads_no_choice(tmp_path, monkeypatch, made):
    path = preferences.settings_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text("not json", encoding="utf-8")  # a broken settings file is read only when the choice is needed
    monkeypatch.setattr(gen, "_codex_available", lambda: (True, ""))
    assert gen.resolve_default_provider() == ("codex", None)
    _codex_down(monkeypatch)
    with pytest.raises(SystemExit, match="invalid preferences"):
        gen.resolve_default_provider()


def test_logo_resolves_the_same_way(tmp_path, monkeypatch, made):
    from sprite_gen.gen import logo

    _codex_down(monkeypatch)
    out_dir = tmp_path / "logo"
    with pytest.raises(base.CodexUnavailableAsk):
        logo.run(text="STARFALL", style="painted fantasy", out_dir=out_dir)
    assert made == [] and not out_dir.exists()


# --- a named provider runs as named ---------------------------------------------------------------------------


def test_a_named_provider_runs_as_named_whatever_was_chosen(tmp_path, codex, made, monkeypatch):
    _choose("openai")
    with pytest.raises(SystemExit) as failed:
        gen.run(provider="codex", prompt="a red apple", out=tmp_path / "out.png")
    assert not isinstance(failed.value, base.CodexUnavailableAsk) and USAGE_LIMIT_SAID[0] in str(failed.value.code)
    assert made == ["codex"]
    monkeypatch.setattr(gen, "_codex_available", lambda: pytest.fail("a named provider resolves no default"))
    report = tmp_path / "grok.json"
    assert gen.run(provider="grok", prompt="a red apple", out=tmp_path / "grok.png", report=report) == 0
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider_resolved_from"] == "explicit" and "provider_fallback" not in payload


# --- batch verbs stop with the same question ------------------------------------------------------------------


def _prepared_run(tmp_path: Path) -> Path:
    out_dir = tmp_path / "run"
    states = {"idle": {"frames": 4, "fps": 6, "loop": True, "action": "standing"},
              "walk": {"frames": 6, "fps": 8, "loop": True, "action": "walking"}}
    result = run_script("prepare_sprite_run.py", "--out-dir", str(out_dir), "--character-id", "askbot",
                        "--request-json", json.dumps({"states": states}))
    assert result.returncode == 0, result.stdout + result.stderr
    Image.new("RGB", (64, 64), (255, 0, 255)).save(out_dir / "base-source.png")
    return out_dir


def test_gen_set_whose_rows_asked_stops_with_the_same_question(tmp_path):
    run_dir = _prepared_run(tmp_path)
    run = _cli("gen-set", "--run-dir", str(run_dir), env=_without_codex(tmp_path))
    assert run.returncode == base.CODEX_UNAVAILABLE_EXIT, run.stdout + run.stderr
    # each row's own question stays in its log; the set asks once
    assert len([line for line in run.stderr.splitlines() if line.startswith(base.CODEX_UNAVAILABLE_ASK)]) == 1
    question = base.asked_codex_unavailable(run.stderr)
    assert question["cause"] == "login" and question["choices"]["openai"] == "--provider openai"
    reports = run_dir / "reports" / "gen-set"
    payload = json.loads((reports / "set.report.json").read_text(encoding="utf-8"))
    assert payload["asked"] == question and payload["ok"] == 0
    assert all(item["asked"] == question for item in payload["items"])
    assert "| idle | - | - |" in (reports / "table.md").read_text(encoding="utf-8")
    assert "ASKED" in (reports / "table.md").read_text(encoding="utf-8")
    assert not (run_dir / "raw" / "idle.png").exists() and not (run_dir / "raw" / "walk.png").exists()


def test_gen_set_takes_the_providers_gen_takes():
    """The question's answer is rerun with --provider openai, so gen-set must take it (and runs it as named)."""
    args = _build_parser().parse_args(["gen-set", "--run-dir", "run", "--provider", "openai"])
    assert args.provider == "openai"


def test_video_set_whose_mid_step_redraw_asked_stops_with_the_same_question(tmp_path, monkeypatch):
    hermetic = _without_codex(tmp_path)
    for name in ("PATH", "GROK_HOME"):
        monkeypatch.setenv(name, hermetic[name])
    for name in ("XAI_API_KEY", "OPENAI_API_KEY"):
        monkeypatch.delenv(name, raising=False)
    still = Image.new("RGB", (96, 128), (0, 255, 0))
    for y in range(20, 110):
        for x in range(36, 60):
            still.putpixel((x, y), (120, 60, 40))
    still.save(tmp_path / "front.png")
    root = tmp_path / "set"
    with pytest.raises(base.CodexUnavailableAsk) as asked:
        batch.run_set(bases={"front": tmp_path / "front.png"}, states=["walk"], root=root, character=None,
                      duration=3, resolution="720p", key="green", concurrency=1, force=False, gap=0,
                      video_runner=lambda *a, **k: pytest.fail("no clip is filmed from a start still never drawn"),
                      align_cycles="off")
    question = asked.value.question
    assert asked.value.code == base.CODEX_UNAVAILABLE_EXIT and question["cause"] == "login"
    assert question["choices"] == {"openai": "--still-provider openai", "grok": "--still-provider grok", "stop": None}
    assert list(question["choices"]) == ["openai", "grok", "stop"]
    payload = json.loads((root / "set.report.json").read_text(encoding="utf-8"))
    assert payload["asked"] == question and payload["items"][0]["asked"]["cause"] == "login"


# --- the guided request asks once and saves it ----------------------------------------------------------------


@pytest.fixture
def ready_login(monkeypatch):
    monkeypatch.setattr(guide, "probe_access", lambda provider: {
        "provider": provider, "login": "ready", "subscription": "unknown", "quota": "unknown",
        "billing": "subscription", "reason": "unverified media access"})


def test_the_guide_reports_the_choice_under_the_name_the_setting_is_saved_by(ready_login, monkeypatch):
    monkeypatch.setattr(guide, "CODEX_UNAVAILABLE_SETTING", "renamed")
    monkeypatch.setattr(guide, "GENERAL_FIELDS", {"renamed": guide.GENERAL_FIELDS[gen.CODEX_UNAVAILABLE_SETTING]})
    view = guide.guide("image", choices={"image_provider": "codex"}, confirmed_access=("codex",))
    assert view["renamed"] == {"choice": "ask", "source": "default"}


def test_the_guide_asks_what_to_do_when_codex_cannot_run_once_and_the_answer_is_saved(ready_login, monkeypatch):
    request = dict(choices={"image_provider": "codex"}, confirmed_access=("codex",))
    view = guide.guide("image", **request)
    asked = [q for q in view["questions"] if q["field"] == "codex_unavailable"]
    assert view["status"] == "needs-input" and len(asked) == 1
    assert list(asked[0]["options"]) == ["ask", "grok", "openai"] and "과금" in asked[0]["options"]["openai"]
    assert view["codex_unavailable"] == {"choice": "ask", "source": "default"}
    saved = preferences.save_settings(None, {}, general={"codex_unavailable": "ask"},
                                      expected_revision=view["settings_revision"])
    assert saved["general"] == {"codex_unavailable": "ask"} and saved["profiles"] == {}
    view = guide.guide("image", **request)
    assert view["status"] == "ready" and view["questions"] == []
    assert view["codex_unavailable"] == {"choice": "ask", "source": "saved"}
    monkeypatch.setenv(gen.CODEX_UNAVAILABLE_ENV, "grok")
    assert guide.guide("image", **request)["codex_unavailable"] == {"choice": "grok",
                                                                    "source": gen.CODEX_UNAVAILABLE_ENV}


def test_the_choice_is_kept_beside_the_profiles_in_the_one_settings_file():
    first = preferences.save_settings("image", {"image_provider": "grok"}, expected_revision="missing")
    second = preferences.save_settings(None, {}, general={"codex_unavailable": "openai"},
                                       expected_revision=first["revision"])
    assert second["profiles"] == first["profiles"] and second["general"] == {"codex_unavailable": "openai"}
    third = preferences.save_settings("image", {}, expected_revision=second["revision"], clear=True)
    assert third["profiles"] == {} and third["general"] == {"codex_unavailable": "openai"}
    for bad in ({"codex_unavailable": "gemini"}, {"default_provider": "grok"}):
        with pytest.raises(ValueError):
            preferences.save_settings(None, {}, general=bad, expected_revision=third["revision"])
    assert json.loads(preferences.settings_path().read_text(encoding="utf-8"))["version"] == 2


def test_a_version_1_settings_file_still_reads_with_nothing_chosen():
    path = preferences.settings_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text('{"version":1,"profiles":{"image":{"curation":"skip"}}}', encoding="utf-8")
    settings = preferences.read_settings()
    assert settings["profiles"] == {"image": {"curation": "skip"}} and settings["general"] == {}


def test_the_defaults_cli_saves_and_shows_the_choice(tmp_path):
    saved = _cli("defaults", "save", "--codex-unavailable", "grok", "--expected-revision", "missing")
    assert saved.returncode == 0, saved.stderr
    shown = json.loads(_cli("defaults", "show").stdout)
    assert shown["general"] == {"codex_unavailable": "grok"} and shown["profiles"] == {}
    refused = _cli("defaults", "save", "--codex-unavailable", "gemini", "--expected-revision", shown["revision"])
    assert refused.returncode != 0


def test_skill_names_the_exit_code_the_line_and_the_three_choices():
    skill = (REPO_ROOT / "SKILL.md").read_text(encoding="utf-8")
    assert f"exit {base.CODEX_UNAVAILABLE_EXIT}" in skill and base.CODEX_UNAVAILABLE_ASK.strip() in skill
    for words in ("OpenAI API", "그록", "멈추기", "--codex-unavailable"):
        assert words in skill