lemming-cli 0.1.0__py3-none-any.whl

lemming/tasks/operations.py

@@ -0,0 +1,258 @@
+"""Task CRUD operations: add, update, delete, and context updates."""
+
+import os
+import pathlib
+import time
+
+from .. import models, persistence
+from . import lifecycle
+
+
+def add_task(
+    tasks_file: pathlib.Path,
+    description: str,
+    runner: str | None = None,
+    index: int = -1,
+    parent: str | None = None,
+    parent_tasks_file: str | None = None,
+) -> models.Task:
+    """Adds a new task to the roadmap.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        description: Description of the task.
+        runner: Optional preferred runner for this task.
+        index: Position to insert the task at (default: append).
+        parent: Optional parent task ID.
+        parent_tasks_file: Optional parent tasks file path.
+
+    Returns:
+        The newly created Task.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+
+        task_id = lifecycle.generate_task_id()
+        existing_ids = {t.id for t in data.tasks}
+        while task_id in existing_ids:
+            task_id = lifecycle.generate_task_id()
+
+        # Detect if we are running inside an agent and set parent automatically
+        if not parent:
+            parent = os.environ.get("LEMMING_PARENT_TASK_ID")
+            if not parent_tasks_file:
+                parent_tasks_file = os.environ.get("LEMMING_PARENT_TASKS_FILE")
+
+        new_task = models.Task(
+            id=task_id,
+            description=description,
+            runner=runner,
+            parent=parent,
+            parent_tasks_file=parent_tasks_file,
+        )
+
+        if index == -1:
+            data.tasks.append(new_task)
+        else:
+            data.tasks.insert(index, new_task)
+
+        persistence.save_tasks(tasks_file, data)
+    return new_task
+
+
+def delete_tasks(
+    tasks_file: pathlib.Path,
+    task_id: str | None = None,
+    all_tasks: bool = False,
+    completed_only: bool = False,
+) -> int:
+    """Deletes tasks from the roadmap.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: Optional ID of a specific task to delete.
+        all_tasks: If True, deletes all tasks and clears context.
+        completed_only: If True, deletes only completed tasks.
+
+    Returns:
+        The number of tasks deleted.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        initial_count = len(data.tasks)
+
+        if all_tasks:
+            for t in data.tasks:
+                lifecycle.reset_task_logs(tasks_file, t.id)
+            data.tasks = []
+            data.context = ""
+        elif completed_only:
+            completed_tasks = [
+                t
+                for t in data.tasks
+                if t.status
+                in (
+                    models.TaskStatus.COMPLETED,
+                    models.TaskStatus.FAILED,
+                    models.TaskStatus.CANCELLED,
+                )
+            ]
+            for t in completed_tasks:
+                lifecycle.reset_task_logs(tasks_file, t.id)
+            data.tasks = [
+                t
+                for t in data.tasks
+                if t.status
+                not in (
+                    models.TaskStatus.COMPLETED,
+                    models.TaskStatus.FAILED,
+                    models.TaskStatus.CANCELLED,
+                )
+            ]
+        elif task_id:
+            tasks_to_delete = [
+                t for t in data.tasks if t.id.startswith(task_id)
+            ]
+            for t in tasks_to_delete:
+                lifecycle.reset_task_logs(tasks_file, t.id)
+            data.tasks = [t for t in data.tasks if not t.id.startswith(task_id)]
+
+        persistence.save_tasks(tasks_file, data)
+        return initial_count - len(data.tasks)
+
+
+def update_task(
+    tasks_file: pathlib.Path,
+    task_id: str,
+    description: str | None = None,
+    runner: str | None = None,
+    index: int | None = None,
+    status: str | None = None,
+    require_progress: bool = False,
+    parent: str | None = None,
+    parent_tasks_file: str | None = None,
+    force: bool = False,
+) -> models.Task:
+    """Updates an existing task.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: ID of the task to update.
+        description: New description.
+        runner: New preferred runner.
+        index: New position in the task list.
+        status: New status.
+        require_progress: If True, raises ValueError if the task has no
+            progress.
+        parent: New parent task ID.
+        parent_tasks_file: New parent tasks file path.
+        force: If True, force status transition even if task is in progress.
+
+    Returns:
+        The updated Task.
+
+    Raises:
+        ValueError: If the task is not found, or if validation fails.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+
+        # Find the task
+        task_idx = -1
+        target = None
+        for i, t in enumerate(data.tasks):
+            if t.id.startswith(task_id):
+                task_idx = i
+                target = t
+                break
+
+        if not target:
+            raise models.TaskNotFoundError(f"Task {task_id} not found")
+
+        if target.status == models.TaskStatus.COMPLETED and description:
+            raise ValueError("Cannot edit description of a completed task")
+
+        if require_progress and not target.progress:
+            raise ValueError(
+                f"Task {target.id} has no recorded progress. "
+                "Record at least one progress entry before completing "
+                "or failing."
+            )
+
+        if description is not None:
+            target.description = description
+        if runner is not None:
+            target.runner = runner
+        if parent is not None:
+            if parent == "":
+                target.parent = None
+            else:
+                target.parent = parent
+        if parent_tasks_file is not None:
+            if parent_tasks_file == "":
+                target.parent_tasks_file = None
+            else:
+                target.parent_tasks_file = parent_tasks_file
+
+        if status and status != target.status:
+            # If the task is currently in progress, we don't transition to
+            # completed/failed immediately. We set requested_status so the
+            # orchestrator can run hooks before final completion.
+            if (
+                not force
+                and target.status == models.TaskStatus.IN_PROGRESS
+                and status
+                in (
+                    models.TaskStatus.COMPLETED,
+                    models.TaskStatus.FAILED,
+                    models.TaskStatus.CANCELLED,
+                )
+            ):
+                lifecycle.update_run_time(target)
+                target.requested_status = models.TaskStatus(status)
+                target.last_started_at = (
+                    time.time()
+                )  # Track hook execution time
+            else:
+                if target.status == models.TaskStatus.IN_PROGRESS:
+                    lifecycle.update_run_time(target)
+
+                target.status = models.TaskStatus(status)
+                if status in (
+                    models.TaskStatus.COMPLETED,
+                    models.TaskStatus.FAILED,
+                    models.TaskStatus.CANCELLED,
+                ):
+                    target.completed_at = time.time()
+                    target.pid = None
+                    target.last_heartbeat = None
+                    target.requested_status = None
+                elif status == models.TaskStatus.PENDING:
+                    target.completed_at = None
+                    target.attempts = 0
+                    target.requested_status = None
+                elif target.completed_at is not None:
+                    target.completed_at = None
+
+        if index is not None:
+            task_to_move = data.tasks.pop(task_idx)
+            if index == -1:
+                data.tasks.append(task_to_move)
+            else:
+                data.tasks.insert(index, task_to_move)
+
+        persistence.save_tasks(tasks_file, data)
+    return target
+
+
+def update_context(tasks_file: pathlib.Path, context: str) -> None:
+    """Updates the project context.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        context: The new project context string.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        data.context = context
+        persistence.save_tasks(tasks_file, data)

lemming/tasks/operations_test.py

@@ -0,0 +1,172 @@
+import os
+import time
+from unittest.mock import patch
+
+import pytest
+
+from .. import models, persistence
+from . import operations
+
+
+def test_add_task_captures_parent_project(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    parent_file = tmp_path / "parent_tasks.yml"
+
+    with patch.dict(
+        os.environ,
+        {
+            "LEMMING_PARENT_TASK_ID": "parent123",
+            "LEMMING_PARENT_TASKS_FILE": str(parent_file),
+        },
+    ):
+        task = operations.add_task(tasks_file, "child task")
+        assert task.parent == "parent123"
+        assert task.parent_tasks_file == str(parent_file)
+
+    # Manual override
+    task2 = operations.add_task(tasks_file, "another task", parent="override")
+    assert task2.parent == "override"
+    assert task2.parent_tasks_file is None
+
+
+def test_add_task(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    # Scaffold tasks file
+    persistence.save_tasks(tasks_file, models.Roadmap())
+
+    now = time.time()
+    task = operations.add_task(tasks_file, "New task")
+    assert task.description == "New task"
+    assert task.status == models.TaskStatus.PENDING
+    assert task.created_at >= now
+
+    data = persistence.load_tasks(tasks_file)
+    assert len(data.tasks) == 1
+    assert data.tasks[0].created_at == task.created_at
+
+
+def test_update_task_description(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    task = operations.add_task(tasks_file, "Old description")
+    task_id = task.id
+
+    # 1. Successful update
+    updated = operations.update_task(
+        tasks_file, task_id, description="New description"
+    )
+    assert updated.description == "New description"
+
+    # 2. Cannot edit description of a completed task
+    operations.update_task(
+        tasks_file, task_id, status=models.TaskStatus.COMPLETED
+    )
+
+    with pytest.raises(
+        ValueError, match="Cannot edit description of a completed task"
+    ):
+        operations.update_task(
+            tasks_file, task_id, description="Trying to change"
+        )
+
+
+def test_update_task_runner(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    task = operations.add_task(tasks_file, "Task without runner")
+    task_id = task.id
+
+    assert task.runner is None
+
+    updated = operations.update_task(
+        tasks_file, task_id, runner="custom-runner"
+    )
+    assert updated.runner == "custom-runner"
+
+
+def test_update_task_index(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    operations.add_task(tasks_file, "Task 0")
+    operations.add_task(tasks_file, "Task 1")
+    t2 = operations.add_task(tasks_file, "Task 2")
+    task_id = t2.id
+
+    # data.tasks is [Task 0, Task 1, Task 2]
+    # Move Task 2 to index 0
+    operations.update_task(tasks_file, task_id, index=0)
+    data = persistence.load_tasks(tasks_file)
+    assert [t.description for t in data.tasks] == ["Task 2", "Task 0", "Task 1"]
+
+    # Move Task 2 to the end
+    operations.update_task(tasks_file, task_id, index=-1)
+    data = persistence.load_tasks(tasks_file)
+    assert [t.description for t in data.tasks] == ["Task 0", "Task 1", "Task 2"]
+
+
+def test_update_task_status_lifecycle(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    task = operations.add_task(tasks_file, "Status lifecycle")
+    task_id = task.id
+
+    # 1. PENDING -> COMPLETED
+    updated = operations.update_task(
+        tasks_file, task_id, status=models.TaskStatus.COMPLETED
+    )
+    assert updated.status == models.TaskStatus.COMPLETED
+    assert updated.completed_at is not None
+
+    # 2. COMPLETED -> PENDING (resets attempts and completed_at)
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        data.tasks[0].attempts = 5
+        persistence.save_tasks(tasks_file, data)
+
+    updated = operations.update_task(
+        tasks_file, task_id, status=models.TaskStatus.PENDING
+    )
+    assert updated.status == models.TaskStatus.PENDING
+    assert updated.completed_at is None
+    assert updated.attempts == 0
+
+
+def test_update_task_parent_fields(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    task = operations.add_task(tasks_file, "Update parent fields")
+    task_id = task.id
+
+    # 1. Update with values
+    updated = operations.update_task(
+        tasks_file,
+        task_id,
+        parent="parent123",
+        parent_tasks_file="parent_tasks.yml",
+    )
+    assert updated.parent == "parent123"
+    assert updated.parent_tasks_file == "parent_tasks.yml"
+
+    # 2. Clear values with empty strings
+    cleared = operations.update_task(
+        tasks_file,
+        task_id,
+        parent="",
+        parent_tasks_file="",
+    )
+    assert cleared.parent is None
+    assert cleared.parent_tasks_file is None
+
+
+def test_delete_tasks(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    operations.add_task(tasks_file, "Task 1")
+    t2 = operations.add_task(tasks_file, "Task 2")
+
+    count = operations.delete_tasks(tasks_file, task_id=t2.id)
+    assert count == 1
+    data = persistence.load_tasks(tasks_file)
+    assert len(data.tasks) == 1
+    assert data.tasks[0].description == "Task 1"
+
+
+def test_update_context(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    operations.update_context(tasks_file, "new context")
+    data = persistence.load_tasks(tasks_file)
+    assert data.context == "new context"

lemming/tasks/progress.py

@@ -0,0 +1,29 @@
+"""Recording of task progress entries."""
+
+import pathlib
+
+from .. import models, persistence
+
+
+def add_progress(
+    tasks_file: pathlib.Path, task_id: str, text: str
+) -> models.Task:
+    """Adds a progress entry to a task.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        task_id: ID of the task to add progress to.
+        text: The progress text to add.
+
+    Returns:
+        The updated Task.
+    """
+    with persistence.lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+        target = next((t for t in data.tasks if t.id.startswith(task_id)), None)
+        if not target:
+            raise ValueError(f"Task {task_id} not found")
+
+        target.progress.append(text)
+        persistence.save_tasks(tasks_file, data)
+    return target

lemming/tasks/progress_test.py

@@ -0,0 +1,22 @@
+from lemming import models, persistence
+from lemming.tasks import progress
+
+
+def test_add_progress(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="123",
+                description="Task 1",
+            )
+        ]
+    )
+    # create file to test load/save logic
+    persistence.save_tasks(tasks_file, data)
+
+    target = progress.add_progress(tasks_file, "123", "Found bug in module X")
+
+    assert target.id == "123"
+    assert len(target.progress) == 1
+    assert target.progress[0] == "Found bug in module X"

lemming/tasks/queries.py

@@ -0,0 +1,128 @@
+"""Read-only queries over project tasks and orchestrator state."""
+
+import pathlib
+import time
+
+from .. import models, paths, persistence
+from . import lifecycle
+
+
+def get_project_data(tasks_file: pathlib.Path) -> models.ProjectData:
+    """Consolidated logic to get project state (tasks, context, loop status).
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+
+    Returns:
+        A ProjectData containing the enriched project state.
+    """
+    with persistence.read_lock_tasks(tasks_file):
+        data = persistence.load_tasks(tasks_file)
+    now = time.time()
+
+    # Deduplicate tasks by ID and enrich metadata.
+    seen_ids = set()
+    unique_tasks = []
+    loop_running = lifecycle.is_loop_running(tasks_file)
+
+    for i, t in enumerate(data.tasks):
+        if t.id in seen_ids:
+            continue
+        seen_ids.add(t.id)
+        unique_tasks.append(t)
+
+        t.index = i
+        t.has_runner_log = paths.get_log_file(tasks_file, t.id).exists()
+
+        # Detect active loop from task heartbeats if not already known.
+        if not loop_running and lifecycle.is_task_active(t, now):
+            loop_running = True
+
+    # Unified sort: uncompleted (pending, in_progress) first, then completed
+    # (completed, failed). Within each group:
+    # - Uncompleted: in_progress tasks first, then by index (YAML order),
+    #   then by created_at.
+    # - Completed: newer tasks appear first (reverse chronological).
+    def sort_key(t):
+        is_done = t.status in (
+            models.TaskStatus.COMPLETED,
+            models.TaskStatus.FAILED,
+            models.TaskStatus.CANCELLED,
+        )
+        is_in_progress = t.status == models.TaskStatus.IN_PROGRESS
+        if not is_done:
+            # For pending/in_progress, prioritize in_progress and then YAML
+            # order (index)
+            return (
+                0,
+                0 if is_in_progress else 1,
+                (t.index if t.index is not None else 0),
+                (t.created_at or 0),
+            )
+        else:
+            # For completed/failed, we want newest first
+            return (
+                1,
+                -(t.completed_at or t.created_at or 0),
+                -(t.index if t.index is not None else 0),
+            )
+
+    unique_tasks.sort(key=sort_key)
+
+    return models.ProjectData(
+        context=data.context,
+        tasks=unique_tasks,
+        config=data.config,
+        cwd=str(paths.get_working_dir(tasks_file)),
+        loop_running=loop_running,
+    )
+
+
+def get_pending_task(data: models.Roadmap) -> models.Task | None:
+    """Finds the next task to be executed.
+
+    Args:
+        data: The Roadmap to search.
+
+    Returns:
+        The next Task to execute, or None if no tasks are pending or a task
+        is already in progress.
+    """
+    now = time.time()
+
+    # 1. Check if ANY task is currently active (running or running hooks).
+    # If so, we must not start any other task (unless it's finalizing).
+    for task in data.tasks:
+        if lifecycle.is_task_active(task, now):
+            return None
+
+        # If it's NOT active, but it has a requested_status, it means it's a
+        # crashed finalizing task. We MUST pick it up immediately.
+        if task.requested_status:
+            return task
+
+    # 2. Sort uncompleted tasks (pending or stale in_progress) to pick the
+    # oldest one (FIFO). Note: we exclude tasks that are currently finalizing
+    # (have requested_status).
+    uncompleted = []
+    for i, task in enumerate(data.tasks):
+        if (
+            task.status
+            in (models.TaskStatus.PENDING, models.TaskStatus.IN_PROGRESS)
+            and not task.requested_status
+        ):
+            # We need to preserve the original index for tie-breaking
+            task.index = i
+            uncompleted.append(task)
+
+    if not uncompleted:
+        return None
+
+    def sort_key(t):
+        return (
+            (t.index if t.index is not None else 0),
+            (t.created_at or 0),
+        )
+
+    uncompleted.sort(key=sort_key)
+    return uncompleted[0]