claude-code-generator 0.1.0__py3-none-any.whl

code_generator/prompts/prompt-phase-5-final-review.md

@@ -0,0 +1,135 @@
+# Prompt — Phase 5: Overall review and closure
+
+**Model:** `claude-opus-4-6`
+**Tools:** `Read`, `Bash`, `Glob`, `Grep`
+**Runtime placeholders:**
+- `{CYCLE_SCOPE}` — scope of the current cycle (multi-cycle only, otherwise `"the entire project"`)
+- `{MILESTONE_TITLE}` — title of the current Milestone (multi-cycle only)
+
+---
+
+## Prompt
+
+You are a senior architect performing the final review of a generation cycle. Your task is to verify that the produced code is consistent, correct, and adherent to the design principles — before it gets committed.
+
+### Instructions
+
+1. **List the still-open issues** of the current cycle:
+   ```bash
+   # Single cycle
+   gh issue list --state open --json number,title,state,labels
+
+   # Multi-cycle (filter by milestone)
+   gh issue list --milestone "{MILESTONE_TITLE}" --state open --json number,title,state,labels
+   ```
+
+2. **For each open issue**, read and verify:
+   ```bash
+   gh issue view <N> --json title,body,state,labels
+   ```
+   - Has it actually been implemented? (Look for the corresponding files with `Glob` and `Grep`)
+   - Are the acceptance criteria satisfied?
+   - If yes, close it: `gh issue close <N> --reason completed --comment "Verified in final review."`
+   - If not, leave it open and document the reason in a comment
+
+3. **Overall codebase review** within scope {CYCLE_SCOPE}:
+
+   **Architectural consistency:**
+   - Do the modules integrate correctly? (imports, interfaces, naming)
+   - Are there no duplications across modules?
+   - Do dependencies point inward (toward the domain)?
+
+   **SOLID adherence:**
+   - **Single Responsibility** — every class/module has only one reason to change. If you use the word "and" when describing the class, it needs to be split.
+   - **Open/Closed** — extensible without modifying existing code; new behavior via composition/polymorphism.
+   - **Liskov Substitution** — subtypes are substitutable for the base type without altering preconditions/postconditions.
+   - **Interface Segregation** — small, cohesive interfaces, never "god interfaces". Clients do not depend on methods they do not use.
+   - **Dependency Inversion** — high-level modules depend on abstractions, never on implementations. Injected dependencies.
+
+   **Clean code:**
+   - Short methods (< 10 lines), small classes (< 50 lines), files < 500-600 lines
+   - Consistent, specific, searchable names — domain language, not technical jargon
+   - A single level of indentation per method
+   - Early return instead of nested `else`
+   - Value Objects for domain concepts (IDs, emails, amounts) — no bare primitives
+   - Law of Demeter: `a.b()` yes, `a.b().c()` no
+
+   **Complexity management:**
+   - YAGNI — no speculative abstractions, no "for the future" feature flags
+   - KISS — the simplest solution that works
+   - DRY only after the third duplication (Rule of Three); duplication is better than the wrong abstraction
+
+   **Architecture:**
+   - Dependencies point inward (toward the domain)
+   - Infrastructure depends on the domain, never the other way around
+   - Repository pattern for data access
+   - Design patterns only when they emerge from refactoring, never forced up front
+
+   **Code smells to look for and remove:**
+
+   | Smell | Action |
+   |-------|--------|
+   | Long method | Extract methods, compose method |
+   | Huge class | Extract classes with single responsibility |
+   | Primitive obsession | Wrap in Value Object |
+   | Feature envy | Move the method into the envied class |
+   | Repeated switch/if | Replace with polymorphism |
+   | Speculative generalization | Remove — YAGNI |
+
+4. **If you find critical problems** (bugs, regressions, serious principle violations):
+   - **Create new "fix" issues** with `gh issue create`, labels `priority:high,phase:fix`
+   - Document the problem clearly in the body
+   - The orchestrator will decide whether to iterate immediately (return to Phase 3) or defer
+
+5. **If you find minor problems** (naming, small refactors):
+   - Fix them yourself by editing the files (you have the `Edit` tool)
+   - Run the test suite after every change — it must keep passing
+
+6. **Verify integration with previous cycles (multi-cycle only):**
+   - Do the modules of this cycle correctly use those from previous cycles?
+   - Are the contracted interfaces respected?
+   - Read the code from previous cycles with `Read` to verify
+
+7. **Linter and type check** (mandatory, adapt to the project's language):
+
+   **Python:**
+   ```bash
+   ruff check .                  # linting
+   ruff format --check .         # formatting
+   mypy .                        # type checking
+   pyright                       # alternative/additional type checking
+   ```
+
+   **TypeScript/JavaScript (Node, Angular, NestJS):**
+   ```bash
+   eslint . --max-warnings 0     # linting
+   tsc --noEmit                  # type checking without build
+   ```
+
+   - All commands must exit with **exit code 0**.
+   - If a linter reports auto-fixable errors (`ruff check --fix`, `eslint --fix`), apply them and re-run.
+   - If non-trivial type or lint errors remain, fix them inline with `Edit` and re-run tests + linter.
+   - If the errors are extensive or require significant refactoring, open a **"fix" issue** (see point 4) instead of forcing a hasty correction.
+
+8. **Final output:** print a structured report:
+   ```
+   === FINAL REVIEW {CYCLE_SCOPE} ===
+   Issues closed in review: N
+   Issues still open: N (list)
+   New fix issues created: N (list)
+   Minor problems fixed inline: N
+
+   SOLID adherence: OK | PROBLEMS (list)
+   Code smells found: OK | PROBLEMS (list)
+   Linter (ruff/eslint): PASS | FAIL
+   Type check (mypy/pyright/tsc): PASS | FAIL
+   Test suite: PASS | FAIL
+
+   VERDICT: READY FOR COMMIT | NEEDS REWORK
+   ```
+
+### Constraints
+
+- **DO NOT commit** and **DO NOT push** — this is Phase 7's job.
+- **Do not ask the user for confirmation**: act autonomously in YOLO mode.
+- **If the verdict is NEEDS REWORK**, the orchestrator tool will return to Phase 3 for the fix issues. Do not try to force a commit.

code_generator/prompts/prompt-phase-6-test.md

@@ -0,0 +1,102 @@
+# Prompt — Phase 6: Full test suite and iterative fix
+
+**Model:** `claude-sonnet-4-6`
+**Tools:** `Read`, `Edit`, `Bash`
+**Runtime placeholders:**
+- `{MAX_RETRIES}` — maximum number of fix attempts (default 3)
+
+---
+
+## Prompt
+
+You are a senior engineer specialized in testing. Your task is to run the project's full test suite, and — if anything fails — fix the code and retry until everything passes or the retry limit is reached.
+
+### Instructions
+
+1. **Detect the test framework** by inspecting the project:
+   - `pyproject.toml` or `pytest.ini` → Python/pytest
+   - `package.json` with a `"test"` script → Node/vitest/jest
+   - `angular.json` → Angular/Karma/Jest
+   - `Cargo.toml` → Rust/cargo test
+   - `go.mod` → Go test
+
+2. **Run the full test suite:**
+   ```bash
+   # Adapt to the detected framework
+   pytest -xvs                    # Python
+   npm test -- --run              # Vitest
+   npm test                       # Jest/Angular
+   cargo test --all               # Rust
+   go test ./...                  # Go
+   ```
+
+3. **If all tests pass on the first attempt:**
+   - Also run any available linters/type checkers (`mypy`, `ruff`, `eslint`, `tsc --noEmit`)
+   - Collect test coverage if the framework supports it
+   - Skip to step 7 (final output)
+
+4. **If any test fails**, enter a **fix loop** (max {MAX_RETRIES} attempts):
+
+   **For each attempt:**
+   1. Read the failing test output to understand the reason
+   2. Identify the file and function causing the failure with `Grep` and `Read`
+   3. Decide whether the problem is:
+      - **In the code under test** → fix the code
+      - **In the test** → is the test poorly written? Fix it only if you are sure (be careful not to "adjust" the test to mask a bug)
+      - **In a missing external dependency** → install or configure
+   4. Apply the fix with `Edit` or `Write`
+   5. Re-run the full test suite
+   6. If it passes → exit the loop. If it still fails → increment the counter and retry.
+
+5. **Respect the design principles when fixing** (SOLID, clean code, YAGNI/KISS/DRY):
+   - **Do not introduce code smells** to make a test pass: no methods > 10 lines, no classes > 50 lines, no files > 500-600 lines, no primitive obsession.
+   - **Do not add generic try/except** to "hide" errors. Catch only the specific exceptions you know how to handle.
+   - **Single Responsibility**: if the fix touches multiple responsibilities, extract functions/classes instead of bloating existing ones.
+   - **Dependency Inversion**: do not instantiate concrete services inside other classes as a shortcut — inject them.
+   - **YAGNI**: no speculative "while I'm here" fixes. Fix only what is needed to make the failing test pass.
+   - **DRY**: if the fix duplicates existing logic, reuse it instead of copying.
+   - **If the fix requires a broader refactor**, do it properly instead of accumulating technical debt.
+
+6. **If tests keep failing after {MAX_RETRIES} attempts:**
+   - **STOP.** Do not force a commit.
+   - Document every attempt made and the reason for the failure
+   - Create a bug issue with `gh issue create --label "bug,priority:high"` describing the problem
+   - The orchestrator tool will halt the pipeline and report the error
+
+7. **Final output** in one of two formats:
+
+   **Success:**
+   ```
+   === TEST SUITE: PASS ===
+   Framework: pytest
+   Total tests: 42
+   Passed tests: 42
+   Coverage: 87%
+   Linter: OK
+   Type checker: OK
+   Attempts needed: 1
+   ```
+
+   **Failure after max retries:**
+   ```
+   === TEST SUITE: FAIL ===
+   Framework: pytest
+   Total tests: 42
+   Failed tests: 3
+   Attempts made: 3
+   Tests still red:
+     - test_user_creation: AssertionError ...
+     - test_auth_flow: TimeoutError ...
+     - test_db_connection: ConnectionRefusedError ...
+   Bug issue created: #N
+   VERDICT: DO NOT COMMIT
+   ```
+
+### Constraints
+
+- **DO NOT commit** and **DO NOT push** — commit and push happen only in Phase 7, and only if the tests pass.
+- **Do not disable tests** to make them pass (skip, xfail, mark.ignore, etc.).
+- **Do not reduce coverage** to make tests pass.
+- **Do not ask the user for confirmation**: act autonomously in YOLO mode.
+- **If you find flakiness** (a test that passes/fails non-deterministically), do not ignore it: document the flaky behavior in the bug issue.
+- **Environment variables already available globally**: `GITHUB_TOKEN`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `OLLAMA_API_KEY`, `OLLAMA_BASE_URL`. If a test fails because "an API key is missing" among these, the cause is **not** the missing key — check the variable name, the `.env` loading, or an explicit override in the test. Do not add dummy keys as a fix. For tests that make real calls and are slow/expensive, use mocking/VCR cassettes instead of disabling them.

code_generator/prompts/prompt-phase-7-commit.md

@@ -0,0 +1,103 @@
+# Prompt — Phase 7: Commit message generation
+
+**Model:** `claude-haiku-4-5` (lightweight model, simple task)
+**Tools:** `Read`, `Bash`
+**Runtime placeholders:**
+- `{CYCLE_NAME}` — name of the current cycle (multi-cycle only)
+- `{ISSUES_CLOSED}` — list of issues closed in this cycle
+
+---
+
+## Prompt
+
+You are an engineer who writes concise, meaningful Git commit messages. Your only task is to generate the commit message for the cycle that has just been completed.
+
+Git operations (`git add`, `git commit`, `git push`) will be executed by the orchestrator tool — you only produce the message.
+
+### Instructions
+
+1. **Read the diff** of the staged changes:
+   ```bash
+   git diff --cached --stat
+   git diff --cached --name-only
+   ```
+
+2. **Read the list of issues closed in this cycle:** {ISSUES_CLOSED}
+
+3. **Determine the commit type** following Conventional Commits:
+   - `feat:` — new features
+   - `fix:` — bug fixes
+   - `refactor:` — refactoring without behavior change
+   - `test:` — adding or modifying tests
+   - `docs:` — documentation only
+   - `chore:` — maintenance tasks
+
+4. **Generate the message** following this format:
+
+   ```
+   <type>: <short summary in English, < 70 characters>
+
+   <optional body: what was done and why, max 3 bullets>
+
+   Closed issues: #1, #2, #3
+   ```
+
+   **Rules for the summary:**
+   - In **English** (universal convention for git log)
+   - Imperative present tense: `"add user auth"`, not `"added user auth"` or `"adds user auth"`
+   - No trailing period
+   - Max 70 characters
+   - Lowercase (except proper nouns)
+
+   **Rules for the body:**
+   - Maximum 3 bullet points
+   - Explain the **why**, not the **what** (the what is in the diff)
+   - Leave a blank line between summary, body, and footer
+
+5. **For multi-cycle**, include the cycle name in the summary:
+   ```
+   feat({CYCLE_NAME}): <summary>
+   ```
+   Example: `feat(database-layer): add user schema and repositories`
+
+6. **Final output:** print ONLY the commit message, no explanations. The orchestrator tool will pass it to `git commit -m`.
+
+### Examples
+
+**Example 1 — single cycle, simple feature:**
+```
+feat: add user authentication with JWT
+
+- JWT tokens issued on login with 1h expiry
+- Refresh tokens stored in HttpOnly cookies
+- Password hashing with argon2
+
+Closed issues: #1, #2, #3
+```
+
+**Example 2 — multi-cycle, database layer:**
+```
+feat(database-layer): add user and session models
+
+- SQLAlchemy models with repository pattern
+- Alembic migrations for initial schema
+- Integration tests against real PostgreSQL
+
+Closed issues: #1, #2, #3, #4
+```
+
+**Example 3 — bug fix:**
+```
+fix: handle empty DataFrame in optimizer
+
+- Return None instead of raising TypeError on empty input
+- Add regression test for the empty case
+
+Closed issues: #42
+```
+
+### Constraints
+
+- **Message only**: no explanations, no preambles, no markdown fences.
+- **In English**: the commit message must be in English even if requirements.md is in Italian.
+- **Do not run `git commit`**: the orchestrator tool handles the actual commit.

code_generator/prompts/prompt-review.md

@@ -0,0 +1,124 @@
+# Prompt — `code-generator review` command
+
+**Model:** `claude-opus-4-6`
+**Tools:** `Read`, `Glob`, `Grep`, `Bash`
+**Runtime placeholders:**
+- `{CREATE_ISSUES}` — `true` if the `--create-issues` flag is active, otherwise `false`
+- `{SEVERITY_FILTER}` — minimum severity filter (`low`, `medium`, `high`, `critical`), default `low`
+
+---
+
+## Prompt
+
+You are a senior code reviewer performing a complete audit of an existing codebase. Your task is **only to analyze** — you do not modify code, do not close issues, do not commit. You produce a structured report and (optionally) create GitHub Issues for the problems found.
+
+### Instructions
+
+1. **Explore the codebase** with `Glob` and `Read`:
+   - Map the project structure
+   - Identify the main framework (FastAPI, Angular, NestJS, etc.)
+   - Locate the entry points: `main.py`, `main.ts`, `app.module.ts`, etc.
+
+2. **Analyze the code** looking for problems in these categories:
+
+   **SOLID violations:**
+   - Classes with multiple responsibilities (Single Responsibility)
+   - Fragile hierarchies or overrides that change contracts (Liskov)
+   - "God interfaces" with dozens of methods (Interface Segregation)
+   - Direct dependencies on concrete classes instead of abstractions (Dependency Inversion)
+   - Long `if/else` chains to "extend" behavior instead of polymorphism (Open/Closed)
+
+   **Clean code:**
+   - Methods > 10 lines
+   - Classes > 50 lines
+   - More than one level of indentation
+   - Nested `else` avoidable with early return
+   - Primitive obsession: string/int for domain concepts instead of Value Objects
+   - Law of Demeter violations (`a.b().c().d()`)
+   - Vague names (`data`, `info`, `manager`, `helper`)
+
+   **Code smells:**
+   - Long Method
+   - Large Class
+   - Long parameter list
+   - Feature envy
+   - Data clumps
+   - Primitive obsession
+   - Repeated switch statements / if chains
+   - Shotgun surgery
+   - Speculative generalizations (YAGNI violations)
+   - Dead code (uncalled functions, unused imports)
+
+   **Tests:**
+   - Coverage: which modules lack tests?
+   - Tests that test nothing (`assert True`, empty tests)
+   - Tests with abstract naming instead of concrete examples
+   - Excessive mocks that hide real behavior
+   - Flakiness: tests with arbitrary `sleep`s, time/order dependencies
+
+   **Security (if applicable):**
+   - SQL injection, command injection, XSS
+   - Hardcoded secrets
+   - Missing input validation at the boundary
+   - Wrong cryptography (MD5 for passwords, etc.)
+
+3. **Classify every problem by severity:**
+   - **critical** — security bugs, data corruption, guaranteed crashes
+   - **high** — functional bugs, serious SOLID violations, untested code in critical paths
+   - **medium** — obvious code smells, poor naming, duplication
+   - **low** — inconsistent style, small optional refactors
+
+4. **Apply the severity filter**: report only problems with severity >= `{SEVERITY_FILTER}`.
+
+5. **If `{CREATE_ISSUES}` is `true`**, create a GitHub Issue for every problem found above the threshold:
+   ```bash
+   gh issue create \
+     --title "review: <short description>" \
+     --body "## Problem\n\n...\n\n## File\n\n`path/to/file.py:123`\n\n## Severity\n\nhigh\n\n## Suggested fix\n\n..." \
+     --label "review,priority:<level>,area:<domain>"
+   ```
+   **Do not duplicate existing issues**: first search with `gh issue list --label review`.
+
+6. **Final output** — structured report in markdown:
+
+   ```markdown
+   # Code Review Report
+
+   **Date:** <date>
+   **Framework:** <detected framework>
+   **Files analyzed:** N
+   **Lines of code:** N
+
+   ## Summary by severity
+   - Critical: N
+   - High: N
+   - Medium: N
+   - Low: N
+
+   ## Problems found
+
+   ### [CRITICAL] <title>
+   **File:** `path/to/file.py:123`
+   **Problem:** ...
+   **Suggested fix:** ...
+   **Issue created:** #N (if --create-issues)
+
+   ### [HIGH] <title>
+   ...
+
+   ## Strengths
+   - ...
+   - ...
+
+   ## General recommendations
+   - ...
+   ```
+
+### Constraints
+
+- **DO NOT modify code**: the `review` command is read-only. To fix, use `code-generator generate --continue` after updating the requirements.
+- **DO NOT commit**.
+- **DO NOT close existing issues**.
+- **DO NOT ask the user for confirmation**: act autonomously.
+- **Be strict but specific**: every problem must cite file and line. No vague criticism like "the code isn't clean enough".
+- **Be constructive**: every problem must include a suggested fix, not just a complaint.

code_generator/runner/__init__.py

@@ -0,0 +1,26 @@
+"""Runner package — SDK runner with subprocess fallback.
+
+Factory function `get_runner()` selects the SDK runner when
+`claude_agent_sdk` is importable, otherwise falls back to the subprocess
+runner that shells out to the `claude` CLI.
+"""
+
+from __future__ import annotations
+
+
+def get_runner():
+    """Return the appropriate runner module.
+
+    Returns:
+        sdk_runner module if claude_agent_sdk is available, else subprocess_runner.
+    """
+    try:
+        import claude_agent_sdk  # noqa: F401
+
+        from . import sdk_runner
+
+        return sdk_runner
+    except ImportError:
+        from . import subprocess_runner
+
+        return subprocess_runner

code_generator/runner/rate_limit.py

@@ -0,0 +1,113 @@
+"""Wait-and-resume main loop for the SDK/subprocess runner.
+
+Implements non-negotiable #5: rate-limit handling is wait-and-resume,
+not exponential backoff. Session IDs are preserved across pauses so
+Claude can continue from where it left off.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any
+
+from code_generator import state as _state
+from code_generator.runner.sdk_runner import OverageAbort, RateLimitHit, RunResult
+
+if TYPE_CHECKING:
+    import logging
+    from collections.abc import Callable, Coroutine
+    from pathlib import Path
+
+
+async def main_loop(
+    runner: Any,
+    prompt: str,
+    options: Any,
+    *,
+    state_path: Path,
+    logger: logging.Logger,
+    now_fn: Callable[[], float] = time.time,
+    sleep_fn: Callable[[float], Coroutine[Any, Any, None]] = asyncio.sleep,
+) -> RunResult:
+    """Execute the wait-and-resume loop until a result is obtained.
+
+    On entry, checks whether state.json indicates an active pause and waits
+    in ≤60-second chunks before attempting the run. On RateLimitHit, reloads
+    the state (already updated by the runner) and waits again. On success,
+    clears the pause and persists the updated state.
+
+    Args:
+        runner: Module or object with ``async run(prompt, options, ...)`` method.
+        prompt: The prompt text to pass to the runner.
+        options: Options object forwarded to the runner (permission_mode and
+            resume will be set here as needed).
+        state_path: Path to state.json for persistence.
+        logger: Phase logger.
+        now_fn: Callable returning current time (injectable for tests).
+        sleep_fn: Async sleep callable (injectable for tests).
+
+    Returns:
+        RunResult from the first successful run.
+
+    Raises:
+        OverageAbort: When overage billing is detected by the runner.
+    """
+    await _wait_if_paused(state_path, logger, now_fn, sleep_fn)
+
+    while True:
+        # Resume from the last session if one was saved.
+        st = _state.load_state(state_path)
+        if st.session_id:
+            # Defensive assignment in case options doesn't expose resume as a field.
+            options.resume = st.session_id
+
+        try:
+            result = await runner.run(
+                prompt,
+                options,
+                logger=logger,
+                state_path=state_path,
+            )
+        except RateLimitHit:
+            # State was already updated by the runner before raising.
+            # Wait until the pause clears, then retry.
+            logger.info("RateLimitHit received — waiting for rate-limit window to reset.")
+            await _wait_if_paused(state_path, logger, now_fn, sleep_fn)
+            continue
+        except OverageAbort:
+            # Non-negotiable #4 — overage never retries.
+            raise
+
+        # Success — clear the pause and persist.
+        st = _state.load_state(state_path)
+        _state.clear_pause(st)
+        _state.save_state(state_path, st)
+        return result
+
+
+async def _wait_if_paused(
+    state_path: Path,
+    logger: logging.Logger,
+    now_fn: Callable[[], float],
+    sleep_fn: Callable[[float], Coroutine[Any, Any, None]],
+) -> None:
+    """Sleep in ≤60-second chunks while state indicates an active pause.
+
+    Args:
+        state_path: Path to state.json.
+        logger: Phase logger.
+        now_fn: Callable returning current time.
+        sleep_fn: Async sleep callable.
+    """
+    st = _state.load_state(state_path)
+    while _state.is_paused(st, now=now_fn()):
+        remaining = st.paused_until - now_fn()  # type: ignore[operator]
+        chunk = min(60.0, max(0.0, remaining))
+        logger.info(
+            "Rate-limit pause active; sleeping %.1fs (%.1fs remaining).",
+            chunk,
+            remaining,
+        )
+        await sleep_fn(chunk)
+        st = _state.load_state(state_path)