spritegen-cli 0.1.0__py3-none-any.whl

spritegen/workspace.py

@@ -0,0 +1,852 @@
+"""The asset directory, and the state file that says where it stopped.
+
+Everything belonging to one character lives under `assets/<name>/`, and `state.json`
+inside it is the only record of progress. No stage takes an input or output path: it
+asks here. That is what lets `status` say what comes next and lets a stage refuse to
+run out of order.
+
+The state file holds what happened, never what should happen next — the pipeline's
+shape is in `stages`, and two records of one fact disagree. So `stages` here maps only
+the stages that have *completed*, and an asset that has just been opened has an empty
+one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from . import stages as registry
+
+
+class StageRefused(ValueError):
+    """A stage was asked to run and must not.
+
+    A ValueError so the CLI turns it into an exit code and a line on stderr, rather
+    than a traceback: being refused is an answer, not a crash.
+    """
+
+
+STATE_FILE = "state.json"
+LEDGER_FILE = "ledger.jsonl"
+
+#: Where a sprite's prompts are kept, versioned, inside the sprite's own directory.
+PROMPTS_DIR = "prompts"
+
+#: The number of the on-disk shape. 1 was a directory per stage; 2 is a directory per
+#: artifact kind, with art directions under `sheet/`. A state file with no number is 1.
+LAYOUT = 2
+
+#: An asset name is a directory name, so it may not steer the path anywhere.
+_FORBIDDEN_CHARS = frozenset(r'/\:*?"<>|')
+
+#: Names Windows reserves for devices, with or without an extension. `mkdir CON` fails
+#: with something that reads like a permissions problem rather than a naming one, so it
+#: is refused here where the reason can be said.
+_RESERVED = frozenset(
+    {"con", "prn", "aux", "nul"}
+    | {f"com{digit}" for digit in "123456789"}
+    | {f"lpt{digit}" for digit in "123456789"}
+)
+
+
+#: Where an installed spritegen keeps a project's assets: a directory of its own inside
+#: the project, holding one subdirectory per character.
+WORKSPACE_DIR = Path("spritegen") / "assets"
+
+#: What makes a directory a project root, when there is no workspace to find. Any one of
+#: them is enough — a repository is a project whether or not it is Python.
+ROOT_MARKERS = (".git", ".claude", "pyproject.toml", "package.json")
+
+
+def _nearest(start: Path, relative: Path | str) -> Path | None:
+    """The nearest existing `<base>/relative` at or above `start`, within the ceiling.
+
+    The ceiling is `settings.search_from`, and it is shared with the `.env` search on
+    purpose: both walk upward from the working directory, and both would otherwise reach
+    the filesystem root. A `spritegen/assets` created once in a home directory would
+    become the asset store of every unrelated project run from anywhere beneath it.
+    """
+    from . import settings
+
+    for base in settings.search_from(start):
+        candidate = base / relative
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def project_root(start: Path | None = None) -> Path:
+    """The project this CLI is being run inside, or the working directory.
+
+    Searched the same way `settings.dotenv` searches for a `.env` and `skill.target` for a
+    `.claude`, and bounded the same way: the directory a command is typed in is rarely the
+    top of the thing it is about, but neither is the filesystem root.
+    """
+    from . import settings
+
+    start = Path.cwd() if start is None else start
+    for base in settings.search_from(start):
+        if any((base / marker).exists() for marker in ROOT_MARKERS):
+            return base
+    return start
+
+
+def assets_root(start: Path | None = None) -> Path:
+    """Where the assets live.
+
+    Four answers, in this order, and the order is the whole design:
+
+    1. **`SPRITEGEN_ASSETS`** — an explicit answer always wins, which is what lets a test
+       and a second collection of characters exist at all.
+    2. **The nearest existing `spritegen/assets/`** at or above the working directory.
+       This is the installed shape: the CLI comes from PyPI, the project it serves is
+       somebody else's, and the state and the images belong to that project rather than
+       to the tool. Searching upward is what makes a command work from anywhere inside
+       the project instead of only from its root, and it stops at a repository boundary
+       — see `settings.search_from` for why that ceiling has to be there.
+    3. **An existing `assets/`** at or above the working directory — the shape before
+       there was a published CLI, kept so a workspace that already has one keeps working.
+    4. **`<project root>/spritegen/assets`**, which is where `init` would create it.
+
+    Nothing here creates a directory. A path that does not exist is the answer `status`
+    and every stage report, which is what lets them say to run `init` rather than
+    opening an empty workspace nobody asked for.
+    """
+    from . import settings
+
+    override = settings.load().assets
+    if override:
+        return Path(override)
+
+    start = Path.cwd() if start is None else start
+    found = _nearest(start, WORKSPACE_DIR)
+    if found is not None:
+        return found
+    legacy = _nearest(start, "assets")
+    if legacy is not None:
+        return legacy
+    return project_root(start) / WORKSPACE_DIR
+
+
+def check_name(name: str) -> str:
+    """`name` if it is usable as a directory name, and an error naming the reason if not.
+
+    Rejected here rather than by the filesystem: a name with a separator in it would
+    silently write outside the assets root, one that is empty or all dots would resolve
+    to the root itself, and a name Windows reserves fails at `mkdir` with an error that
+    reads like a permissions problem.
+
+    **Two inputs go through this, not one.** An asset's name, and the animation a pose is
+    for — both become a directory, and there is no second rule for the second one.
+    """
+    if not name or name != name.strip():
+        raise ValueError(f"asset name {name!r} is empty or padded with spaces")
+    if set(name) <= {"."}:
+        raise ValueError(f"asset name {name!r} is not a name")
+    bad = sorted(_FORBIDDEN_CHARS & set(name))
+    if bad:
+        shown = "".join(bad)
+        raise ValueError(f"asset name {name!r} may not contain {shown!r}")
+    if ".." in name:
+        raise ValueError(f'asset name {name!r} may not contain ".."')
+    if name.endswith("."):
+        # Windows strips it, so `attack.` and `attack` would be one directory under two
+        # names — and the state file would hold both.
+        raise ValueError(f"asset name {name!r} may not end with a dot")
+    if name.split(".", 1)[0].lower() in _RESERVED:
+        raise ValueError(f"asset name {name!r} is a name Windows reserves for a device")
+    return name
+
+
+def asset_dir(name: str) -> Path:
+    return assets_root() / check_name(name)
+
+
+def state_path(name: str) -> Path:
+    return asset_dir(name) / STATE_FILE
+
+
+def ledger_path(name: str) -> Path:
+    return asset_dir(name) / LEDGER_FILE
+
+
+@dataclass
+class State:
+    """One asset's progress.
+
+    Two records, and they answer different questions. `stages` maps a completed stage's
+    name to whatever that stage recorded, in the order the stages completed — that order
+    is not derivable from anything else and is what `Context.source` reads. `artifacts`
+    maps a kind to where its files are, which is what anyone asking "what does this
+    sprite have" wants and what no amount of reading `stages` gives you directly.
+
+    `layout` is the number of the on-disk shape. A file without one was written before
+    the shape had a number, and saying so is different from reading it as empty.
+    """
+
+    name: str
+    created: str
+    stages: dict[str, dict] = field(default_factory=dict)
+    artifacts: dict[str, dict] = field(default_factory=dict)
+    layout: int = LAYOUT
+
+    def completed(self) -> set[str]:
+        return set(self.stages)
+
+    def last(self) -> str | None:
+        """The stage that completed most recently, or None if none has.
+
+        Completion order is `stages` insertion order, which survives the JSON round
+        trip. A stage re-run with --force keeps the position it first took: the file
+        answers "what has been done", and re-doing one does not make it newer.
+        """
+        return next(reversed(self.stages), None) if self.stages else None
+
+    def to_json(self) -> dict:
+        return {
+            "name": self.name,
+            "created": self.created,
+            "layout": self.layout,
+            "stages": self.stages,
+            "artifacts": self.artifacts,
+        }
+
+    @classmethod
+    def from_json(cls, raw: dict) -> State:
+        missing = {"name", "created"} - set(raw)
+        if missing:
+            raise ValueError(f"state file is missing {', '.join(sorted(missing))}")
+        return cls(
+            name=raw["name"],
+            created=raw["created"],
+            stages=raw.get("stages") or {},
+            artifacts=raw.get("artifacts") or {},
+            # A state file with no layout number was written before there were any, and
+            # that is exactly what R1.5 has to be able to tell apart from an empty one.
+            layout=int(raw.get("layout", 1)),
+        )
+
+    def outdated(self) -> bool:
+        """Whether this workspace predates the current layout — R1.5."""
+        return self.layout < LAYOUT
+
+
+def require_workspace() -> Path:
+    """The assets root, if it is there or was named outright. An error naming `init` if not.
+
+    Creating a discovered root here would be the wrong kindness. `assets_root` resolves
+    to a path whether or not anything is at it, so a `new` typed in the wrong directory
+    would quietly open a second workspace beside the real one — and the first sign of it
+    would be a `status` that has forgotten every character. `init` is where a workspace
+    comes from, and it says where it made one.
+
+    A root named by `SPRITEGEN_ASSETS` is the exception, and for the same reason it wins
+    everywhere else: it was not guessed. Whoever set it said where the assets go, and
+    being told to run `init` to create the directory they just named would be absurd.
+    """
+    root = assets_root()
+    if root.is_dir():
+        return root
+    from . import settings
+
+    if settings.load().assets:
+        root.mkdir(parents=True, exist_ok=True)
+        return root
+    raise FileNotFoundError(
+        f"no spritegen workspace at {root}; run `spritegen init` to make one"
+    )
+
+
+def create(name: str) -> State:
+    """Open a new asset — R1.1, R1.2.
+
+    Refuses an asset that already exists instead of merging into it: the state file is
+    the record of what was paid for, and re-opening on top of one would lose it.
+    """
+    require_workspace()
+    directory = asset_dir(name)
+    if directory.exists():
+        raise FileExistsError(f"asset {name!r} already exists at {directory}")
+    directory.mkdir(parents=True)
+    state = State(name=name, created=datetime.now(UTC).isoformat(timespec="seconds"), stages={})
+    save(state)
+    return state
+
+
+def load(name: str) -> State:
+    path = state_path(name)
+    if not path.exists():
+        raise FileNotFoundError(f"asset {name!r} has no {STATE_FILE}; run `spritegen new {name}`")
+    return State.from_json(json.loads(path.read_text(encoding="utf-8")))
+
+
+def save(state: State) -> Path:
+    path = state_path(state.name)
+    path.write_text(
+        json.dumps(state.to_json(), indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    return path
+
+
+def known() -> list[str]:
+    """Every asset that has a state file, in name order."""
+    root = assets_root()
+    if not root.is_dir():
+        return []
+    return sorted(d.name for d in root.iterdir() if (d / STATE_FILE).is_file())
+
+
+def satisfied(state: State, stage: registry.Stage) -> bool:
+    """Whether this stage's input exists — **by artifact, not by stage name**.
+
+    A stage names the stages it follows, but what it actually needs is the *kind* those
+    stages produce. Those were the same thing while a stage made one thing. They are not
+    now: `anchor` produces `anchor`, `box-art` or `icon` depending on what it was asked
+    for, and box art is the one the pipeline is told to make *first*, before the anchor
+    exists.
+
+    Asking by stage name made having box art mean having an anchor. `motion` and `video`
+    became eligible, `Context.source` resolved to the box-art directory, and a paid call
+    ran against an illustration instead of the neutral sprite it deforms from — silently,
+    because every check involved had been told the anchor was there.
+    """
+    if not stage.requires:
+        return True
+    return any(registry.get(dep).produces in state.artifacts for dep in stage.requires)
+
+
+def next_stages(state: State) -> tuple[str, ...]:
+    """The stages that could run now — R1.3.
+
+    A stage is eligible when its input exists and it still has something to make. Plural
+    because the pipeline branches: with an anchor, both `motion` and `video` can run, and
+    choosing between them is the operator's call, not this function's.
+
+    **"Still has something to make" is per kind for a stage that makes several.** `anchor`
+    having run for box art has not made an anchor, and this route is one the skill tells
+    you to take — box art first, then the anchor that quotes it. Saying "nothing comes
+    next" there is advice against the tool's own recommendation.
+
+    For a stage that makes one thing it stays "has this stage run", which is what keeps
+    the untaken branch on offer: `motion` and `video` are alternatives, having taken one
+    leaves the other worth running, and they are two stages rather than two kinds.
+    """
+    return tuple(
+        stage.name
+        for stage in registry.STAGES
+        if pending(state, stage) and satisfied(state, stage)
+    )
+
+
+def pending(state: State, stage: registry.Stage) -> bool:
+    """Whether this stage still has the artifact it is chiefly for.
+
+    `produces` is that artifact — the anchor, out of a stage that can also make box art
+    and an icon. Those two are asked for by name when somebody wants them; they are not
+    what comes next, and offering `anchor` forever until all three exist would be as
+    useless as the bug this replaced, in the other direction.
+
+    **A stage that varies by variant rather than by kind falls to "has it run".** `pose`
+    and `board` can both make more — another animation, another art direction — and how
+    many is unbounded, so there is no count at which they are finished. Offering them
+    forever is the honest answer and the useless one: `status` would never be able to say
+    an asset is complete, which is the signal people read it for. So they are offered
+    once, `require_ready` keeps letting you make another, and the skill is what says so.
+    """
+    if stage.kind_option is None:
+        return stage.name not in state.stages
+    return stage.produces not in state.artifacts
+
+
+def output_dir(
+    asset: str, stage_name: str, kind: str | None = None, variant: str | None = None
+) -> Path:
+    """Where a stage writes for `asset` — R1.1, R1.3.
+
+    The only place that turns a stage and its options into a path, which is what lets
+    the layout change without every stage learning about it.
+
+    `kind` is what the artifact *is*, and it is the directory: box art, an anchor and an
+    icon all come out of `anchor` and are three different things. `variant` is a
+    dimension under that kind rather than a step after it — `sheet/sharp/` and
+    `sheet/pixel-art/` are one sprite closed two ways, and a project may want both.
+
+    Both default to the stage's own `produces` and to no variant, so a stage that makes
+    one thing needs to say nothing.
+    """
+    stage = registry.get(stage_name)
+    directory = asset_dir(asset) / (kind or stage.produces)
+    return directory / variant if variant else directory
+
+
+class Escaped(ValueError):
+    """A recorded path that does not stay inside the asset it belongs to."""
+
+
+def inside(asset: str, relative: str) -> Path:
+    """`asset_dir(asset) / relative`, refused unless it stays inside the asset.
+
+    **Every path that came out of `state.json` goes through here.** `check_name` guards
+    the asset's *name*, which is what this tool chooses; `dir` is a string in a file on
+    disk that anything with write access can change — a synced workspace, an `assets/`
+    somebody committed, another tool in the same session.
+
+    Two ways it escapes and both are silent. `Path("a") / "/etc"` discards the left side
+    entirely, so an absolute value replaces the asset directory outright; and `..`
+    segments are honoured by the filesystem however deep they go. What that would buy is
+    not hypothetical: `inspect` lists filenames, `upscale` reads and overwrites in place,
+    and `Context.source` decides what a paid stage uploads — which would make an edited
+    state file a way to send somebody's files to a third party on their own key.
+    """
+    base = asset_dir(asset).resolve()
+    candidate = (base / relative).resolve()
+    if candidate != base and base not in candidate.parents:
+        raise Escaped(
+            f"{asset}: {relative!r} in {STATE_FILE} points outside the asset directory; "
+            f"it has been edited by something other than spritegen"
+        )
+    return candidate
+
+
+def stage_output(asset: str, stage_name: str, recorded: dict | None = None) -> Path:
+    """Where that stage actually wrote, read back from what it recorded.
+
+    A stage records the directory it used, because the options that chose it are gone by
+    the time the next stage runs. Falling back to the default is for a state file written
+    before this existed, and for a stage that has not run.
+    """
+    if recorded and recorded.get("dir"):
+        return inside(asset, recorded["dir"])
+    return output_dir(asset, stage_name)
+
+
+def has_output(asset: str, stage_name: str, kind: str | None = None,
+               variant: str | None = None) -> bool:
+    """Whether that output is already on disk.
+
+    Asked of the filesystem rather than of the state file. The two disagree when a run
+    died between writing its files and recording itself, and in that case the files are
+    what would be overwritten.
+    """
+    directory = output_dir(asset, stage_name, kind, variant)
+    return directory.is_dir() and any(directory.iterdir())
+
+
+def require_ready(
+    state: State,
+    stage_name: str,
+    *,
+    force: bool = False,
+    kind: str | None = None,
+    variant: str | None = None,
+) -> registry.Stage:
+    """The stage, if it may run now — R1.4, R1.5.
+
+    Refuses in two cases and names what to do about each: a prerequisite that has not
+    completed, and output that is already there. Every stage calls this before doing
+    anything, which is why the checks live here and not in five modules.
+    """
+    stage = registry.get(stage_name)
+
+    if not satisfied(state, stage):
+        wanted = sorted({registry.get(dep).produces for dep in stage.requires})
+        missing = " or ".join(stage.requires)
+        needs = " or ".join(wanted)
+        raise StageRefused(
+            f"{state.name}: {stage_name!r} needs {needs!r}, which {missing} produces "
+            f"and which this asset does not have"
+        )
+
+    # What is checked is the directory *this* run would write, not the stage as a whole:
+    # box art and an anchor both come out of `anchor`, and having one is not a reason to
+    # refuse the other. The same goes for a second art direction of one sheet.
+    made = kind or stage.produces
+    artifact = f"{made}:{variant}" if variant else made
+    entry = state.stages.get(stage_name)
+    # An entry that never said what it produced predates this, and what it made cannot
+    # be told from here. Refusing is the recoverable answer; overwriting is not.
+    completed = entry is not None and entry.get("produced", artifact) == artifact
+    if not force and (completed or has_output(state.name, stage_name, kind, variant)):
+        raise StageRefused(
+            f"{state.name}: {stage_name!r} already produced {artifact!r}; "
+            f"pass --force to rewrite it"
+        )
+
+    return stage
+
+
+@dataclass
+class Context:
+    """What a stage is handed: its asset, and every path it is allowed to touch — R3.2.
+
+    A stage takes no input or output path from the command line. It asks this object,
+    which derives everything from the asset directory. That is what makes a run
+    reproducible from `state.json` alone, and what stops two stages from disagreeing
+    about where the board is.
+    """
+
+    state: State
+    stage: registry.Stage
+    force: bool = False
+    dry_run: bool = False
+    kind: str | None = None
+    variant: str | None = None
+    prompt: str | None = None
+    parts: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def artifact(self) -> str:
+        """The key this run's output is recorded under: the kind, or kind:variant."""
+        kind = self.kind or self.stage.produces
+        return f"{kind}:{self.variant}" if self.variant else kind
+
+    @property
+    def asset(self) -> str:
+        return self.state.name
+
+    @property
+    def directory(self) -> Path:
+        return asset_dir(self.asset)
+
+    @property
+    def out(self) -> Path:
+        """Where this stage writes. Not created — see `ensure_out`."""
+        return output_dir(self.asset, self.stage.name, self.kind, self.variant)
+
+    def ensure_out(self) -> Path:
+        """`out`, created. A dry run never calls this, so it leaves no directory behind."""
+        self.out.mkdir(parents=True, exist_ok=True)
+        return self.out
+
+    @property
+    def source(self) -> Path:
+        """The directory holding this stage's input — resolved by kind, not by stage.
+
+        A stage's `requires` names stages, but the input is the *artifact* those stages
+        produce, and that is what is looked up. Where two branches produce the same kind
+        — `motion` and `video` both make `frames` — they write the same directory, so
+        there is no "which branch was most recent" left to decide: whichever ran last is
+        what is in there.
+        """
+        if not self.stage.requires:
+            raise ValueError(f"{self.stage.name!r} has no input stage; its input is its prompt")
+
+        for dep in self.stage.requires:
+            kind = registry.get(dep).produces
+            entry = self.state.artifacts.get(kind)
+            if entry is not None:
+                return inside(self.asset, entry["dir"])
+
+        wanted = " or ".join(sorted({registry.get(d).produces for d in self.stage.requires}))
+        raise StageRefused(f"{self.asset}: {self.stage.name!r} has no {wanted} to read")
+
+    def source_files(self, pattern: str = "*") -> list[Path]:
+        """The input files, sorted by name, so a frame order is a frame order."""
+        return sorted(path for path in self.source.glob(pattern) if path.is_file())
+
+    @property
+    def ledger(self) -> Path:
+        return ledger_path(self.asset)
+
+    def keep_prompt(self, text: str, part: str | None = None) -> str:
+        """Store a prompt for this run and return the version to record — R2.1, R2.4.
+
+        Called before the paid call, not after it. A prompt written only on success is
+        missing from exactly the runs somebody needs to go back and look at, and a
+        `--prompt-file` outside the workspace can be edited or deleted the moment the
+        call returns.
+
+        `part` names one piece of a run that makes more than one image from more than one
+        text — a pose's closing frame against its opening one. Without it the prompt is
+        the run's, and it is the one the artifact cites. **A part is stored and recorded
+        but does not become the artifact's prompt**: one artifact cites one text, and
+        citing the second call's text for the first call's image would be a provenance
+        record that is wrong rather than missing.
+        """
+        from . import prompts
+
+        stem = self.artifact.replace(":", "-")
+        kept = prompts.store(self.directory, f"{stem}-{part}" if part else stem, text)
+        if part is None:
+            self.prompt = kept
+        else:
+            self.parts[part] = kept
+        return kept
+
+    def paid_call(
+        self,
+        *,
+        endpoint: str,
+        payload: dict,
+        urls: list[str] | None = None,
+        files: list[Path] | None = None,
+    ) -> dict:
+        """Record one paid call against this asset — R2.1.
+
+        Called by the stage right after the call returns and the files are on disk,
+        whether or not the stage goes on to succeed: the money is gone either way.
+        """
+        from . import ledger
+
+        line = ledger.entry(
+            stage=self.stage.name,
+            endpoint=endpoint,
+            payload=payload,
+            urls=urls,
+            files=files,
+        )
+        return ledger.append(self.ledger, line)
+
+    def record(self, **fields) -> State:
+        """Mark this stage complete, note what it produced, and write the state file — R1.4.
+
+        Called once, at the end of a stage that actually produced something. A dry run
+        does not call it, which is why a dry run cannot advance an asset.
+
+        Two entries go in, because two questions get asked. `stages` keeps the order the
+        pipeline ran in, and carries `dir` so the next stage can find the output without
+        re-deriving the options that chose it. `artifacts` is indexed by what the thing
+        *is*, and it lists the files — which is what `show` reads and what the editor
+        will read after it.
+        """
+        directory = self.out.relative_to(self.directory).as_posix()
+        self.state.stages[self.stage.name] = {
+            "produced": self.artifact,
+            "dir": directory,
+            **fields,
+        }
+        self.state.artifacts[self.artifact] = {
+            "dir": directory,
+            "files": sorted(path.name for path in self.out.glob("*") if path.is_file())
+            if self.out.is_dir()
+            else [],
+            "stage": self.stage.name,
+            # R2.3 — which text produced this, answered without opening the image.
+            "prompt": fields.get("prompt", self.prompt),
+            **({"prompts": dict(self.parts)} if self.parts else {}),
+        }
+        save(self.state)
+        return self.state
+
+
+def prepare(
+    asset: str,
+    stage_name: str,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+    kind: str | None = None,
+    variant: str | None = None,
+) -> Context:
+    """Load the asset, check the stage may run, and hand back its context — R3.2.
+
+    The one way into a stage. Every stage module's `run` starts here, so the order
+    check and the path resolution cannot be skipped by one of them.
+    """
+    state = load(asset)
+    stage = require_ready(state, stage_name, force=force, kind=kind, variant=variant)
+    return Context(
+        state=state, stage=stage, force=force, dry_run=dry_run, kind=kind, variant=variant
+    )
+
+
+def context_from_args(args: argparse.Namespace) -> Context:
+    """`prepare`, filled from the parsed command line.
+
+    `dry_run` is absent on a free stage's parser, so it is read defensively rather
+    than assumed.
+    """
+    stage = registry.get(args.command)
+    return prepare(
+        args.name,
+        args.command,
+        force=getattr(args, "force", False),
+        dry_run=getattr(args, "dry_run", False),
+        kind=_option_value(args, stage.kind_option),
+        variant=_option_value(args, stage.variant_option),
+    )
+
+
+def _option_value(args: argparse.Namespace, option: str | None) -> str | None:
+    """The value of a named option, or None when the stage declares none."""
+    return getattr(args, option, None) if option else None
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Where each asset stopped, and what comes next — R1.3.
+
+    ASCII only. A Windows console runs on a codepage that has no em dash, and a
+    console this tool cannot encode into drops the line rather than raising where
+    anyone would see it.
+    """
+    root = assets_root()
+    as_json = getattr(args, "json", False)
+
+    if not root.is_dir():
+        if as_json:
+            print(json.dumps({"root": str(root), "workspace": False, "assets": []}, indent=2))
+            return 0
+        print(f"no spritegen workspace at {root}; run `spritegen init` to make one")
+        return 0
+
+    names = known()
+    if as_json:
+        print(
+            json.dumps(
+                {"root": str(root), "workspace": True, "assets": [inspect(n) for n in names]},
+                indent=2,
+                ensure_ascii=False,
+            )
+        )
+        return 0
+
+    if not names:
+        print(f"no assets under {root}; run `spritegen new <name>` to open one")
+        return 0
+
+    width = max(len(name) for name in names)
+    outdated = []
+    for name in names:
+        state = load(name)
+        last = state.last() or "-"
+        upcoming = next_stages(state)
+        nxt = ", ".join(upcoming) if upcoming else "- complete"
+        stale = "  [layout 1]" if state.outdated() else ""
+        if state.outdated():
+            outdated.append(name)
+        print(f"{name:<{width}}  last: {last:<7}  next: {nxt}{stale}")
+
+    # R1.5 — an asset in the old shape is not an empty one, and saying which command
+    # fixes it is the difference between a finding and a puzzle.
+    if outdated:
+        which = "these assets are" if len(outdated) > 1 else f"{outdated[0]} is"
+        print(f"{which} in an older layout; run `spritegen migrate` to move them")
+    return 0
+
+
+def inspect(name: str) -> dict:
+    """Everything known about one sprite — R3.1, R3.3.
+
+    Two independent records go in and neither is reconciled here. `artifacts` is what the
+    stage said it wrote; `on_disk` is what is there now. `drift` is where they differ, and
+    it is reported rather than resolved: a file deleted by hand and a file written by hand
+    are different mistakes, and only the person in front of it knows which happened.
+    """
+    from . import prompts
+
+    state = load(name)
+    directory = asset_dir(name)
+
+    artifacts = {}
+    drift = []
+    for key, entry in state.artifacts.items():
+        target = inside(name, entry["dir"])
+        found = (
+            sorted(path.name for path in target.glob("*") if path.is_file())
+            if target.is_dir()
+            else []
+        )
+        recorded = list(entry.get("files") or [])
+        missing = [one for one in recorded if one not in found]
+        extra = [one for one in found if one not in recorded]
+        if missing or extra:
+            drift.append({"artifact": key, "dir": entry["dir"], "missing": missing, "extra": extra})
+        artifacts[key] = {**entry, "on_disk": found}
+
+    kept = {}
+    for path in sorted(prompts.directory(directory).glob("*.md")):
+        match = prompts.PATTERN.match(path.name)
+        if match:
+            kept.setdefault(match.group("kind"), []).append(int(match.group("version")))
+
+    return {
+        "name": state.name,
+        "created": state.created,
+        "layout": state.layout,
+        "outdated": state.outdated(),
+        "last": state.last(),
+        "next": list(next_stages(state)),
+        "artifacts": artifacts,
+        "prompts": {kind: sorted(found) for kind, found in kept.items()},
+        "drift": drift,
+    }
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    """What one sprite holds, and what could be produced next — R3.1, R3.2, R3.3.
+
+    ASCII only, for the reason `cmd_status` is. `--json` is for another program; a person
+    who ran this without the flag asked for the terminal form and should not get JSON.
+    """
+    found = inspect(check_name(args.name))
+
+    if getattr(args, "json", False):
+        print(json.dumps(found, indent=2, ensure_ascii=False))
+        return 0
+
+    stale = "  [layout 1: run `spritegen migrate`]" if found["outdated"] else ""
+    print(f"{found['name']}  created {found['created']}{stale}")
+    print(f"  last: {found['last'] or '-'}   next: {', '.join(found['next']) or '- complete'}")
+
+    if not found["artifacts"]:
+        print("  no artifact yet")
+    for key, entry in found["artifacts"].items():
+        prompt = f"  <- {entry['prompt']}" if entry.get("prompt") else ""
+        print(f"  {key:<16} {entry['dir']:<16} {len(entry['on_disk'])} file(s){prompt}")
+
+    for kind, found_versions in found["prompts"].items():
+        print(f"  prompt {kind}: v{', v'.join(str(one) for one in found_versions)}")
+
+    for one in found["drift"]:
+        where = one["artifact"]
+        if one["missing"]:
+            gone = ", ".join(one["missing"])
+            print(f"  drift {where}: recorded but not on disk: {gone}")
+        if one["extra"]:
+            new_files = ", ".join(one["extra"])
+            print(f"  drift {where}: on disk but not recorded: {new_files}")
+    return 0
+
+
+def cmd_new(args: argparse.Namespace) -> int:
+    state = create(args.name)
+    print(f"{state.name}  opened at {asset_dir(state.name)}  no stage complete")
+    return 0
+
+
+def cmd_cost(args: argparse.Namespace) -> int:
+    """The paid calls per asset, read from the ledger and nothing else — R2.4.
+
+    Deliberately does not open `state.json`. An asset whose outputs were deleted, or
+    whose state file was lost, still cost what it cost, and the ledger is the only
+    record that survives either.
+    """
+    from . import ledger
+
+    requested = getattr(args, "name", None)
+    names = [check_name(requested)] if requested else known()
+    if not names:
+        print(f"no assets under {assets_root()}")
+        return 0
+
+    total_calls = 0
+    for name in names:
+        rows = ledger.summarise(ledger.read(ledger_path(name)))
+        calls = sum(row["calls"] for row in rows)
+        total_calls += calls
+        print(f"{name}  {calls} paid call{'' if calls == 1 else 's'}")
+        for row in sorted(rows, key=lambda r: (r["stage"], r["endpoint"])):
+            size = f"{row['bytes'] / 1e6:.1f} MB" if row["bytes"] else "-"
+            files = f"{row['files']} file" + ("" if row["files"] == 1 else "s")
+            print(
+                f"  {row['stage']:<7} {row['endpoint']:<38} "
+                f"{row['calls']:>3} x  {files:<9}  {size}"
+            )
+
+    if len(names) > 1:
+        print(f"total  {total_calls} paid calls")
+    return 0