kash-shell 0.3.28__py3-none-any.whl → 0.3.33__py3-none-any.whl

kash/commands/workspace/workspace_commands.py

@@ -100,8 +100,9 @@ def cache_list(media: bool = False, content: bool = False, workspace: str | None
     """
     List the contents of the workspace media and content caches. By default lists both caches.
 
-    :param media: List media cache only.
-    :param content: List content cache only.
+    Args:
+        media: List media cache only.
+        content: List content cache only.
     """
     if not media and not content:
         media = True
@@ -131,9 +132,10 @@ def clear_cache(media: bool = False, content: bool = False, workspace: str | Non
     """
     Clear the media and content caches. By default clears both caches.
 
-    :param media: Clear media cache only.
-    :param content: Clear content cache only.
-    :param global_cache: If in a workspace, clear the global caches, not the workspace caches.
+    Args:
+        media: Clear media cache only.
+        content: Clear content cache only.
+        global_cache: If in a workspace, clear the global caches, not the workspace caches.
     """
     if not media and not content:
         media = True
@@ -193,8 +195,9 @@ def history(max: int = 30, raw: bool = False) -> None:
 
     For xonsh's built-in history, use `xhistory`.
 
-    :param max: Show at most the last `max` commands.
-    :param raw: Show raw command history by tailing the history file directly.
+    Args:
+        max: Show at most the last `max` commands.
+        raw: Show raw command history by tailing the history file directly.
     """
     # TODO: Customize this by time frame.
     ws = current_ws()
@@ -395,15 +398,21 @@ def params(full: bool = False) -> None:
 
 @kash_command
 def import_item(
-    *files_or_urls: str, type: ItemType | None = None, inplace: bool = False
+    *files_or_urls: str,
+    type: ItemType | None = None,
+    inplace: bool = False,
+    with_sidematter: bool = False,
 ) -> ShellResult:
     """
     Add a file or URL resource to the workspace as an item.
 
-    :param inplace: If set and the item is already in the store, reimport the item,
-      adding or rewriting metadata frontmatter.
-    :param type: Change the item type. Usually items are auto-detected from the file
-      format (typically doc or resource), but you can override this with this option.
+    Args:
+        inplace: If set and the item is already in the store, reimport the item,
+            adding or rewriting metadata frontmatter.
+        type: Change the item type. Usually items are auto-detected from the file
+            format (typically doc or resource), but you can override this with this option.
+        with_sidematter: If set, will copy any sidematter-format files (metadata/assets)
+            to the destination.
     """
     if not files_or_urls:
         raise InvalidInput("No files or URLs provided")
@@ -412,7 +421,9 @@ def import_item(
     store_paths = []
 
     locators = [resolve_locator_arg(r) for r in files_or_urls]
-    store_paths = ws.import_items(*locators, as_type=type, reimport=inplace)
+    store_paths = ws.import_items(
+        *locators, as_type=type, reimport=inplace, with_sidematter=with_sidematter
+    )
 
     print_status(
         "Imported %s %s:\n%s",
@@ -434,9 +445,10 @@ def save_clipboard(
     """
     Import the contents of the OS-native clipboard as a new item in the workspace.
 
-    :param title: The title of the new item (default: "pasted_text").
-    :param type: The type of the new item (default: resource).
-    :param format: The format of the new item (default: plaintext).
+    Args:
+        title: The title of the new item (default: "pasted_text").
+        type: The type of the new item (default: resource).
+        format: The format of the new item (default: plaintext).
     """
     import pyperclip
 
@@ -537,8 +549,9 @@ def applicable_actions(*paths: str, brief: bool = False, all: bool = False) -> N
     Show the actions that are applicable to the current selection.
     This is a great command to use at any point to see what actions are available!
 
-    :param brief: Show only action names. Otherwise show actions and descriptions.
-    :param all: Include actions with no preconditions.
+    Args:
+        brief: Show only action names. Otherwise show actions and descriptions.
+        all: Include actions with no preconditions.
     """
     store_paths = assemble_store_path_args(*paths)
     ws = current_ws()
@@ -592,19 +605,19 @@ def applicable_actions(*paths: str, brief: bool = False, all: bool = False) -> N
 
 
 @kash_command
-def preconditions() -> None:
+def preconditions(path: str | None = None) -> None:
     """
-    List all preconditions and if the current selection meets them.
+    List all preconditions and if the current selection or specified path meets them.
     """
 
     ws = current_ws()
-    selection = ws.selections.current.paths
-    if not selection:
-        raise InvalidInput("No selection")
-
-    items = [ws.load(item) for item in selection]
+    input_paths = assemble_path_args(path)
+    items = [ws.load(item) for item in input_paths]
 
-    print_status("Precondition check for selection:\n %s", fmt_lines(selection))
+    if path:
+        print_status("Precondition check for path:\n%s", fmt_lines([fmt_loc(path)]))
+    else:
+        print_status("Precondition check for selection:\n%s", fmt_lines(input_paths))
 
     for precondition in get_all_preconditions().values():
         satisfied = all(precondition(item) for item in items)

kash/config/logger.py

@@ -281,7 +281,7 @@ def _do_logging_setup(log_settings: LogSettings):
 def prefix(line: str, emoji: str = "", warn_emoji: str = "") -> str:
     prefix = task_stack_prefix_str()
     emojis = f"{warn_emoji}{emoji}".strip()
-    return " ".join(filter(None, [prefix, emojis, line]))
+    return "".join(filter(None, [prefix, emojis, line]))
 
 
 def prefix_args(

kash/config/setup.py

@@ -1,7 +1,5 @@
-from enum import Enum
 from functools import cache
 from pathlib import Path
-from typing import Any
 
 from clideps.env_vars.dotenv_utils import load_dotenv_paths
 
@@ -77,29 +75,6 @@ def kash_setup(
 
 
 def _lib_setup():
-    from frontmatter_format.yaml_util import add_default_yaml_customizer
-    from ruamel.yaml import Representer
+    from sidematter_format import register_default_yaml_representers
 
-    def represent_enum(dumper: Representer, data: Enum) -> Any:
-        """
-        Represent Enums as their values.
-        Helps make it easy to serialize enums to YAML everywhere.
-        We use the convention of storing enum values as readable strings.
-        """
-        return dumper.represent_str(data.value)
-
-    add_default_yaml_customizer(
-        lambda yaml: yaml.representer.add_multi_representer(Enum, represent_enum)
-    )
-
-    # Maybe useful?
-
-    # from pydantic import BaseModel
-
-    # def represent_pydantic(dumper: Representer, data: BaseModel) -> Any:
-    #     """Represent Pydantic models as YAML dictionaries."""
-    #     return dumper.represent_dict(data.model_dump())
-
-    # add_default_yaml_customizer(
-    #     lambda yaml: yaml.representer.add_multi_representer(BaseModel, represent_pydantic)
-    # )
+    register_default_yaml_representers()

kash/config/text_styles.py

@@ -262,7 +262,7 @@ PROMPT_ASSIST = "(assistant) ❯"
 
 EMOJI_HINT = "👉"
 
-EMOJI_MSG_INDENT = "⋮"
+EMOJI_MSG_INDENT = "⋮   "
 
 EMOJI_START = "[➤]"
 

kash/docs/markdown/topics/a1_what_is_kash.md

@@ -1,3 +1,16 @@
+## Hello!
+
+If you’re seeing this, you there’s a good chance I shared it with you for feedback.
+Thank you for checking out Kash.
+
+It’s new, the result of some experimentation over the past few months.
+I like a lot of things about it but it isn’t mature and I’d love your help to make it
+more usable. If you try it please **let me know** what works and what doesn’t work.
+Or if you just don’t get it, where you lost interest or got stuck.
+My contact info is at [github.com/jlevy](https://github.com/jlevy) or [follow or DM
+me](https://x.com/ojoshe) (I’m fastest on Twitter DMs).
+Thank you. :)
+
 ## What is Kash?
 
 > “*Simple should be simple.
@@ -12,9 +25,15 @@ It operates on “items” such as URLs, files, or Markdown notes within a works
 directory.
 
 You can use Kash as an **interactive, AI-native command-line** shell for practical
-knowledge tasks. It’s also **a Python library** that lets you convert a simple Python
-function into a command and an MCP tool, so it integrates with other tools like
-Anthropic Desktop or Cursor.
+knowledge tasks.
+
+But it’s actually not just a shell, and you can skip the shell entirely.
+It’s really simply **a Python library** that lets you convert a simple Python function
+into “actions” that work in a clean way on plain files in a workspace.
+An action is also an MCP tool, so it integrates with other tools like Anthropic Desktop
+or Cursor.
+
+So basically, it gives a unified way to use the shell, Python functions, and MCP tools.
 
 It’s new and still has some rough edges, but it’s now working well enough it is feeling
 quite powerful. It now serves as a replacement for my usual shell (previously bash or
@@ -73,10 +92,10 @@ quick to install via uv.
 - **Support for any API:** Kash is tool agnostic and runs locally, on file inputs in
   simple formats, so you own and manage your data and workspaces however you like.
   You can use it with any models or APIs you like, and is already set up to use the APIs
-  of **OpenAI GPT-4o and o1**, **Anthropic Claude 3.7**, **Google Gemini**, **xAI
-  Grok**, **Mistral**, **Groq (Llama, Qwen, Deepseek)** (via **LiteLLM**), **Deepgram**,
-  **Perplexity**, **Firecrawl**, **Exa**, and any Python libraries.
-  There is also some experimental support for **LlamaIndex** and **ChromaDB**.
+  of **OpenAI** (GPT-5 is now the default model), **Anthropic Claude**, **Google
+  Gemini**, **xAI Grok**, **Mistral**, **Groq (Llama, Qwen, Deepseek)** (via
+  **LiteLLM**), **Deepgram**, **Perplexity**, **Firecrawl**, **Exa**, and any Python
+  libraries. There is also some experimental support for **LlamaIndex** and **ChromaDB**.
 
 - **MCP support:** Finally, an action is also an **MCP tool server** so you can use it
   in any MCP client, like Anthropic Desktop or Cursor.
@@ -110,14 +129,3 @@ I’ve separately built a new desktop terminal app, Kerm, which adds support for
 “Kerm codes” protocol for such visual components, encoded as OSC codes then rendered in
 the terminal. Because Kash supports these codes, as this develops you will get the
 visuals of a web app layered on the flexibility of a text-based terminal.
-
-### Is Kash Mature?
-
-It’s the result of a couple months of coding and experimentation, and it’s still in
-progress and has rough edges.
-Please help me make it better by sharing your ideas and feedback!
-It’s easiest to DM me at [twitter.com/ojoshe](https://x.com/ojoshe).
-My contact info is at [github.com/jlevy](https://github.com/jlevy).
-
-[**Please follow or DM me**](https://x.com/ojoshe) for future updates or if you have
-ideas, feedback, or use cases for Kash!

kash/docs/markdown/topics/a2_installation.md

@@ -60,8 +60,9 @@ These are for `kash-media` but you can use a `kash-shell` for a more basic setup
 
    ```shell
    sudo apt-get update
-   sudo apt-get install -y libgl1 ffmpeg libmagic-dev 
-   # For the additional command-line tools, pixi is better on Ubuntu:
+   sudo apt-get install -y libgl1 ffmpeg libmagic-dev imagemagick bat ripgrep hexyl
+
+   # Or for additional command-line tools, pixi is better on Ubuntu:
    curl -fsSL https://pixi.sh/install.sh | sh
    . ~/.bashrc
    pixi global install ripgrep bat eza hexyl imagemagick zoxide

kash/exec/action_decorators.py

@@ -31,12 +31,13 @@ from kash.model.actions_model import (
     ParamSource,
     TitleTemplate,
 )
-from kash.model.exec_model import ExecContext
+from kash.model.exec_model import ActionContext, ExecContext
 from kash.model.items_model import Item, ItemType
 from kash.model.params_model import Param, ParamDeclarations, TypedParamValues
 from kash.model.preconditions_model import Precondition
 from kash.utils.common.function_inspect import FuncParam, inspect_function_params
 from kash.utils.errors import InvalidDefinition
+from kash.utils.file_utils.file_formats_model import Format
 
 log = get_logger(__name__)
 
@@ -204,6 +205,7 @@ def kash_action(
     arg_type: ArgType = ArgType.Locator,
     expected_args: ArgCount = ONE_ARG,
     output_type: ItemType = ItemType.doc,
+    output_format: Format | None = None,
     expected_outputs: ArgCount = ONE_ARG,
     params: ParamDeclarations = (),
     run_per_item: bool | None = None,
@@ -318,6 +320,7 @@ def kash_action(
                 self.arg_type = arg_type
                 self.uses_selection = uses_selection
                 self.output_type = output_type
+                self.output_format = output_format
                 self.interactive_input = interactive_input
                 self.live_output = live_output
                 self.mcp_tool = mcp_tool
@@ -328,7 +331,7 @@ def kash_action(
                 super().__post_init__()
 
             @override
-            def run(self, input: ActionInput, context: ExecContext) -> ActionResult:
+            def run(self, input: ActionInput, context: ActionContext) -> ActionResult:
                 # Map the final, current actions param values back to the function parameters.
                 pos_args: list[Any] = []
                 kw_args: dict[str, Any] = {}
@@ -397,9 +400,8 @@ def kash_action(
                 context = ExecContext(action, current_runtime_settings())
 
             # Run the action.
-            result, _, _ = run_action_with_caching(context, action_input)
-
-            return result
+            result_with_paths = run_action_with_caching(context, action_input)
+            return result_with_paths.result
 
         if is_simple_func:
             # Need to convert back to a SimpleActionFunction.

kash/exec/action_exec.py

@@ -1,5 +1,5 @@
 import time
-from dataclasses import replace
+from dataclasses import dataclass, replace
 from pathlib import Path
 
 from prettyfmt import fmt_lines, fmt_path, plural
@@ -23,14 +23,16 @@ from kash.model.actions_model import (
     ExecContext,
     PathOpType,
 )
-from kash.model.exec_model import RuntimeSettings
+from kash.model.exec_model import ActionContext, RuntimeSettings
 from kash.model.items_model import Item, State
 from kash.model.operations_model import Input, Operation, Source
 from kash.model.params_model import ALL_COMMON_PARAMS, GLOBAL_PARAMS, RawParamValues
 from kash.model.paths_model import StorePath
 from kash.shell.output.shell_output import PrintHooks
+from kash.utils.common.s3_utils import get_s3_parent_folder, s3_sync_to_folder
 from kash.utils.common.task_stack import task_stack
 from kash.utils.common.type_utils import not_none
+from kash.utils.common.url import Url, is_s3_url
 from kash.utils.errors import ContentError, InvalidOutput, get_nonfatal_exceptions
 from kash.workspaces import Selection, current_ws
 
@@ -42,6 +44,7 @@ def prepare_action_input(*input_args: CommandArg, refetch: bool = False) -> Acti
     Prepare input args, which may be URLs or paths, into items that correspond to
     URL or file resources, either finding them in the workspace or importing them.
     Also fetches metadata for URLs if they don't already have title and description.
+    Automatically imports any URLs and copies any sidematter-format files (metadata/assets).
     """
     from kash.exec.fetch_url_items import fetch_url_item_content
 
@@ -49,7 +52,7 @@ def prepare_action_input(*input_args: CommandArg, refetch: bool = False) -> Acti
 
     # Ensure input items are already saved in the workspace and load the corresponding items.
     # This also imports any URLs.
-    input_items = [ws.import_and_load(arg) for arg in input_args]
+    input_items = [ws.import_and_load(arg, with_sidematter=True) for arg in input_args]
 
     # URLs should have metadata like a title and be valid, so we fetch them.
     if input_items:
@@ -109,9 +112,7 @@ def log_action(action: Action, action_input: ActionInput, operation: Operation):
     log.info("Input items are:\n%s", fmt_lines(action_input.items))
 
 
-def check_for_existing_result(
-    context: ExecContext, action_input: ActionInput, operation: Operation
-) -> ActionResult | None:
+def check_for_existing_result(context: ActionContext) -> ActionResult | None:
     """
     Check if we already have the results for this operation (same action and inputs)
     If so return it, unless rerun is requested, in which case we just log that the results
@@ -126,7 +127,7 @@ def check_for_existing_result(
 
     # Check if a previous run already produced the result.
     # To do this we preassemble outputs.
-    preassembled_result = action.preassemble(operation, action_input)
+    preassembled_result = action.preassemble_result(context)
     if preassembled_result:
         # Check if these items already exist, with last_operation matching action and input fingerprints.
         already_present = [ws.find_by_id(item) for item in preassembled_result.items]
@@ -155,7 +156,7 @@ def check_for_existing_result(
 
 
 def run_action_operation(
-    context: ExecContext,
+    context: ActionContext,
     action_input: ActionInput,
     operation: Operation,
 ) -> ActionResult:
@@ -183,7 +184,7 @@ def run_action_operation(
             this_op = replace(operation, arguments=[operation.arguments[i]])
         else:
             this_op = operation
-        item.update_history(Source(operation=this_op, output_num=i, cacheable=action.cacheable))
+        item.update_source(Source(operation=this_op, output_num=i, cacheable=action.cacheable))
 
     # Override the state if appropriate (this handles marking items as transient).
     if settings.override_state:
@@ -205,7 +206,7 @@ class SkipItem(Exception):
     """
 
 
-def _run_for_each_item(context: ExecContext, input: ActionInput) -> ActionResult:
+def _run_for_each_item(context: ActionContext, input: ActionInput) -> ActionResult:
     """
     Helper to process each input item. If non-fatal errors are encountered on any item,
     they are reported and processing continues with the next item.
@@ -340,69 +341,116 @@ def save_action_result(
     return result_store_paths, archived_store_paths
 
 
+@dataclass(frozen=True)
+class ResultWithPaths:
+    """
+    Result of an action, including the store paths of any S3 items created.
+    """
+
+    result: ActionResult
+    result_paths: list[StorePath]
+    archived_paths: list[StorePath]
+    s3_paths: list[Url]
+
+
 def run_action_with_caching(
-    context: ExecContext, action_input: ActionInput
-) -> tuple[ActionResult, list[StorePath], list[StorePath]]:
+    exec_context: ExecContext, action_input: ActionInput
+) -> ResultWithPaths:
     """
     Run an action, including validation, only rerunning if `rerun` requested or
     result is not already present. Returns the result, the store paths of the
     result items, and the store paths of any archived items.
 
+    Also handles optional S3 syncing if the input was from S3.
+
     Note: Mutates the input but only to add `context` to each item.
     """
-    action = context.action
-    settings = context.settings
+    action = exec_context.action
+    settings = exec_context.settings
     ws = settings.workspace
 
-    # For convenience, we include the context to each item too (this helps so per-item
-    # functions don't have to take context args everywhere).
-    for item in action_input.items:
-        item.context = context
+    # If the input is from S3, we note the parent folder to copy the output back to.
+    s3_parent_folder = None
+    if exec_context.settings.sync_to_s3 and action_input.items and action_input.items[0].url:
+        url = action_input.items[0].url
+        if url and is_s3_url(url):
+            s3_parent_folder = get_s3_parent_folder(url)
 
     # Assemble the operation and validate the action input.
-    operation = validate_action_input(context, ws, action, action_input)
+    operation = validate_action_input(exec_context, ws, action, action_input)
 
     # Log what we're about to run.
     log_action(action, action_input, operation)
 
-    # Check if a previous run already produced the result.
-    existing_result = check_for_existing_result(context, action_input, operation)
+    # Consolidate all the context.
+    context = ActionContext(
+        exec_context=exec_context, operation=operation, action_input=action_input
+    )
 
-    if existing_result and not settings.rerun:
-        # Use the cached result.
-        result = existing_result
-        result_store_paths = [StorePath(not_none(item.store_path)) for item in result.items]
-        archived_store_paths = []
+    try:
+        # Hack to add the context to each item.
+        # We do this before cache preassemble check.
+        action_input.set_context(context)
 
-        PrintHooks.before_done_message()
-        log.message(
-            "%s Skipped: `%s` completed with %s %s",
-            EMOJI_SKIP,
-            action.name,
-            len(result.items),
-            plural("item", len(result.items)),
-        )
-    else:
-        # Run it!
-        result = run_action_operation(context, action_input, operation)
-        result_store_paths, archived_store_paths = save_action_result(
-            ws,
-            result,
-            action_input,
-            as_tmp=settings.tmp_output,
-            no_format=settings.no_format,
-        )
+        # Check if a previous run already produced the result.
+        existing_result = check_for_existing_result(context)
 
-        PrintHooks.before_done_message()
-        log.message(
-            "%s Action: `%s` completed with %s %s",
-            EMOJI_SUCCESS,
-            action.name,
-            len(result.items),
-            plural("item", len(result.items)),
+        if existing_result and not settings.rerun:
+            # Use the cached result.
+            result = existing_result
+            result_store_paths = [StorePath(not_none(item.store_path)) for item in result.items]
+            archived_store_paths = []
+
+            PrintHooks.before_done_message()
+            log.message(
+                "%s Skipped: `%s` completed with %s %s",
+                EMOJI_SKIP,
+                action.name,
+                len(result.items),
+                plural("item", len(result.items)),
+            )
+        else:
+            # Run it!
+            result = run_action_operation(context, action_input, operation)
+            result_store_paths, archived_store_paths = save_action_result(
+                ws,
+                result,
+                action_input,
+                as_tmp=settings.tmp_output,
+                no_format=settings.no_format,
+            )
+
+            PrintHooks.before_done_message()
+            log.message(
+                "%s Action: `%s` completed with %s %s",
+                EMOJI_SUCCESS,
+                action.name,
+                len(result.items),
+                plural("item", len(result.items)),
+            )
+    finally:
+        action_input.clear_context()
+
+    # If the action created an S3 item, we copy it back to the same S3 parent folder.
+    # Only do this for the first result, for simplicity.
+    s3_urls: list[Url] = []
+    if s3_parent_folder and len(result_store_paths) > 0:
+        log.warning(
+            "Source was an S3 path so syncing result S3: %s -> %s",
+            result_store_paths[0],
+            s3_parent_folder,
+        )
+        s3_urls = s3_sync_to_folder(
+            result_store_paths[0], s3_parent_folder, include_sidematter=True
         )
+        log.message("Synced result to S3:\n%s", fmt_lines(s3_urls))
 
-    return result, result_store_paths, archived_store_paths
+    return ResultWithPaths(
+        result=result,
+        result_paths=result_store_paths,
+        archived_paths=archived_store_paths,
+        s3_paths=s3_urls,
+    )
 
 
 def run_action_with_shell_context(
@@ -480,7 +528,10 @@ def run_action_with_shell_context(
     input = prepare_action_input(*args, refetch=refetch)
 
     # Finally, run the action.
-    result, result_store_paths, archived_store_paths = run_action_with_caching(context, input)
+    result_with_paths = run_action_with_caching(context, input)
+    result = result_with_paths.result
+    result_store_paths = result_with_paths.result_paths
+    archived_store_paths = result_with_paths.archived_paths
 
     # Implement any path operations from the output and/or select the final output
     if not internal_call: