@supacloud/cli 0.18.0 → 0.20.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:
 
@@ -325,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"],
@@ -6580,6 +6572,15 @@ var RELEASE_MUTATION_RESPONSE_TIMEOUT = 5000;
 var RELEASE_MUTATION_RESPONSE_MAX_BYTES = 64 * 1024;
 var MAX_RETRIES = 2;
 var RETRY_BASE_DELAY = 500;
+function validatedGetResponseLimit(options) {
+  const maxBytes = options.maxResponseBytes;
+  if (maxBytes === undefined)
+    return;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new RangeError("HTTP response limit must be a positive safe integer");
+  }
+  return maxBytes;
+}
 function isRetryableMethod(method) {
   const normalizedMethod = (method ?? "GET").toUpperCase();
   return normalizedMethod === "GET" || normalizedMethod === "HEAD";
@@ -6614,7 +6615,8 @@ async function fetchWithTimeout(url, options) {
   try {
     return await fetch(url, {
       ...options,
-      signal: controller.signal
+      signal: controller.signal,
+      redirect: "error"
     });
   } finally {
     clearTimeout(timeout);
@@ -6794,12 +6796,13 @@ class HttpTransport {
     }
   }
   async get(path, options = {}) {
+    const maxResponseBytes = validatedGetResponseLimit(options);
     try {
       const res = await fetchWithRetry(`${this.baseUrl}${path}`, {
         method: "GET",
         headers: this.headers()
       });
-      const data = options.maxResponseBytes === undefined ? await res.json().catch(() => null) : await boundedResponseJson(res, options.maxResponseBytes);
+      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);
@@ -7964,14 +7967,15 @@ ${JSON.stringify(r.data, null, 2)}` : `❌ Failed (${r.status}): ${JSON.stringif
 var RELEASE_CONTROL_RESPONSE_SCHEMA = "supacloud.cli.release-control.v1";
 function releaseControlSuccess(operation, payload) {
   return releaseControlResponse({
+    ...payload,
     schema: RELEASE_CONTROL_RESPONSE_SCHEMA,
     ok: true,
-    operation,
-    ...payload
+    operation
   });
 }
-function releaseControlFailure(operation, code, httpStatus) {
+function releaseControlFailure(operation, code, httpStatus, safeState = {}) {
   return releaseControlErrorResponse({
+    ...safeState,
     schema: RELEASE_CONTROL_RESPONSE_SCHEMA,
     ok: false,
     operation,
@@ -9402,7 +9406,210 @@ Actions: list, get, create, update, delete, deploy_git, deploy_upload, redeploy,
   });
 }
 
+// src/shared/tools/project-read-projection.ts
+var PROJECT_READ_RESPONSE_MAX_BYTES = 1048576;
+var PROJECT_REF_PATTERN3 = /^[a-z0-9-]{1,20}$/;
+var SAFE_IDENTIFIER_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+var REGION_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+var STATUS_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+var DNS_LABEL_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+var DATABASE_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+var PROJECT_SUMMARY_KEYS = new Set([
+  "id",
+  "ref",
+  "organization_id",
+  "organization_slug",
+  "name",
+  "region",
+  "created_at",
+  "status"
+]);
+var PROJECT_DETAILS_KEYS = new Set([
+  ...PROJECT_SUMMARY_KEYS,
+  "database",
+  "api",
+  "studio",
+  "config",
+  "anon_key",
+  "services"
+]);
+var PROJECT_DATABASE_KEYS = new Set([
+  "host",
+  "version",
+  "postgres_engine",
+  "release_channel"
+]);
+var PROJECT_ENDPOINT_KEYS = new Set(["url"]);
+function plainRecord(candidate) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+    return null;
+  const prototype = Object.getPrototypeOf(candidate);
+  return prototype === Object.prototype || prototype === null ? candidate : null;
+}
+function hasOnlyKeys(record, allowedKeys) {
+  return Object.keys(record).every((key) => allowedKeys.has(key));
+}
+function hasWellFormedUnicode(text) {
+  for (let index = 0;index < text.length; index++) {
+    const codeUnit = text.charCodeAt(index);
+    if (codeUnit >= 55296 && codeUnit <= 56319) {
+      if (index + 1 >= text.length)
+        return false;
+      const lowSurrogate = text.charCodeAt(index + 1);
+      if (lowSurrogate < 56320 || lowSurrogate > 57343)
+        return false;
+      index++;
+    } else if (codeUnit >= 56320 && codeUnit <= 57343) {
+      return false;
+    }
+  }
+  return true;
+}
+function boundedText(candidate, maxLength) {
+  return typeof candidate === "string" && candidate.length > 0 && candidate.length <= maxLength && !/[\u0000-\u001f\u007f]/u.test(candidate) && hasWellFormedUnicode(candidate) ? candidate : null;
+}
+function matchingText(candidate, maxLength, pattern) {
+  const candidateText = boundedText(candidate, maxLength);
+  return candidateText && pattern.test(candidateText) ? candidateText : null;
+}
+function canonicalTimestamp(candidate) {
+  const timestamp = boundedText(candidate, 64);
+  if (!timestamp)
+    return null;
+  const milliseconds = Date.parse(timestamp);
+  return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === timestamp ? timestamp : null;
+}
+function projectedSummary(project) {
+  const summary = {
+    id: matchingText(project.id, 128, SAFE_IDENTIFIER_PATTERN),
+    ref: matchingText(project.ref, 20, PROJECT_REF_PATTERN3),
+    organization_id: matchingText(project.organization_id, 128, SAFE_IDENTIFIER_PATTERN),
+    organization_slug: matchingText(project.organization_slug, 128, SAFE_IDENTIFIER_PATTERN),
+    name: boundedText(project.name, 100),
+    region: matchingText(project.region, 64, REGION_PATTERN),
+    created_at: canonicalTimestamp(project.created_at),
+    status: matchingText(project.status, 64, STATUS_PATTERN)
+  };
+  return Object.values(summary).every((field) => field !== null) ? summary : null;
+}
+function databaseHost(candidate) {
+  const host = boundedText(candidate, 255);
+  if (!host)
+    return null;
+  if (host.startsWith("[") && host.endsWith("]")) {
+    try {
+      const parsedHost = new URL(`http://${host}`);
+      return parsedHost.host === host ? host : null;
+    } catch (error) {
+      if (error instanceof TypeError)
+        return null;
+      throw error;
+    }
+  }
+  const ipv4Parts = host.split(".");
+  if (ipv4Parts.length === 4 && ipv4Parts.every((part) => /^\d{1,3}$/u.test(part))) {
+    return ipv4Parts.every((part) => Number(part) <= 255) ? host : null;
+  }
+  return ipv4Parts.every((label) => DNS_LABEL_PATTERN.test(label)) ? host : null;
+}
+function projectDatabase(candidate) {
+  const database = plainRecord(candidate);
+  if (!database || !hasOnlyKeys(database, PROJECT_DATABASE_KEYS))
+    return null;
+  const host = databaseHost(database.host);
+  const version = matchingText(database.version, 64, DATABASE_VERSION_PATTERN);
+  const postgresEngine = matchingText(database.postgres_engine, 64, DATABASE_VERSION_PATTERN);
+  const releaseChannel = matchingText(database.release_channel, 64, DATABASE_VERSION_PATTERN);
+  return host && version && postgresEngine && releaseChannel ? { host, version, postgres_engine: postgresEngine, release_channel: releaseChannel } : null;
+}
+function rawUrlHasNoPath(candidate) {
+  if (candidate.trim() !== candidate || candidate.includes("\\"))
+    return false;
+  const schemeEnd = candidate.indexOf("://");
+  const pathStart = candidate.indexOf("/", schemeEnd + 3);
+  return pathStart === -1;
+}
+function projectEndpoint(candidate) {
+  const endpoint = plainRecord(candidate);
+  if (!endpoint || !hasOnlyKeys(endpoint, PROJECT_ENDPOINT_KEYS))
+    return null;
+  const endpointUrl = boundedText(endpoint.url, 2048);
+  if (!endpointUrl || !rawUrlHasNoPath(endpointUrl))
+    return null;
+  try {
+    const url = new URL(endpointUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.pathname !== "/")
+      return null;
+    return { url: url.origin };
+  } catch (error) {
+    if (error instanceof TypeError)
+      return null;
+    throw error;
+  }
+}
+function discardedDetailFieldsAreValid(project) {
+  if (project.config !== undefined && plainRecord(project.config) === null)
+    return false;
+  if (project.anon_key !== undefined && boundedText(project.anon_key, 16384) === null)
+    return false;
+  return project.services === undefined || Array.isArray(project.services);
+}
+function projectDetails(candidate, expectedRef) {
+  const project = plainRecord(candidate);
+  if (!project || !hasOnlyKeys(project, PROJECT_DETAILS_KEYS))
+    return null;
+  const summary = projectedSummary(project);
+  const database = projectDatabase(project.database);
+  const api = project.api === undefined ? undefined : projectEndpoint(project.api);
+  const studio = project.studio === undefined ? undefined : projectEndpoint(project.studio);
+  if (!summary || summary.ref !== expectedRef || !database || !discardedDetailFieldsAreValid(project) || project.api !== undefined && !api || project.studio !== undefined && !studio)
+    return null;
+  return {
+    ...summary,
+    database,
+    ...api ? { api } : {},
+    ...studio ? { studio } : {}
+  };
+}
+function payloadWithinLimit(candidate) {
+  try {
+    const serializedPayload = JSON.stringify(candidate);
+    return serializedPayload !== undefined && new TextEncoder().encode(serializedPayload).byteLength <= PROJECT_READ_RESPONSE_MAX_BYTES;
+  } catch {
+    return false;
+  }
+}
+function validHttpStatus(status) {
+  return Number.isSafeInteger(status) && status >= 100 && status <= 599;
+}
+function successfulResponse(response) {
+  return response.ok === true && validHttpStatus(response.status) && response.status >= 200 && response.status <= 299;
+}
+function failedResult(message) {
+  return { text: `❌ ${message}`, isError: true };
+}
+function failedHttpResult(label, status) {
+  return failedResult(validHttpStatus(status) ? `${label} request failed (${status})` : `${label} request failed`);
+}
+function successfulResult(payload) {
+  return { text: JSON.stringify(payload, null, 2), isError: false };
+}
+function projectGetRead(response, expectedRef) {
+  if (!successfulResponse(response))
+    return failedHttpResult("Project get", response.status);
+  if (!payloadWithinLimit(response.data))
+    return failedResult("Invalid project response");
+  const project = projectDetails(response.data, expectedRef);
+  return project ? successfulResult(project) : failedResult("Invalid project response");
+}
+
 // src/shared/tools/project-cli-tools.ts
+function projectReadResponse(readResult) {
+  return {
+    content: [{ type: "text", text: readResult.text }],
+    ...readResult.isError ? { isError: true } : {}
+  };
+}
 var formatTasks = (data) => {
   if (!Array.isArray(data))
     return JSON.stringify(data, null, 2);
@@ -9558,8 +9765,9 @@ Actions: get, health, logs, api_keys, settings, tasks, task_detail, task_cancel,
     let text;
     switch (action) {
       case "get":
-        text = ok(await http.get(`/v1/projects/${resolvedRef}`));
-        break;
+        return projectReadResponse(projectGetRead(await http.get(`/v1/projects/${resolvedRef}`, {
+          maxResponseBytes: PROJECT_READ_RESPONSE_MAX_BYTES
+        }), resolvedRef));
       case "health":
         text = ok(await http.get(`/v1/projects/${resolvedRef}/health`));
         break;
@@ -10655,10 +10863,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(`
 `)
     }]
@@ -10745,7 +10953,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",
@@ -11368,10 +11576,245 @@ 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 = /^v1\/(?:[a-z0-9][a-z0-9._-]{0,63})\/([A-Za-z0-9_-]{2,171})$/;
+var RESOURCE_ID_CONTROL_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
+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 MAX_RESOURCE_ID_BYTES = 128;
+var FATAL_UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+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 canonicalTimestamp2(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 || canonicalTimestamp2(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 canonicalMutationResourceKey(candidate) {
+  if (typeof candidate !== "string")
+    return false;
+  const match = RESOURCE_KEY_PATTERN.exec(candidate);
+  if (!match)
+    return false;
+  const encodedResourceId = match[1];
+  const resourceIdBytes = Buffer.from(encodedResourceId, "base64url");
+  if (resourceIdBytes.byteLength < 1 || resourceIdBytes.byteLength > MAX_RESOURCE_ID_BYTES || resourceIdBytes.toString("base64url") !== encodedResourceId)
+    return false;
+  let resourceId;
+  try {
+    resourceId = FATAL_UTF8_DECODER.decode(resourceIdBytes);
+  } catch (decodeError) {
+    if (decodeError instanceof TypeError)
+      return false;
+    throw decodeError;
+  }
+  return resourceId.trim() === resourceId && !RESOURCE_ID_CONTROL_PATTERN.test(resourceId) && Buffer.from(resourceId, "utf8").equals(resourceIdBytes);
+}
+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 && !canonicalMutationResourceKey(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) && canonicalTimestamp2(mutation.created_at) && canonicalTimestamp2(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);
+  }
+  if (readback.mutation.status !== "succeeded") {
+    return releaseControlFailure("mutations.status", "MUTATION_NOT_SUCCEEDED", null, {
+      project_ref: ref,
+      mutation: readback.mutation
+    });
+  }
+  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.18.0",
+  version: "0.20.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -11436,13 +11879,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);
@@ -11453,6 +11897,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,
@@ -11462,16 +11913,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
@@ -11480,21 +11957,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 {
@@ -11552,15 +12039,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}
@@ -11591,6 +12078,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
@@ -11640,13 +12128,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`,
@@ -11657,7 +12148,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 () => ({
@@ -11665,7 +12156,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.`
             }
           ]
         })
@@ -11684,7 +12175,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: {},
@@ -11696,19 +12187,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"
@@ -11742,6 +12232,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.18.0",
+  "version": "0.20.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",