@supacloud/admin 0.19.0 → 0.20.1

package/README.md

@@ -101,6 +101,9 @@ npx @supacloud/admin ssh ping
 npx @supacloud/admin ssh versions
 npx @supacloud/admin ssh diagnose
 npx @supacloud/admin ssh upgrade_status --transaction_id 11111111-1111-4111-8111-111111111111
+npx @supacloud/admin ssh backup_cleanup_plan --before 2026-09-03 --keep_latest 2
+npx @supacloud/admin ssh backup_cleanup_apply --before 2026-09-03 --keep_latest 2 \
+  --plan_sha256 <plan_sha256>
 npx @supacloud/admin project create --name my-app --domain example.com \
   --env_file /secure/path/.env.project-credentials.test --environment test
 npx @supacloud/admin project list
@@ -118,6 +121,29 @@ plus an explicit `tree_sha256` digest. An `unknown` component remains a valid
 inventory result, while any `error` component makes the CLI exit non-zero after
 printing the structured report.
 
+## Managed rollback backup cleanup
+
+Use the two-step SSH cleanup flow when old platform rollback directories consume
+disk space:
+
+```bash
+npx @supacloud/admin ssh backup_cleanup_plan \
+  --before 2026-09-03 --keep_latest 2
+# review plan_sha256 and the candidate list
+npx @supacloud/admin ssh backup_cleanup_apply \
+  --before 2026-09-03 --keep_latest 2 \
+  --plan_sha256 <plan_sha256>
+```
+
+The plan is read-only. Apply requires the exact digest from the plan and
+recomputes it immediately before deletion. Only completed `committed` or
+`rolled_back` transaction directories directly under
+`/opt/supacloud/backups` are eligible; the newest `keep_latest` directories
+are retained, and candidates must be older than `before`. Symlinks,
+mountpoints, malformed transaction names, missing status files, and every path
+outside the managed backup root are refused. Production runs also require the
+normal `--confirm-production host:<ssh-host>[:port]` confirmation.
+
 ## Verified platform upgrades
 
 Use one explicit Admin command to upgrade Management, Web Console, and an

package/dist/index.js

@@ -25886,12 +25886,13 @@ var ACTION_POLICY = {
       "exec",
       "troubleshoot",
       "container_logs",
+      "backup_cleanup_plan",
       "tenant_list",
       "tenant_inspect",
       "tenant_diagnose",
       "upgrade_status"
     ],
-    write: ["setup", "install", "upgrade", "tenant_migrate"]
+    write: ["setup", "install", "upgrade", "backup_cleanup_apply", "tenant_migrate"]
   }
 };
 var DYNAMIC_ACTION_FIELDS = {
@@ -25902,7 +25903,8 @@ var REFLESS_WRITE_ACTIONS = new Set([
   "project.create",
   "ssh.setup",
   "ssh.install",
-  "ssh.upgrade"
+  "ssh.upgrade",
+  "ssh.backup_cleanup_apply"
 ]);
 var SSH_PROJECT_REF_ACTIONS = new Set(["tenant_manage", "tenant_inspect", "tenant_diagnose"]);
 var PLATFORM_PROJECT_REF_ACTIONS = new Set([
@@ -28506,6 +28508,9 @@ var WEB_TREE_AFTER_LABEL = "SUPACLOUD_WEB_TREE_SHA256_AFTER=";
 var WEB_MARKER_AFTER_LABEL = "SUPACLOUD_WEB_MARKER_BASE64_AFTER=";
 var WEB_ROOT_REAL_AFTER_LABEL = "SUPACLOUD_WEB_ROOT_REAL_AFTER=";
 var WEB_ROOT_ID_AFTER_LABEL = "SUPACLOUD_WEB_ROOT_ID_AFTER=";
+var BACKUP_CLEANUP_ROOT = "/opt/supacloud/backups";
+var BACKUP_CLEANUP_PLAN_SHA256 = /^[a-f0-9]{64}$/;
+var BACKUP_CLEANUP_DATE = /^\d{4}-\d{2}-\d{2}$/;
 function fixedBinaryProbeCommand(executablePath, versionArgument) {
   const executable = quoteEnvValue(executablePath);
   return [
@@ -28617,6 +28622,66 @@ function assertSafeReleaseTag(value) {
   }
   return value;
 }
+function assertBackupCleanupDate(value) {
+  if (!BACKUP_CLEANUP_DATE.test(value))
+    throw new Error("before must be an ISO date (YYYY-MM-DD)");
+  const parsed = Date.parse(`${value}T00:00:00Z`);
+  if (!Number.isFinite(parsed) || new Date(parsed).toISOString().slice(0, 10) !== value) {
+    throw new Error("before must be a valid ISO date (YYYY-MM-DD)");
+  }
+  return value;
+}
+function assertBackupCleanupKeepLatest(value) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 100) {
+    throw new Error("keep_latest must be an integer between 1 and 100");
+  }
+  return value;
+}
+function assertBackupCleanupPlanSha256(value) {
+  if (!BACKUP_CLEANUP_PLAN_SHA256.test(value))
+    throw new Error("plan_sha256 must be a lowercase SHA-256 digest");
+  return value;
+}
+function backupCleanupCommand(args) {
+  const before = quoteEnvValue(args.before);
+  const keepLatest = String(args.keepLatest);
+  const expectedPlan = args.planSha256 ? quoteEnvValue(args.planSha256) : "";
+  const manifest = [
+    "set -euo pipefail",
+    "export TMPDIR=/dev/shm",
+    ...args.apply ? [buildUpgradeLockScript(SUPACLOUD_UPGRADE_LOCK_PATH)] : [],
+    `ROOT=${quoteEnvValue(BACKUP_CLEANUP_ROOT)}`,
+    `BEFORE=${before}`,
+    `KEEP_LATEST=${keepLatest}`,
+    "collect() {",
+    `  find -P "$ROOT" -mindepth 1 -maxdepth 1 -type d -name 'supacloud-*' -print0 |`,
+    "    while IFS= read -r -d '' path; do",
+    "      base=${path##*/}",
+    '      case "$base" in supacloud-[A-Za-z0-9._-]*-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]T[0-9][0-9][0-9][0-9][0-9][0-9]Z-[A-Za-z0-9._-]*) ;; *) continue ;; esac',
+    '      status_file="$path/transaction-status.json"',
+    '      [ -f "$status_file" ] && [ ! -L "$status_file" ] || continue',
+    `      status=$(sed -nE 's/^[[:space:]]*"status"[[:space:]]*:[[:space:]]*"([^"]+)".*$/\\1/p' "$status_file" | head -1)`,
+    '      case "$status" in committed|rolled_back) ;; *) continue ;; esac',
+    `      finished=$(sed -nE 's/^[[:space:]]*"finishedAt"[[:space:]]*:[[:space:]]*"([^"]+)".*$/\\1/p' "$status_file" | head -1)`,
+    "      finished_date=${finished:0:10}",
+    '      [[ "$finished_date" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || continue',
+    `      bytes=$(du -sb -- "$path" | awk '{print $1}')`,
+    `      printf '%s\\t%s\\t%s\\t%s\\n' "$finished" "$status" "$bytes" "$path"`,
+    "    done",
+    "}",
+    `manifest=$(collect | sort -t $'\\t' -k1,1r | awk -F '\\t' -v keep="$KEEP_LATEST" -v before="$BEFORE" 'NR > keep && substr($1,1,10) < before')`,
+    `plan_sha256=$(printf '%s' "$manifest" | sha256sum | awk '{print $1}')`,
+    'echo "plan_sha256=$plan_sha256"',
+    'echo "before=$BEFORE keep_latest=$KEEP_LATEST"',
+    `if [ -n "$manifest" ]; then printf '%s\\n' "$manifest"; else echo 'candidates=0'; fi`
+  ];
+  if (!args.apply)
+    return manifest.join(`
+`);
+  manifest.push(`expected=${expectedPlan}`, `[ "$plan_sha256" = "$expected" ] || { echo 'plan_sha256 mismatch; refusing cleanup' >&2; exit 65; }`, "freed=0", "deleted=0", 'if [ -n "$manifest" ]; then', "  while IFS=$'\\t' read -r finished status bytes path; do", '    [ -n "$path" ] || continue', `    case "$path" in "$ROOT"/supacloud-*) ;; *) echo 'candidate escaped backup root' >&2; exit 66 ;; esac`, '    [ -d "$path" ] && [ ! -L "$path" ] || { echo "candidate changed: $path" >&2; exit 67; }', '    mountpoint -q -- "$path" && { echo "mountpoint candidate: $path" >&2; exit 68; }', '    find -P -- "$path" -xdev -depth -delete', '    [ ! -e "$path" ] || { echo "candidate was not removed: $path" >&2; exit 69; }', "    freed=$((freed + bytes))", "    deleted=$((deleted + 1))", '  done <<< "$manifest"', "fi", 'echo "deleted=$deleted freed_bytes=$freed"', "df -B1 / | tail -1");
+  return manifest.join(`
+`);
+}
 function assertExactStableVersion2(value, fieldName) {
   const normalized = value.startsWith("v") ? value.slice(1) : value;
   if (!EXACT_STABLE_SEMVER.test(normalized)) {
@@ -29349,7 +29414,7 @@ function platformVersionsToolResult(report) {
 }
 function registerSshTools(server, ssh) {
   server.tool("ssh", `Server management via SSH. Available before & after SupaCloud installation.
-Actions: ping, setup, install, upgrade, upgrade_status, versions, diagnose, exec, troubleshoot, container_logs, tenant_manage, tenant_list, tenant_inspect, tenant_diagnose, tenant_migrate`, {
+Actions: ping, setup, install, upgrade, upgrade_status, versions, diagnose, exec, troubleshoot, container_logs, backup_cleanup_plan, backup_cleanup_apply, tenant_manage, tenant_list, tenant_inspect, tenant_diagnose, tenant_migrate`, {
     action: withDescription(stringEnum([
       "ping",
       "setup",
@@ -29361,6 +29426,8 @@ Actions: ping, setup, install, upgrade, upgrade_status, versions, diagnose, exec
       "exec",
       "troubleshoot",
       "container_logs",
+      "backup_cleanup_plan",
+      "backup_cleanup_apply",
       "tenant_manage",
       "tenant_list",
       "tenant_inspect",
@@ -29381,6 +29448,9 @@ Actions: ping, setup, install, upgrade, upgrade_status, versions, diagnose, exec
     artifact_transport: optional(stringEnum(["local", "remote"]), "[upgrade] Download verified release assets locally or on the server (default: remote)"),
     github_proxy: optional(Type.String(), "[install/upgrade] Explicit GitHub proxy prefix, or direct/none"),
     focus: optional(stringEnum(["all", "containers", "database", "network", "disk", "logs"]), "[troubleshoot] Focus area"),
+    before: optional(Type.String(), "[backup_cleanup_*] Delete only completed rollback directories finished before YYYY-MM-DD"),
+    keep_latest: optional(Type.Number(), "[backup_cleanup_*] Keep this many newest completed rollback directories (default: 2)"),
+    plan_sha256: optional(Type.String(), "[backup_cleanup_apply] Exact plan_sha256 returned by backup_cleanup_plan"),
     container: optional(Type.String(), "[container_logs] Container name"),
     lines: optional(Type.Number(), "[container_logs] Number of log lines (default: 100)"),
     project_ref: optional(Type.String(), "[tenant_*] Project reference ID"),
@@ -29545,6 +29615,25 @@ ${upgradeExecution.stdout.slice(-300)}${edgeBoundary}`;
       case "versions": {
         return platformVersionsToolResult(await platformVersions(ssh));
       }
+      case "backup_cleanup_plan":
+      case "backup_cleanup_apply": {
+        if (typeof args.before !== "string")
+          throw new Error("'before' required");
+        const before = assertBackupCleanupDate(args.before);
+        const keepLatest = args.keep_latest === undefined ? 2 : assertBackupCleanupKeepLatest(args.keep_latest);
+        const apply = action === "backup_cleanup_apply";
+        const planSha256 = args.plan_sha256 === undefined ? undefined : assertBackupCleanupPlanSha256(String(args.plan_sha256));
+        if (apply && !planSha256)
+          throw new Error("'plan_sha256' required for backup_cleanup_apply");
+        if (!apply && planSha256)
+          throw new Error("plan_sha256 is only valid for backup_cleanup_apply");
+        const r = await ssh.exec(backupCleanupCommand({ before, keepLatest, planSha256, apply }), 120000);
+        if (!r.success) {
+          throw new Error(`Backup cleanup ${apply ? "apply" : "plan"} failed (exit ${r.code}): ${(r.stderr || r.stdout).slice(-1000)}`);
+        }
+        text = r.stdout;
+        break;
+      }
       case "diagnose": {
         const cmds = [
           "set -o pipefail",
@@ -32571,7 +32660,7 @@ Actions: list_releases, get_release, upload_release, activate_release`, {
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.19.0",
+  version: "0.20.1",
   description: "Platform administration CLI for SupaCloud operators",
   type: "module",
   main: "./dist/index.js",
@@ -32606,7 +32695,7 @@ var package_default = {
   },
   devDependencies: {
     "@types/bun": "^1.4.0",
-    "@types/ssh2": "^1.15.5",
+    "@types/ssh2": "^1.15.6",
     typescript: "^7.0.2"
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/admin",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Platform administration CLI for SupaCloud operators",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,7 @@
   },
   "devDependencies": {
     "@types/bun": "^1.4.0",
-    "@types/ssh2": "^1.15.5",
+    "@types/ssh2": "^1.15.6",
     "typescript": "^7.0.2"
   }
 }