kash-shell 0.3.9__py3-none-any.whl → 0.3.10__py3-none-any.whl

kash/commands/workspace/selection_commands.py

@@ -27,8 +27,9 @@ def select(
     previous: bool = False,
     next: bool = False,
     pop: bool = False,
-    clear: bool = False,
+    clear_all: bool = False,
     clear_future: bool = False,
+    refresh: bool = False,
 ) -> ShellResult:
     """
     Set or show the current selection.
@@ -47,12 +48,13 @@ def select(
     :param previous: Move back in the selection history to the previous selection.
     :param next: Move forward in the selection history to the next selection.
     :param pop: Pop the current selection from the history.
-    :param clear: Clear the full selection history.
+    :param clear_all: Clear the full selection history.
     :param clear_future: Clear all selections from history after the current one.
+    :param refresh: Refresh the current selection to drop any paths that no longer exist.
     """
     ws = current_ws()
 
-    # TODO: It would be nice to be able to read stdin from a pipe but this isn't working rn.
+    # FIXME: It would be nice to be able to read stdin from a pipe but this isn't working rn.
     # You could then run `... | select --stdin` to select the piped input.
     # Globally we have THREAD_SUBPROCS=False to avoid hard-to-interrupt subprocesses.
     # But xonsh seems to hang with stdin unless we modify the spec to be threadable?
@@ -61,7 +63,7 @@ def select(
     # if stdin:
     #     paths = tuple(sys.stdin.read().splitlines())
 
-    exclusive_flags = [history, last, back, forward, previous, next, pop, clear, clear_future]
+    exclusive_flags = [history, last, back, forward, previous, next, pop, clear_all, clear_future]
     if sum(bool(f) for f in exclusive_flags) > 1:
         raise InvalidInput("Cannot combine multiple flags")
     if paths and any(exclusive_flags):
@@ -96,12 +98,15 @@ def select(
     elif pop:
         ws.selections.pop()
         return ShellResult(show_selection=True)
-    elif clear:
-        ws.selections.clear()
+    elif clear_all:
+        ws.selections.clear_all()
         return ShellResult(show_selection=True)
     elif clear_future:
         ws.selections.clear_future()
         return ShellResult(show_selection=True)
+    elif refresh:
+        ws.selections.refresh_current(ws.base_dir)
+        return ShellResult(show_selection=True)
     else:
         return ShellResult(show_selection=True)
 

kash/commands/workspace/workspace_commands.py

@@ -15,7 +15,6 @@ from kash.config.text_styles import (
     EMOJI_WARN,
     STYLE_EMPH,
     STYLE_HINT,
-    format_success_emoji,
 )
 from kash.exec import (
     assemble_path_args,
@@ -36,7 +35,11 @@ from kash.model.items_model import Item, ItemType
 from kash.model.params_model import GLOBAL_PARAMS
 from kash.model.paths_model import StorePath, fmt_store_path
 from kash.shell.input.param_inputs import input_param_name, input_param_value
-from kash.shell.output.shell_formatting import format_name_and_description, format_name_and_value
+from kash.shell.output.shell_formatting import (
+    format_name_and_description,
+    format_name_and_value,
+    format_success_emoji,
+)
 from kash.shell.output.shell_output import (
     PrintHooks,
     Wrap,
@@ -170,14 +173,15 @@ def cache_media(*urls: str) -> None:
 
 
 @kash_command
-def cache_content(*urls_or_paths: str) -> None:
+def cache_content(*urls_or_paths: str, refetch: bool = False) -> None:
     """
     Cache the given file in the content cache. Downloads any URL or copies a local file.
     """
+    expiration_sec = 0 if refetch else None
     PrintHooks.spacer()
     for url_or_path in urls_or_paths:
         locator = resolve_locator_arg(url_or_path)
-        cache_path, was_cached = cache_file(locator)
+        cache_path, was_cached = cache_file(locator, expiration_sec=expiration_sec)
         cache_str = " (already cached)" if was_cached else ""
         cprint(f"{fmt_loc(url_or_path)}{cache_str}:", style=STYLE_EMPH, text_wrap=Wrap.NONE)
         cprint(f"{cache_path}", text_wrap=Wrap.INDENT_ONLY)
@@ -185,10 +189,13 @@ def cache_content(*urls_or_paths: str) -> None:
 
 
 @kash_command
-def download(*urls_or_paths: str) -> None:
+def download(*urls_or_paths: str, refetch: bool = False) -> None:
     """
-    Download a URL or resource. Inputs can be URLs or paths to URL resources.
+    Download a URL or resource. Uses cached content if available, unless `refetch` is true.
+    Inputs can be URLs or paths to URL resources.
     """
+    expiration_sec = 0 if refetch else None
+
     # TODO: Add option to include frontmatter metadata for text files.
     ws = current_ws()
     for url_or_path in urls_or_paths:
@@ -211,7 +218,7 @@ def download(*urls_or_paths: str) -> None:
             media_tools.cache_media(url)
         else:
             log.message("Will cache file and save to workspace: %s", fmt_loc(url))
-            cache_path, _was_cached = cache_file(url)
+            cache_path, _was_cached = cache_file(url, expiration_sec=expiration_sec)
             item = Item.from_external_path(cache_path, item_type=ItemType.resource)
             store_path = ws.save(item)
 
@@ -402,12 +409,10 @@ def set_params(*key_vals: str) -> None:
 
 
 @kash_command
-def list_params(full: bool = False) -> None:
+def params(full: bool = False) -> None:
     """
-    Show or set currently set of workspace parameters, which are settings that may be used
+    List currently set workspace parameters, which are settings that may be used
     by commands and actions or to override default parameters.
-
-    Run with no args to interactively set parameters.
     """
     ws: Workspace = current_ws()
     settable_params = GLOBAL_PARAMS
@@ -461,9 +466,7 @@ def import_item(
 
 
 @kash_command
-def fetch_metadata(
-    *files_or_urls: str, no_cache: bool = False, refetch: bool = False
-) -> ShellResult:
+def fetch_metadata(*files_or_urls: str, refetch: bool = False) -> ShellResult:
     """
     Fetch metadata for the given URLs or resources. Imports new URLs and saves back
     the fetched metadata for existing resources.
@@ -483,7 +486,7 @@ def fetch_metadata(
         try:
             if isinstance(locator, Path):
                 raise InvalidInput()
-            fetched_item = fetch_url_metadata(locator, use_cache=not no_cache, refetch=refetch)
+            fetched_item = fetch_url_metadata(locator, refetch=refetch)
             store_paths.append(fetched_item.store_path)
         except InvalidInput:
             log.warning("Not a URL or URL resource, will not fetch metadata: %s", fmt_loc(locator))

kash/config/colors.py

@@ -134,8 +134,10 @@ web_light_translucent = SimpleNamespace(
     primary_light=hsl_to_hex("hsl(188, 40%, 62%)"),
     secondary=hsl_to_hex("hsl(188, 12%, 28%)"),
     bg=hsl_to_hex("hsla(44, 6%, 100%, 0.75)"),
+    bg_solid=hsl_to_hex("hsla(44, 6%, 100%, 1)"),
     bg_header=hsl_to_hex("hsla(188, 42%, 70%, 0.2)"),
     bg_alt=hsl_to_hex("hsla(44, 28%, 90%, 0.3)"),
+    bg_alt_solid=hsl_to_hex("hsla(44, 28%, 97%, 1)"),
     text=hsl_to_hex("hsl(188, 39%, 11%)"),
     border=hsl_to_hex("hsl(188, 8%, 50%)"),
     border_hint=hsl_to_hex("hsla(188, 8%, 72%, 0.7)"),

kash/config/env_settings.py

@@ -28,6 +28,12 @@ class KashEnv(str, Enum):
     KASH_MCP_WS = "KASH_MCP_WS"
     """The directory for the workspace for MCP servers."""
 
+    KASH_SHOW_TRACEBACK = "KASH_SHOW_TRACEBACK"
+    """Whether to show tracebacks on actions and commands in the shell."""
+
+    KASH_USER_AGENT = "KASH_USER_AGENT"
+    """The user agent to use for HTTP requests."""
+
     @overload
     def read_str(self) -> str | None: ...
 
@@ -42,7 +48,7 @@ class KashEnv(str, Enum):
         return os.environ.get(self.value, default)
 
     @overload
-    def read_path(self, default: None) -> None: ...
+    def read_path(self) -> Path | None: ...
 
     @overload
     def read_path(self, default: Path) -> Path: ...
@@ -57,3 +63,10 @@ class KashEnv(str, Enum):
             return Path(value).expanduser().resolve()
         else:
             return default.expanduser().resolve() if default else None
+
+    def read_bool(self, default: bool = False) -> bool:
+        """
+        Get the value of the environment variable as a boolean.
+        """
+        value = str(os.environ.get(self.value, default) or "").lower()
+        return bool(value and value != "0" and value != "false" and value != "no")

kash/config/init.py

@@ -9,10 +9,10 @@ def kash_reload_all() -> tuple[dict[str, Callable], dict[str, type["Action"]]]:
     """
     Import all kash modules that define actions and commands.
     """
-    from kash.exec.action_registry import reload_all_action_classes
+    from kash.exec.action_registry import refresh_action_classes
     from kash.exec.command_registry import get_all_commands
 
     commands = get_all_commands()
-    actions = reload_all_action_classes()
+    actions = refresh_action_classes()
 
     return commands, actions

kash/config/logger.py

@@ -2,7 +2,6 @@ import contextvars
 import logging
 import os
 import re
-import threading
 from collections.abc import Generator
 from contextlib import contextmanager
 from dataclasses import dataclass
@@ -17,7 +16,7 @@ from rich._null_file import NULL_FILE
 from rich.console import Console
 from rich.logging import RichHandler
 from rich.theme import Theme
-from strif import atomic_output_file, new_timestamped_uid
+from strif import AtomicVar, atomic_output_file, new_timestamped_uid
 from typing_extensions import override
 
 import kash.config.suppress_warnings  # noqa: F401
@@ -38,55 +37,41 @@ from kash.utils.common.stack_traces import current_stack_traces
 from kash.utils.common.task_stack import task_stack_prefix_str
 
 
-@dataclass(frozen=True)
+@dataclass
 class LogSettings:
     log_console_level: LogLevel
     log_file_level: LogLevel
-    # Always the same global log directory.
+
     global_log_dir: Path
+    """Global directory for log files."""
 
     # These directories can change based on the current workspace:
     log_dir: Path
-    log_objects_dir: Path
-    log_file_path: Path
-
-
-_log_dir = get_system_logs_dir()
-"""
-Parent of the "logs" directory. Initially the global kash workspace.
-"""
-
-
-LOG_NAME_GLOBAL = "global"
+    """Parent of the "logs" directory. Initially the global kash workspace."""
 
-_log_name = LOG_NAME_GLOBAL
-"""
-Name of the log file. By default the workspace name or "global" if
-for the global workspace.
-"""
+    log_name: str
+    """Name of the log file. Typically the workspace name or "workspace" if for the global workspace."""
 
-_log_lock = threading.RLock()
+    log_objects_dir: Path
+    log_file_path: Path
 
 
-def make_valid_log_name(name: str) -> str:
-    name = str(name).strip().rstrip("/").removesuffix(".log")
-    name = re.sub(r"[^\w-]", "_", name)
-    return name
+LOG_NAME_GLOBAL = "workspace"
 
 
 def _read_log_settings() -> LogSettings:
-    global _log_dir, _log_name
     return LogSettings(
         log_console_level=global_settings().console_log_level,
         log_file_level=global_settings().file_log_level,
         global_log_dir=get_system_logs_dir(),
-        log_dir=_log_dir,
-        log_objects_dir=_log_dir / "objects" / _log_name,
-        log_file_path=_log_dir / f"{_log_name}.log",
+        log_dir=get_system_logs_dir(),
+        log_name=LOG_NAME_GLOBAL,
+        log_objects_dir=get_system_logs_dir() / "objects" / LOG_NAME_GLOBAL,
+        log_file_path=get_system_logs_dir() / f"{LOG_NAME_GLOBAL}.log",
     )
 
 
-_log_settings: LogSettings = _read_log_settings()
+_log_settings: AtomicVar[LogSettings] = AtomicVar(_read_log_settings())
 
 _setup_done = False
 
@@ -95,19 +80,13 @@ def get_log_settings() -> LogSettings:
     """
     Currently active log settings.
     """
-    return _log_settings
+    return _log_settings.copy()
 
 
-def reset_log_root(log_root: Path | None = None, log_name: str | None = None):
-    """
-    Reset the logging root or log name, if it has changed. None means no change
-    and global default values.
-    """
-    global _log_lock, _log_base, _log_name
-    with _log_lock:
-        _log_base = log_root or get_system_logs_dir()
-        _log_name = make_valid_log_name(log_name or LOG_NAME_GLOBAL)
-        reload_rich_logging_setup()
+def make_valid_log_name(name: str) -> str:
+    name = str(name).strip().rstrip("/").removesuffix(".log")
+    name = re.sub(r"[^\w-]", "_", name)
+    return name
 
 
 console_context_var: contextvars.ContextVar[Console | None] = contextvars.ContextVar(
@@ -169,6 +148,30 @@ _file_handler: logging.FileHandler
 _console_handler: logging.Handler
 
 
+def reset_rich_logging(
+    log_root: Path | None = None,
+    log_name: str | None = None,
+    log_path: Path | None = None,
+):
+    """
+    Set or reset the logging root or log name, if it has changed. None means no change
+    and global default values. `log_name` is the name of the log, excluding
+    the `.log` extension. If `log_path` is provided, it will be used to infer
+    the log root and name.
+    """
+    if log_path:
+        if not log_path.parent.exists():
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+        log_root = log_path.parent
+        log_name = log_path.name
+
+    global _log_settings
+    with _log_settings.updates() as settings:
+        settings.log_dir = log_root or get_system_logs_dir()
+        settings.log_name = make_valid_log_name(log_name or LOG_NAME_GLOBAL)
+        reload_rich_logging_setup()
+
+
 def reload_rich_logging_setup():
     """
     Set up or reset logging setup. This is for rich/formatted console logging and
@@ -176,12 +179,12 @@ def reload_rich_logging_setup():
     Call at initial run and again if log directory changes. Replaces all previous
     loggers and handlers. Can be called to reset with different settings.
     """
-    global _log_lock, _log_settings, _setup_done
-    with _log_lock:
+    global _setup_done, _log_settings
+    with _log_settings.lock:
         new_log_settings = _read_log_settings()
-        if not _setup_done or new_log_settings != _log_settings:
+        if not _setup_done or new_log_settings != _log_settings.value:
             _do_logging_setup(new_log_settings)
-            _log_settings = new_log_settings
+            _log_settings.set(new_log_settings)
             _setup_done = True
 
             # get_console().print(
@@ -190,6 +193,15 @@ def reload_rich_logging_setup():
             # )
 
 
+@cache
+def _init_rich_logging():
+    rich.reconfigure(theme=get_theme(), highlighter=get_highlighter())
+
+    logging.setLoggerClass(CustomLogger)
+
+    reload_rich_logging_setup()
+
+
 def _do_logging_setup(log_settings: LogSettings):
     from kash.config.suppress_warnings import demote_warnings, filter_warnings
 
@@ -319,7 +331,7 @@ class CustomLogger(logging.Logger):
         filename = (
             f"{prefix}{slugify_snake(description)}.{new_timestamped_uid()}.{file_ext.lstrip('.')}"
         )
-        path = _log_settings.log_objects_dir / filename
+        path = _log_settings.copy().log_objects_dir / filename
         with atomic_output_file(path, make_parents=True) as tmp_filename:
             if isinstance(obj, bytes):
                 with open(tmp_filename, "wb") as f:
@@ -346,7 +358,7 @@ def get_logger(name: str) -> CustomLogger:
     Get a logger that's compatible with system logging but has our additional custom
     methods.
     """
-    init_rich_logging()
+    _init_rich_logging()
     logger = logging.getLogger(name)
     # print("Logger is", logger)
     return cast(CustomLogger, logger)
@@ -354,12 +366,3 @@ def get_logger(name: str) -> CustomLogger:
 
 def get_log_file_stream():
     return _file_handler.stream
-
-
-@cache
-def init_rich_logging():
-    rich.reconfigure(theme=get_theme(), highlighter=get_highlighter())
-
-    logging.setLoggerClass(CustomLogger)
-
-    reload_rich_logging_setup()

kash/config/logger_basic.py

@@ -30,7 +30,7 @@ def basic_stderr_handler(level: LogLevel) -> logging.StreamHandler:
     return handler
 
 
-def basic_logging_setup(file_log_path: Path | None, level: LogLevel):
+def basic_logging_setup(log_path: Path | None, level: LogLevel):
     """
     Set up basic logging to a file and to stderr.
     """
@@ -38,8 +38,8 @@ def basic_logging_setup(file_log_path: Path | None, level: LogLevel):
     for h in root_logger.handlers[:]:
         root_logger.removeHandler(h)
 
-    if file_log_path:
-        file_handler: FileHandler = basic_file_handler(file_log_path, level)
+    if log_path:
+        file_handler: FileHandler = basic_file_handler(log_path, level)
         root_logger.addHandler(file_handler)
 
     stderr_handler = basic_stderr_handler(level)

kash/config/settings.py

@@ -5,15 +5,16 @@ from logging import DEBUG, ERROR, INFO, WARNING
 from pathlib import Path
 
 from pydantic.dataclasses import dataclass
+from strif import AtomicVar
 
 from kash.config.env_settings import KashEnv
-from kash.utils.common.atomic_var import AtomicVar
 
 APP_NAME = "kash"
 
 DOT_DIR = ".kash"
 
-GLOBAL_WS_NAME = "global"
+GLOBAL_WS_NAME = "workspace"
+"""Name of the global workspace."""
 
 RECOMMENDED_API_KEYS = [
     "OPENAI_API_KEY",
@@ -23,51 +24,28 @@ RECOMMENDED_API_KEYS = [
 ]
 
 
-def get_ws_root_dir() -> Path:
-    """Default root directory for kash workspaces."""
-    return KashEnv.KASH_WS_ROOT.read_path(Path("~/Kash"))
-
-
-def get_global_ws_dir() -> Path:
-    """Default global workspace directory."""
-    kash_ws_dir = KashEnv.KASH_GLOBAL_WS.read_path(None)
-    if kash_ws_dir:
-        return kash_ws_dir
-    else:
-        return get_ws_root_dir() / GLOBAL_WS_NAME
-
-
-def get_system_config_dir() -> Path:
-    return Path("~/.config/kash").expanduser().resolve()
-
-
-def get_rcfile_path() -> Path:
-    return get_system_config_dir() / "kashrc"
-
-
-def get_system_logs_dir() -> Path:
-    """Default global and system logs directory (for server logs, etc)."""
-    return KashEnv.KASH_SYSTEM_LOGS_DIR.read_path(get_ws_root_dir() / "logs")
-
-
-def get_system_cache_dir() -> Path:
-    """Default global and system cache directory (for global media, content, etc)."""
-    return KashEnv.KASH_SYSTEM_CACHE_DIR.read_path(get_ws_root_dir() / "cache")
-
-
-def get_system_env_path() -> Path:
-    return get_system_config_dir() / "env.local"
-
-
-def get_mcp_ws_dir() -> Path | None:
+def get_all_common_api_env_vars() -> list[str]:
     """
-    Get the directory for the MCP workspace, if set.
+    Get all the common environment variables that are recommended to be set.
     """
-    mcp_dir = KashEnv.KASH_MCP_WS.read_str()
-    if mcp_dir:
-        return Path(mcp_dir).expanduser().resolve()
-    else:
-        return None
+    from clideps.env_vars.env_names import get_all_common_env_names
+
+    return list(set(get_all_common_env_names() + RECOMMENDED_API_KEYS))
+
+
+RECOMMENDED_PKGS = [
+    "less",
+    "eza",
+    "ripgrep",
+    "bat",
+    "zoxide",
+    "dust",
+    "duf",
+    "pygmentize",
+    "hexyl",
+    "ffmpeg",
+    "imagemagick",
+]
 
 
 MEDIA_CACHE_NAME = "media"
@@ -86,11 +64,6 @@ LOCAL_SERVER_PORTS_MAX = 30
 LOCAL_SERVER_LOG_NAME = "local_server"
 
 
-@cache
-def local_server_log_path() -> Path:
-    return resolve_and_create_dirs(get_system_logs_dir() / f"{LOCAL_SERVER_LOG_NAME}.log")
-
-
 class LogLevel(Enum):
     debug = DEBUG
     info = INFO
@@ -146,11 +119,15 @@ def find_in_cwd_or_parents(filename: Path | str) -> Path | None:
     return None
 
 
+def _get_rcfile_path() -> Path:
+    return _get_system_config_dir() / "kashrc"
+
+
 def find_rcfiles() -> list[Path]:
     """
     Find active rcfiles. Currently only supports one.
     """
-    rcfile_path = get_rcfile_path()
+    rcfile_path = _get_rcfile_path()
     if rcfile_path.exists():
         return [rcfile_path]
     else:
@@ -159,9 +136,30 @@ def find_rcfiles() -> list[Path]:
 
 @dataclass
 class Settings:
+    ws_root_dir: Path
+    """A default root directory for kash workspaces (typically `~/Kash`)."""
+
+    global_ws_dir: Path
+    """The directory for the default global workspace."""
+
+    system_config_dir: Path
+    """The directory for system-wide configuration files."""
+
     media_cache_dir: Path
     """The workspace media cache directory, for caching audio, video, and transcripts."""
 
+    system_logs_dir: Path
+    """Default global and system logs directory (for server logs, etc)."""
+
+    system_cache_dir: Path
+    """Default global and system cache directory (for global media, content, etc)."""
+
+    mcp_ws_dir: Path | None
+    """The directory for the MCP workspace, if set."""
+
+    local_server_log_path: Path
+    """The path to the local server log."""
+
     content_cache_dir: Path
     """The workspace content cache directory, for caching web or local files."""
     # TODO: Separate workspace cached content (e.g. thumbnails) vs global files
@@ -198,12 +196,60 @@ class Settings:
     """If true, use Nerd Icons in file listings. Requires a compatible font."""
 
 
-# Initial default settings.
-_settings = AtomicVar(
-    Settings(
+ws_root_dir = Path("~/Kash").expanduser()
+
+
+def _get_ws_root_dir() -> Path:
+    """Default root directory for kash workspaces."""
+    return KashEnv.KASH_WS_ROOT.read_path(default=ws_root_dir)
+
+
+def _get_global_ws_dir() -> Path:
+    kash_ws_dir = KashEnv.KASH_GLOBAL_WS.read_path()
+    if kash_ws_dir:
+        return kash_ws_dir
+    else:
+        return _get_ws_root_dir() / GLOBAL_WS_NAME
+
+
+def get_system_logs_dir() -> Path:
+    return KashEnv.KASH_SYSTEM_LOGS_DIR.read_path(default=_get_ws_root_dir() / "logs")
+
+
+def _get_system_config_dir() -> Path:
+    return Path("~/.config/kash").expanduser().resolve()
+
+
+def _get_system_cache_dir() -> Path:
+    return KashEnv.KASH_SYSTEM_CACHE_DIR.read_path(default=_get_ws_root_dir() / "cache")
+
+
+def _get_mcp_ws_dir() -> Path | None:
+    mcp_dir = KashEnv.KASH_MCP_WS.read_str()
+    if mcp_dir:
+        return Path(mcp_dir).expanduser().resolve()
+    else:
+        return None
+
+
+@cache
+def _get_local_server_log_path() -> Path:
+    return resolve_and_create_dirs(get_system_logs_dir() / f"{LOCAL_SERVER_LOG_NAME}.log")
+
+
+def _read_settings():
+    return Settings(
+        # Essential system settings for logs, workspaces, and configs:
+        ws_root_dir=_get_ws_root_dir(),
+        global_ws_dir=_get_global_ws_dir(),
+        system_config_dir=_get_system_config_dir(),
+        system_logs_dir=get_system_logs_dir(),
+        system_cache_dir=_get_system_cache_dir(),
+        mcp_ws_dir=_get_mcp_ws_dir(),
+        local_server_log_path=_get_local_server_log_path(),
         # These default to the global but can be overridden by workspace settings.
-        media_cache_dir=get_system_cache_dir() / MEDIA_CACHE_NAME,
-        content_cache_dir=get_system_cache_dir() / CONTENT_CACHE_NAME,
+        media_cache_dir=_get_system_cache_dir() / MEDIA_CACHE_NAME,
+        content_cache_dir=_get_system_cache_dir() / CONTENT_CACHE_NAME,
         debug_assistant=True,
         default_editor="nano",
         file_log_level=LogLevel.info,
@@ -215,7 +261,20 @@ _settings = AtomicVar(
         use_kerm_codes=False,
         use_nerd_icons=True,
     )
-)
+
+
+# Initial default settings.
+_settings = AtomicVar(_read_settings())
+
+
+def configure_ws_and_settings(root_dir: Path):
+    """
+    Reset and reload all settings, deriving all paths from the new workspace
+    root. Good if embedding kash in another app.
+    """
+    global ws_root_dir
+    ws_root_dir = root_dir
+    _settings.set(_read_settings())
 
 
 def atomic_global_settings() -> AtomicVar[Settings]: