@supacloud/admin 0.24.2 → 0.25.0

package/README.md

@@ -70,6 +70,7 @@ production requires the exact project ref confirmation:
 
 ```bash
 supacloud-admin frontend list_releases --ref abc123 --id web
+supacloud-admin frontend get_active_release --ref abc123 --id web
 supacloud-admin frontend get_release --ref abc123 --id web --release_id <sha256>
 supacloud-admin frontend upload_release --ref abc123 --id web \
   --zip_path /secure/site.zip --confirm-production abc123
@@ -77,6 +78,8 @@ supacloud-admin frontend activate_release --ref abc123 --id web \
   --release_id <sha256> --expected_active_release_id absent \
   --expected_activation_id absent --mutation_id <uuid-v4> \
   --confirm-production abc123
+supacloud-admin frontend rollback --ref abc123 --id web \
+  --release_id <retained-sha256> --confirm-production abc123
 ```
 
 The CLI reads the archive through a no-follow file descriptor, verifies its
@@ -88,6 +91,13 @@ activation mutations require the Linux held-directory-FD implementation; on
 other platforms, Management API returns HTTP 503 before it reads the upload
 body, creates release directories, or writes a mutation journal.
 
+The active snapshot automatically supports older HTTP 404 endpoints through
+bounded history and exact artifact readback, never authorization or integrity
+failures. `rollback` handles current CAS and mutation IDs automatically while
+requiring an explicit retained target. It never retries a concurrent conflict,
+restores a database or infers the previous version from sorted history.
+Unknown results include the mutation ID for read-only reconciliation.
+
 SSH host keys are fail-closed: setting `SUPACLOUD_HOST` and credentials is not
 enough to enable SSH actions. Obtain the fingerprint through a trusted channel,
 compare it out of band, then set it explicitly. For example, the discovery

package/dist/index.js

@@ -2855,23 +2855,23 @@ var require_nacl_fast = __commonJS(function(exports, module) {
       randombytes = fn;
     };
     (function() {
-      var crypto = typeof self !== "undefined" ? self.crypto || self.msCrypto : null;
-      if (crypto && crypto.getRandomValues) {
+      var crypto2 = typeof self !== "undefined" ? self.crypto || self.msCrypto : null;
+      if (crypto2 && crypto2.getRandomValues) {
         var QUOTA = 65536;
         nacl.setPRNG(function(x, n) {
           var i, v = new Uint8Array(n);
           for (i = 0;i < n; i += QUOTA) {
-            crypto.getRandomValues(v.subarray(i, i + Math.min(n - i, QUOTA)));
+            crypto2.getRandomValues(v.subarray(i, i + Math.min(n - i, QUOTA)));
           }
           for (i = 0;i < n; i++)
             x[i] = v[i];
           cleanup(v);
         });
       } else if (true) {
-        crypto = __require("crypto");
-        if (crypto && crypto.randomBytes) {
+        crypto2 = __require("crypto");
+        if (crypto2 && crypto2.randomBytes) {
           nacl.setPRNG(function(x, n) {
-            var i, v = crypto.randomBytes(n);
+            var i, v = crypto2.randomBytes(n);
             for (i = 0;i < n; i++)
               x[i] = v[i];
             cleanup(v);
@@ -4135,14 +4135,14 @@ var require_bcrypt_pbkdf = __commonJS(function(exports, module) {
 
 // node_modules/ssh2/lib/protocol/constants.js
 var require_constants = __commonJS(function(exports, module) {
-  var crypto = __require("crypto");
+  var crypto2 = __require("crypto");
   var cpuInfo;
   try {
     cpuInfo = __require("cpu-features")();
   } catch {}
   var { bindingAvailable, CIPHER_INFO, MAC_INFO } = require_crypto();
   var eddsaSupported = (() => {
-    if (typeof crypto.sign === "function" && typeof crypto.verify === "function") {
+    if (typeof crypto2.sign === "function" && typeof crypto2.verify === "function") {
       const key = `-----BEGIN PRIVATE KEY-----\r
 MC4CAQAwBQYDK2VwBCIEIHKj+sVa9WcD` + `/q2DJUJaf43Kptc8xYuUQA4bOFj9vC8T\r
 -----END PRIVATE KEY-----`;
@@ -4150,14 +4150,14 @@ MC4CAQAwBQYDK2VwBCIEIHKj+sVa9WcD` + `/q2DJUJaf43Kptc8xYuUQA4bOFj9vC8T\r
       let sig;
       let verified;
       try {
-        sig = crypto.sign(null, data, key);
-        verified = crypto.verify(null, data, key, sig);
+        sig = crypto2.sign(null, data, key);
+        verified = crypto2.verify(null, data, key, sig);
       } catch {}
       return Buffer.isBuffer(sig) && sig.length === 64 && verified === true;
     }
     return false;
   })();
-  var curve25519Supported = typeof crypto.diffieHellman === "function" && typeof crypto.generateKeyPairSync === "function" && typeof crypto.createPublicKey === "function";
+  var curve25519Supported = typeof crypto2.diffieHellman === "function" && typeof crypto2.generateKeyPairSync === "function" && typeof crypto2.createPublicKey === "function";
   var DEFAULT_KEX = [
     "ecdh-sha2-nistp256",
     "ecdh-sha2-nistp384",
@@ -4192,7 +4192,7 @@ MC4CAQAwBQYDK2VwBCIEIHKj+sVa9WcD` + `/q2DJUJaf43Kptc8xYuUQA4bOFj9vC8T\r
     "ssh-dss"
   ]);
   var canUseCipher = (() => {
-    const ciphers = crypto.getCiphers();
+    const ciphers = crypto2.getCiphers();
     return (name) => ciphers.includes(CIPHER_INFO[name].sslName);
   })();
   var DEFAULT_CIPHER = [
@@ -4227,7 +4227,7 @@ MC4CAQAwBQYDK2VwBCIEIHKj+sVa9WcD` + `/q2DJUJaf43Kptc8xYuUQA4bOFj9vC8T\r
     "arcfour"
   ].filter(canUseCipher));
   var canUseMAC = (() => {
-    const hashes = crypto.getHashes();
+    const hashes = crypto2.getHashes();
     return (name) => hashes.includes(MAC_INFO[name].sslName);
   })();
   var DEFAULT_MAC = [
@@ -19618,6 +19618,11 @@ class DecodeBuilder {
 function Codec(type) {
   return new DecodeBuilder(type);
 }
+function Decode(type, callback) {
+  return Codec(type).Decode(callback).Encode(() => {
+    throw Error("Encode not implemented");
+  });
+}
 function IsCodec(value) {
   return IsSchema(value) && HasPropertyKey(value, "~codec") && IsObject(value["~codec"]) && HasPropertyKey(value["~codec"], "encode") && HasPropertyKey(value["~codec"], "decode");
 }
@@ -24838,7 +24843,22 @@ var Delete = _Object_({
 });
 var Edit = Union([Insert2, Update2, Delete]);
 // ../cli/src/shared/schema.ts
-var OUTPUT_SCHEMA = "~supacloudOutputSchema";
+var DECODE_ID = "~supacloudDecodeId";
+
+class OutputDecodeError extends Error {
+  decodeId;
+  issues;
+  constructor(decodeId, issues) {
+    super(issues.map((issue) => `- ${issue.path}: ${issue.message}`).join(`
+`));
+    this.decodeId = decodeId;
+    this.issues = issues;
+  }
+}
+function decodeIdOf(schema) {
+  const value = Object.getOwnPropertyDescriptor(schema, DECODE_ID)?.value;
+  return typeof value === "symbol" ? value : undefined;
+}
 function schemaErrorPath(path) {
   return path.replace(/^\//, "").replaceAll("/", ".") || "args";
 }
@@ -24850,42 +24870,46 @@ function transformErrorLine(error) {
   const path = typeof error === "object" && error !== null && "instancePath" in error && typeof error.instancePath === "string" ? schemaErrorPath(error.instancePath) : "args";
   return `- ${path}: ${message}`;
 }
-function parseToolArguments(schema, input) {
-  const objectSchema = _Object_(schema, { additionalProperties: false });
-  const issues = schemaErrorLines(objectSchema, input);
+function validateToolArguments(schema, input) {
+  const issues = schemaErrorLines(_Object_(schema, { additionalProperties: false }), input);
   if (issues.length > 0)
     throw new Error(`Invalid arguments:
 ${issues.join(`
 `)}`);
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseToolArguments(schema, input) {
+  const objectSchema = _Object_(schema, { additionalProperties: false });
+  validateToolArguments(schema, input);
   let decoded;
   try {
     decoded = Decode10(objectSchema, input);
   } catch (error) {
+    if (error instanceof OutputDecodeError) {
+      const entry = Object.entries(schema).find(([, property]) => decodeIdOf(property) === error.decodeId);
+      const path = entry?.[0] ?? "args";
+      const issues = error.issues.map((issue) => `- ${issue.path === "args" ? path : `${path}.${issue.path}`}: ${issue.message}`);
+      throw new Error(`Invalid arguments:
+${issues.join(`
+`)}`);
+    }
     throw new Error(`Invalid arguments:
 ${transformErrorLine(error)}`);
   }
-  const decodedIssues = [];
-  for (const [name, propertySchema] of Object.entries(schema)) {
-    const outputSchema = propertySchema?.[OUTPUT_SCHEMA];
-    if (outputSchema === undefined || decoded[name] === undefined)
-      continue;
-    for (const issue of Errors2(outputSchema, decoded[name])) {
-      const path = schemaErrorPath(issue.instancePath);
-      decodedIssues.push(`- ${path === "args" ? name : `${name}.${path}`}: ${issue.message}`);
-    }
+  const decodedFields = decoded;
+  if (!isRecord(decodedFields)) {
+    throw new Error("Invalid arguments: decoded value must be an object");
   }
-  if (decodedIssues.length > 0)
-    throw new Error(`Invalid arguments:
-${decodedIssues.join(`
-`)}`);
   return decoded;
 }
 function stringEnum(values, options) {
-  const enumRecord = Object.fromEntries(values.map((entry) => [entry, entry]));
-  return Enum(enumRecord, options);
+  return Enum([...values], options);
 }
 function mergeSchemaOptions(schema, options) {
-  const result = Object.create(Object.getPrototypeOf(schema));
+  const result = { ...schema };
+  Object.setPrototypeOf(result, Object.getPrototypeOf(schema));
   Object.defineProperties(result, Object.getOwnPropertyDescriptors(schema));
   for (const [key, value] of Object.entries(options)) {
     Object.defineProperty(result, key, { value, enumerable: true, writable: true, configurable: true });
@@ -24899,9 +24923,19 @@ function optional(schema, description) {
   return Optional(description ? withDescription(schema, description) : schema);
 }
 function decodedSchema(inputSchema, outputSchema, decode, options) {
-  const transform = Codec(inputSchema).Decode((input) => decode(input)).Encode((output) => output);
+  const decodeId = Symbol("decodedSchema");
+  const transform = Decode(inputSchema, (input) => {
+    const value = decode(input);
+    const issues = [...Errors2(outputSchema, value)].map((issue) => ({
+      path: schemaErrorPath(issue.instancePath),
+      message: issue.message
+    }));
+    if (issues.length > 0)
+      throw new OutputDecodeError(decodeId, issues);
+    return Decode10(outputSchema, value);
+  });
   const result = options ? mergeSchemaOptions(transform, options) : transform;
-  Object.defineProperty(result, OUTPUT_SCHEMA, { value: outputSchema, enumerable: false, configurable: true });
+  Object.defineProperty(result, DECODE_ID, { value: decodeId, enumerable: false, configurable: true });
   return result;
 }
 function schemaEnumValues(schema) {
@@ -25894,8 +25928,8 @@ var ACTION_POLICY = {
     ]
   },
   frontend: {
-    read: ["list_releases", "get_release"],
-    write: ["upload_release", "activate_release"]
+    read: ["list_releases", "get_active_release", "get_release"],
+    write: ["upload_release", "activate_release", "rollback"]
   },
   ssh: {
     read: [
@@ -33709,13 +33743,13 @@ async function writeProjectEnvFile(prepared, credentials, operations = nodeProje
     throw new ProjectCreateEnvError("ENV_FILE_WRITE_FAILED");
   }
 }
-function isRecord(candidate) {
+function isRecord2(candidate) {
   return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
 }
 function decodedJwtPart(encodedPart) {
   try {
     const decodedPart = JSON.parse(Buffer.from(encodedPart, "base64url").toString("utf8"));
-    return isRecord(decodedPart) ? decodedPart : null;
+    return isRecord2(decodedPart) ? decodedPart : null;
   } catch {
     return null;
   }
@@ -33756,28 +33790,28 @@ function projectApiUrl(candidate, projectRef, expectedApiOrigin) {
   return parsedUrl.origin;
 }
 function parseProjectCreateIdentity(responsePayload, expectedApiOrigin) {
-  if (!isRecord(responsePayload) || typeof responsePayload.ref !== "string")
+  if (!isRecord2(responsePayload) || typeof responsePayload.ref !== "string")
     return null;
-  if (!PROJECT_REF.test(responsePayload.ref) || !isRecord(responsePayload.api))
+  if (!PROJECT_REF.test(responsePayload.ref) || !isRecord2(responsePayload.api))
     return null;
   const apiUrl = projectApiUrl(responsePayload.api.url, responsePayload.ref, expectedApiOrigin);
   return apiUrl ? { projectRef: responsePayload.ref, apiUrl } : null;
 }
 function parseProjectCreateWithoutCredentials(responsePayload, expectedApiOrigin) {
   const identity = parseProjectCreateIdentity(responsePayload, expectedApiOrigin);
-  if (!identity || !isRecord(responsePayload))
+  if (!identity || !isRecord2(responsePayload))
     return null;
   return Object.hasOwn(responsePayload, "credentials") ? null : identity;
 }
 function parseProjectCreateCredentials(responsePayload, expectedApiOrigin, expectedProjectName) {
-  if (!expectedApiOrigin || !expectedProjectName || !isRecord(responsePayload))
+  if (!expectedApiOrigin || !expectedProjectName || !isRecord2(responsePayload))
     return null;
   if (responsePayload.name !== expectedProjectName)
     return null;
   const identity = parseProjectCreateIdentity(responsePayload, expectedApiOrigin);
   if (!identity)
     return null;
-  if (!isRecord(responsePayload.credentials))
+  if (!isRecord2(responsePayload.credentials))
     return null;
   const serviceRoleKey = responsePayload.credentials.service_role_key;
   return isServiceRoleKey(serviceRoleKey) ? { ...identity, serviceRoleKey } : null;
@@ -34171,7 +34205,7 @@ var POSTGREST_ATTESTATION_STATES = [
 var POSTGREST_DESIRED_STATES = ["running", "stopped"];
 var POSTGREST_ACTUAL_STATES = ["running", "stopped", "starting", "error"];
 var POSTGREST_HEALTH_STATES = ["healthy", "unhealthy", "unknown"];
-function isRecord2(candidate) {
+function isRecord3(candidate) {
   return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
 }
 function hasExactKeys(candidate, expectedKeys) {
@@ -34220,7 +34254,7 @@ function hasValidSecretsState(candidate) {
   return isLoadedSecretsState(candidate) || isUnverifiedSecretsState(candidate);
 }
 function isRuntimeSecretsSnapshot(payload) {
-  if (!isRecord2(payload) || !hasExactKeys(payload, SECRETS_KEYS))
+  if (!isRecord3(payload) || !hasExactKeys(payload, SECRETS_KEYS))
     return false;
   if (!isRevisionOrNull(payload.loaded_revision) || typeof payload.desired_revision !== "string" || !ATTESTED_REVISION_PATTERN.test(payload.desired_revision) || !isEnumMember(payload.load_state, SECRET_LOAD_STATES) || !(payload.load_source === null || isEnumMember(payload.load_source, SECRET_LOAD_SOURCES)) || !isBooleanOrNull(payload.matches_desired) || !isIsoTimestampOrNull(payload.loaded_at))
     return false;
@@ -34253,7 +34287,7 @@ function hasValidPostgrestState(candidate) {
   return candidate.attestation_state === "drifted";
 }
 function isPostgrestRuntimeSnapshot(payload, projectRef) {
-  if (!isRecord2(payload) || !hasExactKeys(payload, POSTGREST_KEYS))
+  if (!isRecord3(payload) || !hasExactKeys(payload, POSTGREST_KEYS))
     return false;
   if (typeof payload.desired_revision !== "string" || !ATTESTED_REVISION_PATTERN.test(payload.desired_revision) || !isRevisionOrNull(payload.loaded_revision) || !isEnumMember(payload.attestation_state, POSTGREST_ATTESTATION_STATES) || !isBooleanOrNull(payload.matches_desired) || !isEnumMember(payload.desired, POSTGREST_DESIRED_STATES) || !isEnumMember(payload.actual, POSTGREST_ACTUAL_STATES) || !isEnumMember(payload.health, POSTGREST_HEALTH_STATES) || !Number.isSafeInteger(payload.port) || Number(payload.port) < 1 || Number(payload.port) > 65535 || payload.unit !== `supacloud-pgrst@${projectRef}` || !isIsoTimestampOrNull(payload.loaded_at))
     return false;
@@ -34273,7 +34307,7 @@ function hasCausalLoadTimestamps(snapshot) {
   return [snapshot.secrets.loaded_at, snapshot.postgrest.loaded_at].every((loadedAt) => loadedAt === null || Date.parse(loadedAt) <= capturedAt);
 }
 function parseProjectRuntimeSnapshot(payload, requestedProjectRef) {
-  if (!SAFE_PROJECT_REF3.test(requestedProjectRef) || !isRecord2(payload) || !hasExactKeys(payload, SNAPSHOT_KEYS) || payload.schema !== RUNTIME_SNAPSHOT_SCHEMA || payload.project_ref !== requestedProjectRef || !isIsoTimestampOrNull(payload.captured_at) || payload.captured_at === null || !isRuntimeSecretsSnapshot(payload.secrets) || !isPostgrestRuntimeSnapshot(payload.postgrest, requestedProjectRef))
+  if (!SAFE_PROJECT_REF3.test(requestedProjectRef) || !isRecord3(payload) || !hasExactKeys(payload, SNAPSHOT_KEYS) || payload.schema !== RUNTIME_SNAPSHOT_SCHEMA || payload.project_ref !== requestedProjectRef || !isIsoTimestampOrNull(payload.captured_at) || payload.captured_at === null || !isRuntimeSecretsSnapshot(payload.secrets) || !isPostgrestRuntimeSnapshot(payload.postgrest, requestedProjectRef))
     return null;
   const snapshot = payload;
   return hasCausalLoadTimestamps(snapshot) ? sanitizedSnapshot(snapshot) : null;
@@ -34812,6 +34846,21 @@ function registerAdminProjectCliTools(server, http, options = {}) {
   });
 }
 
+// ../cli/src/shared/tool-server.ts
+var resultSchema = _Object_({
+  content: _Array_(_Object_({ type: Literal("text"), text: String2() })),
+  isError: Optional(Boolean2())
+});
+function registerTool(server, name, description, schema, callback) {
+  server.tool(name, description, schema, async (input) => {
+    const args = parseToolArguments(schema, input);
+    const result = await callback(args);
+    if (!Check2(resultSchema, result))
+      throw new Error(`Invalid result from tool '${name}'`);
+    return result;
+  });
+}
+
 // ../cli/src/shared/tools/gateway-tools.ts
 function parseCliStringArray(value) {
   if (Array.isArray(value))
@@ -34866,7 +34915,7 @@ var ok2 = (res) => res.ok ? JSON.stringify(res.data, null, 2) : `❌ Failed (${r
 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 权限。
+  registerTool(server, "gateway", `Gateway / Caddy 配置（通过 JSON Admin API 注入）。要求 admin 权限。
 Actions: routes, upsert_route, update_route, delete_route, config, get_certificate, update_certificate, issue_certificate, deploy_certificate, rebuild, custom_hostname, set_custom_hostname, delete_custom_hostname, verify_custom_hostname`, {
     action: withDescription(stringEnum([
       "routes",
@@ -35267,12 +35316,15 @@ function releaseInventory(candidate, expected) {
     next_cursor: nextCursor
   };
 }
-function releaseEndpoint(projectRef, deploymentId) {
+function deploymentEndpoint(projectRef, deploymentId) {
   if (!PROJECT_REF_PATTERN3.test(projectRef))
     throw new Error("'ref' is invalid for frontend releases");
   if (!DEPLOYMENT_ID_PATTERN.test(deploymentId))
     throw new Error("'id' is invalid for frontend releases");
-  return `/v1/projects/${encodeURIComponent(projectRef)}/frontend/deployments/${encodeURIComponent(deploymentId)}/releases`;
+  return `/v1/projects/${encodeURIComponent(projectRef)}/frontend/deployments/${encodeURIComponent(deploymentId)}`;
+}
+function releaseEndpoint(projectRef, deploymentId) {
+  return `${deploymentEndpoint(projectRef, deploymentId)}/releases`;
 }
 function releasePath(projectRef, deploymentId, releaseId) {
   if (!RELEASE_ID_PATTERN.test(releaseId))
@@ -35477,16 +35529,15 @@ function activationReceipt(candidate, input) {
   return release;
 }
 async function activeReleaseReadback(http, identity) {
-  const endpoint = releaseEndpoint(identity.projectRef, identity.deploymentId);
-  const inventoryRead = await http.get(`${endpoint}?limit=${RELEASE_LIST_LIMIT_MAX}`, {
-    maxJsonBytes: RESPONSE_MAX_BYTES
-  });
-  const inventory = inventoryRead.ok ? releaseInventory(inventoryRead.data, {
-    projectRef: identity.projectRef,
-    deploymentId: identity.deploymentId
-  }) : null;
-  if (!inventory || inventory.releases.length > RELEASE_LIST_LIMIT_MAX || inventory.active_release_id !== identity.releaseId || inventory.active_activation_id !== identity.mutationId) {
-    return { release: null, status: inventoryRead.status };
+  const snapshot = await readActiveFrontendRelease(http, identity.projectRef, identity.deploymentId);
+  if ("failure" in snapshot)
+    return { release: null, status: snapshot.status };
+  const inventory = snapshot.inventory;
+  if (inventory.active_release_id !== identity.releaseId || inventory.active_activation_id !== identity.mutationId) {
+    return { release: null, status: 200 };
+  }
+  if (snapshot.exactReadback) {
+    return { release: inventory.releases[0] ?? null, status: 200 };
   }
   const releaseRead = await http.get(releasePath(identity.projectRef, identity.deploymentId, identity.releaseId), { maxJsonBytes: RESPONSE_MAX_BYTES });
   const release = releaseRead.ok ? releaseEnvelope(releaseRead.data, {
@@ -35496,6 +35547,100 @@ async function activeReleaseReadback(http, identity) {
   }) : null;
   return { release, status: releaseRead.status };
 }
+async function readActiveFrontendRelease(http, projectRef, deploymentId) {
+  const response = await http.get(`${deploymentEndpoint(projectRef, deploymentId)}/active-release`, {
+    maxJsonBytes: RESPONSE_MAX_BYTES
+  });
+  const inventory = response.ok && response.status === 200 ? releaseInventory(response.data, { projectRef, deploymentId }) : null;
+  if (inventory) {
+    if (inventory.next_cursor !== null || inventory.releases.length !== (inventory.active_release_id === null ? 0 : 1) || inventory.releases[0] && inventory.releases[0].release_id !== inventory.active_release_id) {
+      return { failure: releaseReadFailure("frontend.get_active_release", response), status: response.status };
+    }
+    return { inventory, exactReadback: false };
+  }
+  if (response.ok || response.status !== 404) {
+    return { failure: releaseReadFailure("frontend.get_active_release", response), status: response.status };
+  }
+  const historyResponse = await http.get(`${releaseEndpoint(projectRef, deploymentId)}?limit=1`, {
+    maxJsonBytes: RESPONSE_MAX_BYTES
+  });
+  const history = historyResponse.ok && historyResponse.status === 200 ? releaseInventory(historyResponse.data, { projectRef, deploymentId }) : null;
+  if (!history || history.releases.length > 1) {
+    return {
+      failure: releaseReadFailure("frontend.get_active_release", historyResponse),
+      status: historyResponse.status
+    };
+  }
+  if (history.active_release_id === null) {
+    return { inventory: { ...history, releases: [], next_cursor: null }, exactReadback: false };
+  }
+  const exactResponse = await http.get(releasePath(projectRef, deploymentId, history.active_release_id), {
+    maxJsonBytes: RESPONSE_MAX_BYTES
+  });
+  const release = exactResponse.ok && exactResponse.status === 200 ? releaseEnvelope(exactResponse.data, { projectRef, deploymentId, releaseId: history.active_release_id }) : null;
+  if (!release) {
+    return {
+      failure: releaseReadFailure("frontend.get_active_release", exactResponse),
+      status: exactResponse.status
+    };
+  }
+  return { inventory: { ...history, releases: [release], next_cursor: null }, exactReadback: true };
+}
+async function getActiveFrontendRelease(http, projectRef, deploymentId) {
+  const snapshot = await readActiveFrontendRelease(http, projectRef, deploymentId);
+  return "failure" in snapshot ? snapshot.failure : toolResponse(snapshot.inventory);
+}
+async function rollbackFrontendRelease(http, projectRef, deploymentId, releaseId) {
+  if (!RELEASE_ID_PATTERN.test(releaseId))
+    throw new Error("'release_id' must be a SHA-256 digest");
+  const authority = await readActiveFrontendRelease(http, projectRef, deploymentId);
+  if ("failure" in authority)
+    return authority.failure;
+  const inventory = authority.inventory;
+  if (inventory.active_release_id === releaseId) {
+    return toolResponse({
+      project_ref: projectRef,
+      deployment_id: deploymentId,
+      active_release_id: releaseId,
+      activation_id: inventory.active_activation_id,
+      unchanged: true
+    });
+  }
+  if (inventory.active_release_id === null || inventory.active_activation_id === null) {
+    return releaseFailure("frontend.rollback", "NO_ACTIVE_RELEASE", 409);
+  }
+  const target = await getFrontendRelease(http, projectRef, deploymentId, releaseId);
+  if (target.isError)
+    return target;
+  const mutationId = crypto.randomUUID();
+  const activation = await activateFrontendRelease(http, {
+    projectRef,
+    deploymentId,
+    releaseId,
+    expectedActiveReleaseId: inventory.active_release_id,
+    expectedActivationId: inventory.active_activation_id,
+    mutationId
+  });
+  if (activation.isError) {
+    return {
+      ...toolResponse({
+        ...JSON.parse(activation.content[0].text),
+        operation: "frontend.rollback",
+        mutation_id: mutationId,
+        target_release_id: releaseId,
+        expected_active_release_id: inventory.active_release_id,
+        expected_activation_id: inventory.active_activation_id
+      }),
+      isError: true
+    };
+  }
+  return toolResponse({
+    ...JSON.parse(activation.content[0].text),
+    rollback: true,
+    previous_release_id: inventory.active_release_id,
+    previous_activation_id: inventory.active_activation_id
+  });
+}
 async function activateFrontendRelease(http, input) {
   const mutationId = input.mutationId;
   if (!MUTATION_ID_PATTERN.test(mutationId))
@@ -35561,17 +35706,19 @@ async function activationReadback(http, input, mutationId, activationStatus) {
 // src/shared/tools/frontend-tools.ts
 function registerFrontendTools(server, http) {
   server.tool("frontend", `Immutable prebuilt frontend release control.
-Actions: list_releases, get_release, upload_release, activate_release`, {
+Actions: list_releases, get_active_release, get_release, upload_release, activate_release, rollback`, {
     action: withDescription(stringEnum([
       "list_releases",
+      "get_active_release",
       "get_release",
       "upload_release",
-      "activate_release"
+      "activate_release",
+      "rollback"
     ]), "Action"),
     ref: optional(String4(), "Project ref"),
     id: optional(String4(), "Deployment ID"),
     zip_path: optional(String4(), "[upload_release] Local ZIP file path"),
-    release_id: optional(String4(), "[get_release/activate_release] SHA-256 release ID"),
+    release_id: optional(String4(), "[get_release/activate_release/rollback] SHA-256 release ID"),
     expected_active_release_id: optional(String4(), "[activate_release] Current release SHA-256 or absent"),
     expected_activation_id: optional(String4(), "[activate_release] Current activation UUIDv4 or absent"),
     mutation_id: optional(String4(), "[activate_release] Required retry-stable UUIDv4"),
@@ -35604,6 +35751,10 @@ Actions: list_releases, get_release, upload_release, activate_release`, {
         need("id", id);
         need("release_id", release_id);
         return getFrontendRelease(http, ref, id, release_id);
+      case "get_active_release":
+        need("ref", ref);
+        need("id", id);
+        return getActiveFrontendRelease(http, ref, id);
       case "upload_release":
         need("ref", ref);
         need("id", id);
@@ -35624,6 +35775,11 @@ Actions: list_releases, get_release, upload_release, activate_release`, {
           expectedActivationId: expected_activation_id,
           mutationId: mutation_id
         });
+      case "rollback":
+        need("ref", ref);
+        need("id", id);
+        need("release_id", release_id);
+        return rollbackFrontendRelease(http, ref, id, release_id);
       default:
         throw new Error("Unknown immutable frontend release action");
     }
@@ -35632,7 +35788,7 @@ Actions: list_releases, get_release, upload_release, activate_release`, {
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.24.2",
+  version: "0.25.0",
   description: "Platform administration CLI for SupaCloud operators",
   type: "module",
   main: "./dist/index.js",
@@ -35665,7 +35821,7 @@ var package_default = {
   },
   dependencies: {
     typebox: "1.3.34",
-    "@supacloud/cli": "0.68.1",
+    "@supacloud/cli": "0.76.0",
     ssh2: "^1.17.0"
   },
   devDependencies: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/admin",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Platform administration CLI for SupaCloud operators",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "typebox": "1.3.34",
-    "@supacloud/cli": "0.68.1",
+    "@supacloud/cli": "0.76.0",
     "ssh2": "^1.17.0"
   },
   "devDependencies": {