fix(bash): zbackup — real pg_dump error reporting + require an explicit target (all) (#9)

* fix(bash): zbackup reports the real pg_dump failure, not "No DATABASE_URL"

local_pg_dump returned 1 for four different cases (no .env, no
DATABASE_URL, unparseable URL, and an actual dump failure), and the
caller printed "No local DATABASE_URL - source-only backup" for every
one. So a project that HAS a DATABASE_URL whose dump failed was
mislabeled as having none — the two messages contradicted each other.

- Distinguish the cases with exit codes: 0 dumped, 1 attempted-but-failed,
  2 no local database. The caller now prints the right line for each.
- Stop swallowing pg_dump's stderr (2>/dev/null); on failure, surface the
  actual error (version mismatch, unreachable host, auth) plus the
  host:port/db it tried, so failures are diagnosable.

* fix(bash): zbackup treats a not-running local DB as a calm skip

Fold all pg_dump messaging into local_pg_dump (caller just captures
success) and special-case an unreachable database. "connection refused"
/ "could not connect" / DNS / timeout now print a quiet
"Local database not running at host:port - source-only backup." instead
of a red multi-line error - a stopped dev DB is a normal state. Real
failures (version mismatch, auth, missing db) still print the full
pg_dump error so they're diagnosable.

* fix(bash): zbackup/zbackup_and_sync require an explicit target, matching PowerShell

Bare `zbackup` quietly backed up every project - inconsistent with the
PowerShell version (and with zdeploy), and an easy way to kick off a
huge unintended backup. Now a bare invocation prints usage and lists the
projects; `all` does what bare used to (every project + the scripts
folder). Same for `zbackup_and_sync`, and setup_backup_schedule's cron
line now passes `all` so the scheduled job still backs everything up.

bash/setup_backup_schedule

@@ -30,7 +30,7 @@ if ! [[ "$hh" =~ ^[0-9]{1,2}$ && "$mm" =~ ^[0-9]{2}$ ]] || [ "$hh" -gt 23 ] || [
   err "Invalid --time '$at_time' (expected HH:MM, 24h)"; exit 1
 fi
 
-cron_line="${mm#0} ${hh#0} * * * $_HERE/zbackup_and_sync >> \$HOME/zbackup_and_sync.log 2>&1"
+cron_line="${mm#0} ${hh#0} * * * $_HERE/zbackup_and_sync all >> \$HOME/zbackup_and_sync.log 2>&1"
 
 info "=== Backup schedule (cron) ==="
 dim  "Daily at $at_time:"

bash/zbackup

@@ -7,8 +7,8 @@
 # project's .env has a DATABASE_URL) into the backups folder.
 #
 # Usage:
-#   zbackup                              # every project in zconfig.json + this scripts folder
 #   zbackup <project> [<project> ...]
+#   zbackup all                          # every project in zconfig.json + this scripts folder
 #   zbackup scripts                      # just this scripts folder ('scripts' is a reserved word)
 #   zbackup pyapp --tag "pre-migration"
 #
@@ -30,8 +30,18 @@ while [ $# -gt 0 ]; do
 done
 
 BACKUP_ROOT="$(z_path "$(zq '.paths.backupsLocal')")"
-include_scripts=0
+
+# Require an explicit target: bare invocation shows usage instead of quietly
+# backing up everything - 'all' is explicit, matching zdeploy.
 if [ "${#projects[@]}" -eq 0 ]; then
+  printf '\n'; warn "Usage: zbackup <project> [<project> ...] | all | scripts  [--tag \"label\"]"
+  dim "  Projects in zconfig.json: $(zproj_csv)"
+  dim "  'all' backs up every project plus this scripts folder; 'scripts' just this folder."
+  exit 1
+fi
+
+include_scripts=0
+if printf '%s\n' "${projects[@]}" | grep -qx 'all'; then
   projects=(); while IFS= read -r _zl || [ -n "$_zl" ]; do projects+=("$_zl"); done < <(zproj_keys)
   include_scripts=1
 else
@@ -46,24 +56,34 @@ ts()         { date +%Y%m%d-%H%M%S; }
 tag_suffix() { [ -n "$tag" ] && printf '_%s' "$(printf '%s' "$tag" | tr -s '[:space:]' '_')"; }
 
 # Dump the project's Postgres database if its .env declares a DATABASE_URL.
-# Checks <root>/.env, then <root>/backend/.env. Returns 0 and writes $2 on success.
+# Checks <root>/.env, then <root>/backend/.env. Prints its own status line for
+# every outcome; returns 0 (dumped, $2 written) or 1 (nothing dumped).
+# A not-running database (connection refused) is a calm, expected skip; a real
+# failure (version mismatch, auth, missing db) prints the loud pg_dump error.
 local_pg_dump() {  # <root> <out_path>
-  local root="$1" out="$2" env_file db_url
+  local root="$1" out="$2" env_file db_url err_out rc
   env_file="$root/.env"; [ -f "$env_file" ] || env_file="$root/backend/.env"
-  [ -f "$env_file" ] || return 1
+  if [ ! -f "$env_file" ]; then dim "    No local DATABASE_URL - source-only backup."; return 1; fi
   db_url="$(grep -m1 '^DATABASE_URL=' "$env_file" | cut -d= -f2- | tr -d '[:space:]')"
-  [ -n "$db_url" ] || return 1
+  if [ -z "$db_url" ]; then dim "    No local DATABASE_URL - source-only backup."; return 1; fi
   db_url="$(printf '%s' "$db_url" | sed -E 's|^postgresql\+[^:]+://|postgresql://|')"
   if [[ "$db_url" =~ ^postgresql://([^:]+):([^@]+)@([^:]+):([0-9]+)/([^?]+) ]]; then
     local user="${BASH_REMATCH[1]}" pass="${BASH_REMATCH[2]}" host="${BASH_REMATCH[3]}"
     local port="${BASH_REMATCH[4]}" db="${BASH_REMATCH[5]}"
     command -v pg_dump >/dev/null 2>&1 || { err '    pg_dump not installed - skipping PG backup'; return 1; }
-    if PGPASSWORD="$(z_urldecode "$pass")" pg_dump -h "$host" -p "$port" -U "$user" -d "$db" -F p -f "$out" 2>/dev/null \
-       && [ -f "$out" ]; then
+    err_out="$(PGPASSWORD="$(z_urldecode "$pass")" pg_dump -h "$host" -p "$port" -U "$user" -d "$db" -F p -f "$out" 2>&1)"; rc=$?
+    if [ "$rc" -eq 0 ] && [ -f "$out" ]; then
       ok "    PostgreSQL dump: $(awk -v b="$(wc -c < "$out")" 'BEGIN{printf "%.1f", b/1024}') KB"
       return 0
     fi
-    err "    pg_dump failed"
+    # Not reachable (usually just not running locally) is expected - stay calm.
+    if printf '%s' "$err_out" | grep -qiE 'connection refused|could not connect|no route to host|could not translate host|timeout expired'; then
+      dim "    Local database not running at $host:$port - source-only backup."
+      return 1
+    fi
+    # A real failure (version mismatch, auth, missing db) - show the reason.
+    err "    pg_dump failed ($host:$port/$db as $user):"
+    printf '%s\n' "$err_out" | grep -v '^[[:space:]]*$' | sed 's/^/      /' >&2
     return 1
   fi
   err '    Could not parse DATABASE_URL - skipping PG backup'
@@ -87,8 +107,7 @@ backup_project() {  # <key>
   dump_dir="$(mktemp -d "${TMPDIR:-/tmp}/zbackup_${key}_XXXXXX")"
   db_dump="$dump_dir/database_pg.sql"
   warn "  [1/3] Checking for a local database to dump..."
-  if local_pg_dump "$root" "$db_dump"; then extra="$db_dump"
-  else dim "    No local DATABASE_URL - source-only backup."; fi
+  if local_pg_dump "$root" "$db_dump"; then extra="$db_dump"; fi
 
   warn "  [2/3] Archiving source..."
   local excl=()

bash/zbackup_and_sync

@@ -6,11 +6,11 @@
 # zbackup_and_sync — run backups, then sync the backups folder offsite.
 #
 # Usage:
-#   zbackup_and_sync                          # backup everything + sync
 #   zbackup_and_sync <project> [<project> ...]
+#   zbackup_and_sync all                      # backup everything + sync
 #
 # Cron example (see setup_backup_schedule):
-#   0 2 * * *  /path/to/zscripts/bash/zbackup_and_sync >> ~/zbackup.log 2>&1
+#   0 2 * * *  /path/to/zscripts/bash/zbackup_and_sync all >> ~/zbackup.log 2>&1
 
 set -uo pipefail
 _HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -18,6 +18,14 @@ source "$_HERE/zhelpers.sh"
 z_track_start "$@"
 z_need_config
 
+# Require an explicit target (matching zbackup/zdeploy); 'all' backs up everything.
+if [ $# -eq 0 ]; then
+  printf '\n'; warn "Usage: zbackup_and_sync <project> [<project> ...] | all"
+  dim "  Projects in zconfig.json: $(zproj_csv)"
+  dim "  'all' backs up every project plus the scripts folder, then syncs offsite."
+  exit 1
+fi
+
 printf '\n'
 info "============================================"
 info "   Backup & Sync - $(date '+%Y-%m-%d %H:%M:%S')"