create-bw-app 0.18.6 → 0.19.0

package/README.md

@@ -33,11 +33,13 @@ From a generated app, use `bw` to manage the machine-readable `.brightweb/app-ma
 bw add projects
 bw upgrade
 bw doctor
+bw admin create --email owner@example.com
 ```
 
 - `bw add <moduleKey>` resolves requirements, installs thin package mounts and module wiring, and appends migrations.
 - `bw upgrade [moduleKey]` includes the existing managed update flow plus forward-only module migrations.
-- `bw doctor` checks package, config, scaffold, environment-name, and migration consistency. Add `--report` to stamp the result in the app manifest.
+- `bw doctor` checks package, config, scaffold, environment-name, migration, configured function-region, and deployed function-region consistency. Pass `--deployment-url` to inspect the deployed `x-vercel-id`; add `--report` to stamp the result in the app manifest.
+- `bw admin create --email <email>` creates a passwordless Supabase Auth user, transactionally ensures its profile and `admin` assignment, then sends the Core Auth `/reset-password` flow. It refuses an existing admin unless `--force` is passed and never promotes an existing Auth user.
 - All mutating commands support `--dry-run`.
 
 ## Update existing apps
@@ -67,6 +69,8 @@ Current updater behavior:
 - prompts for app type: `platform` or `site`
 - prompts for project name
 - prompts for optional platform modules: `admin`, `crm`, `marketing`, and `projects`
+- accepts or prompts for the Supabase project region and writes the nearest verified Vercel Functions region to `vercel.json`
+- leaves `vercel.json` valid but unpinned, with a commented setup placeholder in the generated runbook, when the Supabase region is absent or unknown
 - prompts to install dependencies immediately
 - copies a clean Next.js App Router starter template
 - platform apps include BrightWeb auth, shell wiring, and optional direct package mounts
@@ -90,6 +94,8 @@ When this package runs in BrightWeb workspace mode, it can:
 
 Platform mode always resolves to the `Core + Admin` database baseline. Selecting `admin` affects the Admin package mount and wiring, not whether the Admin database layer exists.
 
+The scaffold records `SUPABASE_PROJECT_REGION` in `.env.local` and infrastructure metadata. Keep it aligned when replacing a Supabase project so `bw doctor --deployment-url <url>` can compare the current database location with the region observed from Vercel's `x-vercel-id` response header.
+
 ## Related references
 
 - `packages/create-bw-app/src/generator.mjs`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.18.6",
+  "version": "0.19.0",
   "type": "module",
   "bin": {
     "create-bw-app": "bin/create-bw-app.mjs",
@@ -25,6 +25,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.10.1"
+    "@inquirer/prompts": "^7.10.1",
+    "@supabase/supabase-js": "^2.110.8"
   }
 }

package/src/admin.mjs

@@ -0,0 +1,204 @@
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { createClient } from "@supabase/supabase-js";
+import { loadAppEnvironment, readFirstEnvironmentValue } from "./env.mjs";
+
+const HELP = `Usage: bw admin create --email <email> [options]
+
+Options:
+  --email <email>          Email address for the first administrator
+  --target-dir <path>      App directory (defaults to cwd)
+  --force                  Allow creation when the project already has an admin
+  --dry-run                Validate and inspect without creating the user
+  --help                   Show this help
+
+The command never accepts or prompts for a password. It sends the user through
+the scaffolded core-auth /reset-password recovery flow.`;
+
+function normalizeEmail(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+
+function validateEmail(email) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+function resolveAdminEnvironment(environment) {
+  const supabaseUrl = readFirstEnvironmentValue(environment, ["NEXT_PUBLIC_SUPABASE_URL"]);
+  const secretKey = readFirstEnvironmentValue(environment, [
+    "SUPABASE_SECRET_DEFAULT_KEY",
+    "SUPABASE_SERVICE_ROLE_KEY",
+  ]);
+  const appUrl = readFirstEnvironmentValue(environment, [
+    "NEXT_PUBLIC_APP_URL",
+    "PUBLIC_APP_URL",
+  ]);
+
+  if (!supabaseUrl) {
+    throw new Error("Missing NEXT_PUBLIC_SUPABASE_URL in the process environment or .env.local.");
+  }
+  if (!secretKey) {
+    throw new Error(
+      "Missing SUPABASE_SECRET_DEFAULT_KEY (or legacy SUPABASE_SERVICE_ROLE_KEY) in the process environment or .env.local.",
+    );
+  }
+  if (!secretKey.startsWith("sb_secret_")) {
+    throw new Error(
+      "Invalid Supabase secret: SUPABASE_SECRET_DEFAULT_KEY must use an sb_secret_ key.",
+    );
+  }
+  if (!appUrl) {
+    throw new Error("Missing NEXT_PUBLIC_APP_URL in the process environment or .env.local.");
+  }
+
+  let resetPasswordUrl;
+  try {
+    resetPasswordUrl = new URL("/reset-password", appUrl).toString();
+  } catch {
+    throw new Error("NEXT_PUBLIC_APP_URL must be an absolute URL.");
+  }
+
+  return { supabaseUrl, secretKey, resetPasswordUrl };
+}
+
+async function findAuthUserByEmail(supabase, email) {
+  const perPage = 1000;
+  for (let page = 1; ; page += 1) {
+    const { data, error } = await supabase.auth.admin.listUsers({ page, perPage });
+    if (error) throw new Error(`Could not inspect Supabase Auth users: ${error.message}`);
+    const match = data.users.find((user) => normalizeEmail(user.email) === email);
+    if (match) return match;
+    if (data.users.length < perPage) return null;
+  }
+}
+
+async function projectHasAdmin(supabase) {
+  const { data, error } = await supabase
+    .from("user_role_assignments")
+    .select("profile_id")
+    .eq("role_code", "admin")
+    .limit(1);
+  if (error) {
+    throw new Error(
+      `Could not inspect administrator assignments: ${error.message}. Apply the generated Supabase migrations first.`,
+    );
+  }
+  return Array.isArray(data) && data.length > 0;
+}
+
+async function deleteCreatedAuthUser(supabase, userId) {
+  const { error } = await supabase.auth.admin.deleteUser(userId);
+  return error || null;
+}
+
+function bootstrapErrorMessage(error) {
+  const message = error?.message || "Unknown database error";
+  if (message.toLowerCase().includes("administrator already exists")) {
+    return "A project administrator already exists. Re-run with --force only when intentionally adding another new admin.";
+  }
+  return `Could not create the administrator profile and role: ${message}`;
+}
+
+export async function createFirstAdmin(action, argvOptions = {}, runtimeOptions = {}) {
+  if (argvOptions.help) {
+    (runtimeOptions.output || output).write(`${HELP}\n`);
+    return { help: true };
+  }
+  if (action !== "create") {
+    throw new Error(`Unknown admin command: ${action || "(missing)"}\n\n${HELP}`);
+  }
+  if ("password" in argvOptions) {
+    throw new Error("Passwords are not accepted by bw admin create. The command sends a password-set email instead.");
+  }
+
+  const email = normalizeEmail(argvOptions.email);
+  if (!validateEmail(email)) {
+    throw new Error("A valid --email <email> is required.");
+  }
+
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const environment = await loadAppEnvironment(targetDir, runtimeOptions.env || process.env);
+  const { supabaseUrl, secretKey, resetPasswordUrl } = resolveAdminEnvironment(environment);
+  const clientFactory = runtimeOptions.createClient || createClient;
+  const supabase = clientFactory(supabaseUrl, secretKey, {
+    auth: {
+      autoRefreshToken: false,
+      persistSession: false,
+      detectSessionInUrl: false,
+    },
+  });
+
+  const hasAdmin = await projectHasAdmin(supabase);
+  if (hasAdmin && !argvOptions.force) {
+    throw new Error(
+      "A project administrator already exists. Refusing bootstrap; pass --force only when intentionally adding another new admin.",
+    );
+  }
+
+  const existingUser = await findAuthUserByEmail(supabase, email);
+  if (existingUser) {
+    throw new Error(
+      `Auth user ${email} already exists (${existingUser.id}). Refusing to promote an existing account; use the in-app admin role controls.`,
+    );
+  }
+
+  if (argvOptions.dryRun) {
+    (runtimeOptions.output || output).write(
+      `DRY RUN ${email} can be created${hasAdmin ? " with --force" : " as the first administrator"}.\n`,
+    );
+    return { dryRun: true, email, forced: Boolean(argvOptions.force) };
+  }
+
+  const { data: created, error: createError } = await supabase.auth.admin.createUser({
+    email,
+    email_confirm: true,
+  });
+  if (createError || !created.user?.id) {
+    throw new Error(`Could not create Supabase Auth user ${email}: ${createError?.message || "missing user id"}`);
+  }
+
+  const userId = created.user.id;
+  let profileId = null;
+  try {
+    const { data: bootstrapRows, error: bootstrapError } = await supabase.rpc(
+      "bootstrap_first_admin",
+      {
+        p_user_id: userId,
+        p_email: email,
+        p_force: Boolean(argvOptions.force),
+      },
+    );
+    if (bootstrapError) throw new Error(bootstrapErrorMessage(bootstrapError));
+    profileId = Array.isArray(bootstrapRows) ? bootstrapRows[0]?.profile_id ?? null : null;
+    if (!profileId) throw new Error("The bootstrap transaction did not return a profile id.");
+
+    const { error: recoveryError } = await supabase.auth.resetPasswordForEmail(email, {
+      redirectTo: resetPasswordUrl,
+    });
+    if (recoveryError) {
+      throw new Error(`Could not send the password-set email: ${recoveryError.message}`);
+    }
+  } catch (error) {
+    const rollbackError = await deleteCreatedAuthUser(supabase, userId);
+    const message = error instanceof Error ? error.message : "Unknown bootstrap error";
+    if (rollbackError) {
+      throw new Error(
+        `${message} Automatic rollback also failed: ${rollbackError.message}. Auth user ${userId} may require manual cleanup.`,
+      );
+    }
+    throw new Error(`${message} The newly created Auth user and its cascaded profile/role were rolled back.`);
+  }
+
+  (runtimeOptions.output || output).write(
+    `Created administrator ${email}. A password-set link was sent for ${resetPasswordUrl}.\n`,
+  );
+  return {
+    email,
+    userId,
+    profileId,
+    forced: Boolean(argvOptions.force),
+    resetPasswordUrl,
+  };
+}
+
+export { HELP as ADMIN_HELP };

package/src/app-manifest.mjs

@@ -104,6 +104,7 @@ export async function writeAppManifest(targetDir, manifest) {
 
 export function validateAppManifest(manifest) {
   const errors = [];
+  const isNullableString = (value) => value === null || typeof value === "string";
   if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return ["manifest must be an object"];
   if (manifest.contractVersion !== 1) errors.push("contractVersion must equal 1");
   if (!manifest.app || typeof manifest.app.slug !== "string" || !["platform", "site"].includes(manifest.app.template) || typeof manifest.app.scaffoldedWith !== "string") {
@@ -120,6 +121,15 @@ export function validateAppManifest(manifest) {
     if (!entry || typeof entry.module !== "string" || !/^sha256:[a-f0-9]{64}$/.test(entry.hash || "") || !["current", "drifted", "missing"].includes(entry.status) || (entry.intent != null && !["managed", "owned", "skipped"].includes(entry.intent))) errors.push(`scaffoldFiles.${relativePath} is invalid`);
   }
   if (manifest.lastDoctor != null && (typeof manifest.lastDoctor.at !== "string" || typeof manifest.lastDoctor.ok !== "boolean")) errors.push("lastDoctor is invalid");
+  if (
+    manifest.infrastructure != null
+    && (
+      typeof manifest.infrastructure !== "object"
+      || Array.isArray(manifest.infrastructure)
+      || !isNullableString(manifest.infrastructure.supabaseRegion)
+      || !isNullableString(manifest.infrastructure.vercelRegion)
+    )
+  ) errors.push("infrastructure is invalid");
   return errors;
 }
 
@@ -156,7 +166,16 @@ export async function collectScaffoldFiles(targetDir, selectedModules) {
   return result;
 }
 
-export async function createInitialAppManifest({ targetDir, slug, template, selectedModules, versionMap, dbInstallPlan, cliVersion }) {
+export async function createInitialAppManifest({
+  targetDir,
+  slug,
+  template,
+  selectedModules,
+  versionMap,
+  dbInstallPlan,
+  cliVersion,
+  infrastructure,
+}) {
   const now = new Date().toISOString();
   const modules = {};
   if (template === "platform") {
@@ -179,6 +198,7 @@ export async function createInitialAppManifest({ targetDir, slug, template, sele
     scaffoldFiles: template === "platform" ? await collectScaffoldFiles(targetDir, selectedModules) : {},
     managedFiles: template === "platform" ? MANAGED_APP_FILES : ["docs/ai/app-context.json"],
     migrationCursor,
+    ...(infrastructure ? { infrastructure } : {}),
   };
 }
 

package/src/bw.mjs

@@ -1,4 +1,5 @@
 import { addBrightwebModule } from "./add.mjs";
+import { createFirstAdmin } from "./admin.mjs";
 import { adoptBrightwebApp } from "./adopt.mjs";
 import { diffBrightwebScaffold } from "./diff.mjs";
 import { doctorBrightwebApp } from "./doctor.mjs";
@@ -7,7 +8,7 @@ import { scaffoldBrightwebApp } from "./scaffold-cmd.mjs";
 import { updateBrightwebApp } from "./update.mjs";
 import { upgradeBrightwebApp } from "./upgrade.mjs";
 
-const HELP = `Usage: bw <command> [options]\n\nCommands:\n  add <moduleKey>       Install a module and its requirements\n  adopt                 Create an honest manifest for a legacy app\n  diff <relpath>        Compare a tracked scaffold file with its template\n  scaffold <action>     List or record per-file scaffold intent\n  remove <moduleKey>    Conservatively remove module package wiring\n  upgrade [moduleKey]   Upgrade packages, managed files, and migrations\n  update                Alias for the legacy create-bw-app update flow\n  doctor                Validate app health and manifest consistency\n\nRun bw <command> --help for command-specific options.`;
+const HELP = `Usage: bw <command> [options]\n\nCommands:\n  add <moduleKey>       Install a module and its requirements\n  admin create          Bootstrap a passwordless administrator safely\n  adopt                 Create an honest manifest for a legacy app\n  diff <relpath>        Compare a tracked scaffold file with its template\n  scaffold <action>     List or record per-file scaffold intent\n  remove <moduleKey>    Conservatively remove module package wiring\n  upgrade [moduleKey]   Upgrade packages, managed files, and migrations\n  update                Alias for the legacy create-bw-app update flow\n  doctor                Validate app health and manifest consistency\n\nRun bw <command> --help for command-specific options.`;
 
 function parseOptions(argv) {
   const options = {};
@@ -36,6 +37,7 @@ export async function runBwCli(argv = process.argv.slice(2), runtimeOptions = {}
   const { options, positionals } = parseOptions(argv.slice(1));
   try {
     if (command === "add") await addBrightwebModule(positionals[0], options, runtimeOptions);
+    else if (command === "admin") await createFirstAdmin(positionals[0], options, runtimeOptions);
     else if (command === "adopt") await adoptBrightwebApp(options, runtimeOptions);
     else if (command === "diff") await diffBrightwebScaffold(positionals[0], options, runtimeOptions);
     else if (command === "scaffold") await scaffoldBrightwebApp(positionals[0], positionals.slice(1), options, runtimeOptions);

package/src/constants.mjs

@@ -230,6 +230,7 @@ Scaffold options:
   --target-dir <path>            Exact output directory, bypassing slug folder creation
   --workspace-root <path>        BrightWeb workspace root for local mode
   --dependency-mode <mode>       "workspace" or "published"
+  --supabase-region <region>      Supabase project region used to place Vercel Functions
   --install                      Install dependencies after scaffolding
   --no-install                   Skip dependency installation
   --yes                          Accept defaults for any missing optional prompt

package/src/doctor.mjs

@@ -3,12 +3,151 @@ import path from "node:path";
 import { stdout as output } from "node:process";
 import { cursorMigrationStatus } from "./migrations.mjs";
 import { findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, readConfiguredModuleFlags, satisfiesVersion, validateAppManifest, writeAppManifest } from "./app-manifest.mjs";
+import { loadAppEnvironment, readFirstEnvironmentValue } from "./env.mjs";
 import { pathExists, readJsonIfPresent } from "./generator.mjs";
+import { nearestVercelRegion, normalizeSupabaseRegion } from "./regions.mjs";
 import { scaffoldDrift } from "./scaffold.mjs";
 
-const HELP = `Usage: bw doctor [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --strict                  Treat warnings as failures\n  --report                  Stamp lastDoctor in the app manifest\n  --help                    Show this help`;
+const HELP = `Usage: bw doctor [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --deployment-url <url>    Deployed app URL (defaults to PUBLIC_APP_URL/NEXT_PUBLIC_APP_URL)\n  --supabase-region <id>    Current Supabase project region override\n  --strict                  Treat warnings as failures\n  --report                  Stamp lastDoctor in the app manifest\n  --help                    Show this help`;
 const RUNTIME_PACKAGE_NAMES = ["react", "react-dom", "next"];
 
+function isLocalDeploymentUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+
+export function parseVercelFunctionRegion(vercelId) {
+  if (typeof vercelId !== "string") return null;
+  const regions = vercelId
+    .split("::")
+    .map((segment) => segment.match(/^([a-z]{3}\d)/)?.[1] ?? null)
+    .filter(Boolean);
+  return regions[1] || null;
+}
+
+async function inspectFunctionRegion({
+  targetDir,
+  options,
+  runtimeOptions,
+  appManifest,
+  environment,
+  add,
+}) {
+  if (appManifest.app.template !== "platform") return;
+
+  const supabaseRegion = normalizeSupabaseRegion(
+    options.supabaseRegion
+      || environment.SUPABASE_PROJECT_REGION
+      || appManifest.infrastructure?.supabaseRegion,
+  );
+  const expectedVercelRegion = nearestVercelRegion(supabaseRegion);
+  const vercelConfig = await readJsonIfPresent(path.join(targetDir, "vercel.json"));
+  const configuredVercelRegions = Array.isArray(vercelConfig?.regions)
+    ? vercelConfig.regions.filter((entry) => typeof entry === "string")
+    : [];
+
+  if (!supabaseRegion) {
+    add(
+      "WARN",
+      "function-region",
+      "Supabase region is unknown; set SUPABASE_PROJECT_REGION or pass --supabase-region before pinning Vercel Functions.",
+    );
+    return;
+  }
+  if (!expectedVercelRegion) {
+    add(
+      "WARN",
+      "function-region",
+      `Supabase region ${supabaseRegion} has no verified Vercel mapping; vercel.json was left unpinned.`,
+    );
+    return;
+  }
+  if (!configuredVercelRegions.includes(expectedVercelRegion)) {
+    add(
+      "WARN",
+      "function-region-config",
+      `Supabase ${supabaseRegion} maps to ${expectedVercelRegion}, but vercel.json has ${configuredVercelRegions.join(", ") || "no regions"}.`,
+    );
+  } else {
+    add(
+      "PASS",
+      "function-region-config",
+      `Supabase ${supabaseRegion} maps to configured Vercel region ${expectedVercelRegion}.`,
+    );
+  }
+
+  const deploymentUrl = readFirstEnvironmentValue(
+    {
+      ...environment,
+      ...(options.deploymentUrl ? { BW_DOCTOR_DEPLOYMENT_URL: options.deploymentUrl } : {}),
+    },
+    ["BW_DOCTOR_DEPLOYMENT_URL", "PUBLIC_APP_URL", "NEXT_PUBLIC_APP_URL"],
+  );
+  if (!deploymentUrl || isLocalDeploymentUrl(deploymentUrl)) {
+    add(
+      "INFO",
+      "function-region-deployed",
+      "SKIP deployed region check; pass --deployment-url with a non-local app URL.",
+    );
+    return;
+  }
+
+  let endpoint;
+  try {
+    endpoint = new URL("/api/cron/keepalive", deploymentUrl).toString();
+  } catch {
+    add("WARN", "function-region-deployed", `Invalid deployment URL: ${deploymentUrl}.`);
+    return;
+  }
+
+  const fetchImpl = runtimeOptions.fetchImpl || globalThis.fetch;
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    runtimeOptions.regionCheckTimeoutMs || 5_000,
+  );
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: "GET",
+      redirect: "follow",
+      signal: controller.signal,
+    });
+    const vercelId = response.headers.get("x-vercel-id");
+    const deployedRegion = parseVercelFunctionRegion(vercelId);
+    if (!deployedRegion) {
+      add(
+        "WARN",
+        "function-region-deployed",
+        `No Vercel Function region was present in x-vercel-id from ${endpoint}.`,
+      );
+    } else if (deployedRegion !== expectedVercelRegion) {
+      add(
+        "WARN",
+        "function-region-deployed",
+        `Deployed function region ${deployedRegion} does not match ${expectedVercelRegion} for Supabase ${supabaseRegion}.`,
+      );
+    } else {
+      add(
+        "PASS",
+        "function-region-deployed",
+        `Deployed function region ${deployedRegion} matches Supabase ${supabaseRegion}.`,
+      );
+    }
+  } catch (error) {
+    add(
+      "WARN",
+      "function-region-deployed",
+      `Could not inspect ${endpoint}: ${error instanceof Error ? error.message : String(error)}.`,
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 export async function findInstalledRuntimeVersions(targetDir) {
   const storeDir = path.join(targetDir, "node_modules", ".pnpm");
   if (!(await pathExists(storeDir))) {
@@ -107,18 +246,21 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
   add(scaffoldStatus, "scaffold", `${scaffoldGroups.current.length} current, ${scaffoldGroups.owned.length} owned, ${scaffoldGroups.skipped.length} skipped, ${scaffoldGroups.undecidedDrift.length} undecided-drift, ${scaffoldGroups.undecidedMissing.length} undecided-missing, ${scaffoldGroups.mismatched.length} intent-mismatch.`);
   add("INFO", "owned-surfaces", `Owned surfaces: ${(appManifest.ownedSurfaces || []).join(", ") || "none"}.`);
 
-  const envNames = new Set(Object.keys(process.env));
-  const envPath = path.join(targetDir, ".env.local");
-  if (await pathExists(envPath)) {
-    for (const line of (await fs.readFile(envPath, "utf8")).split(/\r?\n/)) {
-      const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
-      if (match) envNames.add(match[1]);
-    }
-  }
+  const environment = await loadAppEnvironment(targetDir, runtimeOptions.env || process.env);
+  const envNames = new Set(Object.keys(environment));
   const missingEnv = [];
   for (const key of Object.keys(appManifest.modules || {})) for (const entry of catalog[key]?.manifest?.env || []) if (entry.required && !envNames.has(entry.name)) missingEnv.push(`${key}:${entry.name}`);
   add(missingEnv.length ? "FAIL" : "PASS", "env", missingEnv.length ? `Missing required names: ${missingEnv.join(", ")}` : "Required environment variable names are present.");
 
+  await inspectFunctionRegion({
+    targetDir,
+    options: argvOptions,
+    runtimeOptions,
+    appManifest,
+    environment,
+    add,
+  });
+
   const migrationProblems = [];
   const migrationKeys = appManifest.app.template === "platform"
     ? Array.from(new Set(["core", "admin", ...Object.keys(appManifest.modules || {})]))

package/src/env.mjs

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathExists } from "./generator.mjs";
+
+function parseValue(rawValue) {
+  const trimmed = rawValue.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"'))
+    || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed.replace(/\s+#.*$/, "").trim();
+}
+
+export function parseDotEnv(content) {
+  const values = {};
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/);
+    if (!match) continue;
+    values[match[1]] = parseValue(match[2]);
+  }
+  return values;
+}
+
+export async function loadAppEnvironment(targetDir, runtimeEnv = process.env) {
+  const envPath = path.join(targetDir, ".env.local");
+  const fileValues = await pathExists(envPath)
+    ? parseDotEnv(await fs.readFile(envPath, "utf8"))
+    : {};
+  const runtimeValues = Object.fromEntries(
+    Object.entries(runtimeEnv || {}).filter(([, value]) => typeof value === "string"),
+  );
+  return { ...fileValues, ...runtimeValues };
+}
+
+export function readFirstEnvironmentValue(environment, names) {
+  for (const name of names) {
+    const value = environment[name]?.trim();
+    if (value) return value;
+  }
+  return null;
+}

package/src/generator.mjs

@@ -17,6 +17,12 @@ import {
   TEMPLATE_OPTIONS,
 } from "./constants.mjs";
 import { createInitialAppManifest, writeAppManifest } from "./app-manifest.mjs";
+import {
+  createVercelConfig,
+  nearestVercelRegion,
+  normalizeSupabaseRegion,
+  regionSetupNote,
+} from "./regions.mjs";
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
@@ -416,13 +422,14 @@ export function createPlatformModulesConfigFile(selectedModules) {
   ].join("\n");
 }
 
-function createEnvFileContent() {
+function createEnvFileContent(supabaseRegion) {
   return [
     "NEXT_PUBLIC_APP_URL=http://localhost:3000",
     "PUBLIC_APP_URL=http://localhost:3000",
     "NEXT_PUBLIC_SUPABASE_URL=",
     "NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=",
     "SUPABASE_SECRET_DEFAULT_KEY=",
+    `SUPABASE_PROJECT_REGION=${normalizeSupabaseRegion(supabaseRegion) || ""}`,
     "RESEND_API_KEY=",
     "RESEND_WEBHOOK_SECRET=",
     "RESEND_FROM_TRANSACTIONAL=",
@@ -512,6 +519,7 @@ function createPlatformReadme({
   workspaceMode,
   packageManager,
   dbInstallPlan,
+  supabaseRegion,
 }) {
   const moduleLines = SELECTABLE_MODULES.map((moduleDefinition) => {
     const enabled = selectedModules.includes(moduleDefinition.key);
@@ -524,12 +532,16 @@ function createPlatformReadme({
     ? [
         "1. Review `.env.local` and fill in real service credentials.",
         "2. Run `pnpm install` from the BrightWeb workspace root.",
-        `3. Run \`pnpm --filter ${slug} dev\`.`,
+        "3. Link the Supabase project and run `supabase db push` from this app.",
+        "4. Run `bw admin create --email you@example.com` to create the first administrator.",
+        `5. Run \`pnpm --filter ${slug} dev\`.`,
       ]
     : [
         "1. Review `.env.local` and fill in real service credentials.",
         `2. Run \`${packageManager} install\`.`,
-        `3. Run \`${packageManager} dev\`.`,
+        "3. Link the Supabase project and run `supabase db push`.",
+        "4. Run `bw admin create --email you@example.com` to create the first administrator.",
+        `5. Run \`${packageManager} dev\`.`,
       ];
 
   return [
@@ -563,6 +575,16 @@ function createPlatformReadme({
           "",
         ]
       : []),
+    "## First administrator",
+    "",
+    "Run `bw admin create --email you@example.com` after the generated migrations and `.env.local` values are in place.",
+    "The command refuses projects that already contain an admin unless `--force` is explicit, refuses to promote an existing Auth user, never accepts a password, and sends the new user through the Core Auth `/reset-password` flow.",
+    "",
+    "## Function region",
+    "",
+    regionSetupNote(supabaseRegion),
+    "Keep `SUPABASE_PROJECT_REGION` current if the Supabase project is replaced, then run `bw doctor --deployment-url https://your-app.example` to compare it with the deployed Vercel Function region.",
+    "",
     "## Package mounts",
     "",
     ...getPlatformStarterRoutes(selectedModules).map((route) => `- \`${route}\``),
@@ -1080,6 +1102,10 @@ async function writeClientStack(baseRoot, slug, dbInstallPlan, options = {}) {
         historyMode: "greenfield-modular",
         futureMode: "forward-only-modular",
         enabledModules,
+        infrastructure: {
+          supabaseRegion: normalizeSupabaseRegion(options.supabaseRegion),
+          vercelRegion: nearestVercelRegion(options.supabaseRegion),
+        },
         clientMigrationPath: `supabase/clients/${slug}/migrations`,
         notes: [
           generatedInWorkspaceMode
@@ -1126,7 +1152,13 @@ async function writeSupabaseCliMigrations({ targetDir, dbInstallPlan }) {
   }
 }
 
-async function writeBundledSupabaseBaseline({ targetDir, slug, dbInstallPlan, registry }) {
+async function writeBundledSupabaseBaseline({
+  targetDir,
+  slug,
+  dbInstallPlan,
+  registry,
+  supabaseRegion,
+}) {
   const shippedModuleKeys = dbInstallPlan.resolvedOrder;
   if (shippedModuleKeys.length === 0) {
     return;
@@ -1155,7 +1187,7 @@ async function writeBundledSupabaseBaseline({ targetDir, slug, dbInstallPlan, re
     );
   }
 
-  await writeClientStack(targetDir, slug, dbInstallPlan);
+  await writeClientStack(targetDir, slug, dbInstallPlan, { supabaseRegion });
   await writeSupabaseCliMigrations({ targetDir, dbInstallPlan });
 }
 
@@ -1188,6 +1220,7 @@ function renderPlanSummary({
   install,
   template,
   dbInstallPlan,
+  supabaseRegion,
 }) {
   const installLocation = workspaceMode ? "workspace root" : "project directory";
   const templateLabel = TEMPLATE_OPTIONS.find((templateOption) => templateOption.key === template)?.label || template;
@@ -1209,6 +1242,12 @@ function renderPlanSummary({
           ...dbInstallPlan.notes.map((note) => `- ${note}`),
         ]
       : []),
+    ...(template === "platform"
+      ? [
+          `Supabase region: ${normalizeSupabaseRegion(supabaseRegion) || "unknown"}`,
+          `Vercel Functions region: ${nearestVercelRegion(supabaseRegion) || "placeholder (not pinned)"}`,
+        ]
+      : []),
     `Install dependencies: ${install ? `yes (${packageManager} in ${installLocation})` : "no"}`,
   ].join("\n");
 }
@@ -1243,6 +1282,7 @@ async function collectAnswers(argvOptions, runtimeOptions) {
   }
 
   let selectedModules = [];
+  let supabaseRegion = null;
 
   if (template === "platform") {
     const askedModules = [];
@@ -1264,6 +1304,15 @@ async function collectAnswers(argvOptions, runtimeOptions) {
       : argvOptions.yes
         ? []
         : askedModules;
+
+    supabaseRegion = normalizeSupabaseRegion(
+      argvOptions.supabaseRegion
+        || (argvOptions.yes
+          ? null
+          : await promptInput({
+              message: "What Supabase region is the project in? (for example eu-west-3; leave blank if unknown)",
+            })),
+    );
   }
 
   const install =
@@ -1280,6 +1329,7 @@ async function collectAnswers(argvOptions, runtimeOptions) {
     slug: resolvedSlug,
     template,
     selectedModules,
+    supabaseRegion,
     install,
   };
 }
@@ -1351,9 +1401,10 @@ async function scaffoldPlatformProject({
     }),
   );
 
-  const envFileContent = createEnvFileContent();
+  const vercelConfig = createVercelConfig(answers.supabaseRegion);
 
-  await fs.writeFile(path.join(targetDir, ".env.local"), envFileContent);
+  await fs.writeFile(path.join(targetDir, ".env.local"), createEnvFileContent(answers.supabaseRegion));
+  await fs.writeFile(path.join(targetDir, "vercel.json"), `${JSON.stringify(vercelConfig.config, null, 2)}\n`);
   await fs.writeFile(path.join(targetDir, ".gitignore"), createGitignore());
   await fs.writeFile(
     path.join(targetDir, "README.md"),
@@ -1363,11 +1414,15 @@ async function scaffoldPlatformProject({
       workspaceMode,
       packageManager,
       dbInstallPlan,
+      supabaseRegion: answers.supabaseRegion,
     }),
   );
 
   if (workspaceMode) {
-    await writeClientStack(workspaceRoot, answers.slug, dbInstallPlan, { workspaceMode: true });
+    await writeClientStack(workspaceRoot, answers.slug, dbInstallPlan, {
+      workspaceMode: true,
+      supabaseRegion: answers.supabaseRegion,
+    });
     await writeSupabaseCliMigrations({ targetDir, dbInstallPlan });
   } else {
     await writeBundledSupabaseBaseline({
@@ -1375,6 +1430,7 @@ async function scaffoldPlatformProject({
       slug: answers.slug,
       dbInstallPlan,
       registry: dbRegistry,
+      supabaseRegion: answers.supabaseRegion,
     });
   }
 
@@ -1387,6 +1443,10 @@ async function scaffoldPlatformProject({
     versionMap,
     dbInstallPlan,
     cliVersion: cliPackage?.version || "0.0.0",
+    infrastructure: {
+      supabaseRegion: vercelConfig.supabaseRegion,
+      vercelRegion: vercelConfig.vercelRegion,
+    },
   }));
 }
 
@@ -1515,6 +1575,7 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
       install: answers.install,
       template: answers.template,
       dbInstallPlan,
+      supabaseRegion: answers.supabaseRegion,
     })}\n\n`);
     return {
       answers,
@@ -1535,6 +1596,7 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
     install: answers.install,
     template: answers.template,
     dbInstallPlan,
+    supabaseRegion: answers.supabaseRegion,
   })}\n\n`);
 
   if (answers.template === "site") {

package/src/regions.mjs

@@ -0,0 +1,60 @@
+// Supabase: https://supabase.com/docs/guides/platform/regions
+// Vercel: https://vercel.com/docs/regions
+// Verified 2026-07-29. Keep this list explicit; unknown regions must remain unpinned.
+export const SUPABASE_TO_VERCEL_REGION = Object.freeze({
+  americas: "iad1",
+  emea: "fra1",
+  apac: "sin1",
+  "us-west-1": "sfo1",
+  "us-west-2": "pdx1",
+  "us-east-1": "iad1",
+  "us-east-2": "cle1",
+  "ca-central-1": "yul1",
+  "eu-west-1": "dub1",
+  "eu-west-2": "lhr1",
+  "eu-west-3": "cdg1",
+  "eu-central-1": "fra1",
+  "eu-central-2": "fra1",
+  "eu-north-1": "arn1",
+  "ap-south-1": "bom1",
+  "ap-southeast-1": "sin1",
+  "ap-northeast-1": "hnd1",
+  "ap-northeast-2": "icn1",
+  "ap-southeast-2": "syd1",
+  "sa-east-1": "gru1",
+});
+
+export function normalizeSupabaseRegion(value) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return normalized || null;
+}
+
+export function nearestVercelRegion(supabaseRegion) {
+  const normalized = normalizeSupabaseRegion(supabaseRegion);
+  return normalized ? SUPABASE_TO_VERCEL_REGION[normalized] ?? null : null;
+}
+
+export function createVercelConfig(supabaseRegion) {
+  const vercelRegion = nearestVercelRegion(supabaseRegion);
+  return {
+    config: vercelRegion
+      ? {
+          $schema: "https://openapi.vercel.sh/vercel.json",
+          regions: [vercelRegion],
+        }
+      : {
+          $schema: "https://openapi.vercel.sh/vercel.json",
+        },
+    supabaseRegion: normalizeSupabaseRegion(supabaseRegion),
+    vercelRegion,
+  };
+}
+
+export function regionSetupNote(supabaseRegion) {
+  const normalized = normalizeSupabaseRegion(supabaseRegion);
+  const vercelRegion = nearestVercelRegion(normalized);
+  if (vercelRegion) {
+    return `Supabase region \`${normalized}\` maps to Vercel Functions region \`${vercelRegion}\` in \`vercel.json\`.`;
+  }
+  return "<!-- vercel.json region placeholder: once the Supabase region is known, set SUPABASE_PROJECT_REGION and add the nearest verified Vercel region as `\"regions\": [\"<region>\"]`. -->";
+}

package/template/supabase/modules/admin/migrations/20260729120000_bootstrap_first_admin.sql

@@ -0,0 +1,114 @@
+-- Transactional database half of `bw admin create`.
+
+CREATE OR REPLACE FUNCTION public.bootstrap_first_admin(
+  p_user_id uuid,
+  p_email text,
+  p_force boolean DEFAULT false
+)
+RETURNS TABLE (
+  profile_id uuid,
+  previous_role_code text
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, auth
+AS $$
+DECLARE
+  v_email text;
+  v_auth_email text;
+  v_profile_id uuid;
+  v_previous_role_code text;
+BEGIN
+  IF COALESCE(auth.jwt() ->> 'role', '') <> 'service_role' THEN
+    RAISE EXCEPTION 'bootstrap_first_admin requires service_role'
+      USING ERRCODE = '42501';
+  END IF;
+
+  v_email := NULLIF(lower(trim(COALESCE(p_email, ''))), '');
+  IF p_user_id IS NULL OR v_email IS NULL THEN
+    RAISE EXCEPTION 'A user id and email are required'
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT lower(trim(u.email))
+  INTO v_auth_email
+  FROM auth.users u
+  WHERE u.id = p_user_id;
+
+  IF v_auth_email IS NULL OR v_auth_email <> v_email THEN
+    RAISE EXCEPTION 'Auth user and email do not match'
+      USING ERRCODE = '22023';
+  END IF;
+
+  PERFORM pg_advisory_xact_lock(hashtextextended('brightweb:first-admin-bootstrap', 0));
+
+  IF NOT p_force AND EXISTS (
+    SELECT 1
+    FROM public.user_role_assignments ura
+    WHERE ura.role_code = 'admin'
+  ) THEN
+    RAISE EXCEPTION 'A project administrator already exists'
+      USING ERRCODE = '42501';
+  END IF;
+
+  SELECT p.id
+  INTO v_profile_id
+  FROM public.profiles p
+  WHERE p.user_id = p_user_id
+  FOR UPDATE;
+
+  IF v_profile_id IS NULL THEN
+    IF EXISTS (
+      SELECT 1
+      FROM public.profiles p
+      WHERE lower(p.email) = v_email
+    ) THEN
+      RAISE EXCEPTION 'A profile already exists for this email'
+        USING ERRCODE = '23505';
+    END IF;
+
+    INSERT INTO public.profiles (user_id, email)
+    VALUES (p_user_id, v_email)
+    RETURNING id INTO v_profile_id;
+  ELSE
+    UPDATE public.profiles
+    SET email = v_email,
+        updated_at = now()
+    WHERE id = v_profile_id;
+  END IF;
+
+  SELECT ura.role_code
+  INTO v_previous_role_code
+  FROM public.user_role_assignments ura
+  WHERE ura.profile_id = v_profile_id
+  FOR UPDATE;
+
+  INSERT INTO public.user_role_assignments (
+    profile_id,
+    role_code,
+    assigned_by_profile_id,
+    assigned_at,
+    reason
+  )
+  VALUES (
+    v_profile_id,
+    'admin',
+    NULL,
+    now(),
+    'bw_admin_create_bootstrap'
+  )
+  ON CONFLICT (profile_id)
+  DO UPDATE SET
+    role_code = EXCLUDED.role_code,
+    assigned_by_profile_id = NULL,
+    assigned_at = EXCLUDED.assigned_at,
+    reason = EXCLUDED.reason;
+
+  RETURN QUERY SELECT v_profile_id, v_previous_role_code;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.bootstrap_first_admin(uuid, text, boolean) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.bootstrap_first_admin(uuid, text, boolean) FROM anon;
+REVOKE ALL ON FUNCTION public.bootstrap_first_admin(uuid, text, boolean) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.bootstrap_first_admin(uuid, text, boolean) TO service_role;