spawnio 1.0.9__tar.gz → 1.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spawnio
-Version: 1.0.9
+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.9
+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.
 ```
@@ -791,8 +793,42 @@ spawn doctor --fix --license mit
 
 ```bash
 spawn version
-# → Spawn v1.0.9
+# → 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,7 @@ 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 |

{spawnio-1.0.9 → 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.9
+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.
 ```
@@ -780,8 +782,42 @@ spawn doctor --fix --license mit
 
 ```bash
 spawn version
-# → Spawn v1.0.9
+# → 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,7 @@ 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 |

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

@@ -23,9 +23,10 @@ Entry point: `spawn.cli.app:main` (defined in `pyproject.toml` as `[project.scri
 
 ```
 src/spawn/
-├── __init__.py         # __version__ via importlib.metadata, fallback "1.0.9"
+├── __init__.py         # __version__ via importlib.metadata, fallback "1.1.0" (keep in sync with pyproject.toml)
 ├── cli/
-│   ├── app.py          # Typer app: create, version, doctor commands
+│   ├── 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/
@@ -41,6 +42,18 @@ src/spawn/
 │   ├── 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
@@ -255,3 +268,23 @@ To add a template: subclass `BaseTemplate` in `templates/<slug>/` and add a `Tem
 ## 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.9 → spawnio-1.1.0}/docs/changelog.md

@@ -3,6 +3,33 @@
 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

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

@@ -7,7 +7,8 @@
 | `spawn` | Show the banner, version, and command list |
 | `spawn create` | Scaffold a new project (interactive or non-interactive) |
 | `spawn doctor` | Score a project directory's health out of 135 |
-| `spawn version` | Print the installed version |
+| `spawn inspect` | Inspect a repository and report what it contains (read-only) |
+| `spawn version` | Print the installed version (also `spawn --version`) |
 
 ---
 
@@ -18,12 +19,13 @@ Running `spawn` with no arguments prints the ASCII banner, the installed version
 ```
 <ASCII SPAWN banner — "scaffold your next project">
 
-v1.0.9
+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.
 ```
@@ -398,7 +400,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.9",
+  "spawn_version": "1.1.0",
   "created_at": "2026-01-01T00:00:00+00:00",
   "generator": "blueprint",
   "git": true,
@@ -518,13 +520,71 @@ spawn doctor --fix --license mit
 
 ---
 
+## `spawn inspect`
+
+```
+spawn inspect [PATH] [--json] [--verbose | -v]
+```
+
+Statically inspects a repository and reports its languages, frameworks, declared dependencies, package managers, engineering tooling and layout. `PATH` defaults to `.`. Every positive finding carries repository-relative evidence.
+
+| Option | Effect |
+|---|---|
+| `--json` | Print the full report as JSON on stdout (`schema_version` `"1.0"`); errors go to stderr |
+| `--verbose`, `-v` | Show all dependencies, all top-level entries and evidence paths |
+
+### Safety
+
+`spawn inspect` is read-only and static. It never executes or imports repository code, installs dependencies, uses the network or writes to the repository. Symbolic links and directory junctions are listed as skipped, never followed. Files are read with a 1 MB cap. `.env` files are never read.
+
+### Human output
+
+Sections, in order: header, **Project overview** (primary language, framework, package manager, origin, Spawn version for Spawn-generated projects), **Technology** (languages, other frameworks, dependencies), **Tooling** (tools, CI, containers, databases), **Repository structure** (file/directory counts, top-level entries, structure markers), **Diagnostics**, and a final status line.
+
+State markers:
+
+| Marker (ASCII) | State | Meaning |
+|---|---|---|
+| `✓` (`+`) | detected | A direct static indicator exists |
+| `~` | inferred | Indirect evidence only (for example a declared dependency without config); the detail says why |
+| `?` | unknown | The check could not be completed |
+| `○` (`-`) | not detected / not checked | Looked for and absent, or not looked for |
+
+The framework line is suffixed `inferred` when the primary framework rests on a dependency declaration alone. Diagnostics list warnings and errors with a stable code (for example `discovery.permission_denied`, `framework.malformed_manifest`) and the affected path. A report with warnings ends `Inspection partial: findings may be incomplete`.
+
+### JSON output
+
+`--json` writes one JSON document to stdout and nothing else. `target.root` is always `"."`; no absolute path is emitted. Fields: `schema_version`, `status`, `generated_at`, `target`, `recorded_metadata`, `summary`, `structure`, `findings`, `analyzer_results`, `diagnostics`.
+
+```bash
+spawn inspect ./my-project --json
+```
+
+### Inspect exit codes
+
+| Code | When |
+|---|---|
+| 0 | Inspection complete or partial (a partial report still prints) |
+| 7 | Path missing, not a directory or unreadable; or the repository root could not be scanned (status `failed`) |
+| 10 | Unexpected error |
+
+With `--json`, an invalid path prints the message to stderr, leaves stdout empty and exits 7. An unexpected error in `--json` mode also prints to stderr only (`SPAWN_DEBUG=1` raises the traceback).
+
+### Limitations
+
+See [Supported technologies](inspection/supported-technologies.md#limitations) for what is and is not detected.
+
+---
+
 ## `spawn version`
 
-Prints the installed version. No arguments or options; exit code 0; writes nothing.
+Prints the installed version. `spawn --version` prints the same line. No other arguments or options; exit code 0; writes nothing.
 
 ```bash
 spawn version
-# Spawn v1.0.9
+# Spawn v1.1.0
+spawn --version
+# Spawn v1.1.0
 ```
 
 ---
@@ -540,6 +600,7 @@ spawn version
 | 4 | Toolchain error (`git` or `uv` missing or failed) |
 | 5 | Generation / template error |
 | 6 | Publish error (GitHub publishing failed) |
+| 7 | Inspection error (`spawn inspect`: invalid or unreadable path, or a failed inspection) |
 | 10 | Unexpected error (re-run with `SPAWN_DEBUG=1` for a traceback) |
 | 130 | Cancelled (Ctrl+C, EOF, or declining the final prompt) |
 

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

@@ -49,19 +49,20 @@ After installation, `spawn` is available anywhere on your machine.
 
 ```bash
 spawn version
-# Spawn v1.0.9
+# Spawn v1.1.0
 ```
 
 Or just run `spawn` with no arguments to see the command overview:
 
 ```
 SPAWN — scaffold your next project
-v1.0.9
+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.
 ```