bijux-cli 0.1.0__py3-none-any.whl

bijux_cli/api.py

@@ -0,0 +1,326 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Provides a high-level, synchronous facade for the Bijux CLI's core engine.
+
+This module defines the `BijuxAPI` class, which serves as the primary public
+interface for programmatic interaction with the CLI. It wraps the asynchronous
+core `Engine` and other services to present a stable, thread-safe, and
+synchronous API.
+
+This facade is intended for use in integrations, testing, or any scenario
+where the CLI's command and plugin management logic needs to be embedded
+within another Python application.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+import importlib
+import os
+from pathlib import Path
+import sys
+from typing import Any
+
+from bijux_cli.commands.utilities import validate_common_flags
+from bijux_cli.contracts import (
+    ObservabilityProtocol,
+    RegistryProtocol,
+    TelemetryProtocol,
+)
+from bijux_cli.core.di import DIContainer
+from bijux_cli.core.engine import Engine
+from bijux_cli.core.enums import OutputFormat
+from bijux_cli.core.exceptions import BijuxError, CommandError, ServiceError
+
+IGNORE = {"PS1", "LS_COLORS", "PROMPT_COMMAND", "GIT_PS1_FORMAT"}
+
+
+class BijuxAPI:
+    """A thread-safe, synchronous access layer for the Bijux CLI engine.
+
+    This class provides a stable public API for registering commands, executing
+    them, and managing plugins. It wraps the internal asynchronous `Engine` to
+    allow for simpler, synchronous integration into other applications.
+
+    Attributes:
+        _di (DIContainer): The dependency injection container.
+        _engine (Engine): The core asynchronous runtime engine.
+        _registry (RegistryProtocol): The plugin registry service.
+        _obs (ObservabilityProtocol): The logging service.
+        _tel (TelemetryProtocol): The telemetry service.
+    """
+
+    def __init__(self, *, debug: bool = False) -> None:
+        """Initializes the `BijuxAPI` and the underlying CLI engine.
+
+        Args:
+            debug (bool): If True, enables debug mode for all underlying
+                services. Defaults to False.
+        """
+        DIContainer.reset()
+        self._di = DIContainer.current()
+        self._engine = Engine(
+            self._di,
+            debug=debug,
+            fmt=OutputFormat.JSON,
+        )
+        self._registry: RegistryProtocol = self._di.resolve(RegistryProtocol)
+        self._obs: ObservabilityProtocol = self._di.resolve(ObservabilityProtocol)
+        self._tel: TelemetryProtocol = self._di.resolve(TelemetryProtocol)
+
+    def _schedule_event(self, name: str, payload: dict[str, Any]) -> None:
+        """Schedules a "fire-and-forget" asynchronous telemetry event.
+
+        This helper handles the execution of async telemetry calls from a
+        synchronous context.
+
+        Args:
+            name (str): The name of the telemetry event.
+            payload (dict[str, Any]): The data associated with the event.
+        """
+        maybe_coro: Coroutine[Any, Any, None] | None = self._tel.event(name, payload)
+        if asyncio.iscoroutine(maybe_coro):
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(maybe_coro)
+            except RuntimeError:
+                asyncio.run(maybe_coro)
+
+    def register(self, name: str, callback: Callable[..., Any]) -> None:
+        """Registers or replaces a Python callable as a CLI command.
+
+        The provided callable is wrapped to handle both synchronous and
+        asynchronous functions automatically.
+
+        Args:
+            name (str): The command name to register.
+            callback (Callable[..., Any]): The Python function to be executed
+                when the command is run.
+
+        Raises:
+            BijuxError: If the command name is already in use or another
+                registration error occurs.
+        """
+
+        class _Wrapper:
+            """Wraps a user-provided callable to be executed asynchronously."""
+
+            def __init__(self, cb: Callable[..., Any]) -> None:
+                """Initializes the wrapper.
+
+                Args:
+                    cb (Callable[..., Any]): The callable to wrap.
+                """
+                self._cb = cb
+
+            async def execute(self, *args: Any, **kwargs: Any) -> Any:
+                """Execute the wrapped callable, awaiting if it's a coroutine.
+
+                Args:
+                    *args (Any): Positional arguments to pass to the callable.
+                    **kwargs (Any): Keyword arguments to pass to the callable.
+
+                Returns:
+                    Any: The result of the callable execution.
+                """
+                if asyncio.iscoroutinefunction(self._cb):
+                    return await self._cb(*args, **kwargs)
+                return self._cb(*args, **kwargs)
+
+        try:
+            if self._registry.has(name):
+                self._registry.deregister(name)
+            self._registry.register(name, _Wrapper(callback))
+            self._obs.log("info", "Registered command", extra={"name": name})
+            self._schedule_event("api.register", {"name": name})
+        except ServiceError as exc:
+            self._schedule_event(
+                "api.register.error", {"name": name, "error": str(exc)}
+            )
+            raise BijuxError(
+                f"Could not register command {name}: {exc}", http_status=500
+            ) from exc
+
+    def run_sync(
+        self,
+        name: str,
+        *args: Any,
+        quiet: bool = False,
+        verbose: bool = False,
+        fmt: str = "json",
+        pretty: bool = True,
+        debug: bool = False,
+        **kwargs: Any,
+    ) -> Any:
+        """Runs a command synchronously.
+
+        This method is a blocking wrapper around the asynchronous `run_async`
+        method. It manages the asyncio event loop to provide a simple,
+        synchronous interface.
+
+        Args:
+            name (str): The name of the command to run.
+            *args (Any): Positional arguments for the command.
+            quiet (bool): If True, suppresses output.
+            verbose (bool): If True, enables verbose logging.
+            fmt (str): The output format ("json" or "yaml").
+            pretty (bool): If True, formats the output for readability.
+            debug (bool): If True, enables debug mode.
+            **kwargs (Any): Additional keyword arguments to pass to the command.
+
+        Returns:
+            Any: The result of the command's execution.
+        """
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(
+                self.run_async(
+                    name,
+                    *args,
+                    quiet=quiet,
+                    verbose=verbose,
+                    fmt=fmt,
+                    pretty=pretty,
+                    debug=debug,
+                    **kwargs,
+                )
+            )
+        else:
+            return loop.run_until_complete(
+                self.run_async(
+                    name,
+                    *args,
+                    quiet=quiet,
+                    verbose=verbose,
+                    fmt=fmt,
+                    pretty=pretty,
+                    debug=debug,
+                    **kwargs,
+                )
+            )
+
+    async def run_async(
+        self,
+        name: str,
+        *args: Any,
+        quiet: bool = False,
+        verbose: bool = False,
+        fmt: str = "json",
+        pretty: bool = True,
+        debug: bool = False,
+        **kwargs: Any,
+    ) -> Any:
+        """Runs a command asynchronously with validation.
+
+        This method performs validation of flags and environment variables
+        before dispatching the command to the internal engine for execution.
+
+        Args:
+            name (str): The name of the command to execute.
+            *args (Any): Positional arguments for the command.
+            quiet (bool): If True, suppresses output.
+            verbose (bool): If True, enables verbose output.
+            fmt (str): The output format ("json" or "yaml").
+            pretty (bool): If True, formats the output for readability.
+            debug (bool): If True, enables debug mode.
+            **kwargs (Any): Additional keyword arguments to pass to the command.
+
+        Returns:
+            Any: The result of the command's execution.
+
+        Raises:
+            BijuxError: For invalid flags, unsupported formats, or internal
+                execution errors.
+        """
+        try:
+            fmt = fmt.lower()
+            if fmt not in ("json", "yaml"):
+                raise BijuxError("Unsupported format", http_status=400)
+
+            if quiet and (verbose or debug):
+                raise BijuxError(
+                    "--quiet cannot be combined with --verbose/--debug", http_status=400
+                )
+
+            validate_common_flags(fmt, name, quiet, verbose or debug)
+
+            for k, v in os.environ.items():
+                if k in IGNORE:
+                    continue
+                if not v.isascii():
+                    raise BijuxError(
+                        "Non-ASCII characters in environment", http_status=400
+                    )
+
+            result = await self._engine.run_command(name, *args, **kwargs)
+            self._schedule_event("api.run", {"name": name})
+            return result
+
+        except CommandError as exc:
+            self._schedule_event("api.run.error", {"name": name, "error": str(exc)})
+            raise BijuxError(
+                f"Failed to run command {name}: {exc}", http_status=500
+            ) from exc
+
+        except ServiceError as exc:
+            self._schedule_event("api.run.error", {"name": name, "error": str(exc)})
+            raise BijuxError(
+                f"Failed to run command {name}: {exc}", http_status=500
+            ) from exc
+
+        except BijuxError:
+            raise
+
+        except Exception as exc:
+            self._schedule_event("api.run.error", {"name": name, "error": str(exc)})
+            raise BijuxError(
+                f"Failed to run command {name}: {exc}", http_status=500
+            ) from exc
+
+    def load_plugin(self, path: str | Path) -> None:
+        """Loads or reloads a plugin module from a file path.
+
+        This method dynamically loads the specified plugin file, initializes it,
+        and registers it with the CLI system. If the plugin is already loaded,
+        it is reloaded.
+
+        Args:
+            path (str | Path): The filesystem path to the plugin's Python file.
+
+        Raises:
+            BijuxError: If plugin loading, initialization, or registration fails.
+        """
+        from bijux_cli.__version__ import __version__
+        from bijux_cli.services.plugins import load_plugin as _load_plugin
+
+        p = Path(path).expanduser().resolve()
+        module_name = f"bijux_plugin_{p.stem}"
+
+        try:
+            if module_name in sys.modules:
+                importlib.reload(sys.modules[module_name])
+
+            plugin = _load_plugin(p, module_name)
+            plugin.startup(self._engine.di)
+
+            if self._registry.has(p.stem):
+                self._registry.deregister(p.stem)
+
+            self._registry.register(
+                p.stem,
+                plugin,
+                alias=str(__version__),
+            )
+            self._obs.log("info", "Loaded plugin", extra={"path": str(p)})
+            self._schedule_event("api.plugin_loaded", {"path": str(p)})
+
+        except Exception as exc:
+            self._schedule_event(
+                "api.plugin_load.error", {"path": str(p), "error": str(exc)}
+            )
+            raise BijuxError(
+                f"Failed to load plugin {p}: {exc}", http_status=500
+            ) from exc

bijux_cli/cli.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Constructs the main `Typer` application for the Bijux CLI.
+
+This module serves as the primary builder for the entire CLI. It defines the
+root `Typer` app, orchestrates the registration of all core commands and
+the discovery of dynamic plugins, and sets the default behavior for when the
+CLI is invoked without any command.
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+import sys
+
+import typer
+from typer import Context
+
+from bijux_cli.commands import register_commands, register_dynamic_plugins
+
+
+def maybe_default_to_repl(ctx: Context) -> None:
+    """Invokes the `repl` command if no other subcommand is specified.
+
+    This function is used as the root callback for the main `Typer` application.
+    It checks if a subcommand was invoked and, if not, re-executes the CLI
+    with the `repl` command.
+
+    Args:
+        ctx (Context): The Typer context, used to check for an invoked subcommand.
+
+    Returns:
+        None:
+    """
+    if ctx.invoked_subcommand is None:
+        subprocess.call([sys.argv[0], "repl"])  # noqa: S603  # nosec B603
+
+
+def build_app() -> typer.Typer:
+    """Builds and configures the root `Typer` application.
+
+    This factory function performs the main steps of assembling the CLI:
+    1.  Creates the root `Typer` app instance.
+    2.  Registers all core, built-in commands.
+    3.  Discovers and registers all dynamic plugins.
+    4.  Sets the default callback to launch the REPL.
+
+    Returns:
+        typer.Typer: The fully constructed `Typer` application.
+    """
+    app = typer.Typer(
+        help="Bijux CLI – Lean, plug-in‑driven command‑line interface.",
+        invoke_without_command=True,
+        context_settings={
+            "ignore_unknown_options": True,
+            "allow_extra_args": True,
+        },
+    )
+    register_commands(app)
+    register_dynamic_plugins(app)
+    app.callback(invoke_without_command=True)(maybe_default_to_repl)
+    return app
+
+
+app = build_app()
+
+__all__ = ["build_app", "app"]

bijux_cli/commands/__init__.py

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Constructs the command structure for the Bijux CLI application.
+
+This module is responsible for assembling the entire CLI by registering all
+core command groups and dynamically discovering and loading external plugins.
+It provides the central mechanism that makes the CLI's command system modular
+and extensible.
+
+The primary functions are:
+* `register_commands`: Attaches all built-in command `Typer` applications
+    (e.g., `config_app`, `plugins_app`) to the main root application.
+* `register_dynamic_plugins`: Scans for plugins from package entry points
+    and the local plugins directory, loading and attaching them to the root
+    application. Errors during this process are logged as warnings.
+* `list_registered_command_names`: Provides a way to retrieve the names of all
+    successfully registered commands, including dynamic plugins.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from typer import Typer
+
+from bijux_cli.commands.audit import audit_app
+from bijux_cli.commands.config import config_app
+from bijux_cli.commands.dev import dev_app
+from bijux_cli.commands.docs import docs_app
+from bijux_cli.commands.doctor import doctor_app
+from bijux_cli.commands.help import help_app
+from bijux_cli.commands.history import history_app
+from bijux_cli.commands.memory import memory_app
+from bijux_cli.commands.plugins import plugins_app
+from bijux_cli.commands.repl import repl_app
+from bijux_cli.commands.sleep import sleep_app
+from bijux_cli.commands.status import status_app
+from bijux_cli.commands.version import version_app
+
+logger = logging.getLogger(__name__)
+
+_CORE_COMMANDS = {
+    "audit": audit_app,
+    "config": config_app,
+    "dev": dev_app,
+    "docs": docs_app,
+    "doctor": doctor_app,
+    "help": help_app,
+    "history": history_app,
+    "memory": memory_app,
+    "plugins": plugins_app,
+    "repl": repl_app,
+    "status": status_app,
+    "version": version_app,
+    "sleep": sleep_app,
+}
+_REGISTERED_COMMANDS: set[str] = set(_CORE_COMMANDS.keys())
+
+
+def register_commands(app: Typer) -> list[str]:
+    """Registers all core, built-in commands with the main Typer application.
+
+    Args:
+        app (Typer): The main Typer application to which commands will be added.
+
+    Returns:
+        list[str]: An alphabetically sorted list of the names of the registered
+            core commands.
+    """
+    for name, cmd in sorted(_CORE_COMMANDS.items()):
+        app.add_typer(cmd, name=name, invoke_without_command=True)
+        _REGISTERED_COMMANDS.add(name)
+    return sorted(_CORE_COMMANDS.keys())
+
+
+def register_dynamic_plugins(app: Typer) -> None:
+    """Discovers and registers all third-party plugins.
+
+    This function scans for plugins from two sources:
+    1.  Python package entry points registered under the `bijux_cli.plugins` group.
+    2.  Subdirectories within the local plugins folder that contain a `plugin.py`.
+
+    For each discovered plugin, this function expects the loaded module to expose
+    either a callable `cli()` that returns a `Typer` app or an `app` attribute
+    that is a `Typer` instance. All discovery and loading errors are logged
+    and suppressed to prevent a single faulty plugin from crashing the CLI.
+
+    Args:
+        app (Typer): The root Typer application to which discovered plugin
+            apps will be attached.
+
+    Returns:
+        None:
+    """
+    import importlib.util
+    import sys
+
+    try:
+        import importlib.metadata
+
+        eps = importlib.metadata.entry_points()
+        for ep in eps.select(group="bijux_cli.plugins"):
+            try:
+                plugin_app = ep.load()
+                app.add_typer(plugin_app, name=ep.name)
+                _REGISTERED_COMMANDS.add(ep.name)
+            except Exception as exc:
+                logger.debug("Failed to load entry-point plugin %r: %s", ep.name, exc)
+    except Exception as e:
+        logger.debug("Entry points loading failed: %s", e)
+
+    try:
+        from bijux_cli.services.plugins import get_plugins_dir
+
+        plugins_dir = get_plugins_dir()
+        for pdir in plugins_dir.iterdir():
+            plug_py = pdir / "plugin.py"
+            if not plug_py.is_file():
+                continue
+            mod_name = f"_bijux_cli_plugin_{pdir.name}"
+            spec = importlib.util.spec_from_file_location(mod_name, plug_py)
+            if not spec or not spec.loader:
+                continue
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[mod_name] = module
+            try:
+                spec.loader.exec_module(module)
+                plugin_app = None
+                if hasattr(module, "cli") and callable(module.cli):
+                    plugin_app = module.cli()
+                elif hasattr(module, "app"):
+                    plugin_app = module.app
+                else:
+                    logger.debug(
+                        "Plugin %r has no CLI entrypoint (no cli()/app).", pdir.name
+                    )
+                    continue
+                if isinstance(plugin_app, Typer):
+                    app.add_typer(plugin_app, name=pdir.name)
+                    _REGISTERED_COMMANDS.add(pdir.name)
+                else:
+                    logger.debug(
+                        "Plugin %r loaded but did not return a Typer app instance.",
+                        pdir.name,
+                    )
+            except Exception as exc:
+                logger.debug("Failed to load local plugin %r: %s", pdir.name, exc)
+            finally:
+                sys.modules.pop(mod_name, None)
+    except Exception as e:
+        logger.debug("Dynamic plugin discovery failed: %s", e)
+
+
+def list_registered_command_names() -> list[str]:
+    """Returns a list of all registered command names.
+
+    This includes both core commands and any dynamically loaded plugins.
+
+    Returns:
+        list[str]: An alphabetically sorted list of all command names.
+    """
+    return sorted(_REGISTERED_COMMANDS)
+
+
+__all__ = [
+    "register_commands",
+    "register_dynamic_plugins",
+    "list_registered_command_names",
+]