@supacloud/cli 0.22.1 → 0.23.0

package/README.md

@@ -106,6 +106,28 @@ loopback development origins, with the default `:80` likewise omitted. Use
 `SUPACLOUD_PROJECT_REF` when it cannot be inferred from a managed
 `<ref>.api.*` application hostname.
 
+### Verified release controls
+
+`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.
+
+```bash
+supacloud-cli release logical_backup_list --ref abc123
+supacloud-cli release logical_backup_create --ref abc123
+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.
+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
+confirmation and read-only protections.
+
 The legacy `.env` fallback is unclassified and therefore does not enable the
 production confirmation gate. Production automation must select a `prod` or
 `production` profile, or set `SUPACLOUD_ENV=production` together with a complete

package/dist/index.js

@@ -6484,6 +6484,10 @@ var ACTION_POLICY = {
   },
   scheduled_functions: { read: ["list", "get"], write: ["create", "update", "delete"] },
   mutations: { read: ["status"] },
+  release: {
+    read: ["logical_backup_list", "postgrest_status"],
+    write: ["logical_backup_create", "postgrest_restart"]
+  },
   secrets: { read: ["list"], write: ["upsert", "delete"] },
   frontend: {
     read: ["list", "get", "build_logs", "list_frameworks", "list_records"],
@@ -6568,6 +6572,7 @@ function validateExecutionPolicyCoverage(tools) {
 
 // src/shared/transports/http.ts
 var DEFAULT_TIMEOUT = 30000;
+var MAX_POST_TIMEOUT_MS = 36 * 60000;
 var RELEASE_MUTATION_RESPONSE_TIMEOUT = 5000;
 var RELEASE_MUTATION_RESPONSE_MAX_BYTES = 64 * 1024;
 var MAX_RETRIES = 2;
@@ -6581,6 +6586,29 @@ function validatedGetResponseLimit(options) {
   }
   return maxBytes;
 }
+function validatedJsonResponseLimit(maxBytes) {
+  if (maxBytes === undefined)
+    return;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new RangeError("HTTP JSON response limit must be a positive safe integer");
+  }
+  return maxBytes;
+}
+function validatedPostTimeout(options) {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_POST_TIMEOUT_MS) {
+    throw new RangeError(`HTTP request timeout must be between 1 and ${MAX_POST_TIMEOUT_MS} ms`);
+  }
+  return timeoutMs;
+}
+function validatedResponseTimeout(timeoutMs) {
+  if (timeoutMs === undefined)
+    return;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_POST_TIMEOUT_MS) {
+    throw new RangeError(`HTTP response timeout must be between 1 and ${MAX_POST_TIMEOUT_MS} ms`);
+  }
+  return timeoutMs;
+}
 function isRetryableMethod(method) {
   const normalizedMethod = (method ?? "GET").toUpperCase();
   return normalizedMethod === "GET" || normalizedMethod === "HEAD";
@@ -6609,9 +6637,9 @@ function responseReadFailure(status) {
     responseReadError: true
   };
 }
-async function fetchWithTimeout(url, options) {
+async function fetchWithTimeout(url, options, timeoutMs = DEFAULT_TIMEOUT) {
   const controller = new AbortController;
-  const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
     return await fetch(url, {
       ...options,
@@ -6622,11 +6650,11 @@ async function fetchWithTimeout(url, options) {
     clearTimeout(timeout);
   }
 }
-async function fetchWithRetry(url, options) {
+async function fetchWithRetry(url, options, timeoutMs = DEFAULT_TIMEOUT) {
   const retries = isRetryableMethod(options.method) ? MAX_RETRIES : 0;
   for (let attempt = 0;attempt <= retries; attempt++) {
     try {
-      const res = await fetchWithTimeout(url, options);
+      const res = await fetchWithTimeout(url, options, timeoutMs);
       if (res.status >= 500 && res.status < 600 && attempt < retries) {
         const delay = RETRY_BASE_DELAY * Math.pow(2, attempt);
         await new Promise((r) => setTimeout(r, delay));
@@ -6685,7 +6713,7 @@ async function responseBytesFromReader(reader, maxBytes, declaredBytes) {
     chunks.push(value);
   }
 }
-async function responseBytesWithinLimit(response, maxBytes) {
+async function responseBytesWithinLimit(response, maxBytes, responseTimeoutMs) {
   if (declaredResponseTooLarge(response, maxBytes)) {
     await response.body?.cancel();
     return null;
@@ -6693,7 +6721,7 @@ async function responseBytesWithinLimit(response, maxBytes) {
   if (!response.body)
     return new Uint8Array;
   const reader = response.body.getReader();
-  const bodyRead = await responseBytesFromReader(reader, maxBytes, null);
+  const bodyRead = responseTimeoutMs === undefined ? await responseBytesFromReader(reader, maxBytes, null) : await responseBytesBeforeDeadline(reader, maxBytes, null, responseTimeoutMs);
   return bodyRead.ok ? bodyRead.bytes : null;
 }
 function parsedUtf8Json(responseBytes) {
@@ -6706,8 +6734,8 @@ function parsedUtf8Json(responseBytes) {
     throw error;
   }
 }
-async function boundedResponseJson(response, maxBytes) {
-  const responseBytes = await responseBytesWithinLimit(response, maxBytes);
+async function boundedResponseJson(response, maxBytes, responseTimeoutMs) {
+  const responseBytes = await responseBytesWithinLimit(response, maxBytes, responseTimeoutMs);
   if (responseBytes === null)
     return null;
   const parsed = parsedUtf8Json(responseBytes);
@@ -6736,19 +6764,19 @@ async function releaseMutationResponseBytes(response) {
   if (!response.body) {
     return declaredBytes === null || declaredBytes === 0 ? { ok: true, bytes: new Uint8Array } : { ok: false };
   }
-  return responseBytesBeforeDeadline(response.body.getReader(), declaredBytes);
+  return responseBytesBeforeDeadline(response.body.getReader(), RELEASE_MUTATION_RESPONSE_MAX_BYTES, declaredBytes, RELEASE_MUTATION_RESPONSE_TIMEOUT);
 }
-async function responseBytesBeforeDeadline(reader, declaredBytes) {
+async function responseBytesBeforeDeadline(reader, maxBytes, declaredBytes, responseTimeoutMs) {
   let deadlineTimer;
   const deadline = new Promise((resolve2) => {
     deadlineTimer = setTimeout(() => {
       cancelResponseReader(reader);
       resolve2({ ok: false });
-    }, RELEASE_MUTATION_RESPONSE_TIMEOUT);
+    }, responseTimeoutMs);
   });
   try {
     return await Promise.race([
-      responseBytesFromReader(reader, RELEASE_MUTATION_RESPONSE_MAX_BYTES, declaredBytes),
+      responseBytesFromReader(reader, maxBytes, declaredBytes),
       deadline
     ]);
   } catch {
@@ -6782,13 +6810,13 @@ class HttpTransport {
       "Content-Type": "application/json"
     };
   }
-  async mutationWithResponseReader(method, path, serializedBody, responseReader) {
+  async mutationWithResponseReader(method, path, serializedBody, responseReader, timeoutMs = DEFAULT_TIMEOUT) {
     try {
       const response = await fetchWithRetry(`${this.baseUrl}${path}`, {
         method,
         headers: this.headers(),
         body: serializedBody
-      });
+      }, timeoutMs);
       const responseBody = await responseReader(response);
       return responseBody.ok ? { ok: response.ok, status: response.status, data: responseBody.parsedJson } : responseReadFailure(response.status);
     } catch (error) {
@@ -6797,26 +6825,47 @@ class HttpTransport {
   }
   async get(path, options = {}) {
     const maxResponseBytes = validatedGetResponseLimit(options);
+    const maxJsonBytes = validatedJsonResponseLimit(options.maxJsonBytes);
+    const responseTimeoutMs = validatedResponseTimeout(options.responseTimeoutMs);
+    if (maxResponseBytes !== undefined && maxJsonBytes !== undefined) {
+      throw new RangeError("HTTP response limit options are mutually exclusive");
+    }
     try {
       const res = await fetchWithRetry(`${this.baseUrl}${path}`, {
         method: "GET",
         headers: this.headers()
       });
+      if (maxJsonBytes !== undefined) {
+        const data2 = await boundedResponseJson(res, maxJsonBytes, responseTimeoutMs);
+        return data2 === null ? responseReadFailure(res.status) : { ok: res.ok, status: res.status, data: data2 };
+      }
       const data = maxResponseBytes === undefined ? await res.json().catch(() => null) : await boundedResponseJson(res, maxResponseBytes);
       return { ok: res.ok, status: res.status, data };
     } catch (error) {
       return transportFailure(error);
     }
   }
-  async post(path, body) {
+  async post(path, body, options) {
+    const timeoutMs = validatedPostTimeout(options);
+    const maxJsonBytes = validatedJsonResponseLimit(options?.maxJsonBytes);
     try {
-      return await this.mutationWithResponseReader("POST", path, serializedRequestBody(body), responseJsonOrNull);
+      if (maxJsonBytes === undefined) {
+        return await this.mutationWithResponseReader("POST", path, serializedRequestBody(body), responseJsonOrNull, timeoutMs);
+      }
+      const response = await fetchWithRetry(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: this.headers(),
+        body: serializedRequestBody(body)
+      }, timeoutMs);
+      const data = await boundedResponseJson(response, maxJsonBytes);
+      return data === null ? responseReadFailure(response.status) : { ok: response.ok, status: response.status, data };
     } catch (error) {
       return transportFailure(error);
     }
   }
-  async postReleaseMutation(path, body) {
-    return this.mutationWithResponseReader("POST", path, serializedRequestBody(body), releaseMutationResponseJson);
+  async postReleaseMutation(path, body, options) {
+    const timeoutMs = validatedPostTimeout(options);
+    return this.mutationWithResponseReader("POST", path, serializedRequestBody(body), releaseMutationResponseJson, timeoutMs);
   }
   async patchReleaseMutation(path, body) {
     return this.mutationWithResponseReader("PATCH", path, serializedRequestBody(body), releaseMutationResponseJson);
@@ -12155,10 +12204,210 @@ var MUTATION_TOOL_SCHEMA = {
   ref: withDescription(Type.String(), "[status] Project ref"),
   mutation_id: withDescription(Type.String(), "[status] Client mutation UUID")
 };
+
+// src/shared/tools/release-tools.ts
+var SAFE_PROJECT_REF = /^[A-Za-z0-9_-]{1,64}$/;
+var BACKUP_ID = /^logical-full_[A-Za-z0-9_-]{1,64}_[a-f0-9]{32}$/;
+var SHA256 = /^[a-f0-9]{64}$/;
+var SAFE_DATABASE = /^[^\u0000-\u001f\u007f]{1,128}$/;
+var INVENTORY_MAX_BYTES = 1024 * 1024;
+var MUTATION_MAX_BYTES = 64 * 1024;
+var BACKUP_TIMEOUT_MS = 36 * 60000;
+var RELEASE_READ_RESPONSE_TIMEOUT_MS = 5000;
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function canonicalTimestamp3(value) {
+  if (typeof value !== "string")
+    return false;
+  const parsed = new Date(value);
+  return Number.isFinite(parsed.valueOf()) && parsed.toISOString() === value;
+}
+function validProjectRef(ref) {
+  return SAFE_PROJECT_REF.test(ref);
+}
+function backupBelongsToProject(backupId, projectRef) {
+  return BACKUP_ID.test(backupId) && backupId.startsWith(`logical-full_${projectRef}_`);
+}
+function verifiedBackup(value, projectRef) {
+  if (!isRecord(value) || typeof value.backup_id !== "string" || !backupBelongsToProject(value.backup_id, projectRef) || value.project_ref !== projectRef || typeof value.database !== "string" || !SAFE_DATABASE.test(value.database) || value.kind !== "logical-full" || !canonicalTimestamp3(value.created_at) || !canonicalTimestamp3(value.completed_at) || new Date(value.completed_at).valueOf() < new Date(value.created_at).valueOf() || typeof value.bytes !== "number" || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || typeof value.sha256 !== "string" || !SHA256.test(value.sha256))
+    return null;
+  return {
+    backup_id: value.backup_id,
+    project_ref: projectRef,
+    database: value.database,
+    kind: "logical-full",
+    created_at: value.created_at,
+    completed_at: value.completed_at,
+    bytes: value.bytes,
+    sha256: value.sha256
+  };
+}
+function backupInventory(value, projectRef) {
+  if (!isRecord(value) || !Array.isArray(value.backups))
+    return null;
+  const backups = value.backups.map((backup) => verifiedBackup(backup, projectRef));
+  if (backups.some((backup) => backup === null))
+    return null;
+  const inventory = backups;
+  return new Set(inventory.map((backup) => backup.backup_id)).size === inventory.length ? inventory : null;
+}
+function publicBackup(backup) {
+  return {
+    backup_id: backup.backup_id,
+    project_ref: backup.project_ref,
+    kind: backup.kind,
+    created_at: backup.created_at,
+    completed_at: backup.completed_at,
+    bytes: backup.bytes,
+    sha256: backup.sha256
+  };
+}
+function equalBackup(left, right) {
+  return left.backup_id === right.backup_id && left.project_ref === right.project_ref && left.database === right.database && left.kind === right.kind && left.created_at === right.created_at && left.completed_at === right.completed_at && left.bytes === right.bytes && left.sha256 === right.sha256;
+}
+function newlyCreatedBackup(before, after) {
+  const afterById = new Map(after.map((backup) => [backup.backup_id, backup]));
+  for (const previous of before) {
+    const current = afterById.get(previous.backup_id);
+    if (!current || !equalBackup(previous, current))
+      return null;
+  }
+  const known = new Set(before.map((backup) => backup.backup_id));
+  const additions = after.filter((backup) => !known.has(backup.backup_id));
+  return additions.length === 1 ? additions[0] : null;
+}
+function endpoint(projectRef) {
+  if (!validProjectRef(projectRef))
+    throw new Error("'ref' is invalid for release controls");
+  return `/v1/projects/${encodeURIComponent(projectRef)}`;
+}
+function httpFailure(operation, response) {
+  if (response.responseReadError) {
+    return releaseControlFailure(operation, "INVALID_RESPONSE", response.status);
+  }
+  return releaseControlFailure(operation, "HTTP_ERROR", response.transportError ? null : response.status);
+}
+function mutationFailure(operation, response) {
+  if (response.responseReadError || response.transportError || response.status === 408 || response.status >= 500) {
+    return releaseControlFailure(operation, "OUTCOME_UNKNOWN", response.transportError ? null : response.status);
+  }
+  return releaseControlFailure(operation, "HTTP_ERROR", response.status);
+}
+async function readInventory(http, projectRef) {
+  const response = await http.get(`${endpoint(projectRef)}/database/backups/logical`, {
+    maxJsonBytes: INVENTORY_MAX_BYTES,
+    responseTimeoutMs: RELEASE_READ_RESPONSE_TIMEOUT_MS
+  });
+  return { response, inventory: response.ok && response.status === 200 ? backupInventory(response.data, projectRef) : null };
+}
+function readInventoryFailure(operation, read) {
+  if (!read.response.ok)
+    return httpFailure(operation, read.response);
+  if (read.response.status !== 200 || !read.inventory) {
+    return releaseControlFailure(operation, "INVALID_RESPONSE", read.response.status);
+  }
+  return null;
+}
+function postgrestStatus(value) {
+  if (!isRecord(value) || value.component !== "postgrest" || !["running", "stopped"].includes(String(value.desired)) || !["running", "stopped", "starting", "error"].includes(String(value.actual)) || !["healthy", "unhealthy", "unknown"].includes(String(value.health)))
+    return null;
+  return {
+    desired: value.desired,
+    actual: value.actual,
+    health: value.health
+  };
+}
+async function readPostgrestStatus(http, projectRef) {
+  const response = await http.get(`${endpoint(projectRef)}/services/postgrest/status`, {
+    maxJsonBytes: MUTATION_MAX_BYTES,
+    responseTimeoutMs: RELEASE_READ_RESPONSE_TIMEOUT_MS
+  });
+  return { response, status: response.ok && response.status === 200 ? postgrestStatus(response.data) : null };
+}
+function readPostgrestFailure(operation, read) {
+  if (!read.response.ok)
+    return httpFailure(operation, read.response);
+  return read.response.status === 200 && read.status ? null : releaseControlFailure(operation, "INVALID_RESPONSE", read.response.status);
+}
+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", {
+    action: withDescription(stringEnum([
+      "logical_backup_list",
+      "logical_backup_create",
+      "postgrest_status",
+      "postgrest_restart"
+    ]), "Release control action"),
+    ref: optional(Type.String(), options.projectRef ? "Optional override when not auto-linked" : "Project ref")
+  }, async ({ action, ref }) => {
+    const projectRef = typeof ref === "string" && ref || options.projectRef;
+    if (!projectRef)
+      throw new Error("'ref' is required for release controls");
+    if (!validProjectRef(projectRef))
+      throw new Error("'ref' is invalid for release controls");
+    if (action === "logical_backup_list") {
+      const read2 = await readInventory(http, projectRef);
+      const failure = readInventoryFailure("release.logical_backup.list", read2);
+      return failure ?? releaseControlSuccess("release.logical_backup.list", {
+        project_ref: projectRef,
+        backups: read2.inventory.map(publicBackup)
+      });
+    }
+    if (action === "logical_backup_create") {
+      const before = await readInventory(http, projectRef);
+      const beforeFailure = readInventoryFailure("release.logical_backup.create", before);
+      if (beforeFailure)
+        return beforeFailure;
+      const mutation2 = await http.postReleaseMutation(`${endpoint(projectRef)}/database/backups/logical`, {}, {
+        timeoutMs: BACKUP_TIMEOUT_MS
+      });
+      const after = await readInventory(http, projectRef);
+      if (!mutation2.ok || mutation2.status !== 200) {
+        return mutationFailure("release.logical_backup.create", mutation2);
+      }
+      const responseBackup = isRecord(mutation2.data) ? verifiedBackup(mutation2.data.backup, projectRef) : null;
+      const afterFailure = readInventoryFailure("release.logical_backup.create", after);
+      const addedBackup = after.inventory && newlyCreatedBackup(before.inventory, after.inventory);
+      if (!responseBackup || afterFailure || !addedBackup || !equalBackup(responseBackup, addedBackup)) {
+        return releaseControlFailure("release.logical_backup.create", "OUTCOME_UNKNOWN", mutation2.status);
+      }
+      return releaseControlSuccess("release.logical_backup.create", {
+        project_ref: projectRef,
+        backup: publicBackup(addedBackup)
+      });
+    }
+    if (action === "postgrest_status") {
+      const read2 = await readPostgrestStatus(http, projectRef);
+      const failure = readPostgrestFailure("release.postgrest.status", read2);
+      return failure ?? releaseControlSuccess("release.postgrest.status", {
+        project_ref: projectRef,
+        postgrest: read2.status
+      });
+    }
+    if (action !== "postgrest_restart")
+      throw new Error("Unknown release control action");
+    const mutation = await http.postReleaseMutation(`${endpoint(projectRef)}/services/postgrest/restart`);
+    const read = await readPostgrestStatus(http, projectRef);
+    if (!mutation.ok || mutation.status !== 200) {
+      return mutationFailure("release.postgrest.restart", mutation);
+    }
+    const readFailure = readPostgrestFailure("release.postgrest.restart", read);
+    if (!isRestartReceipt(mutation.data) || readFailure || read.status.desired !== "running" || read.status.actual !== "running" || read.status.health !== "healthy") {
+      return releaseControlFailure("release.postgrest.restart", "OUTCOME_UNKNOWN", mutation.status);
+    }
+    return releaseControlSuccess("release.postgrest.restart", {
+      project_ref: projectRef,
+      postgrest: read.status
+    });
+  });
+}
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.22.1",
+  version: "0.23.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -12402,6 +12651,9 @@ EXAMPLES
   ${preferredCommand} project get
   ${preferredCommand} project logs --log_type database
   ${preferredCommand} project task_stats
+  ${preferredCommand} release logical_backup_create --ref abc123
+  ${preferredCommand} release postgrest_status --ref abc123
+  ${preferredCommand} release postgrest_restart --ref abc123
   ${preferredCommand} queue stats --queue emails
   ${preferredCommand} queue dlq --queue emails --limit 20
   ${preferredCommand} frontend list --ref abc123
@@ -12494,7 +12746,7 @@ function createCliTools(context, confirmProduction) {
         ]
       })
     };
-    for (const name of ["database", "auth", "storage", "edge_functions", "secrets", "frontend", "queue", "task_events", "scheduled_functions", "mutations", "diagnostics", "gateway", "branch"]) {
+    for (const name of ["database", "auth", "storage", "edge_functions", "secrets", "frontend", "queue", "task_events", "scheduled_functions", "mutations", "diagnostics", "gateway", "branch", "release"]) {
       tools[name] = {
         schema: { action: genericActionSchema },
         callback: async () => ({
@@ -12579,6 +12831,9 @@ function createCliTools(context, confirmProduction) {
     readOnly: context.readOnly
   })));
   assign(captureTools((server) => registerMutationTools(server, http)));
+  assign(captureTools((server) => registerReleaseTools(server, http, {
+    projectRef: context.projectRef || undefined
+  })));
   assign(captureTools((server) => registerFrontendTools(server, http)));
   assign(captureTools((server) => registerGatewayTools(server, http, {
     projectRef: context.projectRef || undefined

package/package.json

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