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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-utils
-Version: 0.3.85
+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

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

@@ -1,6 +1,6 @@
 [project]
 name = "csrd-utils"
-version = "0.3.85"
+version = "0.3.86"
 description = "CLI utilities for csrd service generation and feature augmentation"
 license = { text = "MIT" }
 requires-python = ">=3.12"

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/compose/__init__.py

@@ -0,0 +1,93 @@
+"""Compose package namespace — re-exports only, no business logic."""
+
+# Re-export model types for convenience
+from ..models import (
+    INFRA_ALL_TYPES,
+    INFRA_CATEGORIES,
+    INFRA_DATABASES,
+    ComposeSpec,
+    InfraNode,
+    PresetDefinition,
+    ServiceNode,
+)
+from .infra import (
+    INFRA_REGISTRY,
+    INFRA_RENDERERS,
+    InfraDescriptor,
+    descriptor_for,
+    descriptors_for_feature,
+    detect_configured_db,
+    render_infra,
+)
+from .loader import (
+    SPEC_FILENAME,
+    default_spec,
+    load_spec,
+    save_spec,
+    spec_file_path,
+)
+from .operations import (
+    add_infra,
+    add_service,
+    apply,
+    available_infra,
+    configured_infra,
+    remove_infra,
+    validate,
+)
+from .presets import (
+    PRESET_REGISTRY,
+    list_presets,
+    members_for_category,
+)
+from .renderer import render_workspace
+from .scaffolder import scaffold_service, scaffold_services
+from .yaml_editor import (
+    deep_merge,
+    dumps_yaml,
+    ensure_list_item,
+    load_yaml,
+    save_yaml,
+    set_key,
+)
+
+__all__ = [
+    "INFRA_ALL_TYPES",
+    "INFRA_CATEGORIES",
+    "INFRA_DATABASES",
+    "INFRA_REGISTRY",
+    "INFRA_RENDERERS",
+    "PRESET_REGISTRY",
+    "SPEC_FILENAME",
+    "ComposeSpec",
+    "InfraDescriptor",
+    "InfraNode",
+    "PresetDefinition",
+    "ServiceNode",
+    "add_infra",
+    "add_service",
+    "apply",
+    "available_infra",
+    "configured_infra",
+    "deep_merge",
+    "default_spec",
+    "descriptor_for",
+    "descriptors_for_feature",
+    "detect_configured_db",
+    "dumps_yaml",
+    "ensure_list_item",
+    "list_presets",
+    "load_spec",
+    "load_yaml",
+    "members_for_category",
+    "remove_infra",
+    "render_infra",
+    "render_workspace",
+    "save_spec",
+    "save_yaml",
+    "scaffold_service",
+    "scaffold_services",
+    "set_key",
+    "spec_file_path",
+    "validate",
+]