create-bw-app 0.27.1 → 0.27.3

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}`);
+      }
+    }
+  }
+}

package/src/removal-dependents.mjs

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// Conservative literal-import diagnostic, not a complete application bundler.
+// Generated replacements and deliberate clean deletions are outside the surviving set.
+export async function findSurvivingPackageImports(targetDir, packageName, excludedPaths) {
+  const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const imports = new RegExp(`(?:\\bfrom\\s*|\\bimport\\s*(?:\\(\\s*)?|\\brequire\\s*\\(\\s*)["']${escaped}(?:/[^"']*)?["']`);
+  const stylesheetImports = new RegExp(`@(?:import|reference)\\s*(?:url\\(\\s*)?["']?${escaped}(?:/[^"'\\s);]+)?(?=["'\\s);]|$)`, "i");
+  const sourceExtension = /\.(?:[cm]?[jt]sx?|mdx|css)$/i;
+  const findings = [];
+  const ignored = new Set(["node_modules", ".git", ".next", ".brightweb", "supabase", "dist", "build"]);
+  async function visit(directory) {
+    for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+      if (ignored.has(entry.name)) continue;
+      const fullPath = path.join(directory, entry.name);
+      const relativePath = path.relative(targetDir, fullPath);
+      if (excludedPaths.has(relativePath)) continue;
+      if (entry.isSymbolicLink()) {
+        // Do not read outside the app or silently declare linked source safe.
+        if (entry.name.includes(".") && !sourceExtension.test(entry.name)) continue;
+        findings.push(`${relativePath} (linked source; inspect dependencies explicitly)`);
+      } else if (entry.isDirectory()) await visit(fullPath);
+      else if (sourceExtension.test(entry.name)) {
+        const source = await fs.readFile(fullPath, "utf8");
+        if ((/\.css$/i.test(entry.name) ? stylesheetImports : imports).test(source)) findings.push(relativePath);
+      }
+    }
+  }
+  await visit(targetDir);
+  return findings.sort();
+}

package/src/remove.mjs

@@ -1,3 +1,5 @@
+import { findSurvivingPackageImports } from "./removal-dependents.mjs";
+import { assertMutationTargets } from "./mutation-paths.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { stdout as output } from "node:process";
@@ -10,18 +12,13 @@ import {
   writeAppManifest,
 } from "./app-manifest.mjs";
 import {
-  createAppContextFile,
   createDbInstallPlan,
-  createModuleToolbarControlsConfig,
-  createNextConfig,
-  createOptionalModuleRouteFiles,
-  createPlatformGlobalsCss,
-  createPlatformModulesConfigFile,
-  createShellConfig,
+  createManagedPlatformFiles,
   getDbModuleRegistry,
   pathExists,
   readJsonIfPresent,
 } from "./generator.mjs";
+import { assertNoUntrackedScaffoldWrites, preserveScaffoldDecisions, scaffoldDrift } from "./scaffold.mjs";
 import { resolveSafeRelativePath } from "./safe-path.mjs";
 
 const HELP = `Usage: bw remove <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 removal plan without writing\n  --yes                     Apply the removal plan\n  --help                    Show this help`;
@@ -38,7 +35,7 @@ function databaseNotice(moduleKey, ownedObjects) {
 
 export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtimeOptions = {}) {
   if (!moduleKey || 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 appManifest = await readAppManifest(targetDir);
   if (!appManifest.modules[moduleKey]) throw new Error(`Module ${moduleKey} is not installed according to .brightweb/app-manifest.json.`);
   const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
@@ -61,34 +58,34 @@ export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtime
     workspaceMode: Object.values(nextPackageJson.dependencies || {}).some((value) => String(value).startsWith("workspace:")),
     registry: dbRegistry,
   });
-  const managedWrites = {
-    "next.config.ts": createNextConfig({ template: "platform", selectedModules: remainingModules }),
-    "app/globals.css": await createPlatformGlobalsCss(remainingModules),
-    "config/module-toolbar-controls.tsx": createModuleToolbarControlsConfig(remainingModules),
-    "config/modules.ts": createPlatformModulesConfigFile(remainingModules),
-    "config/shell.ts": createShellConfig(remainingModules),
-    "docs/ai/app-context.json": createAppContextFile({ slug: appManifest.app.slug, template: "platform", selectedModules: remainingModules.filter((key) => key !== "orgs"), dbInstallPlan }),
-    ...createOptionalModuleRouteFiles(remainingModules),
-  };
+  const managedWrites = await createManagedPlatformFiles({ slug: appManifest.app.slug, selectedModules: remainingModules, dbInstallPlan });
 
-  const cleanFiles = [];
-  const driftedFiles = [];
-  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles || {})) {
-    if (record.module !== moduleKey) continue;
-    const filePath = resolveSafeRelativePath(targetDir, relativePath, "Manifest scaffold file path");
-    if (!(await pathExists(filePath))) continue;
-    if ((record.intent || "managed") === "managed" && await hashFile(filePath) === record.hash) cleanFiles.push(relativePath);
-    else driftedFiles.push(relativePath);
-  }
+  const live = await scaffoldDrift(targetDir, appManifest.scaffoldFiles);
+  const { protectedPaths } = live;
+  for (const relativePath of protectedPaths) delete managedWrites[relativePath];
+  await assertNoUntrackedScaffoldWrites({
+    targetDir,
+    scaffoldFiles: appManifest.scaffoldFiles,
+    moduleKeys: remainingModules,
+    relativePaths: Object.keys(managedWrites),
+  });
+  const retainedFiles = live.entries.filter((entry) => entry.module === moduleKey && protectedPaths.has(entry.relativePath)).map((entry) => entry.relativePath);
+  const moduleFiles = live.entries.filter((entry) => entry.module === moduleKey && entry.status !== "missing");
+  const cleanFiles = moduleFiles.filter((entry) => !protectedPaths.has(entry.relativePath)).map((entry) => entry.relativePath);
+  const driftedFiles = moduleFiles.filter((entry) => protectedPaths.has(entry.relativePath)).map((entry) => entry.relativePath);
+  await assertMutationTargets(targetDir, ["package.json", ".brightweb/app-manifest.json", ...cleanFiles, ...Object.keys(managedWrites)]);
+  const dependentsOnDisk = await findSurvivingPackageImports(targetDir, packageName, new Set([...cleanFiles, ...Object.keys(managedWrites)]));
+  if (dependentsOnDisk.length) throw new Error(`Cannot remove ${moduleKey}: surviving app files depend on ${packageName}: ${dependentsOnDisk.join(", ")}. Reconcile those imports before removal; app-owned content was not changed.`);
   const notice = databaseNotice(moduleKey, catalog[moduleKey]?.manifest?.database?.ownedObjects || []);
   const apply = argvOptions.yes === true && argvOptions.dryRun !== true;
   output.write(`bw remove ${moduleKey}${apply ? "" : " (plan only; pass --yes to apply)"}\n`);
   output.write(`Dependency to remove: ${packageName}\n`);
   output.write(`Clean scaffold files to remove: ${cleanFiles.join(", ") || "none"}\n`);
+  output.write(`Scaffold decisions retained for re-add: ${retainedFiles.join(", ") || "none"}\n`);
   output.write(`Drifted scaffold files left in place: ${driftedFiles.join(", ") || "none"}\n`);
   for (const relativePath of driftedFiles) output.write(`WARN ${relativePath} is drifted and will be left in place.\n`);
   for (const line of notice) output.write(`${line}\n`);
-  if (!apply) return { dryRun: true, moduleKey, cleanFiles, driftedFiles, notice };
+  if (!apply) return { dryRun: true, moduleKey, cleanFiles, driftedFiles, retainedFiles, notice };
 
   await fs.writeFile(packagePath, `${JSON.stringify(nextPackageJson, null, 2)}\n`, "utf8");
   for (const relativePath of cleanFiles) await fs.rm(resolveSafeRelativePath(targetDir, relativePath, "Manifest scaffold file path"));
@@ -101,7 +98,11 @@ export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtime
   if (appManifest.modules.orgs) {
     appManifest.modules.orgs.exposed = remainingModules.some((key) => ["crm", "marketing", "projects"].includes(key));
   }
-  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles || {})) if (record.module === moduleKey) delete appManifest.scaffoldFiles[relativePath];
+  appManifest.scaffoldFiles = preserveScaffoldDecisions(
+    Object.fromEntries(Object.entries(appManifest.scaffoldFiles).filter(([, record]) => record.module !== moduleKey)),
+    appManifest.scaffoldFiles,
+    protectedPaths,
+  );
   for (const relativePath of Object.keys(managedWrites)) {
     const record = appManifest.scaffoldFiles[relativePath];
     if (!record) continue;
@@ -112,7 +113,7 @@ export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtime
   }
   await writeAppManifest(targetDir, appManifest);
   output.write(`Removed ${moduleKey} package wiring and ${cleanFiles.length} clean scaffold file${cleanFiles.length === 1 ? "" : "s"}. Install dependencies next.\n`);
-  return { dryRun: false, moduleKey, cleanFiles, driftedFiles, notice };
+  return { dryRun: false, moduleKey, cleanFiles, driftedFiles, retainedFiles, notice };
 }
 
 export { HELP as REMOVE_HELP };

package/src/scaffold-cmd.mjs

@@ -1,8 +1,9 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { stdout as output } from "node:process";
 import { findWorkspaceRoot, hashFile, readAppManifest, writeAppManifest } from "./app-manifest.mjs";
 import { pathExists } from "./generator.mjs";
-import { findTrackedTemplate, scaffoldDrift } from "./scaffold.mjs";
+import { canonicalScaffoldHash, scaffoldDrift } from "./scaffold.mjs";
 import { normalizeSafeRelativePath, resolveSafeRelativePath } from "./safe-path.mjs";
 
 const HELP = `Usage: bw scaffold <action> [paths...] [options]\n\nActions:\n  list                List tracked files, live status, and intent\n  own <path>...       Mark existing tracked files as app-owned\n  skip <path>...      Mark missing tracked files as intentionally absent\n  manage <path>...    Return tracked files to BrightWeb management\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --help                    Show this help`;
@@ -14,7 +15,7 @@ export async function scaffoldBrightwebApp(action, paths = [], argvOptions = {},
   if (action !== "list" && paths.length === 0) throw new Error(`bw scaffold ${action} requires at least one tracked <path>.`);
   if (action === "list" && paths.length > 0) throw new Error("bw scaffold list does not accept file paths.");
 
-  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const targetDir = await fs.realpath(path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd()));
   const manifest = await readAppManifest(targetDir);
   const live = await scaffoldDrift(targetDir, manifest.scaffoldFiles);
   if (action === "list") {
@@ -43,15 +44,14 @@ export async function scaffoldBrightwebApp(action, paths = [], argvOptions = {},
     const appPath = resolveSafeRelativePath(targetDir, relativePath, "Manifest scaffold file path");
     const exists = await pathExists(appPath);
     if (action === "manage") {
-      const located = await findTrackedTemplate({ relativePath, manifest, targetDir, workspaceRoot });
-      if (!located.templatePath) throw new Error(`Installed-package template unavailable for ${relativePath}; cannot manage it safely.`);
-      const templateHash = await hashFile(located.templatePath);
+      const templateHash = await canonicalScaffoldHash({ relativePath, manifest, targetDir, workspaceRoot });
+      if (!templateHash) throw new Error(`Installed-package template unavailable for ${relativePath}; cannot manage it safely.`);
       if (exists) {
-        record.hash = await hashFile(appPath);
-        record.status = record.hash === templateHash ? "current" : "drifted";
+        record.status = await hashFile(appPath) === templateHash ? "current" : "drifted";
       } else {
         record.status = "missing";
       }
+      record.hash = templateHash;
     } else {
       record.status = liveByPath.get(relativePath).status;
     }

package/src/scaffold.mjs

@@ -1,3 +1,6 @@
+import { isAppOwnedSeed } from "./file-policy.mjs";
+import { assertMutationTargets } from "./mutation-paths.mjs";
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -34,7 +37,22 @@ export function trackedScaffoldDefinitions(moduleKeys = []) {
   return definitions.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
 }
 
+/** Missing ownership history is not permission to replace an existing scaffold. */
+export async function assertNoUntrackedScaffoldWrites({ targetDir, scaffoldFiles, moduleKeys, relativePaths }) {
+  const tracked = new Set(trackedScaffoldDefinitions(moduleKeys).map((entry) => entry.relativePath));
+  for (const relativePath of relativePaths) {
+    if (!tracked.has(relativePath) || scaffoldFiles[relativePath]) continue;
+    const targetPath = resolveSafeRelativePath(targetDir, relativePath, "Scaffold output path");
+    const exists = await fs.lstat(targetPath).then(() => true, (error) => {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    });
+    if (exists) throw new Error(`Untracked app file conflicts with scaffold output: ${relativePath}. Move or reconcile it explicitly before continuing.`);
+  }
+}
+
 export async function inventoryScaffoldFiles({ targetDir, moduleKeys, templateRoot }) {
+  await assertMutationTargets(targetDir, trackedScaffoldDefinitions(moduleKeys).map((entry) => entry.relativePath));
   const records = {};
   const unsupported = [];
   for (const definition of trackedScaffoldDefinitions(moduleKeys)) {
@@ -47,6 +65,7 @@ export async function inventoryScaffoldFiles({ targetDir, moduleKeys, templateRo
     const templateHash = await hashFile(templatePath);
     const exists = await pathExists(appPath);
     records[definition.relativePath] = {
+      ...(isAppOwnedSeed(definition.relativePath) ? { intent: "owned" } : {}),
       module: definition.moduleKey,
       hash: templateHash,
       status: !exists ? "missing" : await hashFile(appPath) === templateHash ? "current" : "drifted",
@@ -55,14 +74,26 @@ export async function inventoryScaffoldFiles({ targetDir, moduleKeys, templateRo
   return { records, unsupported };
 }
 
+/** Ownership belongs to an exact app path, independently of installed modules. */
+export function preserveScaffoldDecisions(records, previousRecords = {}, protectedPaths = new Set()) {
+  const reconciled = { ...records };
+  for (const [relativePath, record] of Object.entries(previousRecords)) {
+    if (["owned", "skipped"].includes(record.intent) || protectedPaths.has(relativePath)) {
+      reconciled[relativePath] = { ...record };
+    }
+  }
+  return reconciled;
+}
+
 export async function scaffoldDrift(targetDir, scaffoldFiles = {}) {
+  await assertMutationTargets(targetDir, Object.keys(scaffoldFiles));
   const current = [];
   const drifted = [];
   const missing = [];
   const entries = [];
   for (const [relativePath, record] of Object.entries(scaffoldFiles)) {
     const appPath = resolveSafeRelativePath(targetDir, relativePath, "Manifest scaffold file path");
-    const intent = record.intent || "managed";
+    const intent = record.intent === "skipped" ? "skipped" : isAppOwnedSeed(relativePath) ? "owned" : record.intent || "managed";
     let status = "missing";
     if (await pathExists(appPath)) {
       const matchesRecordedHash = await hashFile(appPath) === record.hash;
@@ -73,7 +104,9 @@ export async function scaffoldDrift(targetDir, scaffoldFiles = {}) {
     else if (status === "current") current.push(relativePath);
     else drifted.push(relativePath);
   }
-  return { current, drifted, missing, entries };
+  const intentional = entries.filter((entry) => entry.intent !== "managed").map((entry) => entry.relativePath);
+  const protectedPaths = new Set([...drifted, ...intentional]);
+  return { current, drifted, missing, entries, intentional, protectedPaths };
 }
 
 export async function findTrackedTemplate({ relativePath, manifest, targetDir, workspaceRoot }) {
@@ -89,3 +122,11 @@ export async function findTrackedTemplate({ relativePath, manifest, targetDir, w
 export async function readTextFile(filePath) {
   return fs.readFile(filePath, "utf8");
 }
+
+export async function canonicalScaffoldHash({ relativePath, manifest, targetDir, workspaceRoot }) {
+  const { createOptionalModuleRouteFiles } = await import("./generator.mjs");
+  const generated = createOptionalModuleRouteFiles(Object.keys(manifest.modules || {}))[relativePath];
+  if (generated != null) return `sha256:${createHash("sha256").update(generated).digest("hex")}`;
+  const located = await findTrackedTemplate({ relativePath, manifest, targetDir, workspaceRoot });
+  return located.templatePath ? hashFile(located.templatePath) : null;
+}

package/src/setup.mjs

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import { assertMutationTargets } from "./mutation-paths.mjs";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { readAppManifest, readConfiguredModuleFlags } from "./app-manifest.mjs";
@@ -26,23 +27,12 @@ export default function Page() {
 }
 `;
 
-// Generated paths must remain real directories/files inside the app, even when
-// an intermediate directory or an existing target is a symlink.
 async function inspectTarget(root, relativePath) {
-  let current = root;
-  const parts = relativePath.split("/");
-  for (const [index, part] of parts.entries()) {
-    current = path.join(current, part);
-    let stat;
-    try { stat = await fs.lstat(current); } catch (error) {
-      if (error.code === "ENOENT") return null;
-      throw error;
-    }
-    if (stat.isSymbolicLink()) throw new Error(`Setup does not follow symlinks: ${relativePath}`);
-    if (index < parts.length - 1 && !stat.isDirectory()) throw new Error(`Expected a directory at ${current}`);
-    if (index === parts.length - 1 && !stat.isFile()) throw new Error(`Expected a file at ${relativePath}`);
-  }
-  return fs.readFile(current, "utf8");
+  await assertMutationTargets(root, [relativePath]);
+  return fs.readFile(path.join(root, relativePath), "utf8").catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
 }
 
 function navigationSource(source) {

package/src/update.mjs

@@ -1,3 +1,5 @@
+import { assertMutationTargets } from "./mutation-paths.mjs";
+import { MANAGED_PLATFORM_FILES, MANAGED_SITE_FILES, MODULE_SELECTED_FILES, isAppOwnedSeed } from "./file-policy.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { stdout as output } from "node:process";
@@ -13,13 +15,8 @@ import {
   TEMPLATE_ROOT,
   createAppContextFile,
   createDbInstallPlan,
-  createModuleToolbarControlsConfig,
-  createNextConfig,
-  createOptionalModuleRouteFiles,
+  createManagedPlatformFiles,
   createPackageJson,
-  createPlatformGlobalsCss,
-  createPlatformModulesConfigFile,
-  createShellConfig,
   detectPackageManager,
   getDbModuleRegistry,
   getVersionMap,
@@ -27,33 +24,10 @@ import {
   readJsonIfPresent,
   runInstall,
 } from "./generator.mjs";
-import { readAppManifest } from "./app-manifest.mjs";
-
-const MANAGED_PLATFORM_FILES = [
-  "next.config.ts",
-  path.join("app", "globals.css"),
-  path.join("config", "module-toolbar-controls.tsx"),
-  path.join("config", "modules.ts"),
-  path.join("config", "shell.ts"),
-  path.join("app", "api", "invitations", "_dependencies.ts"),
-  path.join("app", "api", "organizations", "route.ts"),
-  path.join("app", "api", "organizations", "[id]", "route.ts"),
-  path.join("app", "api", "organizations", "[id]", "invitations", "route.ts"),
-  path.join("app", "api", "organizations", "[id]", "invitations", "[invitationId]", "route.ts"),
-  path.join("docs", "ai", "app-context.json"),
-];
-
-const MANAGED_SITE_FILES = [
-  path.join("docs", "ai", "app-context.json"),
-];
-
-const MODULE_SELECTED_PLATFORM_FILES = new Set([
-  path.join("app", "api", "invitations", "_dependencies.ts"),
-  path.join("app", "api", "organizations", "route.ts"),
-  path.join("app", "api", "organizations", "[id]", "route.ts"),
-  path.join("app", "api", "organizations", "[id]", "invitations", "route.ts"),
-  path.join("app", "api", "organizations", "[id]", "invitations", "[invitationId]", "route.ts"),
-]);
+import { assertNoUntrackedScaffoldWrites, scaffoldDrift } from "./scaffold.mjs";
+import { hashFile, writeAppManifest, readAppManifest } from "./app-manifest.mjs";
+
+const MODULE_SELECTED_PLATFORM_FILES = new Set(MODULE_SELECTED_FILES);
 
 const REFRESHABLE_PLATFORM_STARTER_FILES = new Set([
   path.join("app", "api", "notifications", "route.ts"),
@@ -459,8 +433,9 @@ function renderPlanSummary(plan, options = {}) {
 }
 
 export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptions = {}) {
-  const targetDir = resolveUpdateTargetDirectory(runtimeOptions, argvOptions);
-  await readAppManifest(targetDir, { required: false });
+  const targetDir = await fs.realpath(resolveUpdateTargetDirectory(runtimeOptions, argvOptions));
+  const appManifest = await readAppManifest(targetDir, { required: false });
+  await assertMutationTargets(targetDir, ["package.json", ...Object.keys(appManifest?.scaffoldFiles || {})]);
   const packageJsonPath = path.join(targetDir, "package.json");
   const manifest = await readJsonIfPresent(packageJsonPath);
 
@@ -527,20 +502,7 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   }
 
   if (template === "platform") {
-    const canonicalConfigFiles = {
-      "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModules }),
-      [path.join("app", "globals.css")]: await createPlatformGlobalsCss(installedModules),
-      [path.join("config", "module-toolbar-controls.tsx")]: createModuleToolbarControlsConfig(installedModules),
-      [path.join("config", "modules.ts")]: createPlatformModulesConfigFile(installedModules),
-      [path.join("config", "shell.ts")]: createShellConfig(installedModules),
-      ...createOptionalModuleRouteFiles(installedModules),
-      [path.join("docs", "ai", "app-context.json")]: createAppContextFile({
-        slug: manifest.name || path.basename(targetDir),
-        template: "platform",
-        selectedModules: installedModules,
-        dbInstallPlan,
-      }),
-    };
+    const canonicalConfigFiles = await createManagedPlatformFiles({ slug: manifest.name || path.basename(targetDir), selectedModules: installedModules, dbInstallPlan });
 
     for (const relativePath of MANAGED_PLATFORM_FILES) {
       const targetPath = path.join(targetDir, relativePath);
@@ -588,7 +550,8 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
 
   if (argvOptions.refreshStarters) {
     for (const entry of starterFiles.filter((candidate) =>
-      candidate.status !== "current" && (candidate.status === "missing" || candidate.refreshable !== false))) {
+      !MANAGED_PLATFORM_FILES.includes(candidate.relativePath)
+      && candidate.status !== "current" && (candidate.status === "missing" || candidate.refreshable !== false))) {
       fileWrites.push({
         moduleKey: entry.moduleKey,
         relativePath: entry.relativePath,
@@ -599,6 +562,22 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
     }
   }
 
+  // Legacy update may explicitly refresh drift, but never overrides ownership intent.
+  const liveScaffold = await scaffoldDrift(targetDir, appManifest?.scaffoldFiles);
+  const intentionalPaths = new Set(liveScaffold.intentional);
+  for (let index = fileWrites.length - 1; index >= 0; index -= 1) {
+    if (intentionalPaths.has(fileWrites[index].relativePath) || isAppOwnedSeed(fileWrites[index].relativePath)) fileWrites.splice(index, 1);
+  }
+
+  if (appManifest) await assertNoUntrackedScaffoldWrites({
+    targetDir,
+    scaffoldFiles: appManifest.scaffoldFiles,
+    moduleKeys: installedModules,
+    relativePaths: fileWrites.map((entry) => entry.relativePath),
+  });
+
+  await assertMutationTargets(targetDir, [".brightweb/app-manifest.json", ...fileWrites.map((write) => write.relativePath)]);
+
   const modulesConfigMismatch = template === "platform"
     ? await detectModulesConfigMismatch(targetDir, installedModules)
     : null;
@@ -613,6 +592,7 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
     installedModules,
     installedBrightwebPackages: Array.from(installedBrightwebPackagesMap.keys()).sort(),
     targetVersions: canonicalVersions,
+    appManifest,
     packageUpdates: packageJsonUpdate.packageUpdates,
     configFilesToWrite: fileWrites.filter((entry) => entry.type === "config").map((entry) => entry.relativePath),
     starterFilesMissing: starterFilesMissing.map((entry) => entry.relativePath),
@@ -648,6 +628,18 @@ export async function updateBrightwebApp(argvOptions = {}, runtimeOptions = {})
     await fs.writeFile(fileWrite.targetPath, fileWrite.content, "utf8");
   }
 
+  if (plan.appManifest) {
+    let scaffoldChanged = false;
+    for (const write of plan.fileWrites) {
+      const record = plan.appManifest.scaffoldFiles[write.relativePath];
+      if (!record) continue;
+      record.hash = await hashFile(write.targetPath);
+      record.status = "current";
+      scaffoldChanged = true;
+    }
+    if (scaffoldChanged) await writeAppManifest(plan.targetDir, plan.appManifest);
+  }
+
   const packageJsonChanged = plan.fileWrites.some((entry) => entry.relativePath === "package.json");
   if (argvOptions.install && packageJsonChanged) {
     const installRunner = runtimeOptions.installRunner || runInstall;

package/src/upgrade.mjs

@@ -1,3 +1,4 @@
+import { assertMutationTargets } from "./mutation-paths.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { stdout as output } from "node:process";
@@ -6,6 +7,7 @@ import { pathExists, runInstall } from "./generator.mjs";
 import { applyMigrationWrites, getModuleMigrations, planMigrationAppends } from "./migrations.mjs";
 import { buildBrightwebAppUpdatePlan } from "./update.mjs";
 import { resolveSafeRelativePath } from "./safe-path.mjs";
+import { scaffoldDrift } from "./scaffold.mjs";
 import { RETIRED_MODULE_STARTER_FILES } from "./constants.mjs";
 
 const HELP = `Usage: bw upgrade [moduleKey] [options]\n\nOptions:\n  --target-dir <path>                 App directory (defaults to cwd)\n  --workspace-root <path>             BrightWeb workspace root\n  --through-migration <file>          Advance the named module only through this migration\n  --include-destructive-migrations    Explicitly include held destructive migrations\n  --allow-stale-fallback              Use baked-in versions if npm lookup fails\n  --install                           Install changed dependencies\n  --refresh-starters                  Refresh unchanged starter files\n  --dry-run                           Print the upgrade plan without writing\n  --help                              Show this help`;
@@ -25,36 +27,30 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   if (includeDestructiveMigrations && !moduleKey) {
     throw new Error("--include-destructive-migrations requires an explicit module key so destructive scope cannot expand implicitly.");
   }
-  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 (moduleKey && !appManifest.modules[moduleKey]) throw new Error(`Module ${moduleKey} is not installed according to ${path.join(".brightweb", "app-manifest.json")}.`);
   const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
   const updateOptions = { ...argvOptions, targetDir, ...(workspaceRoot ? { workspaceRoot } : {}) };
   const plan = await buildBrightwebAppUpdatePlan(updateOptions, runtimeOptions);
-  const drifted = [];
-  const missing = [];
-  const intentional = [];
-  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles)) {
-    if (["owned", "skipped"].includes(record.intent)) intentional.push(relativePath);
-    const filePath = resolveSafeRelativePath(targetDir, relativePath, "Manifest scaffold file path");
-    if (!(await pathExists(filePath))) { missing.push(relativePath); continue; }
-    if (await hashFile(filePath) !== record.hash) drifted.push(relativePath);
-  }
-  const protectedPaths = new Set([...drifted, ...intentional]);
+  const live = await scaffoldDrift(targetDir, appManifest.scaffoldFiles);
+  const { drifted, missing, intentional, protectedPaths } = live;
   const obsoleteScaffoldFiles = [];
   if (argvOptions.refreshStarters) {
+    const currentPaths = new Set(live.current);
     for (const moduleKey of Object.keys(appManifest.modules)) {
       for (const relativePath of RETIRED_MODULE_STARTER_FILES[moduleKey] ?? []) {
         const record = appManifest.scaffoldFiles[relativePath];
         if (!record || protectedPaths.has(relativePath)) continue;
         const targetPath = resolveSafeRelativePath(targetDir, relativePath, "Obsolete scaffold file path");
-        if (!(await pathExists(targetPath)) || await hashFile(targetPath) !== record.hash) continue;
+        if (!currentPaths.has(relativePath)) continue;
         obsoleteScaffoldFiles.push({ relativePath, targetPath });
       }
     }
   }
   plan.fileDeletes = obsoleteScaffoldFiles;
-  plan.fileWrites = plan.fileWrites.filter((entry) => entry.type !== "starter" || !protectedPaths.has(entry.relativePath));
+  plan.fileWrites = plan.fileWrites.filter((entry) => !protectedPaths.has(entry.relativePath));
+  plan.configFilesToWrite = plan.fileWrites.filter((entry) => entry.type === "config").map((entry) => entry.relativePath);
   plan.starterFilesToRefresh = plan.fileWrites.filter((entry) => entry.type === "starter").map((entry) => entry.relativePath);
   plan.starterFilesDrifted = Array.from(new Set([...plan.starterFilesDrifted, ...drifted]));
   plan.starterFilesMissing = Array.from(new Set([...plan.starterFilesMissing, ...missing]));
@@ -81,7 +77,8 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   const safetyBoundaries = [];
   for (const key of moduleKeys) {
     const migrations = await getModuleMigrations(key, catalog[key]);
-    const destructiveIndex = migrations.findIndex((entry) => entry.destructive);
+    const cursorIndex = migrations.findIndex((entry) => entry.fileName === appManifest.migrationCursor?.[key]);
+    const destructiveIndex = migrations.findIndex((entry, index) => index > cursorIndex && entry.destructive);
     if (throughMigration && key === moduleKey) {
       const cutoffIndex = migrations.findIndex((entry) => entry.fileName === throughMigration);
       if (cutoffIndex >= destructiveIndex && destructiveIndex >= 0 && !includeDestructiveMigrations) {
@@ -91,8 +88,6 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
       continue;
     }
     if (includeDestructiveMigrations || destructiveIndex < 0) continue;
-    const cursorIndex = migrations.findIndex((entry) => entry.fileName === appManifest.migrationCursor?.[key]);
-    if (cursorIndex >= destructiveIndex) continue;
     if (destructiveIndex === 0) {
       throw new Error(`Migration upgrade blocked: ${key} begins with destructive migration ${migrations[0].fileName}; use --include-destructive-migrations after review.`);
     }
@@ -107,6 +102,7 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
     migrationCursor: appManifest.migrationCursor,
     migrationUpperBounds,
   });
+  await assertMutationTargets(targetDir, [".brightweb/app-manifest.json", ...plan.fileWrites.map((write) => write.relativePath), ...plan.fileDeletes.map((entry) => entry.relativePath), ...migrationPlan.writes.map((write) => path.relative(targetDir, write.targetPath))]);
   output.write(`bw upgrade\nPackages to update: ${plan.packageUpdates.length}\nManaged files to write: ${plan.fileWrites.length}\nObsolete managed files to remove: ${plan.fileDeletes.length}\nMigrations to append: ${migrationPlan.appends.length}\n`);
   if (throughMigration) output.write(`Migration cutoff: ${moduleKey} through ${throughMigration}\n`);
   for (const boundary of safetyBoundaries) {
@@ -157,7 +153,7 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
     const existingRecord = appManifest.scaffoldFiles[relativePath];
     if (!existingRecord && write.type !== "starter") continue;
     const targetPath = resolveSafeRelativePath(targetDir, relativePath, "Manifest scaffold file path");
-    if (write.type === "starter" && protectedPaths.has(relativePath)) continue;
+    if (protectedPaths.has(relativePath)) continue;
     if (!(await pathExists(targetPath))) continue;
     const hash = await hashFile(targetPath);
     if (existingRecord) {