@supacloud/cli 0.23.0 → 0.25.0

package/README.md

@@ -111,18 +111,48 @@ loopback development origins, with the default `:80` likewise omitted. Use
 `release` is an official CLI entry point for the existing Management API
 logical-backup and PostgREST lifecycle capabilities. It requires the Management
 API context above; it does not promote an application `service_role` key to
-Management authority. Restore remains an admin-only operation and is not
-exposed by this command group.
+Management authority.
+
+Project pause and restore are explicit lifecycle commands. A logical backup
+restore requires an operator to pause the selected project first and then use
+`project get` to confirm that its status is `paused`. `project restore` resumes
+the paused project lifecycle when its database exists; if the database is
+missing, the platform begins project re-provisioning instead. It does not
+restore a database backup and is never invoked automatically by the CLI.
+
+```bash
+supacloud-cli project pause --ref abc123
+supacloud-cli release logical_backup_restore --ref abc123 \
+  --backup_id logical-full_abc123_<backup-id-suffix> \
+  --expected_sha256 <64-lowercase-hex> \
+  --restore_confirmation RESTORE_PROJECT:abc123:logical-full_abc123_<backup-id-suffix>:<64-lowercase-hex>
+supacloud-cli project restore --ref abc123
+```
 
 ```bash
 supacloud-cli release logical_backup_list --ref abc123
 supacloud-cli release logical_backup_create --ref abc123
+supacloud-cli release logical_backup_restore --ref abc123 \
+  --backup_id logical-full_abc123_<backup-id-suffix> \
+  --expected_sha256 <64-lowercase-hex> \
+  --restore_confirmation RESTORE_PROJECT:abc123:logical-full_abc123_<backup-id-suffix>:<64-lowercase-hex>
 supacloud-cli release postgrest_status --ref abc123
 supacloud-cli release postgrest_restart --ref abc123
 ```
 
 Backup creation reports success only after the CLI verifies exactly one new
 logical-backup receipt against the inventory before and after the mutation.
+Logical restore is project-scoped: pause the selected project first, obtain the
+backup ID and SHA-256 from `logical_backup_list`, and supply both the normal
+production `--confirm-production <ref>` value (for production profiles) and
+the exact `--restore_confirmation
+RESTORE_PROJECT:<ref>:<backup_id>:<sha256>`. Before POST, the CLI re-reads
+that same project's inventory and binds the request to the complete verified
+backup identity; it then verifies both the server receipt and a fresh inventory
+read. It never retries a restore. A transport, server, or unreadable-response
+failure is reported as `OUTCOME_UNKNOWN`; read the inventory and investigate
+before any new restore decision.
+
 PostgREST restart reports success only after it receives a matching restart
 receipt and reads back `desired=running`, `actual=running`, and
 `health=healthy`. Both mutating controls follow the normal production

package/dist/index.js

@@ -6459,7 +6459,7 @@ function resolveSupaCloudContext(env = process.env, cwd = process.cwd(), selecti
 var ACTION_POLICY = {
   project: {
     read: ["get", "health", "logs", "api_keys", "settings", "tasks", "task_detail", "task_stats", "dlq", "background_settings"],
-    write: ["task_cancel", "task_retry", "update_background_settings"]
+    write: ["pause", "restore", "task_cancel", "task_retry", "update_background_settings"]
   },
   database: {
     read: ["list_tables", "describe_columns", "list_indexes", "list_constraints", "list_extensions", "rls_status", "rls_policies", "list_auth_users", "get_auth_user", "connections", "stats", "slow_queries", "list_migrations", "migration_inventory", "project_url", "generate_types"],
@@ -6486,7 +6486,7 @@ var ACTION_POLICY = {
   mutations: { read: ["status"] },
   release: {
     read: ["logical_backup_list", "postgrest_status"],
-    write: ["logical_backup_create", "postgrest_restart"]
+    write: ["logical_backup_create", "logical_backup_restore", "postgrest_restart"]
   },
   secrets: { read: ["list"], write: ["upsert", "delete"] },
   frontend: {
@@ -10098,6 +10098,7 @@ var formatTaskStats = (data) => {
 `);
 };
 var ok = (res) => res.ok ? JSON.stringify(res.data, null, 2) : `❌ Failed (${res.status}): ${JSON.stringify(res.data)}`;
+var simple = (res, msg) => res.ok ? `✅ ${msg}` : `❌ Failed (${res.status})`;
 function buildProjectLogsPath(ref, logType) {
   const params = new URLSearchParams({ limit: "200" });
   if (logType && logType !== "all") {
@@ -10114,9 +10115,11 @@ function resolveRef(refFromArgs, defaultRef) {
 function registerUserProjectCliTools(server, http, options = {}) {
   const { projectRef } = options;
   server.tool("project", `Project-scoped inspection and developer operations.
-Actions: get, health, logs, api_keys, settings, tasks, task_detail, task_cancel, task_retry, task_stats, dlq, background_settings, update_background_settings`, {
+Actions: get, pause, restore, health, logs, api_keys, settings, tasks, task_detail, task_cancel, task_retry, task_stats, dlq, background_settings, update_background_settings`, {
     action: withDescription(stringEnum([
       "get",
+      "pause",
+      "restore",
       "health",
       "logs",
       "api_keys",
@@ -10144,6 +10147,12 @@ Actions: get, health, logs, api_keys, settings, tasks, task_detail, task_cancel,
         return projectReadResponse(projectGetRead(await http.get(`/v1/projects/${resolvedRef}`, {
           maxResponseBytes: PROJECT_READ_RESPONSE_MAX_BYTES
         }), resolvedRef));
+      case "pause":
+        text = simple(await http.post(`/v1/projects/${resolvedRef}/pause`), `Project ${resolvedRef} paused`);
+        break;
+      case "restore":
+        text = simple(await http.post(`/v1/projects/${resolvedRef}/restore`), `Project ${resolvedRef} restored`);
+        break;
       case "health":
         text = ok(await http.get(`/v1/projects/${resolvedRef}/health`));
         break;
@@ -10540,7 +10549,7 @@ var redirectStatus = Type.Optional(Type.Union([
   Type.Literal(308)
 ]));
 var ok2 = (res) => res.ok ? JSON.stringify(res.data, null, 2) : `❌ Failed (${res.status}): ${JSON.stringify(res.data)}`;
-var simple = (res, msg) => res.ok ? `✅ ${msg}` : `❌ Failed (${res.status}): ${JSON.stringify(res.data)}`;
+var simple2 = (res, msg) => res.ok ? `✅ ${msg}` : `❌ Failed (${res.status}): ${JSON.stringify(res.data)}`;
 function registerGatewayTools(server, http, options = {}) {
   const { projectRef } = options;
   server.tool("gateway", `Gateway / Caddy 配置（通过 JSON Admin API 注入）。要求 admin 权限。
@@ -10802,11 +10811,11 @@ Actions: routes, upsert_route, update_route, delete_route, config, get_certifica
         break;
       case "set_custom_hostname": {
         need("custom_hostname", custom_hostname);
-        text = simple(await http.post(`/v1/projects/${projectRefValue}/custom-hostname`, { custom_hostname }), `Custom hostname ${custom_hostname} requested`);
+        text = simple2(await http.post(`/v1/projects/${projectRefValue}/custom-hostname`, { custom_hostname }), `Custom hostname ${custom_hostname} requested`);
         break;
       }
       case "delete_custom_hostname":
-        text = simple(await http.delete(`/v1/projects/${projectRefValue}/custom-hostname`), "Custom hostname removed");
+        text = simple2(await http.delete(`/v1/projects/${projectRefValue}/custom-hostname`), "Custom hostname removed");
         break;
       case "verify_custom_hostname":
         text = ok2(await http.post(`/v1/projects/${projectRefValue}/custom-hostname/verify`));
@@ -12277,6 +12286,19 @@ function newlyCreatedBackup(before, after) {
   const additions = after.filter((backup) => !known.has(backup.backup_id));
   return additions.length === 1 ? additions[0] : null;
 }
+function restoreRequest(projectRef, backupId, expectedSha256, restoreConfirmation) {
+  if (typeof backupId !== "string" || !backupBelongsToProject(backupId, projectRef)) {
+    throw new Error("'backup_id' must identify a logical-full backup for 'ref'");
+  }
+  if (typeof expectedSha256 !== "string" || !SHA256.test(expectedSha256)) {
+    throw new Error("'expected_sha256' must be a lowercase SHA-256 digest");
+  }
+  const confirmation = `RESTORE_PROJECT:${projectRef}:${backupId}:${expectedSha256}`;
+  if (restoreConfirmation !== confirmation) {
+    throw new Error("'restore_confirmation' must exactly confirm the selected logical backup restore");
+  }
+  return { backup_id: backupId, expected_sha256: expectedSha256, confirmation };
+}
 function endpoint(projectRef) {
   if (!validProjectRef(projectRef))
     throw new Error("'ref' is invalid for release controls");
@@ -12334,15 +12356,19 @@ function isRestartReceipt(value) {
   return isRecord(value) && value.service === "postgrest" && value.action === "restart" && value.success === true;
 }
 function registerReleaseTools(server, http, options = {}) {
-  server.tool("release", "Verified release controls using a Management API credential. Actions: logical_backup_list, logical_backup_create, postgrest_status, postgrest_restart", {
+  server.tool("release", "Verified release controls using a Management API credential. Actions: logical_backup_list, logical_backup_create, logical_backup_restore, postgrest_status, postgrest_restart", {
     action: withDescription(stringEnum([
       "logical_backup_list",
       "logical_backup_create",
+      "logical_backup_restore",
       "postgrest_status",
       "postgrest_restart"
     ]), "Release control action"),
-    ref: optional(Type.String(), options.projectRef ? "Optional override when not auto-linked" : "Project ref")
-  }, async ({ action, ref }) => {
+    ref: optional(Type.String(), options.projectRef ? "Optional override when not auto-linked" : "Project ref"),
+    backup_id: optional(Type.String(), "[logical_backup_restore] Exact verified logical-full backup ID from the selected project inventory"),
+    expected_sha256: optional(Type.String(), "[logical_backup_restore] Exact lowercase SHA-256 from the selected project inventory"),
+    restore_confirmation: optional(Type.String(), "[logical_backup_restore] Exact RESTORE_PROJECT:<ref>:<backup_id>:<sha256> confirmation")
+  }, async ({ action, ref, backup_id, expected_sha256, restore_confirmation }) => {
     const projectRef = typeof ref === "string" && ref || options.projectRef;
     if (!projectRef)
       throw new Error("'ref' is required for release controls");
@@ -12379,6 +12405,32 @@ function registerReleaseTools(server, http, options = {}) {
         backup: publicBackup(addedBackup)
       });
     }
+    if (action === "logical_backup_restore") {
+      const request = restoreRequest(projectRef, backup_id, expected_sha256, restore_confirmation);
+      const before = await readInventory(http, projectRef);
+      const beforeFailure = readInventoryFailure("release.logical_backup.restore", before);
+      if (beforeFailure)
+        return beforeFailure;
+      const selectedBackup = before.inventory.find((backup) => backup.backup_id === request.backup_id && backup.sha256 === request.expected_sha256);
+      if (!selectedBackup) {
+        return releaseControlFailure("release.logical_backup.restore", "MUTATION_NOT_SUCCEEDED", null);
+      }
+      const mutation2 = await http.postReleaseMutation(`${endpoint(projectRef)}/database/backups/logical/restore`, request, { timeoutMs: BACKUP_TIMEOUT_MS });
+      if (!mutation2.ok || mutation2.status !== 200) {
+        return mutationFailure("release.logical_backup.restore", mutation2);
+      }
+      const responseBackup = isRecord(mutation2.data) ? verifiedBackup(mutation2.data.restored_backup, projectRef) : null;
+      const after = await readInventory(http, projectRef);
+      const afterFailure = readInventoryFailure("release.logical_backup.restore", after);
+      const restoredInventoryBackup = after.inventory?.find((backup) => backup.backup_id === request.backup_id);
+      if (!responseBackup || !equalBackup(responseBackup, selectedBackup) || afterFailure || !restoredInventoryBackup || !equalBackup(restoredInventoryBackup, selectedBackup)) {
+        return releaseControlFailure("release.logical_backup.restore", "OUTCOME_UNKNOWN", mutation2.status);
+      }
+      return releaseControlSuccess("release.logical_backup.restore", {
+        project_ref: projectRef,
+        backup: publicBackup(selectedBackup)
+      });
+    }
     if (action === "postgrest_status") {
       const read2 = await readPostgrestStatus(http, projectRef);
       const failure = readPostgrestFailure("release.postgrest.status", read2);
@@ -12407,7 +12459,7 @@ function registerReleaseTools(server, http, options = {}) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.23.0",
+  version: "0.25.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -12451,6 +12503,8 @@ var commandName = "supacloud-cli";
 var preferredCommand = commandName;
 var projectActionSchema = stringEnum([
   "get",
+  "pause",
+  "restore",
   "health",
   "logs",
   "api_keys",
@@ -12652,6 +12706,7 @@ EXAMPLES
   ${preferredCommand} project logs --log_type database
   ${preferredCommand} project task_stats
   ${preferredCommand} release logical_backup_create --ref abc123
+  ${preferredCommand} release logical_backup_restore --ref abc123 --backup_id <backup_id> --expected_sha256 <sha256> --restore_confirmation RESTORE_PROJECT:abc123:<backup_id>:<sha256>
   ${preferredCommand} release postgrest_status --ref abc123
   ${preferredCommand} release postgrest_restart --ref abc123
   ${preferredCommand} queue stats --queue emails

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",