feat: allow passing pre-populated registry and executor to create_cli to bypass filesystem discovery

Author: tercel

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.5.1] - 2026-04-03
+
+### Added
+- **Pre-populated registry support** — `create_cli()` accepts optional `registry` and `executor` parameters. When a pre-populated `Registry` is provided, filesystem discovery is skipped entirely. This enables frameworks that register modules at runtime (e.g. apflow's bridge) to generate CLI commands from their existing registry without requiring an extensions directory.
+- Passing `registry` alone auto-builds an `Executor`; passing `executor` without `registry` raises `ValueError`.
+
+---
+
 ## [0.4.1] - 2026-03-30
 
 ### Fixed

README.md

@@ -92,14 +92,29 @@ All modules are auto-discovered. CLI flags are auto-generated from each module's
 ### Programmatic approach (Python API)
 
 ```python
-from apcore import Registry, Executor
-from apcore_cli.__main__ import create_cli
+from apcore_cli import create_cli
 
-# Build the CLI from your registry
+# Build the CLI from an extensions directory (auto-discovers modules)
 cli = create_cli(extensions_dir="./extensions")
 cli(standalone_mode=True)
 ```
 
+#### Pre-populated registry
+
+Frameworks that register modules at runtime (e.g. apflow's bridge) can pass a pre-populated `Registry` directly, skipping filesystem discovery entirely:
+
+```python
+from apcore_cli import create_cli
+
+# registry is already populated by your framework
+cli = create_cli(registry=registry, prog_name="myapp")
+cli(standalone_mode=True)
+
+# Executor is auto-built from the registry if omitted.
+# You can also provide your own:
+cli = create_cli(registry=registry, executor=executor, prog_name="myapp")
+```
+
 Or use the `LazyModuleGroup` directly with Click:
 
 ```python

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.5.0"
+version = "0.5.1"
 description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
 readme = "README.md"
 license = "Apache-2.0"

src/apcore_cli/__init__.py

@@ -25,3 +25,8 @@
     )
 except (ImportError, AttributeError):
     pass  # apcore < 0.15.0 or not installed
+
+# Public API re-exports
+from apcore_cli.__main__ import create_cli
+
+__all__ = ["__version__", "create_cli"]

src/apcore_cli/__main__.py

@@ -5,6 +5,7 @@
 import logging
 import os
 import sys
+from typing import Any
 
 import click
 
@@ -61,6 +62,8 @@ def create_cli(
     prog_name: str | None = None,
     commands_dir: str | None = None,
     binding_path: str | None = None,
+    registry: Any | None = None,
+    executor: Any | None = None,
 ) -> click.Group:
     """Create the CLI application.
 
@@ -77,6 +80,12 @@ def create_cli(
         binding_path: Path to binding.yaml file or directory for display resolution.
                       When set, applies DisplayResolver to convention-scanned modules
                       (requires apcore-toolkit).
+        registry: Pre-populated apcore Registry instance. When provided, skips
+                  filesystem discovery entirely. Useful for frameworks that register
+                  modules at runtime (e.g. apflow's bridge).
+        executor: Pre-built apcore Executor instance. When provided alongside
+                  registry, skips Executor construction. If omitted but registry
+                  is provided, an Executor is built from the given registry.
     """
     if prog_name is None:
         prog_name = os.path.basename(sys.argv[0]) or "apcore-cli"
@@ -121,64 +130,91 @@ def create_cli(
     except (TypeError, ValueError):
         help_text_max_length = 1000
 
-    ext_dir_missing = not os.path.exists(ext_dir)
-    ext_dir_unreadable = not ext_dir_missing and not os.access(ext_dir, os.R_OK)
+    if executor is not None and registry is None:
+        raise ValueError("executor requires registry — pass both or neither")
 
-    if ext_dir_missing:
-        click.echo(
-            f"Error: Extensions directory not found: '{ext_dir}'. Set APCORE_EXTENSIONS_ROOT or verify the path.",
-            err=True,
-        )
-        sys.exit(EXIT_CONFIG_NOT_FOUND)
-
-    if ext_dir_unreadable:
-        click.echo(
-            f"Error: Cannot read extensions directory: '{ext_dir}'. Check permissions.",
-            err=True,
-        )
-        sys.exit(EXIT_CONFIG_NOT_FOUND)
+    if registry is not None:
+        # Pre-populated registry provided — skip filesystem discovery.
+        try:
+            from apcore import Executor as _Executor
 
-    try:
-        from apcore import Executor, Registry
+            if executor is None:
+                executor = _Executor(registry)
+            logger.info("Using pre-populated registry (%d modules).", len(list(registry.list())))
+        except Exception as e:
+            click.echo(
+                f"Error: Failed to initialize executor from provided registry: {e}",
+                err=True,
+            )
+            sys.exit(EXIT_CONFIG_NOT_FOUND)
+    else:
+        # Standard path: discover modules from filesystem.
+        ext_dir_missing = not os.path.exists(ext_dir)
+        ext_dir_unreadable = not ext_dir_missing and not os.access(ext_dir, os.R_OK)
+
+        if ext_dir_missing:
+            click.echo(
+                f"Error: Extensions directory not found: '{ext_dir}'. Set APCORE_EXTENSIONS_ROOT or verify the path.",
+                err=True,
+            )
+            sys.exit(EXIT_CONFIG_NOT_FOUND)
+
+        if ext_dir_unreadable:
+            click.echo(
+                f"Error: Cannot read extensions directory: '{ext_dir}'. Check permissions.",
+                err=True,
+            )
+            sys.exit(EXIT_CONFIG_NOT_FOUND)
 
-        registry = Registry(extensions_dir=ext_dir)
         try:
-            logger.debug("Loading extensions from %s", ext_dir)
-            count = registry.discover()
-            logger.info("Initialized apcore-cli with %d modules.", count)
-        except Exception as e:
-            logger.warning("Discovery failed: %s", e)
+            from apcore import Executor as _Executor
+            from apcore import Registry as _Registry
 
-        # Convention module discovery
-        if commands_dir is not None:
+            registry = _Registry(extensions_dir=ext_dir)
             try:
-                from apcore_toolkit import RegistryWriter
-                from apcore_toolkit.convention_scanner import ConventionScanner
-
-                conv_scanner = ConventionScanner()
-                conv_modules = conv_scanner.scan(commands_dir)
-                if conv_modules:
-                    if binding_path is not None:
-                        try:
-                            from apcore_toolkit import DisplayResolver
-
-                            display_resolver = DisplayResolver()
-                            conv_modules = display_resolver.resolve(conv_modules, binding_path=binding_path)
-                            logger.info("DisplayResolver: applied binding from %s", binding_path)
-                        except ImportError:
-                            logger.warning("DisplayResolver not available in apcore-toolkit")
-                    writer = RegistryWriter()
-                    writer.write(conv_modules, registry)
-                    logger.info("Convention scanner: registered %d modules from %s", len(conv_modules), commands_dir)
-            except ImportError:
-                logger.warning("apcore-toolkit not installed — convention module scanning unavailable")
+                logger.debug("Loading extensions from %s", ext_dir)
+                count = registry.discover()
+                logger.info("Initialized apcore-cli with %d modules.", count)
             except Exception as e:
-                logger.warning("Convention module scanning failed: %s", e)
-
-        executor = Executor(registry)
-    except Exception as e:
-        click.echo(f"Error: Failed to initialize registry: {e}", err=True)
-        sys.exit(EXIT_CONFIG_NOT_FOUND)
+                logger.warning("Discovery failed: %s", e)
+
+            # Convention module discovery
+            if commands_dir is not None:
+                try:
+                    from apcore_toolkit import RegistryWriter
+                    from apcore_toolkit.convention_scanner import ConventionScanner
+
+                    conv_scanner = ConventionScanner()
+                    conv_modules = conv_scanner.scan(commands_dir)
+                    if conv_modules:
+                        if binding_path is not None:
+                            try:
+                                from apcore_toolkit import DisplayResolver
+
+                                display_resolver = DisplayResolver()
+                                conv_modules = display_resolver.resolve(conv_modules, binding_path=binding_path)
+                                logger.info(
+                                    "DisplayResolver: applied binding from %s",
+                                    binding_path,
+                                )
+                            except ImportError:
+                                logger.warning("DisplayResolver not available in apcore-toolkit")
+                        writer = RegistryWriter()
+                        writer.write(conv_modules, registry)
+                        logger.info(
+                            "Convention scanner: registered %d modules from %s",
+                            len(conv_modules),
+                            commands_dir,
+                        )
+                except ImportError:
+                    logger.warning("apcore-toolkit not installed — convention module scanning unavailable")
+                except Exception as e:
+                    logger.warning("Convention module scanning failed: %s", e)
+
+            executor = _Executor(registry)
+        except Exception as e:
+            click.echo(f"Error: Failed to initialize registry: {e}", err=True)
+            sys.exit(EXIT_CONFIG_NOT_FOUND)
 
     # Initialize audit logger
     try:
@@ -277,7 +313,12 @@ def main(prog_name: str | None = None) -> None:
     ext_dir = _extract_extensions_dir()
     cmd_dir = _extract_commands_dir()
     bind_path = _extract_binding_path()
-    cli = create_cli(extensions_dir=ext_dir, prog_name=prog_name, commands_dir=cmd_dir, binding_path=bind_path)
+    cli = create_cli(
+        extensions_dir=ext_dir,
+        prog_name=prog_name,
+        commands_dir=cmd_dir,
+        binding_path=bind_path,
+    )
     cli(standalone_mode=True)
 
 

tests/test_integration.py

@@ -310,3 +310,40 @@ def test_create_cli_override_bypasses_config(self, tmp_path):
         with pytest.raises(SystemExit) as exc_info:
             create_cli(extensions_dir="/nonexistent")
         assert exc_info.value.code == 47
+
+
+class TestPrePopulatedRegistry:
+    """Tests for create_cli with pre-populated registry parameter."""
+
+    def test_create_cli_with_registry_skips_filesystem(self):
+        """When registry is provided, no filesystem discovery occurs."""
+        from apcore_cli.__main__ import create_cli
+
+        registry = MagicMock()
+        registry.list.return_value = ["test.module"]
+
+        executor = MagicMock()
+
+        # Should NOT exit 47 even though no extensions dir exists.
+        cli_group = create_cli(registry=registry, executor=executor, prog_name="test-cli")
+        assert cli_group is not None
+
+    def test_create_cli_with_registry_auto_builds_executor(self):
+        """When registry is provided without executor, an Executor is auto-built."""
+        from apcore_cli.__main__ import create_cli
+
+        registry = MagicMock()
+        registry.list.return_value = []
+
+        # Executor is omitted — should be auto-built from registry.
+        cli_group = create_cli(registry=registry, prog_name="test-cli")
+        assert cli_group is not None
+
+    def test_create_cli_executor_without_registry_raises(self):
+        """Passing executor without registry is a usage error."""
+        from apcore_cli.__main__ import create_cli
+
+        executor = MagicMock()
+
+        with pytest.raises(ValueError, match="executor requires registry"):
+            create_cli(executor=executor, prog_name="test-cli")