apcore-cli 0.4.1__tar.gz → 0.6.0__tar.gz

{apcore_cli-0.4.1 → apcore_cli-0.6.0}/CHANGELOG.md

@@ -6,6 +6,43 @@ 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.6.0] - 2026-04-06
+
+### Changed
+
+- **Dependency bump**: requires `apcore >= 0.17.1` (was `>= 0.15.1`). Adds Execution Pipeline Strategy, Config Bus enhancements, Pipeline v2 declarative step metadata, `minimal` strategy preset.
+- **Schema parser**: Required schema properties now correctly enforced at CLI option level (was silently optional).
+- **Approval gate**: Fixed inverted logic in annotation type guard; `check_approval()` now accepts `timeout` parameter.
+
+### Added
+
+- **FE-11: Usability Enhancements** — 11 new capabilities:
+  - `--dry-run` preflight mode via `Executor.validate()`. Standalone `validate` command.
+  - System management commands: `health`, `usage`, `enable`, `disable`, `reload`, `config get`/`config set`. Graceful no-op when system modules unavailable.
+  - Enhanced error output: structured JSON with `ai_guidance`, `suggestion`, `retryable`, `user_fixable`, `details`. TTY hides machine-only fields.
+  - `--trace` pipeline visualization via `call_with_trace()`.
+  - `CliApprovalHandler` class implementing apcore `ApprovalHandler` protocol, wired to `Executor.set_approval_handler()`. `--approval-timeout`, `--approval-token` flags.
+  - `--stream` JSONL output via `Executor.stream()`.
+  - Enhanced `list` command: `--search`, `--status`, `--annotation`, `--sort`, `--reverse`, `--deprecated`, `--deps`.
+  - `--strategy` selection: `standard`, `internal`, `testing`, `performance`, `minimal`. `describe-pipeline` command.
+  - Output format extensions: `--format csv|yaml|jsonl`, `--fields` dot-path field selection.
+  - Multi-level grouping: `cli.group_depth` config key.
+  - Custom command extension: `create_cli(extra_commands=[...])` with collision detection.
+- New error code: `CONFIG_ENV_MAP_CONFLICT`.
+- New config keys: `cli.approval_timeout` (60), `cli.strategy` ("standard"), `cli.group_depth` (1).
+- New environment variables: `APCORE_CLI_APPROVAL_TIMEOUT`, `APCORE_CLI_STRATEGY`, `APCORE_CLI_GROUP_DEPTH`.
+- New files: `system_cmd.py`, `strategy.py`.
+
+---
+
+## [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

{apcore_cli-0.4.1 → apcore_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apcore-cli
-Version: 0.4.1
+Version: 0.6.0
 Summary: Terminal adapter for apcore — execute AI-Perceivable modules from the command line
 Project-URL: Homepage, https://aiperceivable.com
 Project-URL: Repository, https://github.com/aiperceivable/apcore-cli-python
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
-Requires-Dist: apcore>=0.14.0
+Requires-Dist: apcore>=0.17.1
 Requires-Dist: click>=8.1
 Requires-Dist: cryptography>=41.0
 Requires-Dist: jsonschema>=4.20
@@ -129,14 +129,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

{apcore_cli-0.4.1 → apcore_cli-0.6.0}/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

{apcore_cli-0.4.1 → apcore_cli-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.4.1"
+version = "0.6.0"
 description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
 readme = "README.md"
 license = "Apache-2.0"
@@ -26,7 +26,7 @@ classifiers = [
     "Environment :: Console",
 ]
 dependencies = [
-    "apcore>=0.14.0",
+    "apcore>=0.17.1",
     "click>=8.1",
     "jsonschema>=4.20",
     "rich>=13.0",

apcore_cli-0.6.0/src/apcore_cli/__init__.py

@@ -0,0 +1,35 @@
+"""apcore-cli: CLI adapter for the apcore module ecosystem."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _get_version
+
+try:
+    __version__ = _get_version("apcore-cli")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+# Config Bus namespace registration (apcore >= 0.15.0)
+try:
+    from apcore import Config
+
+    Config.register_namespace(
+        name="apcore-cli",
+        schema=None,
+        env_prefix="APCORE_CLI",
+        defaults={
+            "stdin_buffer_limit": 10_485_760,
+            "auto_approve": False,
+            "help_text_max_length": 1000,
+            "logging_level": "WARNING",
+            "approval_timeout": 60,
+            "strategy": "standard",
+            "group_depth": 1,
+        },
+    )
+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"]

{apcore_cli-0.4.1 → apcore_cli-0.6.0}/src/apcore_cli/__main__.py

@@ -5,15 +5,22 @@ from __future__ import annotations
 import logging
 import os
 import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _get_version
+from typing import Any
 
 import click
 
-from apcore_cli import __version__
 from apcore_cli.cli import GroupedModuleGroup, set_audit_logger, set_verbose_help
 from apcore_cli.config import ConfigResolver
 from apcore_cli.discovery import register_discovery_commands
 from apcore_cli.security.audit import AuditLogger
-from apcore_cli.shell import register_shell_commands
+from apcore_cli.shell import configure_man_help, register_shell_commands
+
+try:
+    __version__ = _get_version("apcore-cli")
+except PackageNotFoundError:
+    __version__ = "unknown"
 
 logger = logging.getLogger("apcore_cli")
 
@@ -61,6 +68,9 @@ 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,
+    extra_commands: list[Any] | None = None,
 ) -> click.Group:
     """Create the CLI application.
 
@@ -77,6 +87,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 +137,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 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 executor is not None and registry is None:
+        raise ValueError("executor requires registry — pass both or neither")
 
-    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:
@@ -187,6 +230,22 @@ def create_cli(
     except Exception as e:
         logger.warning("Failed to initialize audit logger: %s", e)
 
+    # Wire CliApprovalHandler to Executor (FE-11 §3.5)
+    try:
+        import contextlib
+
+        from apcore_cli.approval import CliApprovalHandler
+
+        approval_timeout = 60
+        with contextlib.suppress(TypeError, ValueError):
+            approval_timeout = int(config.resolve("cli.approval_timeout", env_var="APCORE_CLI_APPROVAL_TIMEOUT") or 60)
+        handler = CliApprovalHandler(auto_approve=False, timeout=approval_timeout)
+        if hasattr(executor, "set_approval_handler"):
+            executor.set_approval_handler(handler)
+            logger.debug("CliApprovalHandler wired to Executor (timeout=%ds).", approval_timeout)
+    except Exception as e:
+        logger.debug("Could not wire CliApprovalHandler: %s", e)
+
     @click.group(
         cls=GroupedModuleGroup,
         registry=registry,
@@ -250,17 +309,46 @@ def create_cli(
         ctx.obj["extensions_dir"] = ext_dir
         ctx.obj["verbose_help"] = verbose_help
 
-    # Register discovery commands
+    # Register discovery commands (list, describe)
     register_discovery_commands(cli, registry)
 
+    # Register validate command (FE-11 §3.1)
+    from apcore_cli.discovery import register_validate_command
+
+    register_validate_command(cli, registry, executor)
+
+    # Register system management commands (FE-11 §3.2) — no-op if system modules unavailable
+    from apcore_cli.system_cmd import register_system_commands
+
+    register_system_commands(cli, executor)
+
+    # Register pipeline introspection command (FE-11 §3.8)
+    from apcore_cli.strategy import register_pipeline_command
+
+    register_pipeline_command(cli, executor)
+
     # Register shell integration commands
     register_shell_commands(cli, prog_name=prog_name)
 
+    # Register --help --man support
+    configure_man_help(cli, prog_name, __version__)
+
     # Register init scaffolding command
     from apcore_cli.init_cmd import register_init_command
 
     register_init_command(cli)
 
+    # Register extra commands from downstream projects (FE-11 §3.11)
+    if extra_commands:
+        from apcore_cli.cli import BUILTIN_COMMANDS
+
+        for cmd in extra_commands:
+            cmd_name = getattr(cmd, "name", None)
+            if cmd_name and cmd_name in BUILTIN_COMMANDS:
+                msg = f"Extra command '{cmd_name}' conflicts with built-in command."
+                raise ValueError(msg)
+            cli.add_command(cmd)
+
     return cli
 
 
@@ -274,7 +362,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)