kash-shell 0.3.0__py3-none-any.whl

kash/actions/meta/write_new_action.py

@@ -0,0 +1,157 @@
+from flowmark import Wrap, fill_text
+
+from kash.actions.meta.write_instructions import write_instructions
+from kash.config.logger import get_logger
+from kash.errors import ApiResultError, InvalidInput
+from kash.exec import kash_action
+from kash.exec.preconditions import is_instructions
+from kash.help.assistant import assist_preamble, assistance_structured
+from kash.help.assistant_output import print_assistant_response
+from kash.llm_utils.chat_format import ChatHistory, ChatMessage, ChatRole
+from kash.llm_utils.language_models import LLMName
+from kash.model import (
+    LLM,
+    ONE_OR_NO_ARGS,
+    ActionInput,
+    ActionResult,
+    Format,
+    ItemType,
+    Message,
+    TitleTemplate,
+    common_params,
+)
+from kash.utils.common.lazyobject import lazyobject
+from kash.utils.common.type_utils import not_none
+
+log = get_logger(__name__)
+
+
+@lazyobject
+def write_action_instructions() -> str:
+    from kash.docs.load_source_code import load_source_code
+
+    return (
+        """
+        You are a senior software engineer who writes clean code exactly
+        conforming with existing practice using the kash framework, which you understand
+        clearly. You always want to write actions that are helpful and reusable
+        as command-line operations or as Python libraries, since kash makes
+        commands and actions available to use both ways.
+
+        You need to write Python code to implement an action or a command in kash.
+        
+        Guidelines:
+
+        - Provide Python code in the python_code field.
+
+        - Choose a command implementation (with @kash_command decorating a function) if the
+          operation is very simple and does not have files (Items) to output. To just read
+          a file and show information, or print something, use a command. Choose an
+          action implementation (with @kash_action decorating a class) if the operation
+          has files (Items) to output.
+        
+        - Add non-code commentary in the response_text field explaining any issues or
+          assumptions you made while writing the code.
+
+        - If desired behavior of the code is not clear from the description, add
+          comment placeholders in the code so it can be filled in later.
+
+        - If the user gives other random context, like a previous conversation, consider
+          how you would implement a command or action that would generalize the operation
+          being discussed. Add parameters to the command or action if it makes sense
+          a user would want them, and use defaults as appropriate.
+
+        - Look at the example below. Commonly, you will subclass PerItemAction
+          for simple actions that work on one item at a time. Subclass LLMAction
+          if it is simply a transformation of the input using an LLM.
+.
+        To illustrate, here are a couple examples of the correct format for an action that
+        strips HTML tags:
+        """
+        + load_source_code().example_action_src.replace("{", "{{").replace("}", "}}")
+        + """
+
+        And here are a couple simple command implementations:
+        """
+        + load_source_code().example_command_src.replace("{", "{{").replace("}", "}}")
+        + """
+
+        Next you will get context or a request from the user on a problem, or
+        simply a previous discussion with an assistant describing a partial solution
+        but from which you can understand what action or command would help solve
+        the problem.
+         
+        After thinking about the context below, describe a useful command or action
+        that is appropriate for the problem, and then give the Python code for it.
+        """
+    )
+
+
+@kash_action(
+    expected_args=ONE_OR_NO_ARGS,
+    precondition=is_instructions,
+    cacheable=False,
+    interactive_input=True,
+    params=common_params("model"),
+    title_template=TitleTemplate("Action: {title}"),
+)
+def write_new_action(input: ActionInput, model: LLMName = LLM.default_structured) -> ActionResult:
+    """
+    Create a new kash action or command in Python, based some problem or context or
+    a description of the features.
+
+    If no input is provided, will start an interactive chat to get
+
+    Or `write_instructions` to create a chat to use as input for this action.
+    """
+    if not input.items:
+        # Start a chat to collect the action description.
+        # FIXME: Consider generalizing this so an action can declare an input action to collect its input.
+        chat_result = write_instructions(ActionInput.empty())
+        if not chat_result.items:
+            raise InvalidInput("No chat input provided")
+
+        action_description_item = chat_result.items[0]
+    else:
+        action_description_item = input.items[0]
+
+    # Manually check precondition since we might have created the item
+    is_instructions.check(action_description_item, "action `write_new_action`")
+
+    chat_history = ChatHistory()
+
+    instructions_message = ChatHistory.from_yaml(not_none(action_description_item.body)).messages[0]
+
+    # Give the LLM full context on kash APIs.
+    # But we do this here lazily to prevent circular dependencies.
+    system_message = Message(assist_preamble(is_structured=True, skip_api_docs=False))
+    chat_history.extend(
+        [
+            ChatMessage(ChatRole.system, system_message),
+            ChatMessage(ChatRole.user, str(write_action_instructions)),
+            instructions_message,
+        ]
+    )
+
+    assistant_response = assistance_structured(chat_history.as_chat_completion(), model)
+
+    print_assistant_response(assistant_response, model)
+
+    if not assistant_response.python_code:
+        raise ApiResultError("No Python code provided in the response.")
+
+    body = assistant_response.python_code
+    # Put the instructions in an actual comment at the top of the file.
+    action_comments = "(This action was written by kash `write_new_action`.)\n\n" + str(
+        instructions_message.content
+    )
+    comment = fill_text(action_comments, text_wrap=Wrap.WRAP_FULL, extra_indent="# ")
+    commented_body = "\n\n".join(filter(None, [comment, body]))
+
+    result_item = action_description_item.derived_copy(
+        type=ItemType.extension,
+        format=Format.python,
+        body=commented_body,
+    )
+
+    return ActionResult([result_item])

kash/commands/__init__.py

@@ -0,0 +1,21 @@
+# Import all command modules to ensure commands are registered.
+
+import kash.commands.base.basic_file_commands  # noqa: F401
+import kash.commands.base.browser_commands  # noqa: F401
+import kash.commands.base.debug_commands  # noqa: F401
+import kash.commands.base.diff_commands  # noqa: F401
+import kash.commands.base.files_command  # noqa: F401
+import kash.commands.base.general_commands  # noqa: F401
+import kash.commands.base.global_state_commands  # noqa: F401
+import kash.commands.base.logs_commands  # noqa: F401
+import kash.commands.base.reformat_command  # noqa: F401
+import kash.commands.base.search_command  # noqa: F401
+import kash.commands.base.show_command  # noqa: F401
+import kash.commands.extras.utils_commands  # noqa: F401
+import kash.commands.help.assistant_commands  # noqa: F401  # noqa: F401
+import kash.commands.help.doc_commands  # noqa: F401
+import kash.commands.help.help_commands  # noqa: F401
+import kash.commands.workspace.selection_commands  # noqa: F401
+import kash.commands.workspace.workspace_commands  # noqa: F401
+import kash.local_server.local_server_commands  # noqa: F401
+import kash.mcp.mcp_server_commands  # noqa: F401

kash/commands/base/basic_file_commands.py

@@ -0,0 +1,183 @@
+import os
+
+from frontmatter_format import fmf_read_raw, fmf_strip_frontmatter
+from prettyfmt import fmt_lines
+from strif import copyfile_atomic
+
+from kash.config.logger import get_logger
+from kash.config.text_styles import STYLE_EMPH
+from kash.errors import InvalidInput
+from kash.exec import assemble_path_args, kash_command, resolve_path_arg
+from kash.shell.output.shell_output import (
+    PadStyle,
+    PrintHooks,
+    Wrap,
+    cprint,
+    print_status,
+    print_style,
+)
+from kash.shell.utils.native_utils import edit_files, native_trash
+from kash.shell.utils.native_utils import tail_file as native_tail_file
+from kash.utils.common.format_utils import fmt_loc
+from kash.utils.file_utils.file_formats_model import detect_file_format
+from kash.workspaces.workspace_output import print_file_info
+
+log = get_logger(__name__)
+
+
+@kash_command
+def cbcopy(path: str | None = None, raw: bool = False) -> None:
+    """
+    Copy the contents of a file (or the first file in the selection) to the OS-native
+    clipboard.
+
+    :param raw: Copy the full exact contents of the file. Otherwise frontmatter is omitted.
+    """
+    # TODO: Get this to work for images!
+    import pyperclip
+
+    input_paths = assemble_path_args(path)
+    input_path = input_paths[0]
+
+    format = detect_file_format(input_path)
+    if not format or not format.is_text:
+        raise InvalidInput(f"Cannot copy non-text files to clipboard: {fmt_loc(input_path)}")
+
+    if raw:
+        with open(input_path) as f:
+            content = f.read()
+
+        pyperclip.copy(content)
+        print_status(
+            "Copied raw contents of file to clipboard (%s chars):\n%s",
+            len(content),
+            fmt_lines([fmt_loc(input_path)]),
+        )
+    else:
+        content, metadata_str = fmf_read_raw(input_path)
+        pyperclip.copy(content)
+        skip_msg = ""
+        if metadata_str:
+            skip_msg = f", skipping {len(metadata_str)} chars of frontmatter"
+        print_status(
+            "Copied contents of file to clipboard (%s chars%s):\n%s",
+            len(content),
+            skip_msg,
+            fmt_lines([fmt_loc(input_path)]),
+        )
+
+
+@kash_command
+def edit(path: str | None = None, all: bool = False) -> None:
+    """
+    Edit the contents of a file using the user's default editor (or defaulting to nano).
+
+    :param all: Normally edits only the first file given. This passes all files to the editor.
+    """
+    input_paths = assemble_path_args(path)
+    if not all:
+        input_paths = [input_paths[0]]
+
+    edit_files(*input_paths)
+
+
+@kash_command
+def file_info(*paths: str, size_summary: bool = False, format: bool = False) -> None:
+    """
+    Show info about a file. By default this includes a summary of the size and HTML
+    structure of the items at the given paths (for text documents) and the detected
+    mime type.
+
+    :param size_summary: Only show size summary (words, sentences, paragraphs for a text document).
+    :param format: Only show detected file format.
+    """
+    if not size_summary and not format:
+        size_summary = format = True
+
+    # FIXME: Ensure this yields absolute paths for global workspace store paths
+    input_paths = assemble_path_args(*paths)
+    for input_path in input_paths:
+        cprint(f"{fmt_loc(input_path)}:", style=STYLE_EMPH, text_wrap=Wrap.NONE)
+        with print_style(PadStyle.INDENT):
+            print_file_info(input_path, show_size_details=size_summary, show_format=format)
+        PrintHooks.spacer()
+
+
+@kash_command
+def rename(path: str, new_path: str) -> None:
+    """
+    Rename a file or item. Creates any new parent paths as needed.
+    Note this may invalidate relations that point to the old store path.
+
+    TODO: Add an option here to update all relations in the workspace.
+    """
+    from_path, to_path = assemble_path_args(path, new_path)
+    to_path.parent.mkdir(parents=True, exist_ok=True)
+    os.rename(from_path, to_path)
+
+    print_status(f"Renamed: {fmt_loc(from_path)} -> {fmt_loc(to_path)}")
+
+
+@kash_command
+def copy(*paths: str) -> None:
+    """
+    Copy the items at the given paths to the target path.
+    """
+    if len(paths) < 2:
+        raise InvalidInput("Must provide at least one source path and a target path")
+
+    src_paths = [resolve_path_arg(path) for path in paths[:-1] if path]
+    dest_path = resolve_path_arg(paths[-1])
+
+    if len(src_paths) == 1 and dest_path.is_dir():
+        dest_path = dest_path / src_paths[0].name
+    elif len(src_paths) > 1 and not dest_path.is_dir():
+        raise InvalidInput(f"Cannot copy multiple files to a file target: {dest_path}")
+
+    for src_path in src_paths:
+        copyfile_atomic(src_path, dest_path, make_parents=True)
+
+    print_status(
+        f"Copied:\n{fmt_lines(fmt_loc(p) for p in src_paths)}\n->\n{fmt_lines([fmt_loc(dest_path)])}",
+    )
+
+
+@kash_command
+def trash(*paths: str) -> None:
+    """
+    Trash the items at the given paths. Uses OS-native trash or recycle bin on Mac, Windows, or Linux.
+    """
+
+    resolved_paths = assemble_path_args(*paths)
+    native_trash(*resolved_paths)
+    print_status(f"Deleted (check trash or recycling bin to recover):\n{fmt_lines(resolved_paths)}")
+
+
+@kash_command
+def strip_frontmatter(*paths: str) -> None:
+    """
+    Strip the frontmatter from the given files.
+    """
+    input_paths = assemble_path_args(*paths)
+
+    for path in input_paths:
+        log.message("Stripping frontmatter from: %s", fmt_loc(path))
+        fmf_strip_frontmatter(path)
+
+
+@kash_command
+def tail_file(path: str, follow: bool = False) -> None:
+    """
+    Tail a file. With colorization using bat if available, otherwise using less.
+    If `follow` is True, follows the file as it grows.
+    """
+
+    native_tail_file(path, follow=follow)
+
+
+@kash_command
+def follow_file(path: str) -> None:
+    """
+    Same as `tail_file --follow`.
+    """
+    native_tail_file(path, follow=True)

kash/commands/base/browser_commands.py

@@ -0,0 +1,62 @@
+import urllib.parse
+
+from kash.exec import kash_command
+from kash.shell.utils.native_utils import native_open_url
+
+
+@kash_command
+def browser(url_or_query: str) -> None:
+    """
+    Open a URL or query in the browser.
+    """
+    native_open_url(url_or_query)
+
+
+@kash_command
+def web_search_google(query: str) -> None:
+    """
+    Open browser with a Google for a query.
+    """
+    native_open_url(f"https://www.google.com/search?q={urllib.parse.quote(query)}")
+
+
+@kash_command
+def web_search_duckduckgo(query: str) -> None:
+    """
+    Open browser with a DuckDuckGo search for a query.
+    """
+    native_open_url(f"https://duckduckgo.com/?q={urllib.parse.quote(query)}")
+
+
+@kash_command
+def web_search_bing(query: str) -> None:
+    """
+    Open browser with a Bing search for a query.
+    """
+    native_open_url(f"https://www.bing.com/search?q={urllib.parse.quote(query)}")
+
+
+@kash_command
+def web_search_youtube(query: str) -> None:
+    """
+    Open browser with a YouTube search for a query.
+    """
+    params = {"search_query": query}
+    url = f"https://www.youtube.com/results?{urllib.parse.urlencode(params)}"
+    native_open_url(url)
+
+
+@kash_command
+def web_search_amazon(query: str) -> None:
+    """
+    Open browser with an Amazon search for a query.
+    """
+    native_open_url(f"https://www.amazon.com/s?k={urllib.parse.quote(query)}")
+
+
+@kash_command
+def web_search_perplexity(query: str) -> None:
+    """
+    Open browser with a Perplexity search for a query.
+    """
+    native_open_url(f"https://www.perplexity.ai/search?q={urllib.parse.quote(query)}")

kash/commands/base/debug_commands.py

@@ -0,0 +1,214 @@
+from collections.abc import Callable
+
+import rich
+from flowmark import Wrap
+from strif import single_line
+
+from kash.config.logger import get_logger
+from kash.config.text_styles import STYLE_HINT, STYLE_KEY
+from kash.errors import InvalidInput
+from kash.exec import kash_command
+from kash.help import tldr_help
+from kash.help.function_param_info import annotate_param_info
+from kash.help.recommended_commands import RECOMMENDED_TLDR_COMMANDS
+from kash.model.params_model import Param
+from kash.shell.output.kerm_codes import IframePopover, TextTooltip
+from kash.shell.output.shell_output import PrintHooks, console_pager, cprint, format_name_and_value
+
+log = get_logger(__name__)
+
+
+@kash_command
+def kerm_text_tooltip(text: str) -> None:
+    """
+    Show a tooltip in the Kerm terminal.
+    """
+    tooltip = TextTooltip(text=text)
+    print(tooltip.as_osc(), end="")
+
+
+@kash_command
+def kerm_iframe_popover(url: str) -> None:
+    """
+    Show an iframe popover in the Kerm terminal.
+    """
+    popover = IframePopover(url=url)
+    print(popover.as_osc(), end="")
+
+
+@kash_command
+def dump_tldr_snippets() -> None:
+    """
+    Dev task to run occasionally: Dump a few hundred TLDR snippet examples to a
+    standard script file for use in kash tab completion.
+    """
+    tldr_help.dump_all_tldr_snippets()
+
+
+@kash_command
+def debug_tldr() -> None:
+    """
+    Debug task to dump TLDR snippets for a few commands.
+    """
+    log.message("TLDR cache dir: %s", tldr_help._cache_dir)
+    log.message("TLDR cache timestamp file: %s", tldr_help._timestamp_file)
+    log.message("TLDR cache location: %s", tldr_help._cache_location("en"))
+    log.message("Should update TLDR cache: %s", tldr_help._should_update_cache())
+
+    with console_pager():
+        for command in RECOMMENDED_TLDR_COMMANDS:
+            cprint(f"{command}", style=STYLE_KEY)
+            cprint(f"description: {tldr_help.tldr_description(command)}")
+            cprint(f"help: {tldr_help.tldr_help(command)}")
+            cprint()
+            cprint("parsed snippets:")
+            for snippet in tldr_help.tldr_snippets(command):
+                cprint(f"# {snippet.comment}")
+                cprint(f"{snippet.command_line}")
+            cprint()
+            cprint()
+
+
+@kash_command
+def debug_completions() -> None:
+    """
+    Dump info on all xonsh completers.
+    """
+    from xonsh.built_ins import XSH
+
+    def name_of(completer: Callable) -> str:
+        module_name = completer.__module__ if hasattr(completer, "__module__") else "?"
+        if hasattr(completer, "__name__"):
+            return f"{module_name}.{completer.__name__}"
+        elif hasattr(completer, "__class__"):
+            return f"{module_name}.{completer.__class__.__name__}"
+        else:
+            return str(completer)
+
+    def to_str(completer: Callable) -> str:
+        return f"{name_of(completer)} (non_exclusive={getattr(completer, 'non_exclusive', False)})"
+
+    cprint(f"{len(XSH.completers)} completers registered:")
+    PrintHooks.spacer()
+
+    for completer in XSH.completers.values():
+        cprint(to_str(completer), text_wrap=Wrap.NONE, style=STYLE_KEY)
+        if completer.__doc__:
+            cprint(
+                f"{single_line(completer.__doc__)}", text_wrap=Wrap.WRAP_INDENT, style=STYLE_HINT
+            )
+
+
+@kash_command
+def debug_help() -> None:
+    """
+    Debug task to dump help for all commands and actions.
+    """
+    from kash.docs.all_docs import all_docs
+
+    cprint(f"all_docs: {all_docs}", style=STYLE_KEY)
+
+    cprint("\nhelp_topics:", style=STYLE_KEY)
+
+    for topic in all_docs.help_topics.__dict__.keys():
+        cprint(f"{topic}", text_wrap=Wrap.NONE)
+
+    cprint("\nfaqs:")
+    for faq in all_docs.faqs:
+        cprint(f"{faq}", text_wrap=Wrap.NONE)
+
+    cprint("\ncustom_command_infos:", style=STYLE_KEY)
+    for cmd in all_docs.custom_command_infos:
+        cprint(f"{cmd}", text_wrap=Wrap.NONE)
+
+    cprint("\nstd_command_infos:", style=STYLE_KEY)
+    for cmd in all_docs.std_command_infos:
+        cprint(f"{cmd}", text_wrap=Wrap.NONE)
+
+    cprint("\naction_infos:", style=STYLE_KEY)
+    for action in all_docs.action_infos:
+        cprint(f"{action}", text_wrap=Wrap.NONE)
+
+    # cprint("\nrecipe_snippets:", style=STYLE_KEY)
+    # for snippet in all_docs.recipe_snippets:
+    #     cprint(f"{snippet}", text_wrap=Wrap.NONE)
+
+
+@kash_command
+def debug_command(command_or_action: str) -> None:
+    """
+    Debug task to dump info on a command or action.
+    """
+    from kash.exec.action_registry import get_all_actions_defaults
+    from kash.exec.command_registry import get_all_commands
+
+    def dump_params(param_info: list[Param]) -> None:
+        for param in param_info:
+            cprint(format_name_and_value(param.display, str(param)))
+            cprint()
+
+    try:
+        command = get_all_commands()[command_or_action]
+        param_info = annotate_param_info(command)
+        cprint(format_name_and_value("Command", f"`{command_or_action}`"))
+        cprint(format_name_and_value("Docstring", command.__doc__ or ""))
+        cprint()
+        dump_params(param_info)
+        cprint()
+        rich.inspect(command)
+    except KeyError:
+        try:
+            action = get_all_actions_defaults()[command_or_action]
+            cprint(format_name_and_value("Action", f"`{command_or_action}`"))
+            cprint(format_name_and_value("Description", action.description or ""))
+            cprint()
+            dump_params(list(action.params))
+            cprint()
+            rich.inspect(action.tool_json_schema(), title="JSON Schema", docs=False)
+            cprint()
+            rich.inspect(action, title="Action Instance", docs=False)
+        except KeyError:
+            raise InvalidInput(f"No info found for {command_or_action}")
+
+
+@kash_command
+def reload_system() -> None:
+    """
+    Experimental! Reload the kash package and all its submodules. Also restarts
+    the local the local server. Not perfect! But sometimes useful for development.
+    """
+    import kash
+    from kash.local_server.local_server import restart_local_server
+    from kash.utils.common.import_utils import recursive_reload
+
+    module = kash
+    exclude = ["kash.xontrib.kash_extension"]  # Don't reload the kash initialization.
+
+    def filter_func(name: str) -> bool:
+        if exclude:
+            for excluded_module in exclude:
+                if name == excluded_module or name.startswith(excluded_module + "."):
+                    log.info("Excluding reloading module: %s", name)
+                    return False
+        return True
+
+    package_names = recursive_reload(module, filter_func=filter_func)
+    log.info("Reloaded modules: %s", ", ".join(package_names))
+    log.message("Reloaded %s modules from %s.", len(package_names), module.__name__)
+
+    restart_local_server()
+
+    # TODO Re-register commands and actions.
+
+
+@kash_command
+def reload_commands_and_actions() -> None:
+    """
+    Reload all commands and actions. This can be needed to register newly imported
+    Python files that define commands or actions with the shell.
+    """
+    from kash.xonsh_custom.customize_xonsh import reload_shell_commands_and_actions
+    from kash.xonsh_custom.shell_load_commands import log_command_action_info
+
+    reload_shell_commands_and_actions()
+    log_command_action_info()