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

{apcore_cli-0.5.0 → 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.5.0 → apcore_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apcore-cli
-Version: 0.5.0
+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.15.1
+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.5.0 → 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.5.0 → apcore_cli-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.5.0"
+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",

{apcore_cli-0.5.0 → apcore_cli-0.6.0}/src/apcore_cli/__init__.py

@@ -21,7 +21,15 @@ try:
             "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.5.0 → apcore_cli-0.6.0}/src/apcore_cli/__main__.py

@@ -5,16 +5,23 @@ 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 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
@@ -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,9 +309,24 @@ 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)
 
@@ -264,6 +338,17 @@ def create_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
 
 
@@ -277,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)
 
 

apcore_cli-0.6.0/src/apcore_cli/approval.py

@@ -0,0 +1,235 @@
+"""Approval Gate — TTY-aware HITL approval (FE-03, FE-11 §3.5)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import threading
+from typing import Any
+
+import click
+
+logger = logging.getLogger("apcore_cli.approval")
+
+
+class ApprovalTimeoutError(Exception):
+    """Raised when the approval prompt times out."""
+
+    pass
+
+
+def _get_annotation(annotations: Any, key: str, default: Any = None) -> Any:
+    """Get an annotation value from either a dict or a ModuleAnnotations object."""
+    if isinstance(annotations, dict):
+        return annotations.get(key, default)
+    return getattr(annotations, key, default)
+
+
+# ---------------------------------------------------------------------------
+# CliApprovalHandler — implements apcore ApprovalHandler protocol (FE-11 §3.5)
+# ---------------------------------------------------------------------------
+
+
+class CliApprovalHandler:
+    """ApprovalHandler that prompts in TTY, auto-denies in non-TTY (unless bypassed).
+
+    Implements the apcore ApprovalHandler protocol:
+    - ``request_approval(request) -> ApprovalResult``
+    - ``check_approval(approval_id) -> ApprovalResult``
+
+    Pass to Executor via ``executor.set_approval_handler(handler)``.
+    """
+
+    def __init__(self, auto_approve: bool = False, timeout: int = 60) -> None:
+        self.auto_approve = auto_approve
+        self.timeout = max(1, min(timeout, 3600))
+
+    async def request_approval(self, request: Any) -> Any:
+        """Request approval for a module invocation.
+
+        Follows the apcore ApprovalRequest/ApprovalResult protocol.
+        Returns a dict with ``status``, ``approved_by``, ``reason`` fields
+        (duck-type compatible with ApprovalResult dataclass).
+        """
+        module_id = getattr(request, "module_id", "unknown")
+
+        # Bypass: auto_approve flag
+        if self.auto_approve:
+            logger.info("Approval bypassed via --yes flag for module '%s'.", module_id)
+            return {"status": "approved", "approved_by": "auto_approve"}
+
+        # Bypass: APCORE_CLI_AUTO_APPROVE env var
+        env_val = os.environ.get("APCORE_CLI_AUTO_APPROVE", "")
+        if env_val == "1":
+            logger.info("Approval bypassed via APCORE_CLI_AUTO_APPROVE for '%s'.", module_id)
+            return {"status": "approved", "approved_by": "env_auto_approve"}
+        if env_val != "" and env_val != "1":
+            logger.warning("APCORE_CLI_AUTO_APPROVE='%s', expected '1'. Ignoring.", env_val)
+
+        # Non-TTY: reject
+        if not sys.stdin.isatty():
+            return {
+                "status": "rejected",
+                "reason": "Non-interactive session without --yes",
+            }
+
+        # TTY prompt
+        annotations = getattr(request, "annotations", None) or {}
+        extra = getattr(annotations, "extra", {}) if not isinstance(annotations, dict) else annotations
+        message = extra.get("approval_message") or f"Module '{module_id}' requires approval to execute."
+
+        click.echo(message, err=True)
+        try:
+            approved = _tty_prompt(module_id, self.timeout)
+        except ApprovalTimeoutError:
+            return {"status": "timeout", "reason": f"Timed out after {self.timeout}s"}
+
+        if approved:
+            return {"status": "approved", "approved_by": "tty_user"}
+        return {"status": "rejected", "reason": "User rejected"}
+
+    async def check_approval(self, approval_id: str) -> Any:
+        """Check status of a previously pending approval (Phase B).
+
+        CLI does not support async approval polling; always returns rejected.
+        """
+        return {
+            "status": "rejected",
+            "reason": "CLI does not support async approval polling",
+        }
+
+
+# ---------------------------------------------------------------------------
+# Legacy check_approval() — backward-compatible wrapper
+# ---------------------------------------------------------------------------
+
+
+def check_approval(module_def: Any, auto_approve: bool, timeout: int = 60) -> None:
+    """Check if module requires approval and handle accordingly.
+
+    Returns None if approved (or approval not required).
+    Calls sys.exit(46) if denied/timed out/pending.
+
+    Args:
+        module_def: Module descriptor with annotations.
+        auto_approve: If True, bypass approval (--yes flag).
+        timeout: Approval prompt timeout in seconds.
+    """
+    annotations = getattr(module_def, "annotations", None)
+    if annotations is None or (not isinstance(annotations, dict) and not hasattr(annotations, "requires_approval")):
+        return
+
+    requires = _get_annotation(annotations, "requires_approval", False)
+    if requires is not True:
+        return
+
+    module_id = getattr(module_def, "module_id", getattr(module_def, "canonical_id", "unknown"))
+
+    # Bypass: --yes flag (highest priority)
+    if auto_approve is True:
+        logger.info("Approval bypassed via --yes flag for module '%s'.", module_id)
+        return
+
+    # Bypass: APCORE_CLI_AUTO_APPROVE env var
+    env_val = os.environ.get("APCORE_CLI_AUTO_APPROVE", "")
+    if env_val == "1":
+        logger.info("Approval bypassed via APCORE_CLI_AUTO_APPROVE for '%s'.", module_id)
+        return
+    if env_val != "" and env_val != "1":
+        logger.warning("APCORE_CLI_AUTO_APPROVE='%s', expected '1'. Ignoring.", env_val)
+
+    # Non-TTY check
+    if not sys.stdin.isatty():
+        click.echo(
+            f"Error: Module '{module_id}' requires approval but no interactive "
+            "terminal is available. Use --yes or set APCORE_CLI_AUTO_APPROVE=1 "
+            "to bypass.",
+            err=True,
+        )
+        sys.exit(46)
+
+    # TTY prompt
+    _prompt_with_timeout(module_def, timeout=timeout)
+
+
+# ---------------------------------------------------------------------------
+# Internal prompt implementation
+# ---------------------------------------------------------------------------
+
+
+def _prompt_with_timeout(module_def: Any, timeout: int = 60) -> None:
+    """Display approval prompt with timeout."""
+    timeout = max(1, min(timeout, 3600))
+
+    module_id = getattr(module_def, "module_id", getattr(module_def, "canonical_id", "unknown"))
+    annotations = getattr(module_def, "annotations", None) or {}
+    message = _get_annotation(annotations, "approval_message", None)
+    if message is None:
+        message = f"Module '{module_id}' requires approval to execute."
+
+    click.echo(message, err=True)
+
+    try:
+        approved = _tty_prompt(module_id, timeout)
+    except ApprovalTimeoutError:
+        click.echo(f"Error: Approval prompt timed out after {timeout} seconds.", err=True)
+        sys.exit(46)
+
+    if approved:
+        logger.info("User approved execution of module '%s'.", module_id)
+    else:
+        click.echo("Error: Approval denied.", err=True)
+        sys.exit(46)
+
+
+def _tty_prompt(module_id: str, timeout: int) -> bool:
+    """Run the TTY prompt with timeout. Returns True if approved, raises on timeout."""
+    if sys.platform != "win32":
+        return _prompt_unix(module_id, timeout)
+    return _prompt_windows(module_id, timeout)
+
+
+def _prompt_unix(module_id: str, timeout: int) -> bool:
+    """Unix approval prompt using SIGALRM."""
+    import signal
+
+    def _timeout_handler(signum: int, frame: Any) -> None:
+        raise ApprovalTimeoutError()
+
+    old_handler = signal.signal(signal.SIGALRM, _timeout_handler)
+    signal.alarm(timeout)
+
+    try:
+        approved = click.confirm("Proceed?", default=False)
+    except ApprovalTimeoutError:
+        logger.warning("Approval timed out after %ds for module '%s'.", timeout, module_id)
+        raise
+    finally:
+        signal.alarm(0)
+        signal.signal(signal.SIGALRM, old_handler)
+
+    return approved
+
+
+def _prompt_windows(module_id: str, timeout: int) -> bool:
+    """Windows approval prompt using threading.Timer + ctypes."""
+    import ctypes
+
+    def _interrupt_main() -> None:
+        ctypes.pythonapi.PyThreadState_SetAsyncExc(
+            ctypes.c_ulong(threading.main_thread().ident),
+            ctypes.py_object(ApprovalTimeoutError),
+        )
+
+    timer = threading.Timer(timeout, _interrupt_main)
+    timer.start()
+
+    try:
+        approved = click.confirm("Proceed?", default=False)
+        timer.cancel()
+        return approved
+    except ApprovalTimeoutError:
+        timer.cancel()
+        logger.warning("Approval timed out after %ds for module '%s'.", timeout, module_id)
+        raise