spawnio 1.0.8__tar.gz → 1.0.9__tar.gz

{spawnio-1.0.8 → spawnio-1.0.9}/CONTRIBUTING.md

@@ -35,6 +35,15 @@ uv run pytest --cov=src/spawn --cov-report=term-missing
 
 ---
 
+## Testing and fixtures
+
+- **Factory:** the `spawn_project` fixture in `tests/conftest.py` generates a project offline: `spawn_project("backend-api", framework="fastapi")` returns its `Path`. The `no_toolchain` fixture stubs git, uv and package installs.
+- **Golden trees:** `tests/fixtures/trees/<archetype>.txt` lists every file of a generated archetype. After an intentional output change, regenerate with `SPAWN_UPDATE_TREES=1 uv run pytest tests/test_fixtures.py` and review the diff.
+- **Offline rule:** tests must not use the network, real `git` or real `uv`; use `no_toolchain`.
+- **Adding an archetype:** add an entry to `tests/fixtures/archetypes.py`, run once with `SPAWN_UPDATE_TREES=1` to create its golden tree, and review it.
+
+---
+
 ## Linting and formatting
 
 ```bash
@@ -126,7 +135,7 @@ Add two test files mirroring the existing pattern:
 | File | What to test |
 |---|---|
 | `tests/test_<slug>_template.py` | Template constants, `get_dependencies()`, `get_readme_content()`, `py_compile` on each Python starter file, no unescaped braces |
-| `tests/test_<slug>_generator.py` | `ProjectGenerator().generate()` with mocked uv/git/install, directory structure, README content, `.spawn/meta.json` fields |
+| `tests/test_<slug>_generator.py` | `generate_project(config)` (or `ProjectGenerator().generate()`) with mocked uv/git/install, directory structure, README content, `.spawn/meta.json` fields |
 
 See `tests/test_mcp_server_template.py` and `tests/test_mcp_server_generator.py` for the exact mock patterns (`_mock_uv_and_install()` context manager, `_cfg()` helper, `patch.object(MyTemplate, "post_install")`).
 

{spawnio-1.0.8 → spawnio-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spawnio
-Version: 1.0.8
+Version: 1.0.9
 Summary: Spawn a ready-to-use Python project in seconds
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -144,7 +144,7 @@ Running `spawn` with no arguments shows the banner, the installed version, and t
 
 ```
 SPAWN — scaffold your next project
-v1.0.8
+v1.0.9
 
 Commands
   create    Scaffold a new project
@@ -710,7 +710,7 @@ spawn create --name my-api --template backend-api --framework fastapi --extras r
 spawn create --config spawn.json
 ```
 
-`--config` takes precedence over individual flags. Add `--dry-run` to either form to validate the config and print it without creating any files.
+`--config` takes precedence over individual flags (an explicit `--no-git`/`--no-uv` is ignored with a warning). Add `--dry-run` to either form to validate the config and print it without creating any files.
 
 > Custom Structure is interactive-only in this version.
 
@@ -791,7 +791,7 @@ spawn doctor --fix --license mit
 
 ```bash
 spawn version
-# → Spawn v1.0.8
+# → Spawn v1.0.9
 ```
 
 ### Publish to GitHub
@@ -825,6 +825,7 @@ All tests should pass. If they don't, please [open an issue](https://github.com/
 
 | Version | Highlight |
 |---|---|
+| **v1.0.9** | Core hardening: documented exit-code contract (generation, toolchain and publish failures exit non-zero), `--no-uv` honored for templates (file-only extras still written), path-traversal protection for custom structures, `read_project_metadata` extension boundary |
 | **v1.0.8** | `spawn doctor --fix` (`--dry-run`, `--yes`, `--license`), `--license` flag and prompt on `create`, `CHANGELOG.md` generated for every project, `pre-commit` and `mypy` extras across all templates, Custom Structure Mypy option |
 | **v1.0.7** | Fixed UTF-8 console crash on Windows when stdout is redirected/piped, added Windows reserved device name validation (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`9`, `LPT1`–`9`), clarified Python 3.12 requirement |
 | **v1.0.6** | Removed duplicate banner from `spawn create`; `spawn` alone now shows the banner and command overview |

{spawnio-1.0.8 → spawnio-1.0.9}/README.md

@@ -133,7 +133,7 @@ Running `spawn` with no arguments shows the banner, the installed version, and t
 
 ```
 SPAWN — scaffold your next project
-v1.0.8
+v1.0.9
 
 Commands
   create    Scaffold a new project
@@ -699,7 +699,7 @@ spawn create --name my-api --template backend-api --framework fastapi --extras r
 spawn create --config spawn.json
 ```
 
-`--config` takes precedence over individual flags. Add `--dry-run` to either form to validate the config and print it without creating any files.
+`--config` takes precedence over individual flags (an explicit `--no-git`/`--no-uv` is ignored with a warning). Add `--dry-run` to either form to validate the config and print it without creating any files.
 
 > Custom Structure is interactive-only in this version.
 
@@ -780,7 +780,7 @@ spawn doctor --fix --license mit
 
 ```bash
 spawn version
-# → Spawn v1.0.8
+# → Spawn v1.0.9
 ```
 
 ### Publish to GitHub
@@ -814,6 +814,7 @@ All tests should pass. If they don't, please [open an issue](https://github.com/
 
 | Version | Highlight |
 |---|---|
+| **v1.0.9** | Core hardening: documented exit-code contract (generation, toolchain and publish failures exit non-zero), `--no-uv` honored for templates (file-only extras still written), path-traversal protection for custom structures, `read_project_metadata` extension boundary |
 | **v1.0.8** | `spawn doctor --fix` (`--dry-run`, `--yes`, `--license`), `--license` flag and prompt on `create`, `CHANGELOG.md` generated for every project, `pre-commit` and `mypy` extras across all templates, Custom Structure Mypy option |
 | **v1.0.7** | Fixed UTF-8 console crash on Windows when stdout is redirected/piped, added Windows reserved device name validation (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`9`, `LPT1`–`9`), clarified Python 3.12 requirement |
 | **v1.0.6** | Removed duplicate banner from `spawn create`; `spawn` alone now shows the banner and command overview |

{spawnio-1.0.8 → spawnio-1.0.9}/docs/architecture.md

@@ -23,7 +23,7 @@ Entry point: `spawn.cli.app:main` (defined in `pyproject.toml` as `[project.scri
 
 ```
 src/spawn/
-├── __init__.py         # __version__ via importlib.metadata, fallback "1.0.8"
+├── __init__.py         # __version__ via importlib.metadata, fallback "1.0.9"
 ├── cli/
 │   ├── app.py          # Typer app: create, version, doctor commands
 │   ├── noninteractive.py # Build config from CLI flags or JSON config file
@@ -76,14 +76,18 @@ src/spawn/
 ### 4a. Project Creation Flow
 
 1. User runs `spawn create`
-2. `app.create()` calls `show_banner()`
-3. `get_project_config()` collects name, template, framework, extras, and Git preference
-4. `ProjectGenerator.generate()` resolves the template via `instantiate_template(config)`,
-   creates directories, writes starter files, writes README and `.gitignore`, runs
-   `initialize_git()` (if enabled), `initialize_uv()`, `install_packages()`, `post_install()`,
-   and writes `.spawn/meta.json`
-5. `show_success()` renders the success panel using `template_obj.next_steps`
-6. If Git was enabled, optionally `GitHubPublisher.publish()` stages, commits, and pushes
+2. `app.create()` builds a `ProjectConfig`:
+   - non-interactive (`--name` or `--config`): `cli/noninteractive.py` calls `core/planning.py::plan_project`, which validates the name, rejects an existing destination, and resolves template options, extras and license. Config-file mode ignores explicit `--no-git`/`--no-uv` with a warning.
+   - interactive: `cli/prompts.py::get_project_config()` collects the answers (menus derived from the registry) and builds the config directly
+3. `--dry-run` prints the resolved config and stops; nothing is written
+4. `generators/pipeline.py::generate_project(config)` dispatches on `config.template`:
+   `ProjectGenerator.generate()` for registry templates, `CustomStructureGenerator.generate()` for `"custom"`
+5. Both generators call `generators/destination.py`: `resolve_destination` (single-directory name check), `assert_available` (fails with `FilesystemError` if the path exists in any form, including symlinks) and, for custom structures, `safe_join` (rejects traversal and absolute paths)
+6. `ProjectGenerator` resolves the template via `instantiate_template(config)`, creates directories, writes starter files, README and `.gitignore`, runs `initialize_git()`, `initialize_uv()`, `install_packages()` and `post_install()` (the uv steps are skipped with `--no-uv`; file-only extras are still written and the rest are reported in one "Skipped without uv" warning), then `generators/metadata.py::write_project_meta`
+7. `show_success()` renders the success panel
+8. If Git was enabled and not in non-interactive/`--yes` mode, optionally `GitHubPublisher.publish()` stages, commits, and pushes
+
+**Cleanup rule:** on any failure a generator removes the project directory only if that run created it (`destination.cleanup_created`, which also refuses symlinks, the cwd and its parents, the home directory and filesystem roots). A pre-existing directory is never touched.
 
 ```
 spawn create
@@ -92,26 +96,23 @@ spawn create
 show_banner()                 banner.py
     │
     ▼
-get_project_config()          prompts.py
-    │  → ProjectConfig (name, template, framework, extras, use_git)
+plan_project()                planning.py    (flags / --config)
+get_project_config()          prompts.py     (interactive)
+    │  → ProjectConfig
     ▼
-ProjectGenerator.generate()   project_generator.py
-    ├── instantiate_template()  registry.py  (forwards framework + extras)
-    ├── mkdir + write files     templates/
-    ├── write README.md         shared_content.py
-    ├── write .gitignore        shared_content.py
-    ├── initialize_git()        git.py         (if use_git)
-    ├── initialize_uv()         uv.py
-    ├── install_packages()      uv.py          (if deps non-empty)
-    ├── post_install()          template       (ruff/pytest config, Docker, CI)
-    └── write .spawn/meta.json
+generate_project()            pipeline.py
+    ├── ProjectGenerator / CustomStructureGenerator
+    │     ├── resolve_destination + assert_available   destination.py
+    │     ├── instantiate_template()  registry.py  (forwards framework + extras)
+    │     ├── mkdir + write files, README, .gitignore
+    │     ├── initialize_git()        git.py         (if use_git)
+    │     ├── initialize_uv() / install_packages()   (if use_uv)
+    │     └── post_install()          template       (ruff/pytest config, Docker, CI)
+    └── write_project_meta()    metadata.py  → .spawn/meta.json
+                                (called by ProjectGenerator, or by generate_project for custom)
     │
     ▼
 show_success()                success.py
-    └── template_obj.next_steps (formatted with project_name)
-    │
-    ▼
-GitHubPublisher.publish()     publisher.py    (optional)
 ```
 
 ### 4b. Template System
@@ -173,13 +174,19 @@ and/or `.github/workflows/ci.yml` depending on `self.extras`.
 ### 4d. Error Handling
 
 ```
-SpawnError                    # core/exceptions.py
-└── GitHubPublishError        # github/exceptions.py
+SpawnError                      exit 1   core/exceptions.py
+├── InvalidInputError           exit 1
+│   └── StructureParseError     exit 1
+├── ConfigError                 exit 1
+├── FilesystemError             exit 3
+├── ToolchainError              exit 4
+├── GenerationError             exit 5
+│   └── TemplateError           exit 5
+└── PublishError                exit 6
+    └── GitHubPublishError      exit 6   github/exceptions.py
 ```
 
-`ProjectGenerator.generate()` wraps its body in try/except. Any `OSError` is converted to
-`SpawnError`; any `BaseException` (including `SpawnError`) triggers `shutil.rmtree()` rollback
-before re-raising. The CLI catches both exception types and prints `❌ {message}` in red.
+Generators convert `OSError` to `FilesystemError`, remove only the directory the current run created, and re-raise. `cli/errors.py` owns the CLI handlers: `fail(e)` prints `❌ message` in red and exits with `e.exit_code`; `report_unexpected(e)` handles any other exception, printing a short message and exiting 10 (`UNEXPECTED_EXIT_CODE`), or re-raising for a full traceback when `SPAWN_DEBUG` is set to anything other than empty/`0`/`false`/`no`. Ctrl+C, EOF and declined prompts exit 130; Click usage errors exit 2. See [Exit codes](commands.md#exit-codes).
 
 ## 5. Adding a New Template
 
@@ -197,3 +204,54 @@ uv run pytest -v
 uv run pytest tests/test_generator.py
 uv run ruff check .
 ```
+
+## 7. Pipeline
+
+```
+input -> plan_project -> ProjectConfig -> generate_project -> filesystem -> meta -> publish (optional)
+```
+
+| Step | Owner |
+|---|---|
+| Input (flags, `--config` JSON, prompts) | `cli/noninteractive.py`, `cli/prompts.py` |
+| Plan: validate and resolve options | `core/planning.py::plan_project` |
+| Canonical model | `core/models.py::ProjectConfig` |
+| Generate: folders, files, git, uv, rollback | `generators/pipeline.py::generate_project` |
+| Meta: `.spawn/meta.json` | `generators/metadata.py::write_project_meta` |
+| Publish | `github/publisher.py::GitHubPublisher` (called from `cli/app.py`) |
+
+## 8. Canonical model
+
+`ProjectConfig` is the single model passed between stages.
+
+| Field | Meaning |
+|---|---|
+| `name`, `template` | Project name; template slug (`"custom"` for pasted structures) |
+| `framework`, `provider`, `cli_type`, `data_type` | Template options |
+| `extras`, `license`, `generate_claude_md` | Optional tooling, license (`mit`/`none`), also write `CLAUDE.md` |
+| `use_git`, `use_uv` | Toolchain steps |
+| `custom_*` | Custom-structure entries, dependencies, dev setup, gitignore extras, source format |
+| `destination` | Target directory (`Path` or `None`); excluded from equality |
+
+`to_dict()` returns a JSON-serializable dict of every field (`destination` as a string).
+
+`.spawn/meta.json` is a **historical record, not authoritative**: it stores `intent`, `framework`, `provider`, `spawn_version`, `created_at`, `generator`, `git`, `uv` and `source` only. It does not record `name`, `cli_type`, `data_type`, `extras`, `license` or `generate_claude_md`, and the project may have changed since. `ProjectConfig` is generation intent only; it cannot be reconstructed from metadata.
+
+## 9. Extension boundary
+
+Code that analyses existing projects must not depend on the CLI. It obtains state through `core/`, `generators/` and `templates/`:
+
+| Need | Use |
+|---|---|
+| State of an existing project | `core.project.read_project_metadata(path)`: a `ProjectMetadata`, or `None` if there is no `.spawn/meta.json`; raises `ConfigError` if the file is unreadable or invalid. Read-only; does not validate the intent against the registry |
+| Resolve options into a config | `core.planning.plan_project(...)` |
+| Template catalogue | `core.registry.get_metadata()`, `list_templates()` |
+| Create a project | `generators.pipeline.generate_project(config)` |
+
+**Rule:** no module under `core/`, `generators/`, `templates/`, `utils/` or `github/` may import `spawn.cli`. `tests/test_boundaries.py` enforces this.
+
+To add a template: subclass `BaseTemplate` in `templates/<slug>/` and add a `TemplateMetadata` entry to `TEMPLATES` (see section 5).
+
+## 10. Error model
+
+All Spawn errors derive from `SpawnError` (`core/exceptions.py`); each class carries the CLI `exit_code`. The CLI prints `❌ message` and exits with that code. See [Exit codes](commands.md#exit-codes).

{spawnio-1.0.8 → spawnio-1.0.9}/docs/changelog.md

@@ -3,6 +3,26 @@
 All notable changes to Spawn are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## v1.0.9 — 2026
+
+### Added
+
+- **Canonical `ProjectConfig`** — gains `destination` and `to_dict()`; `core/planning.py::plan_project` resolves options into a config and `generators/pipeline.py::generate_project` builds it.
+- **`core/project.py::read_project_metadata`** — CLI-free, read-only `ProjectMetadata` from `.spawn/meta.json` (`None` if absent, `ConfigError` if invalid). Metadata is historical, not authoritative; `ProjectConfig` is generation intent only.
+- **Fixtures and regression tests** — archetype factory, golden file trees (`SPAWN_UPDATE_TREES=1`), and an import-boundary test (nothing outside `cli/` imports `spawn.cli`).
+
+### Changed
+
+- `--no-uv` is now honored for template projects: uv init, `uv add` and extras that need `pyproject.toml` are skipped (one yellow "Skipped without uv: ..." line lists them); file-only extras such as `pre-commit` are still written.
+- Interactive `spawn create --dry-run` now validates and prints the config without writing anything.
+- `--config` combined with an explicit `--no-git`/`--no-uv` prints a warning that the config file takes precedence.
+- **Error and exit-code contract** — generation, toolchain (git/uv) and publish failures now exit non-zero (3–6) instead of 0; unexpected errors exit 10 with a short message (`SPAWN_DEBUG=1` shows the traceback). Declining the final custom-structure prompt now cancels cleanly (130) instead of raising a traceback. Git/GitHub error text no longer includes URL credentials. See the Exit codes table in `docs/commands.md`.
+
+### Security
+
+- Custom-structure paths that escape the project directory (path traversal) are rejected.
+- Failure cleanup only removes directories created by the current run.
+
 ## v1.0.8 — 2026
 
 ### Added

{spawnio-1.0.8 → spawnio-1.0.9}/docs/commands.md

@@ -13,11 +13,12 @@
 
 ## `spawn` (no arguments)
 
-Running `spawn` with no arguments prints the banner, the installed version, and the command list.
+Running `spawn` with no arguments prints the ASCII banner, the installed version, and the command list. It takes no arguments and no options other than `--help`, `--install-completion` and `--show-completion`, exits 0, and writes nothing.
 
 ```
-SPAWN — scaffold your next project
-v1.0.8
+<ASCII SPAWN banner — "scaffold your next project">
+
+v1.0.9
 
 Commands
   create    Scaffold a new project
@@ -33,6 +34,13 @@ Run spawn COMMAND --help for details on a command.
 
 Creates a new project directory, writes starter files, installs dependencies, and optionally runs `git init` and `uv init`.
 
+**Contract**
+
+- **Arguments:** none. Options and defaults are in the flag table under *Non-interactive mode* (`--git`, `--uv`, `--no-claude-md`, `--license mit`).
+- **Success:** the project is created in `./<name>`, a success panel is shown, exit code 0. `--dry-run` validates and prints the resolved config, writes nothing, exit code 0.
+- **Failure:** `❌ message` is printed and the command exits non-zero (see [Exit codes](#exit-codes)). A partially written project directory is removed.
+- **Filesystem:** writes only a new directory `./<name>`. It fails if that directory already exists (exit 3) and never modifies existing files.
+
 ### Interactive mode
 
 Run with no flags to enter the arrow-key prompt flow:
@@ -143,9 +151,9 @@ spawn create --config spawn.json
 | `--extras` | none | Comma-separated extras, e.g. `ruff,pytest` |
 | `--license` | `mit` | Project license (`mit` or `none`) |
 | `--git` / `--no-git` | `--git` | Initialize a Git repository |
-| `--uv` / `--no-uv` | `--uv` | Initialize uv and install dependencies |
+| `--uv` / `--no-uv` | `--uv` | Initialize uv and install dependencies. With `--no-uv`, extras that need `pyproject.toml` are skipped (one yellow "Skipped without uv" line lists them); file-only extras such as `pre-commit` are still written |
 | `--claude-md` / `--no-claude-md` | `--no-claude-md` | Also write `CLAUDE.md` alongside `AGENTS.md` |
-| `--config` | — | Path to a JSON config file |
+| `--config` | — | Path to a JSON config file. Takes precedence over other flags; an explicit `--no-git`/`--no-uv` is ignored with a yellow warning |
 | `--yes` / `-y` | false | Skip the GitHub publish prompt |
 | `--dry-run` | false | Validate and print the config without creating anything |
 
@@ -379,7 +387,7 @@ Every generated project includes:
 | `CHANGELOG.md` | Keep a Changelog starter documenting the initial release |
 | `LICENSE` | MIT license (when `--license mit`, the default) |
 | `.gitignore` | Python defaults (`.venv/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, etc.) |
-| `.spawn/meta.json` | `intent`, `framework`, `provider`, `spawn_version`, `created_at`, `git`, `uv` |
+| `.spawn/meta.json` | `intent`, `framework`, `provider`, `spawn_version`, `created_at`, `generator`, `git`, `uv`, `source` |
 
 If `--claude-md` was passed (or `"claude_md": true` in the config file), a `CLAUDE.md` file identical to `AGENTS.md` is also written.
 
@@ -390,7 +398,7 @@ If `--claude-md` was passed (or `"claude_md": true` in the config file), a `CLAU
   "intent": "backend-api",
   "framework": "fastapi",
   "provider": null,
-  "spawn_version": "1.0.8",
+  "spawn_version": "1.0.9",
   "created_at": "2026-01-01T00:00:00+00:00",
   "generator": "blueprint",
   "git": true,
@@ -422,14 +430,7 @@ In non-interactive mode or when `--yes` / `-y` is passed, the publish prompt is
 
 ### Error cases
 
-All errors print `❌ message` in red. Any partial directory is deleted on failure.
-
-| Situation | Exit code |
-|---|---|
-| Successful creation | 0 |
-| SpawnError (bad name, unknown template, etc.) | 0 (error printed) |
-| Non-interactive validation error | 1 |
-| Ctrl+C at any prompt | 130 |
+All errors print `❌ message` in red and exit with the code for their error class; any partial directory is deleted on failure. See [Exit codes](#exit-codes) for the full table (for example: invalid input 1, usage error 2, existing destination 3, missing `git`/`uv` 4, generation error 5, Ctrl+C 130).
 
 ---
 
@@ -437,6 +438,14 @@ All errors print `❌ message` in red. Any partial directory is deleted on failu
 
 Scores the current directory (or a given path) for project health. All checks are filesystem-based — nothing is executed or sent over the network.
 
+**Contract**
+
+- **Arguments:** `[PATH]`, default `.`.
+- **Options:** `--fix`, `--dry-run`, `--yes` / `-y`, `--license TEXT`; all off/unset by default, and the last three only apply with `--fix`.
+- **Success:** prints the health report (score out of 135, rating, recommendations), exit code 0. A low score is not a failure.
+- **Failure:** a path that does not exist or is not a directory prints `❌ message`, exit code 1. Declining the `--fix` confirmation exits 130.
+- **Filesystem:** plain `spawn doctor` is read-only. `spawn doctor --fix` only creates missing files and config; it never overwrites and never installs packages. `--fix --dry-run` writes nothing.
+
 ```bash
 spawn doctor
 spawn doctor ./path/to/project
@@ -511,20 +520,30 @@ spawn doctor --fix --license mit
 
 ## `spawn version`
 
-Prints the installed version.
+Prints the installed version. No arguments or options; exit code 0; writes nothing.
 
 ```bash
 spawn version
-# Spawn v1.0.8
+# Spawn v1.0.9
 ```
 
 ---
 
 ## Exit codes
 
-| Situation | Exit code |
+| Code | Meaning |
 |---|---|
-| Any command succeeds | 0 |
-| `spawn doctor` — path does not exist or is not a directory | 1 |
-| Non-interactive validation error / flag error | 1 |
-| Ctrl+C / EOF at any point | 130 |
+| 0 | Success (including a valid `--dry-run`, and GitHub publishing skipped) |
+| 1 | Invalid input or config (bad name, option value, config file, unknown template; `spawn doctor` bad path/flags) |
+| 2 | CLI usage error (unknown option, reported by Click) |
+| 3 | Filesystem error (directory already exists, OS error while writing) |
+| 4 | Toolchain error (`git` or `uv` missing or failed) |
+| 5 | Generation / template error |
+| 6 | Publish error (GitHub publishing failed) |
+| 10 | Unexpected error (re-run with `SPAWN_DEBUG=1` for a traceback) |
+| 130 | Cancelled (Ctrl+C, EOF, or declining the final prompt) |
+
+Failures that happen after the project was created (for example a failed
+GitHub publish) exit non-zero while the generated project remains on disk.
+`spawn doctor --fix` action failures are reported in the output and do not
+change the exit code.

{spawnio-1.0.8 → spawnio-1.0.9}/docs/getting-started.md

@@ -49,14 +49,14 @@ After installation, `spawn` is available anywhere on your machine.
 
 ```bash
 spawn version
-# Spawn v1.0.8
+# Spawn v1.0.9
 ```
 
 Or just run `spawn` with no arguments to see the command overview:
 
 ```
 SPAWN — scaffold your next project
-v1.0.8
+v1.0.9
 
 Commands
   create    Scaffold a new project

{spawnio-1.0.8 → spawnio-1.0.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spawnio"
-version = "1.0.8"
+version = "1.0.9"
 description = "Spawn a ready-to-use Python project in seconds"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -20,6 +20,17 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/spawn"]
 
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/docs",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+    "/CONTRIBUTING.md",
+]
+
 
 [dependency-groups]
 dev = [

{spawnio-1.0.8 → spawnio-1.0.9}/src/spawn/__init__.py

@@ -3,4 +3,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("spawnio")
 except PackageNotFoundError:
-    __version__ = "1.0.8"
+    __version__ = "1.0.9"

{spawnio-1.0.8 → spawnio-1.0.9}/src/spawn/cli/app.py

@@ -1,5 +1,3 @@
-import datetime
-import json
 from pathlib import Path
 
 import typer
@@ -8,9 +6,10 @@ from rich.prompt import Confirm, Prompt
 from spawn import __version__
 from spawn.cli.noninteractive import build_config_from_args, build_config_from_file
 from spawn.cli.prompts import get_project_config
-from spawn.core.exceptions import SpawnError
+from spawn.cli.errors import fail, report_unexpected
+from spawn.core.exceptions import InvalidInputError, SpawnError
 from spawn.core.registry import instantiate_template
-from spawn.generators.project_generator import ProjectGenerator
+from spawn.generators.pipeline import generate_project
 from spawn.github.exceptions import GitHubPublishError
 from spawn.github.publisher import GitHubPublisher
 from spawn.utils.banner import show_banner
@@ -36,30 +35,23 @@ def main_callback(ctx: typer.Context) -> None:
     )
 
 
-def _write_custom_metadata(project_path, config) -> None:
-    meta_dir = project_path / ".spawn"
-    meta_dir.mkdir(exist_ok=True)
-    (meta_dir / "meta.json").write_text(
-        json.dumps(
-            {
-                "intent": "custom",
-                "framework": None,
-                "provider": None,
-                "spawn_version": __version__,
-                "created_at": datetime.datetime.now(datetime.UTC).isoformat(),
-                "generator": "custom",
-                "git": config.use_git,
-                "uv": config.use_uv,
-                "source": config.custom_source_format or "tree",
-            },
-            indent=2,
-        ),
-        encoding="utf-8",
-    )
+def _given_on_command_line(ctx: typer.Context, param: str) -> bool:
+    source = ctx.get_parameter_source(param)
+    return getattr(source, "name", None) == "COMMANDLINE"
+
+
+def _display_info(config) -> tuple[str, list[str]] | None:
+    if config.template == "custom":
+        return "Custom Structure", [f"cd {config.name}", "Start building your project"]
+    template_obj = instantiate_template(config)
+    if template_obj is None:
+        return None
+    return template_obj.name, template_obj.next_steps
 
 
 @app.command()
 def create(
+    ctx: typer.Context,
     name: str = typer.Option(
         None, "--name", help="Project name (enables non-interactive mode)"
     ),
@@ -126,7 +118,7 @@ def create(
                     )
                 else:
                     if template is None:
-                        raise SpawnError(
+                        raise InvalidInputError(
                             "--template is required when using --name without --config."
                         )
                     extras_list = (
@@ -149,55 +141,43 @@ def create(
                     )
 
             except SpawnError as e:
-                console.print(f"[red]❌ {e}[/red]")
-                raise typer.Exit(1)
-
-            if dry_run:
-                console.print("[green]✓ Config valid[/green]")
-                console.print(config)
-                return
+                fail(e)
+
+            if config_file is not None:
+                for param, value, flag in (
+                    ("git", git, "--no-git"),
+                    ("uv", uv, "--no-uv"),
+                ):
+                    if not value and _given_on_command_line(ctx, param):
+                        console.print(
+                            f"[yellow]{flag} ignored: --config takes precedence[/yellow]"
+                        )
         else:
-            config = get_project_config()
+            try:
+                config = get_project_config()
+            except SpawnError as e:
+                fail(e)
 
-        try:
-            if config.template == "custom":
-                from spawn.generators.custom_structure import CustomStructureGenerator
+        if dry_run:
+            console.print("[green]✓ Config valid[/green]")
+            console.print(config)
+            return
 
-                project_path = CustomStructureGenerator().generate(
-                    project_name=config.name,
-                    entries=config.custom_entries or [],
-                    use_git=config.use_git,
-                    use_uv=config.use_uv,
-                    dependencies=config.custom_dependencies,
-                    dev_setup=config.custom_dev_setup,
-                    gitignore_extra=config.custom_gitignore_extra,
-                    generate_claude_md=config.generate_claude_md,
-                )
-                _write_custom_metadata(project_path, config)
-                next_steps = [
-                    f"cd {config.name}",
-                    "Start building your project",
-                ]
+        try:
+            project_path = generate_project(config)
+            info = _display_info(config)
+            if info is not None:
+                template_name, next_steps = info
                 show_success(
                     project_name=config.name,
-                    template_name="Custom Structure",
+                    template_name=template_name,
                     use_git=config.use_git,
                     next_steps=next_steps,
+                    use_uv=config.use_uv,
                 )
-            else:
-                project_path = ProjectGenerator().generate(config)
-                template_obj = instantiate_template(config)
-                if template_obj is not None:
-                    show_success(
-                        project_name=config.name,
-                        template_name=template_obj.name,
-                        use_git=config.use_git,
-                        next_steps=template_obj.next_steps,
-                    )
 
         except SpawnError as e:
-            console.print(f"[red]❌ {e}[/red]")
-            return
+            fail(e)
 
         if not config.use_git:
             console.print(
@@ -225,10 +205,14 @@ def create(
             console.print("[green]🚀 Published successfully![/green]")
 
         except GitHubPublishError as e:
-            console.print(f"[red]❌ {e}[/red]")
+            fail(e)
     except (KeyboardInterrupt, EOFError, typer.Abort):
         console.print("\n[yellow]Cancelled.[/yellow]")
         raise typer.Exit(130)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        report_unexpected(e)
 
 
 @app.command()
@@ -360,6 +344,10 @@ def doctor(
     except (KeyboardInterrupt, EOFError, typer.Abort):
         console.print("\n[yellow]Cancelled.[/yellow]")
         raise typer.Exit(130)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        report_unexpected(e)
 
 
 def main():