claude-code-generator 0.6.1__tar.gz → 0.6.3__tar.gz

{claude_code_generator-0.6.1/src/claude_code_generator.egg-info → claude_code_generator-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-generator
-Version: 0.6.1
+Version: 0.6.3
 Summary: Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file.
 Author: Silvio Baratto
 License: MIT

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-code-generator"
-version = "0.6.1"
+version = "0.6.3"
 description = "Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file."
 readme = "README.md"
 license = { text = "MIT" }

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3/src/claude_code_generator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-generator
-Version: 0.6.1
+Version: 0.6.3
 Summary: Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file.
 Author: Silvio Baratto
 License: MIT

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/src/claude_code_generator.egg-info/SOURCES.txt

@@ -212,6 +212,7 @@ tests/test_phase6.py
 tests/test_phase65_budget.py
 tests/test_phase6_5_integration.py
 tests/test_phase6_5_integration_cycle2.py
+tests/test_phase6_5_port_isolation.py
 tests/test_phase6_5_prompt.py
 tests/test_phase6_5_prompt_snapshot.py
 tests/test_phase6_5_run.py

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/src/code_generator/__init__.py

@@ -1,3 +1,3 @@
 """code-generator: orchestrator CLI for end-to-end project generation."""
 
-__version__ = "0.6.1"
+__version__ = "0.6.3"

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/src/code_generator/orchestrator/phase6_5_verify.py

@@ -32,7 +32,7 @@ import socket
 import subprocess
 import sys
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -348,6 +348,48 @@ def _spawn_child(entry_cmd: list[str], cwd: Path, env: Mapping[str, str]) -> sub
     )
 
 
+def _alloc_free_port() -> int:
+    """Bind ``127.0.0.1:0`` to obtain an OS-assigned free TCP port, then
+    release it.
+
+    Phase 6.5 must not hardcode ``:8000`` — co-resident tooling (e.g. the
+    claude-mem plugin's ``chroma run``) squats well-known ports and returns
+    404 to every health probe, burning the entire repair-retry budget on a
+    purely environmental collision. An ephemeral port makes that collision
+    structurally impossible.
+
+    There is a benign TOCTOU window between release here and the app binding
+    the port; :func:`_ensure_verify_port` closes it by re-checking (and
+    rerolling) immediately before each attempt.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+def _ensure_verify_port(port: int, *, logger: logging.Logger) -> int:
+    """Pre-flight port guard (#2).
+
+    If *port* was claimed by a foreign listener between attempts (a plugin
+    rebinding, a leaked uvicorn from a prior run), reroll to a fresh free
+    port instead of letting the squatter fail a tier and consume a retry.
+    A genuine app bug still fails the tier on its own port; only
+    environmental collisions are absorbed here.
+    """
+    if not _port_open(port):
+        return port
+    new_port = _alloc_free_port()
+    logger.warning(
+        "Phase 6.5 verify port %d occupied by a foreign listener before the "
+        "attempt began; rerolled to %d so the retry budget is not spent on "
+        "an environmental port collision.",
+        port,
+        new_port,
+    )
+    return new_port
+
+
 def _port_open(port: int, host: str = "127.0.0.1", timeout_s: float = 0.25) -> bool:
     try:
         with socket.create_connection((host, port), timeout=timeout_s):
@@ -654,6 +696,10 @@ async def run(
     budget = Phase65BudgetTracker(wall_budget_s=wall_budget_s, turn_budget=turn_budget)
     budget.start()
 
+    # Ephemeral verification port (#1): allocate once so base_url stays
+    # stable across the retry loop; re-checked per attempt by the guard (#2).
+    verify_port = _alloc_free_port()
+
     for attempt in range(max_retries):
         budget.check(turns_consumed=attempt, logger=logger)
         progress = _begin_attempt(target, progress, attempt)
@@ -661,6 +707,7 @@ async def run(
         if attempt > 0:
             _soft_reset_for_repair(project_dir, attempt + 1)
 
+        verify_port = _ensure_verify_port(verify_port, logger=logger)
         outcome = _run_tiers(
             project_dir,
             state,
@@ -669,6 +716,7 @@ async def run(
             progress,
             attempt,
             target,
+            port=verify_port,
             logger=logger,
             detector=detector,
         )
@@ -691,6 +739,7 @@ async def run(
             max_turns=max_turns,
             attempt=attempt,
             target=target,
+            port=verify_port,
         )
 
     raise VerificationFailed(
@@ -722,6 +771,7 @@ def _run_tiers(
     attempt: int,
     target: Any,
     *,
+    port: int,
     logger: logging.Logger,
     detector: DeviationDetector | None = None,
 ) -> TierResult | None:
@@ -731,13 +781,27 @@ def _run_tiers(
     :func:`tier_selector.select_tiers` then iterates ``spec.tiers``,
     skipping any tier with ``enabled=False`` and recording the
     skip reason on ``Phase65Progress``.
+
+    *port* is the ephemeral free port allocated by :func:`run` (#1). It is
+    woven into ``base_url``, the subprocess env (``PORT`` / ``UVICORN_PORT``
+    / ``APP_PORT``), and the persisted spec so both the programmatic tier
+    runners and the SDK repair agent bind the same collision-free port.
     """
-    env = build_agent_env()
+    base_url = f"http://127.0.0.1:{port}"
+    # The SDK repair agent does not inherit this env (its credentials are
+    # locked at shared-client open time); it learns the port from the
+    # persisted spec's base_url/T1.port instead. These vars steer the
+    # programmatic T0/T2 subprocesses and any app that honours $PORT.
+    env = {
+        **build_agent_env(),
+        "PORT": str(port),
+        "UVICORN_PORT": str(port),
+        "APP_PORT": str(port),
+    }
     requirements_path = project_dir / ".code-generator" / "requirements.md"
     endpoints = _load_endpoints(requirements_path)
-    base_url = "http://127.0.0.1:8000"
 
-    spec = _persist_spec_for_attempt(project_dir, requirements_path)
+    spec = _persist_spec_for_attempt(project_dir, requirements_path, port)
     _record_skips(target, progress, spec, attempt, logger=logger)
     save_state(state_path, state)
 
@@ -759,11 +823,15 @@ def _run_tiers(
     return None
 
 
-def _persist_spec_for_attempt(project_dir: Path, requirements_path: Path) -> AgentSpec:
+def _persist_spec_for_attempt(project_dir: Path, requirements_path: Path, port: int) -> AgentSpec:
     """Build the ``AgentSpec`` for this run and atomically persist it.
 
     The spec is the single source of truth consumed by :func:`_run_tiers`
-    and any later replay tooling.
+    *and* the SDK repair agent (the prompt instructs it to trust the spec's
+    declared ports). ``build_agent_spec`` stays pure and deterministic
+    (default ``:8000``); the ephemeral *port* (#1) is layered on here via
+    :func:`dataclasses.replace` so the agent boots the app on a
+    collision-free port instead of the well-known ``:8000``.
     """
     tiers = select_tiers(project_dir, requirements_path)
     requirements_text = (
@@ -771,6 +839,13 @@ def _persist_spec_for_attempt(project_dir: Path, requirements_path: Path) -> Age
     )
     flags = {tier.tier_id: tier.enabled for tier in tiers if tier.tier_id in {"T3", "T4"}}
     spec = build_agent_spec(project_dir, requirements_text, flags)
+    spec = replace(
+        spec,
+        base_url=f"http://127.0.0.1:{port}",
+        tiers=tuple(
+            replace(tier, port=port) if tier.port is not None else tier for tier in spec.tiers
+        ),
+    )
     persist_agent_spec(spec, project_dir / ".code-generator")
     return spec
 
@@ -949,8 +1024,15 @@ async def _run_repair_pass(
     max_turns: int | None,
     attempt: int,
     target: Any,
+    port: int,
 ) -> None:
-    """Dispatch the Sonnet 4.6 repair pass via the per-cycle shared client (#275)."""
+    """Dispatch the Sonnet 4.6 repair pass via the per-cycle shared client (#275).
+
+    *port* is the ephemeral verify port. It is injected into the prompt as
+    ``VERIFY_BASE_URL`` so the repair agent binds the app to the exact
+    host:port the orchestrator's authoritative T2 probe hits — the agent
+    inventing its own port was the entire failure mode this guards against.
+    """
     del runner_module  # rate_limit signal is replayed via run_with_shared_client
     requirements_path = project_dir / ".code-generator" / "requirements.md"
     spec_path = project_dir / ".code-generator" / "phase6_5_spec.json"
@@ -968,6 +1050,7 @@ async def _run_repair_pass(
         ORACLE_REPORT=_load_oracle_report_text(requirements_path),
         TIERS_ACTIVE=tiers_active,
         TIERS_SKIPPED=tiers_skipped,
+        VERIFY_BASE_URL=f"http://127.0.0.1:{port}",
     )
     effort_level = _effort.resolve_effort(
         phase=66, complexity="", issue_labels=[], retry_count=attempt

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/src/code_generator/prompts/__init__.py

@@ -68,6 +68,9 @@ PLACEHOLDER_SPEC: dict[str, frozenset[str]] = {
             "AGENT_SPEC_PATH",
             "TIERS_ACTIVE",
             "TIERS_SKIPPED",
+            # Ephemeral verify-port isolation: the exact host:port the
+            # orchestrator probes; the repair agent must bind precisely this.
+            "VERIFY_BASE_URL",
         }
     ),
     "prompt-phase-7-commit.md": frozenset(

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/src/code_generator/prompts/prompt-phase-6-5-verify.md

@@ -14,6 +14,8 @@ Verification runs in five tiers, lightest first; each is a hard gate on the next
 - **T0 — Build.** Run the canonical build command for the detected stack. Compile errors here block T1.
 - **T1 — Boot smoke.** Start the application or its main entry point. Watch for crash-on-boot, missing dependencies, unreachable migrations, or import-time errors. Time-bound: a successful boot is detected by either an explicit "ready" log line or the process surviving for `BOOT_SMOKE_WINDOW_SECONDS` (default 8 seconds) without exiting.
 - **T2 — API contract.** When the project exposes HTTP routes, replay the acceptance-criteria endpoint list against the running service from T1. Each route must return its documented status code; response-shape checks are advisory unless the criterion specifies them.
+
+> **Mandatory bind address.** The orchestrator runs its own authoritative T2 probe against **exactly** the URL in `{VERIFY_BASE_URL}` (see `## Volatile Context`) — nothing else. The service you boot in T1 **must listen on that exact host and port**. Do not invent your own port, do not "pick a free one", do not switch the host. A self-reported `=== TIER 2: PASS ===` against any other port is meaningless: the orchestrator only sees `{VERIFY_BASE_URL}`, so a different port is an automatic T2 failure no matter what your local curl shows.
 - **T3 — Browser end-to-end (Playwright MCP).** When the project ships a frontend, drive the running app through the Playwright MCP server. Execute every acceptance flow grouped under the relevant `## Scope` subsection. On any scenario failure, persist a screenshot to `.code-generator/screenshots/<scenario>.png`, drain the browser console messages, and attach both to the failure report. Skip cleanly with a single-line reason when no frontend is in scope.
 - **T4 — Container lifecycle.** When the project ships `docker-compose.yml`, `docker-compose.yaml`, or a bare `Dockerfile`, bring the container(s) up (`docker compose up -d --build` or `docker build && docker run`), wait for the health endpoint, replay the T2 contract suite against the containerized service, then tear down via `try/finally` on every code path. Skip cleanly with a logged reason when no docker manifest exists.
 
@@ -27,7 +29,7 @@ Verification runs in five tiers, lightest first; each is a hard gate on the next
 
 2. **Emit a tier plan.** Before running anything, write a short plan covering:
    - T0 build command (string, no chaining).
-   - T1 entry-point command, expected listening port (if applicable), and the readiness signal (log substring or, by default, the boot-window timer).
+   - T1 entry-point command. It **must bind the exact host and port in `{VERIFY_BASE_URL}`** (e.g. `--host 127.0.0.1 --port <that-port>`), plus the readiness signal (log substring or, by default, the boot-window timer). The port is not yours to choose — it is fixed by `{VERIFY_BASE_URL}` and the persisted `AgentSpec`.
    - T2 endpoint list: one row per `(METHOD, PATH, EXPECTED_STATUS)` extracted from the acceptance criteria. When no HTTP routes are extractable, mark T2 as `SKIP` — this is not a failure.
 
 3. **Run the tiers.** For each tier in order:
@@ -56,6 +58,7 @@ Verification runs in five tiers, lightest first; each is a hard gate on the next
 - **Do not modify or delete tests added by Phase 6.** The unit tests are now part of the contract; if a test fails after a repair edit, the patch is wrong, not the test.
 - **Never touch `state.json`.** It is owned by the orchestrator and made read-only during your run.
 - **Never touch `.code-generator/checklists/`.** Tick decisions are computed in Python from your exit code, not by editing the JSON.
+- **Bind the exact `{VERIFY_BASE_URL}` host:port.** This is non-negotiable and overrides any port in `requirements.md`, a Dockerfile, or your own judgement. The orchestrator's authoritative probe hits only `{VERIFY_BASE_URL}`; a service on any other port fails T2 regardless of local curl output. If the app cannot bind that port, fix the app's port configuration (env var, CLI flag, settings) — never relocate the service to a different port to make a local check pass.
 - **Run long-running daemons in the background** — wrap them with `nohup`, `&`, or an equivalent so the verification harness can reclaim the shell, and tear them down via the PID you captured.
 - Stay inside the tiered loop: do not escalate effort by editing this prompt or invoking other agents.
 - Keep repairs minimal — edit the smallest scope that fixes the failing tier; refactors are out of scope here.
@@ -79,7 +82,7 @@ A first-attempt run on a FastAPI project where T0 passes and T1 fails:
 <example>
 Tier plan:
   T0: pip install -e .
-  T1: uvicorn app.main:app --port 8000  (ready = "Application startup complete" or 8s window)
+  T1: uvicorn app.main:app --host 127.0.0.1 --port <VERIFY_BASE_URL port>  (ready = "Application startup complete" or 8s window)
   T2: GET /health -> 200; POST /items -> 201
   T3: SKIP (no frontend)
   T4: SKIP (no docker manifest)
@@ -101,6 +104,7 @@ Still red: T1 (and dependent T2). Repair this attempt; T3/T4 remain SKIP.
 
 ## Volatile Context
 
+- **Mandatory bind address (orchestrator probes EXACTLY this, nothing else):** {VERIFY_BASE_URL}
 - **Project directory:** {PROJECT_DIR}
 - **Requirements file:** {REQUIREMENTS_MD}
 - **Detected stack:** {DETECTED_STACK}

claude_code_generator-0.6.3/tests/test_phase6_5_port_isolation.py

@@ -0,0 +1,87 @@
+"""Phase 6.5 ephemeral-port isolation (#1) and pre-flight port guard (#2).
+
+Regression cover for the well-known-port collision that exhausted the
+repair-retry budget: a co-resident ``chroma run`` (claude-mem plugin)
+squatting ``:8000`` returned 404 to every health probe, so attempts 1+2
+failed environmentally and attempt 3's real fix landed after the budget
+was already spent. The fix moves verification onto an OS-assigned free
+port and rerolls if that port is squatted before an attempt starts.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+from pathlib import Path
+
+from code_generator.orchestrator.agent_spec import load_agent_spec
+from code_generator.orchestrator.phase6_5_verify import (
+    _alloc_free_port,
+    _ensure_verify_port,
+    _persist_spec_for_attempt,
+)
+
+_LOGGER = logging.getLogger("test.phase6_5.port_isolation")
+
+
+def _make_project(tmp_path: Path) -> Path:
+    project_dir = tmp_path / "project"
+    (project_dir / ".code-generator").mkdir(parents=True)
+    (project_dir / ".code-generator" / "requirements.md").write_text(
+        "# Demo\n\n## Tech Stack\n\nFastAPI\n", encoding="utf-8"
+    )
+    return project_dir
+
+
+def test_alloc_free_port_returns_a_bindable_ephemeral_port() -> None:
+    port = _alloc_free_port()
+    assert 1024 < port < 65536
+    # Released back to the OS — re-bindable, proving it was genuinely free.
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind(("127.0.0.1", port))
+
+
+def test_persisted_spec_carries_ephemeral_port_not_8000(tmp_path: Path) -> None:
+    project_dir = _make_project(tmp_path)
+    port = _alloc_free_port()
+
+    _persist_spec_for_attempt(
+        project_dir, project_dir / ".code-generator" / "requirements.md", port
+    )
+
+    spec = load_agent_spec(project_dir / ".code-generator")
+    assert spec.base_url == f"http://127.0.0.1:{port}"
+    assert spec.base_url != "http://127.0.0.1:8000"
+    # Every tier that declares a port (T1) is rewritten to the free port —
+    # this is the field the SDK repair agent reads to boot the app.
+    ported = [t for t in spec.tiers if t.port is not None]
+    assert ported, "expected at least one tier with an explicit port (T1)"
+    assert all(t.port == port for t in ported)
+
+
+def test_guard_passes_through_a_free_port() -> None:
+    port = _alloc_free_port()
+    assert _ensure_verify_port(port, logger=_LOGGER) == port
+
+
+def test_guard_rerolls_when_port_is_squatted(caplog) -> None:
+    """A foreign listener on the chosen port → reroll, never reuse it.
+
+    This is the chroma-on-:8000 scenario in miniature: the guard must
+    hand back a *different*, free port so the squatter cannot fail a
+    tier and burn a retry.
+    """
+    squatter = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    squatter.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    squatter.bind(("127.0.0.1", 0))
+    squatter.listen(1)
+    squatted_port = squatter.getsockname()[1]
+    try:
+        with caplog.at_level(logging.WARNING):
+            rerolled = _ensure_verify_port(squatted_port, logger=_LOGGER)
+        assert rerolled != squatted_port
+        assert 1024 < rerolled < 65536
+        assert "rerolled" in caplog.text
+    finally:
+        squatter.close()

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/tests/test_phase6_5_prompt.py

@@ -20,6 +20,7 @@ _EXPECTED_PLACEHOLDERS = frozenset(
         "AGENT_SPEC_PATH",
         "TIERS_ACTIVE",
         "TIERS_SKIPPED",
+        "VERIFY_BASE_URL",
     }
 )
 
@@ -37,6 +38,7 @@ def _valid_kwargs() -> dict[str, str]:
         "AGENT_SPEC_PATH": "/tmp/proj/.code-generator/phase6_5_spec.json",
         "TIERS_ACTIVE": "T0,T1,T2",
         "TIERS_SKIPPED": "T3 (no frontend), T4 (no docker)",
+        "VERIFY_BASE_URL": "http://127.0.0.1:59568",
     }
 
 

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/tests/test_prompt_prefix_snapshots.py

@@ -82,6 +82,7 @@ PLACEHOLDER_SNAPSHOT_FIXTURES: dict[str, str] = {
     "AGENT_SPEC_PATH": ".code-generator/phase6_5_spec.json",
     "TIERS_ACTIVE": "T0,T1,T2",
     "TIERS_SKIPPED": "",
+    "VERIFY_BASE_URL": "http://127.0.0.1:PORT",
     "CI_LOGS": "",
     "FAILING_JOBS": "",
     "MAX_ATTEMPTS": "5",

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/tests/test_prompt_prefix_stability.py

@@ -175,6 +175,10 @@ _FIXTURES: dict[str, list[dict[str, str]]] = {
             "AGENT_SPEC_PATH": "/tmp/proj-a/.code-generator/phase6_5_spec.json",
             "TIERS_ACTIVE": "T0,T1,T2",
             "TIERS_SKIPPED": "T3 (no frontend), T4 (no docker)",
+            # Identical across all three fixtures: VERIFY_BASE_URL appears in
+            # the cached prefix (T2 section), so the 2048-byte stability
+            # contract requires the same value in every variant.
+            "VERIFY_BASE_URL": "http://127.0.0.1:PORT",
         },
         {
             "PROJECT_DIR": "/srv/proj-b",
@@ -188,6 +192,7 @@ _FIXTURES: dict[str, list[dict[str, str]]] = {
             "AGENT_SPEC_PATH": "/srv/proj-b/.code-generator/phase6_5_spec.json",
             "TIERS_ACTIVE": "T0,T1,T2,T4",
             "TIERS_SKIPPED": "T3 (no frontend)",
+            "VERIFY_BASE_URL": "http://127.0.0.1:PORT",
         },
         {
             "PROJECT_DIR": "/work/proj-c",
@@ -201,6 +206,7 @@ _FIXTURES: dict[str, list[dict[str, str]]] = {
             "AGENT_SPEC_PATH": "/work/proj-c/.code-generator/phase6_5_spec.json",
             "TIERS_ACTIVE": "T0,T3",
             "TIERS_SKIPPED": "T4 (no docker)",
+            "VERIFY_BASE_URL": "http://127.0.0.1:PORT",
         },
     ],
     "prompt-phase-7-commit.md": [

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/tests/test_prompts.py

@@ -52,6 +52,7 @@ _EXPECTED_FILES = {
             "AGENT_SPEC_PATH",
             "TIERS_ACTIVE",
             "TIERS_SKIPPED",
+            "VERIFY_BASE_URL",
         }
     ),
     "prompt-phase-7-commit.md": frozenset(

{claude_code_generator-0.6.1 → claude_code_generator-0.6.3}/tests/test_sica.py

@@ -255,6 +255,7 @@ async def test_when_phase6_5_repair_runs_then_routes_through_sica(
         max_turns=None,
         attempt=0,
         target=target,
+        port=59568,
     )
 
     assert captured_calls