spfn 0.3.0-beta.3 → 0.3.0-beta.5

package/dist/index.js

@@ -103,7 +103,7 @@ async function selectScaffoldMode(options) {
     choices: [
       {
         title: "full (recommended)",
-        description: "Core, auth, i18n, and MCP \u2014 ready for Prototype to Production",
+        description: "Core, auth, i18n, and ops CLI \u2014 ready for Prototype to Production",
         value: "full"
       },
       {
@@ -944,7 +944,7 @@ var init_deployment_config = __esm({
 
 // src/utils/version.ts
 function getCliVersion() {
-  return "0.3.0-beta.3";
+  return "0.3.0-beta.5";
 }
 function getTagFromVersion(version) {
   const match = version.match(/-([a-z]+)\./i);
@@ -988,7 +988,6 @@ async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManage
   if (mode === "full") {
     packageJson.dependencies["@spfn/auth"] = spfnTag;
     packageJson.dependencies["@spfn/i18n"] = spfnTag;
-    packageJson.dependencies["@spfn/mcp"] = spfnTag;
     packageJson.dependencies["@spfn/notification"] = spfnTag;
   }
   packageJson.devDependencies["@types/node"] = "^20.11.0";
@@ -1187,9 +1186,12 @@ SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v1:${randomSecret("base64")}
 # SPFN_AUTH_NAVER_CLIENT_ID=your-naver-client-id
 # SPFN_AUTH_NAVER_CLIENT_SECRET=your-naver-client-secret
 
-# Full scaffold: MCP operator endpoint
-SPFN_MCP_URL=http://localhost:8790
-SPFN_MCP_API_KEY=${randomSecret("base64url")}
+# Full scaffold: ops CLI (spfn ops)
+# Ops commands need no variable of their own \u2014 they authenticate with a token
+# issued by \`spfn ops token issue\`, and issuing one signs in as an administrator.
+# Uncomment to seed that administrator on the next server start, then remove the
+# password once the account exists.
+# SPFN_AUTH_ADMIN_ACCOUNTS=[{"email":"admin@example.com","password":"replace-with-a-strong-password","role":"admin"}]
 `;
 }
 function randomSecret(encoding) {
@@ -1419,9 +1421,12 @@ SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v1:replace-with-a-base64-encoded-32-byte-key
 # SPFN_AUTH_NAVER_CLIENT_ID=your-naver-client-id
 # SPFN_AUTH_NAVER_CLIENT_SECRET=your-naver-client-secret
 
-# Full scaffold: MCP operator endpoint
-SPFN_MCP_URL=http://localhost:8790
-SPFN_MCP_API_KEY=replace-with-a-random-operator-key
+# Full scaffold: ops CLI (spfn ops)
+# Ops commands need no variable of their own \u2014 they authenticate with a token
+# issued by \`spfn ops token issue\`, and issuing one signs in as an administrator.
+# Uncomment to seed that administrator on the next server start, then remove the
+# password once the account exists.
+# SPFN_AUTH_ADMIN_ACCOUNTS=[{"email":"admin@example.com","password":"replace-with-a-strong-password","role":"admin"}]
 `;
   }
 });
@@ -1752,7 +1757,7 @@ var init_function_migrations = __esm({
 });
 
 // src/index.ts
-import { Command as Command17 } from "commander";
+import { Command as Command18 } from "commander";
 
 // src/commands/create.ts
 init_logger();
@@ -5372,6 +5377,11 @@ envCommand.command("validate").description("Validate environment variables again
 import { Command as Command15 } from "commander";
 import chalk36 from "chalk";
 
+// src/utils/ops/plain.ts
+function plain(value) {
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+}
+
 // src/utils/ops/client.ts
 function joinUrl(appUrl, path5) {
   return appUrl.replace(/\/+$/, "") + path5;
@@ -5408,10 +5418,59 @@ async function fetchOpsManifest(appUrl, token) {
   if (manifest?.manifestVersion !== 1 || !Array.isArray(manifest.commands)) {
     throw new Error("The manifest answer has an unknown shape.");
   }
-  return { manifestVersion: 1, commands: usableCommands(manifest.commands) };
+  const modules = usableModules(manifest.modules);
+  return {
+    manifestVersion: 1,
+    ...manifest.modules !== void 0 ? { modules } : {},
+    commands: usableCommands(manifest.commands, new Set(modules.map((module) => module.id)))
+  };
 }
 var OPS_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+var OPS_EFFECTS = /* @__PURE__ */ new Set(["read", "write", "destructive"]);
+var MODULE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var CONTRACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/;
+var MAX_ID_LENGTH = 64;
+var MAX_SOURCE_LENGTH = 128;
+var MAX_SUMMARY_LENGTH = 500;
+var MAX_SCOPES = 64;
+var MAX_SCOPE_LENGTH = 128;
 var OPS_PATH_PREFIX = "/_ops/";
+var OPS_PATH_BASE = "https://spfn.invalid";
+function unstableOpsPathBecause(path5) {
+  let url;
+  try {
+    url = new URL(path5, OPS_PATH_BASE);
+  } catch {
+    return "is not a valid URL path";
+  }
+  if (url.origin !== OPS_PATH_BASE || url.search !== "" || url.hash !== "") {
+    return "is not a plain absolute path";
+  }
+  if (url.pathname !== path5) {
+    return "changes when URL-normalized";
+  }
+  if (!url.pathname.startsWith(OPS_PATH_PREFIX)) {
+    return `is outside ${OPS_PATH_PREFIX}`;
+  }
+  const slashCount = (path5.match(/\//g) ?? []).length;
+  let decoded = path5;
+  for (let depth = 0; depth < 8; depth++) {
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      return "contains malformed percent encoding";
+    }
+    if (next.includes("\\") || (next.match(/\//g) ?? []).length !== slashCount || next.split("/").some((segment) => segment === "." || segment === "..")) {
+      return "contains encoded path separators or dot segments";
+    }
+    if (next === decoded) {
+      return null;
+    }
+    decoded = next;
+  }
+  return "uses too many percent-encoding layers";
+}
 function unusableBecause(command) {
   if (typeof command?.name !== "string" || command.name.length === 0) {
     return "it has no name";
@@ -5419,15 +5478,16 @@ function unusableBecause(command) {
   if (typeof command.method !== "string" || !OPS_METHODS.has(command.method)) {
     return `its method is ${JSON.stringify(command.method)}`;
   }
-  if (typeof command.path !== "string" || !command.path.startsWith(OPS_PATH_PREFIX)) {
-    return `its path ${JSON.stringify(command.path)} is outside ${OPS_PATH_PREFIX}`;
+  if (typeof command.path !== "string") {
+    return `its path ${JSON.stringify(command.path)} is not a string`;
   }
-  if (command.path.split("/").includes("..")) {
-    return `its path ${JSON.stringify(command.path)} climbs out of the ops namespace`;
+  const pathReason = unstableOpsPathBecause(command.path);
+  if (pathReason !== null) {
+    return `its path ${JSON.stringify(command.path)} ${pathReason}`;
   }
   return null;
 }
-function usableCommands(commands) {
+function usableCommands(commands, moduleIds) {
   const usable = [];
   for (const command of commands) {
     const reason = unusableBecause(command);
@@ -5435,19 +5495,142 @@ function usableCommands(commands) {
       console.error(`\u26A0\uFE0F  Ignoring an ops command the manifest announced: ${reason}.`);
       continue;
     }
-    usable.push({ ...command, input: isPlainObject(command.input) ? command.input : {} });
+    const normalized = {
+      name: command.name,
+      method: command.method,
+      path: command.path,
+      input: isPlainObject(command.input) ? command.input : {}
+    };
+    const metadataReason = unusableModuleMetadataBecause(command, moduleIds);
+    if (metadataReason === null && command.module !== void 0) {
+      normalized.module = command.module;
+      normalized.summary = command.summary;
+      normalized.effect = command.effect;
+      normalized.scopes = [...command.scopes];
+    } else if (metadataReason !== null) {
+      normalized.metadataRejected = true;
+      console.error(
+        `\u26A0\uFE0F  Ignoring module metadata for ops command "${plain(command.name)}": ${metadataReason}. Calling it will require --yes.`
+      );
+    }
+    usable.push(normalized);
   }
   return usable;
 }
+function unusableModuleMetadataBecause(command, moduleIds) {
+  const carriesMetadata = command.module !== void 0 || command.summary !== void 0 || command.effect !== void 0 || command.scopes !== void 0;
+  if (!carriesMetadata) {
+    return null;
+  }
+  if (typeof command.module !== "string" || !moduleIds.has(command.module)) {
+    return "it names no usable module";
+  }
+  if (!command.name.startsWith(`${command.module}.`)) {
+    return "its qualified name does not start with the module id";
+  }
+  if (!command.path.startsWith(`${OPS_PATH_PREFIX}${command.module}/`)) {
+    return "its path is outside the module namespace";
+  }
+  if (typeof command.summary !== "string" || command.summary.length === 0 || command.summary.length > MAX_SUMMARY_LENGTH) {
+    return "its summary is missing or too long";
+  }
+  if (typeof command.effect !== "string" || !OPS_EFFECTS.has(command.effect)) {
+    return "its effect is unknown";
+  }
+  if (!Array.isArray(command.scopes) || command.scopes.length === 0 || command.scopes.length > MAX_SCOPES || command.scopes.some((scope) => typeof scope !== "string" || scope.length === 0 || scope.length > MAX_SCOPE_LENGTH)) {
+    return "its scopes are missing or invalid";
+  }
+  return null;
+}
+function usableModules(value) {
+  if (value === void 0) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    console.error("\u26A0\uFE0F  Ignoring ops module metadata: modules is not an array.");
+    return [];
+  }
+  const modules = [];
+  const claimed = /* @__PURE__ */ new Set();
+  for (const raw of value) {
+    const reason = unusableModuleBecause(raw, claimed);
+    if (reason !== null) {
+      console.error(`\u26A0\uFE0F  Ignoring an ops module the manifest announced: ${reason}.`);
+      continue;
+    }
+    const module = raw;
+    claimed.add(module.id);
+    modules.push({
+      id: module.id,
+      source: module.source,
+      contractVersion: module.contractVersion,
+      summary: module.summary
+    });
+  }
+  return modules;
+}
+function unusableModuleBecause(value, claimed) {
+  if (!isPlainObject(value)) {
+    return "it is not an object";
+  }
+  const id = value.id;
+  if (typeof id !== "string" || id.length > MAX_ID_LENGTH || !MODULE_ID.test(id)) {
+    return "its id is invalid";
+  }
+  if (claimed.has(id)) {
+    return `id "${id}" is duplicated`;
+  }
+  if (typeof value.source !== "string" || value.source.length === 0 || value.source.length > MAX_SOURCE_LENGTH) {
+    return `module "${id}" has an invalid source`;
+  }
+  if (typeof value.contractVersion !== "string" || !CONTRACT_VERSION.test(value.contractVersion)) {
+    return `module "${id}" has an invalid contract version`;
+  }
+  if (typeof value.summary !== "string" || value.summary.length === 0 || value.summary.length > MAX_SUMMARY_LENGTH) {
+    return `module "${id}" has an invalid summary`;
+  }
+  return null;
+}
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function climbsOutOfItsSegment(value) {
+  let decoded = value;
+  for (let depth = 0; depth < 8; depth++) {
+    if (decoded.split(/[/\\]/).some((part) => part === "." || part === "..")) {
+      return true;
+    }
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      return false;
+    }
+    if (next === decoded) {
+      return false;
+    }
+    decoded = next;
+  }
+  return true;
+}
 function buildCommandPath(command, params, query) {
+  const templateReason = unstableOpsPathBecause(command.path);
+  if (templateReason !== null) {
+    throw new Error(`Refusing ops command path ${JSON.stringify(command.path)} because it ${templateReason}.`);
+  }
   const path5 = command.path.replace(/:([A-Za-z0-9_]+)/g, (_match, name) => {
     const value = params[name];
     if (value === void 0) {
       throw new Error(`Missing path parameter "${name}" (pass --param ${name}=<value>).`);
     }
+    if (value === "") {
+      throw new Error(`Path parameter "${name}" cannot be empty.`);
+    }
+    if (climbsOutOfItsSegment(value)) {
+      throw new Error(
+        `Path parameter "${name}" contains dot segments and cannot be sent: ${JSON.stringify(value)}.`
+      );
+    }
     return encodeURIComponent(value);
   });
   const search = new URLSearchParams(query).toString();
@@ -5468,9 +5651,6 @@ function isSchema(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 var MAX_SCHEMA_DEPTH = 12;
-function plain(value) {
-  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
-}
 function typeName(schema) {
   if (Array.isArray(schema.enum)) {
     return schema.enum.every((v) => typeof v === "string") ? "string" : "value";
@@ -5556,6 +5736,13 @@ function renderSection(label, flag, rows) {
 function renderCommandUsage(command) {
   const lines = [`${plain(command.name)}  ${command.method} ${plain(command.path)}`, ""];
   let described = false;
+  if (command.summary) {
+    lines.push(`  ${plain(command.summary)}`, "");
+  }
+  if (command.effect || command.scopes) {
+    lines.push(`  Effect: ${command.effect ?? "unknown"}`);
+    lines.push(`  Scopes: ${command.scopes?.map(plain).join(", ") || "(not declared)"}`, "");
+  }
   for (const section of SECTIONS) {
     const schema = command.input[section.key];
     if (!isSchema(schema)) {
@@ -6018,18 +6205,68 @@ function inputSummary(command) {
   }
   return sections.length > 0 ? sections.join("+") : "-";
 }
+function moduleViews(manifest) {
+  return (manifest.modules ?? []).map((module) => {
+    const commands = manifest.commands.filter((command) => command.module === module.id);
+    return {
+      ...module,
+      commandCount: commands.length,
+      effects: [...new Set(commands.map((command) => command.effect).filter(Boolean))].sort()
+    };
+  });
+}
+async function listModules(options) {
+  const appUrl = resolveAppUrl(options);
+  const token = await resolveToken(options, appUrl);
+  const modules = moduleViews(await fetchOpsManifest(appUrl, token));
+  if (options.json) {
+    console.log(JSON.stringify(modules, null, 2));
+    return;
+  }
+  if (modules.length === 0) {
+    console.log(chalk36.yellow("The app exposes no capability ops modules."));
+    return;
+  }
+  console.log(chalk36.bold(`Ops modules at ${appUrl}:
+`));
+  for (const module of modules) {
+    const effects = module.effects.length > 0 ? module.effects.join(",") : "-";
+    console.log(
+      `  ${chalk36.cyan(plain(module.id))}  ${chalk36.gray(plain(module.source))}  contract: ${plain(module.contractVersion)}  commands: ${module.commandCount}  effects: ${effects}`
+    );
+    console.log(chalk36.gray(`    ${plain(module.summary)}`));
+  }
+}
 async function listCommands(options) {
   const appUrl = resolveAppUrl(options);
   const token = await resolveToken(options, appUrl);
   const manifest = await fetchOpsManifest(appUrl, token);
-  if (manifest.commands.length === 0) {
-    console.log(chalk36.yellow("The app exposes no ops commands."));
+  const commands = options.module ? manifest.commands.filter((command) => command.module === options.module) : manifest.commands;
+  if (options.module && !(manifest.modules ?? []).some((module) => module.id === options.module)) {
+    console.error(chalk36.red(`\u274C Unknown ops module "${plain(options.module)}".`));
+    console.error(chalk36.gray(
+      `   Known: ${(manifest.modules ?? []).map((module) => plain(module.id)).join(", ") || "(none)"}`
+    ));
+    process.exit(1);
+  }
+  if (options.json) {
+    console.log(JSON.stringify(commands, null, 2));
+    return;
+  }
+  if (commands.length === 0) {
+    console.log(chalk36.yellow(options.module ? `The "${plain(options.module)}" module exposes no ops commands.` : "The app exposes no ops commands."));
     return;
   }
   console.log(chalk36.bold(`Ops commands at ${appUrl}:
 `));
-  for (const command of manifest.commands) {
-    console.log(`  ${chalk36.cyan(plain(command.name))}  ${chalk36.gray(`${command.method} ${plain(command.path)}`)}  input: ${inputSummary(command)}`);
+  for (const command of commands) {
+    const effect = command.effect ? `  effect: ${command.effect}` : "";
+    console.log(
+      `  ${chalk36.cyan(plain(command.name))}  ${chalk36.gray(`${command.method} ${plain(command.path)}`)}  input: ${inputSummary(command)}${effect}`
+    );
+    if (command.summary) {
+      console.log(chalk36.gray(`    ${plain(command.summary)}`));
+    }
   }
   console.log(chalk36.gray(`
 \u{1F4A1} Invoke: spfn ops call <name> [--param k=v] [--query k=v] [--data '{"..."}']`));
@@ -6049,6 +6286,12 @@ async function callCommand(name, options) {
     console.log(options.json ? JSON.stringify(command, null, 2) : renderCommandUsage(command));
     return;
   }
+  if (destructiveConfirmationRequired(command, options.yes)) {
+    console.error(command.metadataRejected ? chalk36.red(`\u274C "${plain(name)}" announced metadata this CLI refused, so its effect is unknown.`) : chalk36.red(`\u274C "${plain(name)}" is destructive and was not called with --yes.`));
+    console.error(chalk36.gray(`   Review it first: spfn ops call ${plain(name)} --describe`));
+    console.error(chalk36.gray("   Then re-run with --yes."));
+    process.exit(1);
+  }
   let body;
   if (options.data !== void 0) {
     if (command.method === "GET") {
@@ -6077,9 +6320,16 @@ async function callCommand(name, options) {
   console.error(rendered);
   process.exit(1);
 }
+function destructiveConfirmationRequired(command, confirmed) {
+  if (confirmed === true) {
+    return false;
+  }
+  return command.effect === "destructive" || command.metadataRejected === true;
+}
 var opsCommand = new Command15("ops").description("Invoke the app's ops surface (discovered from /_ops/_manifest)");
-opsCommand.command("list").description("List the ops commands the app exposes").option("--app <url>", "app URL (or SPFN_OPS_APP)").option("--token <token>", "ops token (or SPFN_OPS_TOKEN, or keychain)").action(listCommands);
-opsCommand.command("call <name>").description("Invoke one ops command").option("--app <url>", "app URL (or SPFN_OPS_APP)").option("--token <token>", "ops token (or SPFN_OPS_TOKEN, or keychain)").option("--param <k=v>", "path parameter (repeatable)", collectKeyValue, {}).option("--query <k=v>", "query parameter (repeatable)", collectKeyValue, {}).option("--data <json>", "JSON request body").option("--describe", "print the command's usage instead of calling it").option("--json", "with --describe, print the raw JSON Schema").action(callCommand).addHelpText("after", "\nA command's own inputs: spfn ops call <name> --describe");
+opsCommand.command("modules").description("List explicitly mounted capability ops modules").option("--app <url>", "app URL (or SPFN_OPS_APP)").option("--token <token>", "ops token (or SPFN_OPS_TOKEN, or keychain)").option("--json", "print machine-readable JSON").action(listModules);
+opsCommand.command("list").description("List the ops commands the app exposes").option("--app <url>", "app URL (or SPFN_OPS_APP)").option("--token <token>", "ops token (or SPFN_OPS_TOKEN, or keychain)").option("--module <id>", "show commands from one capability module").option("--json", "print machine-readable JSON").action(listCommands);
+opsCommand.command("call <name>").description("Invoke one ops command").option("--app <url>", "app URL (or SPFN_OPS_APP)").option("--token <token>", "ops token (or SPFN_OPS_TOKEN, or keychain)").option("--param <k=v>", "path parameter (repeatable)", collectKeyValue, {}).option("--query <k=v>", "query parameter (repeatable)", collectKeyValue, {}).option("--data <json>", "JSON request body").option("--describe", "print the command's usage instead of calling it").option("--json", "with --describe, print the raw JSON Schema").option("--yes", "confirm an effect=destructive command").action(callCommand).addHelpText("after", "\nA command's own inputs: spfn ops call <name> --describe");
 opsCommand.addCommand(buildTokenCommand());
 
 // src/commands/secret/index.ts
@@ -6664,9 +6914,1002 @@ secretCommand.command("keygen").description("Generate an age key pair for SOPS (
 secretCommand.command("recipients <action> [key]").description("Manage .sops.yaml age recipients: add | remove | list").action(secretRecipients);
 secretCommand.command("check").description("Static hygiene lint \u2014 flag plaintext secret leaks").option(...PKG_OPTION).action(secretCheck);
 
+// src/commands/cloud/index.ts
+import { Command as Command17 } from "commander";
+
+// src/commands/cloud/link.ts
+init_logger();
+import { basename as basename2 } from "path";
+import prompts12 from "prompts";
+import chalk44 from "chalk";
+
+// src/utils/cloud/tokens.ts
+var TOKEN_KEYS = {
+  vercel: "CLOUD_VERCEL_TOKEN",
+  supabase: "CLOUD_SUPABASE_TOKEN"
+};
+async function availableStore() {
+  const store = detectStore();
+  if (!await store.isAvailable()) {
+    throw new Error(
+      `${store.label} is unavailable on this machine, and cloud tokens are stored nowhere else. On Windows install \`@napi-rs/keyring\`; on headless Linux no keyring daemon is present.`
+    );
+  }
+  return store;
+}
+async function storeCloudToken(provider, value) {
+  const store = await availableStore();
+  await store.set(keychainName(TOKEN_KEYS[provider]), value);
+}
+async function getCloudToken(provider) {
+  const store = await availableStore();
+  return store.get(keychainName(TOKEN_KEYS[provider]));
+}
+async function requireCloudToken(provider) {
+  const token = await getCloudToken(provider);
+  if (!token) {
+    throw new Error(`No ${provider} token is stored. Run \`spfn cloud link\` first.`);
+  }
+  return token;
+}
+async function deleteCloudToken(provider) {
+  const store = await availableStore();
+  await store.delete(keychainName(TOKEN_KEYS[provider]));
+}
+
+// src/utils/cloud/config.ts
+init_env_file();
+import { existsSync as existsSync31, mkdirSync as mkdirSync7, readFileSync as readFileSync13, writeFileSync as writeFileSync20 } from "fs";
+import { dirname as dirname6, join as join31 } from "path";
+var CONFIG_REL_PATH = join31(".spfn", "cloud.json");
+function cloudConfigPath(cwd) {
+  return join31(cwd, CONFIG_REL_PATH);
+}
+function readCloudConfig(cwd) {
+  const path5 = cloudConfigPath(cwd);
+  if (!existsSync31(path5)) {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync13(path5, "utf-8"));
+  } catch {
+    throw new Error(`${path5} is not valid JSON \u2014 delete it and run \`spfn cloud link\` again.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path5} does not contain a JSON object \u2014 delete it and run \`spfn cloud link\` again.`);
+  }
+  return parsed;
+}
+function writeCloudConfig(cwd, config) {
+  const path5 = cloudConfigPath(cwd);
+  mkdirSync7(dirname6(path5), { recursive: true });
+  writeFileSync20(path5, JSON.stringify(config, null, 4) + "\n", "utf-8");
+  ensureGitignored(cwd, [{ pattern: ".spfn/cloud.json", comment: "spfn cloud link state (per-user accounts)" }]);
+}
+function requireLinked(config, provider) {
+  const linked = config[provider];
+  if (!linked) {
+    throw new Error(`No ${provider} project is linked. Run \`spfn cloud link\` first.`);
+  }
+  return linked;
+}
+
+// src/utils/cloud/http.ts
+var REQUEST_TIMEOUT_MS = 3e4;
+async function cloudFetch(url, init) {
+  const response = await fetch(url, {
+    method: init.method ?? "GET",
+    headers: {
+      Authorization: `Bearer ${init.token}`,
+      ...init.body !== void 0 ? { "Content-Type": "application/json" } : {}
+    },
+    body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (init.allowNotFound && response.status === 404) {
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(await describeFailure(url, init.provider, response));
+  }
+  return response;
+}
+async function cloudFetchJson(url, init) {
+  const response = await cloudFetch(url, init);
+  return await response.json();
+}
+async function describeFailure(url, provider, response) {
+  const hint = response.status === 401 || response.status === 403 ? " The stored token may be invalid or expired \u2014 run `spfn cloud link --replace` to enter a new one." : "";
+  return `${provider} API responded ${response.status} for ${new URL(url).pathname}.${hint}${await bodyMessage(response)}`;
+}
+async function bodyMessage(response) {
+  try {
+    const body = await response.json();
+    const message = body.error?.message ?? body.message;
+    return message ? ` (${message})` : "";
+  } catch {
+    return "";
+  }
+}
+
+// src/utils/cloud/vercel-api.ts
+var BASE = "https://api.vercel.com";
+var PROVIDER = "Vercel";
+async function getVercelUser(token) {
+  return cloudFetchJson(`${BASE}/v2/user`, { token, provider: PROVIDER });
+}
+async function listVercelProjects(token, teamId) {
+  const query = teamId ? `?teamId=${encodeURIComponent(teamId)}` : "";
+  const data = await cloudFetchJson(`${BASE}/v9/projects${query}`, { token, provider: PROVIDER });
+  return data.projects;
+}
+async function getVercelUsage(token, from, to, teamId) {
+  const params = new URLSearchParams({ from: from.toISOString(), to: to.toISOString() });
+  if (teamId) {
+    params.set("teamId", teamId);
+  }
+  const response = await cloudFetch(`${BASE}/v1/billing/charges?${params}`, { token, provider: PROVIDER, allowNotFound: true });
+  if (response === null) {
+    return [];
+  }
+  const body = await response.text();
+  if (!focusFeedReadable(body)) {
+    throw new Error("Vercel billing feed answered in an unrecognized shape \u2014 usage is unavailable, not zero.");
+  }
+  return aggregateFocusCharges(body);
+}
+function focusFeedReadable(body) {
+  const lines = body.split("\n").filter((line) => line.trim() !== "");
+  return lines.length === 0 || lines.some((line) => Boolean(parseFocusLine(line)?.ServiceName));
+}
+function aggregateFocusCharges(jsonl) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const line of jsonl.split("\n")) {
+    const record = parseFocusLine(line);
+    if (!record?.ServiceName) {
+      continue;
+    }
+    const consumed = Number(record.ConsumedQuantity ?? 0);
+    if (!Number.isFinite(consumed) || consumed === 0) {
+      continue;
+    }
+    const unit = record.ConsumedUnit ?? "";
+    const key = `${record.ServiceName}\0${unit}`;
+    const existing = totals.get(key);
+    if (existing) {
+      existing.consumed += consumed;
+    } else {
+      totals.set(key, { serviceName: record.ServiceName, consumed, unit });
+    }
+  }
+  return [...totals.values()].sort((a, b) => a.serviceName.localeCompare(b.serviceName));
+}
+function parseFocusLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+async function upsertVercelEnvVars(token, projectId, vars, teamId) {
+  const query = new URLSearchParams({ upsert: "true" });
+  if (teamId) {
+    query.set("teamId", teamId);
+  }
+  const response = await cloudFetch(`${BASE}/v10/projects/${encodeURIComponent(projectId)}/env?${query}`, {
+    method: "POST",
+    token,
+    provider: PROVIDER,
+    body: vars
+  });
+  return { failed: extractEnvPushFailures(await response.json().catch(() => null)) };
+}
+function extractEnvPushFailures(body) {
+  const failed = body?.failed;
+  if (!Array.isArray(failed)) {
+    return [];
+  }
+  return failed.map((item) => {
+    const error = item?.error;
+    return {
+      key: error?.key ?? error?.envVarKey ?? "unknown key",
+      message: error?.message ?? "rejected by Vercel"
+    };
+  });
+}
+
+// src/utils/cloud/supabase-api.ts
+var BASE2 = "https://api.supabase.com";
+var PROVIDER2 = "Supabase";
+async function listSupabaseOrganizations(token) {
+  return cloudFetchJson(`${BASE2}/v1/organizations`, { token, provider: PROVIDER2 });
+}
+async function listSupabaseProjects(token) {
+  return cloudFetchJson(`${BASE2}/v1/projects`, { token, provider: PROVIDER2 });
+}
+async function getSupabaseProject(token, ref) {
+  return cloudFetchJson(`${BASE2}/v1/projects/${encodeURIComponent(ref)}`, { token, provider: PROVIDER2 });
+}
+async function getSupabaseApiKeys(token, ref) {
+  return cloudFetchJson(
+    `${BASE2}/v1/projects/${encodeURIComponent(ref)}/api-keys`,
+    { token, provider: PROVIDER2 }
+  );
+}
+async function getSupabasePoolerConfigs(token, ref) {
+  return cloudFetchJson(
+    `${BASE2}/v1/projects/${encodeURIComponent(ref)}/config/database/pooler`,
+    { token, provider: PROVIDER2 }
+  );
+}
+async function runSupabaseQuery(token, ref, query) {
+  return cloudFetchJson(`${BASE2}/v1/projects/${encodeURIComponent(ref)}/database/query`, {
+    method: "POST",
+    token,
+    provider: PROVIDER2,
+    body: { query }
+  });
+}
+async function getSupabaseDbSizeBytes(token, ref) {
+  const rows = await runSupabaseQuery(
+    token,
+    ref,
+    "select pg_database_size(current_database())::bigint as total_bytes;"
+  );
+  return extractDbSizeBytes(rows);
+}
+function extractDbSizeBytes(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return null;
+  }
+  const value = rows[0].total_bytes;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+async function getSupabaseDailyApiCount(token, ref) {
+  const data = await cloudFetchJson(
+    `${BASE2}/v1/projects/${encodeURIComponent(ref)}/analytics/endpoints/usage.api-counts?interval=1day`,
+    { token, provider: PROVIDER2 }
+  );
+  return sumApiCounts(data);
+}
+function sumApiCounts(data) {
+  const result = data?.result;
+  if (!Array.isArray(result)) {
+    return null;
+  }
+  let total = 0;
+  let found = false;
+  for (const row of result) {
+    for (const [field, value] of Object.entries(row)) {
+      if (field !== "count" && !field.startsWith("total_")) {
+        continue;
+      }
+      const count = Number(value);
+      if (Number.isFinite(count)) {
+        total += count;
+        found = true;
+      }
+    }
+  }
+  return found ? total : null;
+}
+
+// src/commands/cloud/link.ts
+async function cloudLink(options) {
+  const cwd = process.cwd();
+  try {
+    const config = readCloudConfig(cwd);
+    await linkVercel(config, cwd, options);
+    writeCloudConfig(cwd, config);
+    await linkSupabase(config, options);
+    writeCloudConfig(cwd, config);
+  } catch (error) {
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+  logger.success(`Link state saved to ${chalk44.cyan(cloudConfigPath(cwd))} (identifiers only \u2014 tokens stay in the keychain).`);
+  logger.info("Next: `spfn cloud status` for limits vs usage, `spfn cloud env pull` for project keys.");
+}
+async function linkVercel(config, cwd, options) {
+  const token = await obtainToken("vercel", "Vercel access token", "VERCEL_TOKEN", "https://vercel.com/account/settings/tokens", options.replace);
+  const user = await getVercelUser(token);
+  logger.success(`Vercel token verified (account: ${user.user.username}).`);
+  await storeCloudToken("vercel", token);
+  const projects = await listVercelProjects(token);
+  if (projects.length === 0) {
+    logger.warn("No Vercel projects found \u2014 deploy once, then re-run `spfn cloud link`.");
+    return;
+  }
+  let projectId;
+  if (options.vercelProject) {
+    projectId = projects.find((p) => p.name === options.vercelProject || p.id === options.vercelProject)?.id;
+    if (!projectId) {
+      throw new Error(`No Vercel project named "${options.vercelProject}" \u2014 available: ${projects.map((p) => p.name).join(", ")}.`);
+    }
+  } else {
+    const defaultIndex = Math.max(0, projects.findIndex((p) => p.name === basename2(cwd)));
+    ({ projectId } = await prompts12({
+      type: "select",
+      name: "projectId",
+      message: "Which Vercel project is this app?",
+      initial: defaultIndex,
+      choices: projects.map((p) => ({ title: p.name, value: p.id }))
+    }));
+  }
+  if (!projectId) {
+    throw new Error("Cancelled \u2014 no Vercel project selected.");
+  }
+  const project = projects.find((p) => p.id === projectId);
+  config.vercel = { projectId: project.id, projectName: project.name };
+  logger.success(`Vercel project linked: ${project.name}`);
+}
+async function linkSupabase(config, options) {
+  const token = await obtainToken("supabase", "Supabase personal access token", "SUPABASE_ACCESS_TOKEN", "https://supabase.com/dashboard/account/tokens", options.replace);
+  const orgs = await listSupabaseOrganizations(token);
+  logger.success(`Supabase token verified (${orgs.length} organization${orgs.length === 1 ? "" : "s"}).`);
+  await storeCloudToken("supabase", token);
+  const projects = await listSupabaseProjects(token);
+  if (projects.length === 0) {
+    logger.warn("No Supabase projects found \u2014 create one, then re-run `spfn cloud link`.");
+    return;
+  }
+  let ref;
+  if (options.supabaseProject) {
+    const match = projects.find((p) => projectRef(p) === options.supabaseProject || p.name === options.supabaseProject);
+    if (!match) {
+      throw new Error(`No Supabase project "${options.supabaseProject}" \u2014 available: ${projects.map((p) => p.name).join(", ")}.`);
+    }
+    ref = projectRef(match);
+  } else {
+    ({ ref } = await prompts12({
+      type: "select",
+      name: "ref",
+      message: "Which Supabase project is this app?",
+      choices: projects.map((p) => ({ title: `${p.name} (${p.region}, ${p.status})`, value: projectRef(p) }))
+    }));
+  }
+  if (!ref) {
+    throw new Error("Cancelled \u2014 no Supabase project selected.");
+  }
+  const project = projects.find((p) => projectRef(p) === ref);
+  const org = orgs.find((o) => o.id === project.organization_id);
+  config.supabase = {
+    projectRef: ref,
+    projectName: project.name,
+    orgSlug: org?.slug ?? project.organization_id,
+    region: project.region
+  };
+}
+function projectRef(project) {
+  return project.ref ?? project.id;
+}
+async function obtainToken(provider, label, envVar, createUrl, replace) {
+  if (replace) {
+    await deleteCloudToken(provider);
+    logger.info(`Stored ${label} discarded${process.env[envVar] ? ` (ignoring ${envVar})` : ""} \u2014 enter a fresh one.`);
+  } else {
+    const fromEnv = process.env[envVar];
+    if (fromEnv) {
+      logger.info(`Using ${label} from ${envVar} (value not shown).`);
+      return fromEnv;
+    }
+    const fromKeychain = await getCloudToken(provider);
+    if (fromKeychain) {
+      logger.info(`Using the ${label} already in the keychain (value not shown). To enter a new one, run \`spfn cloud link --replace\`.`);
+      return fromKeychain;
+    }
+  }
+  logger.info(`Create one at ${chalk44.cyan(createUrl)} if you don't have it yet.`);
+  const { token } = await prompts12({
+    type: "password",
+    name: "token",
+    message: label
+  });
+  if (!token) {
+    throw new Error(`Cancelled \u2014 no ${label} entered.`);
+  }
+  return token;
+}
+
+// src/commands/cloud/limits.ts
+import chalk46 from "chalk";
+
+// src/utils/cloud/limits-data.ts
+var VERCEL_HOBBY_LIMITS = [
+  { key: "fast-data-transfer", label: "Fast data transfer", limit: 100, unit: "GB", per: "month" },
+  { key: "function-invocations", label: "Function invocations", limit: 1e6, unit: "invocations", per: "month" },
+  { key: "active-cpu", label: "Active CPU", limit: 4, unit: "CPU-hours", per: "month" },
+  { key: "provisioned-memory", label: "Provisioned memory", limit: 360, unit: "GB-hours", per: "month" },
+  { key: "edge-requests", label: "Edge requests", limit: 1e6, unit: "requests", per: "month" },
+  { key: "image-transformations", label: "Image transformations", limit: 5e3, unit: "transformations", per: "month" },
+  { key: "deployments", label: "Deployments", limit: 100, unit: "deploys", per: "day" },
+  { key: "concurrent-builds", label: "Concurrent builds", limit: 1, unit: "build", per: "concurrent" }
+];
+var SUPABASE_FREE_LIMITS = [
+  { key: "db-size", label: "Database size (per project)", limit: 500, unit: "MB", per: "total" },
+  { key: "egress", label: "Egress", limit: 5, unit: "GB", per: "month" },
+  { key: "cached-egress", label: "Cached egress", limit: 5, unit: "GB", per: "month" },
+  { key: "mau", label: "Monthly active users", limit: 5e4, unit: "MAU", per: "month" },
+  { key: "storage", label: "File storage", limit: 1, unit: "GB", per: "total" },
+  { key: "edge-invocations", label: "Edge function invocations", limit: 5e5, unit: "invocations", per: "month" },
+  { key: "realtime-connections", label: "Realtime connections", limit: 200, unit: "connections", per: "concurrent" },
+  { key: "realtime-messages", label: "Realtime messages", limit: 2e6, unit: "messages", per: "month" },
+  { key: "active-projects", label: "Active free projects (per org)", limit: 2, unit: "projects", per: "total" }
+];
+var VERCEL_HOBBY_NOTES = [
+  "Cron jobs: at most one, at most once per day (finer schedules fail the deploy).",
+  "Runtime logs are kept for 1 hour.",
+  "Over a limit, the capability pauses until rolling 30-day usage drops back under it \u2014 Hobby is never billed.",
+  "Hobby is for personal, non-commercial use; monetized apps need Pro or a migration."
+];
+var SUPABASE_FREE_NOTES = [
+  "Quota is summed per organization (except database size) \u2014 other projects in the same org share it.",
+  "Projects pause after ~7 idle days; a few DB requests per day keeps one active (1-year restore window).",
+  "No automatic backups; log retention is 1 day.",
+  "Over quota: notification, grace until the end of the billing cycle, then org-wide restrictions."
+];
+var LIMITS_VERIFIED_ON = "2026-08-13";
+
+// src/utils/cloud/format.ts
+import chalk45 from "chalk";
+var MIGRATION_PROMPT_THRESHOLD = 0.8;
+function formatPercent(used, limit) {
+  if (limit <= 0) {
+    return chalk45.dim("n/a");
+  }
+  const ratio = used / limit;
+  const text = `${(ratio * 100).toFixed(1)}%`;
+  if (ratio >= 1) {
+    return chalk45.red.bold(text);
+  }
+  if (ratio >= MIGRATION_PROMPT_THRESHOLD) {
+    return chalk45.yellow.bold(text);
+  }
+  return chalk45.green(text);
+}
+function isNearLimit(used, limit) {
+  return limit > 0 && used / limit >= MIGRATION_PROMPT_THRESHOLD;
+}
+var BYTES_PER_MB = 1e6;
+function formatBytes2(bytes) {
+  if (bytes < 1e3) return `${bytes} B`;
+  if (bytes < BYTES_PER_MB) return `${(bytes / 1e3).toFixed(1)} KB`;
+  if (bytes < 1e3 * BYTES_PER_MB) return `${(bytes / BYTES_PER_MB).toFixed(1)} MB`;
+  return `${(bytes / (1e3 * BYTES_PER_MB)).toFixed(2)} GB`;
+}
+function sameUnit(reported, limitUnit) {
+  return reported === "" || reported.trim().toLowerCase() === limitUnit.trim().toLowerCase();
+}
+function formatCount(value) {
+  return value.toLocaleString("en-US");
+}
+function usageLine(label, used, limit, unit) {
+  const percent = formatPercent(used, limit);
+  const amounts = `${formatCount(round(used))} / ${formatCount(limit)} ${unit}`;
+  return `  ${label.padEnd(34)} ${amounts.padEnd(32)} ${percent}`;
+}
+function round(value) {
+  return Number.isInteger(value) ? value : Number(value.toFixed(2));
+}
+
+// src/commands/cloud/limits.ts
+var PER_LABEL = {
+  month: "/ month",
+  day: "/ day",
+  concurrent: "concurrent",
+  total: "total"
+};
+async function cloudLimits() {
+  printPlan("Vercel Hobby", VERCEL_HOBBY_LIMITS, VERCEL_HOBBY_NOTES);
+  printPlan("Supabase Free", SUPABASE_FREE_LIMITS, SUPABASE_FREE_NOTES);
+  console.log(chalk46.dim(`Numbers verified against the official docs on ${LIMITS_VERIFIED_ON}.`));
+  console.log(chalk46.dim("Live usage against these limits: `spfn cloud status`.\n"));
+}
+function printPlan(title, limits, notes) {
+  console.log(chalk46.bold(`
+${title}`));
+  for (const limit of limits) {
+    const amount = `${formatCount(limit.limit)} ${limit.unit}`;
+    console.log(`  ${limit.label.padEnd(34)} ${amount.padEnd(26)} ${chalk46.dim(PER_LABEL[limit.per])}`);
+  }
+  for (const note of notes) {
+    console.log(chalk46.dim(`  \u2022 ${note}`));
+  }
+  console.log("");
+}
+
+// src/commands/cloud/usage.ts
+init_logger();
+import chalk47 from "chalk";
+
+// src/commands/cloud/collect.ts
+async function collectSnapshot(cwd) {
+  let config;
+  try {
+    config = readCloudConfig(cwd);
+  } catch (error) {
+    return {
+      config: {},
+      vercel: null,
+      supabase: null,
+      problems: [error instanceof Error ? error.message : String(error)]
+    };
+  }
+  const snapshot = { config, vercel: null, supabase: null, problems: [] };
+  await Promise.all([
+    collectVercel(config, snapshot),
+    collectSupabase(config, snapshot)
+  ]);
+  return snapshot;
+}
+async function collectVercel(config, snapshot) {
+  try {
+    const linked = requireLinked(config, "vercel");
+    const token = await requireCloudToken("vercel");
+    const to = /* @__PURE__ */ new Date();
+    const from = new Date(to.getTime() - 30 * 24 * 60 * 60 * 1e3);
+    snapshot.vercel = {
+      projectName: linked.projectName,
+      services: await getVercelUsage(token, from, to, linked.teamId)
+    };
+  } catch (error) {
+    snapshot.problems.push(`Vercel: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function collectSupabase(config, snapshot) {
+  let linked;
+  let token;
+  try {
+    linked = requireLinked(config, "supabase");
+    token = await requireCloudToken("supabase");
+  } catch (error) {
+    snapshot.problems.push(`Supabase: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  const project = await swallow(() => getSupabaseProject(token, linked.projectRef), "Supabase project", snapshot);
+  const status = project?.status ?? "unknown";
+  if (isSupabasePaused(status)) {
+    snapshot.supabase = { projectName: project?.name ?? linked.projectName, status, dbSizeBytes: null, dailyApiCount: null };
+    return;
+  }
+  const [dbSizeBytes, dailyApiCount] = await Promise.all([
+    swallow(() => getSupabaseDbSizeBytes(token, linked.projectRef), "Supabase DB size", snapshot),
+    swallow(() => getSupabaseDailyApiCount(token, linked.projectRef), "Supabase API counts", snapshot)
+  ]);
+  snapshot.supabase = {
+    projectName: project?.name ?? linked.projectName,
+    status,
+    dbSizeBytes: dbSizeBytes ?? null,
+    dailyApiCount: dailyApiCount ?? null
+  };
+}
+function isSupabasePaused(status) {
+  return ["INACTIVE", "PAUSED", "PAUSING", "PAUSE_FAILED"].includes(status.toUpperCase());
+}
+async function swallow(call, label, snapshot) {
+  try {
+    return await call();
+  } catch (error) {
+    snapshot.problems.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+function matchVercelLimit(serviceName) {
+  const normalized = normalize(serviceName);
+  return VERCEL_HOBBY_LIMITS.find((limit) => limit.per === "month" && (normalize(limit.label) === normalized || normalize(limit.key) === normalized));
+}
+function normalize(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+// src/commands/cloud/usage.ts
+async function cloudUsage() {
+  const snapshot = await collectSnapshot(process.cwd());
+  printVercel(snapshot);
+  printSupabase(snapshot);
+  printProblems(snapshot);
+}
+function printVercel(snapshot) {
+  if (!snapshot.vercel) {
+    return;
+  }
+  console.log(chalk47.bold(`
+Vercel \u2014 account-wide usage, rolling 30 days (linked project: ${snapshot.vercel.projectName})`));
+  if (snapshot.vercel.services.length === 0) {
+    console.log(chalk47.dim("  No usage recorded in the billing feed yet."));
+  }
+  for (const service of snapshot.vercel.services) {
+    const amount = `${formatCount(service.consumed)} ${service.unit}`.trim();
+    console.log(`  ${service.serviceName.padEnd(34)} ${amount}`);
+  }
+}
+function printSupabase(snapshot) {
+  if (!snapshot.supabase) {
+    return;
+  }
+  const { projectName, status, dbSizeBytes, dailyApiCount } = snapshot.supabase;
+  console.log(chalk47.bold(`
+Supabase \u2014 ${projectName}`));
+  console.log(`  ${"Project status".padEnd(34)} ${status}`);
+  console.log(`  ${"Database size".padEnd(34)} ${dbSizeBytes === null ? chalk47.dim("unavailable") : formatBytes2(dbSizeBytes)}`);
+  console.log(`  ${"API requests (last 24h)".padEnd(34)} ${dailyApiCount === null ? chalk47.dim("unavailable") : formatCount(dailyApiCount)}`);
+  console.log(chalk47.dim("  Org totals (egress, MAU) have no public API \u2014 exact numbers: supabase.com/dashboard \u2192 Usage."));
+}
+function printProblems(snapshot) {
+  console.log("");
+  for (const problem of snapshot.problems) {
+    logger.warn(problem);
+  }
+  if (snapshot.problems.length > 0 && !snapshot.vercel && !snapshot.supabase) {
+    process.exit(1);
+  }
+}
+
+// src/commands/cloud/status.ts
+init_logger();
+import chalk48 from "chalk";
+async function cloudStatus() {
+  const snapshot = await collectSnapshot(process.cwd());
+  const nearLimit = [];
+  printVercel2(snapshot, nearLimit);
+  printSupabase2(snapshot, nearLimit);
+  console.log("");
+  for (const problem of snapshot.problems) {
+    logger.warn(problem);
+  }
+  printMigrationPrompt(nearLimit);
+  if (!snapshot.vercel && !snapshot.supabase) {
+    process.exit(1);
+  }
+}
+function printVercel2(snapshot, nearLimit) {
+  if (!snapshot.vercel) {
+    return;
+  }
+  console.log(chalk48.bold(`
+Vercel Hobby \u2014 account-wide usage, rolling 30 days (linked project: ${snapshot.vercel.projectName}; limits as of ${LIMITS_VERIFIED_ON})`));
+  if (snapshot.vercel.services.length === 0) {
+    console.log(chalk48.dim("  No usage recorded in the billing feed yet."));
+  }
+  for (const service of snapshot.vercel.services) {
+    const limit = matchVercelLimit(service.serviceName);
+    if (!limit || !sameUnit(service.unit, limit.unit)) {
+      console.log(`  ${service.serviceName.padEnd(34)} ${formatCount(service.consumed)} ${service.unit}`.trimEnd());
+      continue;
+    }
+    console.log(usageLine(limit.label, service.consumed, limit.limit, limit.unit));
+    if (isNearLimit(service.consumed, limit.limit)) {
+      nearLimit.push(`Vercel ${limit.label}`);
+    }
+  }
+}
+function printSupabase2(snapshot, nearLimit) {
+  if (!snapshot.supabase) {
+    return;
+  }
+  const { projectName, status, dbSizeBytes, dailyApiCount } = snapshot.supabase;
+  console.log(chalk48.bold(`
+Supabase Free \u2014 ${projectName}`));
+  if (isSupabasePaused(status)) {
+    console.log(`  ${"Project status".padEnd(34)} ${chalk48.red.bold(status)} \u2014 run \`spfn cloud keepalive\` after restoring it`);
+  } else {
+    console.log(`  ${"Project status".padEnd(34)} ${chalk48.green(status)}`);
+  }
+  if (dbSizeBytes !== null) {
+    const dbLimit = SUPABASE_FREE_LIMITS.find((l) => l.key === "db-size");
+    const usedMb = dbSizeBytes / BYTES_PER_MB;
+    console.log(usageLine(dbLimit.label, usedMb, dbLimit.limit, dbLimit.unit));
+    if (isNearLimit(usedMb, dbLimit.limit)) {
+      nearLimit.push("Supabase database size");
+    }
+  } else {
+    console.log(`  ${"Database size".padEnd(34)} ${chalk48.dim("unavailable")}`);
+  }
+  console.log(`  ${"API requests (last 24h)".padEnd(34)} ${dailyApiCount === null ? chalk48.dim("unavailable") : formatCount(dailyApiCount)}`);
+  console.log(chalk48.dim(`  DB size ${dbSizeBytes === null ? "unknown" : formatBytes2(dbSizeBytes)} counts per project; egress/MAU are org totals \u2014 exact numbers on the dashboard.`));
+}
+function printMigrationPrompt(nearLimit) {
+  if (nearLimit.length === 0) {
+    return;
+  }
+  console.log(chalk48.yellow.bold(`\u26A0 Approaching free-tier limits: ${nearLimit.join(", ")}.`));
+  console.log(chalk48.yellow("  When a Vercel Hobby limit is hit, that capability pauses; Supabase over quota restricts the whole org."));
+  console.log(chalk48.yellow("  Migrating to your own cloud removes these ceilings \u2014 `spfn cloud migrate` (coming soon).\n"));
+}
+
+// src/commands/cloud/keepalive.ts
+init_logger();
+import { existsSync as existsSync32, mkdirSync as mkdirSync8, readFileSync as readFileSync14, writeFileSync as writeFileSync21 } from "fs";
+import { dirname as dirname7, join as join32 } from "path";
+import chalk49 from "chalk";
+var DEFAULT_HEALTH_PATH = "/api/backend/_core/health?detailed=true";
+var DEFAULT_SCHEDULE = "0 3 * * *";
+async function cloudKeepalive(options) {
+  const cwd = process.cwd();
+  const healthPath = options.path ?? DEFAULT_HEALTH_PATH;
+  if (!healthPath.startsWith("/")) {
+    logger.error(`--path must start with a slash (got "${healthPath}") \u2014 both Vercel crons and the workflow URL treat it as absolute.`);
+    process.exit(1);
+  }
+  if (options.githubActions) {
+    setupGithubActions(cwd, healthPath, options.url);
+  } else {
+    setupVercelCron(cwd, healthPath);
+  }
+  try {
+    const config = readCloudConfig(cwd);
+    config.keepalive = { path: healthPath, schedule: DEFAULT_SCHEDULE };
+    writeCloudConfig(cwd, config);
+  } catch (error) {
+    logger.warn(error instanceof Error ? error.message : String(error));
+  }
+  logger.info("The DB ping needs detailed health checks: keep `healthCheck: { detailed: true }` in your server config.");
+}
+function setupVercelCron(cwd, healthPath) {
+  const vercelJsonPath = join32(cwd, "vercel.json");
+  let vercelJson = {};
+  if (existsSync32(vercelJsonPath)) {
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync14(vercelJsonPath, "utf-8"));
+    } catch {
+      logger.error("vercel.json is not valid JSON (comments and trailing commas are not allowed) \u2014 fix it and re-run.");
+      process.exit(1);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      logger.error("vercel.json does not contain a JSON object \u2014 fix it and re-run.");
+      process.exit(1);
+    }
+    vercelJson = parsed;
+  }
+  const result = addCron(vercelJson, healthPath);
+  if (result === "exists") {
+    logger.success(`vercel.json already has a cron for ${healthPath} \u2014 nothing to do.`);
+    return;
+  }
+  if (result === "occupied") {
+    logger.error("vercel.json already has a cron job, and Vercel Hobby allows only one.");
+    logger.info(`Point the existing cron at ${chalk49.cyan(healthPath)} yourself, or use \`--github-actions --url <deployed-url>\`.`);
+    process.exit(1);
+  }
+  writeFileSync21(vercelJsonPath, JSON.stringify(vercelJson, null, 4) + "\n", "utf-8");
+  logger.success(`vercel.json: daily cron added (${DEFAULT_SCHEDULE} UTC \u2192 ${healthPath}). Deploy to activate.`);
+  warnIfBackendRouteMissing(cwd);
+}
+function addCron(vercelJson, healthPath) {
+  const crons = Array.isArray(vercelJson.crons) ? vercelJson.crons : [];
+  if (crons.some((cron) => cron.path === healthPath)) {
+    return "exists";
+  }
+  if (crons.length > 0) {
+    return "occupied";
+  }
+  vercelJson.crons = [{ path: healthPath, schedule: DEFAULT_SCHEDULE }];
+  return "added";
+}
+function setupGithubActions(cwd, healthPath, url) {
+  if (!url) {
+    logger.error("`--github-actions` needs `--url <deployed-url>` \u2014 the workflow runs outside your app and must know where it lives.");
+    process.exit(1);
+  }
+  const workflowPath = join32(cwd, ".github", "workflows", "spfn-keepalive.yml");
+  if (existsSync32(workflowPath)) {
+    logger.success(`${workflowPath} already exists \u2014 nothing to do.`);
+    return;
+  }
+  const base = normalizeDeployUrl(url);
+  if (!base) {
+    logger.error(`--url "${url}" is not a valid URL. Pass the deployed app origin, e.g. https://myapp.vercel.app.`);
+    process.exit(1);
+  }
+  mkdirSync8(dirname7(workflowPath), { recursive: true });
+  writeFileSync21(workflowPath, githubWorkflow(new URL(healthPath, base).toString()), "utf-8");
+  logger.success(".github/workflows/spfn-keepalive.yml: daily keep-alive workflow added. Commit and push to activate.");
+}
+function normalizeDeployUrl(url) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^https?:\/\//i.test(url)) {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = new URL(/^https?:\/\//i.test(url) ? url : `https://${url}`);
+  } catch {
+    return null;
+  }
+  if (!parsed.hostname.includes(".")) {
+    return null;
+  }
+  return parsed.origin + "/";
+}
+function githubWorkflow(healthUrl) {
+  return `# Keeps the Supabase Free project from pausing: one DB-touching request per day.
+# Generated by \`spfn cloud keepalive --github-actions\`.
+name: spfn-keepalive
+
+on:
+    schedule:
+        - cron: '${DEFAULT_SCHEDULE}'
+    workflow_dispatch:
+
+jobs:
+    ping:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Ping health endpoint (detailed = includes a DB query)
+              run: curl --fail --silent --show-error --max-time 30 '${healthUrl}'
+`;
+}
+function warnIfBackendRouteMissing(cwd) {
+  const routePath = join32(cwd, "src", "app", "api", "backend", "[[...route]]", "route.ts");
+  if (!existsSync32(routePath)) {
+    logger.warn("src/app/api/backend/[[...route]]/route.ts not found \u2014 the cron path answers only after `spfn add vercel`.");
+  }
+}
+
+// src/commands/cloud/env.ts
+init_logger();
+init_env_file();
+import { join as join33 } from "path";
+import prompts13 from "prompts";
+import chalk50 from "chalk";
+async function cloudEnvPull(options) {
+  const cwd = process.cwd();
+  try {
+    const linked = requireLinked(readCloudConfig(cwd), "supabase");
+    const token = await requireCloudToken("supabase");
+    const keys = await getSupabaseApiKeys(token, linked.projectRef);
+    writePublicValues(cwd, linked.projectRef, keys);
+    await storeServiceKey(cwd, keys);
+    if (options.dbUrl) {
+      await storeDatabaseUrl(cwd, token, linked.projectRef);
+    }
+  } catch (error) {
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+  logger.info("Values were written to files/keychain only \u2014 none were displayed.");
+}
+function writePublicValues(cwd, projectRef2, keys) {
+  const envLocalPath = join33(cwd, ".env.local");
+  ensureGitignored(cwd, [{ pattern: ".env.local", comment: "local env (per-machine values)" }]);
+  upsertEnvVar(envLocalPath, "NEXT_PUBLIC_SUPABASE_URL", `https://${projectRef2}.supabase.co`);
+  logger.success("NEXT_PUBLIC_SUPABASE_URL \u2192 .env.local");
+  const anon = findKey(keys, ["anon", "publishable"]);
+  if (anon) {
+    upsertEnvVar(envLocalPath, "NEXT_PUBLIC_SUPABASE_ANON_KEY", anon.api_key);
+    logger.success(`NEXT_PUBLIC_SUPABASE_ANON_KEY \u2192 .env.local (from "${anon.name}"; public by design)`);
+  } else {
+    logger.warn("No anon/publishable key found on the project \u2014 skipped NEXT_PUBLIC_SUPABASE_ANON_KEY.");
+  }
+}
+async function storeServiceKey(cwd, keys) {
+  const service = findKey(keys, ["service_role", "secret"]);
+  if (!service) {
+    logger.warn("No service_role/secret key found on the project \u2014 skipped SUPABASE_SERVICE_ROLE_KEY.");
+    return;
+  }
+  await storeSecret(cwd, "local", "SUPABASE_SERVICE_ROLE_KEY", service.api_key);
+}
+function findKey(keys, candidates) {
+  return keys.find((key) => candidates.includes(key.name)) ?? keys.find((key) => key.type !== void 0 && candidates.includes(key.type));
+}
+async function storeDatabaseUrl(cwd, token, projectRef2) {
+  const template = await poolerTemplate(token, projectRef2);
+  if (!template) {
+    logger.warn("Could not read the pooler connection template from the API \u2014 skipped DATABASE_URL. Copy it from the dashboard (Connect \u2192 Session pooler) into `spfn secret set DATABASE_URL` instead.");
+    return;
+  }
+  const { password } = await prompts13({
+    type: "password",
+    name: "password",
+    message: "Supabase database password (set at project creation; not retrievable via API)"
+  });
+  if (!password) {
+    logger.warn("No password entered \u2014 skipped DATABASE_URL.");
+    return;
+  }
+  const url = sessionPoolerUrl(template, password);
+  await storeSecret(cwd, "local", "DATABASE_URL", url);
+  logger.info("This is the session-mode pooler connection (IPv4-safe, works for migrations). Serverless runtime can use the transaction pooler (port 6543) instead.");
+}
+async function poolerTemplate(token, projectRef2) {
+  try {
+    const configs = await getSupabasePoolerConfigs(token, projectRef2);
+    return configs.find((c) => c.database_type === "PRIMARY")?.connection_string ?? configs.find((c) => c.connection_string)?.connection_string;
+  } catch (error) {
+    logger.warn(error instanceof Error ? error.message : String(error));
+    return void 0;
+  }
+}
+function sessionPoolerUrl(template, password) {
+  const filled = template.replace("[YOUR-PASSWORD]", encodeURIComponent(password));
+  const url = new URL(filled);
+  url.port = "5432";
+  return url.toString();
+}
+async function cloudEnvPush(keys) {
+  const cwd = process.cwd();
+  if (keys.length === 0) {
+    logger.error("Name the env keys to push: `spfn cloud env push KEY [KEY...]` (values are looked up locally, never passed as arguments).");
+    process.exit(1);
+  }
+  try {
+    const linked = requireLinked(readCloudConfig(cwd), "vercel");
+    const token = await requireCloudToken("vercel");
+    const { vars, missing, unresolved } = await resolveLocalValues(cwd, keys);
+    for (const key of unresolved) {
+      logger.warn(`${key}: .env.server points at the keychain but the item could not be resolved \u2014 skipped (a stale value from another file will not be pushed in its place).`);
+    }
+    for (const key of missing) {
+      logger.warn(`${key}: not found in .env/.env.local/.env.server or the keychain \u2014 skipped.`);
+    }
+    if (vars.length === 0) {
+      logger.error("Nothing to push.");
+      process.exit(1);
+    }
+    const result = await upsertVercelEnvVars(token, linked.projectId, vars, linked.teamId);
+    const failedKeys = new Set(result.failed.map((f) => f.key));
+    for (const failure of result.failed) {
+      logger.error(`${failure.key}: rejected by Vercel \u2014 ${failure.message}`);
+    }
+    for (const envVar of vars.filter((v) => !failedKeys.has(v.key))) {
+      logger.success(`${envVar.key} \u2192 Vercel ${chalk50.cyan(linked.projectName)} (${envVar.type}, ${envVar.target.join("+")})`);
+    }
+    if (result.failed.length > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+async function resolveLocalValues(cwd, keys) {
+  const publicEnv = { ...parseEnvFile(join33(cwd, ".env")), ...parseEnvFile(join33(cwd, ".env.local")) };
+  const serverEnv = parseEnvFile(join33(cwd, ".env.server"));
+  const keychain = await resolveKeychainEnv(cwd);
+  const vars = [];
+  const missing = [];
+  const unresolved = [];
+  for (const key of keys) {
+    if (serverEnv[key]?.startsWith(KEYCHAIN_REF_PREFIX) && keychain.env[key] === void 0) {
+      unresolved.push(key);
+      continue;
+    }
+    const value = keychain.env[key] ?? serverEnv[key] ?? publicEnv[key];
+    if (value === void 0) {
+      missing.push(key);
+      continue;
+    }
+    vars.push({
+      key,
+      value,
+      type: key.startsWith("NEXT_PUBLIC_") ? "plain" : "encrypted",
+      target: ["production", "preview"]
+    });
+  }
+  return { vars, missing, unresolved };
+}
+
+// src/commands/cloud/index.ts
+var cloudCommand = new Command17("cloud").description("Manage the free-tier cloud accounts this app deploys to (Vercel + Supabase)");
+cloudCommand.command("link").description("Connect your Vercel and Supabase accounts (tokens go to the OS keychain)").option("--vercel-project <nameOrId>", "Pick the Vercel project without prompting").option("--supabase-project <refOrName>", "Pick the Supabase project without prompting").option("--replace", "Discard the stored tokens and enter fresh ones").action(cloudLink);
+cloudCommand.command("limits").description("Show the free-plan limits (Vercel Hobby, Supabase Free)").action(cloudLimits);
+cloudCommand.command("usage").description("Show current usage from the provider APIs").action(cloudUsage);
+cloudCommand.command("status").description("Usage measured against the free-plan limits, with warnings from 80%").action(cloudStatus);
+cloudCommand.command("keepalive").description("Keep the Supabase project from pausing (daily health-check cron)").option("--path <path>", "Health endpoint path the cron should hit").option("--github-actions", "Generate a GitHub Actions workflow instead of a Vercel cron").option("--url <url>", "Deployed app URL (required with --github-actions)").action(cloudKeepalive);
+var envGroup = cloudCommand.command("env").description("Sync env vars and API keys between the providers and this app");
+envGroup.command("pull").description("Fetch Supabase keys into .env.local / the keychain (values never displayed)").option("--db-url", "Also compose DATABASE_URL (prompts for the database password)").action(cloudEnvPull);
+envGroup.command("push").description("Push local env values to the Vercel project env by key name").argument("[keys...]", "Env var names to push (values resolve locally)").action(cloudEnvPush);
+
 // src/index.ts
 init_version();
-var program = new Command17();
+var program = new Command18();
 program.name("spfn").description("SPFN CLI - The Missing Backend for Next.js").version(getCliVersion());
 program.addCommand(createCommand);
 program.addCommand(initCommand);
@@ -6683,6 +7926,7 @@ program.addCommand(dbCommand);
 program.addCommand(envCommand);
 program.addCommand(opsCommand);
 program.addCommand(secretCommand);
+program.addCommand(cloudCommand);
 async function run() {
   await program.parseAsync(process.argv);
 }