kash-shell 0.3.0__py3-none-any.whl

kash/commands/base/logs_commands.py

@@ -0,0 +1,92 @@
+import os
+
+from prettyfmt import fmt_lines
+
+from kash.commands.base.basic_file_commands import trash
+from kash.config.logger import get_log_settings, get_logger, reload_rich_logging_setup
+from kash.config.settings import (
+    LogLevel,
+    atomic_global_settings,
+    global_settings,
+    server_log_file_path,
+)
+from kash.exec import kash_command
+from kash.shell.output.shell_output import cprint, format_name_and_value, print_status
+from kash.shell.utils.native_utils import tail_file
+from kash.utils.common.format_utils import fmt_loc
+
+log = get_logger(__name__)
+
+
+@kash_command
+def logs(follow: bool = False) -> None:
+    """
+    Page through the logs for the current workspace.
+
+    :param follow: Follow the file as it grows.
+    """
+    tail_file(get_log_settings().log_file_path, follow=follow)
+
+
+@kash_command
+def clear_logs() -> None:
+    """
+    Clear the logs for the current workspace. Logs for the current workspace will be lost
+    permanently!
+    """
+    log_path = get_log_settings().log_file_path
+    if log_path.exists():
+        with open(log_path, "w"):
+            pass
+    obj_dir = get_log_settings().log_objects_dir
+    if obj_dir.exists():
+        trash(obj_dir)
+        os.makedirs(obj_dir, exist_ok=True)
+
+    print_status("Logs cleared:\n%s", fmt_lines([fmt_loc(log_path)]))
+
+
+@kash_command
+def log_level(level: str | None = None, console: bool = False, file: bool = False) -> None:
+    """
+    Set or show the log level. Applies to both console and file log levels unless specified.
+
+    :param level: The log level to set. If not specified, will show current level.
+    :param console: Set console log level only.
+    :param file: Set file log level only.
+    """
+    if not console and not file:
+        console = True
+        file = True
+
+    if level:
+        level_parsed = LogLevel.parse(level)
+        with atomic_global_settings().updates() as settings:
+            if console:
+                settings.console_log_level = level_parsed
+            if file:
+                settings.file_log_level = level_parsed
+
+        reload_rich_logging_setup()
+
+    settings = get_log_settings()
+    cprint(format_name_and_value("file_log_level", settings.log_file_level.name))
+    cprint(format_name_and_value("console_log_level", settings.log_console_level.name))
+
+
+@kash_command
+def log_settings() -> None:
+    """
+    Show the current log settings.
+    """
+    settings = get_log_settings()
+    cprint(format_name_and_value("log_dir", str(settings.log_dir)))
+    cprint(format_name_and_value("log_file_path", str(settings.log_file_path)))
+    cprint(format_name_and_value("log_objects_dir", str(settings.log_objects_dir)))
+    cprint(format_name_and_value("log_file_level", settings.log_file_level.name))
+    cprint(format_name_and_value("log_console_level", settings.log_console_level.name))
+    cprint(
+        format_name_and_value(
+            "server_log_file", str(server_log_file_path(global_settings().local_server_port))
+        )
+    )

kash/commands/base/reformat_command.py

@@ -0,0 +1,54 @@
+import os
+
+from prettyfmt import fmt_lines
+
+from kash.commands.base.basic_file_commands import trash
+from kash.commands.workspace.selection_commands import select
+from kash.config.logger import get_logger
+from kash.exec import assemble_path_args, kash_command, resolvable_paths
+from kash.exec_model.shell_model import ShellResult
+from kash.shell.output.shell_output import print_status
+from kash.text_handling.doc_normalization import normalize_text_file
+from kash.utils.common.format_utils import fmt_loc
+from kash.utils.file_utils.filename_parsing import join_filename, split_filename
+
+log = get_logger(__name__)
+
+
+@kash_command
+def reformat(*paths: str, inplace: bool = False) -> ShellResult:
+    """
+    Format text, Markdown, or HTML according to kash conventions.
+
+    TODO: Also handle JSON and YAML.
+
+    :param inplace: Overwrite the original file. Otherwise save to a new
+    file with `_formatted` appended to the original name.
+    """
+    resolved_paths = assemble_path_args(*paths)
+    final_paths = []
+
+    for path in resolved_paths:
+        target_path = None
+        dirname, name, item_type, ext = split_filename(path)
+        new_name = f"{name}_formatted"
+        target_path = join_filename(dirname, new_name, item_type, ext)
+
+        normalize_text_file(path, target_path=target_path)
+        if inplace:
+            trash(path)
+            os.rename(target_path, path)
+            print_status("Formatted:\n%s", fmt_lines([fmt_loc(path)]))
+            final_paths.append(path)
+        else:
+            print_status(
+                "Formatted:\n%s",
+                fmt_lines([f"{fmt_loc(path)} -> {fmt_loc(target_path)}"]),
+            )
+            final_paths.append(target_path)
+
+    resolvable = resolvable_paths(final_paths)
+    if resolvable:
+        select(*resolvable)
+
+    return ShellResult(show_selection=len(resolvable) > 0)

kash/commands/base/search_command.py

@@ -0,0 +1,65 @@
+from pathlib import Path
+
+from kash.config.logger import get_logger
+from kash.errors import InvalidState
+from kash.exec import assemble_path_args, kash_command
+from kash.exec_model.shell_model import ShellResult
+from kash.shell.output.shell_output import cprint
+from kash.shell.utils.sys_tool_deps import SysTool, sys_tool_check
+from kash.utils.common.parse_shell_args import shell_quote
+
+log = get_logger(__name__)
+
+
+@kash_command
+def search(
+    query_str: str,
+    *paths: str,
+    sort: str = "path",
+    ignore_case: bool = False,
+    verbose: bool = False,
+) -> ShellResult:
+    """
+    Search for a string in files at the given paths and return their store paths.
+    Useful to find all docs or resources matching a string or regex. This wraps
+    ripgrep.
+
+    Example: Look for all resource files containing the string "youtube.com",
+    sorted by date modified:
+
+    search "youtube.com" resources/ --sort=modified
+
+    :param sort: How to sort results. Can be `path` or `modified` or `created` (as with `rg`).
+    :param ignore_case: Ignore case when searching.
+    :param verbose: Also print the ripgrep command line.
+    """
+    sys_tool_check().require(SysTool.ripgrep)
+    from ripgrepy import RipGrepNotFound, Ripgrepy
+
+    resolved_paths = assemble_path_args(*paths)
+
+    strip_prefix = None
+    if not resolved_paths:
+        resolved_paths = (Path("."),)
+        strip_prefix = "./"
+    try:
+        rg = Ripgrepy(query_str, *[str(p) for p in resolved_paths])
+        rg = rg.files_with_matches().sort(sort)
+        if ignore_case:
+            rg = rg.ignore_case()
+        if verbose:
+            command = " ".join(
+                [shell_quote(arg) for arg in rg.command]
+                + [query_str]
+                + [str(p) for p in resolved_paths]
+            )
+            cprint(f"{command}")
+        rg_output = rg.run().as_string
+        results: list[str] = [
+            line.lstrip(strip_prefix) if strip_prefix and line.startswith(strip_prefix) else line
+            for line in rg_output.splitlines()
+        ]
+
+        return ShellResult(results, show_result=True)
+    except RipGrepNotFound:
+        raise InvalidState("`rg` command not found. Install ripgrep to use the search command.")

kash/commands/base/show_command.py

@@ -0,0 +1,69 @@
+from kash.config.logger import get_logger
+from kash.config.text_styles import STYLE_HINT
+from kash.errors import InvalidInput, InvalidState
+from kash.exec import assemble_path_args, kash_command
+from kash.model.paths_model import StorePath
+from kash.shell.output.shell_output import cprint
+from kash.shell.utils.native_utils import ViewMode, terminal_show_image, view_file_native
+from kash.web_content.file_cache_utils import cache_file
+from kash.workspaces import current_ws
+
+log = get_logger(__name__)
+
+
+@kash_command
+def show(
+    path: str | None = None,
+    console: bool = False,
+    native: bool = False,
+    thumbnail: bool = False,
+    browser: bool = False,
+) -> None:
+    """
+    Show the contents of a file if one is given, or the first file if multiple files
+    are selected. Will try to use native apps or web browser to display the file if
+    appropriate, and otherwise display the file in the console.
+
+    Will use `bat` if available to show files in the console, including syntax
+    highlighting and git diffs.
+
+    :param console: Force display to console (not browser or native apps).
+    :param native: Force display with a native app (depending on your system configuration).
+    :param thumbnail: If there is a thumbnail image, show it too.
+    :param browser: Force display with your default web browser.
+    """
+    view_mode = (
+        ViewMode.console
+        if console
+        else ViewMode.browser
+        if browser
+        else ViewMode.native
+        if native
+        else ViewMode.auto
+    )
+    try:
+        input_paths = assemble_path_args(path)
+        input_path = input_paths[0]
+
+        if isinstance(input_path, StorePath):
+            ws = current_ws()
+            if input_path.is_file():
+                # Optionally, if we can inline display the image (like in kitty) above the text representation, do that.
+                item = ws.load(input_path)
+                if thumbnail and item.thumbnail_url:
+                    try:
+                        local_path, _was_cached = cache_file(item.thumbnail_url)
+                        terminal_show_image(local_path)
+                    except Exception as e:
+                        log.info("Had trouble showing thumbnail image (will skip): %s", e)
+                        cprint(f"[Image: {item.thumbnail_url}]", style=STYLE_HINT)
+
+            view_file_native(ws.base_dir / input_path, view_mode=view_mode)
+        else:
+            view_file_native(input_path, view_mode=view_mode)
+    except (InvalidInput, InvalidState):
+        if path:
+            # If path is absolute or we couldbn't get a selection, just show the file.
+            view_file_native(path, view_mode=view_mode)
+        else:
+            raise InvalidInput("No selection")

kash/commands/extras/utils_commands.py

@@ -0,0 +1,27 @@
+from flowmark import Wrap
+from rich.text import Text
+
+from kash.exec import kash_command
+from kash.shell.output.shell_output import cprint
+
+
+@kash_command
+def explain_unicode(text: str) -> None:
+    """
+    Explain the Unicode characters in the given text, showing their hex code and their full Unicode name.
+    """
+    import unicodedata
+
+    def unicode_char_name(char: str) -> str:
+        try:
+            return unicodedata.name(char)
+        except ValueError:
+            return hex(ord(char))
+
+    for i, char in enumerate(text):
+        cprint(
+            Text.from_markup(
+                f"[hint]{i:05d}[/hint]: [key]{char}[/key] [hint]([/hint][emph]{unicode_char_name(char)}[/emph][hint])[/hint]"
+            ),
+            text_wrap=Wrap.NONE,
+        )

kash/commands/help/assistant_commands.py

@@ -0,0 +1,97 @@
+from rich import get_console
+
+from kash.commands.base.basic_file_commands import trash
+from kash.commands.workspace.selection_commands import select
+from kash.config.logger import get_logger
+from kash.config.text_styles import PROMPT_ASSIST, SPINNER
+from kash.exec import kash_command
+from kash.exec_model.shell_model import ShellResult
+from kash.form_input.prompt_input import prompt_simple_string
+from kash.help.assistant import (
+    AssistanceType,
+    assist_system_message_with_state,
+    shell_context_assistance,
+)
+from kash.llm_utils.language_models import LLM
+from kash.model.items_model import Item, ItemType
+from kash.shell.utils.native_utils import tail_file
+from kash.utils.file_utils.file_formats_model import Format
+from kash.workspaces import current_ws
+
+log = get_logger(__name__)
+
+
+@kash_command
+def assist(
+    input: str | None = None,
+    model: LLM | None = None,
+    type: AssistanceType = AssistanceType.basic,
+) -> None:
+    """
+    Invoke the kash assistant. You don't normally need this command as it is the same as just
+    asking a question (a question ending with ?) on the kash console.
+
+    :param type: The type of assistance to use.
+    :param model: The model to use for the assistant. If not provided, the default model
+        for the assistant type is used.
+    """
+    if not input:
+        input = prompt_simple_string(
+            "What do you need help with? (Ask any question or press enter to see main `help` page.)",
+            prompt_symbol=PROMPT_ASSIST,
+        )
+        if not input.strip():
+            help()
+            return
+
+    with get_console().status("Thinking…", spinner=SPINNER):
+        shell_context_assistance(input, model=model, assistance_type=type)
+
+
+@kash_command
+def assistant_system_message(
+    is_structured: bool = False, skip_api_docs: bool = False
+) -> ShellResult:
+    """
+    Save the assistant system message. Useful for debugging.
+    """
+
+    item = Item(
+        type=ItemType.export,
+        title="Assistant System Message",
+        format=Format.markdown,
+        body=assist_system_message_with_state(
+            is_structured=is_structured, skip_api_docs=skip_api_docs
+        ),
+    )
+    ws = current_ws()
+    store_path = ws.save(item, as_tmp=True)
+
+    log.message("Saved assistant system message to %s", store_path)
+
+    select(store_path)
+
+    return ShellResult(show_selection=True)
+
+
+@kash_command
+def assistant_history(follow: bool = False) -> None:
+    """
+    Show the assistant history for the current workspace.
+
+    :param follow: Follow the file as it grows.
+    """
+    ws = current_ws()
+    tail_file(ws.base_dir / ws.dirs.assistant_history_yml, follow=follow)
+
+
+@kash_command
+def clear_assistant() -> None:
+    """
+    Clear the assistant history for the current workspace. Old history file will be
+    moved to the trash.
+    """
+    ws = current_ws()
+    path = ws.base_dir / ws.dirs.assistant_history_yml
+    if path.exists():
+        trash(path)

kash/commands/help/doc_commands.py

@@ -0,0 +1,226 @@
+import re
+from pathlib import Path
+
+from rich.box import SQUARE
+from rich.console import Group
+from rich.panel import Panel
+from rich.text import Text
+
+from kash.config.colors import rich_terminal_dark
+from kash.config.logger import get_logger, record_console
+from kash.config.text_styles import (
+    COLOR_HINT,
+    CONSOLE_WRAP_WIDTH,
+    LOGO_LARGE,
+    STYLE_EMPH,
+    STYLE_LOGO,
+    TAGLINE_STYLED,
+)
+from kash.docs.all_docs import all_docs
+from kash.exec import kash_command
+from kash.help.help_pages import print_see_also
+from kash.shell.output.shell_output import PrintHooks, console_pager, cprint, print_markdown
+from kash.utils.rich_custom.rich_markdown_fork import Markdown
+from kash.version import get_version_name
+
+log = get_logger(__name__)
+
+
+# Break the line into non-space and space chunks by using a regex.
+# Colorize each chunk and optionally swap lines to spaces.
+def logo_colorize_line(line: str, space_replacement: str = " ", line_offset: int = 0) -> Text:
+    line = " " * line_offset + line
+    bits = re.findall(r"[^\s]+|\s+", line)
+    texts = []
+    solid_count = 0
+    for i, bit in enumerate(bits):
+        if bit.strip():
+            texts.append(
+                Text(
+                    bit,
+                    style=STYLE_LOGO if solid_count > 0 else STYLE_EMPH,
+                )
+            )
+            solid_count += 1
+        else:
+            bit = re.sub(r" ", space_replacement, bit)
+            if i > 0:
+                bit = " " + bit[1:]
+            if i < len(bits) - 1:
+                bit = bit[:-1] + " "
+            texts.append(Text(bit, style=COLOR_HINT))
+    return Text.assemble(*texts)
+
+
+def color_logo() -> Group:
+    logo_lines = LOGO_LARGE.split("\n")
+    left_margin = 2
+    offset = 2
+    return Group(
+        *[logo_colorize_line(line, " ", left_margin + offset) for line in logo_lines],
+        Text.assemble(" " * left_margin, TAGLINE_STYLED),
+    )
+
+
+def branded_box(content: Group | None, version: str | None = None) -> Panel:
+    line_char = "─"
+    panel_width = CONSOLE_WRAP_WIDTH
+
+    logo_lines = LOGO_LARGE.split("\n")
+    logo_top = logo_colorize_line(logo_lines[0], line_char)
+    offset = (panel_width - 4 - len(logo_top)) // 2
+    tagline_offset = (panel_width - 4 - len(TAGLINE_STYLED)) // 2 + 1
+
+    logo_rest = [logo_colorize_line(line, " ", offset) for line in logo_lines[1:]]
+    if version:
+        header = Text.assemble(*logo_top)
+        footer = Text(version, style=COLOR_HINT, justify="right")
+    else:
+        header = Text.assemble(*logo_top)
+        footer = None
+
+    body = ["", content] if content else []
+
+    return Panel(
+        Group(
+            *logo_rest,
+            "",
+            Text.assemble(" " * tagline_offset, TAGLINE_STYLED),
+            # Text(" " * tagline_offset + "🮎" * len(TAGLINE_STYLED), style=STYLE_EMPH),
+            *body,
+        ),
+        title=header,
+        title_align="center",
+        subtitle=footer,
+        subtitle_align="right",
+        border_style=COLOR_HINT,
+        padding=(0, 1),
+        width=panel_width,
+        box=SQUARE,
+    )
+
+
+@kash_command
+def kash_logo(box: bool = False, svg_out: str | None = None, html_out: str | None = None) -> None:
+    """
+    Show the kash logo.
+    """
+    logo = branded_box(None) if box else color_logo()
+
+    cprint(logo)
+
+    if svg_out:
+        with record_console() as console:
+            console.print(logo)
+        with Path(svg_out).open("w") as f:
+            f.write(console.export_svg(theme=rich_terminal_dark))
+        log.message(f"Wrote logo: {svg_out}")
+    if html_out:
+        with record_console() as console:
+            console.print(logo)
+        with Path(html_out).open("w") as f:
+            f.write(console.export_html(theme=rich_terminal_dark))
+        log.message(f"Wrote logo: {html_out}")
+
+
+@kash_command
+def welcome() -> None:
+    """
+    Print a welcome message.
+    """
+
+    help_topics = all_docs.help_topics
+    version = get_version_name()
+    # Create header with logo and right-justified version
+
+    PrintHooks.before_welcome()
+    cprint(
+        branded_box(
+            Group(Markdown(help_topics.welcome)),
+            version,
+        )
+    )
+    cprint(Panel(Markdown(help_topics.warning), box=SQUARE, border_style=COLOR_HINT))
+
+
+@kash_command
+def manual(no_pager: bool = False) -> None:
+    """
+    Show the kash full manual with all help pages.
+    """
+    # TODO: Take an argument to show help for a specific command or action.
+
+    from kash.help.help_pages import print_manual
+
+    with console_pager(use_pager=not no_pager):
+        print_manual()
+
+
+@kash_command
+def why_kash() -> None:
+    """
+    Show help on why kash was created.
+    """
+    help_topics = all_docs.help_topics
+    with console_pager():
+        print_markdown(help_topics.what_is_kash)
+        print_markdown(help_topics.philosophy_of_kash)
+        print_see_also(["help", "getting_started", "faq", "commands", "actions"])
+
+
+@kash_command
+def installation() -> None:
+    """
+    Show help on installing kash.
+    """
+    help_topics = all_docs.help_topics
+    with console_pager():
+        print_markdown(help_topics.installation)
+        print_see_also(
+            [
+                "What is kash?",
+                "What can I do with kash?",
+                "getting_started",
+                "What are the most important kash commands?",
+                "commands",
+                "actions",
+                "check_tools",
+                "faq",
+            ]
+        )
+
+
+@kash_command
+def getting_started() -> None:
+    """
+    Show help on getting started using kash.
+    """
+    help_topics = all_docs.help_topics
+    with console_pager():
+        print_markdown(help_topics.getting_started)
+        print_see_also(
+            [
+                "What is kash?",
+                "What can I do with kash?",
+                "What are the most important kash commands?",
+                "commands",
+                "actions",
+                "check_tools",
+                "faq",
+            ]
+        )
+
+
+@kash_command
+def faq() -> None:
+    """
+    Show the kash FAQ.
+    """
+    help_topics = all_docs.help_topics
+    with console_pager():
+        print_markdown(help_topics.faq)
+
+        print_see_also(["help", "commands", "actions"])
+
+
+DOC_COMMANDS = [welcome, manual, why_kash, getting_started, faq]