lemming-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{lemming_cli-0.1.2 → lemming_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lemming-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: An autonomous, iterative task runner for AI coding agents.
 Project-URL: Homepage, https://github.com/owahltinez/lemming
 Project-URL: Repository, https://github.com/owahltinez/lemming
@@ -158,19 +158,24 @@ tasks may not fully achieve the stated goal. **Orchestrator Hooks** address this
 by running custom agents or scripts after each task execution to evaluate
 results and adapt the roadmap.
 
-By default, Lemming runs all available hooks (including the built-in `roadmap`
-hook). You can customize this behavior via the `hooks` subcommand:
+Lemming runs every hook it discovers on the filesystem (including the
+built-in `roadmap` hook). Hooks are plain Markdown files, and udev-style
+filename conventions control their behavior:
 
-```bash
-# Enable or disable hooks for the project
-lemming hooks enable lint
-lemming hooks disable roadmap
+- **Ordering**: A numeric prefix sets the execution order (e.g.
+  `10-lint.md` runs before `90-roadmap.md`); files without a prefix
+  default to priority 50.
+- **Failure hooks**: Hooks at priority 90 and above also run when a task
+  fails; all others only run on success.
+- **Disabling**: An empty file masks (disables) the hook of the same name
+  from a lower-precedence layer.
 
-# Set the exact list of active hooks
-lemming hooks set roadmap lint
+```bash
+# Disable a hook for this project (writes an empty .lemming/hooks/50-lint.md)
+lemming hooks disable lint
 
-# Reset to default (run all available hooks)
-lemming hooks reset
+# Re-enable it (removes the mask file)
+lemming hooks enable lint
 ```
 
 ### Built-in Hooks ⚓️
@@ -194,10 +199,10 @@ You can create your own hooks by adding Markdown files to:
 1.  **Project-specific**: `.lemming/hooks/*.md`
 2.  **Global**: `~/.local/lemming/hooks/*.md`
 
-Lemming's built-in hooks can be symlinked to the global directory using
-`lemming hooks install`. This allows you to easily **override** a built-in hook
-by replacing its symlink with a file, or **disable** a global override by
-deleting the symlink.
+To **override** a built-in hook, create a file with the same logical name
+(the numeric prefix is not part of the name, so `20-roadmap.md` overrides
+the built-in `90-roadmap.md` and also moves it to priority 20); delete the
+file to restore the built-in version.
 
 Hooks follow a specific discovery precedence: **Project > Global > Built-in**.
 See [docs/HOOKS.md](docs/HOOKS.md) for more details.
@@ -207,18 +212,14 @@ See [docs/HOOKS.md](docs/HOOKS.md) for more details.
 Use the `config` and `hooks` commands to manage your project's execution loop:
 
 ```bash
-# List all available hooks (built-in and local)
+# List all hooks in execution order, with source and status
 lemming hooks list
 
-# Install (symlink) built-in hooks to the global directory
-lemming hooks install
-
-# View current project configuration
+# View current project configuration (includes the active hooks)
 lemming config list
 
 # Persist configuration to tasks.yml
 lemming config set runner aider
-lemming hooks set roadmap lint
 ```
 
 ### Evaluating Prompt Changes

{lemming_cli-0.1.2 → lemming_cli-0.1.4}/README.md

@@ -136,19 +136,24 @@ tasks may not fully achieve the stated goal. **Orchestrator Hooks** address this
 by running custom agents or scripts after each task execution to evaluate
 results and adapt the roadmap.
 
-By default, Lemming runs all available hooks (including the built-in `roadmap`
-hook). You can customize this behavior via the `hooks` subcommand:
+Lemming runs every hook it discovers on the filesystem (including the
+built-in `roadmap` hook). Hooks are plain Markdown files, and udev-style
+filename conventions control their behavior:
+
+- **Ordering**: A numeric prefix sets the execution order (e.g.
+  `10-lint.md` runs before `90-roadmap.md`); files without a prefix
+  default to priority 50.
+- **Failure hooks**: Hooks at priority 90 and above also run when a task
+  fails; all others only run on success.
+- **Disabling**: An empty file masks (disables) the hook of the same name
+  from a lower-precedence layer.
 
 ```bash
-# Enable or disable hooks for the project
-lemming hooks enable lint
-lemming hooks disable roadmap
-
-# Set the exact list of active hooks
-lemming hooks set roadmap lint
+# Disable a hook for this project (writes an empty .lemming/hooks/50-lint.md)
+lemming hooks disable lint
 
-# Reset to default (run all available hooks)
-lemming hooks reset
+# Re-enable it (removes the mask file)
+lemming hooks enable lint
 ```
 
 ### Built-in Hooks ⚓️
@@ -172,10 +177,10 @@ You can create your own hooks by adding Markdown files to:
 1.  **Project-specific**: `.lemming/hooks/*.md`
 2.  **Global**: `~/.local/lemming/hooks/*.md`
 
-Lemming's built-in hooks can be symlinked to the global directory using
-`lemming hooks install`. This allows you to easily **override** a built-in hook
-by replacing its symlink with a file, or **disable** a global override by
-deleting the symlink.
+To **override** a built-in hook, create a file with the same logical name
+(the numeric prefix is not part of the name, so `20-roadmap.md` overrides
+the built-in `90-roadmap.md` and also moves it to priority 20); delete the
+file to restore the built-in version.
 
 Hooks follow a specific discovery precedence: **Project > Global > Built-in**.
 See [docs/HOOKS.md](docs/HOOKS.md) for more details.
@@ -185,18 +190,14 @@ See [docs/HOOKS.md](docs/HOOKS.md) for more details.
 Use the `config` and `hooks` commands to manage your project's execution loop:
 
 ```bash
-# List all available hooks (built-in and local)
+# List all hooks in execution order, with source and status
 lemming hooks list
 
-# Install (symlink) built-in hooks to the global directory
-lemming hooks install
-
-# View current project configuration
+# View current project configuration (includes the active hooks)
 lemming config list
 
 # Persist configuration to tasks.yml
 lemming config set runner aider
-lemming hooks set roadmap lint
 ```
 
 ### Evaluating Prompt Changes

{lemming_cli-0.1.2 → lemming_cli-0.1.4}/docs/HOOKS.md

@@ -19,6 +19,27 @@ more **orchestrator hooks**. Each hook:
     execution log, and any commands it runs (e.g. `lemming add`, `lemming edit`)
     are executed against the roadmap.
 
+## Naming Convention
+
+Hooks are Markdown files discovered from the filesystem, and udev-style
+filename conventions control their behavior:
+
+- **Ordering**: A numeric prefix determines execution order: `10-lint.md`
+  runs before `90-roadmap.md`. Files without a prefix default to priority
+  50. The prefix is **not** part of the hook's name: `90-roadmap.md`
+  defines the hook `roadmap`.
+- **Failure hooks**: Hooks at priority 90 and above also run when a task
+  fails. All other hooks only run after successful tasks. The built-in
+  `roadmap` hook ships as `90-roadmap.md` so it can react to failures.
+- **Masking**: An empty file disables the hook of the same name from a
+  lower-precedence layer (see below). For example, an empty
+  `.lemming/hooks/readability.md` disables the built-in `readability` hook
+  for that project.
+- **Overriding**: A non-empty file replaces the hook of the same name from
+  a lower-precedence layer. The winning filename also determines the
+  priority, so keep the `9x-` prefix when overriding a failure hook (e.g.
+  `90-roadmap.md`), or use a different prefix to deliberately reorder it.
+
 ## Built-in Hooks
 
 ### `roadmap` (Default)
@@ -57,35 +78,18 @@ locations:
 
 ### Precedence
 
-When Lemming looks for a hook template, it follows this order:
+When Lemming looks for a hook, it resolves each logical name through the
+following layers, highest precedence first:
 
 1.  **Project-specific**: `.lemming/hooks/`
 2.  **Global**: `~/.local/lemming/hooks/`
 3.  **Built-in**: Bundled with the Lemming package.
 
-### Global Hook Management
-
-Lemming's built-in hooks can be symlinked into the global directory
-(`~/.local/lemming/hooks/`) to make them easily discoverable and overridable.
-
-Use the following command to install the symlinks:
-
-```bash
-lemming hooks install
-```
-
-This provides several ways to manage them:
-
-- **Override**: Replace the symlink with your own Markdown file of the same
-  name.
-- **Disable Global Override**: Delete the symlink from the global directory.
-  Lemming will fall back to the built-in version unless the hook is also
-  disabled in the project configuration.
-- **Restore Defaults**: Run `lemming hooks install`. Lemming will recreate any
-  missing built-in symlinks.
-
-Users can also add their own global hooks to this directory, making them
-available to all Lemming projects on the system.
+Because of this precedence order, overriding a built-in hook only requires
+creating a Markdown file with the same logical name in the project or global
+directory (e.g. `~/.local/lemming/hooks/90-roadmap.md`); delete the file to
+restore the built-in version. Global hooks are available to all Lemming
+projects on the system.
 
 ### Example: `lint` hook
 
@@ -107,29 +111,28 @@ are issues, add a new task to fix them.
 
 ## Using Hooks
 
-### Configuration
+### Enabling and Disabling
 
-By default, Lemming runs all hooks configured in your `tasks.yml`. If no hooks
-are explicitly configured, all available hooks (built-in and project-specific)
-are executed.
+Lemming runs every hook it discovers that is not masked. There is no hook
+configuration in `tasks.yml`; the filesystem is the single source of truth.
 
-Use the `hooks` command group to manage which hooks should run automatically:
+The `hooks` command group provides shortcuts for managing project masks:
 
 ```bash
-# Enable or disable one or more hooks
-lemming hooks enable lint
-lemming hooks disable roadmap lint
+# Disable a hook for this project (writes an empty .lemming/hooks/50-lint.md)
+lemming hooks disable lint
 
-# Set the exact list of active hooks
-lemming hooks set roadmap lint
-
-# Reset to run all available hooks (default)
-lemming hooks reset
+# Re-enable it (removes the mask file)
+lemming hooks enable lint
 ```
 
-Changes to hook configuration are picked up dynamically by the running
-orchestrator loop. You can toggle hooks from the CLI or the Web UI while Lemming
-is running, and the next task execution will respect the updated settings.
+These commands validate the hook names before changing anything and refuse
+to touch files with content (a non-empty file is an override, not a mask).
+An empty file created by hand works just as well; the commands additionally
+keep the hook's priority in the mask filename so listings stay accurate.
+
+Hooks are re-discovered on every task execution, so changes are picked up
+dynamically by a running orchestrator loop.
 
 ### Available Variables
 
@@ -146,7 +149,8 @@ Your hook template can use the following placeholders:
 
 ### Listing Hooks
 
-You can see all available hooks (built-in and local) using the CLI:
+You can see all hooks in execution order, with their priority, source layer,
+and status (disabled, runs on failure) using the CLI:
 
 ```bash
 lemming hooks list

{lemming_cli-0.1.2 → lemming_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lemming-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "An autonomous, iterative task runner for AI coding agents."
 readme = "README.md"
 authors = [

lemming_cli-0.1.4/src/lemming/api/hooks.py

@@ -0,0 +1,57 @@
+"""API routes for listing and toggling orchestrator hooks."""
+
+import pathlib
+
+import fastapi
+import pydantic
+
+from .. import hooks
+from . import context
+
+router = fastapi.APIRouter()
+
+
+def _hook_payload(tasks_file: pathlib.Path) -> list[dict]:
+    """Serializes resolved hooks for API responses."""
+    return [
+        {
+            "name": h.name,
+            "priority": h.priority,
+            "source": h.source,
+            "masked": h.masked,
+            "runs_on_failure": h.priority >= hooks.FAILURE_HOOK_PRIORITY,
+        }
+        for h in hooks.resolve_hooks(tasks_file)
+    ]
+
+
+@router.get("/api/hooks")
+def list_hooks(request: fastapi.Request, project: str | None = None):
+    """List resolved orchestrator hooks in execution order."""
+    tasks_file = context.resolve_tasks_file(request.app.state, project)
+    return _hook_payload(tasks_file)
+
+
+class HookToggle(pydantic.BaseModel):
+    """Request body for enabling or disabling a hook."""
+
+    name: str
+    enabled: bool
+
+
+@router.post("/api/hooks")
+def toggle_hook(
+    request: fastapi.Request,
+    toggle: HookToggle,
+    project: str | None = None,
+):
+    """Enable or disable a hook by removing or creating its project mask."""
+    tasks_file = context.resolve_tasks_file(request.app.state, project)
+    try:
+        if toggle.enabled:
+            hooks.enable_hooks([toggle.name], tasks_file)
+        else:
+            hooks.disable_hooks([toggle.name], tasks_file)
+    except ValueError as e:
+        raise fastapi.HTTPException(status_code=400, detail=str(e))
+    return _hook_payload(tasks_file)

lemming_cli-0.1.4/src/lemming/api/hooks_test.py

@@ -0,0 +1,92 @@
+import lemming.api
+
+
+def test_list_hooks(client, test_tasks, monkeypatch, tmp_path):
+    """The /api/hooks endpoint returns resolved hooks in execution order."""
+    monkeypatch.setenv("LEMMING_HOME", str(tmp_path / "lemming_home"))
+
+    response = client.get("/api/hooks")
+
+    assert response.status_code == 200
+    payload = response.json()
+    hooks = {h["name"]: h for h in payload}
+    assert hooks["roadmap"]["priority"] == 90
+    assert hooks["roadmap"]["runs_on_failure"] is True
+    assert hooks["roadmap"]["masked"] is False
+    assert hooks["readability"]["source"] == "built-in"
+    assert hooks["readability"]["runs_on_failure"] is False
+
+    # Hooks are sorted by ascending priority
+    priorities = [h["priority"] for h in payload]
+    assert priorities == sorted(priorities)
+
+
+def test_list_hooks_with_project(client, test_tasks, monkeypatch, tmp_path):
+    """The /api/hooks endpoint works with a specified project."""
+    monkeypatch.setenv("LEMMING_HOME", str(tmp_path / "lemming_home"))
+    root = lemming.api.app.state.root
+    project_dir = root / "project1"
+    project_dir.mkdir()
+    tasks_file = project_dir / "tasks.yml"
+    tasks_file.touch()
+
+    response = client.get("/api/hooks", params={"project": "project1"})
+
+    assert response.status_code == 200
+    assert "roadmap" in {h["name"] for h in response.json()}
+
+
+def test_toggle_hook(client, test_tasks, monkeypatch, tmp_path):
+    """Disabling a hook creates a project mask; enabling removes it."""
+    monkeypatch.setenv("LEMMING_HOME", str(tmp_path / "lemming_home"))
+    # The mask filename keeps the hook's priority (roadmap is 90)
+    mask = test_tasks.parent / ".lemming" / "hooks" / "90-roadmap.md"
+
+    # Disable: the response reflects the mask and the file exists
+    response = client.post(
+        "/api/hooks", json={"name": "roadmap", "enabled": False}
+    )
+    assert response.status_code == 200
+    hooks = {h["name"]: h for h in response.json()}
+    assert hooks["roadmap"]["masked"] is True
+    assert mask.exists()
+    assert mask.read_text(encoding="utf-8") == ""
+
+    # Enable: the mask is removed
+    response = client.post(
+        "/api/hooks", json={"name": "roadmap", "enabled": True}
+    )
+    assert response.status_code == 200
+    hooks = {h["name"]: h for h in response.json()}
+    assert hooks["roadmap"]["masked"] is False
+    assert not mask.exists()
+
+
+def test_toggle_unknown_hook(client, test_tasks, monkeypatch, tmp_path):
+    """Toggling an unknown hook returns a 400 error."""
+    monkeypatch.setenv("LEMMING_HOME", str(tmp_path / "lemming_home"))
+
+    response = client.post(
+        "/api/hooks", json={"name": "does-not-exist", "enabled": False}
+    )
+
+    assert response.status_code == 400
+    assert "not found" in response.json()["detail"]
+
+
+def test_toggle_hook_refuses_project_override(
+    client, test_tasks, monkeypatch, tmp_path
+):
+    """Disabling a hook with a project override must not clobber it."""
+    monkeypatch.setenv("LEMMING_HOME", str(tmp_path / "lemming_home"))
+    local_hooks_dir = test_tasks.parent / ".lemming" / "hooks"
+    local_hooks_dir.mkdir(parents=True)
+    override = local_hooks_dir / "roadmap.md"
+    override.write_text("custom prompt", encoding="utf-8")
+
+    response = client.post(
+        "/api/hooks", json={"name": "roadmap", "enabled": False}
+    )
+
+    assert response.status_code == 400
+    assert override.read_text(encoding="utf-8") == "custom prompt"

{lemming_cli-0.1.2 → lemming_cli-0.1.4}/src/lemming/cli/config.py

@@ -2,7 +2,7 @@
 
 import click
 
-from .. import tasks
+from .. import hooks, tasks
 from ..orchestrator import format_duration, parse_timeout
 from .main import cli
 
@@ -25,9 +25,12 @@ def config_list(ctx: click.Context):
     click.echo(f"  Runner:        {c.runner}")
     click.echo(f"  Retries:       {c.retries}")
     click.echo(f"  Time limit:    {format_duration(c.time_limit)}")
+
+    # Hooks are discovered from the filesystem, not stored in config
+    active_hooks = hooks.list_hooks(tasks_file)
     click.echo(
         "  Hooks:         "
-        f"{', '.join(c.hooks) if c.hooks is not None else '(all)'}"
+        f"{', '.join(active_hooks) if active_hooks else '(none)'}"
     )
 
 

{lemming_cli-0.1.2 → lemming_cli-0.1.4}/src/lemming/cli/config_test.py

@@ -35,6 +35,9 @@ class TestCLIConfig(unittest.TestCase):
         )
         self.assertEqual(result.exit_code, 0)
         self.assertIn("Runner:", result.output)
+        # Active hooks are discovered from the filesystem and displayed
+        self.assertIn("Hooks:", result.output)
+        self.assertIn("roadmap", result.output)
 
     def test_config_set(self):
         result = self.cli_runner.invoke(

lemming_cli-0.1.4/src/lemming/cli/hooks.py

@@ -0,0 +1,85 @@
+"""CLI commands for managing orchestrator hooks."""
+
+import click
+
+from .. import hooks
+from .main import cli
+
+
+@cli.group(name="hooks", short_help="Manage orchestrator hooks")
+def hooks_group():
+    """Manages orchestrator hooks.
+
+    Hooks are Markdown prompt files discovered from the project
+    (.lemming/hooks/), global (~/.local/lemming/hooks/), and built-in
+    layers, with the project layer taking precedence. A numeric filename
+    prefix (e.g. 90-roadmap.md) sets the execution order; hooks at 90 and
+    above also run when a task fails. An empty file disables (masks) the
+    hook of the same name.
+    """
+    pass
+
+
+@hooks_group.command(name="list")
+@click.pass_context
+def hooks_list(ctx: click.Context):
+    """Lists hooks in execution order with source and status."""
+    tasks_file = ctx.obj["TASKS_FILE"]
+
+    click.secho("Orchestrator hooks (in execution order):", bold=True)
+    for hook in hooks.resolve_hooks(tasks_file):
+        notes = []
+        if hook.priority >= hooks.FAILURE_HOOK_PRIORITY:
+            notes.append("runs on failure")
+        if hook.masked:
+            notes.append("disabled")
+        suffix = f" ({', '.join(notes)})" if notes else ""
+        click.echo(
+            f"  {hook.priority:>3}  {hook.name:20} {hook.source}{suffix}"
+        )
+
+
+@hooks_group.command(name="disable")
+@click.argument("names", nargs=-1, required=True)
+@click.pass_context
+def hooks_disable(ctx: click.Context, names: tuple[str, ...]):
+    """Disables hooks for this project.
+
+    Writes an empty mask file to .lemming/hooks/, which shadows the hook of
+    the same name. An empty file created by hand works just as well; the
+    command additionally validates the names and keeps the hook's priority
+    in the mask filename so listings stay accurate.
+    """
+    tasks_file = ctx.obj["TASKS_FILE"]
+
+    try:
+        results = hooks.disable_hooks(list(names), tasks_file)
+    except ValueError as e:
+        click.echo(f"Error: {e}")
+        ctx.exit(1)
+
+    for name, mask in results.items():
+        if mask is None:
+            click.echo(f"Hook '{name}' is already disabled.")
+        else:
+            click.echo(f"Disabled hook: {name} (masked by {mask})")
+
+
+@hooks_group.command(name="enable")
+@click.argument("names", nargs=-1, required=True)
+@click.pass_context
+def hooks_enable(ctx: click.Context, names: tuple[str, ...]):
+    """Re-enables hooks by removing their project mask files."""
+    tasks_file = ctx.obj["TASKS_FILE"]
+
+    try:
+        results = hooks.enable_hooks(list(names), tasks_file)
+    except ValueError as e:
+        click.echo(f"Error: {e}")
+        ctx.exit(1)
+
+    for name, removed in results.items():
+        if removed:
+            click.echo(f"Enabled hook: {name}")
+        else:
+            click.echo(f"Hook '{name}' is already enabled.")