create-bw-app 0.27.3 → 0.27.5

package/package.json

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

package/src/add.mjs

@@ -6,7 +6,7 @@ import { SELECTABLE_MODULES } from "./constants.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";
+import { assertMigrationMutationTargets, 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`;
 
@@ -109,7 +109,8 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
     }
   }
 
-  await assertMutationTargets(targetDir, ["package.json", ".brightweb/app-manifest.json", ...Object.keys(managedWrites), ...overlayFiles, ...migrationPlan.writes.map((write) => path.relative(targetDir, write.targetPath))]);
+  await assertMutationTargets(targetDir, ["package.json", ".brightweb/app-manifest.json", ...Object.keys(managedWrites), ...overlayFiles]);
+  await assertMigrationMutationTargets(targetDir, migrationPlan.writes);
 
   const summary = [
     "bw add",

package/src/constants.mjs

@@ -140,6 +140,10 @@ export const MODULE_STARTER_FILES = {
     "app/api/projects/[id]/milestones/[itemId]/route.ts",
     "app/api/projects/[id]/tasks/route.ts",
     "app/api/projects/[id]/tasks/[itemId]/route.ts",
+    "app/api/projects/[id]/client-tasks/route.ts",
+    "app/api/projects/[id]/client-tasks/[itemId]/route.ts",
+    "app/api/account/projects/[id]/tasks/route.ts",
+    "app/api/account/projects/[id]/tasks/[itemId]/route.ts",
   ],
 };
 
@@ -187,14 +191,14 @@ export const PLATFORM_STARTER_FILES = [
 ];
 
 export const APP_DEPENDENCY_DEFAULTS = {
-  "@brightweblabs/app-shell": "^0.16.3",
+  "@brightweblabs/app-shell": "^0.16.4",
   "@brightweblabs/core-auth": "^0.12.2",
   "@brightweblabs/infra": "^0.7.0",
-  "@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/module-admin": "^0.9.9",
+  "@brightweblabs/module-crm": "^0.18.6",
+  "@brightweblabs/module-marketing": "^0.5.3",
+  "@brightweblabs/module-orgs": "^0.7.5",
+  "@brightweblabs/module-projects": "^0.20.0",
   "@brightweblabs/theme": "^0.8.4",
   "@brightweblabs/ui": "^1.5.6",
   "geist": "1.7.2",

package/src/generator.mjs

@@ -1,3 +1,4 @@
+import { orderFreshMigrationSources } from "./migration-order.mjs";
 import { fileOwnership, assertGeneratedFileInventory, MANAGED_PLATFORM_FILES, MODULE_SELECTED_FILES } from "./file-policy.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -1388,7 +1389,7 @@ async function writeSupabaseCliMigrations({ targetDir, dbInstallPlan }) {
   await ensureDirectory(targetMigrationsDir);
   await fs.writeFile(path.join(targetSupabaseDir, "config.toml"), createGeneratedSupabaseConfig(path.basename(targetDir)), "utf8");
 
-  let sequence = 1;
+  const sources = [];
   for (const moduleKey of dbInstallPlan.resolvedOrder) {
     const sourceModuleDir = path.join(TEMPLATE_SUPABASE_ROOT, "modules", moduleKey, "migrations");
     if (!(await pathExists(sourceModuleDir))) {
@@ -1400,14 +1401,13 @@ async function writeSupabaseCliMigrations({ targetDir, dbInstallPlan }) {
       .sort();
 
     for (const fileName of fileNames) {
-      const targetFileName = `${String(sequence).padStart(4, "0")}_${moduleKey}__${fileName}`;
-      await fs.copyFile(
-        path.join(sourceModuleDir, fileName),
-        path.join(targetMigrationsDir, targetFileName),
-      );
-      sequence += 1;
+      sources.push({ moduleKey, fileName, sourcePath: path.join(sourceModuleDir, fileName) });
     }
   }
+  for (const [index, source] of orderFreshMigrationSources(sources).entries()) {
+    const targetFileName = `${String(index + 1).padStart(4, "0")}_${source.moduleKey}__${source.fileName}`;
+    await fs.copyFile(source.sourcePath, path.join(targetMigrationsDir, targetFileName));
+  }
 }
 
 async function writeBundledSupabaseBaseline({
@@ -1449,9 +1449,13 @@ async function writeBundledSupabaseBaseline({
   await writeSupabaseCliMigrations({ targetDir, dbInstallPlan });
 }
 
-export async function runInstall(command, cwd) {
+export async function runInstall(command, cwd, { updateLockfile = false } = {}) {
+  // Explicit upgrades change dependency inputs and must reconcile their lockfile,
+  // including in CI. Ordinary/scaffold installs retain the caller's policy.
+  const args = ["install"];
+  if (command === "pnpm" && updateLockfile) args.push("--no-frozen-lockfile");
   return new Promise((resolve, reject) => {
-    const child = spawn(command, ["install"], {
+    const child = spawn(command, args, {
       cwd,
       stdio: "inherit",
       shell: process.platform === "win32",

package/src/migration-order.mjs

@@ -0,0 +1,8 @@
+// Inputs are grouped in dependency order. Stable sorting keeps that order for
+// equal timestamps, while later cross-module changes run after earlier baselines.
+// Only fresh assemblies use this; existing numbered history is immutable.
+export function orderFreshMigrationSources(sources) {
+  return [...sources].sort((left, right) =>
+    left.fileName.split("_")[0].localeCompare(right.fileName.split("_")[0]),
+  );
+}

package/src/migrations.mjs

@@ -1,4 +1,6 @@
 import semver from "semver";
+import { load as loadYaml } from "js-yaml";
+import { assertMutationTargets } from "./mutation-paths.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
@@ -16,6 +18,39 @@ export async function findAppMigrationsDirectory(targetDir) {
   }
 }
 
+// Database migrations may belong to the containing consumer workspace, while
+// app files remain bounded to the app itself. Never realpath the migration
+// directory: that would hide links below the legitimate workspace boundary.
+export async function assertMigrationMutationTargets(targetDir, writes) {
+  if (writes.length === 0) return;
+  const appRoot = await fs.realpath(path.resolve(targetDir));
+  let boundary = appRoot;
+  let current = appRoot;
+  while (true) {
+    const workspacePath = path.join(current, "pnpm-workspace.yaml");
+    const workspaceConfig = await pathExists(workspacePath)
+      ? loadYaml(await fs.readFile(workspacePath, "utf8")) : null;
+    const manifestPath = path.join(current, "package.json");
+    const manifest = await pathExists(manifestPath)
+      ? JSON.parse(await fs.readFile(manifestPath, "utf8")) : null;
+    if ((workspaceConfig != null && Object.hasOwn(workspaceConfig, "packages"))
+      || manifest?.workspaces || await pathExists(path.join(current, ".git"))) {
+      boundary = current;
+      break;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  const migrationsDir = await findAppMigrationsDirectory(appRoot);
+  for (const write of writes) {
+    if (path.dirname(write.targetPath) !== migrationsDir) {
+      throw new Error("Migration write must target the app's discovered migrations directory.");
+    }
+  }
+  await assertMutationTargets(boundary, writes.map((write) => path.relative(boundary, write.targetPath)));
+}
+
 export async function getModuleMigrations(moduleKey, catalogEntry = {}) {
   const candidates = [];
   const configuredPath = catalogEntry.manifest?.database?.migrations;
@@ -62,8 +97,11 @@ export async function planMigrationAppends({
     return Math.max(maximum, Number(match?.[1] || 0));
   }, 0);
   const appends = [];
+  const recovered = [];
   const deferred = [];
   const nextCursor = { ...migrationCursor };
+  let pendingGap = false;
+  let lastRecoveredFileName = null;
   for (const moduleKey of moduleKeys) {
     const migrations = await getModuleMigrations(moduleKey, catalog[moduleKey]);
     const cursor = migrationCursor[moduleKey];
@@ -90,10 +128,39 @@ export async function planMigrationAppends({
       ? migrationsInScope.filter((entry) => entry.fileName > cursor)
       : migrationsInScope;
     for (const entry of pending) {
-      sequence += 1;
-      const targetFileName = `${String(sequence).padStart(4, "0")}_${moduleKey}__${entry.fileName}`;
       const source = await fs.readFile(entry.sourcePath, "utf8");
       const version = catalog[moduleKey]?.version || "unknown";
+      const headerPattern = /^[ \t]*--[ \t]*bw-module:\s*([^@\s]+)@([^\s]+)\s+([^\s]+)[ \t]*\r?\n/;
+      const matches = existing.filter(file => {
+        const header = file.content.match(headerPattern);
+        return file.fileName === entry.fileName
+          || file.fileName.endsWith(`_${moduleKey}__${entry.fileName}`)
+          || (header?.[1] === moduleKey && header?.[3] === entry.fileName);
+      });
+      if (matches.length) {
+        if (matches.length !== 1) throw new Error(`Cannot recover migration ${moduleKey}/${entry.fileName}: multiple files claim the same source.`);
+        const previous = matches[0];
+        if (pendingGap || (lastRecoveredFileName && previous.fileName <= lastRecoveredFileName)) {
+          throw new Error(`Cannot recover migration ${moduleKey}/${entry.fileName}: existing SQL is not a contiguous ordered prefix. Reconcile interrupted history before upgrading.`);
+        }
+        lastRecoveredFileName = previous.fileName;
+        const header = previous.content.match(headerPattern);
+        const comparison = header && catalog[moduleKey]?.version ? compareSemver(header[2], version) : 0;
+        const sameIdentity = !header || (header[1] === moduleKey && header[3] === entry.fileName);
+        const previousSource = header ? previous.content.slice(header[0].length) : previous.content;
+        if (!sameIdentity || comparison == null || comparison > 0 || sha256(previousSource) !== sha256(source)) {
+          throw new Error(`Cannot recover migration ${moduleKey}/${entry.fileName}: existing source bytes or provenance conflict. Existing SQL was left untouched.`);
+        }
+        const owner = path.dirname(path.dirname(migrationsDir));
+        await assertMutationTargets(owner, [path.relative(owner, previous.targetPath)]);
+        // The previous attempt may have persisted SQL before its cursor write.
+        // Recover only an exact source match; never rewrite or duplicate history.
+        recovered.push({ moduleKey, originalFileName: entry.fileName, targetPath: previous.targetPath });
+        continue;
+      }
+      pendingGap = true;
+      sequence += 1;
+      const targetFileName = `${String(sequence).padStart(4, "0")}_${moduleKey}__${entry.fileName}`;
       appends.push({
         moduleKey,
         originalFileName: entry.fileName,
@@ -104,13 +171,13 @@ export async function planMigrationAppends({
     }
     if (migrationsInScope.length > 0) nextCursor[moduleKey] = migrationsInScope.at(-1).fileName;
   }
-  return { writes: appends, repairs: [], appends, deferred, nextCursor };
+  return { writes: appends, repairs: [], appends, recovered, deferred, nextCursor };
 }
 
 export async function applyMigrationWrites(writes) {
   for (const write of writes) {
     await fs.mkdir(path.dirname(write.targetPath), { recursive: true });
-    await fs.writeFile(write.targetPath, write.content, "utf8");
+    await fs.writeFile(write.targetPath, write.content, { encoding: "utf8", flag: "wx" });
   }
 }
 
@@ -186,7 +253,7 @@ export async function exactMigrationCompatibilityStatus({ targetDir, moduleKey,
   const legacyEquivalent = [];
   for (const entry of migrationsInScope) {
     const matches = installed.filter(({ fileName, content }) => {
-      const header = content.match(/^\s*--\s*bw-module:\s*([^@\s]+)@([^\s]+)\s+([^\s]+)\s*\n/im);
+      const header = content.match(/^\s*--\s*bw-module:\s*([^@\s]+)@([^\s]+)\s+([^\s]+)[ \t]*\r?\n/im);
       return (header?.[1] === moduleKey && header?.[3] === entry.fileName)
         || fileName === entry.fileName
         || fileName.endsWith(`_${moduleKey}__${entry.fileName}`);
@@ -200,7 +267,7 @@ export async function exactMigrationCompatibilityStatus({ targetDir, moduleKey,
       continue;
     }
     const [{ fileName, content }] = matches;
-    const header = content.match(/^\s*--\s*bw-module:\s*([^@\s]+)@([^\s]+)\s+([^\s]+)\s*\n/im);
+    const header = content.match(/^\s*--\s*bw-module:\s*([^@\s]+)@([^\s]+)\s+([^\s]+)[ \t]*\r?\n/im);
     const expectedVersion = catalogEntry?.version;
     if (expectedVersion && header) {
       const comparison = compareSemver(header[2], expectedVersion);

package/src/update.mjs

@@ -1,6 +1,10 @@
 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 semver from "semver";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { load as loadYaml } from "js-yaml";
 import path from "node:path";
 import { stdout as output } from "node:process";
 import {
@@ -87,6 +91,7 @@ async function resolvePublishedBrightwebVersions(installedBrightwebPackages, opt
     throw new Error("Published updates require fetch support to resolve BrightWeb package versions from npm.");
   }
 
+  const registryUrl = (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/$/, "");
   const fallbackVersionMap = options.fallbackVersionMap || {};
   const allowStaleFallback = options.allowStaleFallback === true;
   const resolvedVersions = {};
@@ -95,7 +100,7 @@ async function resolvePublishedBrightwebVersions(installedBrightwebPackages, opt
   await Promise.all(
     packageNames.map(async (packageName) => {
       try {
-        const response = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`);
+        const response = await fetchImpl(`${registryUrl}/${encodeURIComponent(packageName)}/latest`);
         if (!response?.ok) {
           throw new Error(`npm registry responded with ${response?.status ?? "an unknown error"}`);
         }
@@ -432,6 +437,50 @@ function renderPlanSummary(plan, options = {}) {
   return `${lines.join("\n")}\n`;
 }
 
+// A version-pinned app patch is part of the app's customization contract.
+// Check target versions even when an earlier failed upgrade already wrote them.
+async function assertTargetPatchCompatibility(targetDir, targetVersions) {
+  let directory = targetDir;
+  let lockOwner = null;
+  while (!(await pathExists(path.join(directory, "pnpm-workspace.yaml")))) {
+    if (!lockOwner && await pathExists(path.join(directory, "pnpm-lock.yaml"))) lockOwner = directory;
+    const parent = path.dirname(directory);
+    if (parent === directory) { directory = lockOwner ?? targetDir; break; }
+    directory = parent;
+  }
+  // pnpm selects the nearest settings file even without a packages list. A
+  // child lockfile does not hide an enclosing pnpm workspace's configuration.
+  const manifest = await readJsonIfPresent(path.join(directory, "package.json"));
+  const workspacePath = path.join(directory, "pnpm-workspace.yaml");
+  const workspace = await pathExists(workspacePath)
+    ? loadYaml(await fs.readFile(workspacePath, "utf8")) : null;
+  const source = workspace && Object.hasOwn(workspace, "patchedDependencies") ? "pnpm-workspace.yaml" : "package.json";
+  const patches = source === "pnpm-workspace.yaml" ? workspace.patchedDependencies : manifest?.pnpm?.patchedDependencies;
+  if (patches == null) return;
+  if (typeof patches !== "object" || Array.isArray(patches)) {
+    throw new Error(`Upgrade blocked: invalid patchedDependencies in ${path.join(directory, source)}. Review the app's patch configuration before retrying.`);
+  }
+  for (const selector of Object.keys(patches)) {
+    const separator = selector.indexOf("@", 1);
+    const packageName = separator < 0 ? selector : selector.slice(0, separator);
+    if (!Object.hasOwn(targetVersions, packageName)) continue;
+    const target = targetVersions[packageName];
+    const range = separator < 0 ? "*" : selector.slice(separator + 1);
+    const version = semver.validRange(target) && semver.minVersion(target)?.version;
+    if (version && semver.validRange(range) && semver.satisfies(version, range)) {
+      // Keep the resolver inside the patch's declared support. Exact/finite
+      // selectors must not drift to another release allowed by a caret.
+      if (!semver.subset(target, range)) targetVersions[packageName] = version;
+      continue;
+    }
+    throw new Error(
+      `Upgrade blocked before writes: app-owned patch ${selector} in ${path.join(directory, source)} does not cover target ${packageName}@${target}.\n`
+      + "Keep the patch and customization intact. Review/recreate it against the target package with pnpm patch and pnpm patch-commit, then verify the customized behavior before retrying.\n"
+      + "If a previous attempt already wrote package or SQL files, this refusal preserves that state. After a reviewed compatible patch is ready, rerun the same command with --install; existing migration files/cursors are verified rather than appended twice.",
+    );
+  }
+}
+
 export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptions = {}) {
   const targetDir = await fs.realpath(resolveUpdateTargetDirectory(runtimeOptions, argvOptions));
   const appManifest = await readAppManifest(targetDir, { required: false });
@@ -485,6 +534,7 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
       ...brightwebVersionOverrides,
     },
   });
+  if (dependencyMode === "published") await assertTargetPatchCompatibility(targetDir, canonicalVersions);
   const packageJsonUpdate = mergeManagedPackageUpdates({
     manifest,
     targetVersions: canonicalVersions,
@@ -604,6 +654,105 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   };
 }
 
+// A successful install is reusable only while its inputs and installed shared
+// package versions still match. Failed/incomplete installs never create proof.
+export async function reconcileDependencyInstallation(plan, runtimeOptions = {}, appManifest = plan.appManifest) {
+  const installCwd = plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : plan.targetDir;
+  async function configurationHash(owner) {
+    const directories = new Set([installCwd, owner]);
+    const relativeTarget = path.relative(owner, plan.targetDir);
+    if (relativeTarget !== ".." && !relativeTarget.startsWith(`..${path.sep}`) && !path.isAbsolute(relativeTarget)) {
+      for (let directory = plan.targetDir; ; directory = path.dirname(directory)) {
+        directories.add(directory);
+        if (directory === owner) break;
+      }
+    } else directories.add(plan.targetDir);
+    const hashes = [];
+    for (const directory of directories) {
+      const patches = {};
+      for (const name of ["package.json", "pnpm-workspace.yaml", ".npmrc"]) {
+        const file = path.join(directory, name);
+        hashes.push(await pathExists(file) ? await hashFile(file) : null);
+        if (name === ".npmrc" || !(await pathExists(file))) continue;
+        const source = await fs.readFile(file, "utf8");
+        const config = name === "package.json" ? JSON.parse(source).pnpm : loadYaml(source);
+        Object.assign(patches, config?.patchedDependencies ?? {});
+      }
+      for (const patch of Object.values(patches)) {
+        const relativePath = typeof patch === "string" ? patch : patch?.path;
+        if (typeof relativePath !== "string") return null;
+        const file = path.resolve(directory, relativePath);
+        hashes.push(await pathExists(file) ? await hashFile(file) : null);
+      }
+    }
+    const environment = Object.entries(process.env)
+      .filter(([name]) => /^(npm_config_|pnpm_|NODE_ENV$|CI$)/i.test(name)).sort(([a], [b]) => a.localeCompare(b));
+    const userConfigs = new Set([path.join(homedir(), ".npmrc")]);
+    for (const [name, value] of environment) {
+      if (/(?:userconfig|globalconfig)$/i.test(name) && value) userConfigs.add(path.resolve(installCwd, value));
+    }
+    for (const file of userConfigs) hashes.push(await pathExists(file) ? await hashFile(file) : null);
+    // Configuration can contain credentials; retain only this aggregate digest.
+    return createHash("sha256").update(JSON.stringify({ hashes, environment })).digest("hex");
+  }
+  async function inputs() {
+    let directory = installCwd;
+    while (true) {
+      for (const name of ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock", "bun.lockb"]) {
+        const lock = path.join(directory, name);
+        if (await pathExists(lock)) return {
+          packageManager: plan.packageManager,
+          appPackageHash: await hashFile(path.join(plan.targetDir, "package.json")),
+          installPackageHash: await pathExists(path.join(directory, "package.json")) ? await hashFile(path.join(directory, "package.json")) : null,
+          lockFile: name, lockHash: await hashFile(lock), configurationHash: await configurationHash(directory),
+        };
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) return { packageManager: plan.packageManager, appPackageHash: await hashFile(path.join(plan.targetDir, "package.json")), installPackageHash: null, lockFile: null, lockHash: null };
+      directory = parent;
+    }
+  }
+  async function installedPackagesMatch() {
+    const pkg = JSON.parse(await fs.readFile(path.join(plan.targetDir, "package.json"), "utf8"));
+    const requirements = Object.entries({ ...pkg.dependencies, ...pkg.devDependencies })
+      .filter(([name]) => BRIGHTWEB_PACKAGE_NAMES.includes(name));
+    if (!requirements.length) return false;
+    for (const [name, range] of requirements) {
+      let directory = plan.targetDir, installed = null;
+      while (true) {
+        const candidate = path.join(directory, "node_modules", ...name.split("/"), "package.json");
+        if (await pathExists(candidate)) {
+          try { installed = JSON.parse(await fs.readFile(candidate, "utf8")); }
+          catch (error) { if (error instanceof SyntaxError || error.code === "ENOENT") return false; throw error; }
+          break;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) break;
+        directory = parent;
+      }
+      if (!installed || !semver.valid(installed.version) || (!String(range).startsWith("workspace:") && !semver.satisfies(installed.version, String(range)))) return false;
+    }
+    return true;
+  }
+  const before = await inputs();
+  if (before.lockHash && before.configurationHash && appManifest?.lastSuccessfulInstall
+    && JSON.stringify(appManifest.lastSuccessfulInstall) === JSON.stringify(before)
+    && await installedPackagesMatch()) {
+    output.write("Installed dependencies already match the verified installation; no installation required.\n");
+    return { installed: false };
+  }
+  if (appManifest?.lastSuccessfulInstall) {
+    delete appManifest.lastSuccessfulInstall;
+    await writeAppManifest(plan.targetDir, appManifest);
+  }
+  await (runtimeOptions.installRunner || runInstall)(plan.packageManager, installCwd, { updateLockfile: true });
+  if (appManifest) {
+    appManifest.lastSuccessfulInstall = await inputs();
+    await writeAppManifest(plan.targetDir, appManifest);
+  }
+  return { installed: true };
+}
+
 export async function updateBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
   const plan = await buildBrightwebAppUpdatePlan(argvOptions, runtimeOptions);
   const installCommand = renderInstallCommand({
@@ -641,10 +790,8 @@ export async function updateBrightwebApp(argvOptions = {}, runtimeOptions = {})
   }
 
   const packageJsonChanged = plan.fileWrites.some((entry) => entry.relativePath === "package.json");
-  if (argvOptions.install && packageJsonChanged) {
-    const installRunner = runtimeOptions.installRunner || runInstall;
-    const installCwd = plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : plan.targetDir;
-    await installRunner(plan.packageManager, installCwd);
+  if (argvOptions.install) {
+    await reconcileDependencyInstallation(plan, runtimeOptions);
   }
 
   if (!argvOptions.install && packageJsonChanged) {

package/src/upgrade.mjs

@@ -1,16 +1,57 @@
 import { assertMutationTargets } from "./mutation-paths.mjs";
 import fs from "node:fs/promises";
+import { load as loadYaml } from "js-yaml";
 import path from "node:path";
 import { stdout as output } from "node:process";
-import { hashFile, findWorkspaceRoot, loadModuleCatalog, readAppManifest, writeAppManifest, cleanVersion } from "./app-manifest.mjs";
-import { pathExists, runInstall } from "./generator.mjs";
-import { applyMigrationWrites, getModuleMigrations, planMigrationAppends } from "./migrations.mjs";
-import { buildBrightwebAppUpdatePlan } from "./update.mjs";
+import { hashFile, findWorkspaceRoot, loadModuleCatalog, readAppManifest, writeAppManifest, cleanVersion, moduleVersion } from "./app-manifest.mjs";
+import { pathExists } from "./generator.mjs";
+import { assertMigrationMutationTargets, applyMigrationWrites, findAppMigrationsDirectory, getModuleMigrations, planMigrationAppends, exactMigrationCompatibilityStatus } from "./migrations.mjs";
+import { buildBrightwebAppUpdatePlan, reconcileDependencyInstallation } 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`;
+const IDENTITY_CORE_MIGRATION = "20261014183138_protect_profile_identity.sql";
+const IDENTITY_DEPENDENT_MIGRATIONS = {
+  admin: "20261014183138_auth_verified_admin_acceptance.sql",
+  orgs: "20261014183138_auth_verified_organization_membership.sql",
+};
+
+function orderSelectedModules(catalog, selected) {
+  const order = [], visited = new Set(), visiting = new Set();
+  const keys = new Set(selected);
+  function visit(key) {
+    if (visited.has(key)) return;
+    if (visiting.has(key)) throw new Error(`Circular migration dependency: ${key}`);
+    visiting.add(key);
+    for (const dependency of Object.keys(catalog[key]?.requires ?? {})) {
+      if (keys.has(dependency)) visit(dependency);
+    }
+    visiting.delete(key);
+    visited.add(key);
+    order.push(key);
+  }
+  for (const key of selected) visit(key);
+  return order;
+}
+
+async function assertIdentityMigrationPrerequisites({ targetDir, catalog, migrationPlan }) {
+  const dependent = [...migrationPlan.appends, ...migrationPlan.recovered]
+    .filter(entry => IDENTITY_DEPENDENT_MIGRATIONS[entry.moduleKey] === entry.originalFileName);
+  if (!dependent.length) return;
+  const instruction = `Identity migration prerequisite missing or invalid. Run bw upgrade core, apply ${IDENTITY_CORE_MIGRATION} successfully to the database, then retry the Admin/Orgs upgrade. Explicit cutoffs are preserved; generated files and cursors do not prove database application.`;
+  const coreIndex = migrationPlan.appends.findIndex(entry => entry.moduleKey === "core" && entry.originalFileName === IDENTITY_CORE_MIGRATION);
+  if (coreIndex >= 0) {
+    if (dependent.some(entry => migrationPlan.appends.indexOf(entry) <= coreIndex)) throw new Error(instruction);
+    return;
+  }
+  const status = await exactMigrationCompatibilityStatus({ targetDir, moduleKey: "core", cursor: IDENTITY_CORE_MIGRATION, catalogEntry: catalog.core, allowDeferred: true });
+  if (status.issues.length) throw new Error(`${instruction} Core SQL verification: ${status.issues.join("; ")}`);
+  const coreFile = status.verified.find(entry => entry.originalFileName === IDENTITY_CORE_MIGRATION)?.fileName;
+  if (!coreFile || dependent.some(entry => path.basename(entry.targetPath) <= coreFile)) throw new Error(instruction);
+}
+
+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 dependencies, including retrying a failed install\n  --refresh-starters                  Refresh unchanged starter files\n  --dry-run                           Print the upgrade plan without writing\n  --help                              Show this help`;
 
 export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOptions = {}) {
   if (argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
@@ -29,7 +70,7 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   }
   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")}.`);
+  if (moduleKey && !appManifest.modules[moduleKey] && !(moduleKey === "core" && appManifest.app?.template === "platform")) 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);
@@ -58,16 +99,26 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
   for (const entry of Object.values(catalog)) {
     const targetVersion = plan.targetVersions?.[entry.packageName];
-    if (targetVersion) entry.version = cleanVersion(targetVersion) || entry.version;
+    if (!targetVersion) continue;
+    const version = cleanVersion(targetVersion) || entry.version;
+    if (!workspaceRoot && version !== entry.version) {
+      if (version !== moduleVersion(entry.key)) {
+        throw new Error(`Migration sources for ${entry.key}@${version} are unavailable. Update create-bw-app to a release with the matching migration bundle before upgrading.`);
+      }
+      // Installed packages still belong to the previous release until --install
+      // runs. The CLI bundle carries the matching target release's SQL.
+      entry.packageRoot = null;
+    }
+    entry.version = version;
   }
   for (const update of plan.packageUpdates) {
     const key = Object.keys(catalog).find((candidate) => catalog[candidate].packageName === update.packageName);
     if (key) catalog[key].version = cleanVersion(update.to) || catalog[key].version;
   }
   const installedMigrationKeys = Object.keys(appManifest.migrationCursor ?? {}).filter((key) => catalog[key]);
-  const moduleKeys = moduleKey
+  const moduleKeys = orderSelectedModules(catalog, moduleKey
     ? [moduleKey]
-    : Array.from(new Set([...installedMigrationKeys, ...Object.keys(appManifest.modules)]));
+    : Array.from(new Set([...installedMigrationKeys, ...Object.keys(appManifest.modules)])));
   const uncursored = [];
   for (const key of moduleKeys) {
     if (appManifest.migrationCursor?.[key] == null && (await getModuleMigrations(key, catalog[key])).length > 0) uncursored.push(key);
@@ -95,6 +146,8 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
     migrationUpperBounds[key] = boundary;
     safetyBoundaries.push({ moduleKey: key, boundary, destructiveMigration: migrations[destructiveIndex].fileName });
   }
+  const migrationsDir = await findAppMigrationsDirectory(targetDir);
+  const migrationOwner = path.dirname(path.dirname(migrationsDir));
   const migrationPlan = await planMigrationAppends({
     targetDir,
     moduleKeys,
@@ -102,8 +155,34 @@ 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))]);
+  await assertMigrationMutationTargets(targetDir, migrationPlan.writes);
+  if (migrationOwner !== targetDir) {
+    let current = targetDir;
+    let declaredOwner = null;
+    while (current !== path.dirname(current)) {
+      const manifestPath = path.join(current, "package.json");
+      const workspacePath = path.join(current, "pnpm-workspace.yaml");
+      // Generated single apps also carry a pnpm settings file; only a package
+      // selection declares a shared workspace ownership boundary.
+      const workspaceConfig = await pathExists(workspacePath)
+        ? loadYaml(await fs.readFile(workspacePath, "utf8")) : null;
+      const workspaceMarker = workspaceConfig != null
+        && Object.hasOwn(workspaceConfig, "packages");
+      const manifest = await pathExists(manifestPath) ? JSON.parse(await fs.readFile(manifestPath, "utf8")) : null;
+      if (workspaceMarker || manifest?.workspaces) { declaredOwner = current; break; }
+      current = path.dirname(current);
+    }
+    if (declaredOwner !== migrationOwner) {
+      throw new Error("Migration upgrade blocked: ancestor SQL directory is outside the app's declared workspace. Keep SQL inside the app or declare the owning workspace before upgrading.");
+    }
+  }
+  await assertIdentityMigrationPrerequisites({ targetDir, catalog, migrationPlan });
+  await assertMutationTargets(targetDir, [".brightweb/app-manifest.json", ...plan.fileWrites.map((write) => write.relativePath), ...plan.fileDeletes.map((entry) => entry.relativePath)]);
+  // Monorepo clients keep SQL beside the app. Validate that owner boundary
+  // separately; app-managed paths must still remain inside the app itself.
+  await assertMutationTargets(migrationOwner, migrationPlan.writes.map(write => path.relative(migrationOwner, 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 (migrationPlan.recovered.length) output.write(`Previously written migrations verified for recovery: ${migrationPlan.recovered.length}\n`);
   if (throughMigration) output.write(`Migration cutoff: ${moduleKey} through ${throughMigration}\n`);
   for (const boundary of safetyBoundaries) {
     output.write(`Migration safety boundary: ${boundary.moduleKey} through ${boundary.boundary}; held ${boundary.destructiveMigration}\n`);
@@ -168,10 +247,9 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
     }
   }
   await writeAppManifest(targetDir, appManifest);
-  const packageChanged = plan.fileWrites.some((entry) => entry.relativePath === "package.json");
-  if (argvOptions.install && packageChanged) {
-    const runner = runtimeOptions.installRunner || runInstall;
-    await runner(plan.packageManager, plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : targetDir);
+  // Explicit installation also reconciles a previous failed install after files were updated.
+  if (argvOptions.install) {
+    await reconcileDependencyInstallation({ ...plan, targetDir }, runtimeOptions, appManifest);
   }
   output.write(`Applied ${plan.fileWrites.length} managed change${plan.fileWrites.length === 1 ? "" : "s"}, removed ${plan.fileDeletes.length} obsolete managed file${plan.fileDeletes.length === 1 ? "" : "s"}, and added ${migrationPlan.appends.length} new migration${migrationPlan.appends.length === 1 ? "" : "s"}.\n`);
   return { dryRun: false, plan, migrationPlan, drifted, missing };

package/template/modules/projects/app/api/account/projects/[id]/tasks/[itemId]/route.ts

@@ -0,0 +1,2 @@
+export const dynamic = "force-dynamic";
+export { clientProjectTaskPost as POST } from "@brightweblabs/module-projects/route-handlers";

package/template/modules/projects/app/api/account/projects/[id]/tasks/route.ts

@@ -0,0 +1,2 @@
+export const dynamic = "force-dynamic";
+export { clientProjectTasksGet as GET } from "@brightweblabs/module-projects/route-handlers";

package/template/modules/projects/app/api/projects/[id]/client-tasks/[itemId]/route.ts

@@ -0,0 +1,2 @@
+export const dynamic = "force-dynamic";
+export { projectClientTaskPatch as PATCH } from "@brightweblabs/module-projects/route-handlers";

package/template/modules/projects/app/api/projects/[id]/client-tasks/route.ts

@@ -0,0 +1,2 @@
+export const dynamic = "force-dynamic";
+export { projectClientTasksGet as GET, projectClientTasksPost as POST } from "@brightweblabs/module-projects/route-handlers";