caffeinated-whale-cli 2.2.0__tar.gz → 2.3.0__tar.gz

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 2.2.0
+Version: 2.3.0
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -1114,14 +1114,24 @@ cwcli apps checkout [OPTIONS] PROJECT_NAME APP REF
 
 **`apps list`** - lists apps available in the bench (live `ls apps/`); with `--installed`/`--site` it also lists the apps installed per site (all sites by default, grouped by site).
 
-**`apps install`** - fetches (`bench get-app`, honoring `--branch`) and installs each app on the target site(s). Each `APP` is a known app name **or** a git URL (passed straight to `bench get-app`, so custom apps not in bench's registry work). `--fetch-only` fetches without installing on any site. A bench that is already running may still serve code it loaded before the install and fail to see the new app: install therefore **resynchronises** that bench - it restarts every cwcli-supervised program that runs the bench's Python (`web`, `schedule`, and every worker) and requires every changed site to answer Frappe before it reports success. Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm. A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy. `socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing. Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists. A bench that was not running is left alone.
+**`apps install`** - ensures each app is present on the bench, then installs it on the target site(s).
+An app absent from `apps/` is fetched with `bench get-app` (honoring `--branch`); an app already present is not fetched again, so pre-warmed benches install it without failing on the existing directory.
+Each `APP` is a known app name **or** a git URL (passed straight to `bench get-app` when a fetch is needed, so custom apps not in bench's registry work).
+`--fetch-only` ensures the app is present without installing it on any site.
+`--if-not-present` makes install idempotent: an app already installed on a target site is skipped (reported, not reinstalled, with its install hooks never rerun) and the command still exits 0, so "ensure this app is installed" is a single call whose exit code a script can trust; an app the site does not have is still installed normally, and a genuine install failure still exits non-zero.
+A bench that is already running may still serve code it loaded before the install and fail to see the new app: install therefore **resynchronises** that bench - it restarts every cwcli-supervised program that runs the bench's Python (`web`, `schedule`, and every worker) and requires every changed site to answer Frappe before it reports success.
+Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm.
+A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy.
+`socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing.
+Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists.
+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.
 
 **`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` (a fresh `bench get-app` clone) 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).
+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).
 A **dirty working tree is refused** before anything is fetched, so uncommitted work in the in-instance checkout is never carried across a branch switch.
 Once the checkout step moves the tree, the command runs the same **resynchronise** step `apps install` uses, even if a later `--reset` step fails.
 Swapping the code under a running bench and leaving it serving the branch you just moved off is the quietest form of that defect, because nothing errors at all.
@@ -2224,16 +2234,19 @@ cwcli axi apps update frappe-one erpnext
 cwcli axi apps update frappe-one frappe          # runs 'bench update --reset'
 
 # Put ONE branch, tag, or commit under test in an app already in the bench -
-# the gap 'apps install' (a fresh clone) and 'apps update' (the tracked
+# the gap 'apps install' (bench acquisition and site installation) and 'apps update' (the tracked
 # upstream) leave. Add --reset to force a clean tree at the fetched ref.
 cwcli axi apps checkout frappe-one myapp feature/new-thing
 cwcli axi apps checkout frappe-one myapp feature/new-thing --reset
 
-# Fetch and install ONE app on ONE named site. --site is required (there is no
+# Ensure and install ONE app on ONE named site. --site is required (there is no
 # fan-out here), and an app already installed on that site is refused rather
-# than re-installed over its existing data.
+# than reinstalled over its existing data unless --if-not-present requests a skip.
 cwcli axi apps install frappe-one hrms --site erp.localhost
 cwcli axi apps install frappe-one https://github.com/me/myapp --site erp.localhost --branch develop
+# Idempotent: skip (do not reinstall) an app already on the site and exit 0, so a
+# CI step can trust the exit code. A real install failure still exits non-zero.
+cwcli axi apps install frappe-one hrms --site erp.localhost --if-not-present
 
 # Provision a new instance, bench, and site; the report prints as ONE TOON
 # document. BLOCKS for the full 10-20 minute run (like axi apps update) and
@@ -2278,9 +2291,9 @@ Use `cwcli open`'s banner for the host address and `cwcli status` for the HTTP o
 
 `cwcli axi apps list` is the read that answers what is *on* the bench `cwcli axi benches` names: the bench's available apps, and with `--installed`/`--site` which apps are installed on which site (only the app name, never the version column `bench list-apps` prints). A site whose read FAILED is reported as `null` and exits `1`, never as an empty list - "has no apps" and "could not tell" are different facts, and only one of them is safe to act on. Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start` (exit 2). **`cwcli axi apps uninstall` deliberately does not exist:** letting an agent drop the tables of a real site is a product decision that deserves its own evidence, not something settled as a side effect of moving code onto the logic core. Use the human `cwcli apps uninstall` (it has `--json` and honest exit codes) until that decision is taken. `cwcli axi apps install` was held under that same shared rationale and now exists, scoped to the half of it that rationale never covered - see below.
 
-`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (a fresh `bench get-app` clone) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
+`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
 
-`cwcli axi apps install <project> <app-or-git-url> --site <site>` fetches an app into the bench and installs it on one named site.
+`cwcli axi apps install <project> <app-or-git-url> --site <site>` ensures the app is present on the bench, fetching it only when absent, and installs it on one named site.
 Installing an app is the first step of essentially any Frappe app work, and until this verb existed it was the one routine operation with no agent-surface form, so an agent had to drop to the raw human command for it.
 It is deliberately narrower than the human `cwcli apps install`, in exactly two ways, because the original deferral of `apps install`/`apps uninstall` named a real threat - an agent destroying site data - that covers `uninstall` unconditionally but covers `install` only in one case.
 Installing an app a site does **not** have creates that app's own tables and touches no other app's data; installing over an app the site **already** has re-runs that app's install hooks against rows that already exist.
@@ -2290,14 +2303,15 @@ So the verb ships scoped to the first case and refuses the second, rather than b
 The human verb installs on every site on the bench when you omit it; an unqualified fan-out is how an agent reaches a site nobody named, so on this surface the target is always explicit.
 That follows `cwcli axi run-tests`, which requires its site for the same reason: `install-app` runs the app's `after_install`, which is arbitrary Python from the repository being installed, against a live database, and when the effect is unbounded, defaulting the target is the wrong default.
 
-**An app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
+**By default, an app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
 The refusal names what to do instead: `cwcli axi apps checkout` to move the app to another ref, `cwcli axi apps update` to pull and migrate it, or the human `cwcli apps install` for a genuine reinstall.
 A site whose installed-app list cannot be *read* is refused too (`app.install_state_unknown`), because an unreadable state must never be treated as "nothing is installed there".
-There is deliberately **no flag to bypass this**: a `--force` here has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
-The escape hatch is the human verb, which is where a human confirms a reinstall.
+There is deliberately **no flag to bypass this by reinstalling**: a `--force` that re-ran the install hooks over existing data has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
+The escape hatch for a genuine reinstall is the human verb, which is where a human confirms one.
 
-Note that the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success.
-The desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so exiting `0` would be asserting something it has not verified.
+By default the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success: the desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so a silent exit `0` would be asserting something it has not verified.
+`--if-not-present` opts into the idempotent reading for a caller that just wants the app present: an app already installed on the site is then **skipped** (reported as a `skip-install` row, with its install hooks never rerun) and the verb exits `0`, so a CI step can trust the exit code instead of swallowing every failure with `|| true`; an app the site lacks is still installed, and a genuine install failure still exits non-zero.
+It is not a `--force`: there is still no way to reinstall over an app the site already has.
 Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start`.
 Private-repo fetches use the same credential bridge as `apps update`/`apps checkout`, so no token is stored in the container.
 On an already-serving bench, the operation resynchronises that bench - it restarts every supervised program running the bench's Python (`web`, `schedule`, workers) and reports a `restart-processes` row.

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/README.md

@@ -1074,14 +1074,24 @@ cwcli apps checkout [OPTIONS] PROJECT_NAME APP REF
 
 **`apps list`** - lists apps available in the bench (live `ls apps/`); with `--installed`/`--site` it also lists the apps installed per site (all sites by default, grouped by site).
 
-**`apps install`** - fetches (`bench get-app`, honoring `--branch`) and installs each app on the target site(s). Each `APP` is a known app name **or** a git URL (passed straight to `bench get-app`, so custom apps not in bench's registry work). `--fetch-only` fetches without installing on any site. A bench that is already running may still serve code it loaded before the install and fail to see the new app: install therefore **resynchronises** that bench - it restarts every cwcli-supervised program that runs the bench's Python (`web`, `schedule`, and every worker) and requires every changed site to answer Frappe before it reports success. Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm. A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy. `socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing. Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists. A bench that was not running is left alone.
+**`apps install`** - ensures each app is present on the bench, then installs it on the target site(s).
+An app absent from `apps/` is fetched with `bench get-app` (honoring `--branch`); an app already present is not fetched again, so pre-warmed benches install it without failing on the existing directory.
+Each `APP` is a known app name **or** a git URL (passed straight to `bench get-app` when a fetch is needed, so custom apps not in bench's registry work).
+`--fetch-only` ensures the app is present without installing it on any site.
+`--if-not-present` makes install idempotent: an app already installed on a target site is skipped (reported, not reinstalled, with its install hooks never rerun) and the command still exits 0, so "ensure this app is installed" is a single call whose exit code a script can trust; an app the site does not have is still installed normally, and a genuine install failure still exits non-zero.
+A bench that is already running may still serve code it loaded before the install and fail to see the new app: install therefore **resynchronises** that bench - it restarts every cwcli-supervised program that runs the bench's Python (`web`, `schedule`, and every worker) and requires every changed site to answer Frappe before it reports success.
+Each restart is announced as it happens and the step is reported as a `restart-processes` row, and the command exits non-zero rather than claiming success for a site it could not confirm.
+A running manager that cwcli does not own is verified without being restarted; an unhealthy site fails with a manual-restart remedy.
+`socketio`, `watch`, and the redis programs are deliberately left alone: they import no Frappe app, and cycling redis would drop the cache and the job queue for nothing.
+Restarting a worker does interrupt a job in flight, which is the honest cost of not leaving background jobs running code that no longer exists.
+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.
 
 **`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` (a fresh `bench get-app` clone) 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).
+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).
 A **dirty working tree is refused** before anything is fetched, so uncommitted work in the in-instance checkout is never carried across a branch switch.
 Once the checkout step moves the tree, the command runs the same **resynchronise** step `apps install` uses, even if a later `--reset` step fails.
 Swapping the code under a running bench and leaving it serving the branch you just moved off is the quietest form of that defect, because nothing errors at all.
@@ -2184,16 +2194,19 @@ cwcli axi apps update frappe-one erpnext
 cwcli axi apps update frappe-one frappe          # runs 'bench update --reset'
 
 # Put ONE branch, tag, or commit under test in an app already in the bench -
-# the gap 'apps install' (a fresh clone) and 'apps update' (the tracked
+# the gap 'apps install' (bench acquisition and site installation) and 'apps update' (the tracked
 # upstream) leave. Add --reset to force a clean tree at the fetched ref.
 cwcli axi apps checkout frappe-one myapp feature/new-thing
 cwcli axi apps checkout frappe-one myapp feature/new-thing --reset
 
-# Fetch and install ONE app on ONE named site. --site is required (there is no
+# Ensure and install ONE app on ONE named site. --site is required (there is no
 # fan-out here), and an app already installed on that site is refused rather
-# than re-installed over its existing data.
+# than reinstalled over its existing data unless --if-not-present requests a skip.
 cwcli axi apps install frappe-one hrms --site erp.localhost
 cwcli axi apps install frappe-one https://github.com/me/myapp --site erp.localhost --branch develop
+# Idempotent: skip (do not reinstall) an app already on the site and exit 0, so a
+# CI step can trust the exit code. A real install failure still exits non-zero.
+cwcli axi apps install frappe-one hrms --site erp.localhost --if-not-present
 
 # Provision a new instance, bench, and site; the report prints as ONE TOON
 # document. BLOCKS for the full 10-20 minute run (like axi apps update) and
@@ -2238,9 +2251,9 @@ Use `cwcli open`'s banner for the host address and `cwcli status` for the HTTP o
 
 `cwcli axi apps list` is the read that answers what is *on* the bench `cwcli axi benches` names: the bench's available apps, and with `--installed`/`--site` which apps are installed on which site (only the app name, never the version column `bench list-apps` prints). A site whose read FAILED is reported as `null` and exits `1`, never as an empty list - "has no apps" and "could not tell" are different facts, and only one of them is safe to act on. Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start` (exit 2). **`cwcli axi apps uninstall` deliberately does not exist:** letting an agent drop the tables of a real site is a product decision that deserves its own evidence, not something settled as a side effect of moving code onto the logic core. Use the human `cwcli apps uninstall` (it has `--json` and honest exit codes) until that decision is taken. `cwcli axi apps install` was held under that same shared rationale and now exists, scoped to the half of it that rationale never covered - see below.
 
-`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (a fresh `bench get-app` clone) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
+`cwcli axi apps checkout <project> <app> <ref>` puts ONE named branch, tag, or commit under test in an app that is already in the bench - the gap `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app) leave. It emits the same per-step TOON report as the other `apps` verbs, one row per git step, and its exit code reads that report's `ok`, so a refused checkout exits `1` rather than looking like a success. **It existed before `apps install` did and while `apps uninstall` still does not, and that was deliberate rather than inconsistent:** their shared deferral names one threat, an agent destroying site data (uninstalling an app drops its tables), while a checkout runs `git fetch` then `git checkout -B` inside the app's source directory - no bench command, no site, no SQL. Its guards each protect against something named: there is no `--yes` (an agent must not start containers you deliberately stopped, so a stopped project is a usage error pointing at `cwcli start`); the app must already be a git checkout, so a typo'd name errors instead of silently doing nothing or implying an install; and a **dirty working tree is refused outright**, before anything is fetched, so your uncommitted edits are never carried across a branch switch. That refusal is deliberately **stronger than git's own**: git blocks only a checkout that would overwrite a modified file, which used to let a non-conflicting edit ride silently onto another ref. It matters here because these checkouts live in a shared dev instance, where the work carried across may not even be yours. Be precise about what counts as dirty: **anything `git status --porcelain` reports - staged changes, unstaged modifications to tracked files, and untracked files** - refuses. Untracked files count because a new module written but not yet added is uncommitted work, and it is exactly the case where the tool must not decide for you that the file is worthless; `.gitignore`d build residue is not reported by git at all, so it never blocks a checkout. `--reset` is the explicit opt-in through the refusal: it is the one destructive flag, is never implied, and is reported as its own row in the output; it discards tracked local edits in the container's copy of the app, which is what the post-merge step of an app delivery workflow wants. It does **not** delete untracked files - cwcli never runs `git clean` - so it lets the checkout proceed and leaves them in place. Private-repo fetches use the same credential bridge as `apps install`/`apps update`, so no token is stored in the container. One current limit: the report does not tell you which commit you landed on - that is deliberately left to a future read verb rather than bolted onto the shared mutation report.
 
-`cwcli axi apps install <project> <app-or-git-url> --site <site>` fetches an app into the bench and installs it on one named site.
+`cwcli axi apps install <project> <app-or-git-url> --site <site>` ensures the app is present on the bench, fetching it only when absent, and installs it on one named site.
 Installing an app is the first step of essentially any Frappe app work, and until this verb existed it was the one routine operation with no agent-surface form, so an agent had to drop to the raw human command for it.
 It is deliberately narrower than the human `cwcli apps install`, in exactly two ways, because the original deferral of `apps install`/`apps uninstall` named a real threat - an agent destroying site data - that covers `uninstall` unconditionally but covers `install` only in one case.
 Installing an app a site does **not** have creates that app's own tables and touches no other app's data; installing over an app the site **already** has re-runs that app's install hooks against rows that already exist.
@@ -2250,14 +2263,15 @@ So the verb ships scoped to the first case and refuses the second, rather than b
 The human verb installs on every site on the bench when you omit it; an unqualified fan-out is how an agent reaches a site nobody named, so on this surface the target is always explicit.
 That follows `cwcli axi run-tests`, which requires its site for the same reason: `install-app` runs the app's `after_install`, which is arbitrary Python from the repository being installed, against a live database, and when the effect is unbounded, defaulting the target is the wrong default.
 
-**An app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
+**By default, an app already installed on that site is refused**, before anything is fetched, as `app.already_installed` with exit `1`.
 The refusal names what to do instead: `cwcli axi apps checkout` to move the app to another ref, `cwcli axi apps update` to pull and migrate it, or the human `cwcli apps install` for a genuine reinstall.
 A site whose installed-app list cannot be *read* is refused too (`app.install_state_unknown`), because an unreadable state must never be treated as "nothing is installed there".
-There is deliberately **no flag to bypass this**: a `--force` here has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
-The escape hatch is the human verb, which is where a human confirms a reinstall.
+There is deliberately **no flag to bypass this by reinstalling**: a `--force` that re-ran the install hooks over existing data has no beneficiary in the workflow the verb serves (install, check out a ref, migrate, test), and its mere existence invites its use.
+The escape hatch for a genuine reinstall is the human verb, which is where a human confirms one.
 
-Note that the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success.
-The desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so exiting `0` would be asserting something it has not verified.
+By default the already-installed case is **not** reported as an idempotent exit-`0` no-op, even though the agent surface generally treats an already-satisfied desired state as a success: the desired state here is "installed from this branch", and cwcli cannot confirm the copy already on the site matches the `--branch` you asked for, so a silent exit `0` would be asserting something it has not verified.
+`--if-not-present` opts into the idempotent reading for a caller that just wants the app present: an app already installed on the site is then **skipped** (reported as a `skip-install` row, with its install hooks never rerun) and the verb exits `0`, so a CI step can trust the exit code instead of swallowing every failure with `|| true`; an app the site lacks is still installed, and a genuine install failure still exits non-zero.
+It is not a `--force`: there is still no way to reinstall over an app the site already has.
 Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start`.
 Private-repo fetches use the same credential bridge as `apps update`/`apps checkout`, so no token is stored in the container.
 On an already-serving bench, the operation resynchronises that bench - it restarts every supervised program running the bench's Python (`web`, `schedule`, workers) and reports a `restart-processes` row.

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/pyproject.toml

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

caffeinated_whale_cli-2.3.0/src/caffeinated_whale_cli/__init__.py

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

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/commands/apps.py

@@ -53,6 +53,9 @@ _ANNOUNCE = {
     "install-app": lambda app_name, site: (
         f"[bold cyan]Installing[/bold cyan] {app_name} on [magenta]{site}[/magenta]..."
     ),
+    "skip-install": lambda app_name, site: (
+        f"[dim]Skipping[/dim] {app_name} on [magenta]{site}[/magenta] (already installed)..."
+    ),
     "uninstall-app": lambda app_name, site: (
         f"[bold cyan]Uninstalling[/bold cyan] {app_name} from [magenta]{site}[/magenta]..."
     ),
@@ -267,7 +270,9 @@ def install_apps(
     project_name: str = typer.Argument(
         ..., help="The Docker Compose project name.", autocompletion=complete_project_names
     ),
-    apps: list[str] = typer.Argument(..., help="App name(s) or git URL(s) to fetch and install."),
+    apps: list[str] = typer.Argument(
+        ..., help="App name(s) or git URL(s) to ensure on the bench and install."
+    ),
     bench: str = typer.Option(
         None, "--bench", help="Which bench to target: its numeric index or label."
     ),
@@ -283,16 +288,28 @@ def install_apps(
         "--fetch-only",
         help="Fetch the app(s) into the bench without installing on any site.",
     ),
+    if_not_present: bool = typer.Option(
+        False,
+        "--if-not-present",
+        help=(
+            "Idempotent: skip (do not re-install) an app already installed on a "
+            "target site instead of re-running its install hooks. A skipped app is "
+            "reported and the command still exits 0."
+        ),
+    ),
     json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
     yes: bool = typer.Option(
         False, "--yes", "-y", help="Auto-start stopped containers without prompting."
     ),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
 ):
-    """Fetch (bench get-app) and install app(s) on the target site(s).
+    """Ensure app(s) are present on the bench, then install them on the target site(s).
 
-    Each app is a known app name OR a git URL (passed straight to bench get-app).
+    Apps absent from apps/ are fetched with bench get-app; apps already present skip
+    that fetch. Each app is a known app name OR a git URL.
     Multi-site by default: with no --site the app is installed on every site.
+    With --if-not-present an app already installed on a target site is skipped rather
+    than re-installed, so "ensure this app is installed" is a single idempotent call.
     """
     ensure_containers_running(project_name, require_running=True, verbose=verbose, auto_start=yes)
     resolved = _resolve_bench(project_name, bench, bench_path, verbose)
@@ -305,6 +322,7 @@ def install_apps(
             sites=sites,
             branch=branch,
             fetch_only=fetch_only,
+            if_not_present=if_not_present,
             on_event=_make_renderer(json_output=json_output, verbose=verbose),
         )
     except CwcliError as e:
@@ -322,13 +340,15 @@ def install_apps(
         _refresh_cache(project_name, verbose)
 
     # The banner must match what actually happened: only claim "installed" when an
-    # install-app step ran (not for --fetch-only or a bench with no sites).
-    installed = any(r.action == "install-app" for r in report.results)
-    _report_and_exit(
-        report,
-        json_output,
-        success_msg="App(s) installed." if installed else "App(s) fetched.",
-    )
+    # install-app step ran (not for --fetch-only, a bench with no sites, or an
+    # --if-not-present run that only skipped already-installed apps).
+    if any(r.action == "install-app" for r in report.results):
+        success_msg = "App(s) installed."
+    elif any(r.action == "skip-install" for r in report.results):
+        success_msg = "App(s) already installed; nothing to do."
+    else:
+        success_msg = "App(s) fetched."
+    _report_and_exit(report, json_output, success_msg=success_msg)
 
 
 # ------------------------------------------------------------------------ uninstall
@@ -450,7 +470,7 @@ def checkout_app(
 ):
     """Fetch and check out a branch/ref into an app already installed in the instance.
 
-    Unlike 'apps install' (a fresh get-app clone) and 'apps update' (the tracked
+    Unlike 'apps install' (bench acquisition and site installation) and 'apps update' (the tracked
     upstream on every app), this puts a specific feature branch, tag, or commit
     under test in the EXISTING apps/<app> checkout, authenticated for private repos
     through the same credential bridge as install/update. Use --reset to force a

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/commands/axi.py

@@ -1563,7 +1563,7 @@ def axi_apps_checkout(
 ) -> None:
     """Fetch and check out a ref into an app already in the bench; emit the report as TOON.
 
-    The gap `apps install` (a fresh get-app clone) and `apps update` (the tracked
+    The gap `apps install` (bench acquisition and site installation) and `apps update` (the tracked
     upstream on every app) leave: putting ONE named branch, tag, or commit under
     test in the EXISTING apps/<app> checkout. There is no `axi run`, so this is
     the only agent-surface route to that step.
@@ -1665,15 +1665,27 @@ def axi_apps_install(
     # Named `app_name` because `app` is this module's Typer instance; the metavar
     # keeps the agent-visible usage line matching the human `cwcli apps install`.
     app_name: str = typer.Argument(
-        ..., metavar="APP", help="App name or git URL to fetch and install."
+        ..., metavar="APP", help="App name or git URL to ensure on the bench and install."
     ),
     site: str = typer.Option(
         ..., "--site", help="The single site to install on. Required: there is no fan-out here."
     ),
     bench: str = typer.Option(None, "--bench", help="Which bench: numeric index or label."),
     branch: str = typer.Option(None, "--branch", help="Git branch to fetch (passed to get-app)."),
+    if_not_present: bool = typer.Option(
+        False,
+        "--if-not-present",
+        help=(
+            "Idempotent: if the app is already installed on the site, skip it and "
+            "exit 0 instead of refusing. Does NOT re-install or re-run install "
+            "hooks - it only reports the app as already present."
+        ),
+    ),
 ) -> None:
-    """Fetch and install ONE app on ONE named site; emit the report as TOON.
+    """Ensure and install ONE app on ONE named site; emit the report as TOON.
+
+    An app absent from apps/ is fetched with bench get-app; an app already present
+    skips that fetch and proceeds to the site installation.
 
     Installing an app is the first step of essentially any Frappe app work, and
     without this verb it was the one routine operation with no agent-surface form,
@@ -1711,11 +1723,21 @@ def axi_apps_install(
     `axi migrate`'s absent `--skip-maintenance`. The escape hatch is the human verb,
     which is where a human confirms a reinstall.
 
-    The already-installed case is deliberately NOT reported as an idempotent exit-0
-    no-op, against the general AXI rule that an already-satisfied desired state is a
-    success. The desired state here is "installed FROM this branch", and cwcli
-    cannot confirm the copy already on the site matches the requested `--branch`, so
-    exit 0 would assert something it has not verified.
+    The already-installed case is, BY DEFAULT, deliberately NOT reported as an
+    idempotent exit-0 no-op, against the general AXI rule that an already-satisfied
+    desired state is a success. The desired state here is "installed FROM this
+    branch", and cwcli cannot confirm the copy already on the site matches the
+    requested `--branch`, so a silent exit 0 would assert something it has not
+    verified.
+
+    `--if-not-present` opts INTO the idempotent reading for a caller that just wants
+    the app present: an app already installed on the site is then SKIPPED (reported
+    as an `ok` `skip-install` row, its install hooks NOT re-run) and the verb exits
+    0. It is not a bypass of the safety the refusal guards - it never re-installs
+    over existing data - it is the honest "ensure installed" answer, so a CI step can
+    trust the exit code (a genuine install failure still exits 1) instead of
+    swallowing every failure with `|| true`. It is NOT a `--force`: there is still
+    no way to make the verb re-run install hooks over an app the site already has.
 
     NO --yes and no auto-start: a stopped project is a usage error naming
     `cwcli start`, as every bench-scoped axi verb already does. The private-repo
@@ -1731,7 +1753,10 @@ def axi_apps_install(
             sites=[site],
             branch=branch,
             auto_start=False,
-            require_absent=True,
+            # --if-not-present is the opt-in idempotent path; without it the
+            # already-installed refusal (require_absent) stays the default.
+            require_absent=not if_not_present,
+            if_not_present=if_not_present,
             on_event=_checkout_narrate,
         )
     except CwcliError as error:

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/apps.py

@@ -74,7 +74,7 @@ class AppResult:
 
     app: str
     site: str | None  # None for the bench-wide get-app step
-    action: str  # "get-app" | "install-app" | "uninstall-app" | "restart-processes" | a git step
+    action: str  # "get-app" | "install-app" | "skip-install" | "uninstall-app" | "restart-processes" | a git step
     ok: bool
 
 
@@ -535,6 +535,41 @@ def _refuse_if_installed(
                 )
 
 
+def _read_installed_by_site(
+    frappe_container,
+    path: str,
+    sites: list[str],
+    *,
+    emit: OnEvent,
+) -> dict[str, set[str]]:
+    """Each target site's installed-apps set. FAILS CLOSED on an unreadable site.
+
+    Backs the idempotent ``if_not_present`` install path. A site whose ``list-apps``
+    read fails cannot be confirmed clean, so it refuses (PRECONDITION) rather than
+    proceeding on an unknown - the same fail-honest rule ``_refuse_if_installed``
+    applies, so "could not read the site" never degrades to "the app is not there"
+    and gets silently (re)installed.
+    """
+    installed: dict[str, set[str]] = {}
+    for site in sites:
+        command, ok, site_apps = _installed_apps(frappe_container, path, site)
+        emit(AppsCommand(command=command))
+        if not ok:
+            raise CwcliError(
+                ErrorKind.PRECONDITION,
+                "app.install_state_unknown",
+                f"Could not read the installed apps on site '{site}' (it may not exist "
+                "on this bench), so it cannot be confirmed whether the app is already "
+                "installed there.",
+                hint=(
+                    f"Check the site exists and is readable: 'cwcli axi apps list "
+                    f"<project> --site {site}'."
+                ),
+            )
+        installed[site] = set(site_apps)
+    return installed
+
+
 def install_apps(
     project_name: str,
     apps: list[str],
@@ -546,10 +581,17 @@ def install_apps(
     fetch_only: bool = False,
     auto_start: bool = False,
     require_absent: bool = False,
+    if_not_present: bool = False,
     on_event: OnEvent | None = None,
 ) -> Result[AppsReport]:
     """Fetch (``bench get-app``) and install app(s) on the target site(s).
 
+    The fetch is idempotent on bench-presence: an app already present under the
+    bench's ``apps/`` (e.g. a bench built from a pre-warmed base that carries it)
+    would make ``bench get-app`` fail on the existing directory, so it is skipped
+    and the install-app phase proceeds. This is distinct from ``require_absent``
+    below, which is a per-SITE guard, not a per-bench one.
+
     ``require_absent`` refuses, BEFORE fetching anything, if an app is already
     installed on a target site. It defaults off so the human verb is unchanged, and
     the rule lives here rather than in a frontend so ``axi`` and any future GUI share
@@ -560,6 +602,18 @@ def install_apps(
     The check FAILS CLOSED: a site whose ``list-apps`` read fails cannot be confirmed
     clean, so it refuses rather than proceeding on an unknown (``core.where``'s
     fail-honest rule - an unreadable state must never degrade to "nothing is there").
+
+    ``if_not_present`` is the idempotent reading of "install": an app already
+    installed on a target site is SKIPPED (reported as an ``ok`` ``skip-install``
+    result, never re-installed) instead of refused, so a caller that just wants the
+    app present succeeds (exit 0) and can still trust the exit code for a genuine
+    failure. It is the opt-in alternative to ``require_absent``'s refusal: the two
+    answer the same "already installed on the site" case oppositely, so a frontend
+    passes at most one. It does NOT re-run install hooks for a skipped app (that is
+    exactly what the refusal guarded against), and it FAILS CLOSED on an unreadable
+    site the same way - "could not read" is never treated as "not installed". An app
+    absent from a given site still installs there normally, so a multi-site run
+    skips only the sites that already have it.
     """
     emit: OnEvent = on_event or _noop
 
@@ -580,14 +634,29 @@ def install_apps(
     # so every git-URL fetch is wrapped and torn down; see core.credbridge.
     with credbridge.credential_bridge(frappe_container, path):
         for target in apps:
+            app_name = derive_app_name(target)
+            command, before_apps = _available_apps(frappe_container, path)
+            before = set(before_apps)
+
+            # Idempotent fetch: if the app is already on the BENCH (its apps/ dir
+            # exists), `bench get-app` fails on the existing directory, which used to
+            # fail the whole install of an app a pre-warmed base already carries. Skip
+            # the fetch and install what is present. This is bench-presence, DISTINCT
+            # from the per-site installed-apps guard (`_installed_apps` /
+            # `_refuse_if_installed`): that gates a double SITE-install, this gates the
+            # bench FETCH. The install-app phase below is unchanged either way.
+            if app_name in before:
+                emit(AppsCommand(command=command))
+                results.append(AppResult(app=app_name, site=None, action="get-app", ok=True))
+                fetched.append((target, app_name))
+                continue
+
             get_cmd = f"bench get-app {branch_arg}{shlex.quote(target)}"
 
-            # Announce BEFORE the apps/ read, so --verbose stderr keeps its historical
-            # order: "Fetching x..." then the read's echo then get-app's own echo.
+            # Announce BEFORE the apps/ read echo, so --verbose stderr keeps its
+            # historical order: "Fetching x..." then the read's echo then get-app's own.
             emit(AppsAnnounce(phase="get-app", app=target))
-            command, before_apps = _available_apps(frappe_container, path)
             emit(AppsCommand(command=command))
-            before = set(before_apps)
 
             code = _run_step(
                 frappe_container, get_cmd, path, emit=emit, phase="get-app", app=target
@@ -601,7 +670,7 @@ def install_apps(
             emit(AppsCommand(command=command))
 
             new_dirs = set(after_apps) - before
-            app_name = new_dirs.pop() if len(new_dirs) == 1 else derive_app_name(target)
+            app_name = new_dirs.pop() if len(new_dirs) == 1 else app_name
             fetched.append((target, app_name))
 
     if not fetch_only:
@@ -613,8 +682,25 @@ def install_apps(
                     "no sites on the bench to install on; app(s) fetched only.",
                 )
             )
+        # Idempotent path: read each target site's installed set ONCE (fail-closed),
+        # so an app already installed on a site is skipped below instead of having
+        # its install hooks re-run against that site's existing data.
+        installed_by_site: dict[str, set[str]] = (
+            _read_installed_by_site(frappe_container, path, target_sites, emit=emit)
+            if if_not_present and target_sites
+            else {}
+        )
         for _target, app_name in fetched:
             for site in target_sites:
+                if if_not_present and app_name in installed_by_site.get(site, set()):
+                    # Already present on this site: report it and move on. NOT an
+                    # install-app step, so it drives no resync (nothing changed) and
+                    # never re-runs the app's install hooks.
+                    emit(AppsAnnounce(phase="skip-install", app=app_name, site=site))
+                    results.append(
+                        AppResult(app=app_name, site=site, action="skip-install", ok=True)
+                    )
+                    continue
                 install_cmd = (
                     f"bench --site {shlex.quote(site)} install-app {shlex.quote(app_name)}"
                 )
@@ -631,6 +717,8 @@ def install_apps(
                 results.append(
                     AppResult(app=app_name, site=site, action="install-app", ok=code == 0)
                 )
+                if if_not_present and code == 0:
+                    installed_by_site.setdefault(site, set()).add(app_name)
 
     # Only the sites an install actually landed on: a site whose install-app failed
     # was not changed, so it has nothing to re-verify and must not fail the restart.
@@ -753,8 +841,9 @@ def checkout_app(
 ) -> Result[AppsReport]:
     """Fetch and check out an arbitrary ``ref`` into an app that ALREADY EXISTS.
 
-    The gap ``install``/``update`` leave: ``install`` is ``bench get-app`` (a FRESH
-    clone of a new app) and ``update`` is ``bench update --pull`` (the TRACKED
+    The gap ``install``/``update`` leave: ``install`` acquires an app with ``bench
+    get-app`` when it is absent and installs it on sites, while ``update`` uses
+    ``bench update --pull`` against the TRACKED
     upstream on every app). Neither fetches one named branch/tag/commit into an
     existing ``apps/<app>`` checkout, which is exactly what putting a feature branch
     under test in the instance the app lives in needs.

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/docker.py

@@ -22,7 +22,7 @@ import subprocess
 import docker
 from docker.errors import DockerException
 
-from .errors import CwcliError, ErrorKind
+from .errors import DOCKER_UNREACHABLE_HINT, CwcliError, ErrorKind
 
 _COMPOSE_INSTALL_HINT = (
     "Install the Docker Compose v2 plugin: it ships with Docker Desktop, or "
@@ -332,6 +332,7 @@ def get_frappe_container(project_name: str):
             ErrorKind.DOCKER,
             "docker.unreachable",
             "Could not connect to Docker daemon.",
+            hint=DOCKER_UNREACHABLE_HINT,
         )
 
     if not containers:

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/errors.py

@@ -28,6 +28,13 @@ class ErrorKind(Enum):
     INTERNAL = "internal"  # unexpected
 
 
+# The one next-step string for every "could not connect to the Docker daemon"
+# CwcliError, so every frontend (axi included) renders the same actionable
+# `help:` line instead of a bare error with no remedy. Mirrors the fix string
+# `core/doctor.py`'s own daemon check already carries.
+DOCKER_UNREACHABLE_HINT = "start Docker (Docker Desktop, or `systemctl start docker`)"
+
+
 class CwcliError(Exception):
     """A hard failure the core cannot recover from.
 

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/list.py

@@ -15,7 +15,7 @@ import docker
 from docker.errors import DockerException
 
 from .envelope import Result, Status
-from .errors import CwcliError, ErrorKind
+from .errors import DOCKER_UNREACHABLE_HINT, CwcliError, ErrorKind
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
@@ -64,6 +64,7 @@ def list_instances(*, service_name: str = "frappe") -> Result[list[InstanceDTO]]
             ErrorKind.DOCKER,
             "docker.unreachable",
             "Could not connect to Docker daemon.",
+            hint=DOCKER_UNREACHABLE_HINT,
             detail={"output": str(e)},
         ) from e
 

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/restart.py

@@ -23,7 +23,7 @@ from docker.errors import APIError, NotFound
 from . import resolvers, supervision
 from .docker import get_project_containers
 from .envelope import Choice, Message, Result, Status
-from .errors import CwcliError, ErrorKind
+from .errors import DOCKER_UNREACHABLE_HINT, CwcliError, ErrorKind
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
@@ -52,7 +52,10 @@ def restart_process(
     containers = get_project_containers(project_name)
     if containers is None:
         raise CwcliError(
-            ErrorKind.DOCKER, "docker.unreachable", "Could not connect to Docker daemon."
+            ErrorKind.DOCKER,
+            "docker.unreachable",
+            "Could not connect to Docker daemon.",
+            hint=DOCKER_UNREACHABLE_HINT,
         )
     if not containers:
         raise CwcliError(

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/rm.py

@@ -50,7 +50,7 @@ from ..utils import bench_sites, db_utils
 from ..utils.config_utils import PROJECTS_DIR, cwcli_home
 from .docker import get_project_containers, get_project_networks, get_project_volumes
 from .envelope import Result, Status
-from .errors import CwcliError, ErrorKind
+from .errors import DOCKER_UNREACHABLE_HINT, CwcliError, ErrorKind
 from .resolvers import DEFAULT_BENCH_PATH
 
 # Marker in a Frappe backup filename that identifies the database dump - the one
@@ -839,6 +839,7 @@ def remove(
             ErrorKind.DOCKER,
             "docker.unreachable",
             f"Could not connect to Docker to inspect '{project_name}'.",
+            hint=DOCKER_UNREACHABLE_HINT,
         )
 
     project_dir = PROJECTS_DIR / project_name

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/start.py

@@ -28,7 +28,7 @@ from dataclasses import dataclass
 from . import resolvers, supervision
 from .docker import align_container_user_to_host, get_project_containers
 from .envelope import Message, Result, Status
-from .errors import CwcliError, ErrorKind
+from .errors import DOCKER_UNREACHABLE_HINT, CwcliError, ErrorKind
 
 # Shell metacharacters rejected in the bench path (it is interpolated into the
 # launch shell command; command-injection guard, mirrors core.backup).
@@ -93,7 +93,10 @@ def start(
     containers = get_project_containers(project_name)
     if containers is None:
         raise CwcliError(
-            ErrorKind.DOCKER, "docker.unreachable", "Could not connect to Docker daemon."
+            ErrorKind.DOCKER,
+            "docker.unreachable",
+            "Could not connect to Docker daemon.",
+            hint=DOCKER_UNREACHABLE_HINT,
         )
     if not containers:
         raise CwcliError(

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/status.py

@@ -102,7 +102,7 @@ from docker.errors import APIError, NotFound
 from . import resolvers, supervision
 from .docker import get_project_containers
 from .envelope import Message, Result, Status
-from .errors import CwcliError, ErrorKind
+from .errors import DOCKER_UNREACHABLE_HINT, CwcliError, ErrorKind
 from .supervision import ProcessHealth
 
 OFFLINE = "offline"
@@ -250,7 +250,10 @@ def status(
     containers = get_project_containers(project_name)
     if containers is None:
         raise CwcliError(
-            ErrorKind.DOCKER, "docker.unreachable", "Could not connect to Docker daemon."
+            ErrorKind.DOCKER,
+            "docker.unreachable",
+            "Could not connect to Docker daemon.",
+            hint=DOCKER_UNREACHABLE_HINT,
         )
     # A truly-nonexistent project (typo / never created) has NO containers with the
     # label at all - distinct from a real-but-stopped project, which has a non-empty

{caffeinated_whale_cli-2.2.0 → caffeinated_whale_cli-2.3.0}/src/caffeinated_whale_cli/core/stop.py

@@ -32,7 +32,7 @@ from docker.errors import APIError, NotFound
 from . import resolvers, supervision
 from .docker import get_project_containers
 from .envelope import Message, Result, Status
-from .errors import CwcliError, ErrorKind
+from .errors import DOCKER_UNREACHABLE_HINT, CwcliError, ErrorKind
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
@@ -65,6 +65,7 @@ def stop(project_name: str) -> Result[StopOutcome]:
             ErrorKind.DOCKER,
             "docker.unreachable",
             "Could not connect to Docker daemon.",
+            hint=DOCKER_UNREACHABLE_HINT,
         )
 
     if not containers:
@@ -131,7 +132,10 @@ def stop_bench(
     containers = get_project_containers(project_name)
     if containers is None:
         raise CwcliError(
-            ErrorKind.DOCKER, "docker.unreachable", "Could not connect to Docker daemon."
+            ErrorKind.DOCKER,
+            "docker.unreachable",
+            "Could not connect to Docker daemon.",
+            hint=DOCKER_UNREACHABLE_HINT,
         )
     if not containers:
         raise CwcliError(

caffeinated_whale_cli-2.2.0/src/caffeinated_whale_cli/__init__.py

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