create-bw-app 0.18.6 → 0.20.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 always refuses when the project already has an admin (use the in-app admin role controls to add administrators) 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.20.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/add.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { stdout as output } from "node:process";
 import { SELECTABLE_MODULES } from "./constants.mjs";
-import { TEMPLATE_ROOT, createAppContextFile, createDbInstallPlan, createNextConfig, createPlatformGlobalsCss, createPlatformModulesConfigFile, createShellConfig, getDbModuleRegistry, getVersionMap, pathExists, readJsonIfPresent } from "./generator.mjs";
+import { TEMPLATE_ROOT, createAppContextFile, createDbInstallPlan, createModuleToolbarControlsConfig, createNextConfig, createOptionalModuleRouteFiles, createPlatformGlobalsCss, createPlatformModulesConfigFile, createShellConfig, getDbModuleRegistry, getVersionMap, pathExists, readJsonIfPresent } from "./generator.mjs";
 import { collectScaffoldFiles, findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, resolveModuleClosure, satisfiesVersion, writeAppManifest } from "./app-manifest.mjs";
 import { applyMigrationWrites, planMigrationAppends } from "./migrations.mjs";
 
@@ -66,9 +66,11 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
   const managedWrites = {
     "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModuleKeys }),
     "app/globals.css": await createPlatformGlobalsCss(installedModuleKeys),
+    "config/module-toolbar-controls.tsx": createModuleToolbarControlsConfig(installedModuleKeys),
     "config/modules.ts": createPlatformModulesConfigFile(installedModuleKeys),
     "config/shell.ts": createShellConfig(installedModuleKeys),
     "docs/ai/app-context.json": createAppContextFile({ slug: appManifest.app.slug, template: "platform", selectedModules: installedModuleKeys.filter((key) => key !== "orgs"), dbInstallPlan }),
+    ...createOptionalModuleRouteFiles(installedModuleKeys),
   };
 
   const summary = [
@@ -93,7 +95,13 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
   for (const key of newModules) appManifest.modules[key] = { version: catalog[key].version, installedAt: now, exposed: true };
   appManifest.migrationCursor = migrationPlan.nextCursor;
   const collectedScaffoldFiles = await collectScaffoldFiles(targetDir, installedModuleKeys);
-  appManifest.scaffoldFiles = { ...collectedScaffoldFiles, ...appManifest.scaffoldFiles };
+  const refreshedScaffoldFiles = Object.fromEntries(
+    Object.entries(collectedScaffoldFiles).map(([relativePath, record]) => {
+      const intent = appManifest.scaffoldFiles[relativePath]?.intent;
+      return [relativePath, intent ? { ...record, intent } : record];
+    }),
+  );
+  appManifest.scaffoldFiles = { ...appManifest.scaffoldFiles, ...refreshedScaffoldFiles };
   await writeAppManifest(targetDir, appManifest);
   output.write(`Installed ${newModules.length} module${newModules.length === 1 ? "" : "s"}. ${migrationPlan.writes.length > 0 ? "Run your Supabase migration apply command. " : ""}Run your package manager install command next.\n`);
   return { dryRun: false, newModules, migrationPlan };

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)
+  --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. Use the in-app admin role controls to add administrators.";
+  }
+  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.");
+  }
+  if ("force" in argvOptions) {
+    throw new Error("--force has been removed; use the in-app admin role controls to add administrators.");
+  }
+
+  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) {
+    throw new Error(
+      "A project administrator already exists. Refusing bootstrap; use the in-app admin role controls to add administrators.",
+    );
+  }
+
+  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 as the first administrator.\n`,
+    );
+    return { dryRun: true, email };
+  }
+
+  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,
+      },
+    );
+    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,
+    resetPasswordUrl,
+  };
+}
+
+export { HELP as ADMIN_HELP };

package/src/app-manifest.mjs

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { APP_DEPENDENCY_DEFAULTS, MODULE_STARTER_FILES, PLATFORM_STARTER_FILES, SELECTABLE_MODULES } from "./constants.mjs";
+import { normalizeSafeRelativePath, resolveSafeRelativePath } from "./safe-path.mjs";
 
 const TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "template");
 
@@ -86,6 +87,10 @@ export async function readAppManifest(targetDir, { required = true } = {}) {
   if (!manifest && required) {
     throw new Error(`No BrightWeb app manifest found at ${APP_MANIFEST_PATH}. Pre-manifest apps must be adopted before using bw.`);
   }
+  if (manifest) {
+    const errors = validateAppManifest(manifest);
+    if (errors.length > 0) throw new Error(`Invalid BrightWeb app manifest: ${errors.join("; ")}`);
+  }
   return manifest;
 }
 
@@ -104,6 +109,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") {
@@ -113,13 +119,26 @@ export function validateAppManifest(manifest) {
     if (!manifest[key] || typeof manifest[key] !== "object" || Array.isArray(manifest[key])) errors.push(`${key} must be an object`);
   }
   if (!Array.isArray(manifest.managedFiles) || manifest.managedFiles.some((entry) => typeof entry !== "string")) errors.push("managedFiles must be an array of paths");
+  else for (const [index, relativePath] of manifest.managedFiles.entries()) {
+    try { normalizeSafeRelativePath(relativePath, `managedFiles[${index}]`); } catch (error) { errors.push(error.message); }
+  }
   for (const [key, entry] of Object.entries(manifest.modules || {})) {
     if (!entry || !cleanVersion(entry.version) || typeof entry.installedAt !== "string" || typeof entry.exposed !== "boolean") errors.push(`modules.${key} is invalid`);
   }
   for (const [relativePath, entry] of Object.entries(manifest.scaffoldFiles || {})) {
+    try { normalizeSafeRelativePath(relativePath, `scaffoldFiles path`); } catch (error) { errors.push(error.message); }
     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;
 }
 
@@ -150,13 +169,22 @@ export async function collectScaffoldFiles(targetDir, selectedModules) {
   }
   const result = {};
   for (const [relativePath, moduleKey] of Array.from(files.entries()).sort()) {
-    const targetPath = path.join(targetDir, relativePath);
+    const targetPath = resolveSafeRelativePath(targetDir, relativePath, "Scaffold file path");
     if (await pathExists(targetPath)) result[relativePath] = { module: moduleKey, hash: await hashFile(targetPath), status: "current" };
   }
   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 +207,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

@@ -154,6 +154,7 @@ export const PLATFORM_STARTER_FILES = [
   "app/(shell)/dashboard/dashboard-live-mount.tsx",
   "app/(shell)/dashboard/page.tsx",
   "app/api/account/route.ts",
+  "app/api/cron/keepalive/route.ts",
   "app/api/invitations/_dependencies.ts",
   "app/api/invitations/[invitationId]/route.ts",
   "app/api/invitations/[invitationId]/accept/route.ts",
@@ -170,16 +171,16 @@ export const PLATFORM_STARTER_FILES = [
 ];
 
 export const APP_DEPENDENCY_DEFAULTS = {
-  "@brightweblabs/app-shell": "^0.7.4",
-  "@brightweblabs/core-auth": "^0.7.2",
+  "@brightweblabs/app-shell": "^0.8.0",
+  "@brightweblabs/core-auth": "^0.7.3",
   "@brightweblabs/infra": "^0.4.0",
-  "@brightweblabs/module-admin": "^0.5.10",
-  "@brightweblabs/module-crm": "^0.10.0",
-  "@brightweblabs/module-marketing": "^0.2.9",
-  "@brightweblabs/module-orgs": "^0.3.10",
-  "@brightweblabs/module-projects": "^0.9.1",
-  "@brightweblabs/theme": "^0.5.0",
-  "@brightweblabs/ui": "^1.1.1",
+  "@brightweblabs/module-admin": "^0.5.11",
+  "@brightweblabs/module-crm": "^0.10.1",
+  "@brightweblabs/module-marketing": "^0.2.10",
+  "@brightweblabs/module-orgs": "^0.3.11",
+  "@brightweblabs/module-projects": "^0.9.2",
+  "@brightweblabs/theme": "^0.5.1",
+  "@brightweblabs/ui": "^1.2.0",
   "geist": "1.7.2",
   "lucide-react": "^1.8.0",
   "next": "^16.0.0",
@@ -230,6 +231,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/diff.mjs

@@ -4,6 +4,7 @@ import { stdout as output } from "node:process";
 import { findWorkspaceRoot, readAppManifest } from "./app-manifest.mjs";
 import { pathExists } from "./generator.mjs";
 import { findTrackedTemplate, scaffoldDrift } from "./scaffold.mjs";
+import { normalizeSafeRelativePath, resolveSafeRelativePath } from "./safe-path.mjs";
 
 const HELP = `Usage: bw diff <relpath> [options]\n       bw diff --list [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --list                    Print tracked scaffold drift status\n  --help                    Show this help`;
 
@@ -58,8 +59,7 @@ export async function diffBrightwebScaffold(relativePath, argvOptions = {}, runt
     return { list: true, drift };
   }
   if (!relativePath) throw new Error("bw diff requires a tracked scaffold <relpath>, or pass --list.");
-  const normalized = path.normalize(relativePath).replace(/^\.\//, "");
-  if (path.isAbsolute(relativePath) || normalized.startsWith(`..${path.sep}`)) throw new Error(`Scaffold path must be relative to the app: ${relativePath}`);
+  const normalized = normalizeSafeRelativePath(relativePath, "Scaffold path");
   const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
   const located = await findTrackedTemplate({ relativePath: normalized, manifest, targetDir, workspaceRoot });
   if (!located.record) throw new Error(`${normalized} is not a tracked scaffold file.`);
@@ -68,7 +68,7 @@ export async function diffBrightwebScaffold(relativePath, argvOptions = {}, runt
     output.write(`${warning}\n`);
     return { supported: false, warning };
   }
-  const appPath = path.join(targetDir, normalized);
+  const appPath = resolveSafeRelativePath(targetDir, normalized, "Scaffold path");
   const [templateContent, appContent] = await Promise.all([
     fs.readFile(located.templatePath, "utf8"),
     pathExists(appPath) ? fs.readFile(appPath, "utf8") : Promise.resolve(""),

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 || {})]))