bijux-cli 0.1.0__py3-none-any.whl

bijux_cli/commands/config/get.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Implements the `config get` subcommand for the Bijux CLI.
+
+This module contains the logic for retrieving the value of a specific key
+from the active configuration store. It provides a structured, machine-readable
+response containing the value or an error if the key is not found.
+
+Output Contract:
+    * Success: `{"value": str}`
+    * Verbose: Adds `{"python": str, "platform": str}` to the payload.
+    * Error:   `{"error": str, "code": int}`
+
+Exit Codes:
+    * `0`: Success.
+    * `1`: An unexpected error occurred while accessing the configuration.
+    * `2`: The specified key was not found in the configuration.
+"""
+
+from __future__ import annotations
+
+import platform
+
+import typer
+
+from bijux_cli.commands.utilities import (
+    ascii_safe,
+    emit_error_and_exit,
+    new_run_command,
+    parse_global_flags,
+)
+from bijux_cli.contracts import ConfigProtocol
+from bijux_cli.core.constants import (
+    HELP_DEBUG,
+    HELP_FORMAT,
+    HELP_NO_PRETTY,
+    HELP_QUIET,
+    HELP_VERBOSE,
+)
+from bijux_cli.core.di import DIContainer
+from bijux_cli.core.exceptions import CommandError
+
+
+def get_config(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help="Configuration key to look up"),
+    quiet: bool = typer.Option(False, "-q", "--quiet", help=HELP_QUIET),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help=HELP_VERBOSE),
+    fmt: str = typer.Option("json", "-f", "--format", help=HELP_FORMAT),
+    pretty: bool = typer.Option(True, "--pretty/--no-pretty", help=HELP_NO_PRETTY),
+    debug: bool = typer.Option(False, "-d", "--debug", help=HELP_DEBUG),
+) -> None:
+    """Retrieves the value for a given configuration key.
+
+    This function fetches the value for the specified key from the configuration
+    service and uses the `new_run_command` helper to emit it in a structured
+    payload. It handles errors, such as the key not being found.
+
+    Args:
+        ctx (typer.Context): The Typer context for the CLI.
+        key (str): The configuration key whose value should be retrieved.
+        quiet (bool): If True, suppresses all output except for errors.
+        verbose (bool): If True, includes Python/platform details in the output.
+        fmt (str): The output format, "json" or "yaml".
+        pretty (bool): If True, pretty-prints the output.
+        debug (bool): If True, enables debug diagnostics.
+
+    Returns:
+        None:
+
+    Raises:
+        SystemExit: Always exits with a contract-compliant status code and
+            payload, indicating success or detailing the error.
+    """
+    flags = parse_global_flags()
+
+    quiet = flags["quiet"]
+    verbose = flags["verbose"]
+    fmt = flags["format"]
+    pretty = flags["pretty"]
+    debug = flags["debug"]
+
+    include_runtime = verbose
+    fmt_lower = fmt.lower()
+
+    command = "config get"
+
+    config_svc = DIContainer.current().resolve(ConfigProtocol)
+
+    try:
+        value = config_svc.get(key)
+    except CommandError as exc:
+        if str(exc).startswith("Config key not found"):
+            emit_error_and_exit(
+                f"Config key not found: {key}",
+                code=2,
+                failure="not_found",
+                command=command,
+                fmt=fmt_lower,
+                quiet=quiet,
+                include_runtime=include_runtime,
+                debug=debug,
+                extra={"key": key},
+            )
+        emit_error_and_exit(
+            f"Failed to get config: {exc}",
+            code=1,
+            failure="get_failed",
+            command=command,
+            fmt=fmt_lower,
+            quiet=quiet,
+            include_runtime=include_runtime,
+            debug=debug,
+        )
+
+    def payload_builder(include_runtime: bool) -> dict[str, object]:
+        """Builds a payload containing the retrieved configuration value.
+
+        Args:
+            include_runtime (bool): If True, includes Python and platform info.
+
+        Returns:
+            dict[str, object]: A dictionary containing the key's value and
+                optional runtime metadata.
+        """
+        payload: dict[str, object] = {"value": value}
+        if include_runtime:
+            payload["python"] = ascii_safe(platform.python_version(), "python_version")
+            payload["platform"] = ascii_safe(platform.platform(), "platform")
+        return payload
+
+    new_run_command(
+        command_name=command,
+        payload_builder=payload_builder,
+        quiet=quiet,
+        verbose=verbose,
+        fmt=fmt_lower,
+        pretty=pretty,
+        debug=debug,
+    )

bijux_cli/commands/config/list_cmd.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Implements the `config list` subcommand for the Bijux CLI.
+
+This module contains the logic for listing all keys currently defined in the
+active configuration store. It retrieves the keys and presents them in a
+structured, machine-readable list format.
+
+Output Contract:
+    * Success: `{"items": [{"key": str}, ...]}`
+    * Verbose: Adds `{"python": str, "platform": str}` to the payload.
+    * Error:   `{"error": str, "code": int}`
+
+Exit Codes:
+    * `0`: Success.
+    * `1`: An unexpected error occurred while accessing the configuration.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import platform
+
+import typer
+
+from bijux_cli.commands.utilities import (
+    ascii_safe,
+    emit_error_and_exit,
+    new_run_command,
+    parse_global_flags,
+)
+from bijux_cli.contracts import ConfigProtocol
+from bijux_cli.core.constants import (
+    HELP_DEBUG,
+    HELP_FORMAT,
+    HELP_NO_PRETTY,
+    HELP_QUIET,
+    HELP_VERBOSE,
+)
+from bijux_cli.core.di import DIContainer
+
+
+def list_config(
+    ctx: typer.Context,
+    quiet: bool = typer.Option(False, "-q", "--quiet", help=HELP_QUIET),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help=HELP_VERBOSE),
+    fmt: str = typer.Option("json", "-f", "--format", help=HELP_FORMAT),
+    pretty: bool = typer.Option(True, "--pretty/--no-pretty", help=HELP_NO_PRETTY),
+    debug: bool = typer.Option(False, "-d", "--debug", help=HELP_DEBUG),
+) -> None:
+    """Lists all configuration keys from the active configuration store.
+
+    This function retrieves all defined keys, sorts them, and then uses the
+    `new_run_command` helper to emit them in a structured payload.
+
+    Args:
+        ctx (typer.Context): The Typer context for the CLI.
+        quiet (bool): If True, suppresses all output except for errors.
+        verbose (bool): If True, includes Python/platform details in the output.
+        fmt (str): The output format, "json" or "yaml".
+        pretty (bool): If True, pretty-prints the output.
+        debug (bool): If True, enables debug diagnostics.
+
+    Returns:
+        None:
+
+    Raises:
+        SystemExit: Always exits with a contract-compliant status code and
+            payload, indicating success or detailing the error.
+    """
+    flags = parse_global_flags()
+
+    quiet = flags["quiet"]
+    verbose = flags["verbose"]
+    fmt = flags["format"]
+    pretty = flags["pretty"]
+    debug = flags["debug"]
+
+    include_runtime = verbose
+    fmt_lower = fmt.lower()
+
+    command = "config list"
+
+    config_svc = DIContainer.current().resolve(ConfigProtocol)
+
+    try:
+        keys = config_svc.list_keys()
+    except Exception as exc:
+        emit_error_and_exit(
+            f"Failed to list config: {exc}",
+            code=1,
+            failure="list_failed",
+            command=command,
+            fmt=fmt_lower,
+            quiet=quiet,
+            include_runtime=include_runtime,
+            debug=debug,
+        )
+
+    def payload_builder(include_runtime: bool) -> Mapping[str, object]:
+        """Builds a payload containing the list of configuration keys.
+
+        Args:
+            include_runtime (bool): If True, includes Python and platform info.
+
+        Returns:
+            Mapping[str, object]: A dictionary containing a sorted list of
+                keys under an "items" field, plus optional runtime metadata.
+        """
+        payload: dict[str, object] = {
+            "items": [{"key": k} for k in sorted(keys, key=str.lower)]
+        }
+        if include_runtime:
+            payload["python"] = ascii_safe(platform.python_version(), "python_version")
+            payload["platform"] = ascii_safe(platform.platform(), "platform")
+        return payload
+
+    new_run_command(
+        command_name=command,
+        payload_builder=payload_builder,
+        quiet=quiet,
+        verbose=verbose,
+        fmt=fmt_lower,
+        pretty=pretty,
+        debug=debug,
+    )

bijux_cli/commands/config/load.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Implements the `config load` subcommand for the Bijux CLI.
+
+This module contains the logic for replacing the application's entire
+configuration with the contents of a specified file. It discards any
+in-memory settings and loads the new configuration, emitting a structured
+confirmation upon success.
+
+Output Contract:
+    * Success: `{"status": "loaded", "file": str}`
+    * Verbose: Adds `{"python": str, "platform": str}` to the payload.
+    * Error:   `{"error": str, "code": int}`
+
+Exit Codes:
+    * `0`: Success.
+    * `2`: The specified file could not be found, read, or parsed.
+"""
+
+from __future__ import annotations
+
+import platform
+
+import typer
+
+from bijux_cli.commands.utilities import (
+    ascii_safe,
+    emit_error_and_exit,
+    new_run_command,
+    parse_global_flags,
+)
+from bijux_cli.contracts import ConfigProtocol
+from bijux_cli.core.constants import (
+    HELP_DEBUG,
+    HELP_FORMAT,
+    HELP_NO_PRETTY,
+    HELP_QUIET,
+    HELP_VERBOSE,
+)
+from bijux_cli.core.di import DIContainer
+
+
+def load_config(
+    ctx: typer.Context,
+    path: str = typer.Argument(..., help="Path to load from"),
+    quiet: bool = typer.Option(False, "-q", "--quiet", help=HELP_QUIET),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help=HELP_VERBOSE),
+    fmt: str = typer.Option("json", "-f", "--format", help=HELP_FORMAT),
+    pretty: bool = typer.Option(True, "--pretty/--no-pretty", help=HELP_NO_PRETTY),
+    debug: bool = typer.Option(False, "-d", "--debug", help=HELP_DEBUG),
+) -> None:
+    """Loads configuration from a specified file.
+
+    This function replaces the current in-memory configuration with the
+    contents of the file at the given path. It provides a structured payload
+    to confirm the operation was successful.
+
+    Args:
+        ctx (typer.Context): The Typer context for the CLI.
+        path (str): The path to the configuration file to load.
+        quiet (bool): If True, suppresses all output except for errors.
+        verbose (bool): If True, includes Python/platform details in the output.
+        fmt (str): The output format, "json" or "yaml".
+        pretty (bool): If True, pretty-prints the output.
+        debug (bool): If True, enables debug diagnostics.
+
+    Returns:
+        None:
+
+    Raises:
+        SystemExit: Always exits with a contract-compliant status code and
+            payload, indicating success or detailing the error.
+    """
+    flags = parse_global_flags()
+
+    quiet = flags["quiet"]
+    verbose = flags["verbose"]
+    fmt = flags["format"]
+    pretty = flags["pretty"]
+    debug = flags["debug"]
+
+    include_runtime = verbose
+    fmt_lower = fmt.lower()
+
+    command = "config load"
+
+    config_svc = DIContainer.current().resolve(ConfigProtocol)
+
+    try:
+        config_svc.load(path)
+    except Exception as exc:
+        emit_error_and_exit(
+            f"Failed to load config: {exc}",
+            code=2,
+            failure="load_failed",
+            command=command,
+            fmt=fmt_lower,
+            quiet=quiet,
+            include_runtime=include_runtime,
+            debug=debug,
+            extra={"path": path},
+        )
+
+    def payload_builder(include_runtime: bool) -> dict[str, object]:
+        """Builds the payload confirming a successful configuration load.
+
+        Args:
+            include_runtime (bool): If True, includes Python and platform info.
+
+        Returns:
+            dict[str, object]: The structured payload.
+        """
+        payload: dict[str, object] = {"status": "loaded", "file": path}
+        if include_runtime:
+            payload["python"] = ascii_safe(platform.python_version(), "python_version")
+            payload["platform"] = ascii_safe(platform.platform(), "platform")
+        return payload
+
+    new_run_command(
+        command_name=command,
+        payload_builder=payload_builder,
+        quiet=quiet,
+        verbose=verbose,
+        fmt=fmt_lower,
+        pretty=pretty,
+        debug=debug,
+    )

bijux_cli/commands/config/reload.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Implements the `config reload` subcommand for the Bijux CLI.
+
+This module contains the logic for manually reloading the application's
+configuration from its source file on disk. It discards any in-memory
+settings and replaces them with the content of the configuration file,
+emitting a structured confirmation upon success.
+
+Output Contract:
+    * Success: `{"status": "reloaded"}`
+    * Verbose: Adds `{"python": str, "platform": str}` to the payload.
+    * Error:   `{"error": str, "code": int}`
+
+Exit Codes:
+    * `0`: Success.
+    * `2`: The configuration file could not be read or parsed.
+"""
+
+from __future__ import annotations
+
+import platform
+
+import typer
+
+from bijux_cli.commands.utilities import (
+    ascii_safe,
+    emit_error_and_exit,
+    new_run_command,
+    parse_global_flags,
+)
+from bijux_cli.contracts import ConfigProtocol
+from bijux_cli.core.constants import (
+    HELP_DEBUG,
+    HELP_FORMAT,
+    HELP_NO_PRETTY,
+    HELP_QUIET,
+    HELP_VERBOSE,
+)
+from bijux_cli.core.di import DIContainer
+
+
+def reload_config(
+    ctx: typer.Context,
+    quiet: bool = typer.Option(False, "-q", "--quiet", help=HELP_QUIET),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help=HELP_VERBOSE),
+    fmt: str = typer.Option("json", "-f", "--format", help=HELP_FORMAT),
+    pretty: bool = typer.Option(True, "--pretty/--no-pretty", help=HELP_NO_PRETTY),
+    debug: bool = typer.Option(False, "-d", "--debug", help=HELP_DEBUG),
+) -> None:
+    """Reloads the configuration from disk and emits a structured result.
+
+    This function forces a refresh of the application's configuration from its
+    persistent storage file. It is useful when the configuration has been
+    modified externally. A success or error payload is always emitted.
+
+    Args:
+        ctx (typer.Context): The Typer context for the CLI.
+        quiet (bool): If True, suppresses all output except for errors.
+        verbose (bool): If True, includes Python/platform details in the output.
+        fmt (str): The output format, "json" or "yaml".
+        pretty (bool): If True, pretty-prints the output.
+        debug (bool): If True, enables debug diagnostics.
+
+    Returns:
+        None:
+
+    Raises:
+        SystemExit: Always exits with a contract-compliant status code and
+            payload, indicating success or detailing the error.
+    """
+    flags = parse_global_flags()
+
+    quiet = flags["quiet"]
+    verbose = flags["verbose"]
+    fmt = flags["format"]
+    pretty = flags["pretty"]
+    debug = flags["debug"]
+
+    include_runtime = verbose
+    fmt_lower = fmt.lower()
+
+    command = "config reload"
+
+    config_svc = DIContainer.current().resolve(ConfigProtocol)
+
+    try:
+        config_svc.reload()
+    except Exception as exc:
+        emit_error_and_exit(
+            f"Failed to reload config: {exc}",
+            code=2,
+            failure="reload_failed",
+            command=command,
+            fmt=fmt_lower,
+            quiet=quiet,
+            include_runtime=include_runtime,
+            debug=debug,
+        )
+
+    def payload_builder(include_runtime: bool) -> dict[str, object]:
+        """Builds the payload confirming a successful configuration reload.
+
+        Args:
+            include_runtime (bool): If True, includes Python and platform info.
+
+        Returns:
+            dict[str, object]: The structured payload.
+        """
+        payload: dict[str, object] = {"status": "reloaded"}
+        if include_runtime:
+            payload["python"] = ascii_safe(platform.python_version(), "python_version")
+            payload["platform"] = ascii_safe(platform.platform(), "platform")
+        return payload
+
+    new_run_command(
+        command_name=command,
+        payload_builder=payload_builder,
+        quiet=quiet,
+        verbose=verbose,
+        fmt=fmt_lower,
+        pretty=pretty,
+        debug=debug,
+    )

bijux_cli/commands/config/service.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright © 2025 Bijan Mousavi
+
+"""Implements the root callback for the `bijux config` command group.
+
+This module defines the default action for the `bijux config` command. When
+invoked without a subcommand (like `get`, `set`, or `unset`), it lists all
+key-value pairs currently stored in the active configuration, presenting them
+in a structured, machine-readable format.
+
+Output Contract:
+    * Success: `{"KEY_1": "VALUE_1", "KEY_2": "VALUE_2", ...}`
+    * Verbose: Adds `{"python": str, "platform": str}` to the payload.
+    * Error:   `{"error": str, "code": int}`
+
+Exit Codes:
+    * `0`: Success.
+    * `1`: An unexpected error occurred while accessing the configuration.
+"""
+
+from __future__ import annotations
+
+import platform
+
+import typer
+
+from bijux_cli.commands.utilities import ascii_safe, new_run_command, parse_global_flags
+from bijux_cli.contracts import ConfigProtocol
+from bijux_cli.core.constants import (
+    HELP_DEBUG,
+    HELP_FORMAT,
+    HELP_NO_PRETTY,
+    HELP_QUIET,
+    HELP_VERBOSE,
+)
+from bijux_cli.core.di import DIContainer
+
+
+def config(
+    ctx: typer.Context,
+    quiet: bool = typer.Option(False, "-q", "--quiet", help=HELP_QUIET),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help=HELP_VERBOSE),
+    fmt: str = typer.Option("json", "-f", "--format", help=HELP_FORMAT),
+    pretty: bool = typer.Option(True, "--pretty/--no-pretty", help=HELP_NO_PRETTY),
+    debug: bool = typer.Option(False, "-d", "--debug", help=HELP_DEBUG),
+) -> None:
+    """Defines the entrypoint for the `bijux config` command group.
+
+    This function serves as the default action when `bijux config` is run
+    without a subcommand. It retrieves and displays all key-value pairs from
+    the current configuration. If a subcommand (`get`, `set`, etc.) is
+    invoked, this function yields control to it.
+
+    Args:
+        ctx (typer.Context): The Typer context for the CLI.
+        quiet (bool): If True, suppresses all output except for errors.
+        verbose (bool): If True, includes Python/platform details in the output.
+        fmt (str): The output format, "json" or "yaml".
+        pretty (bool): If True, pretty-prints the output.
+        debug (bool): If True, enables debug diagnostics.
+
+    Returns:
+        None:
+    """
+    if ctx.invoked_subcommand:
+        return
+
+    flags = parse_global_flags()
+
+    quiet = flags["quiet"]
+    verbose = flags["verbose"]
+    fmt = flags["format"]
+    pretty = flags["pretty"]
+    debug = flags["debug"]
+
+    fmt_lower = fmt.lower()
+
+    command = "config"
+
+    config_svc = DIContainer.current().resolve(ConfigProtocol)
+
+    def payload_builder(include_runtime: bool) -> dict[str, object]:
+        """Builds the payload containing all configuration values.
+
+        Args:
+            include_runtime (bool): If True, includes Python and platform info.
+
+        Returns:
+            dict[str, object]: A dictionary of all configuration key-value
+                pairs and optional runtime metadata.
+        """
+        data = config_svc.all()
+        payload: dict[str, object] = dict(data)
+        if include_runtime:
+            payload["python"] = ascii_safe(platform.python_version(), "python_version")
+            payload["platform"] = ascii_safe(platform.platform(), "platform")
+        return payload
+
+    new_run_command(
+        command_name=command,
+        payload_builder=payload_builder,
+        quiet=quiet,
+        verbose=verbose,
+        fmt=fmt_lower,
+        pretty=pretty,
+        debug=debug,
+    )