create-bw-app 0.27.1 → 0.27.3

package/README.md

@@ -40,7 +40,7 @@ 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. For a staged database rollout, `bw upgrade <moduleKey> --through-migration <filename>` still updates packages and managed files but appends and records that module only through the named migration.
 - Destructive migrations are held at the preceding safe boundary. After compatible code is deployed and affected data is backed up, apply a held migration with an explicit module-scoped `bw upgrade <moduleKey> --include-destructive-migrations`. A destructive `--through-migration` target also requires that opt-in.
-- `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 doctor` checks package, config, scaffold, environment-name, migration, configured function-region, and deployed function-region consistency. App-owned scaffold files are preserved on upgrade; doctor warns when their recorded template baseline is outdated and their contents differ from the current template. Use `bw diff`, reconcile relevant changes, and verify behavior before recording the reviewed baseline with `bw scaffold manage <path>` followed by `bw scaffold own <path>` (neither replaces file contents). Live database objects, applied migrations, and authenticated permissions are explicitly **NOT VERIFIED** by doctor; a successful local result does not certify deployed behavior. 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`.
 
@@ -62,7 +62,7 @@ Current updater behavior:
 - fails the update if npm resolution fails unless you pass `--allow-stale-fallback`
 - re-syncs managed BrightWeb config files such as `next.config.ts`, `config/modules.ts`, and `config/shell.ts`
 - preserves app-owned shell customizations in the scaffolded `config/shell.overrides.ts`
-- reports missing or drifted scaffold mounts and only rewrites them with `--refresh-starters`
+- reports missing or drifted scaffold mounts and only rewrites them with `--refresh-starters`; tracked `owned` and `skipped` files remain protected, including managed config routes
 - prints the follow-up install command unless `--install` is passed
 - preserves unrelated third-party dependencies and app-owned product pages
 
@@ -139,3 +139,11 @@ on generated paths. Existing JSON and page files are never replaced, even when
 empty or customized; reruns preserve them. These files are not managed templates
 or refreshable starters, and `bw update --refresh-starters` preserves them and
 shell overrides. New marketing apps do not receive this feature until opted in.
+
+## File and compatibility safety
+
+Lifecycle commands resolve the selected app root and reject symlinks or invalid file types beneath it before writing planned outputs. Root aliases are supported; concurrent filesystem edits are outside this preflight guarantee. App-owned brand, theme, shell override and social content seeds are preserved. The generated app context lists exact generated/scaffold paths, defaults unknown paths to app ownership, and shares its generated inventory with the CLI.
+
+Upgrade refuses unknown migration cursors and uses standard semantic-version ranges. Module removal refuses surviving literal imports of the removed package before changing files; reconcile the app-owned dependents explicitly. This conservative scan is not a complete bundler analysis.
+
+Forced re-adoption and module removal preserve exact-path `owned` and `skipped` decisions. Re-adding a module respects retained decisions; use `bw scaffold manage` after re-adding to reset a path deliberately. Every pending destructive migration requires opt-in, even after a previous destructive step was approved. Managed platform outputs share one renderer across scaffolding, add, remove, and update, with enforced ownership-inventory parity.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.27.1",
+  "version": "0.27.3",
   "type": "module",
   "bin": {
     "create-bw-app": "bin/create-bw-app.mjs",
@@ -26,6 +26,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.10.1",
-    "@supabase/supabase-js": "^2.110.8"
+    "@supabase/supabase-js": "^2.110.8",
+    "semver": "^7.8.5"
   }
 }

package/src/add.mjs

@@ -1,9 +1,11 @@
+import { assertMutationTargets } from "./mutation-paths.mjs";
 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, createModuleToolbarControlsConfig, createNextConfig, createOptionalModuleRouteFiles, createPlatformGlobalsCss, createPlatformModulesConfigFile, createShellConfig, getDbModuleRegistry, getVersionMap, pathExists, readJsonIfPresent } from "./generator.mjs";
+import { TEMPLATE_ROOT, createDbInstallPlan, createManagedPlatformFiles, getDbModuleRegistry, getVersionMap, pathExists, readJsonIfPresent } from "./generator.mjs";
 import { collectScaffoldFiles, findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, resolveModuleClosure, satisfiesVersion, writeAppManifest } from "./app-manifest.mjs";
+import { assertNoUntrackedScaffoldWrites, scaffoldDrift } from "./scaffold.mjs";
 import { applyMigrationWrites, planMigrationAppends } from "./migrations.mjs";
 
 const HELP = `Usage: bw add <moduleKey> [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --dry-run                 Print the install plan without writing\n  --help                    Show this help`;
@@ -13,7 +15,7 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
     output.write(`${HELP}\n`);
     return { help: true };
   }
-  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const targetDir = await fs.realpath(path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd()));
   const appManifest = await readAppManifest(targetDir);
   if (appManifest.app.template !== "platform") throw new Error("bw add is only available for platform apps.");
   const packageJsonPath = path.join(targetDir, "package.json");
@@ -63,15 +65,51 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
     const definition = SELECTABLE_MODULES.find((entry) => entry.key === key);
     if (definition && await pathExists(path.join(TEMPLATE_ROOT, "modules", definition.templateFolder))) overlays.push({ key, source: path.join(TEMPLATE_ROOT, "modules", definition.templateFolder) });
   }
-  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 managedWrites = await createManagedPlatformFiles({ slug: appManifest.app.slug, selectedModules: installedModuleKeys, dbInstallPlan });
+
+  const live = await scaffoldDrift(targetDir, appManifest.scaffoldFiles);
+  const { protectedPaths } = live;
+  for (const relativePath of protectedPaths) delete managedWrites[relativePath];
+
+  if (newModules.length === 0) for (const relativePath of Object.keys(managedWrites)) delete managedWrites[relativePath];
+
+  await assertNoUntrackedScaffoldWrites({
+    targetDir,
+    scaffoldFiles: appManifest.scaffoldFiles,
+    moduleKeys: installedModuleKeys,
+    relativePaths: Object.keys(managedWrites),
+  });
+
+  const overlayFiles = [];
+  // Refuse unknown overlay collisions before package, configuration or migration writes.
+  for (const overlay of overlays) {
+    const pending = [overlay.source];
+    while (pending.length) {
+      const directory = pending.pop();
+      for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+        const source = path.join(directory, entry.name);
+        const relativePath = path.relative(overlay.source, source);
+        const destination = path.join(targetDir, relativePath);
+        const existing = await fs.lstat(destination).catch((error) => {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        });
+        if (entry.isDirectory()) {
+          if (existing && !existing.isDirectory()) {
+            throw new Error(`Cannot add ${moduleKey}: module scaffold requires a directory at ${relativePath}, but an app file or link exists. Reconcile it explicitly before adding the module.`);
+          }
+          pending.push(source);
+          continue;
+        }
+        overlayFiles.push(relativePath);
+        if (!appManifest.scaffoldFiles[relativePath] && existing) {
+          throw new Error(`Cannot add ${moduleKey}: untracked app file conflicts with module scaffold: ${relativePath}. Move or reconcile it explicitly before adding the module.`);
+        }
+      }
+    }
+  }
+
+  await assertMutationTargets(targetDir, ["package.json", ".brightweb/app-manifest.json", ...Object.keys(managedWrites), ...overlayFiles, ...migrationPlan.writes.map((write) => path.relative(targetDir, write.targetPath))]);
 
   const summary = [
     "bw add",
@@ -83,8 +121,19 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
   output.write(`${summary.join("\n")}\n`);
   if (argvOptions.dryRun) return { dryRun: true, newModules, migrationPlan };
 
+  if (newModules.length === 0) return { dryRun: false, newModules, migrationPlan };
+
   if (newModules.length > 0) await fs.writeFile(packageJsonPath, `${JSON.stringify(nextPackageJson, null, 2)}\n`, "utf8");
-  for (const overlay of overlays) await fs.cp(overlay.source, targetDir, { recursive: true });
+  const copiedPaths = new Set();
+  for (const overlay of overlays) await fs.cp(overlay.source, targetDir, {
+    recursive: true,
+    filter: async (source, destination) => {
+      const relativePath = path.relative(targetDir, destination);
+      if (protectedPaths.has(relativePath)) return false;
+      if ((await fs.stat(source)).isFile()) copiedPaths.add(relativePath);
+      return true;
+    },
+  });
   for (const [relativePath, content] of Object.entries(managedWrites)) {
     const targetPath = path.join(targetDir, relativePath);
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
@@ -95,13 +144,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);
-  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 };
+  for (const [relativePath, record] of Object.entries(collectedScaffoldFiles)) {
+    // Existing baselines describe generated bytes, never arbitrary app edits.
+    // Refresh only tracked outputs actually rendered by this command.
+    if (Object.hasOwn(managedWrites, relativePath) || copiedPaths.has(relativePath)) {
+      appManifest.scaffoldFiles[relativePath] = { ...appManifest.scaffoldFiles[relativePath], ...record };
+    }
+  }
   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/adopt.mjs

@@ -10,15 +10,16 @@ import {
   findWorkspaceRoot,
   loadModuleCatalog,
   readConfiguredModuleFlags,
+  readAppManifest,
   writeAppManifest,
 } from "./app-manifest.mjs";
 import { pathExists, readJsonIfPresent } from "./generator.mjs";
 import { findAppMigrationsDirectory, getModuleMigrations } from "./migrations.mjs";
-import { inventoryScaffoldFiles, resolveTemplateRoot } from "./scaffold.mjs";
+import { inventoryScaffoldFiles, preserveScaffoldDecisions, resolveTemplateRoot, scaffoldDrift } from "./scaffold.mjs";
 import { detectDependencyMode, detectTemplate } from "./update.mjs";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const HELP = `Usage: bw adopt [options]\n\nOptions:\n  --target-dir <path>                 App directory (defaults to cwd)\n  --workspace-root <path>             BrightWeb workspace root\n  --cursor <key>=<migrationFilename>  Override a migration cursor (repeatable)\n  --owned-surface <name>              Record an app-owned surface (repeatable)\n  --own <path>                        Mark an existing scaffold file app-owned (repeatable)\n  --skip <path>                       Mark a missing scaffold file intentionally absent (repeatable)\n  --allow-uncursored                   Allow doctor to warn instead of fail on null cursors\n  --force                              Replace an existing app manifest\n  --dry-run                            Print the manifest and warnings without writing\n  --help                               Show this help`;
+const HELP = `Usage: bw adopt [options]\n\nOptions:\n  --target-dir <path>                 App directory (defaults to cwd)\n  --workspace-root <path>             BrightWeb workspace root\n  --cursor <key>=<migrationFilename>  Override a migration cursor (repeatable)\n  --owned-surface <name>              Record an app-owned surface (repeatable)\n  --own <path>                        Mark an existing scaffold file app-owned (repeatable)\n  --skip <path>                       Mark a missing scaffold file intentionally absent (repeatable)\n  --allow-uncursored                   Allow doctor to warn instead of fail on null cursors\n  --force                              Reconcile an existing manifest; preserve ownership decisions\n  --dry-run                            Print the manifest and warnings without writing\n  --help                               Show this help`;
 
 function asList(value) {
   if (value == null) return [];
@@ -54,13 +55,19 @@ function leadingBaselineDomain(content) {
   return line?.match(/^\s*--\s*Brightweb\s+(.+?)\s+v1\s+baseline\.?\s*$/i)?.[1]?.trim().toLowerCase() || null;
 }
 
-async function bootstrapCursor({ moduleKey, catalogEntry, appMigrations, override, warnings }) {
+async function bootstrapCursor({ moduleKey, catalogEntry, appMigrations, override, retainedCursor, warnings }) {
   const shipped = await getModuleMigrations(moduleKey, catalogEntry);
-  if (shipped.length === 0) return { shipsMigrations: false, cursor: undefined, strategy: "none" };
   if (override) {
     if (!shipped.some((entry) => entry.fileName === override)) throw new Error(`Cursor override for ${moduleKey} does not name a shipped migration: ${override}`);
     return { shipsMigrations: true, cursor: override, strategy: "override" };
   }
+  if (retainedCursor !== undefined) {
+    if (!shipped.some((entry) => entry.fileName === retainedCursor)) {
+      throw new Error(`Retained migration cursor for removed module ${moduleKey} does not name a shipped migration: ${retainedCursor}. Reconcile it with an explicit --cursor ${moduleKey}=<migrationFilename>.`);
+    }
+    return { shipsMigrations: true, cursor: retainedCursor, strategy: "retained" };
+  }
+  if (shipped.length === 0) return { shipsMigrations: false, cursor: undefined, strategy: "none" };
 
   const escapedKey = moduleKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const provenance = latestShippedMatch(shipped, (shippedName) => appMigrations.some(({ content }) => {
@@ -89,9 +96,10 @@ async function bootstrapCursor({ moduleKey, catalogEntry, appMigrations, overrid
 
 export async function adoptBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
   if (argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
-  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const targetDir = await fs.realpath(path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd()));
   const existingManifestPath = path.join(targetDir, APP_MANIFEST_PATH);
-  if (await pathExists(existingManifestPath) && !argvOptions.force) throw new Error(`Refusing to overwrite existing ${APP_MANIFEST_PATH}; pass --force to replace it.`);
+  if (await pathExists(existingManifestPath) && !argvOptions.force) throw new Error(`Refusing to overwrite existing ${APP_MANIFEST_PATH}; pass --force to reconcile it while preserving ownership decisions.`);
+  const previousManifest = await readAppManifest(targetDir, { required: false });
   const packageJson = await readJsonIfPresent(path.join(targetDir, "package.json"));
   if (!packageJson) throw new Error(`Target directory does not contain package.json: ${targetDir}`);
 
@@ -123,6 +131,11 @@ export async function adoptBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
   const scaffold = template === "platform"
     ? await inventoryScaffoldFiles({ targetDir, moduleKeys: Object.keys(modules), templateRoot })
     : { records: {}, unsupported: [] };
+  const previousScaffold = await scaffoldDrift(targetDir, previousManifest?.scaffoldFiles);
+  scaffold.records = preserveScaffoldDecisions(scaffold.records, previousManifest?.scaffoldFiles, previousScaffold.protectedPaths);
+  for (const entry of (await scaffoldDrift(targetDir, scaffold.records)).entries) {
+    scaffold.records[entry.relativePath].status = entry.status;
+  }
   const ownedPaths = new Set(asList(argvOptions.own).map(String));
   const skippedPaths = new Set(asList(argvOptions.skip).map(String));
   for (const relativePath of [...ownedPaths, ...skippedPaths]) {
@@ -144,14 +157,23 @@ export async function adoptBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
   }
 
   const overrides = parseCursorOverrides(argvOptions.cursor);
-  const unknownOverride = Object.keys(overrides).find((key) => !catalog[key]);
+  const unknownOverride = Object.keys(overrides).find((key) => !Object.hasOwn(catalog, key));
   if (unknownOverride) throw new Error(`Unknown module key in --cursor: ${unknownOverride}`);
   const appMigrations = template === "platform" ? await migrationFiles(targetDir) : [];
   const migrationCursor = {};
   const cursorStrategies = {};
-  const migrationKeys = template === "platform" ? Array.from(new Set(["core", "admin", ...Object.keys(modules)])) : [];
+  const installedMigrationKeys = new Set(template === "platform" ? ["core", "admin", ...Object.keys(modules)] : []);
+  const migrationKeys = template === "platform"
+    ? Array.from(new Set([...installedMigrationKeys, ...Object.keys(previousManifest?.migrationCursor || {}), ...Object.keys(overrides)]))
+    : [];
   for (const moduleKey of migrationKeys) {
-    const result = await bootstrapCursor({ moduleKey, catalogEntry: catalog[moduleKey], appMigrations, override: overrides[moduleKey], warnings });
+    if (!Object.hasOwn(catalog, moduleKey)) throw new Error(`Unknown retained migration module: ${moduleKey}. Reconcile its history before re-adopting.`);
+    // Removing package wiring never removes applied history. Preserve an exact
+    // retained cursor rather than advancing it from files copied by older tools.
+    const retainedCursor = !installedMigrationKeys.has(moduleKey)
+      ? previousManifest?.migrationCursor?.[moduleKey]
+      : undefined;
+    const result = await bootstrapCursor({ moduleKey, catalogEntry: catalog[moduleKey], appMigrations, override: overrides[moduleKey], retainedCursor, warnings });
     if (result.shipsMigrations) {
       migrationCursor[moduleKey] = result.cursor;
       cursorStrategies[moduleKey] = result.strategy;
@@ -172,7 +194,7 @@ export async function adoptBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
     scaffoldFiles: scaffold.records,
     managedFiles: template === "platform" ? MANAGED_APP_FILES : ["docs/ai/app-context.json"],
     migrationCursor,
-    ownedSurfaces: Array.from(new Set(asList(argvOptions.ownedSurface).map(String))),
+    ownedSurfaces: Array.from(new Set([...(previousManifest?.ownedSurfaces || []), ...asList(argvOptions.ownedSurface).map(String)])),
     adoptionNotes: {
       allowUncursored: argvOptions.allowUncursored === true,
       cursorStrategies,

package/src/app-manifest.mjs

@@ -1,3 +1,6 @@
+import { MANAGED_PLATFORM_FILES, isAppOwnedSeed } from "./file-policy.mjs";
+import semver from "semver";
+import { assertMutationTargets } from "./mutation-paths.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -17,13 +20,7 @@ async function readJsonIfPresent(filePath) {
 }
 
 export const APP_MANIFEST_PATH = path.join(".brightweb", "app-manifest.json");
-export const MANAGED_APP_FILES = [
-  "next.config.ts",
-  "app/globals.css",
-  "config/modules.ts",
-  "config/shell.ts",
-  "docs/ai/app-context.json",
-];
+export const MANAGED_APP_FILES = MANAGED_PLATFORM_FILES;
 
 export const MODULE_PACKAGES = {
   admin: "@brightweblabs/module-admin",
@@ -44,36 +41,13 @@ const FALLBACK_REQUIRES = {
 
 export function cleanVersion(version) {
   if (typeof version !== "string") return null;
-  const match = version.match(/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
-  return match?.[1] || null;
-}
-
-function compareVersions(left, right) {
-  const a = cleanVersion(left)?.split("-")[0].split(".").map(Number) || [];
-  const b = cleanVersion(right)?.split("-")[0].split(".").map(Number) || [];
-  for (let index = 0; index < 3; index += 1) {
-    if ((a[index] || 0) !== (b[index] || 0)) return (a[index] || 0) - (b[index] || 0);
-  }
-  return 0;
+  return semver.valid(version.trim().replace(/^[~^]\s*/, ""));
 }
 
 export function satisfiesVersion(version, range) {
-  const normalized = cleanVersion(version);
-  if (!normalized || typeof range !== "string") return false;
-  if (range === "*" || range === "workspace:*") return true;
-  const expectedMatch = range.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
-  const expected = expectedMatch ? `${expectedMatch[1]}.${expectedMatch[2] || "0"}.${expectedMatch[3] || "0"}` : null;
-  if (!expected) return false;
-  if (range.trim().startsWith(">=")) return compareVersions(normalized, expected) >= 0;
-  if (range.trim().startsWith("^")) {
-    return normalized.split(".")[0] === expected.split(".")[0] && compareVersions(normalized, expected) >= 0;
-  }
-  if (range.trim().startsWith("~")) {
-    const actualParts = normalized.split(".");
-    const expectedParts = expected.split(".");
-    return actualParts[0] === expectedParts[0] && actualParts[1] === expectedParts[1] && compareVersions(normalized, expected) >= 0;
-  }
-  return normalized === expected;
+  if (typeof version !== "string" || typeof range !== "string" || !semver.valid(version)) return false;
+  if (range === "workspace:*") return true;
+  return semver.satisfies(version, range);
 }
 
 export async function hashFile(filePath) {
@@ -82,6 +56,7 @@ export async function hashFile(filePath) {
 }
 
 export async function readAppManifest(targetDir, { required = true } = {}) {
+  await assertMutationTargets(targetDir, [APP_MANIFEST_PATH]);
   const manifestPath = path.join(targetDir, APP_MANIFEST_PATH);
   const manifest = await readJsonIfPresent(manifestPath);
   if (!manifest && required) {
@@ -95,6 +70,7 @@ export async function readAppManifest(targetDir, { required = true } = {}) {
 }
 
 export async function writeAppManifest(targetDir, manifest) {
+  await assertMutationTargets(targetDir, [APP_MANIFEST_PATH]);
   const manifestPath = path.join(targetDir, APP_MANIFEST_PATH);
   await fs.mkdir(path.dirname(manifestPath), { recursive: true });
   const temporaryPath = `${manifestPath}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
@@ -178,7 +154,7 @@ export async function collectScaffoldFiles(targetDir, selectedModules) {
   const result = {};
   for (const [relativePath, moduleKey] of Array.from(files.entries()).sort()) {
     const targetPath = resolveSafeRelativePath(targetDir, relativePath, "Scaffold file path");
-    if (await pathExists(targetPath)) result[relativePath] = { module: moduleKey, hash: await hashFile(targetPath), status: "current" };
+    if (await pathExists(targetPath)) result[relativePath] = { module: moduleKey, hash: await hashFile(targetPath), status: "current", ...(isAppOwnedSeed(relativePath) ? { intent: "owned" } : {}) };
   }
   return result;
 }

package/src/constants.mjs

@@ -116,6 +116,7 @@ export const MODULE_STARTER_FILES = {
     "app/(shell)/projetos/[projectId]/page.tsx",
     "app/(shell)/projetos/[projectId]/quadro/page.tsx",
     "app/(shell)/projetos/[projectId]/tarefas/page.tsx",
+    "app/(shell)/account/perfil/page.tsx",
     "app/(shell)/account/projetos/page.tsx",
     "app/(shell)/account/projetos/loading.tsx",
     "app/(shell)/account/projetos/[projectId]/page.tsx",
@@ -186,16 +187,16 @@ export const PLATFORM_STARTER_FILES = [
 ];
 
 export const APP_DEPENDENCY_DEFAULTS = {
-  "@brightweblabs/app-shell": "^0.16.2",
-  "@brightweblabs/core-auth": "^0.12.1",
+  "@brightweblabs/app-shell": "^0.16.3",
+  "@brightweblabs/core-auth": "^0.12.2",
   "@brightweblabs/infra": "^0.7.0",
-  "@brightweblabs/module-admin": "^0.9.6",
-  "@brightweblabs/module-crm": "^0.18.3",
-  "@brightweblabs/module-marketing": "^0.5.1",
-  "@brightweblabs/module-orgs": "^0.7.2",
-  "@brightweblabs/module-projects": "^0.19.2",
+  "@brightweblabs/module-admin": "^0.9.7",
+  "@brightweblabs/module-crm": "^0.18.4",
+  "@brightweblabs/module-marketing": "^0.5.2",
+  "@brightweblabs/module-orgs": "^0.7.3",
+  "@brightweblabs/module-projects": "^0.19.3",
   "@brightweblabs/theme": "^0.8.4",
-  "@brightweblabs/ui": "^1.5.5",
+  "@brightweblabs/ui": "^1.5.6",
   "geist": "1.7.2",
   "lucide-react": "^1.8.0",
   "next": "^16.0.0",

package/src/doctor.mjs

@@ -3,11 +3,11 @@ import path from "node:path";
 import { stdout as output } from "node:process";
 import { APP_DEPENDENCY_DEFAULTS, BRIGHTWEB_PACKAGE_NAMES } from "./constants.mjs";
 import { cursorMigrationStatus, exactMigrationCompatibilityStatus } from "./migrations.mjs";
-import { findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, readConfiguredModuleFlags, satisfiesVersion, validateAppManifest, writeAppManifest } from "./app-manifest.mjs";
+import { findWorkspaceRoot, hashFile, 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";
+import { canonicalScaffoldHash, 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  --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"];
@@ -378,6 +378,18 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
   add(topologyProblems.length ? "FAIL" : "PASS", "topology", topologyProblems.join("; ") || "Module requirements are satisfied.");
 
   const scaffold = await scaffoldDrift(targetDir, appManifest.scaffoldFiles);
+  const ownedTemplateUpdates = [];
+  for (const entry of scaffold.entries) {
+    if (entry.intent !== "owned" || entry.status === "missing") continue;
+    const templateHash = await canonicalScaffoldHash({ relativePath: entry.relativePath, manifest: appManifest, targetDir, workspaceRoot });
+    // Ownership preserves the recorded baseline during upgrades; it does not prove
+    // that later starter fixes have been reconciled into the app's custom file.
+    if (templateHash && templateHash !== appManifest.scaffoldFiles[entry.relativePath].hash
+      && templateHash !== await hashFile(path.join(targetDir, entry.relativePath))) {
+      ownedTemplateUpdates.push(entry.relativePath);
+    }
+  }
+  if (ownedTemplateUpdates.length) add("WARN", "scaffold-owned-template-updates", `Current templates changed for preserved app-owned files: ${ownedTemplateUpdates.join(", ")}. Compatibility is NOT VERIFIED. Run bw diff, reconcile relevant fixes and verify behavior. After review, use bw scaffold manage followed by bw scaffold own for each custom file to record the current template baseline; these commands do not replace file contents.`);
   const scaffoldGroups = {
     current: scaffold.entries.filter((entry) => entry.status === "current" && entry.intent !== "skipped"),
     owned: scaffold.entries.filter((entry) => entry.intent === "owned" && entry.status === "drifted"),
@@ -391,7 +403,7 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
   if (scaffoldGroups.undecidedDrift.length) add("WARN", "scaffold-undecided-drift", `Unacknowledged drift: ${scaffoldGroups.undecidedDrift.map((entry) => entry.relativePath).join(", ")} (use bw scaffold own or bw diff).`);
   if (scaffoldGroups.undecidedMissing.length) add("WARN", "scaffold-undecided-missing", `Unacknowledged missing files: ${scaffoldGroups.undecidedMissing.map((entry) => entry.relativePath).join(", ")} (use bw scaffold skip after review).`);
   if (scaffoldGroups.mismatched.length) add("FAIL", "scaffold-intent-mismatch", `Recorded scaffold intent no longer matches reality: ${scaffoldGroups.mismatched.map((entry) => `${entry.relativePath} (${entry.intent}, ${entry.status})`).join(", ")}.`);
-  const scaffoldStatus = scaffoldGroups.mismatched.length ? "FAIL" : scaffoldGroups.undecidedDrift.length || scaffoldGroups.undecidedMissing.length ? "WARN" : "PASS";
+  const scaffoldStatus = scaffoldGroups.mismatched.length ? "FAIL" : ownedTemplateUpdates.length || scaffoldGroups.undecidedDrift.length || scaffoldGroups.undecidedMissing.length ? "WARN" : "PASS";
   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"}.`);
 
@@ -456,7 +468,7 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
       add("INFO", `migration-legacy-equivalent-${key}`, `${key}: ${status.legacyEquivalent.length} immutable historical migration file${status.legacyEquivalent.length === 1 ? " matches" : "s match"} a reviewed SQL-equivalent legacy hash.`);
     }
   }
-  add("WARN", "db-objects", "SKIP live database checks are not available yet.");
+  add("WARN", "db-objects", "NOT VERIFIED: live database objects, applied migrations, and authenticated row-level permissions. Local migration provenance does not establish deployed behavior; apply pending migrations and run authenticated admin/client permission checks against the target database.");
   return finish(checks, argvOptions, appManifest, targetDir);
 }
 

package/src/file-policy.mjs

@@ -0,0 +1,40 @@
+import { MODULE_STARTER_FILES, PLATFORM_STARTER_FILES } from "./constants.mjs";
+
+export const MODULE_SELECTED_FILES = [
+  "app/api/invitations/_dependencies.ts",
+  "app/api/organizations/route.ts",
+  "app/api/organizations/[id]/route.ts",
+  "app/api/organizations/[id]/invitations/route.ts",
+  "app/api/organizations/[id]/invitations/[invitationId]/route.ts",
+  "app/api/organizations/[id]/members/[profileId]/route.ts",
+];
+export const MANAGED_PLATFORM_FILES = [
+  "next.config.ts", "app/globals.css", "config/module-toolbar-controls.tsx",
+  "config/modules.ts", "config/shell.ts", ...MODULE_SELECTED_FILES,
+  "docs/ai/app-context.json",
+];
+export const MANAGED_SITE_FILES = ["docs/ai/app-context.json"];
+export const APP_OWNED_FILES = [
+  "config/brand.ts", "config/shell.overrides.ts", "app/theme.css", "app/fonts.ts",
+  "config/social-media-plan.json", "app/(shell)/marketing/social-media/page.tsx",
+  "public/brand/logo-mark.svg", "public/brand/logo-light.svg", "public/brand/logo-dark.svg",
+  "docs/ai/README.md", "docs/ai/examples.md", "AGENTS.md", "README.md",
+];
+export function fileOwnership({ template = "platform", modules = [] } = {}) {
+  const generated = template === "platform" ? MANAGED_PLATFORM_FILES : MANAGED_SITE_FILES;
+  const appOwned = template === "platform" ? APP_OWNED_FILES : ["config/site.ts", "app/fonts.ts", "app/globals.css", "app/layout.tsx", "next.config.ts", "postcss.config.mjs", "tsconfig.json", "docs/ai/README.md", "docs/ai/examples.md", "AGENTS.md", "README.md"];
+  const scaffold = template === "platform" ? [...new Set([...PLATFORM_STARTER_FILES, ...modules.flatMap((key) => MODULE_STARTER_FILES[key] || [])])].filter((p) => !generated.includes(p) && !appOwned.includes(p)) : [];
+  return { default: "app-owned", appOwned: [...appOwned], scaffoldManaged: scaffold, generated: [...generated], precedence: ["explicit-intent-or-drift", "exact-path-policy", "recorded-scaffold", "app-owned-default"] };
+}
+export function isAppOwnedSeed(relativePath) { return APP_OWNED_FILES.includes(relativePath); }
+
+/** Fail before writing when a renderer and its ownership policy disagree. */
+export function assertGeneratedFileInventory(files, expectedPaths, label) {
+  const actualPaths = Object.keys(files);
+  const missing = expectedPaths.filter((relativePath) => !Object.hasOwn(files, relativePath));
+  const unexpected = actualPaths.filter((relativePath) => !expectedPaths.includes(relativePath));
+  if (missing.length || unexpected.length) {
+    throw new Error(`${label} inventory mismatch: missing ${missing.join(", ") || "none"}; unexpected ${unexpected.join(", ") || "none"}.`);
+  }
+  return files;
+}

package/src/generator.mjs

@@ -1,3 +1,4 @@
+import { fileOwnership, assertGeneratedFileInventory, MANAGED_PLATFORM_FILES, MODULE_SELECTED_FILES } from "./file-policy.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -690,20 +691,7 @@ export function createAppContextFile({
         },
         starterRoutes: getSiteStarterRoutes(),
         ownership: {
-          appOwned: [
-            "config/**",
-            "docs/ai/**",
-            "public/**",
-            "AGENTS.md",
-            "README.md",
-          ],
-          scaffoldManaged: [
-            "app/layout.tsx",
-            "app/globals.css",
-            "next.config.ts",
-            "postcss.config.mjs",
-            "tsconfig.json",
-          ],
+          ...fileOwnership({ template: "site" }),
           packageOwned: [],
         },
         agentRules: {
@@ -753,22 +741,7 @@ export function createAppContextFile({
       },
       starterRoutes: getPlatformStarterRoutes(selectedModules),
       ownership: {
-        appOwned: [
-          "config/**",
-          "docs/ai/**",
-          "public/brand/**",
-          "AGENTS.md",
-          "README.md",
-        ],
-        scaffoldManaged: [
-          "app/layout.tsx",
-          "app/globals.css",
-          "app/**/page.tsx",
-          "app/**/route.ts",
-          "next.config.ts",
-          "postcss.config.mjs",
-          "tsconfig.json",
-        ],
+        ...fileOwnership({ template: "platform", modules: selectedModules }),
         packageOwned: [
           ...CORE_PACKAGES,
           ...(selectedModules.includes("crm") || selectedModules.includes("marketing") || selectedModules.includes("projects") ? [ORGS_PACKAGE_NAME] : []),
@@ -1182,7 +1155,7 @@ export function createOptionalModuleRouteFiles(selectedModules) {
       'const acceptOrganizationInvitation = async (_client: never, _input: unknown): Promise<never> => { throw new Error("Convite não encontrado."); };',
     ] : []),
     ...(!crmEnabled ? [
-      "const ensureCrmContactForProfile = async () => ({ success: true as const });",
+      "const ensureCrmContactForProfile = undefined;",
     ] : []),
     (!adminEnabled || !orgsEnabled || !crmEnabled) ? "" : null,
     "export const invitationHttpDependencies = {",
@@ -1213,7 +1186,7 @@ export function createOptionalModuleRouteFiles(selectedModules) {
     "",
     ].filter((line) => line !== null).join("\n");
 
-  return {
+  return assertGeneratedFileInventory({
     "app/api/invitations/_dependencies.ts": invitationDependencies,
     "app/api/organizations/route.ts": createOrganizationRoute([
       crmEnabled
@@ -1287,7 +1260,20 @@ export function createOptionalModuleRouteFiles(selectedModules) {
         "}",
         "",
       ].join("\n"),
-  };
+  }, MODULE_SELECTED_FILES, "Module-selected routes");
+}
+
+/** The same module-aware outputs drive initial scaffolding and every topology refresh. */
+export async function createManagedPlatformFiles({ slug, selectedModules, dbInstallPlan }) {
+  return assertGeneratedFileInventory({
+    "next.config.ts": createNextConfig({ template: "platform", selectedModules }),
+    "app/globals.css": await createPlatformGlobalsCss(selectedModules),
+    "config/module-toolbar-controls.tsx": createModuleToolbarControlsConfig(selectedModules),
+    "config/modules.ts": createPlatformModulesConfigFile(selectedModules),
+    "config/shell.ts": createShellConfig(selectedModules),
+    ...createOptionalModuleRouteFiles(selectedModules),
+    "docs/ai/app-context.json": createAppContextFile({ slug, template: "platform", selectedModules, dbInstallPlan }),
+  }, MANAGED_PLATFORM_FILES, "Managed platform files");
 }
 
 function createSiteConfigFile(slug) {
@@ -1628,6 +1614,7 @@ async function scaffoldPlatformProject({
   dbRegistry,
 }) {
   const brandValues = createDerivedBrandValues(answers.slug);
+  const managedFiles = await createManagedPlatformFiles({ slug: answers.slug, selectedModules, dbInstallPlan });
   const baseTemplateDir = path.join(TEMPLATE_ROOT, "base");
 
   await ensureDirectory(path.dirname(targetDir));
@@ -1659,30 +1646,14 @@ async function scaffoldPlatformProject({
       2,
     )}\n`,
   );
-  await fs.writeFile(path.join(targetDir, "next.config.ts"), createNextConfig({ template: "platform", selectedModules }));
-  await fs.writeFile(path.join(targetDir, "app", "globals.css"), await createPlatformGlobalsCss(selectedModules));
   await fs.writeFile(
     path.join(targetDir, "config", "brand.ts"),
     createPlatformBrandConfigFile({ slug: answers.slug, brandValues }),
   );
-  await fs.writeFile(path.join(targetDir, "config", "modules.ts"), createPlatformModulesConfigFile(selectedModules));
-  await fs.writeFile(
-    path.join(targetDir, "config", "module-toolbar-controls.tsx"),
-    createModuleToolbarControlsConfig(selectedModules),
-  );
-  await fs.writeFile(path.join(targetDir, "config", "shell.ts"), createShellConfig(selectedModules));
-  for (const [relativePath, content] of Object.entries(createOptionalModuleRouteFiles(selectedModules))) {
+  for (const [relativePath, content] of Object.entries(managedFiles)) {
+    await ensureDirectory(path.dirname(path.join(targetDir, relativePath)));
     await fs.writeFile(path.join(targetDir, relativePath), content);
   }
-  await fs.writeFile(
-    path.join(targetDir, "docs", "ai", "app-context.json"),
-    createAppContextFile({
-      slug: answers.slug,
-      template: "platform",
-      selectedModules,
-      dbInstallPlan,
-    }),
-  );
 
   const vercelConfig = createVercelConfig(answers.supabaseRegion);