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

kash/file_storage/item_file_format.py

@@ -1,8 +1,16 @@
 from pathlib import Path
 
-from frontmatter_format import FmStyle, fmf_has_frontmatter, fmf_read, fmf_write
+from frontmatter_format import (
+    FmStyle,
+    fmf_has_frontmatter,
+    fmf_read,
+    fmf_read_frontmatter,
+    fmf_write,
+)
 from funlog import tally_calls
 from prettyfmt import custom_key_sort, fmt_size_human
+from sidematter_format import Sidematter
+from strif import atomic_output_file, single_line
 
 from kash.config.logger import get_logger
 from kash.model.items_model import ITEM_FIELDS, Item
@@ -22,19 +30,28 @@ _item_cache = MtimeCache[Item](max_size=2000, name="Item")
 
 
 @tally_calls()
-def write_item(item: Item, path: Path, normalize: bool = True):
+def write_item(item: Item, path: Path, *, normalize: bool = True, use_frontmatter: bool = True):
     """
-    Write a text item to a file with standard frontmatter format YAML.
+    Write a text item to a file with standard frontmatter format YAML or sidematter format.
     By default normalizes formatting of the body text and updates the item's body.
+
+    If `use_frontmatter` is True, uses frontmatter on the file for metadata, and omits
+    the sidematter metadata file.
+
+    This function does not explicitly write sidematter assets; these can be written
+    separately.
     """
     item.validate()
-    if item.format and not item.format.supports_frontmatter:
+    if use_frontmatter and item.format and not item.format.supports_frontmatter:
         raise ValueError(f"Item format `{item.format.value}` does not support frontmatter: {item}")
 
     # Clear cache before writing.
     _item_cache.delete(path)
 
+    title = item.title
     if normalize:
+        if item.title:
+            title = single_line(item.title)
         body = normalize_formatting(item.body_text(), item.format)
     else:
         body = item.body_text()
@@ -65,29 +82,44 @@ def write_item(item: Item, path: Path, normalize: bool = True):
 
     log.debug("Writing item to %s: body length %s, metadata %s", path, len(body), item.metadata())
 
-    fmf_write(
-        path,
-        body,
-        item.metadata(),
-        style=fm_style,
-        key_sort=ITEM_FIELD_SORT,
-        make_parents=True,
-    )
+    # Use sidematter format
+    spath = Sidematter(path)
+    if use_frontmatter:
+        # Use frontmatter format
+        fmf_write(
+            path,
+            body,
+            item.metadata(),
+            style=fm_style,
+            key_sort=ITEM_FIELD_SORT,
+            make_parents=True,
+        )
+    else:
+        # Write the main file with just the body (no frontmatter)
+        with atomic_output_file(path, make_parents=True) as f:
+            f.write_text(body, encoding="utf-8")
+
+        # Sidematter metadata
+        spath.write_meta(item.metadata(), key_sort=ITEM_FIELD_SORT)
 
     # Update cache.
     _item_cache.update(path, item)
 
-    # Update the item's body to reflect normalization.
+    # Update the item.
+    item.title = title
     item.body = body
 
 
-def read_item(path: Path, base_dir: Path | None) -> Item:
+def read_item(path: Path, base_dir: Path | None, preserve_filename: bool = True) -> Item:
     """
-    Read an item from a file. Uses `base_dir` to resolve paths, so the item's
+    Read a text item from a file. Uses `base_dir` to resolve paths, so the item's
     `store_path` will be set and be relative to `base_dir`.
 
-    If frontmatter format YAML is present, it is parsed. If not, the item will
-    be a resource with a format inferred from the file extension or the content.
+    Automatically detects and reads sidematter format (metadata in .meta.yml/.meta.json
+    sidecar files), which takes precedence over frontmatter when present. Falls back to
+    frontmatter format YAML if no sidematter is found. If neither is present, the item
+    will be a resource with a format inferred from the file extension or the content.
+
     The `store_path` will be the path relative to the `base_dir`, if the file
     is within `base_dir`, or otherwise the `external_path` will be set to the path
     it was read from.
@@ -98,20 +130,48 @@ def read_item(path: Path, base_dir: Path | None) -> Item:
         log.debug("Cache hit for item: %s", path)
         return cached_item
 
-    return _read_item_uncached(path, base_dir)
+    return _read_item_uncached(path, base_dir, preserve_filename=preserve_filename)
 
 
 @tally_calls()
-def _read_item_uncached(path: Path, base_dir: Path | None) -> Item:
+def _read_item_uncached(
+    path: Path,
+    base_dir: Path | None,
+    *,
+    preserve_filename: bool = True,
+    prefer_frontmatter: bool = True,
+) -> Item:
+    # First, try to resolve sidematter
+    sidematter = Sidematter(path).resolve(use_frontmatter=False)
+
+    # Use sidematter metadata unless we find and prefer frontmatter for metadata.
     has_frontmatter = fmf_has_frontmatter(path)
-    body = metadata = None
-    if has_frontmatter:
+    frontmatter_meta = prefer_frontmatter and has_frontmatter and fmf_read_frontmatter(path)
+    if sidematter.meta and not frontmatter_meta:
+        metadata = sidematter.meta
+        body, _frontmatter_metadata = fmf_read(path)
+        log.debug(
+            "Read item from sidematter %s: body length %s, metadata %s",
+            sidematter.meta_path,
+            len(body),
+            metadata,
+        )
+    elif has_frontmatter:
         body, metadata = fmf_read(path)
-        log.debug("Read item from %s: body length %s, metadata %s", path, len(body), metadata)
+        log.debug(
+            "Read item from %s: body length %s, metadata %s",
+            path,
+            len(body),
+            metadata,
+        )
+    else:
+        # Not readable, binary or otherwise.
+        metadata = None
+        body = None
 
-        path = path.resolve()
-        if base_dir:
-            base_dir = base_dir.resolve()
+    path = path.resolve()
+    if base_dir:
+        base_dir = base_dir.resolve()
 
     # Ensure store_path is used if it's within the base_dir, and
     # external_path otherwise.
@@ -128,7 +188,8 @@ def _read_item_uncached(path: Path, base_dir: Path | None) -> Item:
             metadata, body=body, store_path=store_path, external_path=external_path
         )
     else:
-        # This is a file without frontmatter. Infer format from the file and content,
+        # This is a file without frontmatter or sidematter.
+        # Infer format from the file and content,
         # and use store_path or external_path as appropriate.
         item = Item.from_external_path(path)
         if item.format:
@@ -154,6 +215,10 @@ def _read_item_uncached(path: Path, base_dir: Path | None) -> Item:
                 item.body = f.read()
             item.external_path = None
 
+    # Preserve the original filename.
+    if preserve_filename:
+        item.original_filename = path.name
+
     # Update modified time.
     item.set_modified(path.stat().st_mtime)
 

kash/help/help_types.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import TYPE_CHECKING, ClassVar
 
-from flowmark.sentence_split_regex import split_sentences_regex
+from flowmark import split_sentences_regex
 from rich.console import Group
 from rich.text import Text
 from strif import abbrev_str, single_line

kash/llm_utils/llms.py

@@ -13,6 +13,10 @@ class LLM(LLMName, Enum):
     """
 
     # https://platform.openai.com/docs/models
+    gpt_5 = LLMName("gpt-5")
+    gpt_5_mini = LLMName("gpt-5-mini")
+    gpt_5_nano = LLMName("gpt-5-nano")
+    gpt_5_chat = LLMName("gpt-5-chat")
     o4_mini = LLMName("o4-mini")
     o3 = LLMName("o3")
     o3_pro = LLMName("o3-pro")
@@ -25,11 +29,12 @@ class LLM(LLMName, Enum):
     gpt_4o = LLMName("gpt-4o")
     gpt_4o_mini = LLMName("gpt-4o-mini")
     gpt_4 = LLMName("gpt-4")
-
     gpt_4_1_mini = LLMName("gpt-4.1-mini")
     gpt_4_1_nano = LLMName("gpt-4.1-nano")
 
     # https://docs.anthropic.com/en/docs/about-claude/models/all-models
+
+    claude_4_1_opus = LLMName("claude-opus-4-1")
     claude_4_opus = LLMName("claude-opus-4-20250514")
     claude_4_sonnet = LLMName("claude-sonnet-4-20250514")
     claude_3_7_sonnet = LLMName("claude-3-7-sonnet-latest")

kash/local_server/local_server_commands.py

@@ -49,7 +49,8 @@ def local_server_logs(follow: bool = False) -> None:
     """
     Show the logs from the kash local (UI and MCP) servers.
 
-    :param follow: Follow the file as it grows.
+    Args:
+        follow: Follow the file as it grows.
     """
     log_path = global_settings().local_server_log_path
     if not log_path.exists():

kash/mcp/mcp_server_commands.py

@@ -54,8 +54,9 @@ def mcp_logs(follow: bool = False, all: bool = False) -> None:
     """
     Show the logs from the MCP server and CLI proxy process.
 
-    :param follow: Follow the file as it grows.
-    :param all: Show all logs, not just the server logs, including Claude Desktop logs if found.
+    Args:
+        follow: Follow the file as it grows.
+        all: Show all logs, not just the server logs, including Claude Desktop logs if found.
     """
     from kash.mcp.mcp_cli import MCP_CLI_LOG_PATH
 

kash/mcp/mcp_server_routes.py

@@ -238,7 +238,7 @@ def run_mcp_tool(action_name: str, arguments: dict) -> list[TextContent]:
                 action_input = prepare_action_input(*input_items)
 
                 result, result_store_paths, _archived_store_paths = run_action_with_caching(
-                    context=context, action_input=action_input
+                    context, action_input
                 )
 
         # Return final result, formatted for the LLM to understand.

kash/model/actions_model.py

@@ -21,9 +21,8 @@ from kash.exec_model.args_model import NO_ARGS, ONE_ARG, ArgCount, ArgType, Sign
 from kash.exec_model.shell_model import ShellResult
 from kash.llm_utils import LLM, LLMName
 from kash.llm_utils.llm_messages import Message, MessageTemplate
-from kash.model.exec_model import ExecContext
+from kash.model.exec_model import ActionContext, ExecContext
 from kash.model.items_model import UNTITLED, Format, Item, ItemType
-from kash.model.operations_model import Operation, Source
 from kash.model.params_model import (
     ALL_COMMON_PARAMS,
     COMMON_SHELL_PARAMS,
@@ -61,6 +60,17 @@ class ActionInput:
         """An empty input, for when an action processes no items."""
         return ActionInput(items=[])
 
+    # XXX For convenience, we have the ability to include the context on each item
+    # (this helps soper-item functions don't have to take context args everywhere).
+    # TODO: Probably better to move this to a context var.
+    def set_context(self, context: ActionContext) -> None:
+        for item in self.items:
+            item.context = context
+
+    def clear_context(self) -> None:
+        for item in self.items:
+            item.context = None
+
 
 class PathOpType(Enum):
     archive = "archive"
@@ -111,6 +121,10 @@ class ActionResult:
             self.replaces_input or self.skip_duplicates or self.path_ops or self.shell_result
         )
 
+    def set_context(self, context: ActionContext) -> None:
+        for item in self.items:
+            item.context = context
+
     def clear_context(self):
         for item in self.items:
             item.context = None
@@ -505,33 +519,17 @@ class Action(ABC):
                 fmt_lines(overrides),
             )
 
-    def _preassemble_one(
-        self,
-        operation: Operation,
-        input: ActionInput,
-        output_num: int,
-        type: ItemType,
-        **kwargs,
-    ) -> Item:
+    def format_title(self, prev_title: str | None) -> str:
         """
-        Preassemble a single empty output item from the given input items. Include the title,
-        type, and last Operation so we can do an identity check if the output already exists.
+        Format the title for an output item of this action.
         """
-        primary_input = input.items[output_num]
-        item = primary_input.derived_copy(type=type, body=None, **kwargs)
-
+        prev_title = prev_title or UNTITLED
         if self.title_template:
-            item.title = self.title_template.format(
-                title=primary_input.title or UNTITLED, action_name=self.name
-            )
-
-        item.update_history(
-            Source(operation=operation, output_num=output_num, cacheable=self.cacheable)
-        )
-
-        return item
+            return self.title_template.format(title=prev_title, action_name=self.name)
+        else:
+            return prev_title
 
-    def preassemble(self, operation: Operation, input: ActionInput) -> ActionResult | None:
+    def preassemble_result(self, context: ActionContext) -> ActionResult | None:
         """
         Actions can have a separate preliminary step to pre-assemble outputs. This allows
         us to determine the title and types for the output items and check if they were
@@ -549,9 +547,11 @@ class Action(ABC):
             self.cacheable,
         )
         if can_preassemble:
-            return ActionResult(
-                [self._preassemble_one(operation, input, output_num=0, type=self.output_type)]
-            )
+            # Using first input to determine the output title.
+            primary_input = context.action_input.items[0]
+            # In this case we only expect one output.
+            item = primary_input.derived_copy(context, 0)
+            return ActionResult([item])
         else:
             # Caching disabled.
             return None
@@ -600,7 +600,7 @@ class Action(ABC):
         return input_schema
 
     @abstractmethod
-    def run(self, input: ActionInput, context: ExecContext) -> ActionResult:
+    def run(self, input: ActionInput, context: ActionContext) -> ActionResult:
         pass
 
     def __repr__(self):
@@ -626,7 +626,7 @@ class PerItemAction(Action, ABC):
         super().__post_init__()
 
     @override
-    def run(self, input: ActionInput, context: ExecContext) -> ActionResult:
+    def run(self, input: ActionInput, context: ActionContext) -> ActionResult:
         log.info("Running action `%s` per-item.", self.name)
         for item in input.items:
             item.context = context
@@ -642,3 +642,4 @@ class PerItemAction(Action, ABC):
 # Handle circular dependency in Python dataclasses.
 rebuild_dataclass(Item)  # pyright: ignore
 rebuild_dataclass(ExecContext)  # pyright: ignore
+rebuild_dataclass(ActionContext)  # pyright: ignore

kash/model/compound_actions_model.py

@@ -5,7 +5,8 @@ from pydantic.dataclasses import dataclass
 
 from kash.config.logger import get_logger
 from kash.exec.combiners import Combiner
-from kash.model.actions_model import Action, ActionInput, ActionResult, ExecContext
+from kash.model.actions_model import Action, ActionInput, ActionResult
+from kash.model.exec_model import ActionContext
 from kash.model.items_model import Item, State
 from kash.model.params_model import RawParamValues
 from kash.model.paths_model import StorePath
@@ -46,7 +47,7 @@ class SequenceAction(Action):
         )
         self.description = seq_description
 
-    def run(self, input: ActionInput, context: ExecContext) -> ActionResult:
+    def run(self, input: ActionInput, context: ActionContext) -> ActionResult:
         from kash.exec.action_exec import run_action_with_shell_context
         from kash.workspaces import current_ws
 
@@ -140,7 +141,7 @@ class ComboAction(Action):
 
         self.description = combo_description
 
-    def run(self, input: ActionInput, context: ExecContext) -> ActionResult:
+    def run(self, input: ActionInput, context: ActionContext) -> ActionResult:
         from kash.exec.action_exec import run_action_with_shell_context
         from kash.exec.combiners import combine_as_paragraphs
 

kash/model/exec_model.py

@@ -8,10 +8,11 @@ from pydantic.dataclasses import dataclass
 
 from kash.config.logger import get_logger
 from kash.model.items_model import State
+from kash.model.operations_model import Operation
 
 if TYPE_CHECKING:
     from kash.file_storage.file_store import FileStore
-    from kash.model.actions_model import Action
+    from kash.model.actions_model import Action, ActionInput
 
 
 log = get_logger(__name__)
@@ -68,8 +69,8 @@ class RuntimeSettings:
 @dataclass(frozen=True)
 class ExecContext:
     """
-    An action and its context for execution. This is a good place for settings
-    that apply to any action and are bothersome to pass as parameters.
+    An action and its general context for execution. This is a good place for general
+    settings that apply to any action and are bothersome to pass as parameters.
     """
 
     action: Action
@@ -77,3 +78,29 @@ class ExecContext:
 
     settings: RuntimeSettings
     """The workspace and other run-time settings for the action."""
+
+
+@dataclass(frozen=True)
+class ActionContext:
+    """
+    All context for the currently executing action, with all inputs and options.
+    """
+
+    exec_context: ExecContext
+    """The context of the current execution."""
+
+    action_input: ActionInput
+    """The assembled input to the current action."""
+
+    operation: Operation
+    """The operation in full detail, including inputs and options."""
+
+    @property
+    def action(self) -> Action:
+        """The action being executed."""
+        return self.exec_context.action
+
+    @property
+    def settings(self) -> RuntimeSettings:
+        """The workspace and other run-time settings for the action."""
+        return self.exec_context.settings