create-bw-app 0.25.1 → 0.26.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.25.1",
+  "version": "0.26.0",
   "type": "module",
   "bin": {
     "create-bw-app": "bin/create-bw-app.mjs",

package/src/app-manifest.mjs

@@ -129,6 +129,14 @@ export function validateAppManifest(manifest) {
     try { normalizeSafeRelativePath(relativePath, `scaffoldFiles path`); } catch (error) { errors.push(error.message); }
     if (!entry || typeof entry.module !== "string" || !/^sha256:[a-f0-9]{64}$/.test(entry.hash || "") || !["current", "drifted", "missing"].includes(entry.status) || (entry.intent != null && !["managed", "owned", "skipped"].includes(entry.intent))) errors.push(`scaffoldFiles.${relativePath} is invalid`);
   }
+  if (manifest.migrationDeferrals != null) {
+    if (typeof manifest.migrationDeferrals !== "object" || Array.isArray(manifest.migrationDeferrals)) errors.push("migrationDeferrals must be an object");
+    else for (const [key, entry] of Object.entries(manifest.migrationDeferrals)) {
+      if (!entry || entry.reason !== "destructive" || typeof entry.cursor !== "string" || typeof entry.nextMigration !== "string") {
+        errors.push(`migrationDeferrals.${key} is invalid`);
+      }
+    }
+  }
   if (manifest.lastDoctor != null && (typeof manifest.lastDoctor.at !== "string" || typeof manifest.lastDoctor.ok !== "boolean")) errors.push("lastDoctor is invalid");
   if (
     manifest.infrastructure != null

package/src/constants.mjs

@@ -113,8 +113,6 @@ export const MODULE_STARTER_FILES = {
   projects: [
     "app/(shell)/projetos/layout.tsx",
     "app/(shell)/projetos/page.tsx",
-    "app/(shell)/projetos/projetos-live-mounts.tsx",
-    "app/(shell)/projetos/projetos-server-mounts.tsx",
     "app/(shell)/projetos/[projectId]/page.tsx",
     "app/(shell)/projetos/[projectId]/quadro/page.tsx",
     "app/(shell)/projetos/[projectId]/tarefas/page.tsx",
@@ -122,7 +120,6 @@ export const MODULE_STARTER_FILES = {
     "app/(shell)/account/projetos/loading.tsx",
     "app/(shell)/account/projetos/[projectId]/page.tsx",
     "app/(shell)/account/projetos/[projectId]/loading.tsx",
-    "app/api/projects/_handlers.ts",
     "app/api/account/projects/route.ts",
     "app/api/account/projects/[id]/route.ts",
     "app/api/dashboard/projects/route.ts",
@@ -145,6 +142,14 @@ export const MODULE_STARTER_FILES = {
   ],
 };
 
+export const RETIRED_MODULE_STARTER_FILES = {
+  projects: [
+    "app/(shell)/projetos/projetos-live-mounts.tsx",
+    "app/(shell)/projetos/projetos-server-mounts.tsx",
+    "app/api/projects/_handlers.ts",
+  ],
+};
+
 export const PLATFORM_STARTER_FILES = [
   "app/(auth)/auth-provider.tsx",
   "app/(auth)/layout.tsx",
@@ -182,13 +187,13 @@ export const PLATFORM_STARTER_FILES = [
 
 export const APP_DEPENDENCY_DEFAULTS = {
   "@brightweblabs/app-shell": "^0.16.0",
-  "@brightweblabs/core-auth": "^0.11.0",
+  "@brightweblabs/core-auth": "^0.12.0",
   "@brightweblabs/infra": "^0.7.0",
-  "@brightweblabs/module-admin": "^0.9.3",
-  "@brightweblabs/module-crm": "^0.17.3",
-  "@brightweblabs/module-marketing": "^0.4.23",
-  "@brightweblabs/module-orgs": "^0.6.2",
-  "@brightweblabs/module-projects": "^0.18.0",
+  "@brightweblabs/module-admin": "^0.9.4",
+  "@brightweblabs/module-crm": "^0.18.0",
+  "@brightweblabs/module-marketing": "^0.4.24",
+  "@brightweblabs/module-orgs": "^0.7.0",
+  "@brightweblabs/module-projects": "^0.19.0",
   "@brightweblabs/theme": "^0.8.3",
   "@brightweblabs/ui": "^1.5.4",
   "geist": "1.7.2",

package/src/doctor.mjs

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { stdout as output } from "node:process";
-import { cursorMigrationStatus } from "./migrations.mjs";
+import { APP_DEPENDENCY_DEFAULTS, BRIGHTWEB_PACKAGE_NAMES } from "./constants.mjs";
+import { cursorMigrationStatus, exactMigrationCompatibilityStatus } from "./migrations.mjs";
 import { findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, readConfiguredModuleFlags, satisfiesVersion, validateAppManifest, writeAppManifest } from "./app-manifest.mjs";
 import { loadAppEnvironment, readFirstEnvironmentValue } from "./env.mjs";
 import { pathExists, readJsonIfPresent } from "./generator.mjs";
@@ -10,6 +11,143 @@ import { scaffoldDrift } from "./scaffold.mjs";
 
 const HELP = `Usage: bw doctor [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --deployment-url <url>    Deployed app URL (defaults to PUBLIC_APP_URL/NEXT_PUBLIC_APP_URL)\n  --supabase-region <id>    Current Supabase project region override\n  --strict                  Treat warnings as failures\n  --report                  Stamp lastDoctor in the app manifest\n  --help                    Show this help`;
 const RUNTIME_PACKAGE_NAMES = ["react", "react-dom", "next"];
+const LOCAL_DEPENDENCY_PREFIXES = ["file:", "link:", "workspace:", "patch:"];
+
+async function findUp(startDir, fileName) {
+  let current = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(current, fileName);
+    if (await pathExists(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function exactVersionFromDefault(packageName) {
+  const requested = APP_DEPENDENCY_DEFAULTS[packageName];
+  return typeof requested === "string" ? requested.match(/^(?:\^|~)?(.+)$/)?.[1] ?? null : null;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function lockfileIntegrityForPackage(lockfile, packageName, version) {
+  const keyPattern = new RegExp(`^  ['\"]?${escapeRegExp(`${packageName}@${version}`)}['\"]?:$`);
+  const lines = lockfile.split("\n");
+  const start = lines.findIndex((line) => keyPattern.test(line));
+  if (start < 0) return null;
+  const block = [];
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^  \S/.test(lines[index])) break;
+    block.push(lines[index]);
+  }
+  return block.join("\n").match(/^    resolution:\s*\{[^}\n]*integrity:\s*([^,}\s]+)[^}\n]*\}/m)?.[1] ?? null;
+}
+
+export function lockfileImporterResolution(lockfile, importerKey, packageName) {
+  const lines = lockfile.split("\n");
+  const importersIndex = lines.findIndex((line) => /^importers:\s*$/.test(line));
+  if (importersIndex < 0) return null;
+  const normalizedKey = importerKey || ".";
+  const importerPattern = new RegExp(`^  ['\"]?${escapeRegExp(normalizedKey)}['\"]?:\\s*$`);
+  const importerStart = lines.findIndex((line, index) => index > importersIndex && importerPattern.test(line));
+  if (importerStart < 0) return null;
+  let importerEnd = lines.length;
+  for (let index = importerStart + 1; index < lines.length; index += 1) {
+    if (/^  \S/.test(lines[index])) { importerEnd = index; break; }
+  }
+  const dependencyPattern = new RegExp(`^      ['\"]?${escapeRegExp(packageName)}['\"]?:\\s*$`);
+  const dependencyStart = lines.findIndex(
+    (line, index) => index > importerStart && index < importerEnd && dependencyPattern.test(line),
+  );
+  if (dependencyStart < 0) return null;
+  const block = [];
+  for (let index = dependencyStart + 1; index < importerEnd; index += 1) {
+    if (/^      \S/.test(lines[index]) || /^    \S/.test(lines[index])) break;
+    block.push(lines[index]);
+  }
+  return {
+    specifier: block.join("\n").match(/^        specifier:\s*['\"]?([^'\"\s]+)['\"]?\s*$/m)?.[1] ?? null,
+    version: block.join("\n").match(/^        version:\s*['\"]?([^'\"\s]+)['\"]?\s*$/m)?.[1] ?? null,
+  };
+}
+
+async function inspectPackageProvenance(targetDir, dependencyMap) {
+  const issues = [];
+  const verified = [];
+  const lockPath = await findUp(targetDir, "pnpm-lock.yaml");
+  const installRoot = path.join(targetDir, "node_modules");
+  if (!lockPath || !(await pathExists(installRoot))) {
+    return { issues, verified, lockPath, available: false };
+  }
+  const lockfile = lockPath ? await fs.readFile(lockPath, "utf8") : null;
+  const importerKey = lockPath
+    ? path.relative(path.dirname(lockPath), targetDir).split(path.sep).join("/") || "."
+    : ".";
+  const workspaceManifest = lockPath ? await readJsonIfPresent(path.join(path.dirname(lockPath), "package.json")) : null;
+  const overrideMaps = [
+    workspaceManifest?.pnpm?.overrides,
+    workspaceManifest?.pnpm?.patchedDependencies,
+    workspaceManifest?.overrides,
+    workspaceManifest?.resolutions,
+  ].filter((value) => value && typeof value === "object");
+  for (const packageName of BRIGHTWEB_PACKAGE_NAMES) {
+    const requested = dependencyMap[packageName];
+    if (!requested) continue;
+    if (LOCAL_DEPENDENCY_PREFIXES.some((prefix) => String(requested).startsWith(prefix))) {
+      issues.push(`${packageName}: local override ${JSON.stringify(requested)} is forbidden`);
+      continue;
+    }
+    const overrideKey = overrideMaps.flatMap((overrides) => Object.keys(overrides)).find(
+      (key) => key === packageName || key.startsWith(`${packageName}@`),
+    );
+    if (overrideKey) {
+      issues.push(`${packageName}: workspace override or patch ${JSON.stringify(overrideKey)} is forbidden`);
+      continue;
+    }
+    const expectedVersion = exactVersionFromDefault(packageName);
+    if (!expectedVersion) {
+      issues.push(`${packageName}: create-bw-app has no exact compatibility version`);
+      continue;
+    }
+    const manifest = await readJsonIfPresent(path.join(targetDir, "node_modules", packageName, "package.json"));
+    if (!manifest) {
+      issues.push(`${packageName}: installed package manifest is missing`);
+      continue;
+    }
+    if (manifest.version !== expectedVersion) {
+      issues.push(`${packageName}: installed ${manifest.version ?? "unknown"}, expected exact ${expectedVersion}`);
+      continue;
+    }
+    if (!lockfile) {
+      issues.push(`${packageName}: pnpm-lock.yaml was not found`);
+      continue;
+    }
+    const importerResolution = lockfileImporterResolution(lockfile, importerKey, packageName);
+    if (!importerResolution) {
+      issues.push(`${packageName}: target importer ${importerKey} has no lockfile resolution`);
+      continue;
+    }
+    if (LOCAL_DEPENDENCY_PREFIXES.some((prefix) => String(importerResolution.version).startsWith(prefix))) {
+      issues.push(`${packageName}: target importer resolves through forbidden ${JSON.stringify(importerResolution.version)}`);
+      continue;
+    }
+    const resolvedVersion = importerResolution.version?.split("(")[0] ?? null;
+    if (resolvedVersion !== expectedVersion) {
+      issues.push(`${packageName}: target importer resolves ${resolvedVersion ?? "unknown"}, expected exact ${expectedVersion}`);
+      continue;
+    }
+    const integrity = lockfileIntegrityForPackage(lockfile, packageName, expectedVersion);
+    if (!integrity?.startsWith("sha512-")) {
+      issues.push(`${packageName}@${expectedVersion}: registry integrity is missing from pnpm-lock.yaml`);
+      continue;
+    }
+    verified.push(`${packageName}@${expectedVersion}`);
+  }
+  return { issues, verified, lockPath, available: true };
+}
 
 function isLocalDeploymentUrl(value) {
   try {
@@ -202,6 +340,17 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
   }
   add(packageProblems.length ? "FAIL" : "PASS", "packages", packageProblems.join("; ") || "Installed module packages agree with the manifest.");
 
+  const provenance = await inspectPackageProvenance(targetDir, dependencyMap);
+  if (!provenance.available) {
+    add("INFO", "package-provenance", "SKIP exact registry provenance check; install dependencies with a pnpm lockfile first.");
+  } else {
+    add(
+      provenance.issues.length ? "FAIL" : "PASS",
+      "package-provenance",
+      provenance.issues.join("; ") || `${provenance.verified.length} BrightWeb packages match the exact compatibility set and pnpm registry integrity records.`,
+    );
+  }
+
   const runtimeVersions = await findInstalledRuntimeVersions(targetDir);
   const duplicateRuntimes = Object.entries(runtimeVersions)
     .filter(([, versions]) => versions.length > 1)
@@ -276,6 +425,37 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
     if (status.shipsMigrations && status.missing.length > 0) migrationProblems.push(`${key}: ${status.missing.join(", ")}`);
   }
   add(migrationProblems.length ? "FAIL" : "PASS", "migrations", migrationProblems.join("; ") || "Migration cursors and flattened files agree.");
+  for (const key of migrationKeys) {
+    const cursor = appManifest.migrationCursor?.[key];
+    if (cursor == null && appManifest.adoptionNotes?.allowUncursored) {
+      add("WARN", `migration-provenance-${key}`, `${key}: exact migration provenance is unavailable because uncursored adoption is enabled.`);
+      continue;
+    }
+    const status = await exactMigrationCompatibilityStatus({
+      targetDir,
+      moduleKey: key,
+      cursor,
+      catalogEntry: catalog[key],
+      allowDeferred: appManifest.migrationDeferrals?.[key]?.reason === "destructive"
+        && appManifest.migrationDeferrals[key].cursor === cursor,
+    });
+    if (!status.shipsMigrations) continue;
+    const deferral = appManifest.migrationDeferrals?.[key];
+    if (deferral && (!status.deferred?.length || deferral.nextMigration !== status.deferred[0] || !status.nextDeferredIsDestructive)) {
+      status.issues.push(`recorded destructive deferral ${deferral.nextMigration} does not match the next destructive package migration`);
+    }
+    add(
+      status.issues.length ? "FAIL" : "PASS",
+      `migration-provenance-${key}`,
+      status.issues.join("; ") || `${status.verified.length} ${key} migration files match compatible package provenance, source filename, current cursor, and sha256 content.`,
+    );
+    if (status.deferred?.length && status.issues.length === 0) {
+      add("INFO", `migration-deferred-${key}`, `${key}: ${status.deferred.length} later package migration${status.deferred.length === 1 ? " is" : "s are"} intentionally outside cursor ${cursor}: ${status.deferred.join(", ")}.`);
+    }
+    if (status.legacyEquivalent?.length) {
+      add("INFO", `migration-legacy-equivalent-${key}`, `${key}: ${status.legacyEquivalent.length} immutable historical migration file${status.legacyEquivalent.length === 1 ? " matches" : "s match"} a reviewed SQL-equivalent legacy hash.`);
+    }
+  }
   add("WARN", "db-objects", "SKIP live database checks are not available yet.");
   return finish(checks, argvOptions, appManifest, targetDir);
 }

package/src/generator.mjs

@@ -1044,7 +1044,7 @@ export function createModuleToolbarControlsConfig(selectedModules) {
   }
   if (selectedModules.includes("projects")) {
     imports.push('import { ProjectBoardToolbarControls, ProjectsToolbarControls } from "@brightweblabs/module-projects/ui";');
-    entries.push('  projects: () => <ProjectsToolbarControls />,');
+    entries.push('  projects: (viewer) => <ProjectsToolbarControls viewer={viewer} />,');
     entries.push('  "project-board": () => <ProjectBoardToolbarControls />,');
   }
   if (selectedModules.includes("marketing")) {
@@ -1060,13 +1060,15 @@ export function createModuleToolbarControlsConfig(selectedModules) {
     "// MANAGED BY BRIGHTWEB — regenerated when modules are added, removed, or updated.",
     ...imports,
     "",
-    "const toolbarControlBySurface: Partial<Record<ShellToolbarSurface, () => ReactNode>> = {",
+    "type ModuleToolbarViewer = { isAdmin: boolean };",
+    "",
+    "const toolbarControlBySurface: Partial<Record<ShellToolbarSurface, (viewer: ModuleToolbarViewer) => ReactNode>> = {",
     ...entries,
     "};",
     "",
-    "export function getModuleToolbarControls(pathname: string, toolbarRoutes: ShellToolbarRouteConfig[]) {",
+    "export function getModuleToolbarControls(pathname: string, toolbarRoutes: ShellToolbarRouteConfig[], viewer: ModuleToolbarViewer) {",
     "  const surface = resolveShellToolbarSurface(pathname, toolbarRoutes);",
-    "  return surface ? toolbarControlBySurface[surface]?.() ?? null : null;",
+    "  return surface ? toolbarControlBySurface[surface]?.(viewer) ?? null : null;",
     "}",
     "",
   ].join("\n");
@@ -1074,11 +1076,11 @@ export function createModuleToolbarControlsConfig(selectedModules) {
 
 function createOrganizationRoute(methods, enabled) {
   const lines = ['export const dynamic = "force-dynamic";', ""];
-  for (const { method, handler, context = false } of methods) {
+  for (const { method, handler, context = false, packageName = "@brightweblabs/module-orgs" } of methods) {
     if (enabled) {
       lines.push(
         `export async function ${method}(request: Request${context ? ', context: { params: Promise<{ id: string }> }' : ""}) {`,
-        `  const { ${handler} } = await import("@brightweblabs/module-orgs");`,
+        `  const { ${handler} } = await import("${packageName}");`,
         `  return ${handler}(request${context ? ", context" : ""});`,
         "}",
         "",
@@ -1214,20 +1216,34 @@ export function createOptionalModuleRouteFiles(selectedModules) {
   return {
     "app/api/invitations/_dependencies.ts": invitationDependencies,
     "app/api/organizations/route.ts": createOrganizationRoute([
-      { method: "POST", handler: "handleOrganizationsPostRequest" },
+      crmEnabled
+        ? { method: "POST", handler: "handleCrmOrganizationsPostRequest", packageName: "@brightweblabs/module-crm" }
+        : { method: "POST", handler: "handleOrganizationsPostRequest" },
     ], orgsEnabled),
     "app/api/organizations/[id]/route.ts": createOrganizationRoute([
-      { method: "PATCH", handler: "handleOrganizationPatchRequest", context: true },
+      crmEnabled
+        ? { method: "PATCH", handler: "handleCrmOrganizationPatchRequest", packageName: "@brightweblabs/module-crm", context: true }
+        : { method: "PATCH", handler: "handleOrganizationPatchRequest", context: true },
       { method: "DELETE", handler: "handleOrganizationDeleteRequest", context: true },
     ], orgsEnabled),
     "app/api/organizations/[id]/invitations/route.ts": createOrganizationRoute([
       { method: "GET", handler: "handleOrganizationInvitationsGetRequest", context: true },
-      { method: "POST", handler: "handleOrganizationInvitationsPostRequest", context: true },
+      crmEnabled
+        ? { method: "POST", handler: "handleCrmOrganizationInvitationsPostRequest", packageName: "@brightweblabs/module-crm", context: true }
+        : { method: "POST", handler: "handleOrganizationInvitationsPostRequest", context: true },
     ], orgsEnabled),
     "app/api/organizations/[id]/invitations/[invitationId]/route.ts": orgsEnabled
       ? [
         'export const dynamic = "force-dynamic";',
         "",
+        "export async function POST(",
+        "  request: Request,",
+        "  context: { params: Promise<{ id: string; invitationId: string }> },",
+        ") {",
+        '  const { handleOrganizationInvitationResendRequest } = await import("@brightweblabs/module-orgs");',
+        "  return handleOrganizationInvitationResendRequest(request, context);",
+        "}",
+        "",
         "export async function DELETE(",
         "  request: Request,",
         "  context: { params: Promise<{ id: string; invitationId: string }> },",
@@ -1242,6 +1258,10 @@ export function createOptionalModuleRouteFiles(selectedModules) {
         "",
         'type RouteContext = { params: Promise<{ id: string; invitationId: string }> };',
         "",
+        "export async function POST(_request: Request, _context: RouteContext) {",
+        "  return new Response(null, { status: 404 });",
+        "}",
+        "",
         "export async function DELETE(_request: Request, _context: RouteContext) {",
         "  return new Response(null, { status: 404 });",
         "}",

package/src/migrations.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { resolveSafeRelativePath } from "./safe-path.mjs";
 import { TEMPLATE_ROOT, pathExists } from "./generator.mjs";
 
@@ -49,13 +50,17 @@ export async function planMigrationAppends({
 }) {
   const migrationsDir = await findAppMigrationsDirectory(targetDir);
   const existing = (await pathExists(migrationsDir))
-    ? (await fs.readdir(migrationsDir)).filter((fileName) => fileName.endsWith(".sql")).sort()
+    ? await Promise.all((await fs.readdir(migrationsDir)).filter((fileName) => fileName.endsWith(".sql")).sort().map(async (fileName) => ({
+      fileName,
+      targetPath: path.join(migrationsDir, fileName),
+      content: await fs.readFile(path.join(migrationsDir, fileName), "utf8"),
+    })))
     : [];
-  let sequence = existing.reduce((maximum, fileName) => {
-    const match = fileName.match(/^(\d+)_/);
+  let sequence = existing.reduce((maximum, entry) => {
+    const match = entry.fileName.match(/^(\d+)_/);
     return Math.max(maximum, Number(match?.[1] || 0));
   }, 0);
-  const writes = [];
+  const appends = [];
   const deferred = [];
   const nextCursor = { ...migrationCursor };
   for (const moduleKey of moduleKeys) {
@@ -88,7 +93,7 @@ export async function planMigrationAppends({
       const targetFileName = `${String(sequence).padStart(4, "0")}_${moduleKey}__${entry.fileName}`;
       const source = await fs.readFile(entry.sourcePath, "utf8");
       const version = catalog[moduleKey]?.version || "unknown";
-      writes.push({
+      appends.push({
         moduleKey,
         originalFileName: entry.fileName,
         targetFileName,
@@ -98,7 +103,7 @@ export async function planMigrationAppends({
     }
     if (migrationsInScope.length > 0) nextCursor[moduleKey] = migrationsInScope.at(-1).fileName;
   }
-  return { writes, deferred, nextCursor };
+  return { writes: appends, repairs: [], appends, deferred, nextCursor };
 }
 
 export async function applyMigrationWrites(writes) {
@@ -131,3 +136,108 @@ export async function cursorMigrationStatus({ targetDir, moduleKey, cursor, cata
     })).map((entry) => entry.fileName),
   };
 }
+
+function sha256(source) {
+  return createHash("sha256").update(source).digest("hex");
+}
+
+// Historical generated files are immutable. These hashes are reviewed SQL-equivalent
+// renderings shipped by early consumers before canonical provenance was enforced.
+const REVIEWED_LEGACY_MIGRATION_HASHES = new Map([
+  ["core/20260731120000_core_notifications.sql", new Set(["20fbd2158741871ac6b65c4033db5d7c9e889b03a5876d1f32f2b368b35cf24a"])],
+  ["projects/20260731121000_project_notification_audiences.sql", new Set(["1726f2f2403401cda677419e26b49ffa521e49ef0bfa72b56e42428ded7c6312"])],
+]);
+
+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;
+}
+
+export async function exactMigrationCompatibilityStatus({ targetDir, moduleKey, cursor, catalogEntry, allowDeferred = false }) {
+  const migrations = await getModuleMigrations(moduleKey, catalogEntry);
+  if (migrations.length === 0) return { shipsMigrations: false, issues: [], verified: [] };
+  const issues = [];
+  const latest = migrations.at(-1)?.fileName ?? null;
+  let migrationsInScope = [];
+  if (!cursor) {
+    issues.push("migration cursor is missing");
+  } else if (!migrations.some((entry) => entry.fileName === cursor)) {
+    issues.push(`cursor ${cursor} does not exist in the shipped migration history`);
+  } else {
+    migrationsInScope = migrations.filter((entry) => entry.fileName <= cursor);
+    if (cursor !== latest && !allowDeferred) {
+      issues.push(`cursor ${cursor} is stale; exact package compatibility requires ${latest}`);
+    }
+  }
+
+  const migrationsDir = await findAppMigrationsDirectory(targetDir);
+  const installed = [];
+  if (await pathExists(migrationsDir)) {
+    for (const fileName of await fs.readdir(migrationsDir)) {
+      if (!fileName.endsWith(".sql")) continue;
+      installed.push({ fileName, content: await fs.readFile(path.join(migrationsDir, fileName), "utf8") });
+    }
+  }
+
+  const verified = [];
+  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);
+      return (header?.[1] === moduleKey && header?.[3] === entry.fileName)
+        || fileName === entry.fileName
+        || fileName.endsWith(`_${moduleKey}__${entry.fileName}`);
+    });
+    if (matches.length === 0) {
+      issues.push(`${entry.fileName}: generated migration file is missing`);
+      continue;
+    }
+    if (matches.length > 1) {
+      issues.push(`${entry.fileName}: appears in multiple generated migration files (${matches.map(({ fileName }) => fileName).join(", ")})`);
+      continue;
+    }
+    const [{ fileName, content }] = matches;
+    const header = content.match(/^\s*--\s*bw-module:\s*([^@\s]+)@([^\s]+)\s+([^\s]+)\s*\n/im);
+    const expectedVersion = catalogEntry?.version;
+    if (expectedVersion && header) {
+      const comparison = compareSemver(header[2], expectedVersion);
+      if (comparison == null || comparison > 0) {
+        issues.push(`${fileName}: provenance version ${header[2]} is incompatible with installed ${moduleKey}@${expectedVersion}`);
+        continue;
+      }
+    }
+    const source = await fs.readFile(entry.sourcePath, "utf8");
+    const generatedSource = header ? content.slice(header[0].length) : content;
+    const expectedHash = sha256(source);
+    const actualHash = sha256(generatedSource);
+    if (actualHash !== expectedHash) {
+      if (REVIEWED_LEGACY_MIGRATION_HASHES.get(`${moduleKey}/${entry.fileName}`)?.has(actualHash)) {
+        verified.push({ fileName, originalFileName: entry.fileName, sha256: actualHash });
+        legacyEquivalent.push({ fileName, originalFileName: entry.fileName, sha256: actualHash, canonicalSha256: expectedHash });
+        continue;
+      }
+      issues.push(`${fileName}: sha256 ${actualHash} does not match ${entry.fileName} sha256 ${expectedHash}`);
+      continue;
+    }
+    verified.push({ fileName, originalFileName: entry.fileName, sha256: expectedHash });
+  }
+
+  const deferredEntries = cursor && migrations.some((entry) => entry.fileName === cursor)
+    ? migrations.filter((entry) => entry.fileName > cursor)
+    : [];
+
+  return {
+    shipsMigrations: true,
+    latest,
+    issues,
+    verified,
+    legacyEquivalent,
+    deferred: deferredEntries.map((entry) => entry.fileName),
+    nextDeferredIsDestructive: deferredEntries[0]?.destructive === true,
+  };
+}

package/src/upgrade.mjs

@@ -6,6 +6,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 { 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`;
 
@@ -40,6 +41,19 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
     if (await hashFile(filePath) !== record.hash) drifted.push(relativePath);
   }
   const protectedPaths = new Set([...drifted, ...intentional]);
+  const obsoleteScaffoldFiles = [];
+  if (argvOptions.refreshStarters) {
+    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;
+        obsoleteScaffoldFiles.push({ relativePath, targetPath });
+      }
+    }
+  }
+  plan.fileDeletes = obsoleteScaffoldFiles;
   plan.fileWrites = plan.fileWrites.filter((entry) => entry.type !== "starter" || !protectedPaths.has(entry.relativePath));
   plan.starterFilesToRefresh = plan.fileWrites.filter((entry) => entry.type === "starter").map((entry) => entry.relativePath);
   plan.starterFilesDrifted = Array.from(new Set([...plan.starterFilesDrifted, ...drifted]));
@@ -93,7 +107,7 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
     migrationCursor: appManifest.migrationCursor,
     migrationUpperBounds,
   });
-  output.write(`bw upgrade\nPackages to update: ${plan.packageUpdates.length}\nManaged files to write: ${plan.fileWrites.length}\nMigrations to append: ${migrationPlan.writes.length}\n`);
+  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) {
     output.write(`Migration safety boundary: ${boundary.moduleKey} through ${boundary.boundary}; held ${boundary.destructiveMigration}\n`);
@@ -107,14 +121,33 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   for (const relativePath of missing) output.write(`- missing: ${relativePath}\n`);
   for (const relativePath of drifted) output.write(`- drifted: ${relativePath}\n`);
   for (const relativePath of intentional) output.write(`- intent-protected: ${relativePath}\n`);
+  for (const entry of plan.fileDeletes) output.write(`- obsolete managed file: ${entry.relativePath}\n`);
   if (argvOptions.dryRun) return { dryRun: true, plan, migrationPlan, drifted, missing };
 
   for (const write of plan.fileWrites) {
     await fs.mkdir(path.dirname(write.targetPath), { recursive: true });
     await fs.writeFile(write.targetPath, write.content, "utf8");
   }
+  for (const deletion of plan.fileDeletes) {
+    await fs.unlink(deletion.targetPath);
+    delete appManifest.scaffoldFiles[deletion.relativePath];
+  }
   await applyMigrationWrites(migrationPlan.writes);
   appManifest.migrationCursor = migrationPlan.nextCursor;
+  appManifest.migrationDeferrals ??= {};
+  for (const key of moduleKeys) {
+    const firstDeferred = migrationPlan.deferred.find((entry) => entry.moduleKey === key);
+    if (firstDeferred?.destructive) {
+      appManifest.migrationDeferrals[key] = {
+        reason: "destructive",
+        cursor: migrationPlan.nextCursor[key],
+        nextMigration: firstDeferred.fileName,
+      };
+    } else {
+      delete appManifest.migrationDeferrals[key];
+    }
+  }
+  if (Object.keys(appManifest.migrationDeferrals).length === 0) delete appManifest.migrationDeferrals;
   for (const [key, entry] of Object.entries(appManifest.modules)) {
     const packageName = catalog[key]?.packageName;
     if (catalog[key]?.packageRoot || plan.targetVersions?.[packageName]) entry.version = catalog[key].version;
@@ -144,7 +177,7 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
     const runner = runtimeOptions.installRunner || runInstall;
     await runner(plan.packageManager, plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : targetDir);
   }
-  output.write(`Applied ${plan.fileWrites.length} managed change${plan.fileWrites.length === 1 ? "" : "s"} and ${migrationPlan.writes.length} migration${migrationPlan.writes.length === 1 ? "" : "s"}.\n`);
+  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/base/app/(shell)/shell-layout-client.tsx

@@ -84,7 +84,7 @@ function ShellLayoutInner({
     viewer.email ||
     "Conta";
   const projectsBaseHref = pathname.startsWith("/projects") ? "/projects" : "/projetos";
-  const toolbarControls = getModuleToolbarControls(pathname, toolbarRoutes);
+  const toolbarControls = getModuleToolbarControls(pathname, toolbarRoutes, viewer);
 
   const dispatchShellAction = useShellActionDispatch();
   useShellAction("projects-back-to-portfolio", () => {

package/template/base/app/api/organizations/[id]/invitations/[invitationId]/route.ts

@@ -1,5 +1,13 @@
 export const dynamic = "force-dynamic";
 
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ id: string; invitationId: string }> },
+) {
+  const { handleOrganizationInvitationResendRequest } = await import("@brightweblabs/module-orgs");
+  return handleOrganizationInvitationResendRequest(request, context);
+}
+
 export async function DELETE(
   request: Request,
   context: { params: Promise<{ id: string; invitationId: string }> },

package/template/base/app/api/organizations/[id]/invitations/route.ts

@@ -6,6 +6,6 @@ export async function GET(request: Request, context: { params: Promise<{ id: str
 }
 
 export async function POST(request: Request, context: { params: Promise<{ id: string }> }) {
-  const { handleOrganizationInvitationsPostRequest } = await import("@brightweblabs/module-orgs");
-  return handleOrganizationInvitationsPostRequest(request, context);
+  const { handleCrmOrganizationInvitationsPostRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmOrganizationInvitationsPostRequest(request, context);
 }