csrd-utils 0.3.82__tar.gz → 0.3.86__tar.gz

{csrd_utils-0.3.82 → csrd_utils-0.3.86}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-utils
-Version: 0.3.82
+Version: 0.3.86
 Summary: CLI utilities for csrd service generation and feature augmentation
 Project-URL: Repository, https://github.com/csrd-api/fastapi-common
 Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/utils
@@ -8,7 +8,9 @@ Project-URL: Changelog, https://github.com/csrd-api/fastapi-common/blob/main/CHA
 License: MIT
 Requires-Python: >=3.12
 Requires-Dist: cookiecutter<3,>=2.6
+Requires-Dist: pydantic<3,>=2.6
 Requires-Dist: pyyaml<7,>=6
+Requires-Dist: ruamel-yaml<1,>=0.18
 Description-Content-Type: text/markdown
 
 # csrd-utils

{csrd_utils-0.3.82 → csrd_utils-0.3.86}/pyproject.toml

@@ -1,12 +1,14 @@
 [project]
 name = "csrd-utils"
-version = "0.3.82"
+version = "0.3.86"
 description = "CLI utilities for csrd service generation and feature augmentation"
 license = { text = "MIT" }
 requires-python = ">=3.12"
 dependencies = [
     "cookiecutter>=2.6,<3",
     "PyYAML>=6,<7",
+    "pydantic>=2.6,<3",
+    "ruamel.yaml>=0.18,<1",
 ]
 readme = "README.md"
 

{csrd_utils-0.3.82 → csrd_utils-0.3.86}/src/csrd_utils/__main__.py

@@ -3,6 +3,7 @@
 import argparse
 import json
 import shutil
+import sys
 from contextlib import suppress
 from importlib.metadata import version
 from pathlib import Path
@@ -24,6 +25,9 @@ from .cluster import (
 from .doctor import run_doctor
 from .generator import generate_platform_service, generate_service
 from .resources import features_path
+from .v2.compose import apply as v2_compose_apply
+from .v2.compose import validate as v2_compose_validate
+from .v2.generate import run_generate_menu as run_v2_generate_menu
 
 
 class GenerateServiceArgs(TypedDict):
@@ -57,6 +61,7 @@ class GenerateWorkspaceArgs(TypedDict):
     output_dir: Path
     overwrite_if_exists: bool
     generate: str
+    git_init: bool
 
 
 class ExtractWorkspaceServiceArgs(TypedDict):
@@ -416,12 +421,14 @@ def _collect_new_workspace_config(args: argparse.Namespace) -> GenerateWorkspace
     generate = args.generate or _prompt_choice(
         "Generate in workspace now", ["none", "service", "cluster"], "service"
     )
+    git_init = _prompt_bool("Initialize git repository", True)
     return GenerateWorkspaceArgs(
         {
             "name": name,
             "output_dir": output_dir,
             "overwrite_if_exists": args.force,
             "generate": generate,
+            "git_init": git_init,
         }
     )
 
@@ -438,6 +445,10 @@ def _create_workspace(config: GenerateWorkspaceArgs) -> Path:
         )
 
     _write_workspace_marker(workspace_root)
+
+    if config.get("git_init", False):
+        _git_init(workspace_root)
+
     return workspace_root
 
 
@@ -577,6 +588,20 @@ def _write_workspace_marker(path: Path) -> None:
     (path / WORKSPACE_MARKER).write_text("workspace: csrd\n", encoding="utf-8")
 
 
+def _git_init(path: Path) -> None:
+    """Run ``git init`` inside *path* if not already a git repository."""
+    import subprocess
+
+    if (path / ".git").exists():
+        return
+    subprocess.run(
+        ["git", "init"],
+        cwd=path,
+        check=True,
+        capture_output=True,
+    )
+
+
 def _is_workspace(path: Path) -> bool:
     return (path / WORKSPACE_MARKER).is_file()
 
@@ -1199,6 +1224,76 @@ def _build_parser() -> argparse.ArgumentParser:
     completion_sub = completion.add_subparsers(dest="completion_shell", required=True)
     completion_sub.add_parser("bash", help="Print bash completion script")
 
+    v2 = sub.add_parser("v2", help="Preview next-gen generator and compose workflow")
+    v2_sub = v2.add_subparsers(dest="v2_command")
+
+    v2_generate = v2_sub.add_parser("generate", help="Open interactive v2 generator menu")
+    v2_generate.add_argument(
+        "target",
+        nargs="?",
+        choices=["workspace", "preset", "add-service", "add-infra", "remove-infra", "empty"],
+        help="Direct generator target (workspace, preset, add-service, add-infra, remove-infra)",
+    )
+    v2_generate.add_argument(
+        "--name",
+        dest="generate_name",
+        help="Workspace or service name",
+    )
+    v2_generate.add_argument(
+        "--git-init",
+        action="store_true",
+        default=False,
+        help="Initialize a git repository in the generated workspace",
+    )
+    v2_generate.add_argument(
+        "--features",
+        dest="features",
+        nargs="*",
+        choices=["database", "caching", "messaging"],
+        default=None,
+        help="Service capabilities to wire (for add-service)",
+    )
+    v2_generate.add_argument(
+        "--port",
+        dest="port",
+        type=int,
+        default=None,
+        help="Service port (for add-service)",
+    )
+    v2_generate.add_argument(
+        "--infra-type",
+        dest="infra_type",
+        choices=["postgres", "mariadb", "sqlite", "redis", "rabbitmq"],
+        default=None,
+        help="Infrastructure type (for add-infra)",
+    )
+
+    v2_compose = v2_sub.add_parser("compose", help="Compose v2 operations")
+    v2_compose_sub = v2_compose.add_subparsers(dest="v2_compose_command")
+
+    v2_compose_validate = v2_compose_sub.add_parser("validate", help="Validate csrd-compose.yaml")
+    v2_compose_validate.add_argument(
+        "--output", type=Path, default=Path.cwd(), help="Workspace root"
+    )
+    v2_compose_validate.add_argument(
+        "--json", action="store_true", help="Print validated compose spec as JSON"
+    )
+
+    v2_compose_plan = v2_compose_sub.add_parser("plan", help="Preview resolved compose baseline")
+    v2_compose_plan.add_argument("--output", type=Path, default=Path.cwd(), help="Workspace root")
+    v2_compose_plan.add_argument("--json", action="store_true", help="Print plan payload as JSON")
+
+    v2_compose_apply = v2_compose_sub.add_parser(
+        "apply", help="Render baseline workspace artifacts"
+    )
+    v2_compose_apply.add_argument("--output", type=Path, default=Path.cwd(), help="Workspace root")
+    v2_compose_apply.add_argument(
+        "--git-init",
+        action="store_true",
+        default=False,
+        help="Initialize a git repository in the workspace",
+    )
+
     return parser
 
 
@@ -1323,9 +1418,106 @@ def _run_audit(service: Path | None, as_json: bool) -> int:
 
 
 def main() -> int:
+    # Shorthand: `csrd v2 compose <path>` => `csrd v2 compose apply --output <path>`
+    raw_argv = sys.argv[1:]
+    if len(raw_argv) >= 3 and raw_argv[0] == "v2" and raw_argv[1] == "compose":
+        third = raw_argv[2]
+        if third not in {"validate", "plan", "apply", "-h", "--help"} and not third.startswith("-"):
+            shorthand_dir = Path(third).resolve()
+            has_compose_spec = (shorthand_dir / "csrd-compose.yaml").is_file() or (
+                shorthand_dir / "csrd-compose.yml"
+            ).is_file()
+            if not has_compose_spec:
+                print(f"ERROR: Compose shorthand requires csrd-compose.yaml in: {shorthand_dir}")
+                print(
+                    "Hint: create a spec first (csrd v2 generate empty --name <name>) "
+                    "or use explicit apply: csrd v2 compose apply --output <path>"
+                )
+                return 1
+            sys.argv = [
+                sys.argv[0],
+                "v2",
+                "compose",
+                "apply",
+                "--output",
+                third,
+                *raw_argv[3:],
+            ]
+
     parser = _build_parser()
     args = parser.parse_args()
 
+    if args.command == "v2":
+        if getattr(args, "v2_command", None) == "generate":
+            return run_v2_generate_menu(
+                target=getattr(args, "target", None),
+                name=getattr(args, "generate_name", None),
+                git_init=getattr(args, "git_init", False),
+                features=getattr(args, "features", None),
+                port=getattr(args, "port", None),
+                infra_type=getattr(args, "infra_type", None),
+            )
+
+        if getattr(args, "v2_command", None) != "compose":
+            parser.print_help()
+            return 0
+
+        compose_command = getattr(args, "v2_compose_command", None)
+        if compose_command is None:
+            parser.print_help()
+            return 0
+
+        output_dir = Path(args.output).resolve()
+        try:
+            if compose_command == "apply":
+                generated_root = v2_compose_apply(
+                    output_dir, git_init=getattr(args, "git_init", False)
+                )
+                print(f"Rendered compose workspace at: {generated_root}")
+                return 0
+
+            if compose_command == "validate":
+                spec = v2_compose_validate(output_dir)
+                if args.json:
+                    print(json.dumps(spec.model_dump(mode="python"), indent=2, sort_keys=True))
+                else:
+                    print(f"Compose spec valid: {output_dir / 'csrd-compose.yaml'}")
+                return 0
+
+            if compose_command == "plan":
+                spec = v2_compose_validate(output_dir)
+                payload = {
+                    "workspace": spec.workspace.name,
+                    "version": spec.version,
+                    "services": len(spec.services),
+                    "infra": len(spec.infra),
+                    "presets": [preset.name for preset in spec.presets],
+                    "overrides_keys": sorted(spec.overrides.keys()),
+                }
+                if args.json:
+                    print(json.dumps(payload, indent=2, sort_keys=True))
+                else:
+                    print("Compose v2 plan")
+                    print(f"- workspace: {payload['workspace']}")
+                    print(f"- version: {payload['version']}")
+                    print(f"- services: {payload['services']}")
+                    print(f"- infra: {payload['infra']}")
+                    presets = payload["presets"]
+                    overrides_keys = payload["overrides_keys"]
+                    assert isinstance(presets, list)
+                    assert isinstance(overrides_keys, list)
+                    print(f"- presets: {', '.join(presets) if presets else '<none>'}")
+                    print(
+                        f"- overrides: {', '.join(overrides_keys) if overrides_keys else '<none>'}"
+                    )
+                return 0
+        except ValueError as exc:
+            print(f"ERROR: {exc}")
+            return 1
+
+        parser.print_help()
+        return 0
+
     if args.command == "new" and args.new_command == "service":
         try:
             service_config = _collect_new_service_config(args)

csrd_utils-0.3.86/src/csrd_utils/v2/AGENTS.md

@@ -0,0 +1,349 @@
+# Menu System & Compose Design Rules
+
+This file captures the design principles of the `v2/generate` menu system
+and the `v2/compose` rendering pipeline.
+Consult it for every change that adds, removes, or modifies menus, menu items,
+prompts, interactive selection flows, or compose/renderer behavior.
+
+## Scope
+
+- Applies to `packages/utils/src/csrd_utils/v2/**`.
+- Also follow `packages/utils/AGENTS.md` and the top-level `AGENTS.md`.
+
+## Drop-in replacement intent
+
+The `v2` module is intended to **fully replace** the bare `csrd` command.
+Once promoted, the `v2/` directory becomes the top-level implementation and
+the `v2` namespace disappears.
+
+**Naming rule**: Do not use "v2" in any module name, class name, function name,
+variable name, constant, test name, CLI label, or user-facing string inside this
+package. The only place "v2" appears is the directory name itself, which will be
+removed at promotion time. Names should read as if `v2/` does not exist —
+e.g. `compose`, `generate`, `ComposeSpec`, `render_workspace`, not
+`v2_compose`, `V2ComposeSpec`, `render_v2_workspace`.
+
+## Architecture overview
+
+### Generate layer (interactive / CLI)
+
+The menu system is split into three layers:
+
+| Layer | File | Responsibility |
+|---|---|---|
+| **Primitives** | `helpers.py` | `MenuItem` dataclass, rendering, TTY/non-TTY selection, prompt helpers (`prompt_text`, `prompt_yes_no`, `prompt_single_select`, `prompt_multi_select`). |
+| **Orchestration** | `menu.py` | Declarative item lists (`IN_WORKSPACE_ITEMS`, `_build_no_workspace_items`), context predicates, direct-mode dispatch, and the public `run_generate_menu` entry-point. |
+| **Handlers** | `handlers.py` | Business-logic callbacks invoked by menu items. Each returns an `int` exit code. Shared finalization via `_finalize_workspace`. |
+
+Changes must respect this separation. Do not put rendering logic in handlers
+or business logic in helpers.
+
+### Compose layer (deterministic rendering)
+
+The compose pipeline is split into focused modules:
+
+| Module | Responsibility |
+|---|---|
+| `models/spec.py` | Pydantic models: `ComposeSpec`, `ServiceNode`, `InfraNode`, `PresetDefinition`, constants (`INFRA_DATABASES`, `INFRA_CATEGORIES`, etc.) |
+| `compose/infra.py` | `InfraDescriptor` registry — single source of truth for all infra container defs, service env wiring, depends_on, and env example lines |
+| `compose/operations.py` | Workspace mutations: `add_service`, `add_infra`, `remove_infra`, `available_infra`, `configured_infra`, `apply`, `validate` |
+| `compose/renderer.py` | Pure `spec → file content` transforms: docker-compose.yml, .env.example, README, .gitignore, pyproject.toml, workspace marker |
+| `compose/scaffolder.py` | Cookiecutter template → workspace filesystem layout (idempotent) |
+| `compose/loader.py` | Load/save `csrd-compose.yaml` |
+| `compose/presets.py` | Preset definitions and category helpers |
+| `compose/yaml_editor.py` | YAML serialization utilities |
+| `compose/__init__.py` | Re-exports only — no business logic |
+
+## Non-negotiable design rules
+
+### 1. Deterministic rendering
+
+Every render function must be a **pure transform from spec to output**.
+Same `ComposeSpec` → same files, byte-for-byte.
+
+- **No randomness**: no UUIDs, timestamps, random ports, or non-deterministic ordering.
+- **No environment reads**: renderers must not read env vars, `$HOME`, `os.getcwd()`, or any external state.
+- **Stable iteration**: `spec.infra` and `spec.services` are ordered lists (not sets). Compose services appear in insertion order.
+- **Stable YAML**: `dumps_yaml` uses `default_flow_style=False` for consistent formatting.
+- **Test proof**: `test_render_workspace_is_idempotent` asserts two consecutive renders produce byte-identical output.
+
+### 2. Declarative spec as single source of truth
+
+`csrd-compose.yaml` (`ComposeSpec`) is the **only** source of truth for a workspace.
+
+- Renderers never inspect generated files to decide what to generate.
+- Data flow is one-directional: `user input → operations (mutate spec) → renderer (spec → files)`.
+- No feedback loops: the renderer does not read `docker-compose.yml` or scaffolded source to inform its output.
+
+### 3. Data-driven infra registry (DRY / Open-Closed)
+
+All infra knowledge lives in `INFRA_REGISTRY` (`infra.py`) as frozen `InfraDescriptor` instances.
+
+- **Adding a new infra type** requires only adding a new `InfraDescriptor` entry to the registry.
+- Do **not** scatter infra-specific if/elif branches across renderer, env example, or service wiring code.
+- The renderer queries the registry generically via `desc.service_env`, `desc.depends_on`, `desc.env_example_lines`.
+- Exception: sqlite is special-cased in `_wire_feature` because it needs per-service volumes with no shared container. This is documented inline.
+
+### 4. Single Responsibility (SRP)
+
+- `compose/__init__.py` — re-exports only, zero business logic.
+- `operations.py` — spec mutations (add/remove on disk).
+- `renderer.py` — spec → file content (no I/O decisions, no spec mutations).
+- `scaffolder.py` — cookiecutter execution and filesystem rearrangement.
+- `infra.py` — infra data and lookup helpers.
+- `handlers.py` — interactive/direct CLI handlers. Shared finalization via `_finalize_workspace`.
+
+Do not mix responsibilities across these modules.
+
+### 5. DRY: No duplicate definitions
+
+- **Infra wiring** (service env, depends_on, env example) is defined once in `InfraDescriptor`, not repeated in renderer, env builder, or handlers.
+- **Workspace finalization** (create dir → add infra → add services → render) is in `_finalize_workspace`, shared by both `create_workspace` and `create_workspace_from_preset`.
+- **DB detection** is in `infra.detect_configured_db`, not duplicated in renderer and handlers.
+- **Model types** are defined in `models/spec.py`, re-exported through `models/__init__.py` and `compose/__init__.py` — no shim modules or alias files.
+
+### 6. Idempotent scaffolding
+
+`scaffold_service` skips silently if `src/<service-name>/` already exists.
+User edits to scaffolded files are never overwritten on re-render.
+
+- `.env` is created only if missing (user customizations preserved).
+- All other workspace files (compose, env example, pyproject, README, gitignore) are overwritten on every render (they are derived from spec).
+
+### 7. Workspace filesystem contract
+
+```
+<ws-root>/
+  csrd-compose.yaml              ← spec (source of truth)
+  docker-compose.yml             ← rendered from spec
+  .env.example                   ← rendered from spec
+  .env                           ← created once, never overwritten
+  pyproject.toml                 ← rendered from spec (pytest config)
+  README.md                      ← rendered from spec
+  .gitignore                     ← rendered from spec
+  .csrd-workspace                ← marker file
+  Dockerfile.<service-name>      ← one per service, at root
+  src/<service-name>/            ← service source (kebab-case dir)
+  tests/unit/<service_snake>/    ← unit tests (snake_case dir)
+  tests/acceptance/<service_snake>/  ← acceptance stubs (snake_case dir)
+```
+
+- Service source dirs use **kebab-case** (matching `service.name`).
+- Test dirs use **snake_case** (valid Python package names).
+- Dockerfiles use kebab-case service name for the suffix, snake_case for the Python module reference in CMD.
+
+### 8. Consistent model paradigm
+
+All models use **Pydantic `BaseModel`** (from `models/base.py`).
+Do not use `@dataclass` for spec or preset models.
+Use `model_config = ConfigDict(frozen=True)` for immutable models (e.g. `PresetDefinition`).
+
+Exception: `InfraDescriptor` in `infra.py` uses `@dataclass(frozen=True)` because it is a
+compose-internal data structure, not a serializable spec model.
+
+### 9. Exception semantics
+
+- `FileNotFoundError` — missing spec file (`loader.py`).
+- `ValueError` — invalid spec content, duplicate service/infra, unconfigured infra removal.
+- `KeyError` — unknown infra type in registry lookup.
+
+Do not use generic `Exception` or mismatched exception types.
+
+### 10. Declarative item definitions
+
+Menu items are declared as static `list[MenuItem]` constants (or built by a
+simple factory when runtime data like `default_name` is needed).
+
+- **Do not** build menus with imperative if/else chains.
+- Use the `visible` predicate on `MenuItem` to hide items based on context.
+  The `filter_visible()` helper evaluates these at menu-build time.
+
+### 11. Dual-mode: interactive + direct dispatch
+
+Every interactive flow must have a non-interactive (direct) counterpart
+invokable via CLI flags (`target`, `--name`, `--database`, etc.).
+
+- `run_generate_menu` routes direct targets first, then falls through to the
+  interactive menu. Keep this order: direct dispatch → interactive.
+- Direct handlers are named `*_direct`, interactive ones `*_interactive`.
+
+### 12. TTY / non-TTY graceful degradation
+
+All interactive primitives must work in both TTY and non-TTY environments:
+
+- **TTY path**: arrow-key navigation via `cbreak_mode()`, `>` cursor marker.
+- **Non-TTY path**: numbered list with text input fallback.
+- Gate on `sys.stdin.isatty() and sys.stdout.isatty()` — never assume a terminal.
+- `cbreak_mode()` yields `None` when `termios` is unavailable; always handle that.
+- Escape key detection uses `select.select()` with a 50 ms timeout via
+  `_read_escape_seq()` to distinguish standalone Escape from arrow-key
+  prefixes (`\x1b[A`/`\x1b[B`).
+
+### 13. Cancel, interrupt, and back-navigation
+
+**Ctrl-C (KeyboardInterrupt)**:
+- Must **propagate** from all prompt primitives — they must NOT swallow it.
+- Only the outermost handler or `run_menu` catches it.
+- Handlers print `"Cancelled."` (wrapped in `contextlib.suppress`) and
+  return exit code `1`.
+- Swallowing at the primitive level causes fall-through — this is a bug.
+
+**Escape / back (GoBack)**:
+- `GoBack` is a lightweight exception raised by `prompt_single_select` and
+  `prompt_multi_select` when the user presses Escape (TTY) or types `0` /
+  `back` (non-TTY).
+- In **nested flows** (e.g. `_prompt_infra_categories`), catch `GoBack`
+  from sub-selects and loop back to the parent prompt.
+- In **top-level handlers**, catch `GoBack` and skip the step (empty selection).
+- In **`run_menu`**, Escape = cancel (same as selecting the cancel item).
+- Visual hints: `"Esc back"` (TTY), `"0) back"` (non-TTY).
+
+**EOF (EOFError)**:
+- Return quietly with the default/empty value from primitives.
+- `run_menu` returns `0`.
+
+### 14. Exit code contract
+
+All handlers and menu runners return an `int` exit code:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success or clean cancel |
+| `1` | Error or user interrupt |
+
+Do not raise exceptions to signal user-facing outcomes; print and return a code.
+
+### 15. Prompt conventions
+
+- `prompt_text(question, default=...)` — returns default on empty input or EOF.
+  In TTY mode uses `_tty_line_input` (cbreak-mode character-by-character
+  reading) so that Escape raises `GoBack` and Ctrl-C raises
+  `KeyboardInterrupt`. Non-TTY falls back to `input()`.
+- `prompt_yes_no(question, default=True)` — same TTY/non-TTY split. First
+  prompt defaults yes; "add another?" prompts default no.
+- `prompt_single_select` — auto-selects when only one option exists. Escape
+  raises `GoBack`.
+- `prompt_multi_select` — spacebar toggles, Enter confirms; non-TTY accepts
+  comma-separated numbers, `all`, or `back`/`0`. Escape raises `GoBack`.
+
+All four prompts support Escape for back-navigation. Do not invent new prompt
+primitives without adding them to `helpers.py` first.
+
+### 16. Composable wizard flows
+
+Multi-step interactive flows **must** use `run_wizard()` from `helpers.py`
+with a list of `WizardStep` callables.  Each step is a function that receives
+a shared `state: dict[str, object]` and either returns normally (advance) or
+raises `GoBack` (go back).  The wizard handles all back-navigation and
+interrupt logic automatically.
+
+```python
+# ✅ Correct — composable steps, no control flow boilerplate
+steps: list[WizardStep] = [
+    _step_workspace_name,
+    _step_infra_categories,
+    _step_services,
+    _step_git_init,
+]
+state = run_wizard(steps)
+```
+
+```python
+# ❌ Prohibited — hand-coded if/elif step dispatch
+while step <= 3:
+    if step == 0:
+        ...
+    elif step == 1:
+        ...
+```
+
+Rules:
+- **Never** use raw `while step <= N` / `if step == 0` dispatch in handlers.
+- Each step must be an independent `_step_*` function in `handlers.py`.
+- Steps that appear in more than one wizard flow must be shared (e.g.
+  `_step_workspace_name`, `_step_git_init`).
+- Steps communicate exclusively through the shared state dict.
+- `GoBack` at step 0 = cancel (exit code 0).
+- `KeyboardInterrupt` at any step = abort (exit code 1).
+
+Back-navigation semantics:
+```
+Step 0: name       ← Escape here = cancel (exit code 0)
+Step 1: infra      ← Escape here = back to step 0
+Step 2: services   ← Escape here = back to step 1
+Step 3: git init   ← Escape here = back to step 2
+```
+
+
+### 17. Naming & normalization
+
+- Service names: `normalize_service_name()` → kebab-case, appends `-service`.
+- Workspace names: `resolve_workspace_name()` → collapse whitespace, reject
+  path separators.
+- Always print a `"Normalized to: ..."` message when the name changes.
+
+### 18. Category-based infra selection
+
+Infrastructure is organized by category (`database`, `messaging`, `caching`)
+defined in `models/spec.py` via `INFRA_CATEGORIES`.
+
+- Step 1: multi-select categories.
+- Step 2: for each category, single-select the specific type (auto-select if
+  only one member).
+- Already-configured types are excluded from the available set.
+
+Do not bypass the category system with flat infra-type lists.
+
+### 19. Context awareness
+
+Menus adapt based on workspace presence:
+
+- **Inside workspace** (`csrd-compose.yaml` exists): show `add service`,
+  `add infra` (if slots remain), `remove infra` (if any configured), `cancel`.
+- **Outside workspace**: show `custom`, `preset`, `cancel`.
+
+Context predicates (`_has_workspace`, `_has_available_infra`,
+`_has_configured_infra`) must be pure filesystem checks — no global state,
+no caching.
+
+Alias uniqueness: each alias must be unique within a menu list. Do not reuse
+a shortcut alias across items in the same list (e.g. `"c"` for both `custom`
+and `cancel`).
+
+### 20. No runtime auto-discovery
+
+Menu items, infra types, and preset definitions are statically registered.
+Do not add plugin loaders, dynamic module scanning, or entry-point discovery.
+This aligns with the top-level `AGENTS.md` cookiecutter guardrail.
+
+## Audit checklist
+
+When asked to "audit the menus or compose system", verify each of the following:
+
+### Menu audit
+1. Every `MenuItem` has a `label`, at least two `aliases` (full name + shortcut), and a handler.
+2. Every menu list ends with a `cancel` item.
+3. `filter_visible()` is called before passing items to `run_menu()`.
+4. All interactive flows have a `*_direct` counterpart wired in `run_generate_menu`.
+5. TTY and non-TTY paths are both exercised (check for `isatty` gates).
+6. `KeyboardInterrupt` and `EOFError` are caught in every prompt/menu call.
+7. Exit codes follow the `0`/`1` contract.
+8. Infra selection uses the category flow, not a flat list.
+9. Names are normalized and the user is informed of changes.
+10. No new prompt primitives exist outside `helpers.py`.
+11. The three-layer separation (helpers → menu → handlers) is preserved.
+12. Tests in `tests/test_cli.py` and `tests/test_v2_generate*.py` cover new/changed items.
+13. All multi-step interactive flows use `run_wizard()` with a list of `WizardStep` callables — no raw `while step <= N` / `if step == 0` dispatch exists in handlers.
+14. No step logic is duplicated across wizard flows — shared steps (`_step_workspace_name`, `_step_git_init`, etc.) are extracted to `_step_*` functions.
+
+### Compose / renderer audit
+15. All render functions are pure `spec → string` transforms with no side effects, no env reads, no filesystem inspection.
+16. `test_render_workspace_is_idempotent` passes — two consecutive renders produce identical output.
+17. Infra wiring uses `INFRA_REGISTRY` descriptors — no hardcoded if/elif branches (except the documented sqlite special case).
+18. `.env` is created-if-missing, all other files are overwritten from spec.
+19. `compose/__init__.py` contains only re-exports — no business logic.
+20. `operations.py` functions load → mutate → save spec — no rendering.
+21. Workspace finalization uses `_finalize_workspace` — no duplicated create/add/render sequences in handlers.
+22. `detect_configured_db` is defined once in `infra.py` — not duplicated.
+23. Test dirs use snake_case, source dirs use kebab-case, Dockerfiles use kebab-case suffix.
+24. No shim modules or alias re-export files exist (pre-1.0 refactor policy).

csrd_utils-0.3.86/src/csrd_utils/v2/__init__.py

@@ -0,0 +1 @@
+"""Namespace package for next-gen csrd compose and generate flows."""