apcore-cli 0.1.0__py3-none-any.whl

apcore_cli/__init__.py

@@ -0,0 +1,3 @@
+"""apcore-cli: CLI adapter for the apcore module ecosystem."""
+
+__version__ = "0.1.0"

apcore_cli/__main__.py

@@ -0,0 +1,142 @@
+"""Entry point for apcore-cli (FE-01)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+import click
+
+from apcore_cli import __version__
+from apcore_cli.cli import LazyModuleGroup, set_audit_logger
+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
+
+logger = logging.getLogger("apcore_cli")
+
+EXIT_CONFIG_NOT_FOUND = 47
+
+
+def _extract_extensions_dir(argv: list[str] | None = None) -> str | None:
+    """Extract --extensions-dir value from argv before Click parses it.
+
+    This is needed because the registry must be created before Click runs,
+    but --extensions-dir is a Click option parsed at runtime.
+    Returns None if the flag is not present.
+    """
+    args = argv if argv is not None else sys.argv[1:]
+    for i, arg in enumerate(args):
+        if arg == "--extensions-dir" and i + 1 < len(args):
+            return args[i + 1]
+        if arg.startswith("--extensions-dir="):
+            return arg.split("=", 1)[1]
+    return None
+
+
+def create_cli(extensions_dir: str | None = None) -> click.Group:
+    """Create the CLI application.
+
+    Args:
+        extensions_dir: Override for extensions directory.
+                        When None, resolves via ConfigResolver (env/file/default).
+    """
+    if extensions_dir is not None:
+        ext_dir = extensions_dir
+    else:
+        config = ConfigResolver()
+        ext_dir = config.resolve(
+            "extensions.root",
+            cli_flag="--extensions-dir",
+            env_var="APCORE_EXTENSIONS_ROOT",
+        )
+
+    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)
+
+    try:
+        from apcore import Executor, Registry
+
+        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)
+
+        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:
+        audit_logger = AuditLogger()
+        set_audit_logger(audit_logger)
+    except Exception as e:
+        logger.warning("Failed to initialize audit logger: %s", e)
+
+    @click.group(
+        cls=LazyModuleGroup,
+        registry=registry,
+        executor=executor,
+        name="apcore-cli",
+        help="CLI adapter for the apcore module ecosystem.",
+    )
+    @click.version_option(
+        version=__version__,
+        prog_name="apcore-cli",
+    )
+    @click.option(
+        "--extensions-dir",
+        "extensions_dir_opt",
+        default=None,
+        help="Path to apcore extensions directory.",
+    )
+    @click.option(
+        "--log-level",
+        default=None,
+        type=click.Choice(["DEBUG", "INFO", "WARN", "ERROR"], case_sensitive=False),
+        help="Log level.",
+    )
+    @click.pass_context
+    def cli(ctx: click.Context, extensions_dir_opt: str | None = None, log_level: str | None = None) -> None:
+        ctx.ensure_object(dict)
+        ctx.obj["extensions_dir"] = ext_dir
+
+    # Register discovery commands
+    register_discovery_commands(cli, registry)
+
+    # Register shell integration commands
+    register_shell_commands(cli)
+
+    return cli
+
+
+def main() -> None:
+    """Main entry point for apcore-cli."""
+    # Extract --extensions-dir from argv before Click parses
+    ext_dir = _extract_extensions_dir()
+    cli = create_cli(extensions_dir=ext_dir)
+    cli(standalone_mode=True)
+
+
+if __name__ == "__main__":
+    main()

apcore_cli/_sandbox_runner.py

@@ -0,0 +1,25 @@
+"""Entry point for sandboxed module execution (FE-05)."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+
+def main() -> None:
+    module_id = sys.argv[1]
+    input_data = json.loads(sys.stdin.read())
+    extensions_root = os.environ.get("APCORE_EXTENSIONS_ROOT", "./extensions")
+
+    from apcore import Executor, Registry
+
+    registry = Registry(extensions_dir=extensions_root)
+    registry.discover()
+    executor = Executor(registry)
+    result = executor.call(module_id, input_data)
+    json.dump(result, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

apcore_cli/approval.py

@@ -0,0 +1,167 @@
+"""Approval Gate — TTY-aware HITL approval (FE-03)."""
+
+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)
+
+
+def check_approval(module_def: Any, auto_approve: bool, ctx: click.Context) -> 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.
+    """
+    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 module '%s'.",
+            module_id,
+        )
+        return
+    if env_val != "" and env_val != "1":
+        logger.warning(
+            "APCORE_CLI_AUTO_APPROVE is set to '%s', expected '1'. Ignoring.",
+            env_val,
+        )
+
+    # Non-TTY check
+    is_tty = sys.stdin.isatty()
+    if not is_tty:
+        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,
+        )
+        logger.error(
+            "Non-interactive environment, no bypass provided for module '%s'.",
+            module_id,
+        )
+        sys.exit(46)
+
+    # TTY prompt
+    _prompt_with_timeout(module_def, timeout=60)
+
+
+def _prompt_with_timeout(module_def: Any, timeout: int = 60) -> None:
+    """Display approval prompt with timeout."""
+    # Clamp timeout to valid range
+    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)
+
+    if sys.platform != "win32":
+        # Unix: use SIGALRM for timeout
+        _prompt_unix(module_id, timeout)
+    else:
+        # Windows: use threading.Timer for timeout
+        _prompt_windows(module_id, timeout)
+
+
+def _prompt_unix(module_id: str, timeout: int) -> None:
+    """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)
+        signal.alarm(0)
+        signal.signal(signal.SIGALRM, old_handler)
+
+        if approved:
+            logger.info("User approved execution of module '%s'.", module_id)
+            return
+        else:
+            logger.warning("Approval rejected by user for module '%s'.", module_id)
+            click.echo("Error: Approval denied.", err=True)
+            sys.exit(46)
+    except ApprovalTimeoutError:
+        signal.signal(signal.SIGALRM, old_handler)
+        logger.warning("Approval timed out after %ds for module '%s'.", timeout, module_id)
+        click.echo(
+            f"Error: Approval prompt timed out after {timeout} seconds.",
+            err=True,
+        )
+        sys.exit(46)
+
+
+def _prompt_windows(module_id: str, timeout: int) -> None:
+    """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()
+
+        if approved:
+            logger.info("User approved execution of module '%s'.", module_id)
+            return
+        else:
+            logger.warning("Approval rejected by user for module '%s'.", module_id)
+            click.echo("Error: Approval denied.", err=True)
+            sys.exit(46)
+    except ApprovalTimeoutError:
+        timer.cancel()
+        logger.warning("Approval timed out after %ds for module '%s'.", timeout, module_id)
+        click.echo(
+            f"Error: Approval prompt timed out after {timeout} seconds.",
+            err=True,
+        )
+        sys.exit(46)

apcore_cli/cli.py

@@ -0,0 +1,315 @@
+"""Core Dispatcher — CLI entry point and module routing (FE-01)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import sys
+import time
+from typing import TYPE_CHECKING, Any
+
+import click
+import jsonschema
+
+from apcore_cli.approval import check_approval
+from apcore_cli.output import format_exec_result
+from apcore_cli.ref_resolver import resolve_refs
+from apcore_cli.schema_parser import reconvert_enum_values, schema_to_click_options
+from apcore_cli.security.sandbox import Sandbox
+
+if TYPE_CHECKING:
+    from apcore import Executor, Registry
+    from apcore.registry.types import ModuleDescriptor
+
+    from apcore_cli.security.audit import AuditLogger
+
+logger = logging.getLogger("apcore_cli.cli")
+
+BUILTIN_COMMANDS = ["exec", "list", "describe", "completion", "man"]
+
+# Module-level audit logger, set during CLI init
+_audit_logger: AuditLogger | None = None
+
+
+def set_audit_logger(audit_logger: AuditLogger) -> None:
+    """Set the global audit logger instance."""
+    global _audit_logger
+    _audit_logger = audit_logger
+
+
+class LazyModuleGroup(click.Group):
+    """Custom Click Group that lazily loads apcore modules as subcommands."""
+
+    def __init__(self, registry: Registry, executor: Executor, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._registry = registry
+        self._executor = executor
+        self._module_cache: dict[str, click.Command] = {}
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        builtin = list(BUILTIN_COMMANDS)
+        try:
+            module_ids = self._registry.list()
+        except Exception:
+            logger.warning("Failed to list modules from registry")
+            module_ids = []
+        return sorted(set(builtin + module_ids))
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        # Check built-in commands first
+        if cmd_name in self.commands:
+            return self.commands[cmd_name]
+
+        # Check cache
+        if cmd_name in self._module_cache:
+            return self._module_cache[cmd_name]
+
+        # Look up in registry
+        module_def = self._registry.get_definition(cmd_name)
+        if module_def is None:
+            return None
+
+        cmd = build_module_command(module_def, self._executor)
+        self._module_cache[cmd_name] = cmd
+        return cmd
+
+
+# Error code mapping from apcore error codes to CLI exit codes
+_ERROR_CODE_MAP = {
+    "MODULE_NOT_FOUND": 44,
+    "MODULE_LOAD_ERROR": 44,
+    "MODULE_DISABLED": 44,
+    "SCHEMA_VALIDATION_ERROR": 45,
+    "SCHEMA_CIRCULAR_REF": 48,
+    "APPROVAL_DENIED": 46,
+    "APPROVAL_TIMEOUT": 46,
+    "APPROVAL_PENDING": 46,
+    "CONFIG_NOT_FOUND": 47,
+    "CONFIG_INVALID": 47,
+    "MODULE_EXECUTE_ERROR": 1,
+    "MODULE_TIMEOUT": 1,
+    "ACL_DENIED": 77,
+}
+
+
+def _get_module_id(module_def: ModuleDescriptor) -> str:
+    """Get the canonical module ID, falling back to module_id."""
+    cid = getattr(module_def, "canonical_id", None)
+    if isinstance(cid, str):
+        return cid
+    return module_def.module_id
+
+
+def build_module_command(module_def: ModuleDescriptor, executor: Executor) -> click.Command:
+    """Build a Click command from an apcore module definition.
+
+    Generates Click options from the module's input_schema, wires up
+    STDIN input collection, schema validation, approval gating,
+    execution, audit logging, and output formatting.
+    """
+    # Resolve $refs and generate Click options from input_schema
+    raw_schema = getattr(module_def, "input_schema", None)
+    module_id = _get_module_id(module_def)
+
+    # Defensively convert Pydantic model class to dict
+    if raw_schema is None:
+        input_schema: dict = {}
+    elif isinstance(raw_schema, dict):
+        input_schema = raw_schema
+    elif hasattr(raw_schema, "model_json_schema"):
+        # Pydantic v2 BaseModel class
+        input_schema = raw_schema.model_json_schema()
+    elif hasattr(raw_schema, "schema"):
+        # Pydantic v1 BaseModel class
+        input_schema = raw_schema.schema()
+    else:
+        input_schema = {}
+
+    if input_schema.get("properties"):
+        try:
+            resolved_schema = resolve_refs(input_schema, max_depth=32, module_id=module_id)
+        except SystemExit:
+            raise
+        except Exception:
+            resolved_schema = input_schema
+    else:
+        resolved_schema = input_schema
+
+    schema_options = schema_to_click_options(resolved_schema)
+
+    def callback(**kwargs: Any) -> None:
+        # Separate built-in options from schema-generated kwargs
+        stdin_input = kwargs.pop("input", None)
+        auto_approve = kwargs.pop("yes", False)
+        large_input = kwargs.pop("large_input", False)
+        output_format = kwargs.pop("format", None)
+        sandbox_flag = kwargs.pop("sandbox", False)
+
+        merged: dict[str, Any] = {}
+        try:
+            # 1. Collect and merge input (STDIN + CLI flags)
+            merged = collect_input(stdin_input, kwargs, large_input)
+
+            # 2. Reconvert enum values to original types
+            merged = reconvert_enum_values(merged, schema_options)
+
+            # 3. Validate against schema (if schema has properties)
+            if resolved_schema.get("properties"):
+                try:
+                    jsonschema.validate(merged, resolved_schema)
+                except jsonschema.ValidationError as ve:
+                    click.echo(
+                        f"Error: Validation failed for '{ve.path}': {ve.message}.",
+                        err=True,
+                    )
+                    sys.exit(45)
+
+            # 4. Check approval gate
+            check_approval(module_def, auto_approve, click.get_current_context())
+
+            # 5. Execute with timing (optionally sandboxed)
+            audit_start = time.monotonic()
+            sandbox = Sandbox(enabled=sandbox_flag)
+            result = sandbox.execute(module_id, merged, executor)
+            duration_ms = int((time.monotonic() - audit_start) * 1000)
+
+            # 6. Audit log (success)
+            if _audit_logger is not None:
+                _audit_logger.log_execution(module_id, merged, "success", 0, duration_ms)
+
+            # 7. Format and print result
+            format_exec_result(result, output_format)
+
+        except KeyboardInterrupt:
+            click.echo("Execution cancelled.", err=True)
+            sys.exit(130)
+        except SystemExit:
+            raise
+        except Exception as e:
+            error_code = getattr(e, "code", None)
+            exit_code = _ERROR_CODE_MAP.get(error_code, 1)
+
+            # Audit log (error)
+            if _audit_logger is not None:
+                _audit_logger.log_execution(module_id, merged, "error", exit_code, 0)
+
+            click.echo(f"Error: {e}", err=True)
+            sys.exit(exit_code)
+
+    # Build the command with schema-generated options + built-in options
+    cmd = click.Command(
+        name=module_id,
+        help=module_def.description,
+        callback=callback,
+    )
+
+    # Add built-in options
+    cmd.params.append(
+        click.Option(
+            ["--input"],
+            default=None,
+            help="Read input from file or STDIN ('-').",
+        )
+    )
+    cmd.params.append(
+        click.Option(
+            ["--yes", "-y"],
+            is_flag=True,
+            default=False,
+            help="Bypass approval prompts.",
+        )
+    )
+    cmd.params.append(
+        click.Option(
+            ["--large-input"],
+            is_flag=True,
+            default=False,
+            help="Allow STDIN input larger than 10MB.",
+        )
+    )
+    cmd.params.append(
+        click.Option(
+            ["--format"],
+            type=click.Choice(["json", "table"]),
+            default=None,
+            help="Output format.",
+        )
+    )
+    cmd.params.append(
+        click.Option(
+            ["--sandbox"],
+            is_flag=True,
+            default=False,
+            help="Run module in subprocess sandbox.",
+        )
+    )
+
+    # Add schema-generated options
+    cmd.params.extend(schema_options)
+
+    return cmd
+
+
+def validate_module_id(module_id: str) -> None:
+    """Validate module ID format and length."""
+    if len(module_id) > 128:
+        click.echo(
+            f"Error: Invalid module ID format: '{module_id}'. Maximum length is 128 characters.",
+            err=True,
+        )
+        sys.exit(2)
+    if not re.fullmatch(r"[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*", module_id):
+        click.echo(
+            f"Error: Invalid module ID format: '{module_id}'.",
+            err=True,
+        )
+        sys.exit(2)
+
+
+def collect_input(
+    stdin_flag: str | None,
+    cli_kwargs: dict[str, Any],
+    large_input: bool = False,
+) -> dict[str, Any]:
+    """Collect and merge input from STDIN and CLI flags."""
+    # Remove None values from CLI kwargs
+    cli_kwargs_non_none = {k: v for k, v in cli_kwargs.items() if v is not None}
+
+    if not stdin_flag:
+        return cli_kwargs_non_none
+
+    if stdin_flag == "-":
+        raw = sys.stdin.read()
+        raw_size = len(raw.encode("utf-8"))
+
+        if raw_size > 10_485_760 and not large_input:
+            click.echo(
+                "Error: STDIN input exceeds 10MB limit. Use --large-input to override.",
+                err=True,
+            )
+            sys.exit(2)
+
+        if not raw or raw_size == 0:
+            stdin_data: dict[str, Any] = {}
+        else:
+            try:
+                stdin_data = json.loads(raw)
+            except json.JSONDecodeError as e:
+                click.echo(
+                    f"Error: STDIN does not contain valid JSON: {e.msg}.",
+                    err=True,
+                )
+                sys.exit(2)
+
+            if not isinstance(stdin_data, dict):
+                click.echo(
+                    f"Error: STDIN JSON must be an object, got {type(stdin_data).__name__}.",
+                    err=True,
+                )
+                sys.exit(2)
+
+        # CLI flags override STDIN for duplicate keys
+        return {**stdin_data, **cli_kwargs_non_none}
+
+    return cli_kwargs_non_none