create-bw-app 0.27.1 → 0.27.2

package/README.md

@@ -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.2",
   "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

@@ -186,16 +186,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/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);
 

package/src/migrations.mjs

@@ -1,3 +1,4 @@
+import semver from "semver";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
@@ -66,6 +67,9 @@ export async function planMigrationAppends({
   for (const moduleKey of moduleKeys) {
     const migrations = await getModuleMigrations(moduleKey, catalog[moduleKey]);
     const cursor = migrationCursor[moduleKey];
+    if (cursor != null && !migrations.some((entry) => entry.fileName === cursor)) {
+      throw new Error(`Migration cursor ${cursor} does not exist in the shipped ${moduleKey} history; reconcile it explicitly before upgrading.`);
+    }
     const upperBound = migrationUpperBounds[moduleKey];
     let migrationsInScope = migrations;
     if (upperBound) {
@@ -75,9 +79,6 @@ export async function planMigrationAppends({
       }
       if (cursor) {
         const cursorIndex = migrations.findIndex((entry) => entry.fileName === cursor);
-        if (cursorIndex === -1) {
-          throw new Error(`Migration cutoff blocked: current cursor ${cursor} does not exist in the shipped ${moduleKey} migration history.`);
-        }
         if (upperBoundIndex < cursorIndex) {
           throw new Error(`Migration cutoff ${upperBound} is before the current ${moduleKey} cursor ${cursor}.`);
         }
@@ -117,6 +118,9 @@ export async function cursorMigrationStatus({ targetDir, moduleKey, cursor, cata
   const migrations = await getModuleMigrations(moduleKey, catalogEntry);
   if (migrations.length === 0) return { shipsMigrations: false, missing: [] };
   if (!cursor) return { shipsMigrations: true, missing: ["migration cursor"] };
+  if (!migrations.some((entry) => entry.fileName === cursor)) {
+    return { shipsMigrations: true, missing: [`cursor ${cursor} does not exist in the shipped migration history`] };
+  }
   const expected = migrations.filter((entry) => entry.fileName <= cursor);
   const migrationsDir = await findAppMigrationsDirectory(targetDir);
   const installed = [];
@@ -149,13 +153,7 @@ const REVIEWED_LEGACY_MIGRATION_HASHES = new Map([
 ]);
 
 function compareSemver(left, right) {
-  const leftParts = String(left).split(".").map((value) => Number.parseInt(value, 10));
-  const rightParts = String(right).split(".").map((value) => Number.parseInt(value, 10));
-  if (leftParts.length !== 3 || rightParts.length !== 3 || [...leftParts, ...rightParts].some(Number.isNaN)) return null;
-  for (let index = 0; index < 3; index += 1) {
-    if (leftParts[index] !== rightParts[index]) return leftParts[index] < rightParts[index] ? -1 : 1;
-  }
-  return 0;
+  return semver.valid(left) && semver.valid(right) ? semver.compare(left, right) : null;
 }
 
 export async function exactMigrationCompatibilityStatus({ targetDir, moduleKey, cursor, catalogEntry, allowDeferred = false }) {

package/src/mutation-paths.mjs

@@ -0,0 +1,28 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { normalizeSafeRelativePath } from "./safe-path.mjs";
+
+// The caller-selected app root may be an alias (including macOS /var). Resolve
+// that boundary once; links beneath it are never writable lifecycle targets.
+// This preflight assumes no concurrent filesystem edits; it is not a sandbox.
+export async function assertMutationTargets(targetDir, relativePaths) {
+  const root = await fs.realpath(path.resolve(targetDir));
+  if (!(await fs.stat(root)).isDirectory()) throw new Error("App root must be a directory.");
+  for (const input of new Set(relativePaths)) {
+    const relativePath = normalizeSafeRelativePath(input, "Mutation target");
+    let current = root;
+    const parts = relativePath.split("/");
+    for (const [index, part] of parts.entries()) {
+      current = path.join(current, part);
+      const stat = await fs.lstat(current).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (!stat) break;
+      if (stat.isSymbolicLink()) throw new Error(`Lifecycle writes do not follow symlinks: ${relativePath}`);
+      if (index < parts.length - 1 ? !stat.isDirectory() : !stat.isFile()) {
+        throw new Error(`Unexpected filesystem type at mutation target: ${relativePath}`);
+      }
+    }
+  }
+}