etch-loop 0.3.1__tar.gz → 0.4.1__tar.gz

{etch_loop-0.3.1 → etch_loop-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etch-loop
-Version: 0.3.1
+Version: 0.4.1
 Summary: Run Claude Code in a fix-break loop until your codebase is clean
 License: MIT
 Requires-Python: >=3.11

{etch_loop-0.3.1 → etch_loop-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "etch-loop"
-version = "0.3.1"
+version = "0.4.1"
 requires-python = ">=3.11"
 description = "Run Claude Code in a fix-break loop until your codebase is clean"
 readme = "README.md"

etch_loop-0.4.1/src/etch/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.1"

{etch_loop-0.3.1 → etch_loop-0.4.1}/src/etch/agent.py

@@ -51,18 +51,34 @@ def run(
     except OSError as exc:
         raise AgentError(f"Failed to launch claude: {exc}") from exc
 
-    # Write prompt to stdin and close it
-    try:
-        process.stdin.write(prompt)
-        process.stdin.close()
-    except BrokenPipeError as exc:
-        raise AgentError(f"Failed to write prompt to claude stdin: {exc}") from exc
+    # Write prompt to stdin and close it — run in thread to avoid blocking on full pipe buffer
+    stdin_exc: list[Exception] = []
+
+    def write_stdin() -> None:
+        try:
+            process.stdin.write(prompt)
+            process.stdin.close()
+        except BrokenPipeError as exc:
+            stdin_exc.append(exc)
+
+    stdin_writer = threading.Thread(target=write_stdin, daemon=True)
+    stdin_writer.start()
+    stdin_writer.join(timeout=30)
+    if stdin_writer.is_alive():
+        process.kill()
+        raise AgentError("Timed out writing prompt to claude stdin")
+    if stdin_exc:
+        process.kill()
+        raise AgentError(f"Failed to write prompt to claude stdin: {stdin_exc[0]}") from stdin_exc[0]
+
+    if process.stdout is None:
+        process.kill()
+        raise AgentError("claude subprocess has no stdout")
 
     output_lines: list[str] = []
     lock = threading.Lock()
 
     def read_stdout() -> None:
-        assert process.stdout is not None
         for line in process.stdout:
             with lock:
                 output_lines.append(line)
@@ -73,9 +89,16 @@ def run(
 
     reader = threading.Thread(target=read_stdout, daemon=True)
     reader.start()
-    reader.join()
+    reader.join(timeout=300)
+    if reader.is_alive():
+        process.kill()
+        raise AgentError("claude subprocess timed out (output reader still running)")
 
-    process.wait()
+    try:
+        process.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        raise AgentError("claude subprocess timed out waiting for exit")
 
     # Capture stderr for error reporting
     stderr_output = ""

{etch_loop-0.3.1 → etch_loop-0.4.1}/src/etch/analyze.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import subprocess
 from collections import Counter
 from pathlib import Path
@@ -107,12 +108,14 @@ def analyze(root: Path | None = None) -> dict:
         "framework": framework,
         "total_files": total,
         "is_git": (root / ".git").exists(),
+        "root": root,
     }
 
 
 def build_init_prompt(info: dict) -> str:
     """Build the Claude prompt used during etch init to analyze the codebase."""
-    file_tree = "\n".join(f"  {f}" for f in _list_files(Path.cwd())[:60])
+    root = info.get("root", Path.cwd())
+    file_tree = "\n".join(f"  {f}" for f in _list_files(root)[:60])
     if not file_tree:
         file_tree = "  (no tracked files)"
 
@@ -257,6 +260,78 @@ Be adversarial — think like someone actively trying to make this code fail.
 """
 
 
+def build_run_md(info: dict) -> str:
+    """Generate a tailored RUN.md based on detected build system."""
+    root = info.get("root", Path.cwd())
+    commands = _detect_run_commands(root)
+
+    if commands:
+        cmd_list = "\n".join(f"- `{cmd}`" for cmd in commands)
+    else:
+        cmd_list = "- (detect and run the appropriate build/test command for this project)"
+
+    return f"""# RUN — build and test validation
+
+You are a build validator. The fixer has made changes. Your job is to run the project's build and test suite to confirm everything still works.
+
+## Commands to run
+
+{cmd_list}
+
+## Rules
+
+1. Run each command and observe the output
+2. If ALL commands pass:
+   - Write `ETCH_SUMMARY: <e.g. "all 47 tests passed">`
+   - Write `ETCH_ALL_CLEAR`
+3. If ANY command fails:
+   - Write `ETCH_SUMMARY: <what failed, e.g. "3 tests failed in test_auth.py — TypeError on line 42">`
+   - Include the relevant error output so the fixer can diagnose it
+   - Write `ETCH_ISSUES_FOUND`
+
+Do not fix anything — only run and report.
+"""
+
+
+def _detect_run_commands(root: Path) -> list[str]:
+    """Detect build/test commands from project files."""
+    commands: list[str] = []
+
+    if (root / "pyproject.toml").exists() or (root / "setup.py").exists():
+        commands.append("python -m pytest")
+
+    if (root / "package.json").exists():
+        try:
+            pkg = json.loads((root / "package.json").read_text(encoding="utf-8"))
+            scripts = pkg.get("scripts", {})
+            if "build" in scripts:
+                commands.append("npm run build")
+            if "test" in scripts:
+                commands.append("npm test")
+        except (OSError, json.JSONDecodeError):
+            commands.append("npm test")
+
+    if (root / "Cargo.toml").exists():
+        commands.append("cargo test")
+
+    if (root / "go.mod").exists():
+        commands.append("go test ./...")
+
+    if (root / "Gemfile").exists():
+        commands.append("bundle exec rspec")
+
+    if (root / "mix.exs").exists():
+        commands.append("mix test")
+
+    if (root / "pom.xml").exists():
+        commands.append("mvn test -q")
+
+    if not commands and (root / "Makefile").exists():
+        commands.append("make test")
+
+    return commands
+
+
 def _format_scope(info: dict) -> str:
     lines = []
     if info["source_dirs"]:
@@ -288,12 +363,15 @@ def _list_files(root: Path) -> list[str]:
 
     # Fallback: walk filesystem
     files = []
-    for p in root.rglob("*"):
-        if p.is_file() and not any(part in _SKIP_DIRS for part in p.parts):
-            try:
-                files.append(str(p.relative_to(root)))
-            except ValueError:
-                pass
+    try:
+        for p in root.rglob("*"):
+            if p.is_file() and not any(part in _SKIP_DIRS for part in p.parts):
+                try:
+                    files.append(str(p.relative_to(root)))
+                except ValueError:
+                    pass
+    except OSError:
+        pass
     return files
 
 

{etch_loop-0.3.1 → etch_loop-0.4.1}/src/etch/cli.py

@@ -21,6 +21,8 @@ app = typer.Typer(
 def init() -> None:
     """Analyze the codebase with Claude and write tailored SCAN.md, ETCH.md, BREAK.md."""
     root = Path.cwd()
+    etch_dir = root / "etch-loop"
+    etch_dir.mkdir(exist_ok=True)
     info = analyze.analyze(root)
     init_prompt = analyze.build_init_prompt(info)
 
@@ -35,9 +37,10 @@ def init() -> None:
             disp.add_line(display.SYM_NEUTRAL, display.DIM, f"falling back to static analysis ({exc})")
 
         for dest, content, label in [
-            (root / "SCAN.md",  analyze.build_scan_md(info, agent_scope),  "SCAN.md"),
-            (root / "ETCH.md",  analyze.build_etch_md(info, agent_scope),  "ETCH.md"),
-            (root / "BREAK.md", analyze.build_break_md(info, agent_scope), "BREAK.md"),
+            (etch_dir / "SCAN.md",  analyze.build_scan_md(info, agent_scope),  "etch-loop/SCAN.md"),
+            (etch_dir / "ETCH.md",  analyze.build_etch_md(info, agent_scope),  "etch-loop/ETCH.md"),
+            (etch_dir / "BREAK.md", analyze.build_break_md(info, agent_scope), "etch-loop/BREAK.md"),
+            (etch_dir / "RUN.md",   analyze.build_run_md(info),                "etch-loop/RUN.md"),
         ]:
             if dest.exists():
                 disp.add_line(display.SYM_NEUTRAL, display.DIM, f"{label} already exists, skipping")
@@ -53,7 +56,7 @@ def run(
         help="Optional focus description, e.g. 'the auth module' or 'error handling in payments'.",
     ),
     prompt: str = typer.Option(
-        "./ETCH.md",
+        "./etch-loop/ETCH.md",
         "--prompt",
         help="Path to the fixer prompt file (ETCH.md).",
         show_default=True,

{etch_loop-0.3.1 → etch_loop-0.4.1}/src/etch/git.py

@@ -48,8 +48,8 @@ def has_changes() -> bool:
         raise GitError(f"Failed to run git status: {exc}") from exc
 
     if status.returncode != 0:
-        stderr = result.stderr.decode(errors="replace").strip()
-        raise GitError(f"git diff failed (exit {result.returncode}): {stderr}")
+        stderr = status.stderr.strip()
+        raise GitError(f"git status failed (exit {status.returncode}): {stderr}")
 
     return bool(status.stdout.strip())
 

{etch_loop-0.3.1 → etch_loop-0.4.1}/src/etch/loop.py

@@ -49,6 +49,9 @@ def run(
         display.print_error(str(exc))
         return
 
+    # Runner is optional — None means the phase is skipped
+    run_text = prompt.load_run(prompt_path)
+
     if focus:
         scan_text += f"\n\n## User focus\n\nConcentrate on: {focus}\n"
         break_text += f"\n\n## User focus\n\nConcentrate your adversarial review on: {focus}\n"
@@ -63,9 +66,59 @@ def run(
     }
     last_breaker_signal: str | None = None
     last_breaker_output: str | None = None
+    last_runner_output: str | None = None
     iteration_log: list[dict] = []
 
     with display.EtchDisplay(target=str(prompt_path.parent)) as disp:
+
+        # ── Runner helper — called at every clean exit point ──────────────────
+        def try_runner(iter_entry: dict) -> str:
+            """Run the runner phase if configured.
+
+            Returns:
+                "skip"   — no RUN.md, proceed with clean exit
+                "clear"  — runner passed, proceed with clean exit
+                "issues" — runner failed, continue the loop
+                "error"  — agent error, break the loop
+            """
+            nonlocal last_runner_output
+            if not run_text:
+                return "skip"
+
+            disp.start_phase("runner")
+            runner_start = time.monotonic()
+            try:
+                runner_output = agent.run(run_text, verbose=verbose)
+            except AgentError as exc:
+                disp.finish_phase("runner", status="error", detail=str(exc),
+                                  duration=time.monotonic() - runner_start, success=False)
+                return "error"
+
+            runner_duration = time.monotonic() - runner_start
+            runner_signal = signals.parse(runner_output)
+            runner_detail = (
+                signals.extract_summary(runner_output)
+                or signals.extract_finding(runner_output)
+            )
+
+            if runner_signal == "clear":
+                disp.finish_phase("runner", status="all clear",
+                                  detail=runner_detail or "build passed",
+                                  duration=runner_duration, success=True)
+                iter_entry["runner"] = {"status": "all clear", "detail": runner_detail}
+                last_runner_output = None
+                return "clear"
+            else:
+                disp.record_issue()
+                stats["issues"] += 1
+                disp.finish_phase("runner", status="build failed",
+                                  detail=runner_detail or "build failed",
+                                  duration=runner_duration, success=False)
+                iter_entry["runner"] = {"status": "build failed", "detail": runner_detail}
+                last_runner_output = runner_output
+                return "issues"
+
+        # ── Main loop ─────────────────────────────────────────────────────────
         for iteration in range(1, max_iterations + 1):
             stats["iterations"] = iteration
             disp.start_iteration(iteration)
@@ -95,9 +148,19 @@ def run(
                                   detail=scanner_detail or "nothing to fix",
                                   duration=scanner_duration, success=True)
                 iter_entry["scanner"] = {"status": "all clear", "detail": scanner_detail}
-                stats["reason"] = "no_changes"
-                iteration_log.append(iter_entry)
-                break
+                runner_result = try_runner(iter_entry)
+                if runner_result == "error":
+                    stats["reason"] = "agent_error"
+                    iteration_log.append(iter_entry)
+                    break
+                elif runner_result == "issues":
+                    stats["reason"] = "issues"
+                    iteration_log.append(iter_entry)
+                    continue
+                else:  # "clear" or "skip"
+                    stats["reason"] = "no_changes"
+                    iteration_log.append(iter_entry)
+                    break
 
             disp.finish_phase("scanner", status="issues found",
                               detail=scanner_detail or "issues found",
@@ -116,6 +179,12 @@ def run(
                     f"{last_breaker_output.strip()}\n\n"
                     f"Also address these if not already covered above.\n"
                 )
+            if last_runner_output:
+                fixer_prompt += (
+                    f"\n\n## Build/test failures from previous iteration\n\n"
+                    f"{last_runner_output.strip()}\n\n"
+                    f"Fix the underlying code issues causing these failures.\n"
+                )
 
             # ── Fixer phase ───────────────────────────────────────────────────
             disp.start_phase("fixer")
@@ -147,9 +216,19 @@ def run(
                                       duration=fixer_duration, success=True)
                     iter_entry["fixer"] = {"status": "no changes", "detail": "nothing to fix"}
                     if last_breaker_signal != "issues":
-                        stats["reason"] = "no_changes"
-                        iteration_log.append(iter_entry)
-                        break
+                        runner_result = try_runner(iter_entry)
+                        if runner_result == "error":
+                            stats["reason"] = "agent_error"
+                            iteration_log.append(iter_entry)
+                            break
+                        elif runner_result == "issues":
+                            stats["reason"] = "issues"
+                            iteration_log.append(iter_entry)
+                            continue
+                        else:  # "clear" or "skip"
+                            stats["reason"] = "no_changes"
+                            iteration_log.append(iter_entry)
+                            break
                     iteration_log.append(iter_entry)
                     # Fall through to breaker
 
@@ -205,9 +284,19 @@ def run(
                                   detail=breaker_detail or "no issues found",
                                   duration=breaker_duration, success=True)
                 iter_entry["breaker"] = {"status": "all clear", "detail": breaker_detail}
-                stats["reason"] = "clear"
-                iteration_log.append(iter_entry)
-                break
+                runner_result = try_runner(iter_entry)
+                if runner_result == "error":
+                    stats["reason"] = "agent_error"
+                    iteration_log.append(iter_entry)
+                    break
+                elif runner_result == "issues":
+                    stats["reason"] = "issues"
+                    iteration_log.append(iter_entry)
+                    continue
+                else:  # "clear" or "skip"
+                    stats["reason"] = "clear"
+                    iteration_log.append(iter_entry)
+                    break
             else:
                 disp.record_issue()
                 stats["issues"] += 1

{etch_loop-0.3.1 → etch_loop-0.4.1}/src/etch/prompt.py

@@ -75,6 +75,35 @@ def load_break(path: str | Path | None = None) -> str:
     raise PromptError(f"BREAK.md not found. Searched: {searched}")
 
 
+def load_run(path: str | Path | None = None) -> str | None:
+    """Load RUN.md if it exists. Returns None if not found — runner phase is optional.
+
+    Args:
+        path: Optional path. If this is ETCH.md, looks for RUN.md alongside it.
+
+    Returns:
+        File contents as a string, or None if RUN.md is not present.
+    """
+    candidates: list[Path] = []
+
+    if path is not None:
+        p = Path(path)
+        if p.name.upper() == "RUN.MD":
+            candidates.append(p)
+        else:
+            candidates.append(p.parent / "RUN.md")
+
+    candidates.append(Path.cwd() / "RUN.md")
+
+    for candidate in candidates:
+        if candidate.exists() and candidate.is_file():
+            content = candidate.read_text(encoding="utf-8")
+            if content.strip():
+                return content
+
+    return None  # Optional phase — no error if absent
+
+
 def load_scan(path: str | Path | None = None) -> str:
     """Load and return the content of SCAN.md.
 

{etch_loop-0.3.1 → etch_loop-0.4.1}/src/etch/report.py

@@ -67,6 +67,14 @@ def write(
             if detail:
                 lines.append(f"\n> {detail}\n")
 
+        runner = entry.get("runner")
+        if runner:
+            status = runner.get("status", "")
+            detail = runner.get("detail", "")
+            lines.append(f"**runner** — {status}")
+            if detail:
+                lines.append(f"\n> {detail}\n")
+
     path.write_text("\n".join(lines), encoding="utf-8")
     return path
 

etch_loop-0.4.1/src/etch/templates/RUN.md

@@ -0,0 +1,20 @@
+# RUN — build and test validation
+
+You are a build validator. The fixer has made changes. Your job is to run the project's build and test suite to confirm everything still works.
+
+## Commands to run
+
+[configured by etch init]
+
+## Rules
+
+1. Run each command and observe the output
+2. If ALL commands pass:
+   - Write `ETCH_SUMMARY: <e.g. "all 47 tests passed">`
+   - Write `ETCH_ALL_CLEAR`
+3. If ANY command fails:
+   - Write `ETCH_SUMMARY: <what failed, e.g. "3 tests failed in test_auth.py — TypeError on line 42">`
+   - Include the relevant error output so the fixer can diagnose it
+   - Write `ETCH_ISSUES_FOUND`
+
+Do not fix anything — only run and report.

etch_loop-0.3.1/src/etch/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.1"