lemming-cli 0.1.0__py3-none-any.whl

lemming/paths_test.py

@@ -0,0 +1,186 @@
+import logging
+import os
+import pathlib
+import stat
+import subprocess
+from unittest import mock
+
+from lemming import paths
+
+
+def test_get_lemming_home_default():
+    expected = pathlib.Path.home() / ".local" / "lemming"
+    if "LEMMING_HOME" in os.environ:
+        del os.environ["LEMMING_HOME"]
+    assert paths.get_lemming_home() == expected
+
+
+def test_get_lemming_home_override(tmp_path):
+    os.environ["LEMMING_HOME"] = str(tmp_path)
+    assert paths.get_lemming_home() == tmp_path
+    del os.environ["LEMMING_HOME"]
+
+
+def test_get_project_dir(tmp_path):
+    tasks_file = tmp_path / "my_tasks.yml"
+    tasks_file.touch()
+
+    project_dir = paths.get_project_dir(tasks_file)
+    assert str(paths.get_lemming_home()) in str(project_dir)
+
+    # Check that it's consistent
+    assert paths.get_project_dir(tasks_file) == project_dir
+
+
+def test_get_default_tasks_file_local(tmp_path):
+    orig_cwd = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        local_tasks = tmp_path / "tasks.yml"
+        local_tasks.touch()
+        assert paths.get_default_tasks_file() == tmp_path / "tasks.yml"
+    finally:
+        os.chdir(orig_cwd)
+
+
+def test_get_log_file(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    log_file = paths.get_log_file(tasks_file, "task123")
+    assert log_file.name == "task123-runner.log"
+    assert log_file.parent.exists()
+
+
+def test_in_git_repo_and_is_ignored(tmp_path):
+    orig_cwd = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        paths.in_git_repo.cache_clear()
+
+        # Not a git repo yet
+        assert paths.in_git_repo() is False
+        assert paths.is_ignored(tmp_path / "foo.txt") is False
+
+        # Init git repo
+        subprocess.run(["git", "init", "-q"], check=True)
+        subprocess.run(
+            ["git", "config", "user.email", "test@example.com"], check=True
+        )
+        subprocess.run(["git", "config", "user.name", "test"], check=True)
+
+        # Clear cache again
+        paths.in_git_repo.cache_clear()
+
+        assert paths.in_git_repo() is True
+
+        # Create a gitignore
+        (tmp_path / ".gitignore").write_text("ignored.txt\n", encoding="utf-8")
+        (tmp_path / "ignored.txt").touch()
+        (tmp_path / "not_ignored.txt").touch()
+
+        assert paths.is_ignored(tmp_path / "ignored.txt") is True
+        assert paths.is_ignored(tmp_path / "not_ignored.txt") is False
+
+    finally:
+        os.chdir(orig_cwd)
+
+
+class TestParseDotenv:
+    def test_basic_key_value(self, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text("FOO=bar\nBAZ=qux\n")
+        assert paths._parse_dotenv(env_file) == {"FOO": "bar", "BAZ": "qux"}
+
+    def test_comments_and_blank_lines(self, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text("# comment\n\nFOO=bar\n  # another\n")
+        assert paths._parse_dotenv(env_file) == {"FOO": "bar"}
+
+    def test_quoted_values(self, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text("SINGLE='hello world'\nDOUBLE=\"hello world\"\n")
+        result = paths._parse_dotenv(env_file)
+        assert result == {"SINGLE": "hello world", "DOUBLE": "hello world"}
+
+    def test_export_prefix(self, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text("export FOO=bar\n")
+        assert paths._parse_dotenv(env_file) == {"FOO": "bar"}
+
+    def test_value_with_equals(self, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text("URL=https://example.com?a=1&b=2\n")
+        assert paths._parse_dotenv(env_file) == {
+            "URL": "https://example.com?a=1&b=2"
+        }
+
+    def test_missing_file(self, tmp_path):
+        assert paths._parse_dotenv(tmp_path / "nope") == {}
+
+    def test_malformed_line_skipped(self, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text("GOOD=yes\nBADLINE\nALSO_GOOD=yes\n")
+        result = paths._parse_dotenv(env_file)
+        assert result == {"GOOD": "yes", "ALSO_GOOD": "yes"}
+
+
+class TestLoadDotenv:
+    def test_global_env_loaded(self, tmp_path):
+        global_env = tmp_path / ".env"
+        global_env.write_text("LEMMING_TEST_GLOBAL=from_global\n")
+        with mock.patch.object(
+            paths, "get_lemming_home", return_value=tmp_path
+        ):
+            with mock.patch.dict(os.environ, {}, clear=True):
+                os.environ["PATH"] = "/usr/bin:/bin"
+                paths.load_dotenv()
+                assert os.environ["LEMMING_TEST_GLOBAL"] == "from_global"
+
+    def test_project_env_overrides_global(self, tmp_path):
+        home_dir = tmp_path / "home"
+        home_dir.mkdir()
+        proj_dir = tmp_path / "project"
+        proj_dir.mkdir()
+
+        (home_dir / ".env").write_text("MY_VAR=global\nONLY_GLOBAL=yes\n")
+        (proj_dir / ".env").write_text("MY_VAR=project\n")
+
+        with mock.patch.object(
+            paths, "get_lemming_home", return_value=home_dir
+        ):
+            with mock.patch.dict(os.environ, {}, clear=True):
+                os.environ["PATH"] = "/usr/bin:/bin"
+                paths.load_dotenv(project_dir=proj_dir)
+                assert os.environ["MY_VAR"] == "project"
+                assert os.environ["ONLY_GLOBAL"] == "yes"
+
+    def test_real_env_wins(self, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text("EXISTING=from_file\n")
+        with mock.patch.object(
+            paths, "get_lemming_home", return_value=tmp_path
+        ):
+            with mock.patch.dict(
+                os.environ, {"EXISTING": "from_shell"}, clear=True
+            ):
+                os.environ["PATH"] = "/usr/bin:/bin"
+                paths.load_dotenv()
+                assert os.environ["EXISTING"] == "from_shell"
+
+    def test_no_env_files_is_noop(self, tmp_path):
+        with mock.patch.object(
+            paths, "get_lemming_home", return_value=tmp_path
+        ):
+            with mock.patch.dict(os.environ, {}, clear=True):
+                os.environ["PATH"] = "/usr/bin:/bin"
+                paths.load_dotenv()  # should not raise
+
+
+class TestCheckPermissions:
+    def test_warns_on_world_readable(self, tmp_path, caplog):
+        env_file = tmp_path / ".env"
+        env_file.write_text("X=1\n")
+        env_file.chmod(stat.S_IRUSR | stat.S_IWUSR | stat.S_IROTH)
+
+        with caplog.at_level(logging.WARNING):
+            paths._check_permissions(env_file)
+        assert "permissive" in caplog.text

lemming/persistence.py

@@ -0,0 +1,179 @@
+"""YAML persistence and file locking for the roadmap state."""
+
+import contextlib
+import fcntl
+import os
+import pathlib
+
+import yaml
+
+from . import models, paths
+
+STALE_THRESHOLD = 30  # seconds
+LOOP_LOCK_FILENAME = ".lemming_loop.lock"
+
+
+@contextlib.contextmanager
+def lock_tasks(tasks_file: pathlib.Path):
+    """Context manager for cross-platform file locking.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+    """
+    tasks_file.parent.mkdir(parents=True, exist_ok=True)
+    # Ensure the file exists before we can lock it
+    if not tasks_file.exists():
+        tasks_file.write_text("{}", encoding="utf-8")
+
+    lock_path = tasks_file.with_suffix(".lock")
+    with open(lock_path, "w") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(lock_file, fcntl.LOCK_UN)
+
+
+@contextlib.contextmanager
+def read_lock_tasks(tasks_file: pathlib.Path):
+    """Context manager that acquires a shared (read) lock on the tasks file.
+
+    Use this around load_tasks() in read-only paths (e.g. API polling) to
+    prevent reading a partially-written file. Do NOT nest inside lock_tasks()
+    as that will deadlock on Linux.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+    """
+    tasks_file.parent.mkdir(parents=True, exist_ok=True)
+    if not tasks_file.exists():
+        tasks_file.write_text("{}", encoding="utf-8")
+
+    lock_path = tasks_file.with_suffix(".lock")
+    with open(lock_path, "w") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_SH)
+        try:
+            yield
+        finally:
+            fcntl.flock(lock_file, fcntl.LOCK_UN)
+
+
+def load_tasks(tasks_file: pathlib.Path) -> models.Roadmap:
+    """Loads tasks from a YAML file.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+
+    Returns:
+        A Roadmap containing the context and list of tasks.
+    """
+    if not tasks_file.exists():
+        return models.Roadmap(
+            context="# Project Context\n\nAdd your guidelines here.",
+            tasks=[],
+        )
+
+    try:
+        with open(tasks_file, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except (yaml.scanner.ScannerError, yaml.parser.ParserError) as e:
+        # If the file is corrupted, return an empty roadmap.
+        # This allows the user to continue, but may cause loss of some data.
+        # In a real-world scenario, we might want to back up the corrupted file.
+        print(f"Warning: Failed to load corrupted tasks file: {e}")
+        return models.Roadmap(
+            context="# Project Context (Corrupted File Recovery)\n\n"
+            "The tasks file was corrupted and could not be fully loaded.\n"
+            "Check the server logs or the original file for details.",
+            tasks=[],
+        )
+
+    if not data:
+        data = {}
+    # TODO(compat): Remove once all clients write "progress" instead of
+    # "outcomes".
+    for task_data in data.get("tasks", []):
+        if "outcomes" in task_data:
+            task_data["progress"] = task_data.pop("outcomes")
+
+        # TODO(compat): Remove alongside the config migration below.
+        if task_data.get("runner") == "gemini":
+            task_data.pop("runner")
+
+    # TODO(compat): Remove once no persisted configs reference the deprecated
+    # gemini runner. Dropping the key lets runtime detection pick the default.
+    config_data = data.get("config")
+    if isinstance(config_data, dict) and config_data.get("runner") == "gemini":
+        config_data.pop("runner")
+
+    return models.Roadmap.model_validate(data)
+
+
+class _BlockStyleDumper(yaml.SafeDumper):
+    """YAML dumper that forces multiline strings to use block style (|)."""
+
+    def represent_scalar(self, tag, value, style=None):
+        if tag == "tag:yaml.org,2002:str" and "\n" in value:
+            style = "|"
+        return super().represent_scalar(tag, value, style)
+
+
+def save_tasks(tasks_file: pathlib.Path, data: models.Roadmap) -> None:
+    """Saves the roadmap data to a YAML file.
+
+    Args:
+        tasks_file: Path to the tasks YAML file.
+        data: The Roadmap to save.
+    """
+    tasks_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Use a temporary file for atomic write
+    temp_file = tasks_file.with_suffix(".tmp")
+    with open(temp_file, "w", encoding="utf-8") as f:
+        # Exclude runtime-computed fields from the YAML file.
+        exclude = {
+            "tasks": {
+                "__all__": {
+                    "index",
+                    "has_runner_log",
+                }
+            }
+        }
+        yaml.dump(
+            data.model_dump(exclude_none=True, mode="json", exclude=exclude),
+            f,
+            Dumper=_BlockStyleDumper,
+            default_flow_style=False,
+            sort_keys=False,
+            width=1000,
+        )
+
+    # Atomically replace the old file with the new one
+    os.replace(temp_file, tasks_file)
+
+
+def _get_loop_lock_path(tasks_file: pathlib.Path) -> pathlib.Path:
+    project_dir = paths.get_project_dir(tasks_file)
+    project_dir.mkdir(parents=True, exist_ok=True)
+    return project_dir / LOOP_LOCK_FILENAME
+
+
+def acquire_loop_lock(tasks_file: pathlib.Path) -> None:
+    """Write a loop lock file with the current PID."""
+    _get_loop_lock_path(tasks_file).write_text(str(os.getpid()))
+
+
+def release_loop_lock(tasks_file: pathlib.Path) -> None:
+    """Remove the loop lock file."""
+    _get_loop_lock_path(tasks_file).unlink(missing_ok=True)
+
+
+def get_loop_pid(tasks_file: pathlib.Path) -> int | None:
+    """Returns the PID of the running orchestrator loop, if any."""
+    lock_path = _get_loop_lock_path(tasks_file)
+    if not lock_path.exists():
+        return None
+    try:
+        return int(lock_path.read_text().strip())
+    except (ValueError, OSError):
+        return None

lemming/persistence_test.py

@@ -0,0 +1,150 @@
+import os
+
+import yaml
+
+from lemming import models, persistence
+
+
+def test_lock_tasks(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    with persistence.lock_tasks(tasks_file):
+        assert tasks_file.exists()
+        assert tasks_file.read_text() == "{}"
+
+    lock_path = tasks_file.with_suffix(".lock")
+    assert lock_path.exists()
+
+
+def test_load_save_tasks(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        context="test",
+        tasks=[
+            models.Task(
+                id="1",
+                description="task 1",
+                status=models.TaskStatus.PENDING,
+                attempts=0,
+            )
+        ],
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    loaded = persistence.load_tasks(tasks_file)
+    assert loaded.context == "test"
+    assert len(loaded.tasks) == 1
+    assert loaded.tasks[0].id == "1"
+
+
+def test_load_tasks_migrates_deprecated_gemini_runner(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    tasks_file.write_text(
+        yaml.dump({"config": {"runner": "gemini", "retries": 5}})
+    )
+
+    loaded = persistence.load_tasks(tasks_file)
+    # The deprecated runner is dropped so runtime detection supplies the
+    # default.
+    assert loaded.config.runner in models.KNOWN_RUNNERS
+    # Other user-set config values are preserved.
+    assert loaded.config.retries == 5
+
+
+def test_load_tasks_migrates_deprecated_gemini_task_runner(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    tasks_file.write_text(
+        yaml.dump(
+            {
+                "tasks": [
+                    {"id": "1", "description": "a", "runner": "gemini"},
+                    {"id": "2", "description": "b", "runner": "aider"},
+                ]
+            }
+        )
+    )
+
+    loaded = persistence.load_tasks(tasks_file)
+    # The deprecated per-task runner is dropped so the config runner is used.
+    assert loaded.tasks[0].runner is None
+    assert loaded.tasks[1].runner == "aider"
+
+
+def test_load_tasks_preserves_explicit_runner(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    tasks_file.write_text(yaml.dump({"config": {"runner": "aider"}}))
+
+    loaded = persistence.load_tasks(tasks_file)
+    assert loaded.config.runner == "aider"
+
+
+def test_loop_lock_management(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+
+    # Initially, no loop is running
+    assert persistence.get_loop_pid(tasks_file) is None
+
+    # Create a lock file
+    persistence.acquire_loop_lock(tasks_file)
+    pid = persistence.get_loop_pid(tasks_file)
+    assert pid == os.getpid()
+
+    # Release the lock
+    persistence.release_loop_lock(tasks_file)
+    assert persistence.get_loop_pid(tasks_file) is None
+
+
+def test_get_loop_pid_corrupted_lock_file(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    lock_path = persistence._get_loop_lock_path(tasks_file)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write "corrupted" content
+    lock_path.write_text("not-a-pid")
+    assert persistence.get_loop_pid(tasks_file) is None
+
+
+def test_save_tasks_excludes_computed_fields(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    task = models.Task(
+        id="123",
+        description="Test Task",
+        index=5,
+        has_runner_log=True,
+    )
+    roadmap = models.Roadmap(tasks=[task])
+
+    persistence.save_tasks(tasks_file, roadmap)
+
+    # Read the raw YAML to verify exclusion
+    with open(tasks_file, "r", encoding="utf-8") as f:
+        raw_data = yaml.safe_load(f)
+
+    task_data = raw_data["tasks"][0]
+    assert "id" in task_data
+    assert "description" in task_data
+    # Computed fields should be excluded
+    assert "index" not in task_data
+    assert "has_runner_log" not in task_data
+
+
+def test_save_tasks_uses_block_style_for_multiline_strings(tmp_path):
+    tasks_file = tmp_path / "tasks.yml"
+    multiline_description = "Line 1\nLine 2\nLine 3"
+    task = models.Task(
+        id="123",
+        description=multiline_description,
+    )
+    roadmap = models.Roadmap(tasks=[task])
+
+    persistence.save_tasks(tasks_file, roadmap)
+
+    # Read the raw content to check for '|'
+    content = tasks_file.read_text(encoding="utf-8")
+    assert "description: |" in content
+    assert "Line 1" in content
+    assert "Line 2" in content
+    assert "Line 3" in content
+
+    # Verify that it still loads correctly
+    loaded = persistence.load_tasks(tasks_file)
+    assert loaded.tasks[0].description == multiline_description

lemming/prompts/hooks/readability.md

@@ -0,0 +1,42 @@
+# Readability Hook
+
+You are a senior code reviewer. Your goal is to ensure code quality and
+adherence to the Google Style Guide with minimal overhead.
+
+## Context
+
+{{roadmap}}
+
+## Finished Task
+
+{{finished_task}}
+
+## Directives
+
+1.  **Automate**: Immediately run `lemming readability check <path> --fix` for
+    every file modified or created in the last task. This handles standard
+    formatting (ruff, biome, prettier) and type checking (pyrefly).
+2.  **Report**: Record any meaningful findings as progress using
+    `lemming progress {{finished_task_id}} '<finding>'`.
+3.  **No Orchestration**: Do NOT add new tasks to the roadmap. If you identify
+    significant issues that require follow-up work, record them as progress so
+    the roadmap hook can decide whether to add a new task.
+4.  **No Manual Refactoring**: Do NOT perform manual code changes. Stick
+    EXCLUSIVELY to automated fixes via `lemming readability check`.
+5.  **Fast Exit**: If the code is clean after automated checks, exit
+    immediately.
+
+## Commands
+
+```bash
+# Fix formatting/linting
+lemming readability check <path> --fix
+# Consult style guides (only if strictly necessary)
+lemming readability guide <language>
+# Record progress
+lemming --tasks-file {{tasks_file_path}} progress {{finished_task_id}} '<finding>'
+```
+
+Limit your review ONLY to the files changed in the last task. Avoid
+"just-in-case" analysis. Your goal is formatting consistency, not feature
+completeness or architectural review.

lemming/prompts/hooks/roadmap.md

@@ -0,0 +1,61 @@
+# Roadmap Hook
+
+You are a roadmap orchestrator. Your goal is to keep the project on track and
+the plan up-to-date with minimal friction.
+
+## Roadmap
+
+{{roadmap}}
+
+## Finished Task
+
+{{finished_task}}
+
+## Directives
+
+1.  **Diagnose**: Review the execution logs and progress of the finished task to
+    understand its impact on the roadmap. Check if the task was FULLY completed,
+    including any necessary cleanup, teardowns, or documentation.
+2.  **Repair**: If a task has failed, you MUST intervene. Simply resetting a
+    task without changing the approach will lead to the same failure. You MUST
+    either:
+    - Rewrite its description with a fundamentally different approach and then
+      reset its attempts.
+    - Delete it and insert smaller, more manageable prerequisite tasks to
+      unblock the goal.
+    - If it failed due to timeout, split it into smaller sub-tasks.
+    - If it failed due to rate limits (429), you might still want to refine the
+      description to be more efficient, or just reset it if you think it was a
+      transient issue, but be aware that if it reached the max attempts, you
+      MUST change something or the project will abort.
+3.  **Refine**: If any pending tasks are now redundant, overly broad, or based
+    on invalidated assumptions, edit or delete them immediately.
+4.  **Extend**: If the project goal is not yet fully achieved and all tasks are
+    finished, add concrete, self-contained tasks to close the gap.
+5.  **Follow-up**: If you identify missing work from the previous task (like
+    forgotten teardowns, missing tests reported by the testing hook, or
+    formatting issues reported by the readability hook), add new tasks to
+    address them.
+6.  **No Code Changes**: Your only role is to modify the roadmap via the
+    `lemming` CLI. Do NOT touch source files.
+7.  **Fast Exit**: If the roadmap is accurate and well-structured, AND there are
+    no failed tasks that have reached their maximum attempts, you may exit
+    immediately without running any commands. However, if a task is marked as
+    FAILED and has reached its maximum attempts, a Fast Exit will result in the
+    entire project ABORTING. In that case, you MUST repair it.
+
+## Commands
+
+```bash
+# Add new tasks
+lemming --tasks-file {{tasks_file_path}} add '<description>' [--index N]
+# Edit existing tasks
+lemming --tasks-file {{tasks_file_path}} edit <id> --description '<desc>'
+# Reset/Delete/Status
+lemming --tasks-file {{tasks_file_path}} reset <id>
+lemming --tasks-file {{tasks_file_path}} delete <id>
+lemming --tasks-file {{tasks_file_path}} progress <id> '<finding>'
+```
+
+Avoid "be thorough" mindset — favor speed and clarity. Only act if the roadmap
+is factually outdated or inefficient.

lemming/prompts/hooks/testing.md

@@ -0,0 +1,44 @@
+# Testing Hook
+
+You are a senior developer verifying the most recent task for testing and
+reliability. Your goal is to ensure functionality remains robust with minimal
+overhead.
+
+## Context
+
+{{roadmap}}
+
+## Finished Task
+
+{{finished_task}}
+
+## Directives
+
+1.  **Verify**: Every non-trivial code change must have corresponding unit
+    tests. If new or modified logic lacks testing, you must act.
+2.  **Validate**: Run the relevant test suite for the modified components to
+    ensure all tests pass.
+3.  **Repair/Fix**: For minor testing gaps or simple bug fixes in tests, you may
+    fix them only if it's strictly necessary for the test suite to pass the
+    current changes.
+4.  **No Orchestration**: Do NOT add new tasks to the roadmap. If you identify
+    significant testing gaps or architectural issues that require follow-up
+    work, record them as progress so the roadmap hook can decide whether to add
+    a new task.
+5.  **No Manual Refactoring**: Do NOT perform complex, manual code changes or
+    broad refactors. Stick strictly to verification and targeted test fixes.
+6.  **Fast Exit**: If tests are passings and coverage is sufficient for the
+    change, exit immediately.
+7.  **Consolidate Tests**: Maintain a 1:1 mapping between code files and test
+    files in the same directory (excluding integration tests). Avoid one-off
+    test files.
+
+## Commands
+
+```bash
+# Record progress
+lemming --tasks-file {{tasks_file_path}} progress {{finished_task_id}} '<finding>'
+```
+
+Limit your review ONLY to the code changed in the last task. Your goal is
+verification, not a general security or performance audit.