feat: add dry-run validation, structured error reporting, and expanded CLI command support

Author: tercel

CHANGELOG.md

@@ -6,6 +6,35 @@ 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

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.5.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.15.1",
+    "apcore>=0.17.1",
     "click>=8.1",
     "jsonschema>=4.20",
     "rich>=13.0",

src/apcore_cli/__init__.py

@@ -21,6 +21,9 @@
             "auto_approve": False,
             "help_text_max_length": 1000,
             "logging_level": "WARNING",
+            "approval_timeout": 60,
+            "strategy": "standard",
+            "group_depth": 1,
         },
     )
 except (ImportError, AttributeError):

src/apcore_cli/__main__.py

@@ -5,17 +5,23 @@
 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 configure_man_help, register_shell_commands
 
+try:
+    __version__ = _get_version("apcore-cli")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
 logger = logging.getLogger("apcore_cli")
 
 EXIT_CONFIG_NOT_FOUND = 47
@@ -64,6 +70,7 @@ def create_cli(
     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.
 
@@ -223,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,
@@ -286,9 +309,24 @@ def 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)
 
@@ -300,6 +338,17 @@ def cli(
 
     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