etch-loop 0.1.0__tar.gz

etch_loop-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

etch_loop-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: etch-loop
+Version: 0.1.0
+Summary: Run Claude Code in a fix-break loop until your codebase is clean
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: rich
+Requires-Dist: typer
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# etch-loop

etch_loop-0.1.0/README.md

@@ -0,0 +1 @@
+# etch-loop

etch_loop-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "etch-loop"
+version = "0.1.0"
+requires-python = ">=3.11"
+description = "Run Claude Code in a fix-break loop until your codebase is clean"
+readme = "README.md"
+license = { text = "MIT" }
+dependencies = ["typer", "rich"]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+etch = "etch.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/etch"]

etch_loop-0.1.0/src/etch/__init__.py

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

etch_loop-0.1.0/src/etch/agent.py

@@ -0,0 +1,91 @@
+"""Claude agent subprocess runner."""
+
+import subprocess
+import threading
+from collections.abc import Callable
+
+
+class AgentError(Exception):
+    """Raised when the agent subprocess fails or is unavailable."""
+
+
+def run(
+    prompt: str,
+    verbose: bool = False,
+    tick_callback: Callable[[str], None] | None = None,
+) -> str:
+    """Run the Claude agent with the given prompt piped to stdin.
+
+    Launches `claude -p --dangerously-skip-permissions` as a subprocess,
+    pipes `prompt` to its stdin, and returns the full stdout.
+
+    Args:
+        prompt: The prompt text to send to Claude.
+        verbose: If True, streams output to terminal in addition to capturing it.
+        tick_callback: Optional callable called with each line of output as it
+                       arrives. Used by display layer for streaming updates.
+
+    Returns:
+        The full stdout output from the agent as a string.
+
+    Raises:
+        AgentError: If `claude` is not found, or exits with a non-zero code.
+    """
+    cmd = ["claude", "-p", "--dangerously-skip-permissions"]
+
+    try:
+        process = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError:
+        raise AgentError(
+            "claude executable not found. "
+            "Is Claude Code installed? Run: npm install -g @anthropic-ai/claude-code"
+        )
+    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
+
+    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)
+            if verbose:
+                print(line, end="", flush=True)
+            if tick_callback is not None:
+                tick_callback(line)
+
+    reader = threading.Thread(target=read_stdout, daemon=True)
+    reader.start()
+    reader.join()
+
+    process.wait()
+
+    # Capture stderr for error reporting
+    stderr_output = ""
+    if process.stderr:
+        stderr_output = process.stderr.read().strip()
+
+    if process.returncode != 0:
+        detail = stderr_output or "(no stderr)"
+        raise AgentError(
+            f"claude exited with code {process.returncode}: {detail}"
+        )
+
+    return "".join(output_lines)

etch_loop-0.1.0/src/etch/cli.py

@@ -0,0 +1,90 @@
+"""CLI entry points for etch-loop."""
+
+from __future__ import annotations
+
+import importlib.resources
+import shutil
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from etch import display, loop
+
+app = typer.Typer(
+    name="etch",
+    help="Run Claude Code in a fix-break loop, hunting for edge cases.",
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+)
+
+_TEMPLATES = ["ETCH.md", "BREAK.md"]
+
+
+@app.command()
+def init() -> None:
+    """Copy ETCH.md and BREAK.md templates into the current directory."""
+    for filename in _TEMPLATES:
+        dest = Path.cwd() / filename
+
+        if dest.exists():
+            display.print_init_skip(filename)
+            continue
+
+        try:
+            # Python 3.9+ traversable API
+            pkg_templates = importlib.resources.files("etch") / "templates" / filename
+            content = pkg_templates.read_text(encoding="utf-8")
+            dest.write_text(content, encoding="utf-8")
+            display.print_init_ok(filename)
+        except (FileNotFoundError, ModuleNotFoundError, TypeError) as exc:
+            display.print_error(f"Could not copy {filename}: {exc}")
+
+
+@app.command()
+def run(
+    prompt: str = typer.Option(
+        "./ETCH.md",
+        "--prompt",
+        help="Path to the fixer prompt file (ETCH.md).",
+        show_default=True,
+    ),
+    max_iterations: int = typer.Option(
+        20,
+        "--max-iterations",
+        "-n",
+        help="Maximum number of fix-break cycles.",
+        show_default=True,
+        min=1,
+    ),
+    no_commit: bool = typer.Option(
+        False,
+        "--no-commit",
+        help="Skip git commits after fixer runs.",
+        is_flag=True,
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the fixer prompt and exit without running.",
+        is_flag=True,
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Stream agent output to the terminal.",
+        is_flag=True,
+    ),
+) -> None:
+    """Run the fix-break loop against the current repository."""
+    try:
+        loop.run(
+            prompt_path=prompt,
+            max_iterations=max_iterations,
+            no_commit=no_commit,
+            dry_run=dry_run,
+            verbose=verbose,
+        )
+    except KeyboardInterrupt:
+        display.print_interrupted()
+        raise typer.Exit(code=130)

etch_loop-0.1.0/src/etch/display.py

@@ -0,0 +1,389 @@
+"""Rich-based terminal UI for etch-loop."""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from rich.columns import Columns
+from rich.console import Console, ConsoleOptions, RenderableType, RenderResult
+from rich.live import Live
+from rich.panel import Panel
+from rich.segment import Segment
+from rich.style import Style
+from rich.table import Table
+from rich.text import Text
+
+from etch import __version__
+
+# ── Palette ──────────────────────────────────────────────────────────────────
+BG = "#0a0a0a"
+FG = "#e8e8e8"
+DIM = "#555555"
+AMBER = "#d4a547"
+GREEN = "#7aba78"
+RED = "#c96a6a"
+BORDER = "#1e1e1e"
+
+# ── Symbols (ASCII only) ──────────────────────────────────────────────────────
+SYM_RUN = ">"
+SYM_OK = "+"
+SYM_FAIL = "x"
+SYM_NEUTRAL = "-"
+
+SCAN_WIDTH = 40
+SCAN_BLOCK = "▓▒ "  # 3-char block
+SCAN_FILL = "░"
+TICK_MS = 80
+
+
+# ── ScanBar renderable ────────────────────────────────────────────────────────
+
+
+class ScanBar:
+    """A Rich renderable that renders one frame of the scan animation.
+
+    The bar is SCAN_WIDTH chars wide, filled with SCAN_FILL (░).
+    A 3-char SCAN_BLOCK (▓▒ ) slides left-to-right, wrapping at the end.
+    Rendered in amber.
+    """
+
+    def __init__(self, tick: int) -> None:
+        self.tick = tick
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        width = SCAN_WIDTH
+        block = SCAN_BLOCK
+        block_len = len(block)
+        pos = self.tick % width
+
+        bar = list(SCAN_FILL * width)
+        for i, ch in enumerate(block):
+            idx = (pos + i) % width
+            bar[idx] = ch
+
+        yield Segment("".join(bar), Style(color=AMBER))
+
+
+# ── Log entry dataclass ───────────────────────────────────────────────────────
+
+
+@dataclass
+class _LogEntry:
+    """One line in the scrolling log."""
+
+    symbol: str
+    phase: str
+    status: str
+    detail: str | RenderableType
+    color: str
+    running: bool = False
+    tick: int = 0
+
+
+# ── EtchDisplay ──────────────────────────────────────────────────────────────
+
+
+class EtchDisplay:
+    """Manages the Rich Live layout for the etch-loop run."""
+
+    def __init__(self, target: str = "") -> None:
+        self._console = Console(style=f"on {BG}")
+        self._target = target
+        self._entries: list[_LogEntry] = []
+        self._stats: dict[str, Any] = {
+            "iterations": 0,
+            "fixes": 0,
+            "issues": 0,
+            "start": time.monotonic(),
+        }
+        self._live: Live | None = None
+        self._tick = 0
+        self._ticker_stop = threading.Event()
+        self._ticker_thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    # ── Public lifecycle ──────────────────────────────────────────────────────
+
+    def __enter__(self) -> "EtchDisplay":
+        self._live = Live(
+            self._render(),
+            console=self._console,
+            refresh_per_second=15,
+            transient=False,
+        )
+        self._live.__enter__()
+        self._start_ticker()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self._stop_ticker()
+        if self._live is not None:
+            self._live.__exit__(*args)
+
+    # ── Iteration / phase API ─────────────────────────────────────────────────
+
+    def start_iteration(self, n: int) -> None:
+        """Add an iteration header line to the log."""
+        with self._lock:
+            self._stats["iterations"] = n
+            self._entries.append(
+                _LogEntry(
+                    symbol=SYM_NEUTRAL,
+                    phase=f"iteration {n}",
+                    status="",
+                    detail="",
+                    color=DIM,
+                )
+            )
+        self._refresh()
+
+    def start_phase(self, phase: str) -> None:
+        """Add a 'running' line with scan animation for the given phase."""
+        with self._lock:
+            self._entries.append(
+                _LogEntry(
+                    symbol=SYM_RUN,
+                    phase=phase,
+                    status="running",
+                    detail=ScanBar(self._tick),
+                    color=AMBER,
+                    running=True,
+                    tick=self._tick,
+                )
+            )
+        self._refresh()
+
+    def finish_phase(
+        self,
+        phase: str,
+        status: str,
+        detail: str,
+        duration: float,
+        success: bool = True,
+    ) -> None:
+        """Replace the last running line for `phase` with a finished result."""
+        color = GREEN if success else RED
+        symbol = SYM_OK if success else SYM_FAIL
+        dur_str = f"{duration:.1f}s"
+
+        with self._lock:
+            # Find the last running entry for this phase and replace it
+            for i in range(len(self._entries) - 1, -1, -1):
+                entry = self._entries[i]
+                if entry.phase == phase and entry.running:
+                    self._entries[i] = _LogEntry(
+                        symbol=symbol,
+                        phase=phase,
+                        status=status,
+                        detail=detail,
+                        color=color,
+                        running=False,
+                    )
+                    break
+        self._refresh()
+
+    def record_fix(self) -> None:
+        """Increment the fix counter."""
+        with self._lock:
+            self._stats["fixes"] += 1
+
+    def record_issue(self) -> None:
+        """Increment the breaker-issues counter."""
+        with self._lock:
+            self._stats["issues"] += 1
+
+    def print_summary(self, stats: dict[str, Any]) -> None:
+        """Print the final done/stopped/interrupted panel."""
+        self._stop_ticker()
+        if self._live is not None:
+            self._live.stop()
+
+        reason = stats.get("reason", "done")
+        elapsed = stats.get("elapsed", 0.0)
+        iterations = stats.get("iterations", 0)
+        fixes = stats.get("fixes", 0)
+        issues = stats.get("issues", 0)
+
+        elapsed_str = _format_elapsed(elapsed)
+
+        if reason == "clear":
+            title_color = GREEN
+            title = f"[{GREEN}]+ all clear[/{GREEN}]"
+        elif reason == "interrupted":
+            title_color = AMBER
+            title = f"[{AMBER}]- interrupted[/{AMBER}]"
+        elif reason == "max_iterations":
+            title_color = AMBER
+            title = f"[{AMBER}]- stopped (max iterations)[/{AMBER}]"
+        elif reason == "no_changes":
+            title_color = GREEN
+            title = f"[{GREEN}]+ clean — fixer found nothing[/{GREEN}]"
+        else:
+            title_color = FG
+            title = f"[{FG}]done[/{FG}]"
+
+        body = (
+            f"[{DIM}]iterations[/{DIM}] [{FG}]{iterations}[/{FG}]   "
+            f"[{DIM}]fixes[/{DIM}] [{FG}]{fixes}[/{FG}]   "
+            f"[{DIM}]breaker issues[/{DIM}] [{FG}]{issues}[/{FG}]   "
+            f"[{DIM}]{elapsed_str} elapsed[/{DIM}]"
+        )
+
+        panel = Panel(
+            body,
+            title=title,
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+        self._console.print(panel)
+
+    # ── Rendering ─────────────────────────────────────────────────────────────
+
+    def _render(self) -> RenderableType:
+        """Build the full Live renderable."""
+        with self._lock:
+            entries = list(self._entries)
+            tick = self._tick
+            stats = dict(self._stats)
+
+        elapsed = time.monotonic() - stats["start"]
+
+        # Build log table
+        log_table = Table.grid(padding=(0, 1))
+        log_table.add_column(width=2)  # symbol
+        log_table.add_column(width=10)  # phase
+        log_table.add_column(width=12)  # status
+        log_table.add_column()  # detail
+
+        for entry in entries:
+            if entry.running:
+                detail_render: RenderableType = ScanBar(tick)
+            else:
+                detail_render = Text(str(entry.detail), style=Style(color=DIM))
+
+            sym_text = Text(entry.symbol, style=Style(color=entry.color))
+            phase_text = Text(entry.phase, style=Style(color=entry.color))
+            status_text = Text(entry.status, style=Style(color=DIM))
+
+            log_table.add_row(sym_text, phase_text, status_text, detail_render)
+
+        # Header
+        title_str = f"etch loop v{__version__}"
+        if self._target:
+            title_str += f"  {self._target}"
+
+        # Stats footer
+        elapsed_str = _format_elapsed(elapsed)
+        footer = (
+            f"[{DIM}]iterations[/{DIM}] [{FG}]{stats['iterations']}[/{FG}]   "
+            f"[{DIM}]fixes[/{DIM}] [{FG}]{stats['fixes']}[/{FG}]   "
+            f"[{DIM}]breaker issues[/{DIM}] [{FG}]{stats['issues']}[/{FG}]   "
+            f"[{DIM}]{elapsed_str} elapsed[/{DIM}]"
+        )
+
+        panel = Panel(
+            log_table,
+            title=f"[{AMBER}]{title_str}[/{AMBER}]",
+            subtitle=footer,
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+        return panel
+
+    def _refresh(self) -> None:
+        if self._live is not None:
+            self._live.update(self._render())
+
+    # ── Ticker thread ─────────────────────────────────────────────────────────
+
+    def _start_ticker(self) -> None:
+        self._ticker_stop.clear()
+        self._ticker_thread = threading.Thread(
+            target=self._ticker_loop, daemon=True
+        )
+        self._ticker_thread.start()
+
+    def _stop_ticker(self) -> None:
+        self._ticker_stop.set()
+        if self._ticker_thread is not None:
+            self._ticker_thread.join(timeout=1.0)
+            self._ticker_thread = None
+
+    def _ticker_loop(self) -> None:
+        while not self._ticker_stop.is_set():
+            with self._lock:
+                self._tick += 1
+            self._refresh()
+            time.sleep(TICK_MS / 1000.0)
+
+
+# ── Standalone print helpers (used outside Live context) ──────────────────────
+
+_console = Console(style=f"on {BG}")
+
+
+def print_dry_run(prompt_text: str) -> None:
+    """Print the prompt in a panel for --dry-run mode."""
+    _console.print(
+        Panel(
+            Text(prompt_text, style=Style(color=FG)),
+            title=f"[{AMBER}]dry run — prompt preview[/{AMBER}]",
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+    )
+
+
+def print_interrupted() -> None:
+    """Print interrupted notice."""
+    _console.print(
+        Panel(
+            Text("Run interrupted by user.", style=Style(color=AMBER)),
+            title=f"[{AMBER}]- interrupted[/{AMBER}]",
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+    )
+
+
+def print_error(message: str) -> None:
+    """Print an error panel."""
+    _console.print(
+        Panel(
+            Text(message, style=Style(color=RED)),
+            title=f"[{RED}]x error[/{RED}]",
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+    )
+
+
+def print_init_ok(filename: str) -> None:
+    """Print a success line for etch init."""
+    _console.print(f"[{GREEN}]{SYM_OK}[/{GREEN}]  [{FG}]{filename}[/{FG}]")
+
+
+def print_init_skip(filename: str) -> None:
+    """Print a skip line for etch init (file already exists)."""
+    _console.print(
+        f"[{AMBER}]{SYM_NEUTRAL}[/{AMBER}]  [{DIM}]{filename} already exists, skipping[/{DIM}]"
+    )
+
+
+# ── Utilities ─────────────────────────────────────────────────────────────────
+
+
+def _format_elapsed(seconds: float) -> str:
+    """Format elapsed seconds as '2m 14s' or '45s'."""
+    seconds = max(0.0, seconds)
+    mins = int(seconds // 60)
+    secs = int(seconds % 60)
+    if mins > 0:
+        return f"{mins}m {secs}s"
+    return f"{secs}s"