lemming-cli 0.1.0__py3-none-any.whl

lemming/cli/config.py

@@ -0,0 +1,67 @@
+"""CLI commands for managing project configuration."""
+
+import click
+
+from .. import tasks
+from ..orchestrator import format_duration, parse_timeout
+from .main import cli
+
+
+@cli.group(name="config", short_help="Manage project configuration")
+def config_group():
+    """Manages the configuration for the roadmap execution loop."""
+    pass
+
+
+@config_group.command(name="list")
+@click.pass_context
+def config_list(ctx: click.Context):
+    """Shows the current project configuration."""
+    tasks_file = ctx.obj["TASKS_FILE"]
+    data = tasks.load_tasks(tasks_file)
+    c = data.config
+
+    click.secho(f"Configuration for {tasks_file}:", bold=True)
+    click.echo(f"  Runner:        {c.runner}")
+    click.echo(f"  Retries:       {c.retries}")
+    click.echo(f"  Time limit:    {format_duration(c.time_limit)}")
+    click.echo(
+        "  Hooks:         "
+        f"{', '.join(c.hooks) if c.hooks is not None else '(all)'}"
+    )
+
+
+@config_group.command(name="set")
+@click.argument(
+    "key",
+    type=click.Choice(["runner", "retries", "time_limit"]),
+)
+@click.argument("value")
+@click.pass_context
+def config_set(ctx: click.Context, key: str, value: str):
+    """Sets a configuration value.
+
+    Examples:
+      lemming config set runner aider
+      lemming config set retries 5
+      lemming config set time_limit 30m
+    """
+    tasks_file = ctx.obj["TASKS_FILE"]
+    data = tasks.load_tasks(tasks_file)
+
+    if key == "runner":
+        data.config.runner = value
+    elif key == "retries":
+        try:
+            data.config.retries = int(value)
+        except ValueError:
+            raise click.UsageError(f"Value for {key} must be an integer.")
+    elif key == "time_limit":
+        if value.lower() == "none":
+            data.config.time_limit = 0
+        else:
+            seconds = parse_timeout(value)
+            data.config.time_limit = int(seconds // 60)
+
+    tasks.save_tasks(tasks_file, data)
+    click.echo(f"Updated {key} to {value}")

lemming/cli/config_test.py

@@ -0,0 +1,50 @@
+import pathlib
+import shutil
+import tempfile
+import unittest
+
+import click.testing
+
+from lemming import cli, tasks
+
+
+class TestCLIConfig(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 = [
+            "--verbose",
+            "--tasks-file",
+            str(self.test_tasks_file),
+        ]
+
+        # Scaffold a valid file
+        data = tasks.Roadmap(
+            context="Initial context",
+            tasks=[],
+        )
+        tasks.save_tasks(self.test_tasks_file, data)
+
+    def tearDown(self):
+        shutil.rmtree(self.test_dir)
+
+    def test_config_list(self):
+        result = self.cli_runner.invoke(
+            cli.cli, self.base_args + ["config", "list"]
+        )
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Runner:", result.output)
+
+    def test_config_set(self):
+        result = self.cli_runner.invoke(
+            cli.cli, self.base_args + ["config", "set", "runner", "new-runner"]
+        )
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Updated runner to new-runner", result.output)
+        data = tasks.load_tasks(self.test_tasks_file)
+        self.assertEqual(data.config.runner, "new-runner")
+
+
+if __name__ == "__main__":
+    unittest.main()

lemming/cli/context.py

@@ -0,0 +1,40 @@
+"""CLI command for viewing or setting the project context."""
+
+import pathlib
+
+import click
+
+from .. import tasks
+from .main import cli
+
+
+@cli.command(short_help="[<text>] View or set the project context")
+@click.argument("context_text", required=False)
+@click.option(
+    "--file",
+    "-f",
+    type=click.Path(exists=True, path_type=pathlib.Path),
+    help="Read context from a file.",
+)
+@click.pass_context
+def context(
+    ctx: click.Context, context_text: str | None, file: pathlib.Path | None
+):
+    """Sets or displays the global project-wide context and rules.
+
+    Args:
+        ctx: The click context holding shared CLI state.
+        context_text: The context string to set (optional).
+        file: A file path to read the context from (optional).
+    """
+    tasks_file = ctx.obj["TASKS_FILE"]
+
+    if file:
+        tasks.update_context(tasks_file, file.read_text(encoding="utf-8"))
+        click.echo("Project context updated.")
+    elif context_text:
+        tasks.update_context(tasks_file, context_text)
+        click.echo("Project context updated.")
+    else:
+        data = tasks.load_tasks(tasks_file)
+        click.echo(data.context or "No context set.")

lemming/cli/context_test.py

@@ -0,0 +1,49 @@
+import pathlib
+import shutil
+import tempfile
+import unittest
+
+import click.testing
+
+from lemming import cli, tasks
+
+
+class TestCLIContext(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 = [
+            "--verbose",
+            "--tasks-file",
+            str(self.test_tasks_file),
+        ]
+
+        # Scaffold a valid file
+        data = tasks.Roadmap(
+            context="Initial context",
+            tasks=[],
+        )
+        tasks.save_tasks(self.test_tasks_file, data)
+
+    def tearDown(self):
+        shutil.rmtree(self.test_dir)
+
+    def test_context_no_args(self):
+        result = self.cli_runner.invoke(cli.cli, self.base_args + ["context"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Initial context", result.output)
+
+    def test_set_context(self):
+        result = self.cli_runner.invoke(
+            cli.cli, self.base_args + ["context", "Updated context via CLI"]
+        )
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Project context updated.", result.output)
+
+        data = tasks.load_tasks(self.test_tasks_file)
+        self.assertEqual(data.context, "Updated context via CLI")
+
+
+if __name__ == "__main__":
+    unittest.main()

lemming/cli/hooks.py

@@ -0,0 +1,147 @@
+"""CLI commands for managing orchestrator hooks."""
+
+import click
+
+from .. import prompts, tasks
+from .main import cli
+
+
+@cli.group(name="hooks", short_help="Manage orchestrator hooks")
+def hooks_group():
+    """Manages orchestrator hooks."""
+    pass
+
+
+@hooks_group.command(name="list")
+@click.pass_context
+def hooks_list(ctx: click.Context):
+    """Lists available orchestrator hooks."""
+    tasks_file = ctx.obj["TASKS_FILE"]
+    available = prompts.list_hooks(tasks_file)
+
+    data = tasks.load_tasks(tasks_file)
+    active = (
+        set(data.config.hooks)
+        if data.config.hooks is not None
+        else set(available)
+    )
+
+    click.secho("Available orchestrator hooks:", bold=True)
+    for h in available:
+        status = "[active]" if h in active else ""
+        click.echo(f"  - {h:20} {status}")
+
+
+@hooks_group.command(name="enable")
+@click.argument("names", nargs=-1, required=True)
+@click.pass_context
+def hooks_enable(ctx: click.Context, names: tuple[str, ...]):
+    """Enables one or more orchestrator hooks."""
+    tasks_file = ctx.obj["TASKS_FILE"]
+    available = prompts.list_hooks(tasks_file)
+
+    data = tasks.load_tasks(tasks_file)
+    for name in names:
+        if name not in available:
+            click.echo(f"Error: Hook '{name}' not found.")
+            ctx.exit(1)
+
+        if data.config.hooks is None:
+            # If currently "all", it's already enabled. We don't transition
+            # to an explicit list here to keep the default behavior.
+            click.echo(
+                f"Hook '{name}' is already active "
+                "(all available hooks are enabled)."
+            )
+            continue
+
+        if name not in data.config.hooks:
+            data.config.hooks.append(name)
+            click.echo(f"Enabled hook: {name}")
+        else:
+            click.echo(f"Hook '{name}' is already enabled.")
+
+    tasks.save_tasks(tasks_file, data)
+
+
+@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 one or more orchestrator hooks."""
+    tasks_file = ctx.obj["TASKS_FILE"]
+    available = prompts.list_hooks(tasks_file)
+
+    data = tasks.load_tasks(tasks_file)
+    for name in names:
+        if name not in available:
+            click.echo(f"Error: Hook '{name}' not found.")
+            ctx.exit(1)
+
+        if data.config.hooks is None:
+            # If currently "all", we transition to an explicit list minus
+            # the disabled one
+            data.config.hooks = [h for h in available if h != name]
+        else:
+            data.config.hooks = [h for h in data.config.hooks if h != name]
+
+        click.echo(f"Disabled hook: {name}")
+
+    tasks.save_tasks(tasks_file, data)
+
+
+@hooks_group.command(name="set")
+@click.argument("names", nargs=-1)
+@click.pass_context
+def hooks_set(ctx: click.Context, names: tuple[str, ...]):
+    """Sets the specific list of active orchestrator hooks.
+
+    Provide a space-separated list of hook names. If no names are provided,
+    all hooks will be disabled.
+
+    Examples:
+      lemming hooks set roadmap lint
+      lemming hooks set roadmap
+      lemming hooks set  # Disables all hooks
+    """
+    tasks_file = ctx.obj["TASKS_FILE"]
+    available = prompts.list_hooks(tasks_file)
+
+    data = tasks.load_tasks(tasks_file)
+    new_hooks = []
+    for name in names:
+        if name not in available:
+            click.echo(f"Error: Hook '{name}' not found.")
+            ctx.exit(1)
+        new_hooks.append(name)
+
+    data.config.hooks = new_hooks
+    tasks.save_tasks(tasks_file, data)
+
+    if not new_hooks:
+        click.echo("All hooks disabled.")
+    else:
+        click.echo(f"Active hooks set to: {', '.join(new_hooks)}")
+
+
+@hooks_group.command(name="reset")
+@click.pass_context
+def hooks_reset(ctx: click.Context):
+    """Resets hooks to run all available hooks by default."""
+    tasks_file = ctx.obj["TASKS_FILE"]
+    data = tasks.load_tasks(tasks_file)
+    data.config.hooks = None
+    tasks.save_tasks(tasks_file, data)
+    click.echo("Hooks reset to default (all available).")
+
+
+@hooks_group.command(name="install")
+@click.pass_context
+def hooks_install(ctx: click.Context):
+    """Installs (symlinks) built-in hooks into the global hooks directory.
+
+    This makes them easily discoverable and overridable in
+    ~/.local/lemming/hooks/.
+    """
+    prompts.ensure_hooks_symlinked()
+    click.echo("Built-in hooks installed to ~/.local/lemming/hooks/")

lemming/cli/hooks_test.py

@@ -0,0 +1,50 @@
+import pathlib
+import shutil
+import tempfile
+import unittest
+
+import click.testing
+
+from lemming import cli, tasks
+
+
+class TestCLIHooks(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 = [
+            "--verbose",
+            "--tasks-file",
+            str(self.test_tasks_file),
+        ]
+
+        # Scaffold a valid file
+        data = tasks.Roadmap(
+            context="Initial context",
+            tasks=[],
+        )
+        tasks.save_tasks(self.test_tasks_file, data)
+
+    def tearDown(self):
+        shutil.rmtree(self.test_dir)
+
+    def test_hooks_list(self):
+        result = self.cli_runner.invoke(
+            cli.cli, self.base_args + ["hooks", "list"]
+        )
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Available orchestrator hooks:", result.output)
+
+    def test_hooks_reset(self):
+        result = self.cli_runner.invoke(
+            cli.cli, self.base_args + ["hooks", "reset"]
+        )
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("Hooks reset to default", result.output)
+        data = tasks.load_tasks(self.test_tasks_file)
+        self.assertIsNone(data.config.hooks)
+
+
+if __name__ == "__main__":
+    unittest.main()

lemming/cli/main.py

@@ -0,0 +1,42 @@
+"""Top-level click group and shared options for the Lemming CLI."""
+
+import pathlib
+
+import click
+
+from .. import paths
+
+
+@click.group()
+@click.option(
+    "--tasks-file",
+    type=click.Path(path_type=pathlib.Path),
+    help=(
+        "Path to the tasks file (defaults to ./tasks.yml or "
+        "project-isolated tasks in ~/.local/lemming/<hash>/)."
+    ),
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show verbose output.",
+)
+@click.pass_context
+def cli(ctx: click.Context, tasks_file: pathlib.Path | None, verbose: bool):
+    """Lemming: An autonomous, iterative task runner for AI agents.
+
+    Lemming orchestrates AI coding agents by walking through a structured
+    `tasks.yml` file. It manages the context, tracks task attempts, and
+    records progress.
+    """
+    ctx.ensure_object(dict)
+    if tasks_file is None:
+        tasks_file = paths.get_default_tasks_file()
+    tasks_file = tasks_file.resolve()
+
+    # Load .env files (global, then project-level); real env vars always win.
+    paths.load_dotenv(project_dir=paths.get_working_dir(tasks_file))
+
+    ctx.obj["TASKS_FILE"] = tasks_file
+    ctx.obj["VERBOSE"] = verbose

lemming/cli/main_test.py

@@ -0,0 +1,21 @@
+import unittest
+
+import click.testing
+
+from lemming.cli.main import cli
+
+
+class TestCLIMain(unittest.TestCase):
+    def setUp(self):
+        self.cli_runner = click.testing.CliRunner()
+
+    def test_cli_help(self):
+        result = self.cli_runner.invoke(cli, ["--help"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn(
+            "Lemming: An autonomous, iterative task runner", result.output
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

lemming/cli/operations.py

@@ -0,0 +1,226 @@
+"""CLI commands for the orchestrator loop and the web interface."""
+
+import copy
+import os
+import pathlib
+import secrets
+import sys
+import threading
+import time
+
+import click
+
+from .. import paths, providers, tasks
+from ..orchestrator import parse_timeout, run_loop
+from .main import cli
+
+
+@cli.command(
+    short_help="Run the autonomous task execution loop",
+)
+@click.option(
+    "--retry-delay",
+    default=10,
+    help=(
+        "Seconds to wait before retrying a failed task (to handle rate limits)."
+    ),
+)
+@click.option(
+    "--yolo/--no-yolo",
+    default=True,
+    help="Run the runner in YOLO/auto-approve mode.",
+)
+@click.option(
+    "--env",
+    multiple=True,
+    help="Environment variables to set for the runner (e.g. --env KEY=VALUE).",
+)
+@click.option(
+    "--no-defaults",
+    is_flag=True,
+    help="Do not auto-inject default flags (like --yolo) based on runner name.",
+)
+@click.argument("runner_args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def run(
+    ctx: click.Context,
+    retry_delay: int,
+    yolo: bool,
+    env: tuple,
+    no_defaults: bool,
+    runner_args: tuple,
+) -> None:
+    """Starts the orchestrator loop to autonomously execute pending tasks.
+
+    Args:
+        ctx: The click context.
+        retry_delay: Delay between retries.
+        yolo: If True, skip runner confirmations.
+        env: Environment variables to inject.
+        no_defaults: Skip default flag injection.
+        runner_args: Raw arguments passed directly to the runner.
+    """
+    tasks_file = ctx.obj["TASKS_FILE"]
+    verbose = ctx.obj["VERBOSE"]
+
+    # Determine the project's working directory
+    working_dir = paths.get_working_dir(tasks_file)
+
+    # Parse environment overrides
+    env_overrides = {}
+    for e in env:
+        if "=" in e:
+            k, v = e.split("=", 1)
+            env_overrides[k] = v
+        else:
+            env_overrides[e] = ""
+
+    if env_overrides:
+        os.environ.update(env_overrides)
+
+    tasks.acquire_loop_lock(tasks_file)
+    try:
+        run_loop(
+            tasks_file,
+            verbose,
+            retry_delay,
+            yolo,
+            no_defaults,
+            runner_args,
+            working_dir=working_dir,
+        )
+    finally:
+        tasks.release_loop_lock(tasks_file)
+
+
+@cli.command(short_help="Launch the web interface")
+@click.option("--port", default=8999, help="Port to run the server on.")
+@click.option("--host", default="127.0.0.1", help="Host to bind the server to.")
+@click.option(
+    "--tunnel",
+    default=None,
+    type=click.Choice(["cloudflare", "tailscale"]),
+    help="Expose via a public tunnel (cloudflare or tailscale).",
+)
+@click.option(
+    "--timeout",
+    default=None,
+    help=(
+        "Auto-shutdown after duration (e.g., '8h', '30m', '0' to disable)."
+        " Defaults to '8h' when --tunnel is used."
+    ),
+)
+@click.pass_context
+def serve(
+    ctx: click.Context,
+    port: int,
+    host: str,
+    tunnel: str | None,
+    timeout: str | None,
+):
+    """Launches the local web dashboard for monitoring and interaction.
+
+    Optionally exposes it to the public internet via --tunnel.
+    """
+    # Lazy imports: the api package builds the FastAPI app and mounts static
+    # assets at import time, so keep the server stack out of CLI startup.
+    import uvicorn  # noqa: PLC0415
+    import uvicorn.config  # noqa: PLC0415
+
+    from .. import api  # noqa: PLC0415
+
+    api.app.state.tasks_file = ctx.obj["TASKS_FILE"]
+    api.app.state.verbose = ctx.obj["VERBOSE"]
+    api.app.state.root = pathlib.Path.cwd().resolve()
+
+    tunnel_proc = None
+    if tunnel:
+        click.echo(f"[ Lemming ] Starting local server on port {port}...")
+        click.echo(
+            f"[ Lemming ] Initiating public tunnel via {tunnel.capitalize()}..."
+        )
+
+        tunnel_proc = (
+            providers.CloudflareProvider()
+            if tunnel == "cloudflare"
+            else providers.TailscaleProvider()
+        )
+        try:
+            public_url = tunnel_proc.start(port)
+        except Exception as e:
+            click.echo(f"[ Lemming ] Error starting tunnel: {e}", err=True)
+            sys.exit(1)
+
+        token = secrets.token_urlsafe(32)
+        api.app.state.share_token = token
+
+        click.echo("[ Lemming ] ")
+        click.echo("[ Lemming ] ⚠️  SECURITY WARNING ")
+        click.echo(
+            "[ Lemming ] Your Lemming instance is being exposed to the"
+            " public internet."
+        )
+        click.echo(
+            "[ Lemming ] Token-based authentication has been automatically"
+            " enabled."
+        )
+        click.echo("[ Lemming ] ")
+        click.echo(
+            "[ Lemming ] 🌐 Share this exact, secure link with the remote user:"
+        )
+        click.echo(f"[ Lemming ] 👉 {public_url}?token={token}")
+        click.echo("")
+    else:
+        click.echo(f"Launching Lemming UI at http://{host}:{port}")
+
+    # Default timeout to 8h for tunnel mode, 0 (disabled) for local mode.
+    timeout_str = timeout if timeout is not None else ("8h" if tunnel else "0")
+    timeout_seconds = parse_timeout(timeout_str)
+
+    if timeout_seconds > 0:
+        click.echo(
+            "[ Lemming ] The server will automatically shut down"
+            f" in {timeout_str}."
+        )
+
+        def monitor():
+            time.sleep(timeout_seconds)
+            click.echo(
+                "\n[ Lemming ] Timeout reached. Waiting for tasks to finish..."
+            )
+            if tunnel_proc:
+                tunnel_proc.stop()
+
+            tasks_file = api.app.state.tasks_file
+            while True:
+                project_data = tasks.get_project_data(tasks_file)
+                if not project_data.loop_running:
+                    break
+                time.sleep(5)
+
+            click.echo("[ Lemming ] All tasks finished. Exiting.")
+            os._exit(0)
+
+        monitor_thread = threading.Thread(target=monitor, daemon=True)
+        monitor_thread.start()
+
+    if tunnel:
+        click.echo(
+            "[ Lemming ] Press Ctrl+C to manually close the tunnel and"
+            " shut down the server."
+        )
+
+    # Suppress repetitive access-log lines from UI polling endpoints.
+    log_config = copy.deepcopy(uvicorn.config.LOGGING_CONFIG)
+    log_config["filters"] = {
+        "quiet_poll": {"()": "lemming.api.QuietPollFilter"},
+    }
+    log_config["handlers"]["access"]["filters"] = ["quiet_poll"]
+
+    try:
+        uvicorn.run(api.app, host=host, port=port, log_config=log_config)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        if tunnel_proc:
+            tunnel_proc.stop()