@supacloud/cli 0.17.0 → 0.19.0

package/README.md

@@ -92,15 +92,19 @@ supacloud-cli status
 
 Project context is resolved from one atomic source: a named profile selected by
 `--env`, an explicit `--env-file`, a complete process environment, or the
-legacy `.env` fallback. Core URL, token, and project-ref values are not filled
-by mixing sources. If `SUPACLOUD_ENV` is set without a complete process context,
-it strictly selects `.env.supacloud.<value>`. For backward compatibility, when
-no selector and no core process variables are present, `supacloud-cli` still
-tries to auto-link from `.env` using:
-
-- `SUPABASE_URL` or `SUPACLOUD_API_URL`
-- `SUPABASE_SERVICE_ROLE_KEY` or `SUPACLOUD_API_TOKEN`
-- `SUPACLOUD_PROJECT_REF` when the project ref cannot be inferred from a managed `<ref>.api.*` hostname
+legacy `.env` fallback. Core URL, credential, and project-ref values are not
+filled by mixing sources. If `SUPACLOUD_ENV` is set without a complete process
+context, it strictly selects `.env.supacloud.<value>`.
+
+The two credential scopes are separate. Management-backed remote commands use
+only `SUPACLOUD_API_URL` + `SUPACLOUD_API_TOKEN`. An application profile using
+`SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` can be auto-linked for `status`,
+but its service-role key is never substituted for a Management token and cannot
+enable Management-backed tools. Both URL types must be canonical HTTPS origins;
+omit explicit default ports such as `:443`. HTTP is accepted only for literal
+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.
 
 The legacy `.env` fallback is unclassified and therefore does not enable the
 production confirmation gate. Production automation must select a `prod` or
@@ -127,11 +131,13 @@ for one command. A production profile cannot target a different project with
 `--ref`; the requested ref and `--confirm-production` must both exactly match
 the profile's project ref.
 
-`status` checks configuration, Management API connectivity, and authentication;
-it exits non-zero when any required check fails. Its output includes
-`environment`, `source` (`kind` and `path`), `apiUrl`, `projectRef`, `readOnly`,
-`production`, and `hasApiToken`. It never prints the API token or service-role
-key.
+`status` checks configuration, connectivity, and authentication against the
+selected credential scope. Application profiles probe the project data API at
+the exact configured origin; credential-bearing probes refuse redirects. The
+command exits non-zero when any required check fails. Its output includes
+`credentialScope`, `environment`, `source` (`kind` and `path`), `apiUrl`,
+`projectRef`, `readOnly`, `production`, and `hasApiToken`. It never prints the
+API token or service-role key.
 
 Examples:
 
@@ -212,10 +218,10 @@ already exist. Add the positive version observed from `list` as
 pointer; this remains correct across an active-version A→B→A transition.
 
 `deploy`, `deploy_bundle`, and `activate` require
-`--expected-active-version <N|absent>`. Read the current positive integer
-version from `edge_functions list`; use `absent` only when creating a slug that
-does not yet exist. A stale value returns HTTP 409 without building, preheating,
-or activating another version. List output remains a JSON array with string
+`--expected-active-version <N|absent>`. Read the current non-negative integer
+version from `edge_functions list`; use `0` for a listed legacy Function and
+`absent` only when creating a slug that does not yet exist. A stale value returns
+HTTP 409 without building, preheating, or activating another version. List output remains a JSON array with string
 `slug` and numeric `version` fields, while source output is exactly
 `{ "code": "..." }`. Release automation must use `source --version <N>` for a
 version-bound backup.
@@ -228,9 +234,13 @@ server response body.
 Mutation receipts use schema `supacloud.cli.release-control.v1`. An
 `OUTCOME_UNKNOWN` error means the server may have committed the mutation before
 the response was lost or failed validation; read back current state before any
-retry.
-Version `0` is reserved for service-internal legacy recovery and cannot be used
-as a public CLI/API activation target or expected active version.
+retry. For Function deploy, bundle deploy, and activation, the CLI applies a
+separate 5-second, 64 KiB response-body boundary after receiving HTTP headers.
+A stalled, oversized, truncated, unreadable, or malformed body is always
+`OUTCOME_UNKNOWN` and its content is never included in CLI output.
+Version `0` is reserved as the active-version CAS token for legacy Functions. It
+can be passed only as `--expected-active-version`; immutable source reads and
+activation targets still require a positive version.
 
 ```json
 {
@@ -321,10 +331,10 @@ supacloud-cli supabase push --ref abc123 --dir supabase/migrations --dry_run
 supacloud-cli supabase push --ref abc123 --dir supabase/migrations
 ```
 
-`push` uses `SUPABASE_SERVICE_ROLE_KEY` or `SUPACLOUD_API_TOKEN` only for the
-SupaCloud Management API. Those credentials, upstream access tokens, database
-passwords, and secret/key environment variables are removed from the official
-CLI child process, and command output is redacted.
+`push` uses only `SUPACLOUD_API_TOKEN` for the SupaCloud Management API. That
+token, upstream access tokens, database passwords, and secret/key environment
+variables are removed from the official CLI child process, and command output
+is redacted.
 
 `push` requires a resolved project ref; pass `--ref` explicitly or set
 `SUPACLOUD_PROJECT_REF`. Relative migration directories are resolved against

package/dist/index.js

@@ -6333,58 +6333,45 @@ function readEnvFile(path, required) {
     throw new Error(`Failed to read SupaCloud environment file ${path}: ${message}`);
   }
 }
-function normalizeUrl(value) {
-  const trimmed = value.trim().replace(/\/+$/, "");
-  if (!trimmed)
+function canonicalApiOrigin(value) {
+  const candidate = value.trim();
+  if (!candidate)
     return "";
   try {
-    return new URL(trimmed).toString().replace(/\/+$/, "");
-  } catch {
-    return "";
+    const url = new URL(candidate);
+    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    const allowedProtocol = url.protocol === "https:" || url.protocol === "http:" && loopback;
+    const exactOrigin = candidate === url.origin || candidate === `${url.origin}/`;
+    return allowedProtocol && !url.username && !url.password && exactOrigin && url.pathname === "/" && !url.search && !url.hash ? url.origin : "";
+  } catch (error) {
+    if (error instanceof TypeError)
+      return "";
+    throw error;
   }
 }
 function hostFromUrl(value) {
-  try {
-    return new URL(value).hostname;
-  } catch {
-    return "";
-  }
+  return value ? new URL(value).hostname : "";
 }
 function inferProjectRefFromSupabaseUrl(value) {
-  const normalized = normalizeUrl(value);
-  if (!normalized)
+  if (!value)
     return "";
-  return new URL(normalized).hostname.match(/^([a-z0-9-]+)\.api\./i)?.[1] ?? "";
+  return new URL(value).hostname.match(/^([a-z0-9-]+)\.api\./i)?.[1] ?? "";
 }
-function inferManagementApiUrlFromSupabaseUrl(value, projectRef = "") {
-  const normalized = normalizeUrl(value);
-  if (!normalized)
-    return "";
-  const url = new URL(normalized);
-  const host = url.hostname;
-  if (host.startsWith("api.")) {
-    url.hostname = `studio.${host.slice("api.".length)}`;
-    return url.toString().replace(/\/+$/, "");
-  }
-  const ref = projectRef.trim();
-  if (ref && host.startsWith(`${ref}.api.`)) {
-    url.hostname = `studio-${ref}.${host.slice(`${ref}.api.`.length)}`;
-    return url.toString().replace(/\/+$/, "");
-  }
-  const managedHost = host.match(/^([a-z0-9-]+)\.api\.(.+)$/i);
-  if (managedHost) {
-    url.hostname = `studio-${managedHost[1]}.${managedHost[2]}`;
-    return url.toString().replace(/\/+$/, "");
-  }
-  return normalized;
+function sourceCredentialScope(values, explicitApiUrl, supabaseUrl) {
+  const hasManagementContext = Boolean(explicitApiUrl.trim() || values.SUPACLOUD_API_TOKEN?.trim() || values.SUPACLOUD_HOST?.trim());
+  if (hasManagementContext)
+    return "management";
+  return supabaseUrl || values.SUPABASE_SERVICE_ROLE_KEY?.trim() ? "project_application" : "incomplete";
 }
 function sourceProjectCore(values) {
-  const supabaseUrl = normalizeUrl(values.SUPABASE_URL || "");
+  const supabaseUrl = canonicalApiOrigin(values.SUPABASE_URL || "");
   const projectRef = (values.SUPACLOUD_PROJECT_REF || values.X_PROJECT_REF || "").trim() || inferProjectRefFromSupabaseUrl(supabaseUrl);
   const explicitApiUrl = values.SUPACLOUD_API_URL || values.SUPACLOUD_MANAGEMENT_API_URL || values.MANAGEMENT_API_URL || "";
-  const apiUrl = normalizeUrl(explicitApiUrl) || inferManagementApiUrlFromSupabaseUrl(supabaseUrl, projectRef) || (values.SUPACLOUD_HOST ? `http://${values.SUPACLOUD_HOST}:9090` : "");
-  const apiToken = values.SUPACLOUD_API_TOKEN || values.SUPABASE_SERVICE_ROLE_KEY || "";
-  return { apiUrl, apiToken, projectRef, supabaseUrl };
+  const credentialScope = sourceCredentialScope(values, explicitApiUrl, supabaseUrl);
+  const managementUrl = explicitApiUrl || (values.SUPACLOUD_HOST ? `http://${values.SUPACLOUD_HOST}:9090` : "");
+  const apiUrl = credentialScope === "management" ? canonicalApiOrigin(managementUrl) : "";
+  const apiToken = credentialScope === "management" ? values.SUPACLOUD_API_TOKEN || "" : "";
+  return { apiUrl, apiToken, projectRef, supabaseUrl, credentialScope };
 }
 function processValues(env) {
   return Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== undefined));
@@ -6394,6 +6381,9 @@ function hasProcessContext(env) {
 }
 function completeProjectContext(values) {
   const core = sourceProjectCore(values);
+  if (core.credentialScope === "project_application") {
+    return Boolean(core.supabaseUrl && values.SUPABASE_SERVICE_ROLE_KEY?.trim() && core.projectRef);
+  }
   return Boolean(core.apiUrl && core.apiToken && core.projectRef);
 }
 function namedEnvironmentSource(cwd, selector) {
@@ -6459,6 +6449,7 @@ function resolveSupaCloudContext(env = process.env, cwd = process.cwd(), selecti
     production: source.environment === "prod" || source.environment === "production",
     inferredSupabaseUrl: core.supabaseUrl,
     inferredServiceRoleKey: source.values.SUPABASE_SERVICE_ROLE_KEY || "",
+    credentialScope: core.credentialScope,
     source: source.kind,
     sourcePath: source.path
   };
@@ -6492,6 +6483,7 @@ var ACTION_POLICY = {
     write: ["deploy", "deploy_bundle", "config", "activate", "delete"]
   },
   scheduled_functions: { read: ["list", "get"], write: ["create", "update", "delete"] },
+  mutations: { read: ["status"] },
   secrets: { read: ["list"], write: ["upsert", "delete"] },
   frontend: {
     read: ["list", "get", "build_logs", "list_frameworks", "list_records"],
@@ -6576,6 +6568,8 @@ function validateExecutionPolicyCoverage(tools) {
 
 // src/shared/transports/http.ts
 var DEFAULT_TIMEOUT = 30000;
+var RELEASE_MUTATION_RESPONSE_TIMEOUT = 5000;
+var RELEASE_MUTATION_RESPONSE_MAX_BYTES = 64 * 1024;
 var MAX_RETRIES = 2;
 var RETRY_BASE_DELAY = 500;
 function isRetryableMethod(method) {
@@ -6598,13 +6592,22 @@ function transportFailure(error) {
     transportError: true
   };
 }
+function responseReadFailure(status) {
+  return {
+    ok: false,
+    status,
+    data: { error: "Response body unavailable", code: "RESPONSE_READ_ERROR" },
+    responseReadError: true
+  };
+}
 async function fetchWithTimeout(url, options) {
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
   try {
     return await fetch(url, {
       ...options,
-      signal: controller.signal
+      signal: controller.signal,
+      redirect: "error"
     });
   } finally {
     clearTimeout(timeout);
@@ -6647,41 +6650,114 @@ function joinedResponseBytes(chunks, totalBytes) {
   }
   return responseBytes;
 }
-async function responseBytesWithinLimit(response, maxBytes) {
-  if (declaredResponseTooLarge(response, maxBytes)) {
-    await response.body?.cancel();
-    return null;
-  }
-  if (!response.body)
-    return new Uint8Array;
-  const reader = response.body.getReader();
+function cancelResponseReader(reader) {
+  reader.cancel().catch(() => {
+    return;
+  });
+}
+function serializedRequestBody(body) {
+  return body ? JSON.stringify(body) : undefined;
+}
+async function responseBytesFromReader(reader, maxBytes, declaredBytes) {
   const chunks = [];
   let totalBytes = 0;
   while (true) {
     const { done, value } = await reader.read();
-    if (done)
-      return joinedResponseBytes(chunks, totalBytes);
+    if (done) {
+      if (declaredBytes !== null && totalBytes !== declaredBytes)
+        return { ok: false };
+      return { ok: true, bytes: joinedResponseBytes(chunks, totalBytes) };
+    }
     totalBytes += value.byteLength;
     if (totalBytes > maxBytes) {
-      await reader.cancel();
-      return null;
+      cancelResponseReader(reader);
+      return { ok: false };
     }
     chunks.push(value);
   }
 }
+async function responseBytesWithinLimit(response, maxBytes) {
+  if (declaredResponseTooLarge(response, maxBytes)) {
+    await response.body?.cancel();
+    return null;
+  }
+  if (!response.body)
+    return new Uint8Array;
+  const reader = response.body.getReader();
+  const bodyRead = await responseBytesFromReader(reader, maxBytes, null);
+  return bodyRead.ok ? bodyRead.bytes : null;
+}
 function parsedUtf8Json(responseBytes) {
   try {
     const responseText = new TextDecoder("utf-8", { fatal: true }).decode(responseBytes);
-    return JSON.parse(responseText);
+    return { ok: true, parsedJson: JSON.parse(responseText) };
   } catch (error) {
     if (error instanceof SyntaxError || error instanceof TypeError)
-      return null;
+      return { ok: false };
     throw error;
   }
 }
 async function boundedResponseJson(response, maxBytes) {
   const responseBytes = await responseBytesWithinLimit(response, maxBytes);
-  return responseBytes === null ? null : parsedUtf8Json(responseBytes);
+  if (responseBytes === null)
+    return null;
+  const parsed = parsedUtf8Json(responseBytes);
+  return parsed.ok ? parsed.parsedJson : null;
+}
+function declaredIdentityResponseBytes(response) {
+  const contentEncoding = response.headers.get("content-encoding");
+  if (contentEncoding !== null && contentEncoding.toLowerCase() !== "identity")
+    return null;
+  const contentLength = response.headers.get("content-length");
+  if (contentLength === null)
+    return null;
+  if (!/^\d+$/.test(contentLength))
+    return "invalid";
+  const declaredBytes = Number(contentLength);
+  return Number.isSafeInteger(declaredBytes) ? declaredBytes : "invalid";
+}
+async function releaseMutationResponseBytes(response) {
+  const declaredBytes = declaredIdentityResponseBytes(response);
+  if (declaredBytes === "invalid" || declaredBytes !== null && declaredBytes > RELEASE_MUTATION_RESPONSE_MAX_BYTES) {
+    response.body?.cancel().catch(() => {
+      return;
+    });
+    return { ok: false };
+  }
+  if (!response.body) {
+    return declaredBytes === null || declaredBytes === 0 ? { ok: true, bytes: new Uint8Array } : { ok: false };
+  }
+  return responseBytesBeforeDeadline(response.body.getReader(), declaredBytes);
+}
+async function responseBytesBeforeDeadline(reader, declaredBytes) {
+  let deadlineTimer;
+  const deadline = new Promise((resolve2) => {
+    deadlineTimer = setTimeout(() => {
+      cancelResponseReader(reader);
+      resolve2({ ok: false });
+    }, RELEASE_MUTATION_RESPONSE_TIMEOUT);
+  });
+  try {
+    return await Promise.race([
+      responseBytesFromReader(reader, RELEASE_MUTATION_RESPONSE_MAX_BYTES, declaredBytes),
+      deadline
+    ]);
+  } catch {
+    cancelResponseReader(reader);
+    return { ok: false };
+  } finally {
+    clearTimeout(deadlineTimer);
+  }
+}
+async function releaseMutationResponseJson(response) {
+  const responseBytes = await releaseMutationResponseBytes(response);
+  if (!responseBytes.ok)
+    return { ok: false };
+  const parsed = parsedUtf8Json(responseBytes.bytes);
+  return parsed.ok ? { ok: true, parsedJson: parsed.parsedJson } : { ok: false };
+}
+async function responseJsonOrNull(response) {
+  return { ok: true, parsedJson: await response.json().catch(() => null) };
 }
 
 class HttpTransport {
@@ -6697,6 +6773,19 @@ class HttpTransport {
       "Content-Type": "application/json"
     };
   }
+  async postWithResponseReader(path, serializedBody, responseReader) {
+    try {
+      const response = await fetchWithRetry(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: this.headers(),
+        body: serializedBody
+      });
+      const responseBody = await responseReader(response);
+      return responseBody.ok ? { ok: response.ok, status: response.status, data: responseBody.parsedJson } : responseReadFailure(response.status);
+    } catch (error) {
+      return transportFailure(error);
+    }
+  }
   async get(path, options = {}) {
     try {
       const res = await fetchWithRetry(`${this.baseUrl}${path}`, {
@@ -6711,17 +6800,14 @@ class HttpTransport {
   }
   async post(path, body) {
     try {
-      const res = await fetchWithRetry(`${this.baseUrl}${path}`, {
-        method: "POST",
-        headers: this.headers(),
-        body: body ? JSON.stringify(body) : undefined
-      });
-      const data = await res.json().catch(() => null);
-      return { ok: res.ok, status: res.status, data };
+      return await this.postWithResponseReader(path, serializedRequestBody(body), responseJsonOrNull);
     } catch (error) {
       return transportFailure(error);
     }
   }
+  async postReleaseMutation(path, body) {
+    return this.postWithResponseReader(path, serializedRequestBody(body), releaseMutationResponseJson);
+  }
   async postMultipart(path, formData) {
     try {
       const headers = { Authorization: `Bearer ${this.token}` };
@@ -7886,7 +7972,7 @@ function releaseControlFailure(operation, code, httpStatus) {
   });
 }
 function releaseControlMutationFailure(operation, response) {
-  const outcomeUnknown = response.transportError || response.status === 408 || response.status >= 500;
+  const outcomeUnknown = response.transportError || response.responseReadError || response.status === 408 || response.status >= 500;
   return outcomeUnknown ? releaseControlFailure(operation, "OUTCOME_UNKNOWN", response.transportError ? null : response.status) : releaseControlFailure(operation, "HTTP_ERROR", response.status);
 }
 function releaseControlResponse(payload) {
@@ -8523,6 +8609,17 @@ function positiveFunctionVersion(input, label) {
   }
   return version;
 }
+function activeFunctionVersionToken(input) {
+  if (typeof input !== "string" && typeof input !== "number") {
+    throw new Error("Expected active version must be a canonical non-negative safe integer");
+  }
+  const version = String(input);
+  if (!CANONICAL_FUNCTION_VERSION_PATTERN.test(version) || !Number.isSafeInteger(Number(version))) {
+    throw new Error("Expected active version must be a canonical non-negative safe integer");
+  }
+  return version;
+}
+var CANONICAL_FUNCTION_VERSION_PATTERN = /^(?:0|[1-9][0-9]*)$/;
 var POSITIVE_FUNCTION_VERSION_PATTERN = /^[1-9][0-9]*$/;
 var SAFE_FUNCTION_SLUG_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
 var FUNCTION_ACTIVATION_ARGUMENTS = new Set([
@@ -8539,15 +8636,15 @@ var functionVersionSchema = Type.Optional(decodedSchema(Type.Union([
 function parseExpectedActiveVersion(input) {
   if (input === "absent")
     return input;
-  return positiveFunctionVersion(input, "Expected active version");
+  return activeFunctionVersionToken(input);
 }
 var expectedActiveVersionSchema = Type.Optional(decodedSchema(Type.Union([
   Type.Literal("absent"),
-  Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
-  Type.String({ pattern: POSITIVE_FUNCTION_VERSION_PATTERN.source, maxLength: 16 })
+  Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+  Type.String({ pattern: CANONICAL_FUNCTION_VERSION_PATTERN.source, maxLength: 16 })
 ]), Type.Union([
   Type.Literal("absent"),
-  Type.String({ pattern: POSITIVE_FUNCTION_VERSION_PATTERN.source, maxLength: 16 })
+  Type.String({ pattern: CANONICAL_FUNCTION_VERSION_PATTERN.source, maxLength: 16 })
 ]), parseExpectedActiveVersion));
 var secretListSchema = Type.Array(Type.Object({ name: Type.String(), value: Type.String() }));
 var ENVIRONMENT_SECRET_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,255}$/;
@@ -8679,7 +8776,7 @@ function safeFunctionList(payload) {
     const edgeFunction = objectRecord(candidate);
     const slug = edgeFunction?.slug;
     const version = edgeFunction?.version;
-    if (typeof slug !== "string" || !SAFE_FUNCTION_SLUG_PATTERN.test(slug) || typeof version !== "number" || !Number.isSafeInteger(version) || version < 1 || functionSlugs.has(slug))
+    if (typeof slug !== "string" || !SAFE_FUNCTION_SLUG_PATTERN.test(slug) || typeof version !== "number" || !Number.isSafeInteger(version) || version < 0 || functionSlugs.has(slug))
       return null;
     functionSlugs.add(slug);
   }
@@ -8828,7 +8925,7 @@ async function activateFunctionVersion(http, args, readOnly = false) {
     slug: functionSlug,
     expectedActiveVersion,
     targetVersion: version
-  }, await http.post(endpoint, { expected_active_version: expectedActiveVersion }));
+  }, await http.postReleaseMutation(endpoint, { expected_active_version: expectedActiveVersion }));
 }
 function registerAdvancedTools(server, http, environment = process.env, options = {}) {
   server.tool("edge_functions", `Edge Function management (Deno/Bun serverless). Source deploys are bundled; verified prebuilt artifacts stay byte-exact.
@@ -8920,7 +9017,7 @@ ${deployCheck.err}`;
             break;
           }
         }
-        const deploymentResponse = await http.post(edgeFunctionResourcePath(ref, slug), {
+        const deploymentResponse = await http.postReleaseMutation(edgeFunctionResourcePath(ref, slug), {
           code: deployCode.code,
           ...deployCode.prebundled ? { prebundled: true, expected_sha256: deployCode.expectedSha256 } : { minify },
           expected_active_version: expectedActiveVersion,
@@ -8936,7 +9033,7 @@ ${deployCheck.err}`;
       case "deploy_bundle":
         need("slug", slug);
         need("files", files);
-        const bundleResponse = await http.post(`${edgeFunctionResourcePath(ref, slug)}/bundle`, {
+        const bundleResponse = await http.postReleaseMutation(`${edgeFunctionResourcePath(ref, slug)}/bundle`, {
           files,
           entrypoint,
           minify,
@@ -10551,10 +10648,10 @@ function missingMigrationContextResult() {
     content: [{
       type: "text",
       text: [
-        "⚠️ Remote migration push requires SupaCloud project context.",
-        "Provide SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY, or SUPACLOUD_API_URL + SUPACLOUD_API_TOKEN.",
+        "⚠️ Remote migration push requires SupaCloud Management API context.",
+        "Provide SUPACLOUD_API_URL + SUPACLOUD_API_TOKEN.",
         "Also pass --ref or set SUPACLOUD_PROJECT_REF when the project ref cannot be inferred from the URL.",
-        "The service-role credential is sent only to the SupaCloud Management API and is never forwarded to the official CLI."
+        "The Management token is sent only to the SupaCloud Management API and is never forwarded to the official CLI."
       ].join(`
 `)
     }]
@@ -10641,7 +10738,7 @@ function registerSupabaseCliTools(server, options = {}) {
     readOnly: options.readOnly ?? false,
     executeOfficialCli: options.executeOfficialCli || ((request) => executeOfficialSupabaseCli(request, environment))
   };
-  server.tool("supabase", "Controlled adapter for the official open-source Supabase CLI. Remote push stays on the SupaCloud service-role authenticated Management API.", {
+  server.tool("supabase", "Controlled adapter for the official open-source Supabase CLI. Remote push stays on the SupaCloud Management API and requires explicit Management credentials.", {
     action: withDescription(stringEnum([
       "version",
       "migration_new",
@@ -11264,10 +11361,216 @@ var SCHEDULE_TOOL_SCHEMA = {
   body_file: optional(Type.String(), "[create/update] Local JSON object file; content is never printed"),
   header_env: withDescription(headerEnvironmentSchema, "[create/update] JSON map of HTTP header names to environment variable names")
 };
+
+// src/shared/mutation-protocol.ts
+var MUTATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+var FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+var OPERATION_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,127}$/;
+var RESOURCE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,254}$/;
+var FAILURE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+var LEASE_OWNER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,254}$/;
+var TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+var MAX_STATUS_RESPONSE_BYTES = 196608;
+var MUTATION_STATUSES = new Set([
+  "pending",
+  "running",
+  "succeeded",
+  "failed_retryable",
+  "failed_terminal",
+  "outcome_unknown"
+]);
+var MUTATION_RESPONSE_KEYS = ["project_ref", "mutation"];
+var MUTATION_KEYS = [
+  "project_ref",
+  "mutation_id",
+  "operation",
+  "resource_key",
+  "request_fingerprint",
+  "principal",
+  "status",
+  "checkpoint",
+  "receipt",
+  "response_status",
+  "failure_code",
+  "lease",
+  "completed_at",
+  "created_at",
+  "updated_at"
+];
+var PRINCIPAL_KEYS = ["type", "id"];
+var LEASE_KEYS = ["owner", "expires_at", "fencing_epoch"];
+function isMutationId(candidate) {
+  return typeof candidate === "string" && MUTATION_ID_PATTERN.test(candidate);
+}
+function objectRecord3(candidate) {
+  return candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : null;
+}
+function exactRecord(candidate, keys) {
+  const record = objectRecord3(candidate);
+  if (!record || Object.keys(record).length !== keys.length)
+    return null;
+  return keys.every((key) => Object.hasOwn(record, key)) ? record : null;
+}
+function emptyProjection(candidate) {
+  const record = objectRecord3(candidate);
+  return record && Object.keys(record).length === 0 ? record : null;
+}
+function canonicalTimestamp(candidate) {
+  if (typeof candidate !== "string" || !TIMESTAMP_PATTERN.test(candidate))
+    return false;
+  const milliseconds = Date.parse(candidate);
+  return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === candidate;
+}
+function nullableTimestamp(candidate) {
+  return candidate === null || canonicalTimestamp(candidate);
+}
+function safePrincipal(candidate) {
+  const principal = exactRecord(candidate, PRINCIPAL_KEYS);
+  if (!principal || !["master", "admin", "project"].includes(String(principal.type)))
+    return null;
+  if (typeof principal.id !== "string" || !principal.id || principal.id.length > 320 || principal.id.trim() !== principal.id || /[\u0000-\u001f\u007f]/u.test(principal.id))
+    return null;
+  return { type: principal.type, id: principal.id };
+}
+function safeLease(candidate) {
+  const lease = exactRecord(candidate, LEASE_KEYS);
+  if (!lease || lease.owner !== null && (typeof lease.owner !== "string" || !LEASE_OWNER_PATTERN.test(lease.owner)))
+    return null;
+  if (!nullableTimestamp(lease.expires_at) || !Number.isSafeInteger(lease.fencing_epoch) || Number(lease.fencing_epoch) < 0)
+    return null;
+  return {
+    owner: lease.owner,
+    expires_at: lease.expires_at,
+    fencing_epoch: Number(lease.fencing_epoch)
+  };
+}
+function safeResponseStatus(candidate) {
+  if (candidate === null)
+    return null;
+  return Number.isInteger(candidate) && Number(candidate) >= 100 && Number(candidate) <= 599 ? Number(candidate) : undefined;
+}
+function validLeaseState(status, lease) {
+  const running = status === "running";
+  return running ? lease.owner !== null && lease.expires_at !== null && lease.fencing_epoch > 0 : lease.owner === null && lease.expires_at === null;
+}
+function validMutationLifecycle(mutation, receipt, responseStatus) {
+  const terminal = ["succeeded", "failed_terminal", "outcome_unknown"].includes(String(mutation.status));
+  if (mutation.completed_at !== null !== terminal)
+    return false;
+  if (mutation.status === "succeeded") {
+    return receipt !== null && responseStatus !== null && responseStatus >= 200 && responseStatus < 300 && mutation.failure_code === null;
+  }
+  if (mutation.status === "failed_terminal") {
+    return receipt !== null && typeof mutation.failure_code === "string";
+  }
+  if (mutation.status === "failed_retryable" || mutation.status === "outcome_unknown") {
+    return receipt !== null && typeof mutation.failure_code === "string";
+  }
+  if (mutation.status === "pending") {
+    return receipt === null && responseStatus === null && mutation.failure_code === null;
+  }
+  return true;
+}
+function validMutationIdentity(mutation) {
+  if (!isMutationId(mutation.mutation_id) || typeof mutation.project_ref !== "string")
+    return false;
+  if (typeof mutation.operation !== "string" || !OPERATION_PATTERN.test(mutation.operation))
+    return false;
+  if (mutation.resource_key !== null && (typeof mutation.resource_key !== "string" || !RESOURCE_KEY_PATTERN.test(mutation.resource_key)))
+    return false;
+  return typeof mutation.request_fingerprint === "string" && FINGERPRINT_PATTERN.test(mutation.request_fingerprint);
+}
+function validMutationTerminalFields(mutation) {
+  if (typeof mutation.status !== "string" || !MUTATION_STATUSES.has(mutation.status))
+    return false;
+  if (mutation.failure_code !== null && (typeof mutation.failure_code !== "string" || !FAILURE_CODE_PATTERN.test(mutation.failure_code)))
+    return false;
+  return nullableTimestamp(mutation.completed_at) && canonicalTimestamp(mutation.created_at) && canonicalTimestamp(mutation.updated_at);
+}
+function safeMutationStatus(candidate) {
+  const mutation = exactRecord(candidate, MUTATION_KEYS);
+  if (!mutation || !validMutationIdentity(mutation) || !validMutationTerminalFields(mutation))
+    return null;
+  const principal = safePrincipal(mutation.principal);
+  const checkpoint = emptyProjection(mutation.checkpoint);
+  const receipt = mutation.receipt === null ? null : emptyProjection(mutation.receipt);
+  const responseStatus = safeResponseStatus(mutation.response_status);
+  const lease = safeLease(mutation.lease);
+  if (!principal || !checkpoint || mutation.receipt !== null && !receipt || responseStatus === undefined || !lease || !validLeaseState(String(mutation.status), lease) || !validMutationLifecycle(mutation, receipt, responseStatus))
+    return null;
+  return {
+    project_ref: mutation.project_ref,
+    mutation_id: mutation.mutation_id,
+    operation: mutation.operation,
+    resource_key: mutation.resource_key,
+    request_fingerprint: mutation.request_fingerprint,
+    principal,
+    status: mutation.status,
+    checkpoint,
+    receipt,
+    response_status: responseStatus,
+    failure_code: mutation.failure_code,
+    lease,
+    completed_at: mutation.completed_at,
+    created_at: mutation.created_at,
+    updated_at: mutation.updated_at
+  };
+}
+function mutationStatusPath(ref, mutationId) {
+  if (!isMutationId(mutationId))
+    throw new Error("'mutation_id' must be a UUIDv4");
+  return `/v1/projects/${projectRefPathSegment(ref, "Mutations")}/mutations/${encodeURIComponent(mutationId)}`;
+}
+function mutationStatusResponse(ref, mutationId, payload) {
+  const response = exactRecord(payload, MUTATION_RESPONSE_KEYS);
+  const mutation = safeMutationStatus(response?.mutation);
+  return response?.project_ref === ref && mutation?.project_ref === ref && mutation.mutation_id === mutationId ? mutation : null;
+}
+async function fetchMutationStatus(http, ref, mutationId) {
+  const response = await http.get(mutationStatusPath(ref, mutationId), {
+    maxResponseBytes: MAX_STATUS_RESPONSE_BYTES
+  });
+  if (!response.ok) {
+    return { kind: "unavailable", httpStatus: response.transportError ? null : response.status };
+  }
+  const mutation = mutationStatusResponse(ref, mutationId, response.data);
+  return mutation ? { kind: "available", mutation } : { kind: "invalid" };
+}
+
+// src/shared/tools/mutation-tools.ts
+function requiredText3(args, name) {
+  const candidate = args[name];
+  if (typeof candidate !== "string" || !candidate.trim())
+    throw new Error(`'${name}' is required for 'status'`);
+  return candidate.trim();
+}
+async function mutationStatus(http, args) {
+  const ref = requiredText3(args, "ref");
+  projectRefPathSegment(ref, "Mutations");
+  const mutationId = requiredText3(args, "mutation_id");
+  if (!isMutationId(mutationId))
+    throw new Error("'mutation_id' must be a UUIDv4");
+  const readback = await fetchMutationStatus(http, ref, mutationId);
+  if (readback.kind === "unavailable") {
+    return releaseControlFailure("mutations.status", "HTTP_ERROR", readback.httpStatus);
+  }
+  if (readback.kind === "invalid") {
+    return releaseControlFailure("mutations.status", "INVALID_RESPONSE", null);
+  }
+  return releaseControlSuccess("mutations.status", { project_ref: ref, mutation: readback.mutation });
+}
+function registerMutationTools(server, http) {
+  server.tool("mutations", "Durable mutation status readback", MUTATION_TOOL_SCHEMA, (args) => mutationStatus(http, args));
+}
+var MUTATION_TOOL_SCHEMA = {
+  action: withDescription(stringEnum(["status"]), "Action"),
+  ref: withDescription(Type.String(), "[status] Project ref"),
+  mutation_id: withDescription(Type.String(), "[status] Client mutation UUID")
+};
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.17.0",
+  version: "0.19.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -11332,13 +11635,14 @@ function failedEndpointProbe(error) {
   const timedOut = error instanceof Error && error.name === "AbortError";
   return { reachable: false, ok: false, httpStatus: null, error: timedOut ? "timeout" : "unreachable" };
 }
-async function probeEndpoint(url, token) {
+async function probeEndpoint(url, headers) {
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), 3000);
   try {
     const response = await fetch(url, {
       method: "GET",
-      headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+      headers,
+      redirect: "error",
       signal: controller.signal
     });
     return successfulEndpointProbe(response);
@@ -11349,6 +11653,13 @@ async function probeEndpoint(url, token) {
   }
 }
 function missingProjectContextFields(context) {
+  if (context.credentialScope === "project_application") {
+    return [
+      !context.inferredSupabaseUrl ? "secureSupabaseUrl" : null,
+      !context.inferredServiceRoleKey ? "serviceRoleKey" : null,
+      !context.projectRef ? "projectRef" : null
+    ].filter((field) => Boolean(field));
+  }
   return [
     !context.apiUrl ? "apiUrl" : null,
     !context.apiToken ? "apiToken" : null,
@@ -11358,16 +11669,42 @@ function missingProjectContextFields(context) {
 function authenticatedByProbe(authentication) {
   if (!authentication)
     return null;
-  return authentication.reachable && ![401, 403].includes(authentication.httpStatus ?? 0);
+  return authentication.reachable && authentication.ok;
 }
-async function collectProjectStatusChecks(context) {
-  const missing = missingProjectContextFields(context);
-  const connectivity = context.apiUrl ? await probeEndpoint(`${context.apiUrl}/health`) : null;
-  const authentication = missing.length === 0 && connectivity?.ok ? await probeEndpoint(`${context.apiUrl}/v1/projects/${encodeURIComponent(context.projectRef)}/health`, context.apiToken) : null;
+function connectivityProbeIsHealthy(scope, connectivity) {
+  if (!connectivity)
+    return null;
+  if (scope !== "project_application")
+    return connectivity.ok;
+  return connectivity.reachable && (connectivity.ok || [401, 403].includes(connectivity.httpStatus ?? 0));
+}
+function projectApplicationHeaders(serviceRoleKey) {
+  return { Authorization: `Bearer ${serviceRoleKey}`, apikey: serviceRoleKey };
+}
+function projectStatusApiUrl(context) {
+  return context.credentialScope === "project_application" ? context.inferredSupabaseUrl : context.apiUrl;
+}
+function projectStatusProbePlan(context) {
+  if (context.credentialScope === "project_application") {
+    return {
+      apiUrl: projectStatusApiUrl(context),
+      connectivityPath: "/rest/v1/",
+      authenticationPath: "/rest/v1/",
+      authenticationHeaders: projectApplicationHeaders(context.inferredServiceRoleKey)
+    };
+  }
+  return {
+    apiUrl: projectStatusApiUrl(context),
+    connectivityPath: "/health",
+    authenticationPath: `/v1/projects/${encodeURIComponent(context.projectRef)}/health`,
+    authenticationHeaders: { Authorization: `Bearer ${context.apiToken}` }
+  };
+}
+function projectStatusChecks(missing, connectivity, authentication, connectivityOk) {
   return {
     configuration: { ok: missing.length === 0, missing },
     connectivity: {
-      ok: connectivity?.ok ?? null,
+      ok: connectivityOk,
       reachable: connectivity?.reachable ?? null,
       httpStatus: connectivity?.httpStatus ?? null,
       error: connectivity?.error ?? null
@@ -11376,21 +11713,31 @@ async function collectProjectStatusChecks(context) {
     project: { ok: authentication?.ok ?? null }
   };
 }
+async function collectProjectStatusChecks(context) {
+  const missing = missingProjectContextFields(context);
+  const probePlan = projectStatusProbePlan(context);
+  const connectivity = probePlan.apiUrl ? await probeEndpoint(`${probePlan.apiUrl}${probePlan.connectivityPath}`) : null;
+  const connectivityOk = connectivityProbeIsHealthy(context.credentialScope, connectivity);
+  const authentication = missing.length === 0 && connectivityOk ? await probeEndpoint(`${probePlan.apiUrl}${probePlan.authenticationPath}`, probePlan.authenticationHeaders) : null;
+  return projectStatusChecks(missing, connectivity, authentication, connectivityOk);
+}
 function projectStatusIsHealthy(checks) {
   return checks.configuration.ok && checks.connectivity.ok === true && checks.authentication.ok === true && checks.project.ok === true;
 }
 async function createProjectStatusResult(context) {
   const checks = await collectProjectStatusChecks(context);
+  const statusApiUrl = projectStatusApiUrl(context);
   const statusPayload = {
     mode: "project",
+    credentialScope: context.credentialScope,
     environment: context.environment || null,
     source: { kind: context.source, path: context.sourcePath },
     projectRef: context.projectRef || null,
-    apiUrl: context.apiUrl || null,
+    apiUrl: statusApiUrl || null,
     readOnly: context.readOnly,
     production: context.production,
     autoLinked: Boolean(context.inferredSupabaseUrl && context.inferredServiceRoleKey),
-    hasApiToken: Boolean(context.apiToken),
+    hasApiToken: context.credentialScope === "project_application" ? Boolean(context.inferredServiceRoleKey) : Boolean(context.apiToken),
     checks
   };
   return {
@@ -11448,15 +11795,15 @@ GLOBAL FLAGS
 DEFAULT CONTEXT
 
   Without a selector or project variables, runs use the current project's legacy .env.
-  Supported auto-link variables:
-    SUPABASE_URL / SUPACLOUD_API_URL
-    SUPABASE_SERVICE_ROLE_KEY / SUPACLOUD_API_TOKEN
-    SUPACLOUD_PROJECT_REF (when it cannot be inferred from <ref>.api.*)
+  Application status accepts SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY.
+  Management-backed project commands require SUPACLOUD_API_URL +
+  SUPACLOUD_API_TOKEN. These credential scopes are never mixed.
+  SUPACLOUD_PROJECT_REF is required when it cannot be inferred from <ref>.api.*.
 
   SUPACLOUD_READ_ONLY=true blocks remote writes. Production writes require an
   exact --confirm-production value, and cannot override the selected project ref.
 
-  status checks configuration, Management API connectivity, and authentication.
+  status checks configuration, the selected API scope, connectivity, and authentication.
   It exits non-zero when a required check fails.
 
   ${autoLink}
@@ -11487,6 +11834,7 @@ EXAMPLES
   ${preferredCommand} edge_functions deploy --ref abc123 --slug hello --prebundled-path ./dist/hello.js --expected-sha256 <sha256> --expected-active-version 4
   ${preferredCommand} edge_functions activate --ref abc123 --slug hello --version 3 --expected-active-version 4
   ${preferredCommand} scheduled_functions list --ref abc123
+  ${preferredCommand} mutations status --ref abc123 --mutation_id 00000000-0000-4000-8000-000000000001
   ${preferredCommand} edge_functions config --ref abc123 --slug hello --verify_jwt false --background_routes "/queue/*,/render/*"
   ${preferredCommand} secrets upsert --ref abc123 --from-env API_KEY,WEBHOOK_SECRET
   ${preferredCommand} gateway routes --ref abc123
@@ -11536,13 +11884,16 @@ function createCliTools(context, confirmProduction) {
           {
             type: "text",
             text: [
-              "⚠️ Project commands need a project-scoped API context.",
+              "⚠️ Project commands need a Management API context.",
               "",
               "Provide one of these sources:",
               "  - --env <name> for .env.supacloud.<name>",
               "  - --env-file <path> for a file declaring SUPACLOUD_ENV",
-              "  - .env with SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY",
               "  - SUPACLOUD_API_URL + SUPACLOUD_API_TOKEN",
+              "  - SUPACLOUD_PROJECT_REF when the profile cannot infer it",
+              "",
+              "SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY application profiles",
+              "are accepted only by status and local commands.",
               "",
               "Then retry commands such as:",
               `  ${preferredCommand} project get`,
@@ -11553,7 +11904,7 @@ function createCliTools(context, confirmProduction) {
         ]
       })
     };
-    for (const name of ["database", "auth", "storage", "edge_functions", "secrets", "frontend", "queue", "task_events", "scheduled_functions", "diagnostics", "gateway", "branch"]) {
+    for (const name of ["database", "auth", "storage", "edge_functions", "secrets", "frontend", "queue", "task_events", "scheduled_functions", "mutations", "diagnostics", "gateway", "branch"]) {
       tools[name] = {
         schema: { action: genericActionSchema },
         callback: async () => ({
@@ -11561,7 +11912,7 @@ function createCliTools(context, confirmProduction) {
           content: [
             {
               type: "text",
-              text: `⚠️ This command requires project-scoped API context. Run \`${preferredCommand} status\` to inspect current detection.`
+              text: `⚠️ This command requires Management API context. Run \`${preferredCommand} status\` to inspect current detection.`
             }
           ]
         })
@@ -11580,7 +11931,7 @@ function createCliTools(context, confirmProduction) {
       tools.branch = { schema: branchHelpTool.schema, callback: branchContextCallback };
     }
   };
-  if (!context.apiUrl || !context.apiToken) {
+  if (context.credentialScope !== "management" || !context.apiUrl || !context.apiToken) {
     registerContextAwareHelp();
     tools.setup_help = {
       schema: {},
@@ -11592,19 +11943,18 @@ function createCliTools(context, confirmProduction) {
             text: [
               `⚠️ No project context found for ${preferredCommand}.`,
               "",
-              `${preferredCommand} expects project-scoped credentials by default.`,
+              `${preferredCommand} remote tools require Management API credentials.`,
               "Provide one of these sources:",
               "",
               "  1. Named environment file",
               "     supacloud-cli --env test status",
               "",
-              "  2. Current workspace .env",
-              "     SUPABASE_URL=https://your-project.example.com",
-              "     SUPABASE_SERVICE_ROLE_KEY=...",
-              "",
-              "  3. Explicit environment variables",
+              "  2. Explicit environment variables",
               "     SUPACLOUD_API_URL=https://your-project.example.com",
               "     SUPACLOUD_API_TOKEN=...",
+              "     SUPACLOUD_PROJECT_REF=your-project-ref",
+              "",
+              "Application SUPABASE_* profiles remain available to status and local commands.",
               "",
               "For server installation and tenant management, use:",
               "  supacloud-admin"
@@ -11638,6 +11988,7 @@ function createCliTools(context, confirmProduction) {
   assign(captureTools((server) => registerScheduledFunctionTools(server, http, process.env, {
     readOnly: context.readOnly
   })));
+  assign(captureTools((server) => registerMutationTools(server, http)));
   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.17.0",
+  "version": "0.19.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",

package/skills/supacloud-cli/references/command-map.md

@@ -31,7 +31,7 @@ until a project-scoped context is resolved.
 - `supabase`: allowlisted official CLI adapter for migration authoring, local reset/diff, explicit-DSN inspection/backup/type generation, and SupaCloud-controlled migration push.
 - `auth`: provider and authentication configuration.
 - `storage`: buckets and object-management workflows.
-- `edge_functions`: list, read immutable source, deploy, activate, and configure Edge Functions. Pass the positive version read from `list` to `source --version` and as `--expected-active-version`; use `absent` only for a new slug. Version `0` is internal-only.
+- `edge_functions`: list, read immutable source, deploy, activate, and configure Edge Functions. Pass the non-negative version read from `list` as `--expected-active-version`; use `absent` only for a new slug. Version `0` is a legacy CAS token and cannot be used as a source or activation target.
 - `frontend`: list, build/deploy, domain, and deployment workflows.
 - `secrets`: project secret management; never print values after write.
 - `queue`, `task_events`, `diagnostics`: asynchronous workload operations and bounded diagnostics.