spritegen-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/.gitignore

@@ -217,3 +217,12 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 assets/
+
+# CodeGraph index — never committed
+.codegraph/
+
+# ai-jail sandbox configuration, local to a checkout
+.ai-jail
+
+# the spritegen workspace's own settings, and its key
+.spritegen.json

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spritegen-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Sprite generation CLI — a few AI-generated images into a game-ready character sheet
 Requires-Python: >=3.13
 Requires-Dist: av>=12.0

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/docs/adr/0003-append-only-jsonl-ledger.md

@@ -1,5 +1,6 @@
 ---
-status: accepted
+status: superseded
+superseded-by: 0015-record-the-call-before-the-files-it-writes
 ---
 
 # The record of a paid call is append-only JSONL

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/docs/adr/0006-centralise-configuration-and-never-cache-it.md

@@ -1,5 +1,6 @@
 ---
-status: accepted
+status: superseded
+superseded-by: 0016-a-workspace-is-marked-by-the-file-that-configures-it
 ---
 
 # One settings class, read fresh, with a ceiling on the upward search

spritegen_cli-0.4.0/docs/adr/0015-record-the-call-before-the-files-it-writes.md

@@ -0,0 +1,53 @@
+---
+status: accepted
+---
+
+# The ledger records a call before the files it writes
+
+## Context
+
+`adr:0003-append-only-jsonl-ledger` puts one line per paid call in `ledger.jsonl`,
+carrying the endpoint, the payload, the URLs returned and the sha256 of every file
+written. A line can only carry those digests once the files exist, so the write had to
+wait for them.
+
+What sits between the endpoint answering and the files landing is a download, a decode
+and a pack. Any of it can fail — a dropped transfer, a clip `av` will not open, a full
+disk — and the money is already spent when it does. The ledger is the only record that
+a call happened, and in exactly that case it recorded nothing at all: the failure it
+exists to survive was the one it did not.
+
+Appending is what makes the file safe to write from a run that dies, and it is also
+what stops the line being completed later. A record cannot be both written early and
+filled in afterwards.
+
+## Decision
+
+A paid call is **two lines joined by a `call` id**, not one.
+
+The first is written the moment the endpoint answers, before anything is downloaded:
+`kind: "call"`, with the endpoint, the redacted payload and the URLs. The second is
+written when the files land: `kind: "files"`, with the sha256 of each. A stage whose
+whole output is what the call returned, with nothing to download, still writes one
+line.
+
+`summarise` counts a call where `kind` is not `"files"`, so the two lines fold to one
+call and one set of files.
+
+## Consequences
+
+A run that dies mid-download leaves a `call` line with no `files` line. That is the
+point: the asset's ledger says the money went, and the absent second line says nothing
+landed. `cost` reports the call.
+
+A line written before this decision has no `kind`, and is read as a whole call on its
+own — old ledgers keep totalling to what they always did, and the format stays
+append-only, so nothing on disk is rewritten.
+
+The cost is that a reader can no longer assume one line is one call, and that the two
+lines of a call are adjacent only in practice — a concurrent run against one asset
+would interleave them, and the `call` id is what makes that legible rather than the
+line order.
+
+This supersedes `adr:0003-append-only-jsonl-ledger` on the shape of a line only. Its
+other decisions — append-only, upload URLs redacted, one file per asset — stand.

spritegen_cli-0.4.0/docs/adr/0016-a-workspace-is-marked-by-the-file-that-configures-it.md

@@ -0,0 +1,63 @@
+---
+status: accepted
+---
+
+# A workspace is marked by the file that configures it
+
+## Context
+
+`adr:0006-centralise-configuration-and-never-cache-it` reads settings from the
+environment, the nearest `.env`, and the declared default, in that order. Where the
+assets are was a separate question, answered by walking up from the working directory
+looking for a directory named `spritegen/assets`.
+
+That walk had nothing to recognise. A directory of the right name is not a claim to be
+one, so the search could not tell a workspace from a coincidence — and its ceiling
+admitted the home directory as a candidate. Run in `~/spritegen1/test1`, `init`
+reported a workspace at `~/spritegen/assets` and adopted it: one workspace became every
+project's, and a second project on the same machine was not possible without giving it
+a repository first.
+
+The two questions turned out to be one. A project that has its own assets usually wants
+its own cell size, its own matte backend, and — where more than one account is in play —
+its own key.
+
+## Decision
+
+**A directory holding `.spritegen.json` is a workspace root.** Its assets are
+`<root>/spritegen/assets`, and the nearest root at or above the working directory is
+the one a command uses.
+
+The same file carries the settings, as a JSON object whose names are the `Settings`
+fields without the environment's prefix. It sits **between the environment and the
+`.env`**: an exported variable still wins, which is what makes a one-off override work,
+and a machine with one key in `~/.env` keeps working. A name in it that is not a setting
+is refused rather than ignored.
+
+**The home directory is a candidate only when it is where the command was typed.** A
+marker there serves a command run in it and is never climbed into from below.
+
+`init` creates the workspace where it was run, always. It writes the marker with no
+credential in it, adds it to a `.gitignore` that exists, and warns when the marker is
+already tracked by git.
+
+## Consequences
+
+Several workspaces on one machine work, and they work without a repository: the marker
+is the boundary that `.git` used to have to stand in for.
+
+A credential can live in a file inside a project, which is why `init` writes it into
+`.gitignore` and warns when git already has it. `allowed_hosts` is settable there too
+(`adr:0004-allow-list-every-downloaded-host`) — the same reach a `.env` already had,
+bounded by the same ceiling.
+
+Two files now answer the same question, and that is the cost. `.env` is kept because
+removing it would break every machine that has a key today; whether it eventually goes
+is deliberately not decided here.
+
+A workspace opened before this exists has no marker. It keeps working through the
+unmarked fallback, which now holds the same line about the home directory — but it will
+not be found from a sibling project, and `init` in its root is what gives it one.
+
+This supersedes `adr:0006-centralise-configuration-and-never-cache-it` **on the list of
+sources only**. One class, nothing cached, and the ceiling all stand.

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/docs/codewiki/spending-money.md

@@ -6,7 +6,7 @@ goes wrong rather than because of a way it works.
 
 ## A URL an endpoint returned is still a URL somebody could have chosen
 
-[src/spritegen/fal.py:24-86]()
+[src/spritegen/fal.py:24-88]()
 
 The allowed hosts are a fixed tuple plus whatever `SPRITEGEN_ALLOWED_HOSTS` adds. The
 scheme must be https, and an authority carrying userinfo is refused outright — `https://
@@ -16,7 +16,7 @@ check.
 
 ## The redirect chain is walked here, not by the client
 
-[src/spritegen/fal.py:88-156]()
+[src/spritegen/fal.py:153-218]()
 
 This is the reason `httpx` is a dependency at all. A client following redirects itself
 would apply the host check to the URL that was handed in and to nothing after it, so one
@@ -25,7 +25,7 @@ hop out of the allowed set is enough to fetch from anywhere. Every hop is checke
 
 ## One door, and two refusals before anything is spent
 
-[src/spritegen/fal.py:166-211]()
+[src/spritegen/fal.py:220-241]()
 
 `require_key` and the `dry_run` branch live in `call` rather than in each stage, so no
 stage can forget one. `_subscribe` is the only function that touches `fal_client`, and it
@@ -34,7 +34,7 @@ without an HTTP client and what lets a test stand in for the endpoint without on
 
 ## The record redacts what would otherwise be a key
 
-[src/spritegen/ledger.py:23-59]()
+[src/spritegen/ledger.py:30-65]()
 
 `fal_client.upload_file` returns standing access to the uploaded file for anyone holding
 the link. Writing those into the ledger verbatim would turn a per-asset record into a way
@@ -44,7 +44,7 @@ named explicitly.
 
 ## One line, appended, never rewritten
 
-[src/spritegen/ledger.py:75-125]()
+[src/spritegen/ledger.py:81-141]()
 
 JSONL and `append` rather than a document re-serialised whole, because a run that dies
 halfway has still spent the money. A format that rewrites the file to add a line can lose

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/docs/codewiki/the-stage-registry.md

@@ -5,9 +5,14 @@ builds its sub-commands from it, `workspace` checks order against it, and `skill
 generates the published tables out of it. Reading the file tells you what it holds;
 this page is why it holds it there rather than in the stages.
 
+It is three files. `registry.py` is the two dataclasses a stage is described with,
+`catalog.py` is the table itself — four fifths of the whole by line count and none of
+its behaviour — and `__init__.py` is the lookup, which is what a reader of the registry
+came for.
+
 ## An option is declared by the registry, not by the stage that takes it
 
-[src/spritegen/stages/__init__.py:21-35]()
+[src/spritegen/stages/registry.py:12-26]()
 
 The obvious place for `--size` is inside `anchor`. It is here instead because `--help`
 has to be complete, and building help from the stages would mean importing five modules
@@ -16,7 +21,7 @@ value off the parsed namespace and knows nothing about how it was parsed.
 
 ## `requires` is any-one-of, because the pipeline forks
 
-[src/spritegen/stages/__init__.py:38-43]()
+[src/spritegen/stages/registry.py:29-54]()
 
 `motion` and `video` produce the same artifact by different routes, and `matte` takes
 whichever ran. A field meaning *all of these* would have no way to express that, and the
@@ -24,7 +29,7 @@ fork is the shape of the tool rather than an exception in it.
 
 ## Kind and variant, once the stage stopped being the artifact
 
-[src/spritegen/stages/__init__.py:44-67]()
+[src/spritegen/stages/registry.py:29-59]()
 
 `produces` was the stage's name for as long as a stage made one thing. `anchor` makes an
 anchor, box art or an icon; `board` closes one set of frames into as many art directions
@@ -38,7 +43,7 @@ Both name an option this stage already declares, and neither is turned into a pa
 
 ## Order is derived, and there is no list of it
 
-[src/spritegen/stages/__init__.py:440-473]()
+[src/spritegen/stages/__init__.py:43-63]()
 
 `order` walks the table rather than reading a sequence somebody maintained beside it. A
 second record of the pipeline's shape would be the one that goes stale the first time a
@@ -46,7 +51,7 @@ stage is added.
 
 ## The module is resolved only when the command has been chosen
 
-[src/spritegen/stages/__init__.py:476-490]()
+[src/spritegen/stages/__init__.py:66-80]()
 
 This is the reason the registry can describe the whole pipeline without importing Pillow,
 numpy or `fal_client`. It also decides the blast radius of a broken stage: an import

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/docs/codewiki/the-workspace.md

@@ -6,7 +6,7 @@ refusing things.
 
 ## Every upward search stops, and the stop is the security control
 
-[src/spritegen/workspace.py:72-103]()
+[src/spritegen/workspace.py:70-101]()
 
 A command is typed from wherever is convenient, so searching upward for the project is
 right. Searching upward without a ceiling reaches the filesystem root, and everything
@@ -16,7 +16,7 @@ directory nobody chose to configure this tool.
 
 ## Where the assets are, and why the order is the design
 
-[src/spritegen/workspace.py:105-140]()
+[src/spritegen/workspace.py:103-138]()
 
 The explicit variable wins first, which is what lets a test and a second collection of
 characters exist at all. The nearest existing `spritegen/assets/` comes next because that
@@ -25,9 +25,9 @@ else's, so the images belong to that project rather than to the tool.
 
 ## A name off a command line becomes a directory
 
-[src/spritegen/workspace.py:51-70]()
+[src/spritegen/workspace.py:49-68]()
 
-[src/spritegen/workspace.py:142-170]()
+[src/spritegen/workspace.py:140-168]()
 
 The forbidden set and the reserved names are Windows', and they are checked on every
 platform. An asset name arrives from an argument or from a state file written earlier,
@@ -36,7 +36,7 @@ on Windows — which is why CI runs the suite on three operating systems rather
 
 ## Kind, variant and version become a path in exactly one place
 
-[src/spritegen/workspace.py:440-469]()
+[src/spritegen/workspace.py:476-505]()
 
 Every stage writes through this. That is what let layout 1 become layout 2 without each
 stage learning about the move, layout 2 become layout 3 the same way, and it is what
@@ -44,9 +44,9 @@ stage learning about the move, layout 2 become layout 3 the same way, and it is
 
 ## Which version a run writes, and which one it reads
 
-[src/spritegen/workspace.py:491-505]()
+[src/spritegen/workspace.py:527-541]()
 
-[src/spritegen/workspace.py:650-692]()
+[src/spritegen/workspace.py:667-684]()
 
 Two records go into picking a number and neither is trusted over the other: what the
 state file recorded, and what is on disk. They disagree when a run died between writing
@@ -64,7 +64,7 @@ has none, so a re-run cannot re-aim the paid stages that follow it — that is
 
 ## A recorded path is not trusted
 
-[src/spritegen/workspace.py:511-534]()
+[src/spritegen/workspace.py:547-570]()
 
 The state file holds relative paths, and it is a file on disk that something else may
 have written. `inside` is the check that a recorded path still resolves within the asset
@@ -73,7 +73,7 @@ another asset's output because the state said so.
 
 ## What "ready" means when `requires` forks
 
-[src/spritegen/workspace.py:378-418]()
+[src/spritegen/workspace.py:414-454]()
 
 `satisfied` is where the registry's any-one-of semantics turn into a decision, and
 `next_stages` is what `status` prints. Both read the registry; neither keeps a copy of

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/docs/glossary.md

@@ -9,6 +9,9 @@ directory `row/` to `sheet/as-is/` — retired a spelling whose word is still in
 use elsewhere, and listing it would report every correct use as a finding. Add an
 `Avoid:` the first time a genuinely dead, distinctive name turns up.
 
+- **workspace** — a directory holding `.spritegen.json`, and the assets under `spritegen/assets` inside it. One machine carries several, and a command uses the nearest one at or above where it was typed.
+- **workspace root** — the directory the marker is in, which is what `status` names and what `init` creates in. Not the assets directory, which sits inside it.
+- **marker** — `.spritegen.json`: the file that says a directory is a workspace, and holds that workspace's settings. Avoid: config file, settings file
 - **asset** — everything belonging to one character, under `assets/<name>/`. The unit `new`, `status`, `show` and `cost` all talk about, and the reason no stage takes an input or output path.
 - **state file** — `state.json` inside an asset, the only record of progress. It holds the stages that have completed, never what should happen next.
 - **stage** — one step of the pipeline, declared in `stages.STAGES` and implemented by the module of the same name. Most spend money; `board` does not.

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/docs/notes.md

@@ -41,3 +41,7 @@ over this file answers with the example above as well as with the notes. -->
 - n-0001 2026-08-28 #gotcha @src/spritegen/workspace.py — Context.version is resolved on the first ask for out and kept, so a stage that opens its output twice in one run writes both halves to the same version
 - n-0002 2026-08-28 #gotcha @tests/conftest.py — settings.DEFAULT_CACHE is built from Path.home() at import, so conftest moving home afterwards does not move the cache; the suite points SPRITEGEN_CACHE at a temporary directory instead
 - n-0003 2026-08-28 #gotcha @pyproject.toml — the assets root spritegen/ in the repo root shadows the package name, so coverage source=[spritegen] resolves to the empty assets directory and collects nothing — source_pkgs is the unambiguous form
+- n-0004 2026-08-28 #gotcha @src/spritegen/sheet.py — the GIF preview writes one global palette plus one shared local palette whatever the frames were quantised with — Pillow unifies on save, so quantising per frame and quantising the strip produce the same file
+- n-0005 2026-08-28 #gotcha @src/spritegen/upscale.py — the weight cache sidecar must stay a content hash — size and mtime are forgeable with the same write access a swap needs, so a stat-based fast path silently disables the check
+- n-0006 2026-08-28 #gotcha @docs/codewiki/the-workspace.md — a codewiki citation that still resolves after a refactor is not still correct — the range shifts onto a neighbouring function and validate cannot tell, so check what each range opens on
+- n-0007 2026-08-29 #gotcha @src/spritegen/__init__.py — the CLI version came from a hand-written __version__ in spritegen/__init__.py, a second copy of what pyproject.toml declares — it read 0.1.0 through three releases; it is importlib.metadata now and a test pins the two together

spritegen_cli-0.4.0/plans/code-health.md

@@ -0,0 +1,119 @@
+---
+autonomy: auto
+ci: wait
+status: approved
+pr: per-group
+merge: auto
+checksum: a381e0be7b8276b7d56f6be879477d27acc6bab7600bae8957b6bee7d8d0b577
+---
+
+# Code health
+
+Clear what a full read of `src/` and `tests/` turned up: ten defects, seven places
+that repeat work already done, four modules that carry more than one job, and a test
+suite that pays for video encoding no assertion reads.
+
+## Why
+
+None of this was found by a failure — the suite is green and has been. It is what a
+deliberate read found sitting under green tests, which is why it is worth landing as
+one piece of work rather than waiting for each item to announce itself. Three of the
+defects lose something a user cannot get back: a paid call whose ledger line is never
+written, a re-fetch that deletes the good file it was going to replace, and a weight
+file that stops being checked the moment its digest sidecar goes missing. The rest is
+waste that compounds — a 64 MB model re-read per image, a colour count that allocates
+one tuple per pixel of an upscaled frame, twenty-five tests re-encoding the same clip
+at the slowest x264 preset. Done when the defects are fixed with tests that would have
+caught them, the repeated work happens once, the four oversized modules are split
+along the seams the survey mapped, and the suite is faster with no coverage lost.
+
+## Paths
+
+- `src/spritegen/` — `workspace.py`, `fal.py`, `upscale.py`, `imaging.py`, `clip.py`,
+  `drive.py`, `matting.py`, `sheet.py`, `cli.py`, `atlas.py`, `ledger.py`
+- `src/spritegen/stages/` — `__init__.py`, `motion.py`, `pose.py`, `video.py`,
+  `anchor.py`, `matte.py`, `board.py`
+- `src/spritegen/skill/__init__.py`
+- `tests/` — `conftest.py`, `helpers.py`, `test_motion.py`, `test_video.py`
+
+## References
+
+- `adr:0003-append-only-jsonl-ledger` — one line per paid call, carrying the sha256 of
+  every file written. Task 1.1 cannot hold to both halves at once and supersedes it.
+- `adr:0006-centralise-configuration-and-never-cache-it` — nothing is cached and
+  `load()` builds a new object every call. Task 3.5 resolves once per command and
+  passes it down, which is the shape that ADR permits; a module-level cache is not.
+- `adr:0004-allow-list-every-downloaded-host` — the host check task 1.9 walks results
+  for.
+- `adr:0007-heavy-dependencies-are-optional-extras` — why `available()` exists at all,
+  which task 4.7 decides the fate of.
+
+## Out of scope
+
+- The unbounded recursion in `fal.seed_in` and `fal.urls_in`: a hostile response nested
+  a thousand levels deep raises `RecursionError` after billing. Hosts are allow-listed
+  and the impact is one denied run; it is filed on PR #17 and belongs with a review of
+  what else trusts endpoint JSON shape.
+- Introducing `ruff format`. No formatter is configured here and adding one rewrites
+  the tree in a commit nobody can read.
+- Raising the coverage floor. The real number is 91.36% against a floor of 86, but it
+  has been there for one day.
+
+## Tasks
+
+- [x] 1.1 (TDD) Record the paid call in the ledger before the files it writes, and supersede `adr:0003` with the two-line shape
+- [x] 1.2 (TDD) Download to a partial file and rename on success, so a failed re-fetch cannot delete the good file
+  _Depends 1.1_
+- [x] 1.3 (TDD) Write the weight digest when the sidecar is missing, and stop the `finally` arm deleting a completed download
+- [x] 1.4 (Unit) Default `--device` to `None` so the setting is reachable and a dry run names the device the real run will use
+- [x] 1.5 (Unit) Make `matte --mask` on the local backend either write the mask or say it cannot
+- [ ] 1.6 (Unit) Quantise the GIF preview once over the strip instead of a palette per
+      frame
+  _Status removed_
+  _Reason measured against the parity fixture: Pillow already writes one global palette plus one shared local palette whatever the frames were quantised with, so the per-frame ADAPTIVE call produces the same two palettes the strip does — the change grew the file by 800 bytes, altered no palette, and broke a documented parity baseline_
+- [x] 1.7 (Unit) Map transport, codec and OS errors to exit codes, and narrow the catch that turns an internal bug into a user message
+- [x] 1.8 (Unit) Name the file when `state.json` does not parse
+- [x] 1.9 (Unit) Keep walking under a `url` key whose value is not a string
+- [x] 1.10 (Unit) Generate the skill's free-command table from the parser instead of maintaining a second copy
+- [x] 2.1 (Unit) Build the upscale network once per command and pass it to each file
+- [x] 2.2 (Unit) Count colours before the upscale and without a tuple per pixel
+- [x] 2.3 (TDD) Choose the wanted frame indices before decoding, and keep only those
+- [ ] 2.4 (Unit) Re-hash a cached weight only when its size or mtime changed
+  _Status removed_
+  _Reason the win it chased was already delivered by 2.1 — with the network built once per command the weight is hashed once per command either way — and the mechanism defeated the integrity check beside it: size and mtime are forgeable with the same write access the attack needs, so a matching stamp let a swapped weight through unhashed and silent_
+- [x] 2.5 (Unit) Resolve settings once per command and pass them down, adding no cache
+  _Depends 1.4_
+- [x] 2.6 (Unit) Measure alpha in memory, read the sheet once per build, and skip the crops a run without a GIF throws away
+- [x] 2.7 (Unit) Compare found against recorded with sets, not lists
+- [x] 3.1 (Unit) Move the stage catalogue out of `stages/__init__.py` into its own module
+- [ ] 3.2 (Unit) Declare the chroma, prompt, reference and frame-extraction options once
+      and splice them into each stage
+  _Depends 3.1_
+  _Status removed_
+  _Reason only the chroma and despill cluster was duplicated verbatim, and that is done. The prompt, reference and frame-extraction options share flags, kinds and defaults but not their help text: motion explains that the driving cycle caps --frames and video explains that an image-to-video clip opens on a still input image, which is the part of an option worth having. Replaced by 3.8_
+- [x] 3.3 (Unit) Give `Context` the anchor lookup the three stages copy, and drop the cross-stage import
+- [x] 3.4 (Unit) Extract the reference-file check, the missing-URL guard and the chroma finish that each exist three or four times
+  _Depends 3.3_
+- [x] 3.5 (Unit) Extract the layout refusal and the artifact-key composition to one place each
+- [x] 3.6 (Unit) Have the two grid packers share their arithmetic
+- [x] 3.7 (Unit) Split `workspace.py` along the seams the survey mapped, presentation first
+  _Depends 3.3, 3.5_
+- [x] 4.1 (Unit) Delete what nothing calls, and decide whether the availability helpers get a caller or go
+- [x] 5.1 (Unit) Stop the motion tests encoding at 720 and the slowest preset
+- [ ] 5.2 (Unit) Share the cache across the session so the same driving clip encodes
+      once
+  _Depends 5.1_
+  _Status removed_
+  _Reason measured after 5.1: an encode is 20ms at the cell size the tests now use, so sharing the cache across the session saves about 1s of a 20.8s suite, bought with mutable state shared across 799 tests against the one fixture whose purpose is isolating them_
+- [x] 5.3 (Unit) Move the fixtures copied across eleven files into `conftest.py`
+  _Depends 5.1_
+- [x] 3.8 (Unit) Declare the chroma and despill options once and splice them into the
+      three stages that cut
+  _Reason 3.2 asked for four option groups and only one of them was duplication; this is what was actually built_
+
+## Done when
+
+- `uv run pytest -q --cov` passes with coverage no lower than 91.36%.
+- `uv run ruff check src tests` and `scc validate` both exit 0.
+- Every task above is ticked or struck out with a reason.
+- The suite's wall-clock time is lower than the 34 s it takes now, measured the same way.

{spritegen_cli-0.2.0 → spritegen_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spritegen-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Sprite generation CLI — a few AI-generated images into a game-ready character sheet"
 requires-python = ">=3.13"
 

spritegen_cli-0.4.0/specs/workspace-config/design.md

@@ -0,0 +1,98 @@
+# Workspace configuration — design
+
+## What changes, and where
+
+Today a workspace is found by looking for a directory that happens to be named
+`spritegen/assets`, walking up from the working directory. That has no marker, so the
+walk cannot tell a workspace from a coincidence — and it reaches the home directory,
+where one workspace becomes every project's. Run from `~/spritegen1/test1`, `init`
+reported a workspace at `~/spritegen/assets`, which belongs to something else.
+
+The change is a marker. `.spritegen.json` at the root of a workspace says *this is
+one*, the way `package.json` does for npm and `pyproject.toml` for this repository. The
+walk stops at the nearest one, so a second project one directory over is a second
+workspace, and nothing has to be configured for that to be true.
+
+The same file carries the settings, which is the other half: a credential and a cell
+size belong to the project they are for, not to the shell that happened to run the
+command.
+
+- `settings.py` — a source between the environment and `.env`, and the search that
+  finds it.
+- `workspace.py` — `assets_root` resolves through the marker rather than by looking for
+  a directory of the right name.
+- `skill/__init__.py` — `cmd_init` creates in the working directory and writes the file.
+
+## The order settings are read in
+
+Highest wins:
+
+1. **The environment.** `SPRITEGEN_CELL=200 spritegen board …` still overrides for one
+   run, which is `adr:0006`'s reason and does not change.
+2. **`.spritegen.json`** at the workspace root — the new one, and where a project's own
+   answer belongs.
+3. **The nearest `.env`** — kept, because a machine with one `FAL_KEY` for everything is
+   a real setup and breaking it buys nothing.
+4. **The declared default.**
+
+A name in the file that is not a setting is refused rather than ignored: a typo that
+does nothing is worse than one that says so, and this is the file a `fal_key` is
+misspelled in.
+
+## The file
+
+```json
+{
+  "fal_key": "…",
+  "cell": 166,
+  "matte_backend": "local"
+}
+```
+
+Every field is a `Settings` field under its own name, without the `SPRITEGEN_` prefix
+the environment uses — the prefix exists to keep a shared namespace apart, and a file
+of this tool's own has no such namespace to share.
+
+## The credential, and git
+
+`init` writes the file with no credential in it, and adds it to `.gitignore` where one
+exists. It cannot add it where there is no `.gitignore`: writing one is a decision
+about a repository this tool does not own.
+
+That leaves the case the guard is for — a `.spritegen.json` somebody committed before
+putting a key in it. `git ls-files --error-unmatch` answers whether it is tracked in one
+call and needs no repository when there is none, so a warning is cheap. It warns and
+proceeds: refusing would make the tool unusable in exactly the situation somebody is
+trying to fix.
+
+## What a file may point at
+
+A path out of this file is **relative to the workspace and resolved under it** — R4.4,
+R4.5. The environment keeps the unrestricted form, and the difference is who decided:
+exporting a variable takes a shell, while this file arrives by being cloned, extracted,
+or synced onto a mounted drive, and is then read for no reason but the command having
+been run in that directory.
+
+The reachable case is worse than a redirected output directory. `Path.is_dir()` on
+`\host\share` opens an SMB connection and authenticates, so `status` — free, and
+touching no network — would hand a credential to whoever wrote the file. So rooted
+counts, not only absolute: on Windows `/etc/x` carries no drive and is not
+`is_absolute()`, and it leaves the workspace all the same.
+
+**`allowed_hosts` becomes settable from a file inside the project**
+(`adr:0004-allow-list-every-downloaded-host`). That is the same reach a `.env` already
+had, and the ceiling in R1.5 is what bounds both — worth stating rather than
+discovering.
+
+## What this supersedes
+
+`adr:0006-centralise-configuration-and-never-cache-it` names the environment, the
+nearest `.env` and the default as the three sources, in that order. It gains a fourth
+between the first two, and its other decisions — one class, nothing cached, the ceiling
+— stand. A new record supersedes it on the source list alone.
+
+## Not decided here
+
+Whether `.env` is eventually dropped. Two files for one job is one too many, but
+removing one while adding the other would break every machine that has a key today,
+and nothing forces the choice now.

spritegen_cli-0.4.0/specs/workspace-config/requirements.md

@@ -0,0 +1,50 @@
+---
+autonomy: auto
+ci: wait
+branch: feat/workspace-config
+delivery: in-review
+pr: 24
+---
+
+# Workspace configuration — requirements
+
+A workspace is marked by a file it holds, so one machine can carry several and a
+command run inside one never reaches into another.
+
+## R1 — where the workspace is
+
+- **R1.1** The system shall treat a directory holding `.spritegen.json` as a workspace root.
+- **R1.2** When a command needs a workspace, the system shall use the nearest workspace root at or above the working directory.
+- **R1.3** If no workspace root is at or above the working directory, then the system shall refuse and name `spritegen init`.
+- **R1.4** While a workspace root is in use, the system shall keep the assets under `<root>/spritegen/assets`.
+- **R1.5** The system shall stop the upward search at the first repository boundary or at the home directory.
+
+## R2 — opening one
+
+- **R2.1** When `init` runs, the system shall create the workspace in the working directory.
+- **R2.2** When `init` creates a workspace, the system shall write `.spritegen.json` in that directory.
+- **R2.3** Where a `.gitignore` is at the workspace root, the system shall add `.spritegen.json` to it.
+- **R2.4** If a workspace root is already at or above the working directory, then the system shall name it and create the new one anyway.
+- **R2.5** If `.spritegen.json` is already in the working directory, then the system shall leave its contents alone.
+
+## R3 — what configuration is read
+
+- **R3.1** The system shall read its settings from `.spritegen.json` at the workspace root.
+- **R3.2** Where a setting is in the environment, the environment shall win over the file.
+- **R3.3** Where a setting is in neither, the system shall use the `.env` the search finds, and then the default.
+- **R3.4** If `.spritegen.json` does not parse, then the system shall refuse naming the file and the reason.
+- **R3.5** If `.spritegen.json` holds a name that is not a setting, then the system shall refuse naming it.
+- **R3.6** The system shall build its settings fresh on every read and cache nothing.
+
+## R4 — the key in it
+
+- **R4.1** Where `.spritegen.json` holds `fal_key`, the system shall use it as the credential.
+- **R4.2** When `init` writes `.spritegen.json`, the system shall write no credential into it.
+- **R4.3** If `.spritegen.json` is tracked by git, then the system shall warn that a credential in it is committed.
+- **R4.4** (ADDED) Where `.spritegen.json` sets a path, the system shall resolve it under the workspace root.
+- **R4.5** (ADDED) If `.spritegen.json` sets a path that is absolute, rooted or outside the workspace, then the system shall refuse it.
+
+## R5 — saying which one
+
+- **R5.1** When `status` runs, the system shall name the workspace root it is using.
+- **R5.2** When `init` finishes, the system shall name the directory it created.

spritegen_cli-0.4.0/specs/workspace-config/tasks.md

@@ -0,0 +1,25 @@
+# Workspace configuration — tasks
+
+## Tasks
+
+- [x] 1.1 (TDD) Find the workspace root by the marker file, bounded by the ceiling — R1.1, R1.2, R1.5
+- [x] 1.2 (Unit) Resolve the assets under the root the marker names, and refuse when there is none — R1.3, R1.4
+  _Depends 1.1_
+- [x] 2.1 (TDD) Read `.spritegen.json` between the environment and `.env`, refusing a name that is not a setting — R3.1, R3.2, R3.3, R3.4, R3.5, R3.6
+  _Depends 1.1_
+- [x] 2.2 (Unit) Take the credential from the file — R4.1
+  _Depends 2.1_
+- [x] 3.1 (Unit) Create the workspace where `init` was run, and write the marker with no credential in it — R2.1, R2.2, R2.4, R2.5, R4.2, R5.2
+  _Depends 1.2_
+- [x] 3.2 (Unit) Add the marker to a `.gitignore` that is there — R2.3
+  _Depends 3.1_
+- [x] 3.3 (Unit) Warn when the marker is tracked by git — R4.3
+  _Depends 3.1_
+- [x] 4.1 (Unit) Name the workspace root in `status` — R5.1
+  _Depends 1.2_
+- [x] 4.2 (Unit) Record the decision as an ADR superseding `adr:0006` on its source list, and the term in the glossary — R3.1
+  _Depends 2.1_
+- [x] 3.4 (Unit) Stop the skill search climbing into the home directory's .claude — R1.5
+  _Reason the same defect in the other search: the docstring says it is bounded and it is not, so init in a fresh project reported the global skill as already there and set that project up with none_
+- [x] 2.3 (Unit) Bound a path the marker sets to the workspace it is in — R4.4, R4.5
+  _Reason security review: a hostile marker could point assets at a UNC path, and stat on a share authenticates, so status alone leaked a credential_