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

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/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/exec/action_decorators.py

@@ -31,7 +31,7 @@ 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
@@ -328,7 +328,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] = {}

kash/exec/action_exec.py

@@ -23,7 +23,7 @@ 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
@@ -42,6 +42,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 +50,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 +110,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 +125,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 +154,7 @@ def check_for_existing_result(
 
 
 def run_action_operation(
-    context: ExecContext,
+    context: ActionContext,
     action_input: ActionInput,
     operation: Operation,
 ) -> ActionResult:
@@ -205,7 +204,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.
@@ -341,7 +340,7 @@ def save_action_result(
 
 
 def run_action_with_caching(
-    context: ExecContext, action_input: ActionInput
+    exec_context: ExecContext, action_input: ActionInput
 ) -> tuple[ActionResult, list[StorePath], list[StorePath]]:
     """
     Run an action, including validation, only rerunning if `rerun` requested or
@@ -350,57 +349,64 @@ def run_action_with_caching(
 
     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
-
     # 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()
 
     return result, result_store_paths, archived_store_paths
 

kash/exec/fetch_url_items.py

@@ -2,7 +2,7 @@ from dataclasses import dataclass
 
 from kash.config.logger import get_logger
 from kash.exec.preconditions import is_url_resource
-from kash.model.items_model import Item, ItemType
+from kash.model.items_model import Format, Item, ItemType
 from kash.model.paths_model import StorePath
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url, is_url
@@ -36,7 +36,15 @@ def fetch_url_item(
     save_content: bool = True,
     refetch: bool = False,
     cache: bool = True,
+    overwrite: bool = True,
 ) -> FetchItemResult:
+    """
+    Fetch or load an URL or path. For a URL, will fetch the content and metadata and save
+    as an item in the workspace.
+
+    Returns:
+        The fetched or loaded item, already saved to the workspace.
+    """
     from kash.workspaces import current_ws
 
     ws = current_ws()
@@ -51,11 +59,22 @@ def fetch_url_item(
     else:
         raise InvalidInput(f"Not a URL or URL resource: {fmt_loc(locator)}")
 
-    return fetch_url_item_content(item, save_content=save_content, refetch=refetch, cache=cache)
+    return fetch_url_item_content(
+        item,
+        save_content=save_content,
+        refetch=refetch,
+        cache=cache,
+        overwrite=overwrite,
+    )
 
 
 def fetch_url_item_content(
-    item: Item, *, save_content: bool = True, refetch: bool = False, cache: bool = True
+    item: Item,
+    *,
+    save_content: bool = True,
+    refetch: bool = False,
+    cache: bool = True,
+    overwrite: bool = True,
 ) -> FetchItemResult:
     """
     Fetch content and metadata for a URL using a media service if we
@@ -67,8 +86,11 @@ def fetch_url_item_content(
 
     If `cache` is true, the content is also cached in the local file cache.
 
-    The content item is returned if content was saved. Otherwise, the updated
-    URL item is returned.
+    If `overwrite` is true, the item is saved at the same location every time.
+    This is useful to keep resource filenames consistent.
+
+    Returns:
+        The fetched or loaded item, already saved to the workspace.
     """
     from kash.media_base.media_services import get_media_metadata
     from kash.web_content.canon_url import canonicalize_url
@@ -109,7 +131,10 @@ def fetch_url_item_content(
         url_item = item.merged_copy(url_item)
     else:
         page_data = fetch_page_content(url, refetch=refetch, cache=cache)
-        url_item = item.new_copy_with(
+        url_item = Item(
+            type=ItemType.resource,
+            format=Format.url,
+            url=url,
             title=page_data.title or item.title,
             description=page_data.description or item.description,
             thumbnail_url=page_data.thumbnail_url or item.thumbnail_url,
@@ -128,10 +153,10 @@ def fetch_url_item_content(
         log.warning("Failed to fetch page data: title is missing: %s", item.url)
 
     # Now save the updated URL item and also the content item if we have one.
-    ws.save(url_item)
+    ws.save(url_item, overwrite=overwrite)
     assert url_item.store_path
     if content_item:
-        ws.save(content_item)
+        ws.save(content_item, overwrite=overwrite)
         assert content_item.store_path
         log.info(
             "Saved both URL and content item: %s, %s",
@@ -144,4 +169,6 @@ def fetch_url_item_content(
     was_cached = bool(
         not page_data or (page_data.cache_result and page_data.cache_result.was_cached)
     )
-    return FetchItemResult(content_item or url_item, was_cached=was_cached, page_data=page_data)
+    return FetchItemResult(
+        item=content_item or url_item, was_cached=was_cached, page_data=page_data
+    )

kash/exec/preconditions.py

@@ -69,7 +69,7 @@ def is_instructions(item: Item) -> bool:
 
 @kash_precondition
 def is_url_resource(item: Item) -> bool:
-    return bool(item.type == ItemType.resource and item.url)
+    return bool(item.type == ItemType.resource and item.format == Format.url and item.url)
 
 
 @kash_precondition
@@ -126,7 +126,7 @@ def has_markdown_with_html_body(item: Item) -> bool:
 
 @kash_precondition
 def has_fullpage_html_body(item: Item) -> bool:
-    return bool(has_html_body(item) and item.body and is_fullpage_html(item.body))
+    return bool(has_html_compatible_body(item) and item.body and is_fullpage_html(item.body))
 
 
 @kash_precondition

kash/exec/resolve_args.py

@@ -118,10 +118,13 @@ def import_locator_args(
     *locators_or_strs: UnresolvedLocator,
     as_type: ItemType = ItemType.resource,
     reimport: bool = False,
+    with_sidematter: bool = False,
 ) -> list[StorePath]:
     """
     Import locators into the current workspace.
     """
     locators = [resolve_locator_arg(loc) for loc in locators_or_strs]
     ws = current_ws()
-    return ws.import_items(*locators, as_type=as_type, reimport=reimport)
+    return ws.import_items(
+        *locators, as_type=as_type, reimport=reimport, with_sidematter=with_sidematter
+    )

kash/exec/runtime_settings.py

@@ -105,6 +105,7 @@ def kash_runtime(
 ) -> RuntimeSettingsManager:
     """
     Set a specific kash execution context for a with block.
+
     This allows defining a workspace and other execution settings as the ambient
     context within the block.
 

kash/file_storage/file_store.py

@@ -1,5 +1,6 @@
 import functools
 import os
+import shutil
 import threading
 import time
 from collections.abc import Callable, Generator
@@ -9,12 +10,12 @@ from typing import Concatenate, ParamSpec, TypeVar
 
 from funlog import format_duration, log_calls
 from prettyfmt import fmt_lines, fmt_path
-from strif import copyfile_atomic, hash_file, move_file
+from sidematter_format import copy_sidematter, move_sidematter, remove_sidematter
+from strif import copyfile_atomic, hash_file
 from typing_extensions import override
 
 from kash.config.logger import get_log_settings, get_logger
 from kash.config.text_styles import EMOJI_SAVED
-from kash.file_storage.item_file_format import read_item, write_item
 from kash.file_storage.metadata_dirs import MetadataDirs
 from kash.file_storage.store_filenames import (
     folder_for_type,
@@ -83,11 +84,6 @@ class FileStore(Workspace):
     def base_dir(self) -> Path:
         return self.base_dir_path
 
-    @property
-    @override
-    def assets_dir(self) -> Path:
-        return self.base_dir / "assets"
-
     @synchronized
     @log_calls(level="warning", if_slower_than=2.0)
     def reload(self, auto_init: bool = True):
@@ -345,16 +341,23 @@ class FileStore(Workspace):
 
             return StorePath(store_path), old_store_path
 
-    def target_path_for(self, item: Item) -> Path:
+    @synchronized
+    def assign_store_path(self, item: Item) -> Path:
         """
-        Get an the absolute path for an item. Use this if you need to work around the
-        usual save mechanism and write directly to the store yourself, at the location
-        the item usually would be saved.
+        Pick a new store path for the item and mutate `item.store_path`.
 
-        If you write to this path, then set the item's `external_path` to indicate it's
-        already saved.
+        This is useful if you need to write to the store yourself, at the location
+        the item usually would be saved, and also want the path to be fixed.
+
+        This is idempotent. If you also write to the file, call `mark_as_saved()`
+        to indicate that the file is now saved. Otherwise the item should be saved
+        with `save()`.
+
+        Returns the absolute path, for convenience if you wish to write to the file
+        directly.
         """
         store_path, _old_store_path = self.store_path_for(item)
+        item.store_path = str(store_path)
         return self.base_dir / store_path
 
     def _tmp_path_for(self, item: Item) -> StorePath:
@@ -455,6 +458,8 @@ class FileStore(Workspace):
                     # Save as a text item with frontmatter.
                     if item.external_path:
                         item.body = Path(item.external_path).read_text()
+                    from kash.file_storage.item_file_format import write_item
+
                     write_item(item, full_path, normalize=not no_format)
             except OSError as e:
                 log.error("Error saving item: %s", e)
@@ -499,6 +504,8 @@ class FileStore(Workspace):
         """
         Load item at the given path.
         """
+        from kash.file_storage.item_file_format import read_item
+
         return read_item(self.base_dir / store_path, self.base_dir)
 
     def hash(self, store_path: StorePath) -> str:
@@ -513,6 +520,7 @@ class FileStore(Workspace):
         *,
         as_type: ItemType | None = None,
         reimport: bool = False,
+        with_sidematter: bool = False,
     ) -> StorePath:
         """
         Add resources from files or URLs. If a locator is a path, copy it into the store.
@@ -520,7 +528,10 @@ class FileStore(Workspace):
         are not imported again and the existing store path is returned.
         If `as_type` is specified, it will be used to override the item type, otherwise
         we go with our best guess.
+        If `with_sidematter` is true, will copy any sidematter files (metadata/assets) to
+        the destination.
         """
+        from kash.file_storage.item_file_format import read_item
         from kash.web_content.canon_url import canonicalize_url
 
         if isinstance(locator, StorePath) and not reimport:
@@ -580,6 +591,9 @@ class FileStore(Workspace):
                 # we'll pick a new store path.
                 store_path = self.save(item)
                 log.info("Imported text file: %s", item.as_str())
+                # If requested, also copy any sidematter files (metadata/assets) to match destination.
+                if with_sidematter:
+                    copy_sidematter(path, self.base_dir / store_path, copy_original=False)
             else:
                 # Binary or other files we just copy over as-is, preserving the name.
                 # We know the extension is recognized.
@@ -588,7 +602,10 @@ class FileStore(Workspace):
                     raise FileExists(f"Resource already in store: {fmt_loc(store_path)}")
 
                 log.message("Importing resource: %s", fmt_loc(path))
-                copyfile_atomic(path, self.base_dir / store_path, make_parents=True)
+                if with_sidematter:
+                    copy_sidematter(path, self.base_dir / store_path)
+                else:
+                    copyfile_atomic(path, self.base_dir / store_path, make_parents=True)
 
                 # Optimization: Don't import an identical file twice.
                 if old_store_path:
@@ -599,7 +616,10 @@ class FileStore(Workspace):
                             "Imported resource is identical to the previous import: %s",
                             fmt_loc(old_store_path),
                         )
-                        os.unlink(self.base_dir / store_path)
+                        if with_sidematter:
+                            remove_sidematter(self.base_dir / store_path)
+                        else:
+                            os.unlink(self.base_dir / store_path)
                         store_path = old_store_path
                 log.message("Imported resource: %s", fmt_loc(store_path))
             return store_path
@@ -609,16 +629,20 @@ class FileStore(Workspace):
         *locators: Locator,
         as_type: ItemType | None = None,
         reimport: bool = False,
+        with_sidematter: bool = False,
     ) -> list[StorePath]:
         return [
-            self.import_item(locator, as_type=as_type, reimport=reimport) for locator in locators
+            self.import_item(
+                locator, as_type=as_type, reimport=reimport, with_sidematter=with_sidematter
+            )
+            for locator in locators
         ]
 
-    def import_and_load(self, locator: UnresolvedLocator) -> Item:
+    def import_and_load(self, locator: UnresolvedLocator, with_sidematter: bool = False) -> Item:
         """
         Import a locator and return the item.
         """
-        store_path = self.import_item(locator)
+        store_path = self.import_item(locator, with_sidematter=with_sidematter)
         return self.load(store_path)
 
     def _filter_selection_paths(self):
@@ -660,7 +684,12 @@ class FileStore(Workspace):
         # TODO: Update metadata of all relations that point to this path too.
 
     def archive(
-        self, store_path: StorePath, *, missing_ok: bool = False, quiet: bool = False
+        self,
+        store_path: StorePath,
+        *,
+        missing_ok: bool = False,
+        quiet: bool = False,
+        with_sidematter: bool = False,
     ) -> StorePath:
         """
         Archive the item by moving it into the archive directory.
@@ -672,20 +701,24 @@ class FileStore(Workspace):
                 fmt_loc(self.dirs.archive_dir),
             )
         orig_path = self.base_dir / store_path
-        archive_path = self.dirs.archive_dir / store_path
+        full_archive_path = self.base_dir / self.dirs.archive_dir / store_path
         if missing_ok and not orig_path.exists():
             log.message("Item to archive not found so moving on: %s", fmt_loc(orig_path))
             return store_path
         if not orig_path.exists():
             log.warning("Item to archive not found: %s", fmt_loc(orig_path))
             return store_path
-        move_file(orig_path, archive_path)
+        if with_sidematter:
+            move_sidematter(orig_path, full_archive_path)
+        else:
+            os.makedirs(full_archive_path.parent, exist_ok=True)
+            shutil.move(orig_path, full_archive_path)
         self._remove_references([store_path])
 
         archive_path = StorePath(self.dirs.archive_dir / store_path)
         return archive_path
 
-    def unarchive(self, store_path: StorePath) -> StorePath:
+    def unarchive(self, store_path: StorePath, with_sidematter: bool = False) -> StorePath:
         """
         Unarchive the item by moving back out of the archive directory.
         Path may be with or without the archive dir prefix.
@@ -695,7 +728,10 @@ class FileStore(Workspace):
         if full_input_path.is_relative_to(full_archive_path):
             store_path = StorePath(relpath(full_input_path, full_archive_path))
         original_path = self.base_dir / store_path
-        move_file(full_input_path, original_path)
+        if with_sidematter:
+            move_sidematter(full_input_path, original_path)
+        else:
+            shutil.move(full_input_path, original_path)
         return StorePath(store_path)
 
     @synchronized