Fixes CLI docs tests and deployment to use single JSONL lists file.

Author: aaronstevenwhite

bead/cli/deployment.py

@@ -41,7 +41,7 @@ def deployment() -> None:
 
     \b
     Examples:
-        $ bead deployment generate lists/ items.jsonl experiment/
+        $ bead deployment generate lists.jsonl items.jsonl experiment/
         $ bead deployment export-jatos experiment/ study.jzip \\
             --title "My Study"
         $ bead deployment upload-jatos study.jzip \\
@@ -52,9 +52,9 @@ def deployment() -> None:
 
 @click.command()
 @click.argument(
-    "lists_dir", type=click.Path(exists=True, file_okay=False, path_type=Path)
+    "lists_file", type=click.Path(exists=True, dir_okay=False, path_type=Path)
 )
-@click.argument("items_file", type=click.Path(exists=True, path_type=Path))
+@click.argument("items_file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.argument("output_dir", type=click.Path(path_type=Path))
 @click.option(
     "--experiment-type",
@@ -128,7 +128,7 @@ def deployment() -> None:
 @click.pass_context
 def generate(
     ctx: click.Context,
-    lists_dir: Path,
+    lists_file: Path,
     items_file: Path,
     output_dir: Path,
     experiment_type: str,
@@ -148,10 +148,10 @@ def generate(
     ----------
     ctx : click.Context
         Click context object.
-    lists_dir : Path
-        Directory containing experiment list files.
+    lists_file : Path
+        JSONL file containing experiment lists (one list per line).
     items_file : Path
-        Path to items file.
+        JSONL file containing items (one item per line).
     output_dir : Path
         Output directory for generated experiment.
     experiment_type : str
@@ -178,25 +178,25 @@ def generate(
     Examples
     --------
     # Basic balanced distribution
-    $ bead deployment generate lists/ items.jsonl experiment/ \\
+    $ bead deployment generate lists.jsonl items.jsonl experiment/ \\
         --experiment-type forced_choice \\
         --title "Acceptability Study" \\
         --distribution-strategy balanced
 
     # Quota-based with config
-    $ bead deployment generate lists/ items.jsonl experiment/ \\
+    $ bead deployment generate lists.jsonl items.jsonl experiment/ \\
         --experiment-type forced_choice \\
         --distribution-strategy quota_based \\
         --distribution-config '{"participants_per_list": 25, "allow_overflow": false}'
 
     # Stratified by factors
-    $ bead deployment generate lists/ items.jsonl experiment/ \\
+    $ bead deployment generate lists.jsonl items.jsonl experiment/ \\
         --experiment-type forced_choice \\
         --distribution-strategy stratified \\
         --distribution-config '{"factors": ["condition", "verb_type"]}'
 
     # Dry run to preview
-    $ bead deployment generate lists/ items.jsonl experiment/ \\
+    $ bead deployment generate lists.jsonl items.jsonl experiment/ \\
         --experiment-type forced_choice \\
         --distribution-strategy balanced \\
         --dry-run
@@ -227,21 +227,21 @@ def generate(
         except ValueError as e:
             print_error(f"Invalid distribution strategy configuration: {e}")
             ctx.exit(1)
-        # Load experiment lists
-        print_info(f"Loading experiment lists from {lists_dir}")
-        list_files = list(lists_dir.glob("*.jsonl"))
-        if not list_files:
-            print_error(f"No list files found in {lists_dir}")
-            ctx.exit(1)
-
+        # Load experiment lists from JSONL file (one list per line)
+        print_info(f"Loading experiment lists from {lists_file}")
         experiment_lists: list[ExperimentList] = []
-        for list_file in list_files:
-            with open(list_file, encoding="utf-8") as f:
-                first_line = f.readline().strip()
-                if first_line:
-                    list_data = json.loads(first_line)
-                    exp_list = ExperimentList(**list_data)
-                    experiment_lists.append(exp_list)
+        with open(lists_file, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                list_data = json.loads(line)
+                exp_list = ExperimentList(**list_data)
+                experiment_lists.append(exp_list)
+
+        if not experiment_lists:
+            print_error(f"No lists found in {lists_file}")
+            ctx.exit(1)
 
         print_info(f"Loaded {len(experiment_lists)} experiment lists")
 

bead/cli/main.py

@@ -368,31 +368,64 @@ def _generate_gitignore() -> str:
 """
 
 
-# Import command groups
-from bead.cli.active_learning import active_learning  # noqa: E402
-from bead.cli.completion import completion  # noqa: E402
-from bead.cli.config import config  # noqa: E402
-from bead.cli.deployment import deployment  # noqa: E402
-from bead.cli.items import items  # noqa: E402
-from bead.cli.lists import lists  # noqa: E402
-from bead.cli.models import models  # noqa: E402
-from bead.cli.resources import resources  # noqa: E402
-from bead.cli.shell import shell  # noqa: E402
-from bead.cli.simulate import simulate  # noqa: E402
-from bead.cli.templates import templates  # noqa: E402
-from bead.cli.training import training  # noqa: E402
-from bead.cli.workflow import workflow  # noqa: E402
-
-cli.add_command(active_learning)
-cli.add_command(completion)
-cli.add_command(config)
-cli.add_command(resources)
-cli.add_command(templates)
-cli.add_command(items)
-cli.add_command(lists)
-cli.add_command(deployment)
-cli.add_command(models)
-cli.add_command(simulate)
-cli.add_command(shell)
-cli.add_command(training)
-cli.add_command(workflow)
+# Lazy command loading for fast startup
+# Each command group is only imported when actually invoked
+
+
+class LazyGroup(click.Group):
+    """Click group that lazily loads subcommands."""
+
+    def __init__(
+        self,
+        name: str | None = None,
+        lazy_subcommands: dict[str, tuple[str, str]] | None = None,
+        **kwargs: object,
+    ) -> None:
+        super().__init__(name=name, **kwargs)
+        self._lazy_subcommands: dict[str, tuple[str, str]] = lazy_subcommands or {}
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        """List all available commands."""
+        base = super().list_commands(ctx)
+        lazy = list(self._lazy_subcommands.keys())
+        return sorted(base + lazy)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        """Get a command, loading it lazily if needed."""
+        if cmd_name in self._lazy_subcommands:
+            return self._lazy_load(cmd_name)
+        return super().get_command(ctx, cmd_name)
+
+    def _lazy_load(self, cmd_name: str) -> click.Command:
+        """Import and return a lazy command."""
+        import importlib
+
+        module_path, attr_name = self._lazy_subcommands[cmd_name]
+        module = importlib.import_module(module_path)
+        return getattr(module, attr_name)  # type: ignore[no-any-return]
+
+
+# Replace cli group with lazy version
+cli = LazyGroup(
+    name="bead",
+    help=cli.help,
+    params=cli.params,
+    callback=cli.callback,
+    lazy_subcommands={
+        "active-learning": ("bead.cli.active_learning", "active_learning"),
+        "completion": ("bead.cli.completion", "completion"),
+        "config": ("bead.cli.config", "config"),
+        "deployment": ("bead.cli.deployment", "deployment"),
+        "items": ("bead.cli.items", "items"),
+        "lists": ("bead.cli.lists", "lists"),
+        "models": ("bead.cli.models", "models"),
+        "resources": ("bead.cli.resources", "resources"),
+        "shell": ("bead.cli.shell", "shell"),
+        "simulate": ("bead.cli.simulate", "simulate"),
+        "templates": ("bead.cli.templates", "templates"),
+        "training": ("bead.cli.training", "training"),
+        "workflow": ("bead.cli.workflow", "workflow"),
+    },
+)
+# Re-add the init command which is defined above
+cli.add_command(init)

bead/cli/utils.py

@@ -22,9 +22,15 @@
 if TYPE_CHECKING:
     from bead.config import BeadConfig
 
-from bead.config import load_config
 from bead.data.base import JsonValue
 
+
+def _load_config() -> "type":
+    """Lazily import load_config to avoid slow startup."""
+    from bead.config import load_config
+
+    return load_config
+
 console = Console()
 
 
@@ -59,6 +65,7 @@ def load_config_for_cli(
     config_path = Path(config_file) if config_file else None
 
     try:
+        load_config = _load_config()
         config = load_config(config_path=config_path, profile=profile)
 
         if verbose:

docs/user-guide/cli/conftest.py

@@ -2,10 +2,14 @@
 
 This conftest.py sets up the environment for testing bash code blocks
 in CLI documentation using pytest-codeblocks.
+
+The fixtures are copied to a temporary directory to avoid modifying
+the committed fixture files.
 """
 
 import os
 import shutil
+import tempfile
 from pathlib import Path
 
 import pytest
@@ -14,26 +18,19 @@
 DOCS_CLI_DIR = Path(__file__).parent
 PROJECT_ROOT = DOCS_CLI_DIR.parent.parent.parent
 FIXTURES_SRC = PROJECT_ROOT / "tests" / "fixtures" / "api_docs"
-FIXTURES_WORK = PROJECT_ROOT / "tests" / "fixtures" / "cli_work"
 
+# Global temp directory for the test session
+_temp_dir: Path | None = None
 
-def pytest_configure(config: pytest.Config) -> None:
-    """Set up environment before test collection.
 
-    This hook runs before test collection starts. We set up the fixtures
-    directory but do NOT change the cwd yet, as that would break collection.
-    """
-    # Create working directory and copy fixtures
-    FIXTURES_WORK.mkdir(parents=True, exist_ok=True)
+def pytest_configure(config: pytest.Config) -> None:
+    """Set up temporary fixtures directory before test collection."""
+    global _temp_dir
+    _temp_dir = Path(tempfile.mkdtemp(prefix="bead_cli_test_"))
 
+    # Copy fixtures to temp directory
     for item in FIXTURES_SRC.iterdir():
-        dest = FIXTURES_WORK / item.name
-        if dest.exists():
-            if dest.is_dir():
-                shutil.rmtree(dest)
-            else:
-                dest.unlink()
-
+        dest = _temp_dir / item.name
         if item.is_dir():
             shutil.copytree(item, dest)
         else:
@@ -47,11 +44,14 @@ def pytest_runtest_setup(item: pytest.Item) -> None:
     This hook runs just before each test executes. We change the cwd here
     so that bash commands in the markdown files can find the fixture files.
     """
+    if _temp_dir is None:
+        return
+
     # Store original directory on the item for restoration
     item._original_cwd = os.getcwd()  # type: ignore[attr-defined]
 
-    # Change to fixtures directory
-    os.chdir(FIXTURES_WORK)
+    # Change to temp fixtures directory
+    os.chdir(_temp_dir)
 
     # Add .venv/bin to PATH for bead CLI
     venv_bin = PROJECT_ROOT / ".venv" / "bin"
@@ -72,6 +72,8 @@ def pytest_runtest_teardown(item: pytest.Item) -> None:
 
 
 def pytest_unconfigure(config: pytest.Config) -> None:
-    """Clean up fixtures directory after all tests complete."""
-    if FIXTURES_WORK.exists():
-        shutil.rmtree(FIXTURES_WORK, ignore_errors=True)
+    """Clean up temporary fixtures directory after all tests complete."""
+    global _temp_dir
+    if _temp_dir is not None and _temp_dir.exists():
+        shutil.rmtree(_temp_dir, ignore_errors=True)
+        _temp_dir = None