caffeinated-whale-cli 3.1.0__tar.gz → 3.1.2__tar.gz

{caffeinated_whale_cli-3.1.0 → caffeinated_whale_cli-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 3.1.0
+Version: 3.1.2
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -886,6 +886,58 @@ See [For agents: the `cwcli axi` surface](#for-agents-the-cwcli-axi-surface).
 
 ---
 
+### `rm-bench` - Remove One Bench
+
+Permanently removes ONE bench from an instance, leaving every other bench and every container running.
+Like `rm-site`, this is a separate, noun-scoped command rather than a `--bench` flag on `cwcli rm`: `cwcli rm` destroys the whole instance, while `rm-bench` only ever touches the one bench you name, so forgetting a flag can never turn a single-bench cleanup into an instance-wide deletion.
+
+A bench is a directory on the instance's shared workspace bind mount, and its sites' data lives in the shared database - a bench has **no** dedicated container or named volume of its own.
+So `cwcli rm-bench` backs up and drops every site on the target bench (deleting each site's database and files), then deletes the bench directory.
+
+**WARNING:** This action is destructive and cannot be undone.
+Each site is dropped through the same verified copy-out that `cwcli rm-site` uses: `bench drop-site` backs the site up, and cwcli copies that archive out to `~/.cwcli/archive/{project}_dropped_sites/` (or `$CWCLI_HOME/archive/...` when that override is set) and verifies it on disk before the bench directory is deleted.
+If any site's backup cannot be copied out, the bench directory is kept (so the trapped backup is never destroyed) and the command exits non-zero.
+
+A bench that is still running is refused: stop it first with `cwcli stop <project> --bench <selector>`.
+`cwcli rm-bench` never deletes a bench out from under its own running code.
+
+```bash
+cwcli rm-bench [OPTIONS] PROJECT_NAME
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `PROJECT_NAME` | The Docker Compose project name (required) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--bench TEXT` | Which bench to remove: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
+| `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`; cannot be combined with it) |
+| `--db-root-password TEXT` | MariaDB root password used by `bench drop-site` (default: `123`, matching the compose file's own default) |
+| `-y`, `--yes` | Skip the destructive confirmation and auto-start the container |
+| `-v`, `--verbose` | Enable verbose output |
+
+**Examples:**
+
+```bash
+# Remove a bench (with confirmation)
+cwcli rm-bench my-project --bench 2
+
+# Skip the confirmation prompt
+cwcli rm-bench my-project --bench staging --yes
+```
+
+**Agent surface:** `cwcli axi rm-bench <project> --bench <index|label> --yes` emits the outcome as TOON, including `sites_dropped`, `archived_host_paths`, `dir_removed`, and `ok`.
+`--yes` is required (never a prompt) and grants ONLY consent - it never auto-starts a stopped project, exactly like every other bench-scoped `axi` verb.
+A running bench is a non-zero refusal naming `cwcli stop`.
+See [For agents: the `cwcli axi` surface](#for-agents-the-cwcli-axi-surface).
+
+---
+
 ### `logs` - View Bench Logs
 
 View the bench's process logs. supervisord writes one log file per Procfile
@@ -1201,7 +1253,7 @@ A bench that was not running is left alone.
 **`apps uninstall`** - removes each app from the target site(s) (`bench --site <site> uninstall-app`). This destroys site data, so it is gated by `-y`/`--yes` or an interactive confirmation (a non-TTY without `--yes` refuses). It uses the same resynchronise-and-verify step as install, so no supervised process - web, scheduler, or worker - can keep running against the code and tables of an app that is gone.
 
 **`apps update`** - the canonical app-update path (what the deprecated `cwcli update` now delegates to). Updating the `frappe` framework app runs `bench update --reset`; other apps use the normal git-pull + migrate flow. After the migrations finish and maintenance mode is lifted, it runs the same **resynchronise** step as `apps install`, so a `git pull` cannot leave the bench's web, scheduler, and workers on the code that was there before it; every migrated site must answer Frappe before the run reports success. `--site` narrows which affected sites are migrated; if none of the named site(s) actually have the app installed, the command refuses and exits non-zero rather than silently migrating nothing (a genuine typo/mismatch guard - a bench with no affected sites at all still exits zero). It accepts the same migration flags as the [deprecated `update` command](#update---update-apps-and-migrate) (`--clear-cache`, `--clear-website-cache`, `--build`, `--skip-maintenance`, `--no-recache`). When updating the `frappe` framework app the flow runs the bench-wide `bench update --reset`, so `--site` and those per-app migration flags do not apply and are reported as ignored.
-`--force` is an opt-in, **destructive** recovery for a conflicting update: if an app's `git pull` hits a **conflict** (local changes that would be overwritten, or a conflicted merge), it hard-resets that app to its remote tracking branch (`git fetch` then `git reset --hard @{u}`), discarding the local changes, so the update completes instead of failing. It fires **only on a conflict** - a clean update is untouched, and a pull that failed for another reason (network, auth) is left as the failure it is rather than having work discarded. Without `--force`, a conflict fails safely and discards nothing. Every force-reset app is reported (`force_reset_apps`) and a warning is printed at the reset. `--force` does not delete untracked files (it never runs `git clean`), matching `apps checkout --reset`.
+`--force` is an opt-in, **destructive** recovery for a conflicting update: if an app's `git pull` hits a **conflict** (local changes that would be overwritten, or a conflicted merge), it hard-resets that app to its remote tracking branch (`git fetch` then `git reset --hard @{u}`), discarding the local changes, so the update completes instead of failing. It fires **only on a conflict** - a clean update is untouched, and a pull that failed for another reason (network, auth) is left as the failure it is rather than having work discarded. Without `--force`, a conflict fails safely and discards nothing. Every force-reset app is reported (`force_reset_apps`) and a warning is printed at the reset. `--force` does not delete untracked files (it never runs `git clean`), matching `apps checkout --reset`. `--force` also clears a git **"dubious ownership"** refusal before pulling: when an app's repository is owned by a different user than the container runs as - common on a shared-mode or migrated instance whose app sources are owned by a pre-migration uid - it re-owns the repository to the container user so the pull proceeds, rather than surfacing a raw git ownership error. A `cwcli start`/`cwcli restart` self-heals the same ownership so a plain `apps update` works too; `--force` fixes it inline without a restart.
 
 **`apps checkout`** - fetches and checks out an arbitrary branch, tag, or commit (`REF`) into an app that is **already present** in the bench (`apps/<app>`), so a specific feature branch can be put under test in the instance the app lives in.
 Unlike `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app), this targets one existing checkout: it runs `git fetch <remote> <ref>` then `git checkout -B <ref> FETCH_HEAD` in the app directory (the remote is auto-detected - `upstream` for a bench-installed app, `origin` for a hand-cloned one).
@@ -2204,11 +2256,11 @@ cwcli run my-project migrate --bench 1          # by index
 cwcli update my-project --app erpnext --bench staging   # by label
 ```
 
-`--bench` is available on `run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`, `start`, `stop`, `restart`, `status`, and `logs`. Setting labels lives in the [`label`](#label---manage-bench-labels) command.
+`--bench` is available on `run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`, `rm-bench`, `start`, `stop`, `restart`, `status`, and `logs`. Setting labels lives in the [`label`](#label---manage-bench-labels) command.
 
 **No silent guessing on data commands:**
 
-If a project has more than one bench and you do not pass `--bench` (or `--path`), the data commands (`run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`) stop and list the benches instead of guessing:
+If a project has more than one bench and you do not pass `--bench` (or `--path`), the data commands (`run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`, `rm-bench`) stop and list the benches instead of guessing:
 
 ```
 Error: project 'my-project' has multiple benches; specify one with --bench <index|label>:
@@ -2592,14 +2644,14 @@ The CLI uses:
 - **Peewee ORM** - SQLite-based caching
 
 **Logic core:** business logic and I/O live in a UI-pure `core/` package that carries no `rich`/`questionary`/`typer`; it returns a serializable typed envelope (or raises a typed error) so the human CLI, the `cwcli axi` agent surface, and the Console GUI are all thin frontends over one implementation.
-`backup`, `unlock`, `stop`, `label`, `run`, `ls`/`list`, `where`, `start`/`status`/`restart`, `logs`, `inspect`, `apps`, `update`, `open`, `init`, `config`, `restore`, `rm`, and `rm-site` are migrated onto it so far.
+`backup`, `unlock`, `stop`, `label`, `run`, `ls`/`list`, `where`, `start`/`status`/`restart`, `logs`, `inspect`, `apps`, `update`, `open`, `init`, `config`, `restore`, `rm`, `rm-site`, and `rm-bench` are migrated onto it so far.
 
 **Data Directories:**
 - **Projects**: `~/.cwcli/projects/` - Project directories created by `cwcli init`
 - **Config**: `~/.cwcli/config/` - Configuration files
 - **Cache**: `~/.cwcli/cache/cwc-cache.db` - Project inspection cache
 - **Runtime**: `~/.cwcli/run/` - PID and log files for background services
-- **Archive**: `~/.cwcli/archive/` - Pre-deletion backups and config snapshots from `cwcli rm`, plus dropped-site archives from `cwcli rm-site`
+- **Archive**: `~/.cwcli/archive/` - Pre-deletion backups and config snapshots from `cwcli rm`, plus dropped-site archives from `cwcli rm-site` and `cwcli rm-bench`
 - **Transfers**: `~/.cwcli/tmp/` by default, or `$TMPDIR/cwcli/`, `$TEMP/cwcli/`, or `$TMP/cwcli/` when the first non-empty variable in that order is set. Temporary files used by `restore --send` and `restore --receive`; each attempt is removed when it finishes or fails
 
 **Relocating cwcli's data (`CWCLI_HOME`):**

{caffeinated_whale_cli-3.1.0 → caffeinated_whale_cli-3.1.2}/README.md

@@ -846,6 +846,58 @@ See [For agents: the `cwcli axi` surface](#for-agents-the-cwcli-axi-surface).
 
 ---
 
+### `rm-bench` - Remove One Bench
+
+Permanently removes ONE bench from an instance, leaving every other bench and every container running.
+Like `rm-site`, this is a separate, noun-scoped command rather than a `--bench` flag on `cwcli rm`: `cwcli rm` destroys the whole instance, while `rm-bench` only ever touches the one bench you name, so forgetting a flag can never turn a single-bench cleanup into an instance-wide deletion.
+
+A bench is a directory on the instance's shared workspace bind mount, and its sites' data lives in the shared database - a bench has **no** dedicated container or named volume of its own.
+So `cwcli rm-bench` backs up and drops every site on the target bench (deleting each site's database and files), then deletes the bench directory.
+
+**WARNING:** This action is destructive and cannot be undone.
+Each site is dropped through the same verified copy-out that `cwcli rm-site` uses: `bench drop-site` backs the site up, and cwcli copies that archive out to `~/.cwcli/archive/{project}_dropped_sites/` (or `$CWCLI_HOME/archive/...` when that override is set) and verifies it on disk before the bench directory is deleted.
+If any site's backup cannot be copied out, the bench directory is kept (so the trapped backup is never destroyed) and the command exits non-zero.
+
+A bench that is still running is refused: stop it first with `cwcli stop <project> --bench <selector>`.
+`cwcli rm-bench` never deletes a bench out from under its own running code.
+
+```bash
+cwcli rm-bench [OPTIONS] PROJECT_NAME
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `PROJECT_NAME` | The Docker Compose project name (required) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--bench TEXT` | Which bench to remove: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
+| `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`; cannot be combined with it) |
+| `--db-root-password TEXT` | MariaDB root password used by `bench drop-site` (default: `123`, matching the compose file's own default) |
+| `-y`, `--yes` | Skip the destructive confirmation and auto-start the container |
+| `-v`, `--verbose` | Enable verbose output |
+
+**Examples:**
+
+```bash
+# Remove a bench (with confirmation)
+cwcli rm-bench my-project --bench 2
+
+# Skip the confirmation prompt
+cwcli rm-bench my-project --bench staging --yes
+```
+
+**Agent surface:** `cwcli axi rm-bench <project> --bench <index|label> --yes` emits the outcome as TOON, including `sites_dropped`, `archived_host_paths`, `dir_removed`, and `ok`.
+`--yes` is required (never a prompt) and grants ONLY consent - it never auto-starts a stopped project, exactly like every other bench-scoped `axi` verb.
+A running bench is a non-zero refusal naming `cwcli stop`.
+See [For agents: the `cwcli axi` surface](#for-agents-the-cwcli-axi-surface).
+
+---
+
 ### `logs` - View Bench Logs
 
 View the bench's process logs. supervisord writes one log file per Procfile
@@ -1161,7 +1213,7 @@ A bench that was not running is left alone.
 **`apps uninstall`** - removes each app from the target site(s) (`bench --site <site> uninstall-app`). This destroys site data, so it is gated by `-y`/`--yes` or an interactive confirmation (a non-TTY without `--yes` refuses). It uses the same resynchronise-and-verify step as install, so no supervised process - web, scheduler, or worker - can keep running against the code and tables of an app that is gone.
 
 **`apps update`** - the canonical app-update path (what the deprecated `cwcli update` now delegates to). Updating the `frappe` framework app runs `bench update --reset`; other apps use the normal git-pull + migrate flow. After the migrations finish and maintenance mode is lifted, it runs the same **resynchronise** step as `apps install`, so a `git pull` cannot leave the bench's web, scheduler, and workers on the code that was there before it; every migrated site must answer Frappe before the run reports success. `--site` narrows which affected sites are migrated; if none of the named site(s) actually have the app installed, the command refuses and exits non-zero rather than silently migrating nothing (a genuine typo/mismatch guard - a bench with no affected sites at all still exits zero). It accepts the same migration flags as the [deprecated `update` command](#update---update-apps-and-migrate) (`--clear-cache`, `--clear-website-cache`, `--build`, `--skip-maintenance`, `--no-recache`). When updating the `frappe` framework app the flow runs the bench-wide `bench update --reset`, so `--site` and those per-app migration flags do not apply and are reported as ignored.
-`--force` is an opt-in, **destructive** recovery for a conflicting update: if an app's `git pull` hits a **conflict** (local changes that would be overwritten, or a conflicted merge), it hard-resets that app to its remote tracking branch (`git fetch` then `git reset --hard @{u}`), discarding the local changes, so the update completes instead of failing. It fires **only on a conflict** - a clean update is untouched, and a pull that failed for another reason (network, auth) is left as the failure it is rather than having work discarded. Without `--force`, a conflict fails safely and discards nothing. Every force-reset app is reported (`force_reset_apps`) and a warning is printed at the reset. `--force` does not delete untracked files (it never runs `git clean`), matching `apps checkout --reset`.
+`--force` is an opt-in, **destructive** recovery for a conflicting update: if an app's `git pull` hits a **conflict** (local changes that would be overwritten, or a conflicted merge), it hard-resets that app to its remote tracking branch (`git fetch` then `git reset --hard @{u}`), discarding the local changes, so the update completes instead of failing. It fires **only on a conflict** - a clean update is untouched, and a pull that failed for another reason (network, auth) is left as the failure it is rather than having work discarded. Without `--force`, a conflict fails safely and discards nothing. Every force-reset app is reported (`force_reset_apps`) and a warning is printed at the reset. `--force` does not delete untracked files (it never runs `git clean`), matching `apps checkout --reset`. `--force` also clears a git **"dubious ownership"** refusal before pulling: when an app's repository is owned by a different user than the container runs as - common on a shared-mode or migrated instance whose app sources are owned by a pre-migration uid - it re-owns the repository to the container user so the pull proceeds, rather than surfacing a raw git ownership error. A `cwcli start`/`cwcli restart` self-heals the same ownership so a plain `apps update` works too; `--force` fixes it inline without a restart.
 
 **`apps checkout`** - fetches and checks out an arbitrary branch, tag, or commit (`REF`) into an app that is **already present** in the bench (`apps/<app>`), so a specific feature branch can be put under test in the instance the app lives in.
 Unlike `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app), this targets one existing checkout: it runs `git fetch <remote> <ref>` then `git checkout -B <ref> FETCH_HEAD` in the app directory (the remote is auto-detected - `upstream` for a bench-installed app, `origin` for a hand-cloned one).
@@ -2164,11 +2216,11 @@ cwcli run my-project migrate --bench 1          # by index
 cwcli update my-project --app erpnext --bench staging   # by label
 ```
 
-`--bench` is available on `run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`, `start`, `stop`, `restart`, `status`, and `logs`. Setting labels lives in the [`label`](#label---manage-bench-labels) command.
+`--bench` is available on `run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`, `rm-bench`, `start`, `stop`, `restart`, `status`, and `logs`. Setting labels lives in the [`label`](#label---manage-bench-labels) command.
 
 **No silent guessing on data commands:**
 
-If a project has more than one bench and you do not pass `--bench` (or `--path`), the data commands (`run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`) stop and list the benches instead of guessing:
+If a project has more than one bench and you do not pass `--bench` (or `--path`), the data commands (`run`, `backup`, `update`, `open`, `unlock`, `restore`, `rm-site`, `rm-bench`) stop and list the benches instead of guessing:
 
 ```
 Error: project 'my-project' has multiple benches; specify one with --bench <index|label>:
@@ -2552,14 +2604,14 @@ The CLI uses:
 - **Peewee ORM** - SQLite-based caching
 
 **Logic core:** business logic and I/O live in a UI-pure `core/` package that carries no `rich`/`questionary`/`typer`; it returns a serializable typed envelope (or raises a typed error) so the human CLI, the `cwcli axi` agent surface, and the Console GUI are all thin frontends over one implementation.
-`backup`, `unlock`, `stop`, `label`, `run`, `ls`/`list`, `where`, `start`/`status`/`restart`, `logs`, `inspect`, `apps`, `update`, `open`, `init`, `config`, `restore`, `rm`, and `rm-site` are migrated onto it so far.
+`backup`, `unlock`, `stop`, `label`, `run`, `ls`/`list`, `where`, `start`/`status`/`restart`, `logs`, `inspect`, `apps`, `update`, `open`, `init`, `config`, `restore`, `rm`, `rm-site`, and `rm-bench` are migrated onto it so far.
 
 **Data Directories:**
 - **Projects**: `~/.cwcli/projects/` - Project directories created by `cwcli init`
 - **Config**: `~/.cwcli/config/` - Configuration files
 - **Cache**: `~/.cwcli/cache/cwc-cache.db` - Project inspection cache
 - **Runtime**: `~/.cwcli/run/` - PID and log files for background services
-- **Archive**: `~/.cwcli/archive/` - Pre-deletion backups and config snapshots from `cwcli rm`, plus dropped-site archives from `cwcli rm-site`
+- **Archive**: `~/.cwcli/archive/` - Pre-deletion backups and config snapshots from `cwcli rm`, plus dropped-site archives from `cwcli rm-site` and `cwcli rm-bench`
 - **Transfers**: `~/.cwcli/tmp/` by default, or `$TMPDIR/cwcli/`, `$TEMP/cwcli/`, or `$TMP/cwcli/` when the first non-empty variable in that order is set. Temporary files used by `restore --send` and `restore --receive`; each attempt is removed when it finishes or fails
 
 **Relocating cwcli's data (`CWCLI_HOME`):**

{caffeinated_whale_cli-3.1.0 → caffeinated_whale_cli-3.1.2}/pyproject.toml

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

caffeinated_whale_cli-3.1.2/src/caffeinated_whale_cli/__init__.py

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

{caffeinated_whale_cli-3.1.0 → caffeinated_whale_cli-3.1.2}/src/caffeinated_whale_cli/commands/axi.py

@@ -47,6 +47,7 @@ from ..core import list as core_list
 from ..core import logs as core_logs
 from ..core import restart as core_restart
 from ..core import rm as core_rm
+from ..core import rm_bench as core_rm_bench
 from ..core import rm_site as core_rm_site
 from ..core import scale as core_scale
 from ..core import start as core_start
@@ -578,6 +579,11 @@ def _choice_error_message(choice: Choice) -> str:
         # `axi rm-site` only. Dropping a site deletes its database and files;
         # the agent must consent. The --yes flag rides the `help:` line below.
         return "dropping this site permanently deletes its database and files"
+    if choice.kind == "confirm_remove_bench":
+        # `axi rm-bench` only. Removing a bench drops every site on it (their
+        # databases and files) and deletes the bench directory; the agent must
+        # consent. The --yes flag rides the `help:` line below.
+        return "removing this bench drops every site on it and deletes its directory"
     return f"a decision is required: {choice.prompt}"
 
 
@@ -602,6 +608,8 @@ def emit_axi_choice_as_usage_error(choice: Choice) -> None:
         typer.echo(toon.kv("help", "re-run with --yes to accept the whole-instance restart"))
     elif choice.kind == "confirm_drop_site":
         typer.echo(toon.kv("help", "re-run with --yes to consent to permanently dropping it"))
+    elif choice.kind == "confirm_remove_bench":
+        typer.echo(toon.kv("help", "re-run with --yes to consent to permanently removing it"))
     elif choice.kind == "confirm_reuse_bench":
         typer.echo(
             toon.kv(
@@ -2673,6 +2681,122 @@ def axi_rm_site(
     raise typer.Exit(0 if outcome.ok else 1)
 
 
+# --------------------------------------------------------------------------- rm-bench
+
+
+def _rm_bench_narrate(event) -> None:
+    """Every rm-bench event to STDERR (the `_drop_site_narrate` reasoning): the
+    per-site `bench drop-site` output and progress notes are not supervised-process
+    logs, and they must not touch stdout, which carries the one TOON document.
+    """
+    if isinstance(event, core_rm_bench.BenchRmCommand):
+        print(f"$ {event.command}", file=sys.stderr, flush=True)
+    elif isinstance(event, core_rm_bench.BenchRmOutput):
+        print(event.text, end="", file=sys.stderr, flush=True)
+    elif isinstance(event, (core_rm_bench.BenchRmNotice, core_rm_bench.BenchRmStep)):
+        text = getattr(event, "text", None) or getattr(event, "label", "")
+        print(text, file=sys.stderr, flush=True)
+    elif isinstance(event, core_rm_bench.BenchRmWarning):
+        print(f"Warning: {event.text}", file=sys.stderr, flush=True)
+        if event.hint:
+            print(event.hint, file=sys.stderr, flush=True)
+
+
+@app.command("rm-bench")
+def axi_rm_bench(
+    project: str = typer.Argument(..., help="The Docker Compose project name."),
+    bench: str = typer.Option(
+        None, "--bench", help="Which bench to remove: numeric index or label (see 'axi benches')."
+    ),
+    db_root_password: str = typer.Option(
+        "123", "--db-root-password", help="MariaDB root password used by 'bench drop-site'."
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        help="REQUIRED consent to permanently remove this bench and drop its sites.",
+    ),
+) -> None:
+    """Permanently remove ONE bench; emit the outcome as TOON (never prompts).
+
+    The bench-scoped sibling of `axi rm` (whole instance) and `axi rm-site` (one
+    site). A bench has no dedicated container or named volume - it is a directory
+    on the instance's shared workspace bind mount whose sites live in the shared
+    database - so this backs up and drops every site on the bench (deleting each
+    site's database and files) and then deletes the bench directory. Every OTHER
+    bench and every container keep running; it never touches the instance's
+    containers, named volumes, or project directory.
+
+    `--yes` is REQUIRED: without it this is a usage error naming the flag, never
+    a prompt. NO auto-start: a stopped project is a usage error naming
+    `cwcli start`, exactly as every other bench-scoped axi verb refuses it.
+
+    A bench that is still running is refused (exit 1) naming
+    `cwcli stop <project> --bench <selector>`: a live bench is never deleted out
+    from under its own running code.
+
+    Each site is dropped through the same verified copy-out `axi rm-site` uses:
+    `bench drop-site` backs the site up, and cwcli copies that archive out to the
+    managed host location (`archived_host_paths` in the report) and verifies it on
+    disk before the bench directory is deleted. If any site's archive could not be
+    copied out, the directory is kept (to preserve that trapped archive), the site
+    is reported in `sites_failed`, and `ok: false` with a non-zero exit.
+
+    Each `bench drop-site`'s own output goes to stderr in full and unparsed.
+    """
+    if not yes:
+        emit_axi_error(
+            CwcliError(
+                ErrorKind.USAGE,
+                "rm_bench.consent_required",
+                f"Refusing to remove a bench from '{project}' without explicit consent.",
+                hint=(
+                    "re-run with --yes to permanently remove this bench and drop its "
+                    "sites' databases and files"
+                ),
+            )
+        )
+        raise typer.Exit(exit_for(ErrorKind.USAGE))
+
+    try:
+        result = core_rm_bench.remove_bench(
+            project,
+            bench=bench,
+            consent=yes,
+            db_root_password=db_root_password,
+            on_event=_rm_bench_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 BenchRemovalOutcome
+    outcome = result.data
+
+    # Removing a bench changes the instance's bench set, so refresh the cache.
+    # 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):
+        print(
+            f"Warning: bench removed, but re-caching '{project}' failed; "
+            "run 'cwcli inspect --update' to refresh.",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    emit_result(outcome, warnings=result.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.
+    raise typer.Exit(0 if outcome.ok else 1)
+
+
 # ------------------------------------------------------------------------ self-update
 
 

caffeinated_whale_cli-3.1.2/src/caffeinated_whale_cli/commands/rm_bench.py

@@ -0,0 +1,184 @@
+"""``cwcli rm-bench`` - the human frontend over ``core.remove_bench``.
+
+A dedicated, noun-scoped verb (not a ``--bench`` flag on ``rm``): removing ONE
+bench drops its sites and deletes its directory while every sibling bench and
+container keeps running, whereas ``cwcli rm`` destroys the whole instance, and
+hiding that difference behind a flag on the bigger command is a footgun. See
+``core/rm_bench.py``'s module docstring for the full rationale, the "refuse while
+running" gate, and the per-site backup-then-drop the deletion is built from.
+
+This module only prompts, resolves the bench, streams each site drop's own
+output, and renders the outcome; the resolution, the running gate, the
+``bench drop-site`` fan-out, and the directory deletion live in the core.
+"""
+
+import sys
+
+import typer
+
+from ..core import rm_bench as core_rm_bench
+from ..core.envelope import Status
+from ..core.errors import CwcliError
+from ..core.rm_bench import (
+    BenchRmCommand,
+    BenchRmNotice,
+    BenchRmOutput,
+    BenchRmStep,
+    BenchRmWarning,
+)
+from ..utils import cache
+from ..utils.completion_utils import complete_project_names
+from ..utils.console import console, stderr_console
+from ..utils.docker_utils import handle_docker_errors
+from .utils import confirm_or_exit, ensure_containers_running, resolve_bench_path
+
+
+def _make_renderer(*, verbose: bool):
+    def on_event(event) -> None:
+        if isinstance(event, BenchRmStep):
+            if verbose:
+                stderr_console.print(f"[dim]{event.label}[/dim]")
+        elif isinstance(event, BenchRmCommand):
+            if verbose:
+                stderr_console.print(f"[dim]$ {event.command}[/dim]")
+        elif isinstance(event, BenchRmOutput):
+            sys.stdout.write(event.text)
+            sys.stdout.flush()
+        elif isinstance(event, BenchRmNotice):
+            console.print(f"[dim]{event.text}[/dim]")
+        elif isinstance(event, BenchRmWarning):
+            stderr_console.print(f"[yellow]Warning:[/yellow] {event.text}")
+            if event.hint:
+                stderr_console.print(f"[dim]{event.hint}[/dim]")
+
+    return on_event
+
+
+def _exit_on_error(e: CwcliError):
+    stderr_console.print(f"[bold red]Error:[/bold red] {e.message}")
+    if e.hint:
+        stderr_console.print(f"[dim]{e.hint}[/dim]")
+    raise typer.Exit(code=1) from e
+
+
+@handle_docker_errors
+def rm_bench(
+    project_name: str = typer.Argument(
+        ..., help="The Docker Compose project name.", autocompletion=complete_project_names
+    ),
+    bench: str = typer.Option(
+        None, "--bench", help="Which bench to remove: its numeric index or label."
+    ),
+    bench_path: str = typer.Option(
+        None, "--path", "-p", help="Explicit bench directory (lower-level alternative to --bench)."
+    ),
+    db_root_password: str = typer.Option(
+        "123", "--db-root-password", help="MariaDB root password used by 'bench drop-site'."
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip the destructive confirmation and auto-start the container.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
+):
+    """Permanently remove ONE bench from an instance (destructive).
+
+    Backs up and drops every site on the target bench (deleting each site's
+    database and files), then deletes the bench directory. Every OTHER bench and
+    every container keep running - this never touches the instance's containers,
+    named volumes, or the project directory (use 'cwcli rm' to remove the whole
+    instance).
+
+    A bench that is still running is refused: stop it first with
+    'cwcli stop <project> --bench <selector>'. Each site's backup is copied out
+    to ~/.cwcli/archive/<project>_dropped_sites/ (or $CWCLI_HOME/archive/... if
+    that override is set) and verified on disk before the bench directory is
+    deleted; if a backup cannot be copied out, the directory is kept so the
+    backup is never destroyed, and this command exits non-zero.
+
+    Examples:
+        cwcli rm-bench my-project --bench 2
+        cwcli rm-bench my-project --bench staging --yes
+    """
+    ensure_containers_running(project_name, require_running=True, verbose=verbose, auto_start=yes)
+
+    resolved = resolve_bench_path(project_name, bench, bench_path, verbose=verbose)
+    if resolved:
+        bench_path = resolved
+        if verbose:
+            stderr_console.print(f"[dim]Using bench path: {bench_path}[/dim]")
+
+    on_event = _make_renderer(verbose=verbose)
+
+    def _remove(consent: bool):
+        try:
+            return core_rm_bench.remove_bench(
+                project_name,
+                bench_path=bench_path,
+                consent=consent,
+                db_root_password=db_root_password,
+                on_event=on_event,
+            )
+        except CwcliError as e:
+            _exit_on_error(e)
+
+    result = _remove(False)
+
+    if (
+        result.status is Status.NEEDS_CHOICE
+        and result.choice is not None
+        and result.choice.kind == "confirm_remove_bench"
+    ):
+        confirm_or_exit(
+            result.choice.prompt,
+            assume_yes=yes,
+            refuse_message=(
+                "Removing a bench is destructive and no confirmation was given. "
+                "Pass --yes to proceed."
+            ),
+        )
+        console.print(f"[bold red]Removing bench '{bench_path}'...[/bold red]")
+        result = _remove(True)
+
+    if result.status is Status.NEEDS_CHOICE and result.choice is not None:
+        # A resolver fork not handled above (e.g. select_bench, if the cache
+        # changed under us): report rather than guess.
+        stderr_console.print(f"[bold red]Error:[/bold red] {result.choice.prompt}")
+        raise typer.Exit(code=1)
+
+    outcome = result.data
+    assert outcome is not None  # OK/WARNING always carries a BenchRemovalOutcome
+
+    # 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):
+        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:
+        stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
+
+    if outcome.dir_removed:
+        dropped = len(outcome.sites_dropped)
+        console.print(
+            f"[bold green]✓[/bold green] Bench '{outcome.bench_path}' removed "
+            f"({dropped} site(s) backed up and dropped)."
+        )
+        if outcome.archived_host_paths:
+            console.print(
+                "[dim]Each dropped site's backup archive was copied to "
+                f"{outcome.archived_host_paths[0].rsplit('/', 1)[0]}/.[/dim]"
+            )
+    else:
+        stderr_console.print(
+            f"[yellow]Bench '{outcome.bench_path}' was not fully removed; "
+            "see the warnings above.[/yellow]"
+        )
+
+    if not outcome.ok:
+        raise typer.Exit(code=1)