@supacloud/cli 0.11.0 → 0.12.1

package/README.md

@@ -65,8 +65,20 @@ supacloud-cli supabase migration_new --name add_accounts
 supacloud-cli supabase db_diff --schema public --name add_accounts
 supacloud-cli supabase push --ref abc123 --dir supabase/migrations --dry_run
 supacloud-cli frontend list --ref abc123
+supacloud-cli branch create --name feature-orders --data_mode schema_only
+supacloud-cli branch promotion_plan --branch_ref preview123
+supacloud-cli branch promote --branch_ref preview123 --plan_checksum <sha256>
 ```
 
+Branch promotion is migration-first. `branch promotion_plan` prints pending
+versions, names, statement counts, and checksums without echoing SQL into terminal
+logs; review the migration files or the Web Console SQL view before approval.
+`branch promote` requires the reviewed checksum, executes with the project-scoped
+database role, and does not automatically copy branch data.
+Use `--data_mode full_clone` only for an explicitly approved non-sensitive or
+masked debugging dataset. Whole-database replacement is an administrator-only
+break-glass API mode and is intentionally not exposed by this project CLI.
+
 ## Official Supabase CLI adapter
 
 The `supabase` command group is a thin, allowlisted adapter around the official

package/dist/index.js

@@ -6131,7 +6131,8 @@ async function runCli(cliTools, args, options = {}) {
     const otherFields = Object.entries(shape).filter(([name]) => name !== "action");
     const relevantFields = otherFields.filter(([, field]) => {
       const description = getDescription(field);
-      return description.includes(`[${action}]`) || description.includes("[*]");
+      const scopes = [...description.matchAll(/\[([^\]]+)\]/g)].flatMap((match) => match[1]?.split("/") || []);
+      return scopes.includes(action) || scopes.includes("*");
     });
     const argLines = relevantFields.length ? relevantFields.map(([name, field]) => `  --${name}  ${getDescription(field) || "(no description)"}`).join(`
 `) : "  (no documented action-specific flags)";
@@ -6476,6 +6477,12 @@ function appliedMigrationKeys(data) {
   }
   return keys;
 }
+function isAlreadyAppliedMigrationResponse(response) {
+  if (response.status !== 409 || !response.data || typeof response.data !== "object")
+    return false;
+  const body = response.data;
+  return body.code === "409" && body.message === "Migration already applied";
+}
 function sqlReferencesVector(sql) {
   return /\bvector\s*\(\s*\d+\s*\)/i.test(sql) || /::\s*vector\b/i.test(sql) || /\bvector_(cosine|l2|ip)_ops\b/i.test(sql) || /<=>|<#>|<->/.test(sql);
 }
@@ -6733,7 +6740,7 @@ Actions: ${allActions.join(", ")}${readOnly ? " (read-only mode)" : ""}`, {
           const r = await http.post(`/v1/projects/${ref}/database/migrations`, { name, sql, version });
           if (r.ok) {
             applied.push(file);
-          } else if (r.status === 409) {
+          } else if (isAlreadyAppliedMigrationResponse(r)) {
             skipped.push(file);
           } else {
             text = [
@@ -7771,7 +7778,7 @@ ${JSON.stringify(r.data, null, 2)}` : `❌ Failed (${r.status}): ${JSON.stringif
 import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
 import { basename as basename3 } from "node:path";
 function registerFrontendTools(server, http) {
-  server.tool("frontend", `Frontend hosting (static sites & SSR). Supports: static, react, vue, svelte, sveltekit, nextjs, nuxt, astro.
+  server.tool("frontend", `Frontend hosting (static sites & SSR). Supports: static, react, vue, svelte, sveltekit, sveltekit-static, nextjs, nuxt, astro.
 Actions: list, get, create, update, delete, deploy_git, deploy_upload, redeploy, build_logs, add_domain, remove_domain, set_env, list_frameworks, list_records`, {
     action: withDescription(stringEnum([
       "list",
@@ -7792,18 +7799,19 @@ Actions: list, get, create, update, delete, deploy_git, deploy_upload, redeploy,
     ref: optional(Type.String(), "Project ref"),
     id: optional(Type.String(), "Deployment ID"),
     name: optional(Type.String(), "[create] Deployment name"),
-    framework: optional(Type.String(), "[create] Framework (static|react|vue|svelte|sveltekit|nextjs|nuxt|astro)"),
+    framework: optional(Type.String(), "[create] Framework (static|react|vue|svelte|sveltekit|sveltekit-static|nextjs|nuxt|astro)"),
     domain: optional(Type.String(), "[create/update/add_domain/remove_domain] Custom domain"),
     build_command: optional(Type.String(), "[create/update] Build command override"),
     output_dir: optional(Type.String(), "[create/update] Output directory override"),
     install_command: optional(Type.String(), "[create/update] Install command override"),
     node_version: optional(Type.String(), "[create/update] Node.js version"),
+    health_check_path: optional(Type.String(), "[create/update] SSR readiness path (default: /)"),
     env_vars: optional(Type.Record(Type.String(), Type.String()), "[create/update/set_env] Environment variables"),
     git_url: optional(Type.String(), "[deploy_git] Git repository URL"),
     branch: optional(Type.String(), "[deploy_git] Branch (default: main)"),
     zip_path: optional(Type.String(), "[deploy_upload] Local zip file path")
   }, async (args) => {
-    const { action, ref, id, name, framework, domain, build_command, output_dir, install_command, node_version, env_vars, git_url, branch, zip_path } = args;
+    const { action, ref, id, name, framework, domain, build_command, output_dir, install_command, node_version, health_check_path, env_vars, git_url, branch, zip_path } = args;
     const need = (f, v) => {
       if (!v)
         throw new Error(`'${f}' required for '${action}'`);
@@ -7832,6 +7840,7 @@ Actions: list, get, create, update, delete, deploy_git, deploy_upload, redeploy,
           output_dir,
           install_command,
           node_version,
+          health_check_path,
           env_vars
         }));
         break;
@@ -7845,6 +7854,7 @@ Actions: list, get, create, update, delete, deploy_git, deploy_upload, redeploy,
           output_dir,
           install_command,
           node_version,
+          health_check_path,
           env_vars
         }));
         break;
@@ -8741,6 +8751,161 @@ Actions: routes, upsert_route, update_route, delete_route, config, get_certifica
   });
 }
 
+// src/shared/tools/branch-tools.ts
+function resolveProjectRef(ref, projectRef) {
+  const resolved = typeof ref === "string" && ref.trim() ? ref.trim() : projectRef || "";
+  if (!resolved)
+    throw new Error("'ref' is required for this action");
+  return resolved;
+}
+function requireString(value, field) {
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`'${field}' is required`);
+  return value.trim();
+}
+function responseError(result) {
+  if (result.data && typeof result.data === "object") {
+    const data = result.data;
+    const message = data.error || data.message;
+    if (typeof message === "string") {
+      const details = [message];
+      if (Array.isArray(data.applied) && data.applied.length > 0) {
+        const versions = data.applied.map((entry) => entry && typeof entry === "object" ? entry.version : null).filter((version) => typeof version === "string");
+        details.push(`Applied before failure: ${versions.join(", ") || data.applied.length}`);
+        details.push("Fetch a fresh promotion_plan before retrying.");
+      }
+      if (data.replacement_committed === true) {
+        details.push(`Database replacement committed; recovery is required${typeof data.backup_database === "string" ? ` using backup ${data.backup_database}` : ""}.`);
+      }
+      return details.join(`
+`);
+    }
+  }
+  return `Request failed with HTTP ${result.status}`;
+}
+function isPromotionPlan(candidate) {
+  if (!candidate || typeof candidate !== "object")
+    return false;
+  const plan = candidate;
+  return plan.mode === "migrations" && typeof plan.safe_to_apply === "boolean" && typeof plan.plan_checksum === "string" && Array.isArray(plan.pending) && Array.isArray(plan.applied) && Array.isArray(plan.blocked) && Array.isArray(plan.warnings) && typeof plan.requires_destructive_confirmation === "boolean";
+}
+function projectPath(ref) {
+  return `/v1/projects/${encodeURIComponent(ref)}/branches`;
+}
+function branchPath(ref, branchRef) {
+  return `${projectPath(ref)}/${encodeURIComponent(branchRef)}`;
+}
+function formatPromotionPlan(plan) {
+  const lines = [
+    `Migration promotion plan: ${plan.safe_to_apply ? "READY" : "BLOCKED"}`,
+    `Plan checksum: ${plan.plan_checksum}`,
+    `Pending: ${plan.pending.length}`,
+    `Already applied: ${plan.applied.length}`,
+    `Blocked: ${plan.blocked.length}`,
+    "Branch data will not be automatically copied to the parent project."
+  ];
+  if (plan.pending.length > 0) {
+    lines.push("", "Pending migrations:");
+    for (const migration of plan.pending) {
+      lines.push(`  - ${migration.version} ${migration.name || "(unnamed)"}` + ` checksum=${migration.checksum.slice(0, 12)}` + `${migration.destructive ? " destructive" : ""}`);
+    }
+  }
+  if (plan.blocked.length > 0) {
+    lines.push("", "Blocking findings:");
+    for (const blocked of plan.blocked)
+      lines.push(`  - [${blocked.code}] ${blocked.message}`);
+  }
+  if (plan.warnings.length > 0) {
+    lines.push("", "Warnings:", ...plan.warnings.map((warning) => `  - ${warning}`));
+  }
+  if (plan.requires_destructive_confirmation) {
+    lines.push("", "Re-run promote with --confirm_destructive true after reviewing destructive SQL.");
+  }
+  return lines.join(`
+`);
+}
+function readOnlyResult() {
+  return {
+    isError: true,
+    content: [{ type: "text", text: "⚠️ Branch write blocked in read-only mode." }]
+  };
+}
+function formatPromotionResult(responseValue) {
+  if (!responseValue || typeof responseValue !== "object")
+    return "Migrations promoted.";
+  const response = responseValue;
+  const applied = Array.isArray(response.applied) ? response.applied : [];
+  const versions = applied.map((entry) => entry && typeof entry === "object" ? entry.version : null).filter((version) => typeof version === "string");
+  return [
+    `Migration promotion completed: ${applied.length} applied.`,
+    ...versions.length > 0 ? [`Versions: ${versions.join(", ")}`] : [],
+    "Branch data was not automatically copied to the parent project."
+  ].join(`
+`);
+}
+function registerBranchTools(server, http, options = {}) {
+  server.tool("branch", "Preview branch lifecycle and safe migration promotion. Whole-database replacement is intentionally not exposed by this project CLI.", {
+    action: withDescription(stringEnum([
+      "list",
+      "create",
+      "delete",
+      "promotion_plan",
+      "promote"
+    ]), "Action to perform"),
+    ref: optional(Type.String(), "[*] Optional parent project override"),
+    branch_ref: optional(Type.String(), "[delete/promotion_plan/promote] Preview branch ref"),
+    name: optional(Type.String(), "[create] Branch name"),
+    data_mode: optional(stringEnum(["schema_only", "full_clone"]), "[create] Preview data mode (default: schema_only)"),
+    plan_checksum: optional(Type.String(), "[promote] Reviewed plan checksum from promotion_plan"),
+    confirm_destructive: optional(Type.Boolean(), "[promote] Confirm reviewed destructive migrations")
+  }, async (args) => {
+    const action = requireString(args.action, "action");
+    const ref = resolveProjectRef(args.ref, options.projectRef);
+    const writeAction = action === "create" || action === "delete" || action === "promote";
+    if (writeAction && options.readOnly)
+      return readOnlyResult();
+    let result;
+    if (action === "list") {
+      result = await http.get(projectPath(ref));
+    } else if (action === "create") {
+      const name = requireString(args.name, "name");
+      result = await http.post(projectPath(ref), {
+        name,
+        data_mode: args.data_mode === "full_clone" ? "full_clone" : "schema_only"
+      });
+    } else if (action === "delete") {
+      const branchRef = requireString(args.branch_ref, "branch_ref");
+      result = await http.delete(branchPath(ref, branchRef));
+    } else if (action === "promotion_plan") {
+      const branchRef = requireString(args.branch_ref, "branch_ref");
+      result = await http.get(`${branchPath(ref, branchRef)}/promote/plan`);
+      if (result.ok && isPromotionPlan(result.data)) {
+        return { content: [{ type: "text", text: formatPromotionPlan(result.data) }] };
+      }
+    } else if (action === "promote") {
+      const branchRef = requireString(args.branch_ref, "branch_ref");
+      const planChecksum = requireString(args.plan_checksum, "plan_checksum");
+      result = await http.post(`${branchPath(ref, branchRef)}/promote`, {
+        mode: "migrations",
+        plan_checksum: planChecksum,
+        confirm_destructive: args.confirm_destructive === true
+      });
+    } else {
+      throw new Error(`Unknown branch action: ${action}`);
+    }
+    if (!result.ok) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `❌ ${responseError(result)}` }]
+      };
+    }
+    if (action === "promote") {
+      return { content: [{ type: "text", text: formatPromotionResult(result.data) }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
+  });
+}
+
 // src/shared/tools/supabase-cli-tools.ts
 import { spawn } from "node:child_process";
 import { chmodSync, existsSync as existsSync5, mkdirSync, statSync as statSync3, writeFileSync as writeFileSync2 } from "node:fs";
@@ -9461,6 +9626,9 @@ EXAMPLES
   ${preferredCommand} supabase db_diff --schema public --name add_accounts
   ${preferredCommand} supabase push --ref abc123 --dir supabase/migrations --dry_run
   ${preferredCommand} supabase db_dump --db_url "postgresql://..." --file backups/schema.sql
+  ${preferredCommand} branch create --name feature-auth --data_mode schema_only
+  ${preferredCommand} branch promotion_plan --branch_ref preview123
+  ${preferredCommand} branch promote --branch_ref preview123 --plan_checksum <sha256>
   ${preferredCommand} ai show_skill
   ${preferredCommand} ai install_skill --dry_run
   ${preferredCommand} edge_functions deploy --ref abc123 --slug hello --path ./supabase/functions/hello
@@ -9517,7 +9685,7 @@ function createCliTools() {
         ]
       })
     };
-    for (const name of ["database", "auth", "storage", "edge_functions", "secrets", "frontend", "queue", "task_events", "diagnostics", "gateway"]) {
+    for (const name of ["database", "auth", "storage", "edge_functions", "secrets", "frontend", "queue", "task_events", "diagnostics", "gateway", "branch"]) {
       tools[name] = {
         schema: { action: genericActionSchema },
         callback: async () => ({
@@ -9531,6 +9699,13 @@ function createCliTools() {
         })
       };
     }
+    const branchContextCallback = tools.branch.callback;
+    const branchHelpTool = captureTools((server) => registerBranchTools(server, {}, {
+      readOnly: true
+    })).branch;
+    if (branchHelpTool) {
+      tools.branch = { schema: branchHelpTool.schema, callback: branchContextCallback };
+    }
   };
   if (!context.apiUrl || !context.apiToken) {
     registerContextAwareHelp();
@@ -9586,6 +9761,10 @@ function createCliTools() {
   assign(captureTools((server) => registerGatewayTools(server, http, {
     projectRef: context.projectRef || undefined
   })));
+  assign(captureTools((server) => registerBranchTools(server, http, {
+    projectRef: context.projectRef || undefined,
+    readOnly: context.readOnly
+  })));
   assign(captureTools((server) => registerQueueTools(server, http, {
     projectRef: context.projectRef || undefined
   })));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",