cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/cli/app.py

@@ -0,0 +1,125 @@
+import uuid
+from typing import Annotated
+
+import typer
+
+from cmdbox import container
+from cmdbox.cli.commands.alias_fallback import AliasFallbackGroup
+from cmdbox.cli.ui.presenters.app_presenter import render_version
+from cmdbox.logging_setup.log_handlers import configure_logging
+from cmdbox.logging_setup.log_config import build_log_config, get_logger
+from cmdbox.version import __version__
+from cmdbox.database import ensure_schema, get_db
+from .commands.command_crud import app as command_crud_app
+from .commands.command_run import app as command_run_app
+from .commands.variable_crud import app as variable_crud_app
+from .commands.tag_crud import app as tag_crud_app
+from .commands.init import app as init_app
+from .commands.settings import app as settings_app
+from .commands.history import app as history_app
+
+app = typer.Typer(
+    name="cb",
+    cls=AliasFallbackGroup,
+    help="CmdBox is a CLI tool for storing and recalling commands with many helpful quality of life features.",
+    no_args_is_help=True,
+)
+
+app.add_typer(
+    command_crud_app,
+    name="cmd",
+    help="CRUD (Create, Read, Update, Delete) operations for commands.",
+)
+app.add_typer(variable_crud_app, name="var", help="CRUD operations for variables.")
+app.add_typer(tag_crud_app, name="tag", help="CRUD operations for tags.")
+app.add_typer(command_run_app)
+app.add_typer(init_app)
+app.add_typer(settings_app, name="settings", help="Manage CmdBox settings.")
+app.add_typer(
+    history_app, name="history", help="View and re-run command execution history."
+)
+
+
+def version_callback(value: bool):
+    if value:
+        console = container.get_console()
+        rendered_version = render_version(__version__)
+        console.print(rendered_version)
+        raise typer.Exit()
+
+
+@app.callback()
+def common(
+    test: Annotated[
+        bool,
+        typer.Option(
+            "--test",
+            "-t",
+            help="Enables testing mode.  Database will be created in memory and will not affect the "
+            "applications persistent database.",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable additional diagnostic output in the terminal. Sets console log level to INFO.",
+        ),
+    ] = False,
+    debug: Annotated[
+        bool,
+        typer.Option(
+            "--debug",
+            "-d",
+            help="Enable full diagnostic output in the terminal. Sets console log level to DEBUG.",
+        ),
+    ] = False,
+    file_logs: Annotated[
+        bool | None,
+        typer.Option(
+            "--file-logs/--no-file-logs",
+            help="Enable/disables writing diagnostic logs to a file. Defaults to settings.",
+        ),
+    ] = None,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=version_callback,
+            is_eager=True,
+            help="Print the app version and exit.",
+        ),
+    ] = None,
+) -> None:
+    if test:
+        get_db(testing=True)
+
+    settings = container.get_settings()
+
+    run_id = uuid.uuid4().hex[:6]
+    log_config = build_log_config(
+        settings=settings, verbose=verbose, debug=debug, file_logs=file_logs
+    )
+    configure_logging(log_config, run_id=run_id)
+
+    log = get_logger()
+    log.debug(
+        f"startup: test={test}, verbose={verbose}, debug={debug}, file_logs={file_logs}"
+    )
+    log.debug(f"file_logging={log_config.file_enabled} path={log_config.file_path}")
+
+    ensure_schema()
+
+    if test:
+        console = container.get_console()
+        console.info("Testing mode is active, database is in memory.")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

cmdbox/cli/commands/alias_fallback.py

@@ -0,0 +1,102 @@
+import click
+from typer.core import TyperGroup
+
+
+class AliasFallbackGroup(TyperGroup):
+    """
+    Handles command grouping with support for alias-based fallback.
+
+    This class extends the functionality of TyperGroup to include command alias
+    resolution. When a command is not directly found, it attempts to resolve the
+    command name using a predefined alias mapping and dynamically generates an
+    alias command that forwards its arguments to a core `run` command. This allows
+    users to define shorter or alternate names for commands while maintaining
+    flexibility.
+
+    Attributes:
+        _command_aliases (dict[str, str]): A mapping of alias names to their
+            corresponding actual command names. Used for resolving commands
+            through aliases.
+    """
+
+    _command_aliases: dict[str, str] = {
+        "cmds": "cmd",
+        "vars": "var",
+        "tags": "tag",
+        "hist": "history",
+    }
+
+    """
+    The second item in the list is the name of the command as configured by
+    `@app.command("command_name")`, not the method name. Further items in the list
+    will be supplied to that sub-command as args.
+    """
+    _shortcut_commands: dict[str, list[str]] = {"!!": ["history", "last"]}
+
+    def get_command(self, ctx: click.Context, cmd_name: str):
+        """
+        Retrieves a command based on the command name, creating an alias command if
+        the command was not directly found.
+
+        If the command corresponding to `cmd_name` doesn't exist, a new alias
+        command is generated using the `run` command, forwarding all its parameters
+        except the `alias` parameter.
+
+        Args:
+            ctx (click.Context): The Click context in which the command is being
+                invoked.
+            cmd_name (str): The name of the command to retrieve.
+
+        Returns:
+            click.Command: The command object corresponding to the given
+            `cmd_name`, or an alias command if the original command does not exist.
+            Returns None if `run` command is also unavailable.
+        """
+        cmd_name = self._command_aliases.get(cmd_name, cmd_name)
+
+        rv = super().get_command(ctx, cmd_name)
+        if rv is not None:
+            return rv
+
+        run_cmd = super().get_command(ctx, "run")
+        if run_cmd is None:
+            return None
+
+        forwarded_params = [p for p in run_cmd.params if p.name != "alias"]
+
+        @click.command(
+            cmd_name,
+            params=forwarded_params,
+            help=f"Run stored command '{cmd_name}'.",
+            context_settings=run_cmd.context_settings,
+        )
+        @click.pass_context
+        def _alias_cmd(inner_ctx: click.Context, **kwargs):
+            inner_ctx.meta["_extra_args"] = inner_ctx.args[:]
+            inner_ctx.invoke(run_cmd, alias=cmd_name, **kwargs)
+
+        return _alias_cmd
+
+    def resolve_command(self, ctx: click.Context, args: list):
+        """
+        Resolves the command by expanding shortcut commands if applicable.
+
+        This method checks whether the provided command arguments include a shortcut
+        command. If a shortcut command is detected, it is expanded into its full form
+        and the resulting extended argument list is passed to the parent class's
+        `resolve_command` method. If no shortcut is found, the original argument list
+        is passed directly.
+
+        Args:
+            ctx (click.Context): The Click context containing information about the
+                execution of the command.
+            args (list): A list of command-line arguments passed to the command.
+
+        Returns:
+            tuple: A tuple containing the command name, the command object, and a list
+            of remaining arguments.
+        """
+        if args and args[0] in self._shortcut_commands:
+            expanded = self._shortcut_commands[args[0]]
+            return super().resolve_command(ctx, expanded + list(args[1:]))
+        return super().resolve_command(ctx, args)

cmdbox/cli/commands/command_crud.py

@@ -0,0 +1,429 @@
+from typing import Annotated
+import logging
+
+import typer
+
+from cmdbox import container
+from cmdbox.cli.common.errors import make_cli_guard
+from cmdbox.cli.completions.commands import complete_command_aliases
+from cmdbox.cli.completions.fields import (
+    command_field_options,
+    command_editable_field_options,
+)
+from cmdbox.cli.completions.tags import complete_tag_names
+from cmdbox.cli.handlers import command_handlers
+
+app = typer.Typer(no_args_is_help=True)
+
+cli_guard = make_cli_guard(container.get_console)
+
+log = logging.getLogger(__name__)
+
+
+@app.command("add")
+@cli_guard
+def add(
+    alias: Annotated[
+        str,
+        typer.Argument(
+            help="The name of the command.  Will be used to recall the command."
+        ),
+    ] = None,
+    template: Annotated[
+        str,
+        typer.Argument(
+            help="The actual command value that will be executed when the command is recalled using the alias."
+        ),
+    ] = None,
+    description: Annotated[
+        str, typer.Option("--description", "-d", help="A description of the command.")
+    ] = None,
+    tags: Annotated[
+        list[str],
+        typer.Option(
+            "--tags",
+            "-t",
+            help="A list of tags to associate with the command, separated by commas.",
+            autocompletion=complete_tag_names,
+        ),
+    ] = None,
+    cwd: Annotated[
+        str,
+        typer.Option("--cwd", "-c", help="Working directory to run the command from."),
+    ] = None,
+    shell: Annotated[
+        str,
+        typer.Option("--shell", "-s", help="Shell to use when running the command."),
+    ] = None,
+    env: Annotated[
+        list[str],
+        typer.Option(
+            "--env",
+            "-e",
+            help="Environment variable to set when running the command, in KEY=VALUE format.",
+        ),
+    ] = None,
+    timeout: Annotated[
+        int,
+        typer.Option(
+            "--timeout",
+            "-o",
+            help="Maximum number of seconds before the process is killed.",
+        ),
+    ] = None,
+    interactive: Annotated[
+        bool,
+        typer.Option("--interactive", "-i", is_flag=True, help="Interactive mode."),
+    ] = False,
+) -> None:
+    """
+    Adds a new command with an alias, a template, description, and tags. The command
+    can be created in interactive if no options are provided or the `--interactive`
+    flag is used.
+    """
+    log.debug("cmd.add called. alias=%s, interactive=%s", alias, interactive)
+    add_cmd_args = command_handlers.AddCommandArgs(
+        alias=alias,
+        template=template,
+        description=description,
+        tags=tags,
+        cwd=cwd,
+        shell=shell,
+        env=env,
+        timeout=timeout,
+        interactive=interactive,
+    )
+    command_handlers.run_add_command(
+        args=add_cmd_args,
+        get_cmd_services=container.get_command_services,
+        get_tag_services=container.get_tag_services,
+        get_console=container.get_console,
+    )
+
+
+@app.command("get")
+@cli_guard
+def get(
+    alias: Annotated[
+        str,
+        typer.Argument(
+            help="The alias of the command to retrieve.",
+            autocompletion=complete_command_aliases,
+        ),
+    ],
+) -> None:
+    """
+    Retrieves and displays a saved command stored under the provided alias.
+    """
+    log.debug("cmd.get called. alias=%s", alias)
+    command_handlers.run_get_command(
+        alias=alias,
+        get_cmd_services=container.get_command_services,
+        get_console=container.get_console,
+    )
+
+
+@app.command("update")
+@cli_guard
+def update(
+    alias: Annotated[
+        str,
+        typer.Argument(
+            help="The alias of the command to update.",
+            autocompletion=complete_command_aliases,
+        ),
+    ],
+    template: Annotated[
+        str, typer.Option("--template", "-t", help="The new template.")
+    ] = None,
+    description: Annotated[
+        str, typer.Option("--description", "-d", help="The new description.")
+    ] = None,
+    new_alias: Annotated[
+        str, typer.Option("--alias", "-a", help="The new alias.")
+    ] = None,
+    cwd: Annotated[
+        str,
+        typer.Option("--cwd", "-c", help="Working directory to run the command from."),
+    ] = None,
+    shell: Annotated[
+        str,
+        typer.Option("--shell", "-s", help="Shell to use when running the command."),
+    ] = None,
+    env: Annotated[
+        list[str],
+        typer.Option(
+            "--env",
+            "-e",
+            help="Environment variable to set when running the command, in KEY=VALUE format.",
+        ),
+    ] = None,
+    timeout: Annotated[
+        int,
+        typer.Option(
+            "--timeout",
+            "-o",
+            help="Maximum number of seconds before the process is killed.",
+        ),
+    ] = None,
+    set_: Annotated[
+        list[str],
+        typer.Option(
+            "--set",
+            "-s",
+            help="A list of key=value pairs to update.",
+            autocompletion=command_editable_field_options,
+        ),
+    ] = None,
+    edit_mode: Annotated[
+        bool,
+        typer.Option("--edit", "-e", help="Edit mode."),
+    ] = False,
+    edit_fields: Annotated[
+        str,
+        typer.Option(
+            "--edit-fields",
+            help="A list of fields to be edited in edit mode, separated by commas. Defaults to all fields.",
+        ),
+    ] = None,
+) -> None:
+    """
+    Updates an existing command with the provided options. Each field can be updated
+    individually or in bulk using the `--set` option. Using the `--edit` option enables
+    editing the already stored values in an interactive mode.
+    """
+    log.debug(
+        "cmd.update called. alias=%s template_provided=%s description_provided=%s new_alias_provided=%s "
+        "set_used=%s, edit_mode=%s, edit_fields=%s",
+        alias,
+        template is not None,
+        description is not None,
+        new_alias is not None,
+        set_ is not None,
+        edit_mode,
+        edit_fields,
+    )
+    command_handlers.run_update_command(
+        alias=alias,
+        template=template,
+        description=description,
+        new_alias=new_alias,
+        cwd=cwd,
+        shell=shell,
+        env=env,
+        timeout=timeout,
+        set_pairs=set_,
+        edit_mode=edit_mode,
+        edit_fields=edit_fields,
+        get_cmd_services=container.get_command_services,
+        get_settings=container.get_settings,
+        get_console=container.get_console,
+    )
+
+
+app.command("edit", hidden=True)(update)
+
+
+@app.command("list")
+@cli_guard
+def list_cmds(
+    order: Annotated[
+        str,
+        typer.Option(
+            "--order",
+            "-o",
+            help="The field to order the results by.",
+            autocompletion=command_field_options,
+        ),
+    ] = "alias",
+    tags: Annotated[
+        list[str],
+        typer.Option(
+            "--tag",
+            "-t",
+            help="The tag to filter by.",
+            autocompletion=complete_tag_names,
+        ),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="The maximum number of results to return."),
+    ] = 10,
+    fields: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--field",
+            "-f",
+            help="The field(s) to display in the results list. Defaults fields in settings.",
+            autocompletion=command_field_options,
+        ),
+    ] = None,
+) -> None:
+    """
+    Displays all stored commands in a list format. The number of results can be limited
+    with the `--limit` option. The output fields can be customized with the `--field` option.
+    """
+    log.debug(
+        "cmd.list called. order=%s, tags=%s, limit=%s, fields=%s",
+        order,
+        tags,
+        limit,
+        fields,
+    )
+    command_handlers.run_list_command(
+        limit=limit,
+        order=order,
+        tags=tags,
+        fields=fields,
+        get_cmd_services=container.get_command_services,
+        get_settings=container.get_settings,
+        get_console=container.get_console,
+        get_display_field_resolver=container.get_command_display_field_resolver,
+    )
+
+
+app.command("ls", hidden=True)(list_cmds)
+
+
+@app.command("search")
+@cli_guard
+def search(
+    term: Annotated[str, typer.Argument(help="The search term to use.")],
+    limit: Annotated[
+        int, typer.Option(help="The maximum number of results to return.")
+    ] = 10,
+    search_fields: Annotated[
+        list[str],
+        typer.Option(
+            "--in",
+            "-i",
+            help="The fields to search within.",
+            autocompletion=command_field_options,
+        ),
+    ] = None,
+    fields: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--field",
+            "-f",
+            help="The field(s) to display in the results list. Defaults to all fields.",
+            autocompletion=command_field_options,
+        ),
+    ] = None,
+) -> None:
+    """
+    Searches the database for commands matching the provided search term. The search fields
+    can be customized with the `--in` option. The output fields can be customized with the
+    `--field` option.
+    """
+    log.debug(
+        "cmd.search called. term=%s, limit=%s, search_fields=%s, fields=%s",
+        term,
+        limit,
+        search_fields,
+        fields,
+    )
+    command_handlers.run_search_command(
+        term=term,
+        limit=limit,
+        search_fields=search_fields,
+        fields=fields,
+        get_cmd_services=container.get_command_services,
+        get_settings=container.get_settings,
+        get_console=container.get_console,
+        get_display_field_resolver=container.get_command_display_field_resolver,
+        get_search_field_resolver=container.get_command_search_field_resolver,
+    )
+
+
+app.command("find", hidden=True)(search)
+
+
+@app.command("delete")
+@cli_guard
+def delete(
+    alias: Annotated[
+        str,
+        typer.Argument(
+            help="The alias of the command to delete.",
+            autocompletion=complete_command_aliases,
+        ),
+    ],
+) -> None:
+    """
+    Deletes the command stored under the provided alias.
+    """
+    log.debug("cmd.delete called. alias=%s", alias)
+    command_handlers.run_delete_command(
+        alias=alias,
+        get_cmd_services=container.get_command_services,
+        get_console=container.get_console,
+    )
+
+
+app.command("del", hidden=True)(delete)
+app.command("rm", hidden=True)(delete)
+app.command("remove", hidden=True)(delete)
+
+
+@app.command("tag")
+@cli_guard
+def add_tags(
+    alias: Annotated[
+        str,
+        typer.Argument(
+            help="The alias of the command to tag.",
+            autocompletion=complete_command_aliases,
+        ),
+    ] = None,
+    tags: Annotated[
+        list[str],
+        typer.Argument(
+            help="The tags to add to the command, separated by commas.",
+            autocompletion=complete_tag_names,
+        ),
+    ] = None,
+) -> None:
+    """
+    Adds the provided tags to the command stored under the provided alias. Tags must
+    be existing.
+    """
+    log.debug("cmd.tag.add called. alias=%s, tags=%s", alias, tags)
+    command_handlers.run_attach_tags(
+        alias=alias,
+        tag_names=tags,
+        get_cmd_services=container.get_command_services,
+        get_tag_services=container.get_tag_services,
+        get_console=container.get_console,
+    )
+
+
+@app.command("untag")
+@cli_guard
+def remove_tags(
+    alias: Annotated[
+        str,
+        typer.Argument(
+            help="The alias of the command to untag.",
+            autocompletion=complete_command_aliases,
+        ),
+    ] = None,
+    tags: Annotated[
+        list[str],
+        typer.Argument(
+            help="The tags to remove from the command, separated by commas.",
+            autocompletion=complete_tag_names,
+        ),
+    ] = None,
+) -> None:
+    """
+    Removes the provided tags from the command stored under the provided alias.
+    """
+    log.debug("cmd.tag.remove called. alias=%s, tags=%s", alias, tags)
+    command_handlers.run_detach_tags(
+        alias=alias,
+        tag_names=tags,
+        get_cmd_services=container.get_command_services,
+        get_tag_services=container.get_tag_services,
+        get_console=container.get_console,
+    )