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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 3.3.0
+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
@@ -2579,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.3.0 → 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
@@ -2539,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.3.0 → caffeinated_whale_cli-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "caffeinated-whale-cli"
-version = "3.3.0"
+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.3.0 → 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.3.0 → 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.3.0 → caffeinated_whale_cli-3.4.0}/src/caffeinated_whale_cli/commands/console.html

@@ -1982,7 +1982,7 @@ dialog input {
       ? (pendingAction === action ? "working" : "another action is running")
       : null;
     const processDisabledReason = disabledReason("restart_process") || (!process ? "select process" : null);
-    const message = lastAction ? banner(lastAction.ok ? "success" : "danger", null, lastAction.text, lastAction.hint) : "";
+    const message = lastAction ? banner(lastAction.tone || (lastAction.ok ? "success" : "danger"), null, lastAction.text, lastAction.hint) : "";
     el("rail-body").innerHTML = `<div>
       <div class="target"><div class="target-name">${esc(targetName)}</div><div class="target-meta">${esc(targetMeta)}</div></div>
       <div class="action-group">
@@ -2072,10 +2072,14 @@ dialog input {
         }
         const choice = body.choice && body.choice.options ? " Options: " + body.choice.options.map(o => o.label || o.value).join(", ") : "";
         const failure = new Error((error.message || "action failed") + choice);
-        failure.hint = error.hint;
+        const warning = (body.warnings || []).map(w => w.text || w.code || "").filter(Boolean).join(" ");
+        failure.hint = [error.hint, warning].filter((value, index, values) => value && value !== failure.message && values.indexOf(value) === index).join(" ");
         throw failure;
       }
-      lastAction = {ok: true, text: `${action.replaceAll("_", " ")} accepted for ${inst.project}`};
+      const warning = (body.warnings || []).map(w => w.text || w.code || "").filter(Boolean).join(" ");
+      lastAction = warning
+        ? {ok: true, tone: "warn", text: `${action.replaceAll("_", " ")} completed with warnings for ${inst.project}`, hint: warning}
+        : {ok: true, text: `${action.replaceAll("_", " ")} accepted for ${inst.project}`};
       addEvent("fast", `ACTION ${action.replaceAll("_", " ")} ${inst.project}`);
       if (action === "set_label" || action === "checkout_app") {
         // The bench label / app registry just changed; the cached detail no
@@ -2090,6 +2094,7 @@ dialog input {
       pendingAction = null;
       renderRail();
       el("action-status").textContent = lastAction ? lastAction.text : "";
+      if (lastAction && lastAction.hint) el("action-status").textContent += `. ${lastAction.hint}`;
     }
   }
 

{caffeinated_whale_cli-3.3.0 → caffeinated_whale_cli-3.4.0}/src/caffeinated_whale_cli/commands/init.py

@@ -328,11 +328,12 @@ def _resolve_frappe_branch(frappe_branch: str | None, version: str | None) -> st
     return core_init.DEFAULT_FRAPPE_BRANCH
 
 
-def _refresh_cache(project: str, verbose: bool) -> None:
-    """Populate the bench cache right after a fresh bench is created.
+def _refresh_cache(project: str, verbose: bool, bench_path: str) -> None:
+    """Cache the bench right after it is created (or reused).
 
-    ``init_bench`` only CLEARS the project's cache (a stale entry would be
-    worse than none); nothing else repopulates it. Every bench-resolving verb
+    Only this bench is re-read and spliced into the project's cache; a failed
+    recache clears the project's cache instead (a stale entry would be worse
+    than none). Every bench-resolving verb
     (``status``, ``run``, ``apps``, ...) falls back to a hardcoded default
     bench path when the cache is empty, which only happens to match a bench
     built under the DEFAULT ``--bench-parent`` - a custom parent's very first
@@ -340,11 +341,16 @@ def _refresh_cache(project: str, verbose: bool) -> None:
     ``apps.py``'s post-mutation ``_refresh_cache``: degrades to a warning,
     never fails init (the bench itself already succeeded).
     """
-    if not cache.recache_project(project, verbose=verbose):
+    warnings: list = []
+    if not cache.recache_project(
+        project, verbose=verbose, bench_path=bench_path, warnings=warnings
+    ):
         stderr_console.print(
             "[yellow]Warning:[/yellow] bench created, but caching its bench path failed; "
             "run 'cwcli inspect --update' to refresh."
         )
+    for warning in warnings:
+        stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
 
 
 def _bench_web_url(project: str, bench_path: str, site: str) -> str | None:
@@ -794,7 +800,7 @@ def init(
         )
     console.print(f"[dim]Bench path: {report.bench_path}[/dim]")
 
-    _refresh_cache(project, verbose)
+    _refresh_cache(project, verbose, report.bench_path)
 
     # Auto-start the bench dev services (default) so init leaves a running dev
     # environment. Containers are already up (stage 1 brought them up), so no

{caffeinated_whale_cli-3.3.0 → caffeinated_whale_cli-3.4.0}/src/caffeinated_whale_cli/commands/rm.py

@@ -318,12 +318,15 @@ def _stop_after_transient_start(project_name: str) -> None:
         with stderr_console.status(
             f"[bold yellow]Stopping '{project_name}'...[/bold yellow]", spinner="dots"
         ):
-            core_stop.stop(project_name)
+            result = core_stop.stop(project_name)
     except Exception as e:
         stderr_console.print(
             f"[yellow]Warning:[/yellow] Could not stop '{project_name}' after aborting; it may "
             f"still be running: {e}"
         )
+        return
+    for warning in result.warnings:
+        stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
 
 
 def _recover_trailing_flags(
@@ -555,10 +558,15 @@ def rm(
                 if actual_verbose:
                     stderr_console.print(f"[dim]VERBOSE: Re-caching '{project}'...[/dim]")
 
-                if not cache.recache_project(project, verbose=actual_verbose):
+                recache_warnings: list = []
+                if not cache.recache_project(
+                    project, verbose=actual_verbose, warnings=recache_warnings
+                ):
                     stderr_console.print(
                         f"[yellow]Warning:[/yellow] Could not recache '{project}'. Backup may be incomplete."
                     )
+                for warning in recache_warnings:
+                    stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
 
     # Confirmation prompt (unless --yes flag is used)
     if not yes:

{caffeinated_whale_cli-3.3.0 → caffeinated_whale_cli-3.4.0}/src/caffeinated_whale_cli/commands/rm_bench.py

@@ -154,13 +154,16 @@ def rm_bench(
     # Removing a bench changes the instance's bench set, so refresh the cache.
     # A failed recache is a warning, not a non-zero exit: the removal already
     # happened, and failing here would make a retry act on a bench that is gone.
-    if not cache.recache_project(project_name, verbose=verbose):
+    recache_warnings: list = []
+    if not cache.recache_project(
+        project_name, verbose=verbose, bench_path=outcome.bench_path, warnings=recache_warnings
+    ):
         stderr_console.print(
             f"[yellow]Warning:[/yellow] bench removed, but re-caching '{project_name}' failed; "
             "run 'cwcli inspect --update' to refresh."
         )
 
-    for warning in result.warnings:
+    for warning in [*result.warnings, *recache_warnings]:
         stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
 
     if outcome.dir_removed:

{caffeinated_whale_cli-3.3.0 → caffeinated_whale_cli-3.4.0}/src/caffeinated_whale_cli/commands/rm_site.py

@@ -166,13 +166,16 @@ def rm_site(
     outcome = result.data
     assert outcome is not None  # OK/WARNING always carries a DropSiteOutcome
 
-    if not cache.recache_project(project_name, verbose=verbose):
+    recache_warnings: list = []
+    if not cache.recache_project(
+        project_name, verbose=verbose, bench_path=outcome.bench_path, warnings=recache_warnings
+    ):
         stderr_console.print(
             f"[yellow]Warning:[/yellow] site dropped, but re-caching '{project_name}' failed; "
             "run 'cwcli inspect --update' to refresh."
         )
 
-    for warning in result.warnings:
+    for warning in [*result.warnings, *recache_warnings]:
         stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
 
     console.print(f"[bold green]✓[/bold green] Site '{outcome.site}' dropped.")