spawnio 1.0.8__tar.gz → 1.1.0__tar.gz

{spawnio-1.0.8 → spawnio-1.1.0}/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.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spawnio
-Version: 1.0.8
+Version: 1.1.0
 Summary: Spawn a ready-to-use Python project in seconds
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -89,6 +89,7 @@ It's repetitive. It's inconsistent. And you haven't written a single line of *re
 | **GitHub publishing** | Connects your project to an existing GitHub repo and pushes the initial commit |
 | **spawn doctor** | Scores your project's health out of 100, with per-category breakdowns and a prioritized next step |
 | **spawn doctor --fix** | Fixes missing files and config automatically — never overwrites, never installs packages |
+| **spawn inspect** | Static, read-only summary of a repository: languages, frameworks, dependencies, package managers, tooling and layout, as text or JSON |
 
 ---
 
@@ -144,12 +145,13 @@ Running `spawn` with no arguments shows the banner, the installed version, and t
 
 ```
 SPAWN — scaffold your next project
-v1.0.8
+v1.1.0
 
 Commands
   create    Scaffold a new project
   doctor    Check the health of a project directory
   version   Show the installed version
+  inspect   Inspect a repository (read-only)
 
 Run spawn COMMAND --help for details on a command.
 ```
@@ -710,7 +712,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,8 +793,42 @@ spawn doctor --fix --license mit
 
 ```bash
 spawn version
-# → Spawn v1.0.8
+# → Spawn v1.1.0
+
+spawn --version
+# → Spawn v1.1.0
+```
+
+### `spawn inspect`
+
+Give Spawn a repository and receive a deterministic, evidence-backed summary of what it contains.
+
+```bash
+spawn inspect .            # human-readable summary
+spawn inspect . --json     # full report on stdout, schema_version "1.0"
+spawn inspect . --verbose  # all dependencies, entries and evidence paths
+```
+
 ```
+⚡ SPAWN / INSPECT
+
+demo
+python project · 11 files · 3 directories
+
+PROJECT OVERVIEW
+  Primary language  python
+  Framework         Not detected
+  Package manager   Not detected
+  Origin            spawn
+
+✓ Inspection complete
+```
+
+**Scope.** 25 languages by extension and manifest; React, Next.js, Vue, Nuxt, Angular, Svelte, Express, FastAPI, Flask, Django, Starlette, Pydantic and Laravel; dependencies from `pyproject.toml`, `requirements*.txt` and `package.json`; package managers (uv, poetry, pipenv, pip, npm, yarn, pnpm, bun); tooling (ruff, black, flake8, mypy, pyright, pytest, eslint, prettier, jest, vitest, pre-commit, git), CI, containers and databases. Full matrix: [supported technologies](docs/inspection/supported-technologies.md).
+
+**Limitations.** Detection is static and evidence-based: a finding means an indicator exists, not that the project builds or runs. Frameworks seen only in a dependency declaration are marked *inferred*; imports are matched by regex, so import-like text in comments or strings can false-positive. CI, container and pre-commit detection is presence-only. Databases are inferred from driver packages. Manifests such as `Pipfile`, `setup.py`, `Cargo.toml`, `go.mod`, `Gemfile` and `pom.xml` give no dependency findings. Directories named `build`, `dist`, `env`, `target`, `vendor` and the like are skipped at any depth.
+
+**Safety.** `spawn inspect` is read-only: it never runs repository code, installs anything, uses the network or writes to the repository, and it does not follow symbolic links. It exits 0 for complete and partial reports and 7 for an invalid path or failed inspection. See the [command reference](docs/commands.md#spawn-inspect).
 
 ### Publish to GitHub
 
@@ -825,6 +861,8 @@ All tests should pass. If they don't, please [open an issue](https://github.com/
 
 | Version | Highlight |
 |---|---|
+| **v1.1.0** | `spawn inspect`: static, read-only repository inspection (languages, frameworks, dependencies, package managers, tooling, layout) with human and `--json` output; `spawn --version` |
+| **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.1.0}/README.md

@@ -78,6 +78,7 @@ It's repetitive. It's inconsistent. And you haven't written a single line of *re
 | **GitHub publishing** | Connects your project to an existing GitHub repo and pushes the initial commit |
 | **spawn doctor** | Scores your project's health out of 100, with per-category breakdowns and a prioritized next step |
 | **spawn doctor --fix** | Fixes missing files and config automatically — never overwrites, never installs packages |
+| **spawn inspect** | Static, read-only summary of a repository: languages, frameworks, dependencies, package managers, tooling and layout, as text or JSON |
 
 ---
 
@@ -133,12 +134,13 @@ Running `spawn` with no arguments shows the banner, the installed version, and t
 
 ```
 SPAWN — scaffold your next project
-v1.0.8
+v1.1.0
 
 Commands
   create    Scaffold a new project
   doctor    Check the health of a project directory
   version   Show the installed version
+  inspect   Inspect a repository (read-only)
 
 Run spawn COMMAND --help for details on a command.
 ```
@@ -699,7 +701,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,8 +782,42 @@ spawn doctor --fix --license mit
 
 ```bash
 spawn version
-# → Spawn v1.0.8
+# → Spawn v1.1.0
+
+spawn --version
+# → Spawn v1.1.0
+```
+
+### `spawn inspect`
+
+Give Spawn a repository and receive a deterministic, evidence-backed summary of what it contains.
+
+```bash
+spawn inspect .            # human-readable summary
+spawn inspect . --json     # full report on stdout, schema_version "1.0"
+spawn inspect . --verbose  # all dependencies, entries and evidence paths
+```
+
 ```
+⚡ SPAWN / INSPECT
+
+demo
+python project · 11 files · 3 directories
+
+PROJECT OVERVIEW
+  Primary language  python
+  Framework         Not detected
+  Package manager   Not detected
+  Origin            spawn
+
+✓ Inspection complete
+```
+
+**Scope.** 25 languages by extension and manifest; React, Next.js, Vue, Nuxt, Angular, Svelte, Express, FastAPI, Flask, Django, Starlette, Pydantic and Laravel; dependencies from `pyproject.toml`, `requirements*.txt` and `package.json`; package managers (uv, poetry, pipenv, pip, npm, yarn, pnpm, bun); tooling (ruff, black, flake8, mypy, pyright, pytest, eslint, prettier, jest, vitest, pre-commit, git), CI, containers and databases. Full matrix: [supported technologies](docs/inspection/supported-technologies.md).
+
+**Limitations.** Detection is static and evidence-based: a finding means an indicator exists, not that the project builds or runs. Frameworks seen only in a dependency declaration are marked *inferred*; imports are matched by regex, so import-like text in comments or strings can false-positive. CI, container and pre-commit detection is presence-only. Databases are inferred from driver packages. Manifests such as `Pipfile`, `setup.py`, `Cargo.toml`, `go.mod`, `Gemfile` and `pom.xml` give no dependency findings. Directories named `build`, `dist`, `env`, `target`, `vendor` and the like are skipped at any depth.
+
+**Safety.** `spawn inspect` is read-only: it never runs repository code, installs anything, uses the network or writes to the repository, and it does not follow symbolic links. It exits 0 for complete and partial reports and 7 for an invalid path or failed inspection. See the [command reference](docs/commands.md#spawn-inspect).
 
 ### Publish to GitHub
 
@@ -814,6 +850,8 @@ All tests should pass. If they don't, please [open an issue](https://github.com/
 
 | Version | Highlight |
 |---|---|
+| **v1.1.0** | `spawn inspect`: static, read-only repository inspection (languages, frameworks, dependencies, package managers, tooling, layout) with human and `--json` output; `spawn --version` |
+| **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.1.0/docs/architecture.md

@@ -0,0 +1,290 @@
+# Architecture
+
+## 1. Overview
+
+Spawn is a Python CLI tool built with Typer and Rich. It scaffolds new Python projects from templates, optionally publishes them to GitHub, and scores existing projects for environment health.
+
+The three main capabilities are **project generation** (`spawn create`), **GitHub publishing** (optional post-create flow), and **environment health checking** (`spawn doctor`).
+
+## 2. Technology Stack
+
+| Tool | Version | Role |
+|---|---|---|
+| Python | 3.12+ | Core language |
+| Typer | 0.26.7+ | CLI framework |
+| Rich | 15.0.0+ | Terminal UI |
+| uv | any | Environment management |
+| Git | any | Version control |
+| Hatchling | any | Build backend |
+
+Entry point: `spawn.cli.app:main` (defined in `pyproject.toml` as `[project.scripts]`).
+
+## 3. Repository Structure
+
+```
+src/spawn/
+├── __init__.py         # __version__ via importlib.metadata, fallback "1.1.0" (keep in sync with pyproject.toml)
+├── cli/
+│   ├── app.py          # Typer app: create, version (and --version), doctor, inspect commands
+│   ├── inspect_render.py # Rich rendering of an InspectionReport for `spawn inspect`
+│   ├── noninteractive.py # Build config from CLI flags or JSON config file
+│   └── prompts.py      # Interactive prompts; derives menu from registry
+├── core/
+│   ├── exceptions.py   # SpawnError — base exception
+│   ├── models.py       # ProjectConfig dataclass (name, template, use_git, framework, extras, license)
+│   └── registry.py     # TemplateMetadata, TEMPLATES dict, get_template(),
+│                       # instantiate_template(), get_metadata(), list_templates()
+├── generators/
+│   ├── custom_structure.py   # Custom structure parser and generator
+│   ├── project_files.py      # Standalone file writers for LICENSE, README, configs, CI
+│   └── project_generator.py  # Orchestrates generation, dependency install, meta.json write
+├── github/
+│   ├── exceptions.py   # GitHubPublishError
+│   ├── publisher.py    # GitHubPublisher — stages, commits, pushes
+│   └── validators.py   # GitHub URL validation
+├── inspection/         # Read-only repository inspection (never imports spawn.cli)
+│   ├── models.py       # Report/finding/evidence/diagnostic models, SCHEMA_VERSION, validate_report
+│   ├── base.py         # Analyzer protocol
+│   ├── discovery.py    # validate_inspection_root, discover_repository (single inventory scan)
+│   ├── languages.py    # LanguageDetector
+│   ├── frameworks.py   # FrameworkDetector
+│   ├── dependencies.py # DependencyAnalyzer (dependencies, package managers)
+│   ├── tooling.py      # ToolingAnalyzer (tools, CI, containers, databases, structure)
+│   ├── orchestrator.py # run_inspection: runs analyzers, aggregates, builds the report
+│   ├── serialization.py # to_json / from_json
+│   ├── exceptions.py   # InspectionError (exit code 7)
+│   └── _reading.py     # Bounded file reads
+├── templates/
+│   ├── base.py         # BaseTemplate dataclass
+│   ├── shared_content.py     # README_CONTENT, GITIGNORE_CONTENT, CI, and tool configs
+│   ├── backend_api/
+│   │   ├── __init__.py       # BackendAPITemplate (dispatches by framework)
+│   │   └── content.py        # All FastAPI/Flask/Django/Docker/CI content strings
+│   ├── cli_application/
+│   │   ├── __init__.py       # CLITemplate (dispatches by framework + cli_type)
+│   │   └── content.py        # All framework × cli_type content strings
+│   ├── automation/
+│   │   ├── __init__.py       # AutomationTemplate
+│   │   └── content.py        # Workflow, task, logger, test, README content strings
+│   ├── chatbot/
+│   │   ├── __init__.py       # ChatbotTemplate (branches on framework)
+│   │   └── content.py        # LLM provider, chat, prompt, test, README strings
+│   ├── python_script/        # Reserved — not in active menu
+│   ├── data_science/         # Reserved — not in active menu
+│   └── ml_project/           # Reserved — not in active menu
+└── utils/
+    ├── banner.py       # show_banner() — ASCII wordmark with ice-fade colours
+    ├── console.py      # Shared Rich Console instance
+    ├── doctor.py       # ProjectHealthChecker, run_health_check()
+    ├── doctor_fix.py   # FixAction, FixResult, plan_fixes(), apply_fixes(), tool_hints()
+    ├── git.py          # initialize_git(), run_git_command(), add_all(), commit() etc.
+    ├── success.py      # show_success() — renders the success panel
+    ├── theme.py        # UI theme colors and styles
+    ├── uv.py           # initialize_uv(), install_packages()
+    └── validators.py   # validate_project_name()
+```
+
+## 4. Key Flows
+
+### 4a. Project Creation Flow
+
+1. User runs `spawn create`
+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
+    │
+    ▼
+show_banner()                 banner.py
+    │
+    ▼
+plan_project()                planning.py    (flags / --config)
+get_project_config()          prompts.py     (interactive)
+    │  → ProjectConfig
+    ▼
+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
+```
+
+### 4b. Template System
+
+`BaseTemplate` is a dataclass with these fields:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `name` | `str` | Display name shown in the success panel |
+| `folders` | `list[str]` | Directories created under the project root |
+| `starter_files` | `list[tuple[str, str]]` | `(relative_path, content_template)` pairs; `{project_name}` substituted at write time |
+| `next_steps` | `list[str]` | Run commands shown after creation; `{project_name}` substituted at display time |
+
+`BaseTemplate` also provides overridable methods:
+
+| Method | Default | Purpose |
+|---|---|---|
+| `generate(project_path, context)` | Creates folders and writes starter files | Template-specific generation |
+| `get_readme_content(context)` | Returns `None` (use shared README) | Custom README per template |
+| `get_dependencies()` | Returns `[]` | Packages to install via `uv add` |
+| `post_install(project_path)` | No-op | Config writes, Docker files, CI files |
+
+Each template lives in its own subdirectory with an `__init__.py` (class) and `content.py` (string constants).
+
+#### Registry
+
+`registry.py` holds `TEMPLATES: dict[str, TemplateMetadata]`. Current entries in order:
+
+| Key | Template class | Frameworks | Extras |
+|---|---|---|---|
+| `backend-api` | `BackendAPITemplate` | fastapi, flask, django | ruff, pytest, docker, github-actions, pre-commit, mypy |
+| `cli` | `CLITemplate` | typer, click, argparse | ruff, pytest, github-actions, pre-commit, mypy |
+| `automation` | `AutomationTemplate` | none | ruff, pytest, github-actions, pre-commit, mypy |
+| `chatbot` | `ChatbotTemplate` | pydantic-ai, openai-sdk, litellm | ruff, pytest, rich, github-actions, pre-commit, mypy |
+| `agent` | `AgentTemplate` | pydantic-ai, openai-agents | ruff, pytest, github-actions, pre-commit, mypy |
+| `rag` | `RAGTemplate` | none | ruff, pytest, github-actions, pre-commit, mypy |
+| `data` | `DataProjectTemplate` | none | ruff, pytest, github-actions, pre-commit, mypy |
+| `mcp` | `MCPServerTemplate` | none | ruff, pytest, github-actions, pre-commit, mypy |
+
+`get_template(slug)` returns a default-constructed instance. `instantiate_template(config)` forwards `framework`, `extras`, and `cli_type` from `ProjectConfig` to templates whose constructors accept them, using signature introspection.
+
+`_REMOVED_SLUGS = {"fastapi", "python", "data-science", "ml"}` documents slugs that existed in previous versions but are no longer registered.
+
+### 4c. Backend API Dispatch
+
+`BackendAPITemplate.__init__` branches on `framework` to select the correct folder list,
+starter files, and next steps:
+
+```
+framework == "flask"   → FLASK_FOLDERS, FLASK_FILES, flask next steps
+framework == "django"  → DJANGO_FOLDERS, DJANGO_FILES, django next steps
+else (None/"fastapi")  → FASTAPI_FOLDERS, FASTAPI_FILES, fastapi next steps
+```
+
+`get_dependencies()` returns base deps for the framework plus any selected extras.
+`post_install()` writes ruff config, pytest filterwarnings, Dockerfile, `.dockerignore`,
+and/or `.github/workflows/ci.yml` depending on `self.extras`.
+
+### 4d. Error Handling
+
+```
+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
+```
+
+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
+
+1. Create `src/spawn/templates/your_intent/` with `__init__.py` and `content.py`
+2. Subclass `BaseTemplate`; set `name`, `folders`, `starter_files`, `next_steps`
+3. Override `get_dependencies()`, `post_install()`, `get_readme_content()` as needed
+4. Register in `registry.py` — add a `TemplateMetadata` entry to `TEMPLATES`
+5. Write tests in `test_templates.py` and `test_registry.py`
+
+## 6. Running Tests
+
+```bash
+uv run pytest
+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).
+
+## 11. Inspection pipeline
+
+```
+spawn inspect -> run_inspection -> validate root -> discover once -> analyzers -> aggregate/dedupe/sort -> InspectionReport -> human or JSON
+```
+
+| Step | Owner |
+|---|---|
+| CLI: argument, `--json`, exit codes | `cli/app.py::inspect_command` |
+| Validate root (bad root raises `InspectionError`, exit 7) | `inspection/discovery.py::validate_inspection_root` |
+| Discover once: sorted files, directories, skipped, diagnostics; symlinks never followed | `inspection/discovery.py::discover_repository` |
+| Analyzers, fixed order: language, framework, dependency, tooling; each gets the same immutable inventory | `inspection/orchestrator.py::ANALYZERS` |
+| Isolate: a crashing or invalid analyzer becomes a `failed` result, others continue | `orchestrator._run_one` |
+| Aggregate: validate findings, merge by `(category, subject)`, sort; derive summary and structure | `orchestrator._aggregate`, `_summary` |
+| Render: Rich output, or `to_json` on stdout | `cli/inspect_render.py`, `inspection/serialization.py` |
+
+Analyzers only consume the inventory (plus bounded reads of files it lists); they do not walk the tree. Nothing is executed, installed, fetched or written. `.spawn/meta.json` is read at most once, as untrusted recorded metadata.
+
+**Module boundary:** `inspection/` never imports `spawn.cli`; `tests/test_boundaries.py` enforces this. Statuses and semantics are in [the inspection contract](inspection/inspection-contract.md); what is detected is in [supported technologies](inspection/supported-technologies.md).

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

@@ -3,6 +3,53 @@
 All notable changes to Spawn are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## v1.1.0 — 2026
+
+### Added
+
+- **`spawn inspect [PATH] [--json] [--verbose]`** — read-only, static inspection of a repository. Prints a human summary (overview, technology, tooling, structure, diagnostics) or, with `--json`, the full report on stdout. Exits 0 for complete and partial reports and 7 for an invalid path or failed inspection (see `docs/commands.md`).
+- **`spawn --version`** — prints the same line as `spawn version`.
+- **Inspection contract** — `spawn.inspection` models (`InspectionReport`, `Finding`, `Evidence`, `Diagnostic`), `SCHEMA_VERSION` `"1.0"`, `validate_report`, and `to_json` / `from_json`. See `docs/inspection/inspection-contract.md`.
+- **Safe discovery** — one sorted inventory scan; symlinks and junctions are never followed, default exclusions (`.git`, `node_modules`, `build`, `dist`, `venv`, `env`, `target`, ...) match at any depth, errors below the root become diagnostics.
+- **Language and framework detection** — 25 languages by extension and manifest; React, Next.js, Vue, Nuxt, Angular, Svelte, Express, FastAPI, Flask, Django, Starlette, Pydantic and Laravel from manifests (inferred), imports and config files (detected).
+- **Dependency and package-manager analyzer** — direct dependencies from `pyproject.toml`, `requirements*.txt` and `package.json`; uv, poetry, pipenv, pip, npm, yarn, pnpm and bun.
+- **Tooling analyzer** — Python and JavaScript tools, git, CI systems, Docker and Compose, database drivers, `tests-directory`, `src-layout` and `spawn-generated` markers.
+- **Orchestrator** — runs the analyzers in a fixed order with per-analyzer isolation, merges findings by `(category, subject)`, derives the summary and structure, and reads `.spawn/meta.json` as untrusted recorded metadata.
+- **Test corpus** — generated fixture repositories and a regression suite (`tests/test_inspection_*.py`).
+- Release smoke test now runs `spawn inspect . --json` against a generated project and checks it is unchanged.
+
+### Known limitations
+
+- Excluded directory basenames (`build`, `env`, `target`, `vendor`, `dist`, `coverage`, ...) match at any depth.
+- `.git` is detected through discovery's skipped list only.
+- Framework imports are regex-matched: import-like text in comments or strings can false-positive; multi-line and destructured imports are missed.
+- Frameworks found only in a dependency declaration are inferred, and `primary_framework` may be inferred.
+- CI, container and pre-commit detection is presence-only (no YAML parsing).
+- Databases are inferred from driver packages only.
+- A pip and an npm package with the same name share one finding.
+- `Pipfile`, `setup.py`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, `pom.xml` and Gradle files produce no dependency findings; Rails is not detected.
+- `summary.name` is the directory basename.
+
+## 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