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

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

@@ -223,3 +223,6 @@ assets/
 
 # ai-jail sandbox configuration, local to a checkout
 .ai-jail
+
+# the spritegen workspace's own settings, and its key
+.spritegen.json

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spritegen-cli
-Version: 0.3.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.3.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/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.3.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.3.0 → spritegen_cli-0.4.0}/docs/notes.md

@@ -44,3 +44,4 @@ over this file answers with the example above as well as with the notes. -->
 - 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.3.0 → spritegen_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spritegen-cli"
-version = "0.3.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_

spritegen_cli-0.4.0/src/spritegen/__init__.py

@@ -0,0 +1,27 @@
+"""Turn a handful of images into a game-ready character sheet, one stage at a time."""
+
+_VERSION: str | None = None
+
+
+def __getattr__(name: str) -> str:
+    """`__version__`, read from the installed metadata the first time it is asked for.
+
+    Not a constant: it was one, written out by hand, and it read 0.1.0 through two
+    releases that had bumped `pyproject.toml` — the declaration is the only record now.
+
+    Resolved lazily because `importlib.metadata` reads dist-info off disk, and every
+    command builds the parser: `--help`, `status` and `cost` would each pay some thirty
+    milliseconds for a string only `--version` prints.
+    """
+    global _VERSION
+    if name != "__version__":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    if _VERSION is None:
+        from importlib.metadata import PackageNotFoundError
+        from importlib.metadata import version as installed
+
+        try:
+            _VERSION = installed("spritegen-cli")
+        except PackageNotFoundError:  # pragma: no cover - a checkout nobody installed
+            _VERSION = "0.0.0+source"
+    return _VERSION

{spritegen_cli-0.3.0 → spritegen_cli-0.4.0}/src/spritegen/cli.py

@@ -22,7 +22,22 @@ import os
 import sys
 from collections.abc import Sequence
 
-from . import __version__, stages
+from . import stages
+
+
+class _PrintVersion(argparse.Action):
+    """`--version`, resolved when it is asked for rather than when the parser is built.
+
+    Every command builds the parser, and reading the installed metadata costs real
+    milliseconds — see the module `__getattr__` this defers to.
+    """
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        from . import __version__
+
+        # stdout and exit 0, which is where argparse's own version action puts it.
+        print(f"spritegen {__version__}")
+        parser.exit()
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -31,7 +46,7 @@ def build_parser() -> argparse.ArgumentParser:
         prog="spritegen",
         description="Turn a handful of images into a character sheet, one stage at a time.",
     )
-    parser.add_argument("--version", action="version", version=f"spritegen {__version__}")
+    parser.add_argument("--version", action=_PrintVersion, nargs=0, help="print the version")
     sub = parser.add_subparsers(dest="command", metavar="<command>")
 
     new = sub.add_parser("new", help="open a new asset")

{spritegen_cli-0.3.0 → spritegen_cli-0.4.0}/src/spritegen/report.py

@@ -39,16 +39,39 @@ def cmd_status(args: argparse.Namespace) -> int:
     console this tool cannot encode into drops the line rather than raising where
     anyone would see it.
     """
+    from . import settings
+
     root = assets_root()
     as_json = getattr(args, "json", False)
+    # Which workspace answered, by name — R5.1. A machine carries several now, and
+    # "no assets here" is a different sentence from "the workspace you meant is
+    # elsewhere": the second one is what a command run in the wrong directory needs.
+    declared = settings.workspace_root()
 
     if not root.is_dir():
         if as_json:
-            print(json.dumps({"root": str(root), "workspace": False, "assets": []}, indent=2))
+            print(
+                json.dumps(
+                    {
+                        "root": str(root),
+                        "workspace": False,
+                        "declared_at": str(declared) if declared else None,
+                        "assets": [],
+                    },
+                    indent=2,
+                )
+            )
             return 0
         print(f"no spritegen workspace at {root}; run `spritegen init` to make one")
         return 0
 
+    if not as_json:
+        # Only where a marker actually said so. `root.parent.parent` guessed the shape
+        # `<root>/spritegen/assets`, which is wrong for SPRITEGEN_ASSETS pointing
+        # anywhere and for the one-level legacy `assets/` — and a wrong directory printed
+        # under this heading reads as authoritative.
+        print(f"workspace {declared}" if declared else f"assets {root}")
+
     # Resolved once, at the top of the command, and passed down from here: every asset,
     # and every version inside each one, would otherwise rebuild it from the environment.
     names = known(root)
@@ -58,6 +81,7 @@ def cmd_status(args: argparse.Namespace) -> int:
                 {
                     "root": str(root),
                     "workspace": True,
+                    "declared_at": str(declared) if declared else None,
                     "assets": [inspect(name, root) for name in names],
                 },
                 indent=2,