@supacloud/admin 0.11.0 → 0.12.0

package/README.md

@@ -80,6 +80,7 @@ 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
 npx @supacloud/admin project services --ref abc123
+npx @supacloud/admin project runtime_snapshot --ref abc123
 npx @supacloud/admin project service_control --ref abc123 --service gotrue --service_action stop
 ```
 
@@ -167,6 +168,7 @@ Project commands owned by this CLI:
 - `project restart`
 - `project update_settings`
 - `project services` — read-only project service inventory
+- `project runtime_snapshot` — strict read-only runtime revision and PostgREST attestation snapshot
 - `project service_control` — constrained project service lifecycle control
 
 `project create` never prints project credentials. Pass an absolute

package/dist/index.js

@@ -25788,7 +25788,17 @@ function resolveSupaCloudContext(env = process.env, cwd = process.cwd(), selecti
 // src/shared/execution-policy.ts
 var ACTION_POLICY = {
   project: {
-    read: ["list", "get", "settings", "api_keys", "health", "logs", "tasks", "services"],
+    read: [
+      "list",
+      "get",
+      "settings",
+      "api_keys",
+      "health",
+      "logs",
+      "tasks",
+      "services",
+      "runtime_snapshot"
+    ],
     write: ["create", "delete", "pause", "restore", "restart", "update_settings"]
   },
   platform: {
@@ -26023,6 +26033,14 @@ function transportFailure(error) {
     transportError: true
   };
 }
+function responseBodyFailure(status) {
+  return {
+    ok: false,
+    status,
+    data: { error: "Invalid Response", code: "INVALID_RESPONSE" },
+    responseError: true
+  };
+}
 function validatedPostTimeout(options) {
   const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT;
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_POST_TIMEOUT_MS) {
@@ -26039,6 +26057,15 @@ function validatedGetResponseLimit(options) {
   }
   return maxBytes;
 }
+function validatedStrictJsonLimit(options) {
+  const maxBytes = options.maxJsonBytes;
+  if (maxBytes === undefined)
+    return;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new RangeError("HTTP JSON response byte limit must be a positive safe integer");
+  }
+  return maxBytes;
+}
 function responseExceedsDeclaredLimit(response, maxBytes) {
   const contentLength = response.headers.get("content-length");
   return contentLength !== null && /^\d+$/u.test(contentLength) && Number(contentLength) > maxBytes;
@@ -26091,6 +26118,13 @@ async function boundedResponseJson(response, maxBytes) {
     throw error;
   }
 }
+async function strictBoundedResponseJson(response, maxBytes) {
+  const responseBytes = await boundedResponseBytes(response, maxBytes);
+  if (responseBytes === null)
+    throw new Error("HTTP JSON response exceeded its byte limit");
+  const responseText = new TextDecoder("utf-8", { fatal: true }).decode(responseBytes);
+  return JSON.parse(responseText);
+}
 async function fetchWithTimeout(url, options, timeoutMs = DEFAULT_TIMEOUT) {
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -26142,16 +26176,33 @@ class HttpTransport {
   }
   async get(path, options = {}) {
     const maxResponseBytes = validatedGetResponseLimit(options);
+    const maxJsonBytes = validatedStrictJsonLimit(options);
+    if (maxResponseBytes !== undefined && maxJsonBytes !== undefined) {
+      throw new RangeError("HTTP response limit options are mutually exclusive");
+    }
+    let response;
     try {
-      const res = await fetchWithRetry(`${this.baseUrl}${path}`, {
+      response = await fetchWithRetry(`${this.baseUrl}${path}`, {
         method: "GET",
         headers: this.headers()
       });
-      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);
     }
+    if (maxJsonBytes !== undefined) {
+      try {
+        const data2 = await strictBoundedResponseJson(response, maxJsonBytes);
+        return { ok: response.ok, status: response.status, data: data2 };
+      } catch {
+        return responseBodyFailure(response.status);
+      }
+    }
+    if (maxResponseBytes !== undefined) {
+      const data2 = await boundedResponseJson(response, maxResponseBytes);
+      return { ok: response.ok, status: response.status, data: data2 };
+    }
+    const data = await response.json().catch(() => null);
+    return { ok: response.ok, status: response.status, data };
   }
   async post(path, body, options) {
     const timeoutMs = validatedPostTimeout(options);
@@ -30003,6 +30054,152 @@ function projectGetRead(response, expectedRef) {
   const project = projectDetails(response.data, expectedRef);
   return project ? successfulResult(project) : failedResult("Invalid project response");
 }
+// src/shared/tools/project-runtime-snapshot.ts
+var RUNTIME_SNAPSHOT_SCHEMA = "supacloud.runtime-snapshot.v1";
+var ATTESTED_REVISION_PATTERN = /^hmac-sha256:[a-f0-9]{64}$/;
+var SAFE_PROJECT_REF2 = /^[a-z0-9-]{1,20}$/;
+var SNAPSHOT_KEYS = ["schema", "project_ref", "captured_at", "secrets", "postgrest"];
+var SECRETS_KEYS = [
+  "desired_revision",
+  "loaded_revision",
+  "load_state",
+  "load_source",
+  "matches_desired",
+  "loaded_at"
+];
+var POSTGREST_KEYS = [
+  "desired_revision",
+  "loaded_revision",
+  "attestation_state",
+  "matches_desired",
+  "desired",
+  "actual",
+  "health",
+  "port",
+  "unit",
+  "loaded_at"
+];
+var SECRET_LOAD_STATES = ["current", "stale", "not_loaded", "unverified", "unreachable"];
+var SECRET_LOAD_SOURCES = ["management_api", "stale_cache", "file_fallback"];
+var POSTGREST_ATTESTATION_STATES = [
+  "loaded",
+  "stale",
+  "drifted",
+  "unverified_legacy",
+  "stopped",
+  "unreachable"
+];
+var POSTGREST_DESIRED_STATES = ["running", "stopped"];
+var POSTGREST_ACTUAL_STATES = ["running", "stopped", "starting", "error"];
+var POSTGREST_HEALTH_STATES = ["healthy", "unhealthy", "unknown"];
+function isRecord2(candidate) {
+  return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
+}
+function hasExactKeys(candidate, expectedKeys) {
+  const actualKeys = Object.keys(candidate).sort();
+  const sortedExpectedKeys = [...expectedKeys].sort();
+  return actualKeys.length === sortedExpectedKeys.length && actualKeys.every((key, index) => key === sortedExpectedKeys[index]);
+}
+function isEnumMember(candidate, members) {
+  return typeof candidate === "string" && members.includes(candidate);
+}
+function isIsoTimestampOrNull(candidate) {
+  if (candidate === null)
+    return true;
+  if (typeof candidate !== "string")
+    return false;
+  const timestamp = Date.parse(candidate);
+  return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === candidate;
+}
+function isRevisionOrNull(candidate) {
+  return candidate === null || typeof candidate === "string" && ATTESTED_REVISION_PATTERN.test(candidate);
+}
+function isBooleanOrNull(candidate) {
+  return candidate === null || typeof candidate === "boolean";
+}
+function isUnloadedSecretsState(candidate) {
+  return candidate.loaded_revision === null && candidate.load_source === null && candidate.matches_desired === null && candidate.loaded_at === null;
+}
+function isLoadedSecretsState(candidate) {
+  if (candidate.load_state === "current") {
+    return candidate.loaded_revision === candidate.desired_revision && candidate.load_source === "management_api" && candidate.matches_desired === true && candidate.loaded_at !== null;
+  }
+  return candidate.load_state === "stale" && candidate.loaded_revision !== null && candidate.loaded_revision !== candidate.desired_revision && candidate.load_source === "management_api" && candidate.matches_desired === false && candidate.loaded_at !== null;
+}
+function isUnverifiedSecretsState(candidate) {
+  if (candidate.load_state !== "unverified" || candidate.matches_desired !== null || candidate.loaded_at === null)
+    return false;
+  if (candidate.loaded_revision === candidate.desired_revision) {
+    return candidate.load_source === "management_api";
+  }
+  return candidate.loaded_revision === null && candidate.load_source !== null;
+}
+function hasValidSecretsState(candidate) {
+  if (candidate.load_state === "not_loaded" || candidate.load_state === "unreachable") {
+    return isUnloadedSecretsState(candidate);
+  }
+  return isLoadedSecretsState(candidate) || isUnverifiedSecretsState(candidate);
+}
+function isRuntimeSecretsSnapshot(payload) {
+  if (!isRecord2(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;
+  return hasValidSecretsState(payload);
+}
+function hasConsistentRevisionMatch(candidate) {
+  if (candidate.loaded_revision === null)
+    return candidate.matches_desired === null;
+  return candidate.matches_desired === (candidate.loaded_revision === candidate.desired_revision);
+}
+function hasActivePostgrestProjection(candidate) {
+  return candidate.actual === "running" && candidate.health === "healthy" || candidate.actual === "error" && candidate.health === "unhealthy";
+}
+function hasValidPostgrestState(candidate) {
+  if (!hasConsistentRevisionMatch(candidate))
+    return false;
+  if (candidate.attestation_state === "loaded") {
+    return candidate.matches_desired === true && candidate.actual === "running" && candidate.health === "healthy" && candidate.loaded_at !== null;
+  }
+  if (candidate.attestation_state === "stale") {
+    return candidate.loaded_revision !== null && candidate.matches_desired === false && candidate.loaded_at !== null && hasActivePostgrestProjection(candidate);
+  }
+  if (candidate.attestation_state === "unverified_legacy")
+    return candidate.loaded_revision === null;
+  if (candidate.attestation_state === "stopped") {
+    return candidate.loaded_revision === null && candidate.actual === "stopped" && candidate.health === "unknown" && candidate.loaded_at === null;
+  }
+  if (candidate.attestation_state === "unreachable")
+    return candidate.loaded_revision === null;
+  return candidate.attestation_state === "drifted";
+}
+function isPostgrestRuntimeSnapshot(payload, projectRef) {
+  if (!isRecord2(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;
+  return hasValidPostgrestState(payload);
+}
+function sanitizedSnapshot(snapshot) {
+  return {
+    schema: snapshot.schema,
+    project_ref: snapshot.project_ref,
+    captured_at: snapshot.captured_at,
+    secrets: { ...snapshot.secrets },
+    postgrest: { ...snapshot.postgrest }
+  };
+}
+function hasCausalLoadTimestamps(snapshot) {
+  const capturedAt = Date.parse(snapshot.captured_at);
+  return [snapshot.secrets.loaded_at, snapshot.postgrest.loaded_at].every((loadedAt) => loadedAt === null || Date.parse(loadedAt) <= capturedAt);
+}
+function parseProjectRuntimeSnapshot(payload, requestedProjectRef2) {
+  if (!SAFE_PROJECT_REF2.test(requestedProjectRef2) || !isRecord2(payload) || !hasExactKeys(payload, SNAPSHOT_KEYS) || payload.schema !== RUNTIME_SNAPSHOT_SCHEMA || payload.project_ref !== requestedProjectRef2 || !isIsoTimestampOrNull(payload.captured_at) || payload.captured_at === null || !isRuntimeSecretsSnapshot(payload.secrets) || !isPostgrestRuntimeSnapshot(payload.postgrest, requestedProjectRef2))
+    return null;
+  const snapshot = payload;
+  return hasCausalLoadTimestamps(snapshot) ? sanitizedSnapshot(snapshot) : null;
+}
+
 // src/shared/tools/project-cli-tools.ts
 var PROJECT_SERVICE_NAMES = [
   "postgrest",
@@ -30034,9 +30231,10 @@ var STUDIO_PROJECT_SERVICE_STATUSES = [
 ];
 var AUTH_RUNTIME_MANAGED_BY_OWNER = "AUTH_RUNTIME_MANAGED_BY_OWNER";
 var AUTH_SERVICE_HOST_SUFFIX = "-auth";
-var SAFE_PROJECT_REF2 = /^[a-z0-9-]{1,20}$/;
+var SAFE_PROJECT_REF3 = /^[a-z0-9-]{1,20}$/;
 var SAFE_AUTHORITY_PROJECT_REF = /^[A-Za-z0-9_-]{1,20}$/;
 var MAX_SERVICE_CONTROL_MESSAGE_LENGTH = 256;
+var MAX_RUNTIME_SNAPSHOT_BYTES = 64 * 1024;
 var RELEASE_CONTROL_RESPONSE_SCHEMA = "supacloud.cli.release-control.v1";
 var PROJECT_CREATE_OPERATION = "project.create";
 var PROJECT_ENVIRONMENTS = ["test", "production"];
@@ -30250,7 +30448,7 @@ function projectServiceStatusOutput(status) {
 function projectServicesResponse(projectRef, response) {
   if (!response.ok)
     return failedProjectServiceHttpResponse(response);
-  if (!SAFE_PROJECT_REF2.test(projectRef) || !Array.isArray(response.data) || response.data.length !== 5) {
+  if (!SAFE_PROJECT_REF3.test(projectRef) || !Array.isArray(response.data) || response.data.length !== 5) {
     return failedProjectServiceResponse("Project service inventory response is invalid");
   }
   if (!response.data.every((service) => isProjectServiceStatus(service, projectRef))) {
@@ -30263,6 +30461,15 @@ function projectServicesResponse(projectRef, response) {
   const services = response.data.map(projectServiceStatusOutput);
   return projectToolResponse(JSON.stringify({ project_ref: projectRef, services }, null, 2));
 }
+function projectRuntimeSnapshotResponse(projectRef, response) {
+  if (response.responseError) {
+    return failedProjectServiceResponse("Project runtime snapshot response is invalid");
+  }
+  if (!response.ok)
+    return failedProjectServiceHttpResponse(response);
+  const snapshot = parseProjectRuntimeSnapshot(response.data, projectRef);
+  return snapshot ? projectToolResponse(JSON.stringify(snapshot, null, 2)) : failedProjectServiceResponse("Project runtime snapshot response is invalid");
+}
 function supportsProjectServiceAction(service, action) {
   return SUPPORTED_PROJECT_SERVICE_ACTIONS[service].includes(action);
 }
@@ -30336,7 +30543,7 @@ function resolveRef(refFromArgs, defaultRef) {
 }
 function registerAdminProjectCliTools(server, http, options = {}) {
   const fileOperations = options.projectEnvFileOperations;
-  server.tool("project", "Platform-level project lifecycle management. Actions: list, create, get, delete, pause, restore, restart, settings, update_settings, api_keys, health, logs, tasks, services, service_control", {
+  server.tool("project", "Platform-level project lifecycle management. Actions: list, create, get, delete, pause, restore, restart, settings, update_settings, api_keys, health, logs, tasks, services, runtime_snapshot, service_control", {
     action: withDescription(stringEnum([
       "list",
       "create",
@@ -30352,6 +30559,7 @@ function registerAdminProjectCliTools(server, http, options = {}) {
       "logs",
       "tasks",
       "services",
+      "runtime_snapshot",
       "service_control"
     ]), "Action to perform"),
     ref: optional(Type.String(), "[*] Project ref (required for most actions except 'list' and 'create')"),
@@ -30485,6 +30693,10 @@ function registerAdminProjectCliTools(server, http, options = {}) {
         const resolvedRef = resolveRef(ref);
         return projectServicesResponse(resolvedRef, await http.get(`/v1/projects/${encodeURIComponent(resolvedRef)}/services`));
       }
+      case "runtime_snapshot": {
+        const resolvedRef = resolveRef(ref);
+        return projectRuntimeSnapshotResponse(resolvedRef, await http.get(`/v1/projects/${encodeURIComponent(resolvedRef)}/runtime-snapshot`, { maxJsonBytes: MAX_RUNTIME_SNAPSHOT_BYTES }));
+      }
       case "service_control": {
         const resolvedRef = resolveRef(ref);
         if (!service)
@@ -30837,7 +31049,7 @@ Actions: routes, upsert_route, update_route, delete_route, config, get_certifica
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.11.0",
+  version: "0.12.0",
   description: "Platform administration CLI for SupaCloud operators",
   type: "module",
   main: "./dist/index.js",
@@ -30969,6 +31181,7 @@ EXAMPLES
   supacloud-admin project create --name my-app --domain example.com --env_file /secure/path/.env.project-credentials.test --environment test
   supacloud-admin project list
   supacloud-admin project services --ref abc123
+  supacloud-admin project runtime_snapshot --ref abc123
   supacloud-admin project service_control --ref abc123 --service gotrue --service_action stop
   supacloud-admin platform metrics
   supacloud-admin gateway routes --ref abc123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/admin",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Platform administration CLI for SupaCloud operators",
   "type": "module",
   "main": "./dist/index.js",