caffeinated-whale-cli 3.2.0__tar.gz → 3.3.0__tar.gz

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 3.2.0
+Version: 3.3.0
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -2027,7 +2027,7 @@ cwcli config [SUBCOMMAND]
 
 ##### `config show` - Show the Effective Configuration
 
-The one read for everything: the custom search paths, the auto-inspect settings together with live daemon state and boot-hook state, the credential-bridge state (enabled, daemon, transport, wired instances), the tips setting, and the config-file and cache-DB locations.
+The one read for everything: the cache on/off state (and whether `CWCLI_NO_CACHE` is overriding it), the custom search paths, the auto-inspect settings together with live daemon state and boot-hook state, the credential-bridge state (enabled, daemon, transport, wired instances), the tips setting, and the config-file and cache-DB locations.
 
 ```bash
 cwcli config show
@@ -2095,6 +2095,31 @@ cwcli config cache [SUBCOMMAND]
 - **`list [--json]`** - List all projects currently in the cache
   - Example: `cwcli config cache list --json`
 
+- **`disable`** / **`enable`** - Turn the on-disk cache off entirely, or back on (the default)
+  - Example: `cwcli config cache disable`
+  - Example: `cwcli config cache enable`
+  - See ["Disabling caching entirely"](#disabling-caching-entirely) below.
+
+###### Disabling caching entirely
+
+cwcli keeps an on-disk SQLite cache (under `~/.cwcli/cache`, or `$CWCLI_HOME/cache`) that read commands - `inspect`, `status`, `where`, `open`, the `apps` group, tab completion, and every `axi` read verb - work from, so they do not re-inspect a running instance every time.
+
+You can turn it off entirely, in two equivalent ways:
+
+- **Config key:** `cwcli config cache disable` sets `[cache] enabled = false` in the config file. `cwcli config cache enable` reverts it.
+- **Environment variable:** `CWCLI_NO_CACHE=1` disables caching for a single shell or CI job; `CWCLI_NO_CACHE=0` re-enables it. The environment variable **overrides** the config key, so you can force caching on or off for one invocation regardless of the persisted setting.
+
+With caching disabled:
+
+- Every read resolves **live**, as if a fresh `inspect` had just run - a stale cached row can never be served.
+- **Nothing** is written to or read from the cache DB, and a pre-existing cache file is left in place untouched, so re-enabling restores the previous behaviour.
+- Tab completion degrades gracefully to a live/empty lookup rather than serving stale names.
+- `auto-inspect` refuses to start (it exists only to keep the cache warm, which does nothing when caching is off).
+- Bench labels still work, because they are also stored in each bench's marker file.
+- Safety-critical commands (`rm`/`rm-site`'s backup step, `apps checkout`'s wrong-copy detection) get correct live data.
+
+Because every read resolves live, commands are slower than with the cache warm - this is a correctness/isolation mode, not the everyday default.
+
 ##### `config auto-inspect` - Automatic Project Inspection
 
 Manages automatic background inspection of running Frappe projects to keep cached data fresh (tab completion, project status queries, and other commands that rely on cached data).

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/README.md

@@ -1987,7 +1987,7 @@ cwcli config [SUBCOMMAND]
 
 ##### `config show` - Show the Effective Configuration
 
-The one read for everything: the custom search paths, the auto-inspect settings together with live daemon state and boot-hook state, the credential-bridge state (enabled, daemon, transport, wired instances), the tips setting, and the config-file and cache-DB locations.
+The one read for everything: the cache on/off state (and whether `CWCLI_NO_CACHE` is overriding it), the custom search paths, the auto-inspect settings together with live daemon state and boot-hook state, the credential-bridge state (enabled, daemon, transport, wired instances), the tips setting, and the config-file and cache-DB locations.
 
 ```bash
 cwcli config show
@@ -2055,6 +2055,31 @@ cwcli config cache [SUBCOMMAND]
 - **`list [--json]`** - List all projects currently in the cache
   - Example: `cwcli config cache list --json`
 
+- **`disable`** / **`enable`** - Turn the on-disk cache off entirely, or back on (the default)
+  - Example: `cwcli config cache disable`
+  - Example: `cwcli config cache enable`
+  - See ["Disabling caching entirely"](#disabling-caching-entirely) below.
+
+###### Disabling caching entirely
+
+cwcli keeps an on-disk SQLite cache (under `~/.cwcli/cache`, or `$CWCLI_HOME/cache`) that read commands - `inspect`, `status`, `where`, `open`, the `apps` group, tab completion, and every `axi` read verb - work from, so they do not re-inspect a running instance every time.
+
+You can turn it off entirely, in two equivalent ways:
+
+- **Config key:** `cwcli config cache disable` sets `[cache] enabled = false` in the config file. `cwcli config cache enable` reverts it.
+- **Environment variable:** `CWCLI_NO_CACHE=1` disables caching for a single shell or CI job; `CWCLI_NO_CACHE=0` re-enables it. The environment variable **overrides** the config key, so you can force caching on or off for one invocation regardless of the persisted setting.
+
+With caching disabled:
+
+- Every read resolves **live**, as if a fresh `inspect` had just run - a stale cached row can never be served.
+- **Nothing** is written to or read from the cache DB, and a pre-existing cache file is left in place untouched, so re-enabling restores the previous behaviour.
+- Tab completion degrades gracefully to a live/empty lookup rather than serving stale names.
+- `auto-inspect` refuses to start (it exists only to keep the cache warm, which does nothing when caching is off).
+- Bench labels still work, because they are also stored in each bench's marker file.
+- Safety-critical commands (`rm`/`rm-site`'s backup step, `apps checkout`'s wrong-copy detection) get correct live data.
+
+Because every read resolves live, commands are slower than with the cache warm - this is a correctness/isolation mode, not the everyday default.
+
 ##### `config auto-inspect` - Automatic Project Inspection
 
 Manages automatic background inspection of running Frappe projects to keep cached data fresh (tab completion, project status queries, and other commands that rely on cached data).

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "caffeinated-whale-cli"
-version = "3.2.0"
+version = "3.3.0"
 authors = [
   { name = "Christopher McKay", email = "mckay.christopher73@outlook.com" },
 ]

caffeinated_whale_cli-3.3.0/src/caffeinated_whale_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.3.0"

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/commands/config.py

@@ -101,6 +101,17 @@ def show(
     console.print("[bold]Locations[/bold]")
     console.print(f"  Config file: [green]{report.config_file}[/green]")
     console.print(f"  Cache DB:    [green]{report.cache_db}[/green]")
+
+    console.print("\n[bold]Cache[/bold]")
+    if report.cache_enabled:
+        console.print("  Enabled: [green]Yes[/green]")
+    else:
+        source = "CWCLI_NO_CACHE" if report.cache_env_override else "config"
+        console.print(f"  Enabled: [red]No[/red] [dim](disabled via {source})[/dim]")
+        console.print("  [dim]Reads resolve live; nothing is written to the cache DB.[/dim]")
+    if report.cache_env_override:
+        console.print("  [dim]CWCLI_NO_CACHE is set and overrides the config key.[/dim]")
+
     console.print("\n[bold]Search paths[/bold]")
     if report.search_paths:
         for path in report.search_paths:
@@ -351,6 +362,44 @@ def clear_cache(
         )
 
 
+@cache_app.command("enable")
+def cache_enable():
+    """
+    Turn the on-disk cache back on (the default).
+    """
+    _apply_cache_setting(True)
+
+
+@cache_app.command("disable")
+def cache_disable():
+    """
+    Turn the on-disk cache off entirely.
+
+    Every read command then resolves live (as if a fresh inspect ran) and nothing
+    is written to or read from the cache DB. The existing cache file is left in
+    place, so re-enabling restores it. Set CWCLI_NO_CACHE=1 for the same effect
+    per shell / in CI.
+    """
+    _apply_cache_setting(False)
+
+
+def _apply_cache_setting(enabled: bool):
+    state = core_config.set_cache(enabled).data
+    assert state is not None
+    if enabled:
+        console.print("[green]Caching enabled.[/green] Reads use the on-disk cache.")
+    else:
+        console.print(
+            "[yellow]Caching disabled.[/yellow] Reads resolve live; nothing is written "
+            "to the cache DB (the existing cache is left in place)."
+        )
+    if state.env_override and state.enabled != enabled:
+        console.print(
+            "[yellow]Note:[/yellow] CWCLI_NO_CACHE is set and overrides this setting; "
+            f"caching is currently {'enabled' if state.enabled else 'disabled'} for this shell."
+        )
+
+
 @cache_app.command("path")
 def cache_path():
     """

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/core/auto_inspect.py

@@ -160,6 +160,14 @@ def enable(interval: int | None = None, at_boot: bool | None = None) -> Result[A
     it when a changed interval must take effect), then syncs the boot hook when
     ``at_boot`` was requested (``None`` leaves the hook untouched).
     """
+    if config_utils.cache_disabled():
+        raise CwcliError(
+            ErrorKind.USAGE,
+            "auto_inspect.cache_disabled",
+            "Caching is disabled, so auto-inspect has nothing to keep warm.",
+            hint="Re-enable caching first: `cwcli config cache enable` (or unset CWCLI_NO_CACHE).",
+        )
+
     if interval is not None and interval < MIN_INTERVAL:
         raise CwcliError(
             ErrorKind.USAGE,

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/core/config.py

@@ -18,6 +18,7 @@ cannot be checked, nothing is pruned.
 
 from __future__ import annotations
 
+import os
 import posixpath
 from dataclasses import dataclass, field
 
@@ -38,12 +39,22 @@ class ConfigReport:
 
     config_file: str
     cache_db: str
+    cache_enabled: bool
+    cache_env_override: bool
     search_paths: list[str]
     auto_inspect: AutoInspectState
     cred_bridge: CredBridgeState
     show_tips: bool
 
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CacheState:
+    """Whether the on-disk cache is on, and whether an env var is forcing it."""
+
+    enabled: bool
+    env_override: bool  # True when CWCLI_NO_CACHE is set (config key is inert)
+
+
 @dataclass(frozen=True, slots=True, kw_only=True)
 class SearchPathChange:
     """A search-path add/remove: the normalized path and whether anything changed."""
@@ -79,6 +90,12 @@ def _normalize(path: str) -> str:
     return posixpath.normpath(posixpath.expanduser(path))
 
 
+def _cache_env_override() -> bool:
+    """True when CWCLI_NO_CACHE is set to a non-empty value (it wins over config)."""
+    env = os.environ.get("CWCLI_NO_CACHE")
+    return env is not None and env.strip() != ""
+
+
 def show_config() -> Result[ConfigReport]:
     """The effective config as one report: paths, auto-inspect, tips, locations."""
     state = core_auto_inspect.status().data
@@ -91,6 +108,8 @@ def show_config() -> Result[ConfigReport]:
         data=ConfigReport(
             config_file=str(config_utils.CONFIG_FILE),
             cache_db=str(db_utils.DB_PATH),
+            cache_enabled=not config_utils.cache_disabled(),
+            cache_env_override=_cache_env_override(),
             search_paths=list(config["search_paths"]["custom_bench_paths"]),
             auto_inspect=state,
             cred_bridge=bridge_state,
@@ -99,6 +118,22 @@ def show_config() -> Result[ConfigReport]:
     )
 
 
+def set_cache(enabled: bool) -> Result[CacheState]:
+    """Turn the on-disk cache on or off via the ``[cache] enabled`` config key.
+
+    The cache DB is never deleted or altered here - it is left in place so
+    re-enabling restores the previous behaviour. When ``CWCLI_NO_CACHE`` is set it
+    overrides this key, so the returned :class:`CacheState` reports that override.
+    """
+    config_utils.set_cache_enabled(enabled)
+    return Result(
+        status=Status.OK,
+        data=CacheState(
+            enabled=not config_utils.cache_disabled(), env_override=_cache_env_override()
+        ),
+    )
+
+
 def add_search_path(path: str) -> Result[SearchPathChange]:
     """Add a bench search path: refuse non-absolute, normalize before dedup.
 

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/core/inspect.py

@@ -581,6 +581,14 @@ def inspect_raw(
             f"Unknown refresh mode '{refresh}'. Use one of: {', '.join(_REFRESH_MODES)}.",
         )
 
+    # Caching off: always resolve live. Force the full tier so no cached row (T1)
+    # or partial refresh (T2) can be served, and the write below lands in the
+    # ephemeral in-memory store db_utils redirects to (the on-disk cache is never
+    # touched). This is also the recursion base for db_utils._live_populate: a
+    # forced-full run with no selector never reads the cache back.
+    if config_utils.cache_disabled():
+        refresh = "full"
+
     emit = on_event or _noop
     warnings: list[Message] = []
 
@@ -592,7 +600,10 @@ def inspect_raw(
     served_from = "cache"
 
     cached_data = None
-    if refresh != "full" or bench is not None:
+    # With caching disabled there is nothing to read and the read would only
+    # trigger a redundant nested live populate; the forced-full path below does a
+    # fresh discovery and narrows the selector from that.
+    if (refresh != "full" or bench is not None) and not config_utils.cache_disabled():
         cached_data = db_utils.get_cached_project_data(project_name)
 
     if refresh != "full":

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/core/supervision.py

@@ -51,6 +51,7 @@ never returned across a boundary; every return is plain serializable data.
 from __future__ import annotations
 
 import json
+import re
 import shlex
 import time
 from collections.abc import Callable
@@ -1230,6 +1231,89 @@ def _resync_failed(text: str, restarted: list[str]) -> ResyncOutcome:
     return ResyncOutcome(attempted=True, restarted=list(restarted), unserved_sites=[], error=text)
 
 
+# A bench's ``common_site_config.json`` MAY legitimately omit ``webserver_port`` -
+# a DNS-multitenant bench (many domain-named sites) removes it deliberately so
+# Frappe routes purely by Host header, not by a port cwcli would otherwise read as
+# a fixed default. `resolve_assigned_ports(fill_defaults=False)` reports that the
+# same way it reports a genuinely unreadable config: absent. Below, "the config has
+# no port" is answered with EVIDENCE instead - the live web process's own bound
+# port, from its argv - never a bare guess.
+_PORT_FLAG_RE = re.compile(r"--port[=\s]+(\d+)")
+_BIND_FLAG_RE = re.compile(r"(?:--bind|-b)[=\s]+\S*:(\d+)")
+_LISTENER_OWNERSHIP_SCRIPT = r"""
+import os
+import sys
+
+pid = int(sys.argv[1])
+port = int(sys.argv[2])
+bench = os.path.realpath(sys.argv[3])
+try:
+    cwd = os.path.realpath(f"/proc/{pid}/cwd")
+    if os.path.commonpath((cwd, bench)) != bench:
+        raise OSError
+    inodes = set()
+    for fd in os.listdir(f"/proc/{pid}/fd"):
+        try:
+            target = os.readlink(f"/proc/{pid}/fd/{fd}")
+        except OSError:
+            continue
+        if target.startswith("socket:[") and target.endswith("]"):
+            inodes.add(target[8:-1])
+    for table in ("/proc/net/tcp", "/proc/net/tcp6"):
+        with open(table, encoding="ascii") as rows:
+            next(rows)
+            for row in rows:
+                fields = row.split()
+                local_port = int(fields[1].rsplit(":", 1)[1], 16)
+                if fields[3] == "0A" and local_port == port and fields[9] in inodes:
+                    raise SystemExit(0)
+except (OSError, ValueError):
+    raise SystemExit(2)
+raise SystemExit(1)
+""".strip()
+
+
+def _port_from_process(container, pid: int) -> int | None:
+    """The bound port of ``pid``, read from its own argv - evidence, not a guess.
+
+    bench bakes the bench's real assigned port into the Procfile's ``web:`` line at
+    init (``bench serve --port <N>``), so once that line is running its cmdline IS
+    the truth; a gunicorn-fronted web instead carries ``--bind``/``-b <host>:<N>``.
+    Returns None when the process is gone or its argv names no port at all (a bare
+    ``bench serve`` with no ``--port``, which defers to Frappe's own default).
+    """
+    for row in _ps_rows(container):
+        if row.pid != pid:
+            continue
+        match = _PORT_FLAG_RE.search(row.args) or _BIND_FLAG_RE.search(row.args)
+        return int(match.group(1)) if match else None
+    return None
+
+
+def _process_owns_listener(container, pid: int, port: int, bench_path: str) -> bool:
+    """Return whether this bench's process owns the listener on ``port``."""
+    exit_code, _output = container.exec_run(
+        ["python3", "-c", _LISTENER_OWNERSHIP_SCRIPT, str(pid), str(port), bench_path]
+    )
+    return bool(exit_code == 0)
+
+
+def _resync_web_port(container, bench_path: str, web_pid: int | None) -> int | None:
+    ports = resolvers.resolve_assigned_ports(container, [bench_path], fill_defaults=False).get(
+        bench_path
+    )
+    if ports is not None:
+        return ports[0]
+    process_port = _port_from_process(container, web_pid) if web_pid is not None else None
+    if process_port is not None:
+        return process_port
+    if web_pid is not None and _process_owns_listener(
+        container, web_pid, resolvers.WEB_CONTAINER_BASE, bench_path
+    ):
+        return resolvers.WEB_CONTAINER_BASE
+    return None
+
+
 def resync_after_code_change(
     container,
     bench_path: str,
@@ -1280,6 +1364,18 @@ def resync_after_code_change(
       bound-port-shaped claim, and serving stale code is exactly the class of defect a
       claim like that misses. Every site the caller names must answer a real
       site-routed request before the outcome is ``ok``.
+    - **An absent ``webserver_port`` is not a read failure.** A DNS-multitenant
+      bench (many domain-named sites) deliberately removes it from
+      ``common_site_config.json`` so Frappe routes purely by Host header; a bench
+      like that used to fail here with "the bench's assigned port could not be
+      read", even though the update itself had already succeeded. The probe port
+      now falls back to EVIDENCE - the live web process's own bound port (its argv
+      carries bench's real assignment, baked into the Procfile's ``web:`` line at
+      init), then Frappe's own unconfigured default only when that listener is
+      proven to belong to this bench's web process - before the sites are probed
+      for real. Missing evidence fails honestly without probing a sibling bench or
+      blaming a config key that was never supposed to exist.
+      See :func:`_port_from_process`.
     """
     announce = on_restart or (lambda _program: None)
     unique_sites = list(dict.fromkeys(sites))
@@ -1290,6 +1386,7 @@ def resync_after_code_change(
 
     restarted: list[str] = []
     supervised = False
+    web_port: int | None
     try:
         supervised = discover_stack(container, bench_path, required=True).supervisor_up
         if supervised:
@@ -1304,6 +1401,7 @@ def resync_after_code_change(
             # is no site to verify against, and starting one is not this verb's job.
             if states[web][0] not in _LIVE_STATES:
                 return quiet
+            web_port = _resync_web_port(container, bench_path, states[web][1])
 
             for program in code_bearing_programs(list(states)):
                 if states[program][0] not in _LIVE_STATES:
@@ -1320,21 +1418,24 @@ def resync_after_code_change(
                         restarted,
                     )
                 restarted.append(program)
-        elif not discover_unsupervised_stack(container, bench_path, required=True).manager_up:
-            return quiet
+        else:
+            unsupervised = discover_unsupervised_stack(container, bench_path, required=True)
+            if not unsupervised.manager_up:
+                return quiet
+            web_process = next((p for p in unsupervised.processes if p.label == "web"), None)
+            web_port = _resync_web_port(
+                container, bench_path, web_process.pid if web_process is not None else None
+            )
 
-        ports = resolvers.resolve_assigned_ports(container, [bench_path], fill_defaults=False).get(
-            bench_path
-        )
-        if ports is None:
+        if web_port is None:
             return _resync_failed(
-                "the bench's assigned port could not be read, so cwcli could not confirm "
-                "the affected sites serve",
+                "the bench's serving port could not be determined safely, so cwcli could not "
+                "confirm the affected sites serve",
                 restarted,
             )
 
         pending, codes = _wait_for_serving_sites(
-            container, port=ports[0], sites=unique_sites, timeout=timeout
+            container, port=web_port, sites=unique_sites, timeout=timeout
         )
         if pending:
             observed = ", ".join(f"{site}={codes[site] or 'unreachable'}" for site in pending)

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/core/where.py

@@ -31,7 +31,7 @@ from dataclasses import dataclass, field, replace
 
 import peewee
 
-from ..utils import db_utils
+from ..utils import config_utils, db_utils
 from .envelope import Message, Result, Status
 from .errors import CwcliError, ErrorKind
 from .list import list_instances
@@ -177,6 +177,21 @@ def _live_project_names() -> set[str] | None:
     return {instance.project_name for instance in (result.data or [])}
 
 
+def _populate_live_if_disabled() -> None:
+    """With caching off, ``where`` has no cache to search, so inspect every live
+    instance into the ephemeral in-memory store first, then search that.
+
+    Reuses the same live-populate ``db_utils`` runs for a single project (one full
+    inspect per running instance); the on-disk cache is never touched. A daemon we
+    cannot reach leaves the store empty, which ``where`` reports as no matches.
+    """
+    if not config_utils.cache_disabled():
+        return
+    live = _live_project_names()
+    for project_name in live or set():
+        db_utils.get_cached_project_data(project_name)
+
+
 def where(
     search: str,
     *,
@@ -193,6 +208,8 @@ def where(
             "Cannot use --apps and --sites together.",
         )
 
+    _populate_live_if_disabled()
+
     matches: list[WhereMatch] = []
 
     # A corrupt/locked cache or a schema mismatch surfaces here as a raw peewee

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/utils/cache.py

@@ -5,7 +5,7 @@ This module provides utilities for managing the project inspection cache,
 including re-caching operations built on the core inspect slice.
 """
 
-from . import db_utils
+from . import config_utils, db_utils
 
 
 def recache_project(project_name: str, verbose: bool = False) -> bool:
@@ -31,6 +31,11 @@ def recache_project(project_name: str, verbose: bool = False) -> bool:
         True if recache succeeded, False otherwise (including when the project's
         containers are not running, since a stopped bench cannot be inspected).
     """
+    # Caching off: there is no on-disk cache to refresh, so a post-mutation
+    # recache would only run a full inspect into a store that is discarded.
+    if config_utils.cache_disabled():
+        return True
+
     try:
         # Clear the cache for this project
         db_utils.clear_cache_for_project(project_name)

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/utils/completion_utils.py

@@ -11,7 +11,7 @@ import time
 import docker
 import typer
 
-from . import db_utils
+from . import config_utils, db_utils
 
 # Cache configuration
 _CACHE_TTL = 2.0  # Cache results for 2 seconds (enough for tab completion session)
@@ -138,6 +138,12 @@ def complete_app_names(
     if not project_name:
         return []
 
+    # Caching off: degrade to an empty completion rather than blocking the shell
+    # on a live inspect. Empty beats stale, and completion must never do container
+    # I/O.
+    if config_utils.cache_disabled():
+        return []
+
     # Check cache first
     cache_key = f"apps:{project_name}"
     cached = _get_cached(cache_key)
@@ -186,6 +192,12 @@ def complete_site_names(
     if not project_name:
         return []
 
+    # Caching off: degrade to an empty completion rather than blocking the shell
+    # on a live inspect. Empty beats stale, and completion must never do container
+    # I/O.
+    if config_utils.cache_disabled():
+        return []
+
     # Check cache first
     cache_key = f"sites:{project_name}"
     cached = _get_cached(cache_key)

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/utils/config_utils.py

@@ -99,6 +99,18 @@ startup_enabled = false
 # Applies immediately (no daemon restart needed); cwcli's own per-operation
 # bridge (apps install/update, init) is not restricted by this list.
 allowed_hosts = ["github.com", "gitlab.com"]
+
+[cache]
+# The on-disk SQLite cache under <cwcli home>/cache speeds up read commands
+# (inspect, status, where, tab completion, ...) by remembering each project's
+# benches, sites, and apps.
+#
+# Set enabled = false to turn caching off entirely: every read resolves live
+# (as if a fresh inspect ran), nothing is written to or read from the cache DB,
+# and a pre-existing cache is left in place untouched so turning caching back on
+# restores it. The CWCLI_NO_CACHE environment variable overrides this key per
+# shell / in CI (CWCLI_NO_CACHE=1 disables, CWCLI_NO_CACHE=0 re-enables).
+enabled = true
 """
 
 DEFAULT_ALLOWED_HOSTS = ("github.com", "gitlab.com")
@@ -150,6 +162,10 @@ def load_config() -> dict:
             else:
                 for key, value in _cred_bridge_defaults().items():
                     config_data["cred_bridge"].setdefault(key, value)
+            if "cache" not in config_data:
+                config_data["cache"] = {"enabled": True}
+            elif "enabled" not in config_data["cache"]:
+                config_data["cache"]["enabled"] = True
             return config_data
         except toml.TomlDecodeError:
             return {
@@ -157,6 +173,7 @@ def load_config() -> dict:
                 "auto_inspect": {"enabled": False, "interval": 3600, "startup_enabled": False},
                 "ui": {"show_tips": True},
                 "cred_bridge": _cred_bridge_defaults(),
+                "cache": {"enabled": True},
             }
 
 
@@ -286,6 +303,49 @@ def set_cred_bridge_startup(enabled: bool):
     save_config(config)
 
 
+def read_cache_config() -> dict:
+    """Read the [cache] config WITHOUT creating config state.
+
+    Used by :func:`cache_disabled`, which runs on the hot path of every cache
+    read; it must never write a default config file into the user's home as a
+    side effect (mirrors :func:`read_cred_bridge_config`).
+    """
+    default = {"enabled": True}
+    if not CONFIG_FILE.is_file():
+        return default
+    try:
+        with open(CONFIG_FILE) as f:
+            config = toml.load(f)
+    except (OSError, toml.TomlDecodeError):
+        return default
+    cache = config.get("cache", default)
+    return cache if isinstance(cache, dict) else default
+
+
+def cache_disabled() -> bool:
+    """Whether cwcli's on-disk SQLite cache is turned off.
+
+    The ``CWCLI_NO_CACHE`` environment variable overrides the ``[cache] enabled``
+    config key, so caching can be toggled per shell / in CI - and can even be
+    re-enabled (``CWCLI_NO_CACHE=0``) when the config file disables it. An unset
+    or empty env var falls through to the config key (default: enabled).
+    """
+    env = os.environ.get("CWCLI_NO_CACHE")
+    if env is not None and env.strip() != "":
+        return env.strip().lower() in ("1", "true", "yes", "on")
+    return not bool(read_cache_config().get("enabled", True))
+
+
+def set_cache_enabled(enabled: bool):
+    """Enable or disable the on-disk cache via the ``[cache] enabled`` config key."""
+    config = load_config()
+    if "cache" not in config:
+        config["cache"] = {"enabled": enabled}
+    else:
+        config["cache"]["enabled"] = enabled
+    save_config(config)
+
+
 def get_show_tips() -> bool:
     """
     Get whether tips should be shown during long-running operations.

{caffeinated_whale_cli-3.2.0 → caffeinated_whale_cli-3.3.0}/src/caffeinated_whale_cli/utils/db_utils.py

@@ -12,7 +12,7 @@ from peewee import (
     TextField,
 )
 
-from . import shared_home
+from . import config_utils, shared_home
 from .config_utils import cwcli_home
 
 # Resolve the cache location through the shared cwcli_home() helper so the
@@ -21,6 +21,12 @@ from .config_utils import cwcli_home
 CACHE_DIR = cwcli_home() / "cache"
 DB_PATH = CACHE_DIR / "cwc-cache.db"
 
+# The sentinel path an ephemeral in-memory SQLite database uses. When caching is
+# disabled (config_utils.cache_disabled()) the whole cache is redirected here, so
+# the on-disk DB is never opened, read, or written and a stale row can never leak
+# through - see initialize_database() and _live_populate().
+_MEMORY_DB = ":memory:"
+
 # SECURITY: config_json rows are whitelist-filtered by _redact_config_for_cache
 # before write, so the cache never stores DB credentials, encryption keys, or
 # redis URLs. Restrictive filesystem permissions (0700 dir / 0600 file) remain
@@ -30,20 +36,23 @@ DB_PATH = CACHE_DIR / "cwc-cache.db"
 # shared_home).
 
 # Create cache directory with restricted permissions (0700 = owner-only access)
-# This prevents other users on the system from reading cached credentials
-CACHE_DIR.mkdir(parents=True, mode=shared_home.dir_mode(0o700), exist_ok=True)
-
-# Ensure existing directory has correct permissions
-if CACHE_DIR.exists():
-    try:
-        CACHE_DIR.chmod(shared_home.dir_mode(0o700))
-        shared_home.apply_group(CACHE_DIR)
-    except (OSError, PermissionError):
-        # On Windows or restricted filesystems, chmod may fail
-        # Still proceed but permissions may not be as strict
-        pass
+# This prevents other users on the system from reading cached credentials. Skip
+# it entirely when caching is disabled, so a disabled install leaves no on-disk
+# footprint at all.
+if not config_utils.cache_disabled():
+    CACHE_DIR.mkdir(parents=True, mode=shared_home.dir_mode(0o700), exist_ok=True)
+
+    # Ensure existing directory has correct permissions
+    if CACHE_DIR.exists():
+        try:
+            CACHE_DIR.chmod(shared_home.dir_mode(0o700))
+            shared_home.apply_group(CACHE_DIR)
+        except (OSError, PermissionError):
+            # On Windows or restricted filesystems, chmod may fail
+            # Still proceed but permissions may not be as strict
+            pass
 
-db = SqliteDatabase(DB_PATH)
+db = SqliteDatabase(_MEMORY_DB if config_utils.cache_disabled() else DB_PATH)
 
 
 class BaseModel(Model):
@@ -371,7 +380,54 @@ def _scrub_cached_config_secrets():
         print(f"Warning: could not scrub cached config secrets: {e}", file=sys.stderr)
 
 
+# Projects live-populated into the ephemeral in-memory cache this process (see
+# _live_populate). A reentrancy flag stops the populating inspect - which writes
+# the same in-memory DB - from recursing back through a cache read.
+_live_populated: set[str] = set()
+_populating = False
+
+
+def _db_target() -> str:
+    """Where the cache DB should point right now: in-memory when disabled."""
+    return _MEMORY_DB if config_utils.cache_disabled() else str(DB_PATH)
+
+
+def _live_populate(project_name: str) -> None:
+    """In cache-disabled mode, populate the ephemeral in-memory DB with one live
+    inspect so downstream cache reads resolve fresh data instead of nothing.
+
+    The on-disk cache is never touched: the disabled DB points at ``:memory:``,
+    so the inspect's write lands in the ephemeral store this process discards on
+    exit. Memoized and reentrancy-guarded (the inspect writes the same DB), and
+    best-effort: a stopped/absent project simply yields no in-memory rows, which
+    every caller already handles as a cache miss.
+    """
+    global _populating
+    if not config_utils.cache_disabled() or _populating or project_name in _live_populated:
+        return
+    _populating = True
+    try:
+        from ..core import inspect as core_inspect
+
+        core_inspect.inspect(project_name, refresh="full", offer_choice=False)
+    except Exception:  # noqa: BLE001 - a failed live read just leaves the store empty
+        pass
+    finally:
+        _live_populated.add(project_name)  # never retry within one process
+        _populating = False
+
+
 def initialize_database():
+    target = _db_target()
+    if str(db.database) != target:
+        # The disabled state flipped (e.g. a test toggled CWCLI_NO_CACHE, or the
+        # first read after enable/disable). Re-point the shared database so every
+        # model follows it. Switching TO :memory: gives a fresh empty store;
+        # switching back opens the untouched on-disk cache.
+        if not db.is_closed():
+            db.close()
+        db.init(target)
+        _live_populated.clear()
     if db.is_closed():
         db.connect()
     # Create tables if missing
@@ -528,6 +584,7 @@ def _cache_project_data(project_name: str, bench_instances_data: list[dict]) ->
 
 def get_cached_project_data(project_name):
     initialize_database()
+    _live_populate(project_name)
     try:
         project = Project.get(Project.name == project_name)
 
@@ -643,6 +700,7 @@ def get_common_site_config(project_name: str, bench_path: str | None = None) ->
         Dictionary with common site config or None if not found
     """
     initialize_database()
+    _live_populate(project_name)
     try:
         project = Project.get(Project.name == project_name)
 
@@ -685,6 +743,7 @@ def get_site_config(
         Dictionary with site config or None if not found
     """
     initialize_database()
+    _live_populate(project_name)
     try:
         project = Project.get(Project.name == project_name)
 
@@ -729,6 +788,7 @@ def get_all_site_configs(project_name: str, bench_path: str | None = None) -> di
         Dictionary mapping site names to their configs
     """
     initialize_database()
+    _live_populate(project_name)
     result = {}
 
     try:
@@ -763,6 +823,7 @@ def get_current_site(project_name: str, bench_path: str | None = None) -> str |
     non-empty ``current_site`` found (scoped to ``bench_path`` when given).
     """
     initialize_database()
+    _live_populate(project_name)
     try:
         project = Project.get(Project.name == project_name)
 

caffeinated_whale_cli-3.2.0/src/caffeinated_whale_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "3.2.0"