lemming-cli 0.1.0__py3-none-any.whl

lemming/main_test.py

@@ -0,0 +1,44 @@
+import pathlib
+import shutil
+import tempfile
+import unittest
+
+import click.testing
+
+from lemming import main, tasks
+
+
+class TestMain(unittest.TestCase):
+    def setUp(self):
+        self.cli_runner = click.testing.CliRunner()
+        self.test_dir = tempfile.mkdtemp()
+        self.test_tasks_file = pathlib.Path(self.test_dir) / "tasks_test.yml"
+        self.base_args = ["--tasks-file", str(self.test_tasks_file)]
+
+        # Scaffold a valid file
+        data = tasks.Roadmap(
+            context="Initial context",
+            tasks=[
+                tasks.Task(
+                    id="12345678",
+                    description="Initial Task",
+                    status=tasks.TaskStatus.PENDING,
+                    attempts=0,
+                    progress=[],
+                )
+            ],
+        )
+        tasks.save_tasks(self.test_tasks_file, data)
+
+    def tearDown(self):
+        shutil.rmtree(self.test_dir)
+
+    def test_main_cli_entry_point(self):
+        # Verify that main.cli is accessible and works (it's imported from .cli)
+        result = self.cli_runner.invoke(main.cli, self.base_args + ["status"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Initial Task", result.output)
+
+
+if __name__ == "__main__":
+    unittest.main()

lemming/models.py

@@ -0,0 +1,88 @@
+"""Pydantic models for tasks, roadmap state, and runner configuration."""
+
+import enum
+import functools
+import shutil
+import time
+
+import pydantic
+
+# Runner CLIs the orchestrator knows how to drive, in default-preference order.
+KNOWN_RUNNERS = ("agy", "aider", "claude", "codex")
+
+
+@functools.cache
+def detect_default_runner() -> str:
+    """Returns the first known runner CLI found on PATH, falling back to "agy".
+
+    Only used when no runner is persisted in the tasks file; an explicit
+    (user-set) runner always takes precedence and remains sticky.
+    """
+    for name in KNOWN_RUNNERS:
+        if shutil.which(name):
+            return name
+    return KNOWN_RUNNERS[0]
+
+
+class TaskNotFoundError(ValueError):
+    """Raised when a task ID cannot be found in the roadmap."""
+
+
+class TaskStatus(enum.StrEnum):
+    """Enumeration of possible task statuses."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class Task(pydantic.BaseModel):
+    """Represents a single task in the roadmap."""
+
+    id: str
+    description: str
+    status: TaskStatus = TaskStatus.PENDING
+    attempts: int = 0
+    progress: list[str] = pydantic.Field(default_factory=list)
+    runner: str | None = None
+    completed_at: float | None = None
+    started_at: float | None = None
+    last_started_at: float | None = None
+    created_at: float = pydantic.Field(default_factory=time.time)
+    run_time: float = 0.0
+    pid: int | None = None
+    last_heartbeat: float | None = None
+    has_runner_log: bool = False
+    parent: str | None = None
+    parent_tasks_file: str | None = None
+    index: int | None = pydantic.Field(default=None)
+    requested_status: TaskStatus | None = None
+
+
+class RoadmapConfig(pydantic.BaseModel):
+    """Configuration for the roadmap execution loop."""
+
+    retries: int = 3
+    runner: str = pydantic.Field(default_factory=detect_default_runner)
+    hooks: list[str] | None = None
+    time_limit: int = 60
+
+
+class Roadmap(pydantic.BaseModel):
+    """Represents the entire roadmap state."""
+
+    context: str = ""
+    tasks: list[Task] = pydantic.Field(default_factory=list)
+    config: RoadmapConfig = pydantic.Field(default_factory=RoadmapConfig)
+
+
+class ProjectData(pydantic.BaseModel):
+    """Represents the project data returned by the API."""
+
+    context: str
+    tasks: list[Task]
+    config: RoadmapConfig
+    cwd: str
+    loop_running: bool

lemming/models_test.py

@@ -0,0 +1,91 @@
+import pydantic
+import pytest
+
+from lemming import models
+
+
+def test_task_status_values():
+    assert models.TaskStatus.PENDING == "pending"
+    assert models.TaskStatus.IN_PROGRESS == "in_progress"
+    assert models.TaskStatus.COMPLETED == "completed"
+    assert models.TaskStatus.FAILED == "failed"
+
+
+def test_task_model_defaults():
+    task = models.Task(id="123", description="Test")
+    assert task.status == models.TaskStatus.PENDING
+    assert task.attempts == 0
+    assert task.progress == []
+    assert task.run_time == 0.0
+    assert task.created_at > 0
+
+
+def test_task_model_validation():
+    # description is required
+    with pytest.raises(pydantic.ValidationError):
+        models.Task(id="123")
+
+    # id is required
+    with pytest.raises(pydantic.ValidationError):
+        models.Task(description="Test")
+
+
+def test_roadmap_defaults():
+    roadmap = models.Roadmap()
+    assert roadmap.context == ""
+    assert roadmap.tasks == []
+    assert isinstance(roadmap.config, models.RoadmapConfig)
+
+
+def test_roadmap_config_defaults():
+    config = models.RoadmapConfig()
+    assert config.retries == 3
+    assert config.runner in models.KNOWN_RUNNERS
+    assert config.hooks is None
+    assert config.time_limit == 60
+
+
+def test_detect_default_runner_picks_first_installed(monkeypatch):
+    models.detect_default_runner.cache_clear()
+    monkeypatch.setattr(
+        models.shutil,
+        "which",
+        lambda name: "/bin/x" if name == "claude" else None,
+    )
+    assert models.detect_default_runner() == "claude"
+    models.detect_default_runner.cache_clear()
+
+
+def test_detect_default_runner_falls_back_to_agy(monkeypatch):
+    models.detect_default_runner.cache_clear()
+    monkeypatch.setattr(models.shutil, "which", lambda name: None)
+    assert models.detect_default_runner() == "agy"
+    models.detect_default_runner.cache_clear()
+
+
+def test_detect_default_runner_prefers_agy(monkeypatch):
+    models.detect_default_runner.cache_clear()
+    monkeypatch.setattr(models.shutil, "which", lambda name: f"/bin/{name}")
+    assert models.detect_default_runner() == "agy"
+    models.detect_default_runner.cache_clear()
+
+
+def test_roadmap_config_uses_detected_runner(monkeypatch):
+    models.detect_default_runner.cache_clear()
+    monkeypatch.setattr(
+        models.shutil,
+        "which",
+        lambda name: "/bin/x" if name == "codex" else None,
+    )
+    assert models.RoadmapConfig().runner == "codex"
+    # An explicit value always wins over detection.
+    assert models.RoadmapConfig(runner="aider").runner == "aider"
+    models.detect_default_runner.cache_clear()
+
+
+def test_roadmap_config_custom_time_limit():
+    config = models.RoadmapConfig(time_limit=30)
+    assert config.time_limit == 30
+
+    config_disabled = models.RoadmapConfig(time_limit=0)
+    assert config_disabled.time_limit == 0

lemming/orchestrator.py

@@ -0,0 +1,407 @@
+"""Orchestrator loop that executes pending tasks via runners and hooks."""
+
+import os
+import pathlib
+import random
+import time
+
+import click
+
+from . import prompts, runner, tasks
+from .hooks import run_hooks
+
+
+def _process_exhausted_retries(
+    tasks_file: pathlib.Path,
+    task_id: str,
+    retries: int,
+    runner_name: str,
+    yolo: bool,
+    runner_args: tuple,
+    no_defaults: bool,
+    verbose: bool,
+    active_hooks: list[str],
+    working_dir: pathlib.Path | None,
+    time_limit: int,
+) -> bool:
+    """Handles tasks that have exhausted retries.
+
+    Returns True to abort the run loop, False to continue.
+    """
+    # Run hooks (like roadmap revision) even on final failure to give
+    # them a chance to heal the task before we abort.
+    # Mark as in_progress so hooks can run and heartbeats work.
+    # We use update_task to set requested_status=FAILED so it shows
+    # as "Finalizing" in the UI.
+    tasks.mark_task_in_progress(tasks_file, task_id)
+    tasks.update_task(tasks_file, task_id, status=tasks.TaskStatus.FAILED)
+
+    run_hooks(
+        tasks_file,
+        task_id,
+        runner_name,
+        yolo,
+        runner_args,
+        no_defaults,
+        verbose,
+        hooks=active_hooks,
+        working_dir=working_dir,
+        final_status=tasks.TaskStatus.FAILED,
+        time_limit=time_limit,
+    )
+
+    # Re-check: if a hook reset/edited/replaced the task, continue the loop
+    data = tasks.load_tasks(tasks_file)
+    healed_task = next((t for t in data.tasks if t.id == task_id), None)
+    if healed_task and healed_task.attempts >= retries:
+        click.echo(
+            f"\nTask {task_id} failed after {retries} attempts. Aborting run."
+        )
+        return True
+
+    # Orchestrator healed it (reset attempts, deleted it, etc.) — continue
+    # the loop
+    click.echo(f"Orchestrator intervened on task {task_id}. Continuing...")
+    return False
+
+
+def _process_finalizing_task(
+    tasks_file: pathlib.Path,
+    task_id: str,
+    requested_status: tasks.TaskStatus,
+    runner_name: str,
+    yolo: bool,
+    runner_args: tuple,
+    no_defaults: bool,
+    verbose: bool,
+    active_hooks: list[str],
+    working_dir: pathlib.Path | None,
+    time_limit: int,
+) -> None:
+    """Runs hooks for a task that is in a finalizing state."""
+    if verbose:
+        click.echo(
+            f"Task {task_id} resumed in finalizing state "
+            f"({requested_status}). Skipping runner."
+        )
+
+    run_hooks(
+        tasks_file,
+        task_id,
+        runner_name,
+        yolo,
+        runner_args,
+        no_defaults,
+        verbose,
+        hooks=active_hooks,
+        working_dir=working_dir,
+        final_status=requested_status,
+        time_limit=time_limit,
+    )
+
+
+def _handle_runner_exit(
+    tasks_file: pathlib.Path,
+    task_id: str,
+    returncode: int,
+    stdout: str,
+    stderr: str,
+    retries: int,
+    retry_delay: int,
+    runner_name: str,
+    yolo: bool,
+    runner_args: tuple,
+    no_defaults: bool,
+    verbose: bool,
+    active_hooks: list[str],
+    working_dir: pathlib.Path | None,
+    time_limit: int,
+) -> bool:
+    """Handles the aftermath of a task runner exiting.
+
+    Returns True to abort the run loop, False to continue.
+    """
+    # Post-execution validation and heartbeat cleanup
+    # This will mark the task as COMPLETED or PENDING based on whether
+    # the agent called 'lemming complete'.
+    post_task = tasks.finish_task_attempt(tasks_file, task_id)
+
+    if not post_task:
+        click.echo("Error: Task disappeared from roadmap during execution.")
+        return True
+
+    # Run orchestrator hooks synchronously if the task requested a status
+    # change (completion or failure). This ensures the roadmap is updated
+    # and all validation hooks complete before the next task is picked up.
+    if post_task.requested_status:
+        run_hooks(
+            tasks_file,
+            task_id,
+            runner_name,
+            yolo,
+            runner_args,
+            no_defaults,
+            verbose,
+            hooks=active_hooks,
+            working_dir=working_dir,
+            final_status=post_task.requested_status,
+            time_limit=time_limit,
+        )
+
+    if post_task.status == tasks.TaskStatus.COMPLETED:
+        if verbose:
+            click.echo("Runner successfully reported task completion.")
+        else:
+            click.echo(f"[{task_id}] Task completed successfully!")
+    else:
+        if not verbose:
+            if stdout:
+                click.echo(stdout)
+            if stderr:
+                click.echo(stderr, err=True)
+
+        if returncode == -15:
+            if verbose:
+                click.echo("Task was cancelled. Stopping orchestrator loop.")
+            return True
+
+        if verbose:
+            click.echo(
+                "Runner finished execution but did NOT report completion. "
+                "Retrying..."
+            )
+
+        # Only sleep if the task is still pending AND it wasn't cancelled
+        # (it would have requested a status if not)
+        if (
+            post_task.status == tasks.TaskStatus.PENDING
+            and post_task.attempts < retries
+            and retry_delay > 0
+            and post_task.requested_status is None
+        ):
+            if verbose:
+                click.echo(
+                    f"Waiting {retry_delay} seconds before next attempt "
+                    "to avoid rate limits..."
+                )
+            time.sleep(retry_delay)
+
+    return False
+
+
+def run_loop(
+    tasks_file: pathlib.Path,
+    verbose: bool,
+    retry_delay: int,
+    yolo: bool,
+    no_defaults: bool,
+    runner_args: tuple,
+    working_dir: pathlib.Path | None = None,
+) -> None:
+    """Starts the orchestrator loop to autonomously execute pending tasks."""
+    while True:
+        returncode = 0
+
+        # Reload configuration on each iteration to respond to changes
+        # (e.g., from Web UI)
+        data = tasks.load_tasks(tasks_file)
+
+        retries = data.config.retries
+        time_limit = data.config.time_limit
+        runner_name = data.config.runner
+        active_hooks = data.config.hooks
+        if active_hooks is None:
+            active_hooks = prompts.list_hooks(tasks_file)
+
+        current_task = tasks.get_pending_task(data)
+
+        if not current_task:
+            click.echo("All tasks completed!")
+            break
+
+        task_id = current_task.id
+
+        if current_task.attempts >= retries:
+            should_abort = _process_exhausted_retries(
+                tasks_file=tasks_file,
+                task_id=task_id,
+                retries=retries,
+                runner_name=runner_name,
+                yolo=yolo,
+                runner_args=runner_args,
+                no_defaults=no_defaults,
+                verbose=verbose,
+                active_hooks=active_hooks,
+                working_dir=working_dir,
+                time_limit=time_limit,
+            )
+            if should_abort:
+                break
+            continue
+
+        # Add a small random jitter to avoid race conditions between
+        # multiple instances
+        time.sleep(random.uniform(0.1, 0.5))
+
+        # Try to claim the task
+        current_task = tasks.claim_task(tasks_file, task_id, pid=os.getpid())
+        if not current_task:
+            if verbose:
+                click.echo(
+                    f"Task {task_id} already claimed by another instance. "
+                    "Skipping."
+                )
+            continue
+
+        if verbose:
+            click.echo(
+                f"\n--- Task {task_id} "
+                f"(Attempt {current_task.attempts}/{retries}) ---"
+            )
+            click.echo(f"Working on: {current_task.description}")
+        else:
+            click.echo(
+                f"[{task_id}] Attempt {current_task.attempts}/{retries}: "
+                f"{current_task.description}"
+            )
+
+        # If the task was picked up in a finalizing state, skip the runner
+        # and go straight to hooks.
+        if current_task.requested_status:
+            _process_finalizing_task(
+                tasks_file=tasks_file,
+                task_id=task_id,
+                requested_status=current_task.requested_status,
+                runner_name=runner_name,
+                yolo=yolo,
+                runner_args=runner_args,
+                no_defaults=no_defaults,
+                verbose=verbose,
+                active_hooks=active_hooks,
+                working_dir=working_dir,
+                time_limit=time_limit,
+            )
+            continue
+
+        prompt = prompts.prepare_prompt(
+            data, current_task, tasks_file, time_limit
+        )
+
+        if verbose:
+            click.secho("\n=== Runner Prompt ===", fg="blue", bold=True)
+            click.echo(prompt)
+            click.secho("====================\n", fg="blue", bold=True)
+
+        cmd = runner.build_runner_command(
+            current_task.runner or runner_name,
+            prompt,
+            yolo,
+            runner_args,
+            no_defaults,
+            verbose=verbose,
+            time_limit=time_limit,
+        )
+
+        returncode = 0
+        stdout, stderr = "", ""
+        try:
+            returncode, stdout, stderr = runner.run_with_heartbeat(
+                cmd,
+                tasks_file,
+                task_id,
+                verbose,
+                echo_fn=lambda line: click.echo(line, nl=False),
+                header="Task Runner",
+                cwd=working_dir,
+                time_limit=time_limit,
+            )
+            if returncode == runner.RETURNCODE_TIMEOUT:
+                click.echo(
+                    f"\nTask {task_id} killed: "
+                    f"time limit of {time_limit}m reached."
+                )
+            elif returncode != 0:
+                click.echo(
+                    f"\n{runner_name.capitalize()} execution failed "
+                    f"with exit code {returncode}"
+                )
+                if returncode == 127:
+                    click.echo(
+                        f"\nNOTE: Command '{runner_name}' not found.\n"
+                        "If you are using a shell alias, "
+                        "Python subprocesses cannot see it.\n"
+                        "Fixes:\n"
+                        "1. Use the absolute path: `lemming config set "
+                        f"runner /path/to/{runner_name}`\n"
+                        "2. Create an executable wrapper script for "
+                        f"'{runner_name}' in your PATH."
+                    )
+        except Exception as e:
+            click.echo(
+                f"\nAn error occurred while executing {runner_name}: {e}"
+            )
+
+        should_abort = _handle_runner_exit(
+            tasks_file=tasks_file,
+            task_id=task_id,
+            returncode=returncode,
+            stdout=stdout,
+            stderr=stderr,
+            retries=retries,
+            retry_delay=retry_delay,
+            runner_name=runner_name,
+            yolo=yolo,
+            runner_args=runner_args,
+            no_defaults=no_defaults,
+            verbose=verbose,
+            active_hooks=active_hooks,
+            working_dir=working_dir,
+            time_limit=time_limit,
+        )
+        if should_abort:
+            break
+
+
+def format_duration(minutes: int) -> str:
+    """Formats a duration in minutes as a human-readable string.
+
+    Args:
+        minutes: Duration in minutes.
+
+    Returns:
+        A human-readable duration string (e.g., '60m', '2h').
+    """
+    if minutes <= 0:
+        return "none"
+    if minutes >= 60 and minutes % 60 == 0:
+        return f"{minutes // 60}h"
+    return f"{minutes}m"
+
+
+def parse_timeout(t_str: str) -> float:
+    """Parses a duration string into seconds.
+
+    Args:
+        t_str: Duration string (e.g., '8h', '30m', '90s').
+
+    Returns:
+        The duration in seconds as a float.
+    """
+    t_str = t_str.strip()
+    if t_str == "0" or t_str.startswith("-"):
+        return 0.0
+
+    multiplier = 1.0
+    if t_str.endswith("h"):
+        multiplier = 3600.0
+        t_str = t_str[:-1]
+    elif t_str.endswith("m"):
+        multiplier = 60.0
+        t_str = t_str[:-1]
+    elif t_str.endswith("s"):
+        t_str = t_str[:-1]
+
+    try:
+        return float(t_str) * multiplier
+    except ValueError:
+        return 0.0