scaffold-ca-python 0.2.0__tar.gz → 0.2.1__tar.gz

scaffold_ca_python-0.2.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.1"
+}

{scaffold_ca_python-0.2.0 → scaffold_ca_python-0.2.1}/.specify/memory/constitution.md

@@ -34,6 +34,19 @@ None — all placeholders resolved.
 
 ---
 
+### Amendment v2.1.0 (2026-10-22) — MINOR
+**Type**: MINOR — new governance clause (materially expanded guidance).
+
+**Changes**:
+- Governance: added "Pre-existing violations" clause. A feature MAY keep a violation that
+  already existed on `main` if the plan documents it as pre-existing debt in Complexity
+  Tracking and names a numbered follow-up feature whose spec directory exists before merge.
+  New code introduced by a feature MUST still comply with every principle.
+
+**Templates updated**: None. First applied by `specs/022-solid-code-cleanup/plan.md`.
+
+---
+
 ### Amendment v2.0.3 (2026-04-10) — PATCH
 **Type**: PATCH — branch naming exception; no semantic change to other governance rules.
 
@@ -75,7 +88,7 @@ or artifact structure was affected.
 
 # scaffold-ca-python Constitution
 
-**Version**: 2.0.3 | **Ratified**: 2026-03-25 | **Last amended**: 2026-04-10
+**Version**: 2.1.0 | **Ratified**: 2026-03-25 | **Last amended**: 2026-10-22
 
 ## Core Principles
 
@@ -255,7 +268,17 @@ dependencies listed in Principle III, installed via `uv` at generation time.
   - **PATCH**: clarifications, wording improvements, or typo fixes with no semantic change.
 - All pull requests MUST include a Constitution Check section in their plan document
   verifying compliance with every applicable principle.
+- **Pre-existing violations**: A feature MAY leave a violation of a principle in place only if
+  all of the following hold:
+  1. The violation existed on `main` before the feature branch was created (it is not
+     introduced or worsened by the feature).
+  2. The plan's Constitution Check marks the principle as "⚠️ pre-existing debt" and the
+     Complexity Tracking table records the violation, its measured extent, and why fixing it
+     is out of scope.
+  3. A numbered follow-up feature (e.g. `023-error-hints`) is named in Complexity Tracking
+     and its spec directory is created before the feature is merged.
+  New code introduced by the feature MUST comply with every principle.
 - Compliance reviews MUST occur at the start of each new feature branch and before
   merging to `main`.
 
-**Version**: 2.0.3 | **Ratified**: 2026-03-25 | **Last Amended**: 2026-04-10
+**Version**: 2.1.0 | **Ratified**: 2026-03-25 | **Last Amended**: 2026-10-22

{scaffold_ca_python-0.2.0 → scaffold_ca_python-0.2.1}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.1](https://github.com/bancolombia/scaffold-clean-architecture-py/compare/v0.2.0...v0.2.1) (2026-10-23)
+
+
+### Bug Fixes
+
+* **refactor:** simplify scaffolder internals and improve extensibility ([8cb0a96](https://github.com/bancolombia/scaffold-clean-architecture-py/commit/8cb0a967d8e00dc5f995e8178d537a3fe5bb7865))
+
 ## [0.2.0](https://github.com/bancolombia/scaffold-clean-architecture-py/compare/v0.1.4...v0.2.0) (2026-10-19)
 
 

{scaffold_ca_python-0.2.0 → scaffold_ca_python-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scaffold-ca-python
-Version: 0.2.0
+Version: 0.2.1
 Summary: Scaffolder to generate Clean Architecture apps
 Project-URL: Homepage, https://github.com/bancolombia/scaffold-clean-architecture-py
 Project-URL: Repository, https://github.com/bancolombia/scaffold-clean-architecture-py

{scaffold_ca_python-0.2.0 → scaffold_ca_python-0.2.1}/pyproject.toml

@@ -75,7 +75,13 @@ line-length = 120
 target-version = "py313"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "ANN"]
+select = ["E", "F", "I", "UP", "ANN", "B", "SIM", "C90"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+# Temporary: removed by the end of feature 022.
+[tool.ruff.lint.per-file-ignores]
 
 [tool.mypy]
 strict = true

scaffold_ca_python-0.2.1/specs/022-solid-code-cleanup/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: SOLID refactor and comment cleanup
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-22
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- This feature is an internal refactor, so its "users" are the maintainers. The spec deliberately names quality tools (linter, cyclomatic complexity, Google-style docstrings) because they are the goal of the feature itself, not implementation details. They are accepted as an exception to "technology-agnostic".
+- Concrete module names (`commands/`, `gep`, `gpipe`) are used only to bound the scope.

scaffold_ca_python-0.2.1/specs/022-solid-code-cleanup/contracts/cli-behavior.md

@@ -0,0 +1,49 @@
+# Contract: observable CLI behavior
+
+This refactor does **not** change the public interface. The contract is what the suite already verifies, plus the three explicit exceptions listed at the end.
+
+## Invariants
+
+| Aspect | Contract | Verified by |
+|---|---|---|
+| Commands and aliases | `ca/clean-architecture`, `gm`, `guc`, `gda`, `gep`, `gh`, `gpipe`, `vs`, `dm`, `up`, with the same long names | `tests/commands/test_cli.py` |
+| Flags and defaults | Same names, defaults, help panels and epilogs | `--help` snapshot in `test_cli.py` and per-command tests |
+| Generated files | Byte-for-byte identical, including the files that now come from new templates (FR-004) | `tests/commands/test_dry_run_checksum.py`, `tests/templates/` |
+| `--dry-run` | Same list of paths, no writes | `tests/factory/test_dry_run_parity.py` and per-command tests |
+| Error messages | Same text and same `Hint:` (when present) | per-command tests (`strip_ansi`), `tests/commands/test_behavior_contract.py` |
+| Exit codes | `0` success or help, `1` user error, `2` `uv` failure in `up` | per-command tests |
+| `pyproject.toml` | Same injected dependencies, groups and `[project.scripts]` | `tests/core/test_pyproject_writer.py` and gep/gda tests |
+
+## Allowed changes (exhaustive)
+
+### C-1: unified project context (FR-010)
+
+- **Before**: `gep` and `gep --add-tool` used `to_snake_case([project].name)`, with `"project"` as the default.
+- **After**: every command uses `[tool.scaffold-ca-python].name`, falling back to the root directory name.
+- **Impact**: it only changes for projects where `[project].name` was edited by hand and no longer matches the tool section.
+
+### C-2: `gpipe` conflict message (FR-016)
+
+- **Before**:
+  ```
+  Error: '<display>' already exists at '<path>'. Use --force to overwrite.
+  Hint: Remove the existing file first or choose a different provider.
+  ```
+- **After**:
+  ```
+  Error: '<display>' already exists at '<path>'.
+  Hint: Remove the existing file first or choose a different provider.
+  ```
+
+### C-3: TOML sections visible in the `gep` output (FR-021)
+
+- **Before**: Rich interprets `[project.scripts]` as markup and drops it:
+  ```
+  Would update : my_app = "my_app.server:start_server"
+  ✓ Updated : my_app = "my_app.server:start_server"
+  ```
+- **After**: `escape()` is applied, as is already done for `[project.dependencies]`:
+  ```
+  Would update [project.scripts]: my_app = "my_app.server:start_server"
+  ✓ Updated [project.scripts]: my_app = "my_app.server:start_server"
+  ```

scaffold_ca_python-0.2.1/specs/022-solid-code-cleanup/contracts/factory-extension.md

@@ -0,0 +1,46 @@
+# Contract: adding a new type without touching `commands/`
+
+An internal contract for maintainers. `tests/factory/test_extensibility.py` verifies it.
+
+## Entry point
+
+1. Create `factory/entry_points/ep_<type>.py`:
+
+   ```python
+   class EntryPointFoo(EntryPointFactory):
+       subdir: ClassVar[str] = "foo"
+       supported_flags: ClassVar[frozenset[EntryPointFlag]] = frozenset({EntryPointFlag.ENABLE_KAFKA})
+       conflicts: ClassVar[tuple[EntryPointConflict, ...]] = ()
+
+       def build(self, builder: ModuleBuilder) -> None: ...
+   ```
+
+2. Register the factory with one line in `factory/entry_points/__init__.py`:
+
+   ```python
+   ENTRY_POINT_FACTORIES["foo"] = EntryPointFoo
+   ```
+
+3. Add its templates under `templates/entry_point/foo/` and their test under `tests/templates/`, as Constitution II requires.
+
+With that, `gep --type foo` does the following with no further changes:
+
+- validates flags with messages derived from the registered types (research R-02);
+- applies the `conflicts` guards and the duplicate guard on `subdir`;
+- shows `result_notes()`, which by default is the `main.py` replacement notice;
+- registers the script if the factory called `builder.set_project_script(...)`.
+
+## Driven adapter
+
+- Inherit from `DrivenAdapterFactory`.
+- Declare `fixed_name`, or `None` when `--name` provides the name.
+- Register it in `factory/driven_adapters/__init__.py`.
+
+## Pipeline
+
+- Add a `PipelineFactory(output_path=…, template=…, display_name=…)` instance to `PIPELINE_PROVIDERS` in `factory/pipelines/__init__.py`.
+
+## Guarantees
+
+- An unknown `--type` produces `Unknown type '<x>'. Allowed: <registry keys in order>.`. An unknown `--provider` produces `Unknown provider '<x>'. Allowed: <registry keys in order>.`.
+- No module in `commands/` contains type literals (`"restapi"`, `"mcp"`, `"github"`…). The exception is `add_mcp_tool.py`, which is MCP-specific by definition: it validates `--type mcp`.

scaffold_ca_python-0.2.1/specs/022-solid-code-cleanup/data-model.md

@@ -0,0 +1,112 @@
+# Data Model: SOLID refactor and comment cleanup
+
+Internal entities that the refactor introduces or modifies. There is no new persistence: the only persisted state is still the generated project and its `pyproject.toml`.
+
+## ProjectContext (modified: how it is loaded)
+
+| Field | Type | Source |
+|---|---|---|
+| `name` | `str` (validated by `NAME_RE`) | `[tool.scaffold-ca-python].name`; if missing, the root directory name |
+| `python_package` | `str` (computed) | `to_snake_case(name)` |
+| `python_package_script` | `str` (computed) | `to_kebab_case(name)` |
+
+- **Single loader**: `core.project_detector.load_project_context(root: Path) -> ProjectContext`.
+- **FR-011 rule**: `python_package` stays in snake_case. The code `gep` generates does not change for projects created with the tool, because in those `[project].name == [tool.scaffold-ca-python].name`.
+- **Behavior change (FR-010)**: `gep` and `--add-tool` stop reading `[project].name`.
+
+## EntryPointOptions (new, `models/options.py`)
+
+Dataclass with `frozen=True, slots=True`. Groups the 12 parameters of `gep`.
+
+| Field | Type | Default |
+|---|---|---|
+| `type_` | `str` | — |
+| `swagger` | `str \| None` | `None` |
+| `enable_kafka` | `bool` | `False` |
+| `enable_mcp_client` | `bool` | `False` |
+| `with_resources` | `bool` | `False` |
+| `with_prompts` | `bool` | `False` |
+| `add_tool` | `bool` | `False` |
+| `name` | `str \| None` | `None` |
+| `params` | `tuple[str, ...]` | `()` |
+| `returns` | `str` | `"str"` |
+| `description` | `str \| None` | `None` |
+| `dry_run` | `bool` | `False` |
+
+Methods:
+- `creation_flags() -> list[str]`: returns the active creation flags, in the current order (`--swagger`, `--enable-kafka`, `--enable-mcp-client`, `--with-resources`, `--with-prompts`). The `--add-tool` guard uses it.
+- `apply_to(builder, routes) -> None`: transfers the build parameters to the builder (see research R-05).
+
+## EntryPointFlag (new, enum in `factory/entry_points/base.py`)
+
+| Member | Label in messages | Verb | Active when |
+|---|---|---|---|
+| `SWAGGER` | `--swagger` | `is` | `options.swagger` is truthy |
+| `ENABLE_MCP_CLIENT` | `--enable-mcp-client` | `is` | `options.enable_mcp_client` |
+| `MCP_PRIMITIVES` | `--with-resources and --with-prompts` | `are` | `with_resources or with_prompts` |
+| `ENABLE_KAFKA` | `--enable-kafka` | `is` | `options.enable_kafka` |
+
+The command evaluates the flags in table order. Research R-02 describes how the message is derived.
+
+## EntryPointConflict (new)
+
+A named tuple `(label: str, subdir: str)`: a directory under `infrastructure/entry_points/` whose existence prevents creating the type.
+
+## EntryPointFactory (new, ABC implementing `ModuleFactory`)
+
+| Member | Type | Default |
+|---|---|---|
+| `subdir` | `ClassVar[str]` | required |
+| `supported_flags` | `ClassVar[frozenset[EntryPointFlag]]` | `frozenset()` |
+| `conflicts` | `ClassVar[tuple[EntryPointConflict, ...]]` | `()` |
+| `build(builder)` | abstract | — |
+| `result_notes(project_root, pkg, type_key, *, dry_run)` | `list[str]` | `main.py` replacement notice |
+
+Declared values, equivalent to the current logic:
+
+| Type | subdir | supported_flags | conflicts | result_notes |
+|---|---|---|---|---|
+| `restapi` | `api/v1` | SWAGGER, ENABLE_MCP_CLIENT, ENABLE_KAFKA | `mcp_server`, `agent` | override: `main.py` deletion + `[project.scripts]` (escaped, C-3) |
+| `mcp` | `mcp_server` | MCP_PRIMITIVES, ENABLE_KAFKA | `restapi`→`api` | default |
+| `agent` | `agent` | ENABLE_MCP_CLIENT, ENABLE_KAFKA | `restapi`→`api` | default |
+| `generic` | `generic` | ENABLE_MCP_CLIENT, ENABLE_KAFKA | — | default |
+
+Note: today `--enable-kafka` and `--enable-mcp-client` are accepted without error by types that don't use them. Declaring them as supported keeps that behavior.
+
+## DrivenAdapterFactory (new, ABC)
+
+| Member | Type | Meaning |
+|---|---|---|
+| `fixed_name` | `ClassVar[str \| None]` | when set, `--name` is ignored (`rest_consumer`, `secrets`) |
+| `module_name(name: str \| None) -> str \| None` | method | returns `fixed_name or name`. When the result is `None`, the command fails with `"--name is required when --type is {type}."` |
+
+The subdirectory is `to_snake_case(module_name)`.
+
+## PipelineFactory (new, `factory/pipelines/`)
+
+| Field | Type | github | azure |
+|---|---|---|---|
+| `output_path` | relative `PurePosixPath` | `.github/workflows/ci.yml` | `azure-pipelines.yml` |
+| `template` | `str` | `pipeline/github/ci.yml.jinja2` | `pipeline/azure/azure_pipelines.yml.jinja2` |
+| `display_name` | `str` | `ci.yml` | `azure-pipelines.yml` |
+
+`PIPELINE_PROVIDERS: dict[str, PipelineFactory]` keeps the `github, azure` order for the `Allowed: …` message. `build()` renders with the `ProjectContext` (a Pydantic model), so it complies with Constitution II.
+
+## ModuleBuilder (modified)
+
+| Change | Detail |
+|---|---|
+| + `set_project_script(entry_fn: str = "start_server")` | replaces `add_param("scripts_entry"/"scripts_entry_fn")` |
+| + `pending_project_script: str \| None` (property) | what tests and dry-run output read |
+| `persist()` | applies dependencies, groups and the script; no longer reads magic keys from `_params` |
+| `add_param`/`get_param` | kept for build flags (R-05) |
+
+## ModuleTarget (new, `core/module_locator.py`)
+
+`find_module_targets(project_root, pkg, snake) -> list[tuple[Path, Path | None]]`. A single implementation, shared by `delete_module` (preview) and `DeleteModuleFactory` (deletion).
+
+## Internal utilities (stateless)
+
+- `commands/_shared.py`: see research R-07.
+- `commands/_entry_point_rules.py`: `check_flags()`, `check_conflicts()` (research R-02/R-03).
+- New templates: `project/package_init.py.jinja2`, `project/empty.jinja2` (research R-13).

scaffold_ca_python-0.2.1/specs/022-solid-code-cleanup/plan.md

@@ -0,0 +1,189 @@
+# Implementation Plan: SOLID refactor and comment cleanup of the scaffolder
+
+**Branch**: `feature/022-solid-code-cleanup` | **Date**: 2026-10-22 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `/specs/022-solid-code-cleanup/spec.md`
+
+## Summary
+
+Internal refactor of `src/scaffold_ca_python/` with no change to the CLI's observable behavior, apart from the allowed changes C-1, C-2 and C-3. It has five parts.
+
+1. **Shared command utilities.** A common layer for the commands (`commands/_shared.py`) centralizes:
+   - errors with a resolution hint;
+   - project-root lookup;
+   - duplicate guards;
+   - the dry-run tree;
+   - the `--dry-run` option.
+2. **Single context loader.** `load_project_context` moves to `core/project_detector.py` and fixes the `gep` inconsistency.
+3. **Type knowledge lives in the factories.** Entry-point, driven-adapter and pipeline factories declare what is specific to their type through base classes with `ClassVar`s. The registries move into their `factory/` packages, so a new type does not touch `commands/`.
+4. **Complexity ≤ 10.** `_add_tool_impl`, `_generate_entry_point_impl`, `FileWriter._commit`, `StructureValidator.validate` and `DeleteModuleFactory.build` are split.
+5. **Comments, guardrails and output fixes.** Comments and docstrings are cleaned up (Google style, no Spec Kit IDs). Ruff `B`, `SIM` and `C90` are enabled. The `gpipe` hint (FR-016) and the `[project.scripts]` output (FR-021) are fixed.
+
+## Technical Context
+
+**Language/Version**: Python 3.13.
+
+**Primary Dependencies**: Typer (with `Annotated`), Rich, Jinja2, Pydantic v2, PyYAML. No dependencies are added.
+
+**Storage**: local files (the generated project and its `pyproject.toml`).
+
+**Testing**: pytest, pytest-cov (≥80% gate), pytest-benchmark and `typer.testing.CliRunner`. Baseline measured on 2026-10-22: **739 passed, 1 skipped, 96.50% coverage**.
+
+**Target Platform**: cross-platform CLI (macOS, Linux, Windows) distributed through PyPI.
+
+**Project Type**: CLI (single project, `src/` layout).
+
+**Performance Goals**: no regression in `tests/commands/test_performance.py`.
+
+**Constraints**:
+- Output is byte-for-byte identical in generated files, messages and exit codes. The exceptions are:
+  - FR-010 (project context);
+  - FR-016 (`gpipe` message);
+  - FR-021 (`[project.scripts]` shown literally).
+- Existing Jinja templates are not modified. Only two new ones are added (FR-004, research R-13).
+- `mypy --strict` must pass.
+
+**Scale/Scope**: about 4.4k LOC in 40 modules and 50 test files.
+
+Violations measured today with `ruff --select B,SIM,C90` and `max-complexity=10`:
+- **`src/`, 10 in total:**
+  - 6 × C901: `_add_tool_impl` 26, `_generate_entry_point_impl` 24, `_generate_driven_adapter_impl` 13, `StructureValidator.validate` 13, `FileWriter._commit` 12, `DeleteModuleFactory.build` 12.
+  - 2 × B904, 1 × B905 and 1 × SIM108.
+- **`tests/`:** 2 × B017. No C90 violations.
+- **B008:** does not appear, because Typer uses `Annotated`.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* Constitution version: **2.1.0**.
+
+| Principle | Assessment | Status |
+|---|---|---|
+| I. Clean Architecture in generated projects | Templates and generated output don't change. `vs` keeps its logic; only the complexity of `validate` is reduced. | ✅ |
+| II. Template-driven generation | `generate_project` and `generate_pipeline` switch to `TemplateRenderer.render()` with packaged templates instead of `render_string(_tmpl())`. Two files of `ca` that don't come from a template today now do, with the same output (FR-004, R-13): the root package `__init__.py` (an f-string) and the empty `src/tests/__init__.py`. They use the new templates `project/package_init.py.jinja2` and `project/empty.jinja2`. Factories still pass template contexts as `dict`, which is pre-existing debt (see Complexity Tracking). No new code introduces `dict` contexts: the `render_into` helper was dropped. | ✅ / ⚠️ pre-existing debt (Governance v2.1.0) |
+| III. Command parity and `--dry-run` | Commands, aliases and flags don't change, and the parity and checksum tests are kept. | ✅ |
+| IV. Python idioms | Compliance improves: consistent `X \| None` typing, extended ruff rules and strict mypy with no new `type: ignore`. | ✅ |
+| V. Test-first (NON-NEGOTIABLE) | Every story starts with red tests, among them the context regression (FR-020), extensibility with a fake factory, the new `gpipe` message, the `[project.scripts]` output (FR-021), `set_project_script` and the new templates. The pure refactor is covered by the existing suite, green before and after each step. | ✅ |
+| VI. Developer Experience | FR-016 fixes an invalid hint (`--force`) and FR-021 makes `[project.scripts]` visible in the output. 38 of the 56 error messages in `commands/` have no `Hint:`. FR-003 keeps them unchanged; this is pre-existing debt. | ⚠️ pre-existing debt (Governance v2.1.0) |
+| VII. Branches | `feature/022-solid-code-cleanup`, with the `feature/` prefix the repo uses. | ✅ |
+
+**Result**: the gate passes. Two pre-existing violations are kept under the "Pre-existing violations" governance clause (v2.1.0):
+- VI: missing resolution hints;
+- II: template contexts passed as `dict`.
+
+The feature does not introduce or worsen either one. The follow-up spec directories are created in T063 before merge.
+
+**Post-design re-check (Phase 1)**: ✅. The design in [data-model.md](data-model.md) and [contracts/](contracts/):
+- only adds base classes, `ClassVar`s and internal utilities;
+- doesn't change existing templates or flags;
+- changes the output only through C-1, C-2 and C-3.
+
+The adapted tests only change imports or where a factory is registered (see research R-08).
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/022-solid-code-cleanup/
+├── plan.md              # This file
+├── research.md          # Phase 0: design decisions
+├── data-model.md        # Phase 1: internal entities (options, descriptors, context)
+├── quickstart.md        # Phase 1: validation guide
+├── contracts/
+│   ├── cli-behavior.md        # Observable behavior contract (+ allowed changes C-1..C-3)
+│   └── factory-extension.md   # Contract for adding new types
+├── checklists/
+│   └── requirements.md
+└── tasks.md             # Phase 2 (/speckit-tasks)
+```
+
+### Source Code (repository root)
+
+```text
+src/scaffold_ca_python/
+├── cli.py                          # no functional changes
+├── commands/
+│   ├── _shared.py                  # NEW: fail(), require_project_root(), validate_name_or_exit(),
+│   │                               #      ensure_absent(), print_dry_run_tree(),
+│   │                               #      print_pending_dependencies(), dry_run_option(), build_and_persist()
+│   ├── _entry_point_rules.py       # NEW: check_flags(), check_conflicts() (research R-02/R-03)
+│   ├── generate_entry_point.py     # orchestration only: options → validation → factory → presentation
+│   ├── add_mcp_tool.py             # NEW: --add-tool flow extracted from generate_entry_point
+│   ├── generate_driven_adapter.py  # no if/elif per type
+│   ├── generate_pipeline.py        # uses ModuleBuilder + PIPELINE_PROVIDERS, injectable renderer/writer
+│   ├── generate_project.py         # file table + injectable ModuleBuilder
+│   ├── generate_model.py / generate_use_case.py / generate_helper.py / delete_module.py
+│   │                               # no single-entry _REGISTRY; use _shared
+│   ├── update_project.py           # _run_uv() removes the duplicated try/except
+│   └── validate_structure.py
+├── core/
+│   ├── project_detector.py         # + load_project_context() (single definition)
+│   ├── module_locator.py           # NEW: find_module_targets() (shared by dm and its factory)
+│   ├── openapi_routes.py           # NEW: parse_routes() (formerly _parse_swagger in gep)
+│   ├── module_builder.py           # + set_project_script(); no magic keys in persist()
+│   ├── file_writer.py              # _commit split; zip(strict=True)
+│   ├── structure_validator.py      # validate split into _classify/_parse/_violations_in
+│   └── mcp_tool_spec.py, pyproject_writer.py, template_renderer.py, name_utils.py  # docstring cleanup
+├── factory/
+│   ├── __init__.py                 # ModuleFactory (Protocol, unchanged)
+│   ├── entry_points/
+│   │   ├── __init__.py             # ENTRY_POINT_FACTORIES (registry)
+│   │   ├── base.py                 # NEW: EntryPointFactory, EntryPointConflict, EntryPointFlag
+│   │   └── ep_restapi.py, ep_mcp.py, ep_agent.py, ep_generic.py  # declare ClassVars
+│   ├── driven_adapters/
+│   │   ├── __init__.py             # DRIVEN_ADAPTER_FACTORIES
+│   │   ├── base.py                 # NEW: DrivenAdapterFactory
+│   │   └── da_*.py
+│   ├── pipelines/                  # NEW
+│   │   ├── __init__.py             # PIPELINE_PROVIDERS
+│   │   └── pipeline_factory.py     # PipelineFactory (github, azure as descriptor instances)
+│   └── simple/                     # no structural changes; cleanup
+├── models/
+│   ├── context.py                  # docstring cleanup
+│   └── options.py                  # NEW: EntryPointOptions (frozen dataclass)
+└── templates/project/
+    ├── package_init.py.jinja2      # NEW (R-13)
+    └── empty.jinja2                # NEW (R-13)
+
+tests/                              # same layout; new tests:
+├── commands/test_shared.py
+├── commands/test_behavior_contract.py   # US1 safety net + C-3
+├── core/test_project_context.py    # FR-010/FR-020 regression
+├── core/test_module_locator.py
+├── core/test_openapi_routes.py
+├── models/test_options.py
+├── test_source_hygiene.py          # FR-015
+└── factory/test_extensibility.py   # extended: fake factory with a full descriptor
+```
+
+**Structure Decision**: The single project with `src/` layout stays.
+- **Registries:** type registries move from `commands/` to the `__init__.py` of each `factory/` package, so adding a type does not modify `commands/` (SC-005).
+- **Shared logic:** command-shared logic lives in `commands/_shared.py` and not in `core/`, because it depends on Rich and Typer (it is presentation). `core/` stays independent of the CLI.
+- **Template helpers:** the local `tpl()` helpers in the entry-point factories stay as they are. A shared `render_into()` helper was considered and dropped, because it would be new code that accepts `dict` contexts (Constitution II, Governance v2.1.0: new code must comply).
+
+## Suggested implementation order
+
+Each step leaves the suite green and can be its own commit:
+
+1. **Guardrails first:** enable `B`, `SIM` and `C90` in `pyproject.toml`, with a temporary C901 `per-file-ignores` only for the affected modules. It is removed at the end. Fix B904, B905, SIM108 and B017.
+2. **Shared utilities:** create and test `commands/_shared.py`.
+3. **Story 1 (P1), safety net:** behavior-contract tests, green against the current code.
+4. **Story 2 (P1):** `EntryPointFactory` and `DrivenAdapterFactory`, registries in `factory/`, `set_project_script()` and `PipelineFactory`.
+5. **Story 3 (P2), TDD:** single `load_project_context` and its regression test.
+6. **Story 4 (P2):**
+   - split gep (`EntryPointOptions`, `add_mcp_tool.py`, `openapi_routes.py`), `FileWriter`, `StructureValidator`, and `delete_module` (with `module_locator`);
+   - `generate_project` switches to the file table, the new templates and an injectable builder.
+7. **Stories 5 and 6 (P3):**
+   - comment and docstring cleanup and dead code;
+   - the `gpipe` message (C-2) and the `[project.scripts]` output (C-3);
+   - remove the temporary `per-file-ignores`.
+8. **Final verification:** full suite, checksum, parity, generated-tree comparison ([quickstart.md](quickstart.md)), and the follow-up spec directories 023/024.
+
+## Complexity Tracking
+
+Pre-existing violations kept under the Constitution v2.1.0 "Pre-existing violations" governance clause:
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|---|---|---|
+| **VI**: 38 of 56 error messages in `commands/` have no `Hint:`. Examples: the `gep` flag validation, `Unknown type` and `--name is required…`. They are kept unchanged. | FR-003 requires the output to stay unchanged during the refactor. Adding hints would mix a UX change into the refactor. | Adding them here would invalidate the US1 safety net (T008–T010) and multiply the allowed changes. It will be resolved in follow-up feature **023-error-hints**. |
+| **II**: factories pass `dict` contexts to templates. The dicts come from the already validated `ModuleContext.model_dump()`, plus `bool` flags. | Keep the output identical and the refactor scope bounded. | Typing every context with Pydantic touches all 11 factories and their templates. It will be resolved in follow-up feature **024-typed-template-contexts**. No new code in this feature adds `dict` contexts. |

scaffold_ca_python-0.2.1/specs/022-solid-code-cleanup/quickstart.md

@@ -0,0 +1,93 @@
+# Quickstart: validating the 022 refactor
+
+End-to-end validation guide. Design details are in [data-model.md](data-model.md) and [contracts/](contracts/).
+
+## Prerequisites
+
+```bash
+export SSL_CERT_FILE=/etc/ssl/cert.pem   # only if uv fails with a TLS error
+uv sync
+git switch feature/022-solid-code-cleanup
+REPO=~/projects/ingsw/scaffold-clean-architecture-py
+```
+
+## 1. Reference tree (before the refactor)
+
+Run once from `main`, before starting:
+
+```bash
+gen_tree() {   # $1 = output dir, $2 = sha file
+  mkdir -p "$1" && cd "$1"
+  uv run --project "$REPO" scaffold-ca-python ca --name demo-app
+  cd demo-app
+  for t in "gm --name order" "guc --name create_order" "gh --name clock" \
+           "gda --type rest-consumer" "gda --type generic --name cache" \
+           "gep --type mcp --with-resources" "gep --type mcp --add-tool --name ping --returns str" \
+           "gpipe --provider github"; do
+    uv run --project "$REPO" scaffold-ca-python $t
+  done
+  sed -i '' '/^created_at = /d' pyproject.toml          # timestamp differs on every run
+  find . -type f -print0 | sort -z | xargs -0 shasum > "$2"
+}
+gen_tree /tmp/ref022 /tmp/ref022.sha
+```
+
+Repeat for restapi in another directory, because restapi is incompatible with mcp. Use `ca --name demo-api`, then `gep --type restapi` and `gda --type secrets`, and save the hashes to `/tmp/ref022-restapi.sha`.
+
+After the refactor, run the same thing in `/tmp/new022` and `/tmp/new022-restapi`, then compare:
+
+```bash
+diff /tmp/ref022.sha /tmp/new022.sha
+diff /tmp/ref022-restapi.sha /tmp/new022-restapi.sha
+```
+
+**Expected**: no differences. This covers User Story 1 and SC-001.
+
+## 2. Suite and guardrails
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run mypy src/
+uv run pytest
+```
+
+**Expected**:
+- Everything is green, with coverage ≥80% (baseline: 96.50%).
+- The 739 existing tests pass, plus the new ones. Only the tests listed in research R-08 and those of C-1, C-2 and C-3 are adapted.
+
+This covers SC-001, SC-002 and SC-007.
+
+## 3. Measurable criteria
+
+```bash
+# SC-003: zero Spec Kit IDs in src/
+grep -rnE '\b(T0[0-9]{2}|FR-[0-9]{3}|US-?[0-9]|R-[0-9]{2})\b|Phase [0-9]' src/ | grep '\.py:' | wc -l   # → 0
+
+# SC-004: single definitions
+grep -rn "def load_project_context\|def _load_project_context" src/ | wc -l             # → 1
+grep -rn "No scaffold-ca-python project found" src/ | wc -l                            # → 1
+
+# SC-005: no type literals in commands/ (except add_mcp_tool.py)
+grep -nE '"(restapi|agent|generic|rest-consumer|secrets|github|azure)"' src/scaffold_ca_python/commands/*.py   # → empty
+
+# No temporary C901 ignores left
+grep -n "C901" pyproject.toml                                                           # → empty
+
+# FR-004: only the two new templates were added; nothing existing was modified
+git diff --stat main -- src/scaffold_ca_python/templates
+```
+
+## 4. Allowed behavior changes
+
+- **C-1 (FR-010)**: run `uv run pytest tests/core/test_project_context.py`. It uses a project whose `[project].name` differs from `[tool.scaffold-ca-python].name`; `gep` and `gm` must resolve the same package.
+- **C-2 (FR-016)**: run `scaffold-ca-python gpipe --provider github` twice. The second error does not mention `--force`.
+- **C-3 (FR-021)**: `scaffold-ca-python gep --type restapi --dry-run` shows `Would update [project.scripts]: <pkg> = "<pkg>.server:start_server"`.
+
+## 5. Extensibility
+
+```bash
+uv run pytest tests/factory/test_extensibility.py -v
+```
+
+**Expected**: the fake factory registered in `ENTRY_POINT_FACTORIES` generates its files, validates flags and shows its notes, and `commands/` was not modified.