caffeinated-whale-cli 3.2.1__tar.gz → 3.4.0__tar.gz

{caffeinated_whale_cli-3.2.1 → caffeinated_whale_cli-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 3.2.1
+Version: 3.4.0
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -626,6 +626,11 @@ supervisor rather than stopping any container. Sibling benches keep serving, the
 containers stay up, and `cwcli start --bench` brings it back. Stopping a bench
 that is already stopped is a success, not an error.
 
+A whole-instance stop takes the database down last and gives it up to 60 seconds
+to finish its shutdown. If the database exits non-zero (137 means it was killed
+before it finished shutting down), `stop` says so and exits non-zero instead of
+reporting a clean stop.
+
 **Example:**
 
 ```bash
@@ -2027,7 +2032,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 +2100,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).
@@ -2554,8 +2584,12 @@ It exits non-zero if a restart fails or the named site does not answer Frappe's
 
 These are agent-only for now: there is no human `cwcli migrate`, `cwcli run-tests`, or `cwcli build` yet. Use `cwcli run <project> --site <site> migrate` for the human equivalent.
 
+`cwcli axi setup-wizard <project> <site> [--country <country>] [--currency <currency>] [--timezone <timezone>]` headlessly completes a site's Frappe setup wizard. A fresh site - whether created by `cwcli init`/`cwcli axi init` without `--complete-setup`, or by a bare `bench new-site` outside cwcli entirely - is left in the setup-wizard state: `frappe.is_setup_complete()` is `false` and the `desktop:home_page` default stays `setup-wizard`, so a non-System-Manager desk renders with no navbar. This runs the same whitelisted RPC a person finishing the wizard in a browser triggers - `frappe.desk.page.setup_wizard.setup_wizard.setup_complete`, called via `bench execute ... --kwargs` with the args dict the wizard UI would have submitted (System Settings' country/currency/timezone/language; omitted flags fall back to `United States`/`USD`/`UTC`/`English`). It is **idempotent by Frappe's own design**: `setup_complete` checks `frappe.is_setup_complete()` first and no-ops under an advisory lock when the site is already set up, so re-running it is always safe - the report's `already_complete` field says whether it found the site already done. No user is created: `email`/`full_name`/`password` are deliberately left out of the args dict, so the `Administrator` account `cwcli init`'s `--admin-password` already provisioned is left untouched. Like the other bench-scoped verbs it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start`.
+
 `cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. Running several `axi init` calls in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default `123`). The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1); an invalid `--uid` (0, negative, or non-numeric) is rejected before any container work. `--uid` behaves as it does on `cwcli init` (including the root-host fallback, whose one-time warning is folded into the report's `warnings`). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
 
+`--complete-setup` runs the new site's Frappe setup wizard headlessly right after creation - the same operation `cwcli axi setup-wizard` performs standalone, sharing its exact implementation - so a fresh site does not land in the unfinished setup-wizard state a non-System-Manager desk renders with no navbar in. `--country`/`--currency`/`--timezone` tune it (require `--complete-setup`; each has a sensible default when omitted) and are usage errors on their own. Its outcome rides as a `setup_wizard` block inside the SAME `InitReport` document, not a second one; a failure there is never exit `0` even though the bench and site above it were already created successfully - the `setup_wizard` block still carries what happened.
+
 `cwcli axi rm <project> --yes` permanently removes an instance: its containers, named volumes (databases, sites, and files), own Docker Compose network, and local project directory.
 It is the agent form of `cwcli rm`, and it runs the same code.
 The verified per-bench backup is taken and checked before anything is destroyed, and a backup that cannot be created and verified **aborts the removal with everything still intact**, so data is never destroyed without a confirmed copy on the host.

{caffeinated_whale_cli-3.2.1 → caffeinated_whale_cli-3.4.0}/README.md

@@ -586,6 +586,11 @@ supervisor rather than stopping any container. Sibling benches keep serving, the
 containers stay up, and `cwcli start --bench` brings it back. Stopping a bench
 that is already stopped is a success, not an error.
 
+A whole-instance stop takes the database down last and gives it up to 60 seconds
+to finish its shutdown. If the database exits non-zero (137 means it was killed
+before it finished shutting down), `stop` says so and exits non-zero instead of
+reporting a clean stop.
+
 **Example:**
 
 ```bash
@@ -1987,7 +1992,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 +2060,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).
@@ -2514,8 +2544,12 @@ It exits non-zero if a restart fails or the named site does not answer Frappe's
 
 These are agent-only for now: there is no human `cwcli migrate`, `cwcli run-tests`, or `cwcli build` yet. Use `cwcli run <project> --site <site> migrate` for the human equivalent.
 
+`cwcli axi setup-wizard <project> <site> [--country <country>] [--currency <currency>] [--timezone <timezone>]` headlessly completes a site's Frappe setup wizard. A fresh site - whether created by `cwcli init`/`cwcli axi init` without `--complete-setup`, or by a bare `bench new-site` outside cwcli entirely - is left in the setup-wizard state: `frappe.is_setup_complete()` is `false` and the `desktop:home_page` default stays `setup-wizard`, so a non-System-Manager desk renders with no navbar. This runs the same whitelisted RPC a person finishing the wizard in a browser triggers - `frappe.desk.page.setup_wizard.setup_wizard.setup_complete`, called via `bench execute ... --kwargs` with the args dict the wizard UI would have submitted (System Settings' country/currency/timezone/language; omitted flags fall back to `United States`/`USD`/`UTC`/`English`). It is **idempotent by Frappe's own design**: `setup_complete` checks `frappe.is_setup_complete()` first and no-ops under an advisory lock when the site is already set up, so re-running it is always safe - the report's `already_complete` field says whether it found the site already done. No user is created: `email`/`full_name`/`password` are deliberately left out of the args dict, so the `Administrator` account `cwcli init`'s `--admin-password` already provisioned is left untouched. Like the other bench-scoped verbs it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start`.
+
 `cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. Running several `axi init` calls in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default `123`). The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1); an invalid `--uid` (0, negative, or non-numeric) is rejected before any container work. `--uid` behaves as it does on `cwcli init` (including the root-host fallback, whose one-time warning is folded into the report's `warnings`). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
 
+`--complete-setup` runs the new site's Frappe setup wizard headlessly right after creation - the same operation `cwcli axi setup-wizard` performs standalone, sharing its exact implementation - so a fresh site does not land in the unfinished setup-wizard state a non-System-Manager desk renders with no navbar in. `--country`/`--currency`/`--timezone` tune it (require `--complete-setup`; each has a sensible default when omitted) and are usage errors on their own. Its outcome rides as a `setup_wizard` block inside the SAME `InitReport` document, not a second one; a failure there is never exit `0` even though the bench and site above it were already created successfully - the `setup_wizard` block still carries what happened.
+
 `cwcli axi rm <project> --yes` permanently removes an instance: its containers, named volumes (databases, sites, and files), own Docker Compose network, and local project directory.
 It is the agent form of `cwcli rm`, and it runs the same code.
 The verified per-bench backup is taken and checked before anything is destroyed, and a backup that cannot be created and verified **aborts the removal with everything still intact**, so data is never destroyed without a confirmed copy on the host.

{caffeinated_whale_cli-3.2.1 → caffeinated_whale_cli-3.4.0}/pyproject.toml

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

caffeinated_whale_cli-3.4.0/src/caffeinated_whale_cli/__init__.py

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

{caffeinated_whale_cli-3.2.1 → caffeinated_whale_cli-3.4.0}/src/caffeinated_whale_cli/commands/apps.py

@@ -135,18 +135,23 @@ def _make_renderer(*, json_output, verbose):
     return on_event
 
 
-def _refresh_cache(project_name, verbose):
+def _refresh_cache(project_name, verbose, bench_path):
     """Refresh the cache through the existing writer so where/open/inspect stop lying.
 
-    Uses ``cache.recache_project`` (a full inspect that persists via
+    Uses ``cache.recache_project`` scoped to the mutated bench (it persists via
     ``cache_project_data`` -> ``_redact_config_for_cache``), never a direct write.
     Degrades to a warning; the mutation itself already succeeded.
     """
-    if not cache.recache_project(project_name, verbose=verbose):
+    warnings: list = []
+    if not cache.recache_project(
+        project_name, verbose=verbose, bench_path=bench_path, warnings=warnings
+    ):
         stderr_console.print(
             "[yellow]Warning:[/yellow] app mutation succeeded but refreshing the cache failed; "
             "run 'cwcli inspect --update' to refresh."
         )
+    for warning in warnings:
+        stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
 
 
 def _report_and_exit(report, json_output, *, success_msg):
@@ -416,7 +421,7 @@ def install_apps(
     # Refresh the cache if any step succeeded: a fetch changes available apps, an
     # install changes a site's installed apps - both make the cache stale.
     if any(r.ok for r in report.results):
-        _refresh_cache(project_name, verbose)
+        _refresh_cache(project_name, verbose, report.bench_path)
 
     # The banner must match what actually happened: only claim "installed" when an
     # install-app step ran (not for --fetch-only, a bench with no sites, or an
@@ -516,7 +521,7 @@ def uninstall_apps(
     report = result.data
     assert report is not None  # OK/WARNING always carries a report
     if any(r.ok for r in report.results):
-        _refresh_cache(project_name, verbose)
+        _refresh_cache(project_name, verbose, report.bench_path)
 
     _report_and_exit(report, json_output, success_msg="App(s) uninstalled.")
 
@@ -585,7 +590,7 @@ def checkout_app(
     # A checkout changes the app's git state (and possibly its reported version), so
     # refresh the cache whenever any git step ran, matching install/update.
     if any(r.ok for r in report.results):
-        _refresh_cache(project_name, verbose)
+        _refresh_cache(project_name, verbose, report.bench_path)
 
     _report_and_exit(report, json_output, success_msg=f"Checked out {ref} into {app}.")
 

{caffeinated_whale_cli-3.2.1 → caffeinated_whale_cli-3.4.0}/src/caffeinated_whale_cli/commands/axi.py

@@ -877,7 +877,8 @@ def axi_stop(
 
     assert result.data is not None  # OK always carries a StopOutcome
     emit_result(result.data, warnings=result.warnings)
-    raise typer.Exit(0)
+    # A database killed mid-shutdown is a failed stop, not a successful one.
+    raise typer.Exit(1 if result.data.db_clean_shutdown is False else 0)
 
 
 def _axi_stop_bench(project: str, bench: str) -> None:
@@ -925,7 +926,7 @@ def axi_start(
     auto-resolves conflicting Frappe projects); a multi-bench project with no
     ``--bench`` is a usage error naming ``--bench``.
     """
-    _axi_resolve_port_conflicts(project, yes)
+    stop_warnings = _axi_resolve_port_conflicts(project, yes)
 
     try:
         result = core_start.start(project, bench=bench, autorestart=autorestart)
@@ -939,22 +940,23 @@ def axi_start(
         raise typer.Exit(2)
 
     assert result.data is not None  # OK/WARNING always carries a StartOutcome
-    emit_result(result.data, warnings=result.warnings)
+    emit_result(result.data, warnings=[*stop_warnings, *result.warnings])
     raise typer.Exit(0 if result.status in (CoreStatus.OK, CoreStatus.WARNING) else 1)
 
 
-def _axi_resolve_port_conflicts(project: str, yes: bool) -> None:
+def _axi_resolve_port_conflicts(project: str, yes: bool) -> list[Message]:
     """Never-prompt host-side port pre-step for ``axi start`` (D6).
 
     Only meaningful when the container is not already up (a running instance owns
     its ports). A non-Frappe holder cannot be auto-resolved -> ``CONFLICT``; a
     Frappe holder is a ``CONFLICT`` naming ``--yes`` unless ``--yes`` was passed,
-    in which case the conflicting Frappe projects are stopped (stdout stays TOON).
+    in which case the conflicting Frappe projects are stopped (stdout stays TOON)
+    and their stop warnings are returned for the start document.
     """
     from .start import _frappe_running, detect_port_conflicts
 
     if _frappe_running(project):
-        return
+        return []
     conflicting, non_frappe = detect_port_conflicts(project)
     if non_frappe:
         emit_axi_error(
@@ -985,9 +987,10 @@ def _axi_resolve_port_conflicts(project: str, yes: bool) -> None:
         # contract. A project that vanished or stopped in that window is fine here
         # (its ports are free either way) - the recheck below is what decides.
 
+        stop_warnings: list[Message] = []
         for proj in conflicting:
             try:
-                core_stop.stop(proj)
+                stop_warnings.extend(core_stop.stop(proj).warnings)
             except CwcliError as e:
                 if e.kind is not ErrorKind.NOT_FOUND:
                     raise
@@ -1008,6 +1011,8 @@ def _axi_resolve_port_conflicts(project: str, yes: bool) -> None:
                 )
             )
             raise typer.Exit(exit_for(ErrorKind.CONFLICT))
+        return stop_warnings
+    return []
 
 
 # ---------------------------------------------------------------------------- status
@@ -1700,7 +1705,10 @@ def axi_apps_checkout(
     # epilogue gated on a condition already in the returned report. A failed recache
     # is a stderr warning, NOT a non-zero exit: the checkout itself landed, and
     # failing here would make an agent retry a mutation that already succeeded.
-    if any(r.ok for r in report.results) and not cache.recache_project(project):
+    warnings = list(result.warnings)
+    if any(r.ok for r in report.results) and not cache.recache_project(
+        project, bench_path=report.bench_path, warnings=warnings
+    ):
         print(
             f"Warning: checkout completed, but re-caching '{project}' failed; "
             "run 'cwcli inspect --update' to refresh.",
@@ -1708,7 +1716,7 @@ def axi_apps_checkout(
             flush=True,
         )
 
-    emit_result(report, warnings=result.warnings)
+    emit_result(report, warnings=warnings)
     # The exit code reads report.ok, NOT result.status: a failed step is a
     # WARNING-shaped envelope, and WARNING maps to exit 0 everywhere else, so a
     # status-driven code would report success for a checkout git refused.
@@ -1834,7 +1842,10 @@ def axi_apps_install(
     # the cache whenever any step landed, matching the human verb. A failed recache
     # is a stderr warning, NOT a non-zero exit: the install itself landed, and
     # failing here would make an agent retry a mutation that already succeeded.
-    if any(r.ok for r in report.results) and not cache.recache_project(project):
+    warnings = list(result.warnings)
+    if any(r.ok for r in report.results) and not cache.recache_project(
+        project, bench_path=report.bench_path, warnings=warnings
+    ):
         print(
             f"Warning: install completed, but re-caching '{project}' failed; "
             "run 'cwcli inspect --update' to refresh.",
@@ -1842,7 +1853,7 @@ def axi_apps_install(
             flush=True,
         )
 
-    emit_result(report, warnings=result.warnings)
+    emit_result(report, warnings=warnings)
     # The exit code reads report.ok, NOT result.status: a failed step is a
     # WARNING-shaped envelope, and WARNING maps to exit 0 everywhere else, so a
     # status-driven code would report success for an install that failed.
@@ -2091,6 +2102,68 @@ def axi_build(
     raise typer.Exit(0 if report.ok else 1)
 
 
+@app.command("setup-wizard")
+def axi_setup_wizard(
+    project: str = typer.Argument(..., help="The Docker Compose project name."),
+    site: str = typer.Argument(..., help="The site whose setup wizard to complete."),
+    country: str = typer.Option(
+        None, "--country", help="Setup wizard country (default: United States)."
+    ),
+    currency: str = typer.Option(None, "--currency", help="Setup wizard currency (default: USD)."),
+    timezone: str = typer.Option(None, "--timezone", help="Setup wizard timezone (default: UTC)."),
+    bench: str = typer.Option(None, "--bench", help="Which bench: numeric index or label."),
+) -> None:
+    """Headlessly complete an EXISTING site's Frappe setup wizard; emit the report as TOON.
+
+    The standalone twin of `axi init --complete-setup`, sharing its exact
+    implementation (`core.bench_ops.complete_setup_wizard`) - for a site that was
+    created before this existed, or by anything other than cwcli (a bare `bench
+    new-site`), and is stuck in the setup-wizard state: `desktop:home_page` stays
+    `setup-wizard` and a non-System-Manager desk renders with no navbar.
+
+    Runs the SAME whitelisted Frappe RPC a human finishing the wizard in a
+    browser triggers - `frappe.desk.page.setup_wizard.setup_wizard.setup_complete`
+    - via `bench execute ... --kwargs`, with the args dict the wizard UI would
+    have submitted (System Settings' country/currency/timezone/language).
+
+    IDEMPOTENT: Frappe's own `setup_complete` checks `frappe.is_setup_complete()`
+    first and no-ops (under an advisory lock) when the site is already set up, so
+    re-running this against an already-completed site is always safe. The report's
+    `already_complete` field says whether this call found it already done.
+
+    No user is created: `email`/`full_name`/`password` are deliberately left out
+    of the args dict, so the Administrator account cwcli's own `init` already
+    provisioned is left untouched.
+
+    NO --yes and no auto-start: a stopped project is a usage error naming
+    `cwcli start`.
+    """
+    try:
+        result = core_bench_ops.complete_setup_wizard(
+            project,
+            site=site,
+            bench=bench,
+            country=country,
+            currency=currency,
+            timezone=timezone,
+            auto_start=False,
+            on_event=_bench_op_narrate,
+        )
+    except CwcliError as error:
+        emit_axi_error(error)
+        raise typer.Exit(exit_for(error.kind)) from None
+
+    if result.status is CoreStatus.NEEDS_CHOICE:
+        assert result.choice is not None  # NEEDS_CHOICE always carries a Choice
+        emit_axi_choice_as_usage_error(result.choice)
+        raise typer.Exit(2)
+
+    assert result.data is not None  # OK/WARNING always carries a SetupWizardReport
+    report = result.data
+    emit_result(report, warnings=result.warnings)
+    raise typer.Exit(0 if report.ok else 1)
+
+
 # ---------------------------------------------------------------------------- config
 
 
@@ -2272,6 +2345,25 @@ def axi_init(
         "so that case already falls back to a safe default automatically (reported in `warnings`); "
         "pass --uid to choose a specific uid instead. Must be a positive, non-root integer.",
     ),
+    complete_setup: bool = typer.Option(
+        False,
+        "--complete-setup",
+        help="After the site is created, headlessly complete its Frappe setup wizard (same "
+        "effect as finishing it in a browser) so 'desktop:home_page' leaves 'setup-wizard' and "
+        "a non-System-Manager desk renders with its navbar. Without this flag a fresh site is "
+        "left exactly as before: in the unfinished setup-wizard state.",
+    ),
+    setup_country: str = typer.Option(
+        None,
+        "--country",
+        help="Setup wizard country (default: United States). Requires --complete-setup.",
+    ),
+    setup_currency: str = typer.Option(
+        None, "--currency", help="Setup wizard currency (default: USD). Requires --complete-setup."
+    ),
+    setup_timezone: str = typer.Option(
+        None, "--timezone", help="Setup wizard timezone (default: UTC). Requires --complete-setup."
+    ),
 ) -> None:
     """Provision a new instance, bench, and site; emit the report as TOON (never prompts).
 
@@ -2304,7 +2396,23 @@ def axi_init(
     --port (exit 1); containers that do not come up point at `cwcli status` /
     `cwcli logs` (exit 1). There is no --auto-start (compose `cwcli axi start`
     then re-run) and no --verbose (stdout is always TOON).
+
+    --complete-setup runs the site's Frappe setup wizard headlessly right after
+    creation (--country/--currency/--timezone tune it; omitted ones get sensible
+    defaults), and its outcome rides as a `setup_wizard` block inside this SAME
+    document - see `cwcli axi setup-wizard --help` for the standalone verb that
+    completes an EXISTING site's wizard, which shares this exact implementation.
     """
+    if (setup_country or setup_currency or setup_timezone) and not complete_setup:
+        emit_axi_error(
+            CwcliError(
+                ErrorKind.USAGE,
+                "init.setup_flags_without_complete_setup",
+                "--country/--currency/--timezone require --complete-setup.",
+            )
+        )
+        raise typer.Exit(exit_for(ErrorKind.USAGE))
+
     resolved_admin = admin_password or os.environ.get("CWCLI_ADMIN_PASSWORD")
     if not resolved_admin:
         emit_axi_error(
@@ -2319,11 +2427,17 @@ def axi_init(
         raise typer.Exit(exit_for(ErrorKind.USAGE))
     db_root = db_root_password or os.environ.get("CWCLI_DB_ROOT_PASSWORD") or "123"
 
-    # Fail-fast on a bad site name or --uid BEFORE stage 1 (the human init's
-    # ordering): the core re-validates in init_bench, but that runs only after
-    # compose has brought real containers up, which a usage error must never leave
-    # behind.
+    # Fail-fast on a bad project/site name or --uid BEFORE stage 1 (the human
+    # init's ordering): the core re-validates in init_bench, but that runs only
+    # after compose has brought real containers up, which a usage error must never
+    # leave behind. Normalizing the project name here (Docker Compose lowercases it,
+    # and validate_project_slug does the same) is load-bearing, not cosmetic: the
+    # post-creation steps below (dev-services start, recache, setup wizard) look the
+    # container up by this name, so a mixed-case argument would resolve nothing and
+    # they would fail "project not found" - exactly what the human init avoids by
+    # threading the normalized name everywhere.
     try:
+        project = core_init.validate_project_slug(project)
         site = core_init.validate_new_site_name(site)
         core_init.check_uid_override(uid)
     except CwcliError as error:
@@ -2415,7 +2529,8 @@ def axi_init(
     assert bench_result.data is not None  # OK/WARNING always carries an InitReport
     report = bench_result.data
 
-    if not cache.recache_project(project):
+    recache_warnings: list = []
+    if not cache.recache_project(project, bench_path=report.bench_path, warnings=recache_warnings):
         print(
             "Warning: bench created, but caching its bench path failed; "
             "run 'cwcli inspect --update' to refresh.",
@@ -2439,8 +2554,51 @@ def axi_init(
                 if warning.code in ("start.web_not_ready", "start.no_host_port"):
                     print(f"Warning: {warning.text}", file=sys.stderr, flush=True)
 
-    emit_result(bench_result.data, warnings=bench_result.warnings)
-    raise typer.Exit(0 if bench_result.status in (CoreStatus.OK, CoreStatus.WARNING) else 1)
+    setup_wizard_payload: dict | None = None
+    setup_wizard_ok = True
+    if complete_setup:
+        print("Completing the setup wizard...", file=sys.stderr, flush=True)
+        try:
+            setup_result = core_bench_ops.complete_setup_wizard(
+                project,
+                site=report.site_name,
+                bench_path=report.bench_path,
+                country=setup_country,
+                currency=setup_currency,
+                timezone=setup_timezone,
+                auto_start=False,
+                on_event=_bench_op_narrate,
+            )
+        except CwcliError as error:
+            setup_wizard_ok = False
+            setup_wizard_payload = {"ok": False, "error": error.message}
+        else:
+            if setup_result.status is CoreStatus.NEEDS_CHOICE:
+                # The container stopped in the window between bench creation and
+                # here; the bench+site above are already real, so this degrades to
+                # a reported failure rather than aborting before the InitReport
+                # an agent needs is ever printed.
+                setup_wizard_ok = False
+                setup_wizard_payload = {
+                    "ok": False,
+                    "error": f"the frappe container for '{project}' is not running",
+                }
+            else:
+                assert setup_result.data is not None  # OK/WARNING always carries a report
+                setup_wizard_payload = asdict(setup_result.data)
+                setup_wizard_ok = setup_result.data.ok
+
+    # ONE document: the setup_wizard outcome, when requested, is a block inside
+    # the SAME encode() call rather than a second emitted document.
+    payload = asdict(bench_result.data)
+    if setup_wizard_payload is not None:
+        payload["setup_wizard"] = setup_wizard_payload
+    typer.echo(toon.encode(payload, warnings=[*bench_result.warnings, *recache_warnings]))
+
+    # Never exit 0 for a failed explicit request: --complete-setup was asked for,
+    # so its own failure must be visible in the exit code, not just the payload.
+    overall_ok = bench_result.status in (CoreStatus.OK, CoreStatus.WARNING) and setup_wizard_ok
+    raise typer.Exit(0 if overall_ok else 1)
 
 
 # -------------------------------------------------------------------------------- rm
@@ -2711,7 +2869,8 @@ def axi_rm_site(
     # A failed recache is a stderr warning, NOT a non-zero exit: the drop
     # already happened, and failing here would make an agent retry a mutation
     # that already succeeded.
-    if not cache.recache_project(project):
+    warnings = list(result.warnings)
+    if not cache.recache_project(project, bench_path=outcome.bench_path, warnings=warnings):
         print(
             f"Warning: site dropped, but re-caching '{project}' failed; "
             "run 'cwcli inspect --update' to refresh.",
@@ -2719,7 +2878,7 @@ def axi_rm_site(
             flush=True,
         )
 
-    emit_result(outcome, warnings=result.warnings)
+    emit_result(outcome, warnings=warnings)
     # ok, NOT result.status: a drop with an unsafe archive is a WARNING-shaped
     # envelope, which maps to exit 0 everywhere else and would hide leftover
     # in-container credentials behind a green exit code.
@@ -2827,7 +2986,8 @@ def axi_rm_bench(
     # A failed recache is a stderr warning, NOT a non-zero exit: the removal
     # already happened, and failing here would make an agent retry a bench that
     # is already gone.
-    if not cache.recache_project(project):
+    warnings = list(result.warnings)
+    if not cache.recache_project(project, bench_path=outcome.bench_path, warnings=warnings):
         print(
             f"Warning: bench removed, but re-caching '{project}' failed; "
             "run 'cwcli inspect --update' to refresh.",
@@ -2835,7 +2995,7 @@ def axi_rm_bench(
             flush=True,
         )
 
-    emit_result(outcome, warnings=result.warnings)
+    emit_result(outcome, warnings=warnings)
     # ok, NOT result.status: a partial removal (a site's backup trapped in the
     # container) is a WARNING-shaped envelope, which maps to exit 0 everywhere
     # else and would report a green exit for an incomplete removal.

{caffeinated_whale_cli-3.2.1 → caffeinated_whale_cli-3.4.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():
     """