@supacloud/cli 0.18.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:
 
@@ -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"],
@@ -6614,7 +6606,8 @@ async function fetchWithTimeout(url, options) {
   try {
     return await fetch(url, {
       ...options,
-      signal: controller.signal
+      signal: controller.signal,
+      redirect: "error"
     });
   } finally {
     clearTimeout(timeout);
@@ -10655,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(`
 `)
     }]
@@ -10745,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",
@@ -11368,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.18.0",
+  version: "0.19.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -11436,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);
@@ -11453,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,
@@ -11462,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
@@ -11480,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 {
@@ -11552,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}
@@ -11591,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
@@ -11640,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`,
@@ -11657,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 () => ({
@@ -11665,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.`
             }
           ]
         })
@@ -11684,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: {},
@@ -11696,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"
@@ -11742,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.18.0",
+  "version": "0.19.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",