create-bw-app 0.10.0 → 0.11.0

package/src/constants.mjs

@@ -39,11 +39,15 @@ export const CORE_PACKAGES = [
   "@brightweblabs/app-shell",
   "@brightweblabs/core-auth",
   "@brightweblabs/infra",
+  "@brightweblabs/theme",
   "@brightweblabs/ui",
 ];
 
+export const ORGS_PACKAGE_NAME = "@brightweblabs/module-orgs";
+
 export const BRIGHTWEB_PACKAGE_NAMES = [
   ...CORE_PACKAGES,
+  ORGS_PACKAGE_NAME,
   ...SELECTABLE_MODULES.map((moduleDefinition) => moduleDefinition.packageName),
 ];
 
@@ -54,26 +58,34 @@ export const MODULE_STARTER_FILES = {
     "app/playground/admin/page.tsx",
   ],
   crm: [
+    "app/crm/layout.tsx",
+    "app/crm/page.tsx",
     "app/api/crm/contacts/route.ts",
     "app/api/crm/organizations/route.ts",
     "app/api/crm/owners/route.ts",
     "app/api/crm/stats/route.ts",
-    "app/playground/crm/page.tsx",
+    "app/api/crm/timeline/route.ts",
   ],
   projects: [
     "app/playground/projects/page.tsx",
   ],
 };
 
+export const PLATFORM_STARTER_FILES = [
+  "config/shell.overrides.ts",
+];
+
 export const APP_DEPENDENCY_DEFAULTS = {
-  "@brightweblabs/app-shell": "^0.3.0",
-  "@brightweblabs/core-auth": "^0.3.1",
-  "@brightweblabs/infra": "^0.2.1",
-  "@brightweblabs/module-admin": "^0.3.0",
-  "@brightweblabs/module-crm": "^0.3.0",
-  "@brightweblabs/module-projects": "^0.2.2",
-  "@brightweblabs/ui": "^0.3.0",
-  "lucide-react": "^0.562.0",
+  "@brightweblabs/app-shell": "^0.4.0",
+  "@brightweblabs/core-auth": "^0.3.4",
+  "@brightweblabs/infra": "^0.3.1",
+  "@brightweblabs/module-admin": "^0.3.4",
+  "@brightweblabs/module-crm": "^0.5.0",
+  "@brightweblabs/module-orgs": "^0.2.0",
+  "@brightweblabs/module-projects": "^0.4.2",
+  "@brightweblabs/theme": "^0.2.0",
+  "@brightweblabs/ui": "^1.0.0",
+  "lucide-react": "^1.8.0",
   "next": "16.1.6",
   "react": "19.2.3",
   "react-dom": "19.2.3",
@@ -82,7 +94,7 @@ export const APP_DEPENDENCY_DEFAULTS = {
 export const SITE_DEPENDENCY_DEFAULTS = {
   "class-variance-authority": "^0.7.1",
   "clsx": "^2.1.1",
-  "lucide-react": "^0.562.0",
+  "lucide-react": "^1.8.0",
   "next": "16.1.6",
   "react": "19.2.3",
   "react-dom": "19.2.3",
@@ -110,7 +122,6 @@ export const DEFAULTS = {
   tagline: "A configurable Brightweb starter app for new client instances.",
   contactEmail: "hello@example.com",
   supportEmail: "support@example.com",
-  primaryHex: "#1f7a45",
 };
 
 export const HELP_TEXT = `

package/src/diff.mjs

@@ -0,0 +1,85 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { findWorkspaceRoot, readAppManifest } from "./app-manifest.mjs";
+import { pathExists } from "./generator.mjs";
+import { findTrackedTemplate, scaffoldDrift } from "./scaffold.mjs";
+
+const HELP = `Usage: bw diff <relpath> [options]\n       bw diff --list [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --list                    Print tracked scaffold drift status\n  --help                    Show this help`;
+
+function splitLines(content) {
+  const lines = content.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+export function unifiedLineDiff(beforeContent, afterContent, beforeName, afterName) {
+  const before = splitLines(beforeContent);
+  const after = splitLines(afterContent);
+  const table = Array.from({ length: before.length + 1 }, () => new Uint32Array(after.length + 1));
+  for (let left = before.length - 1; left >= 0; left -= 1) {
+    for (let right = after.length - 1; right >= 0; right -= 1) {
+      table[left][right] = before[left] === after[right]
+        ? table[left + 1][right + 1] + 1
+        : Math.max(table[left + 1][right], table[left][right + 1]);
+    }
+  }
+  const body = [];
+  let left = 0;
+  let right = 0;
+  while (left < before.length || right < after.length) {
+    if (left < before.length && right < after.length && before[left] === after[right]) {
+      body.push(` ${before[left]}`); left += 1; right += 1;
+    } else if (right < after.length && (left === before.length || table[left][right + 1] >= table[left + 1][right])) {
+      body.push(`+${after[right]}`); right += 1;
+    } else {
+      body.push(`-${before[left]}`); left += 1;
+    }
+  }
+  return [
+    `--- a/${beforeName}`,
+    `+++ b/${afterName}`,
+    `@@ -1,${before.length} +1,${after.length} @@`,
+    ...body,
+    "",
+  ].join("\n");
+}
+
+export async function diffBrightwebScaffold(relativePath, argvOptions = {}, runtimeOptions = {}) {
+  if (argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const manifest = await readAppManifest(targetDir);
+  if (argvOptions.list) {
+    const drift = await scaffoldDrift(targetDir, manifest.scaffoldFiles);
+    output.write("STATUS\tSCAFFOLD FILE\n");
+    for (const status of ["current", "drifted", "missing"]) {
+      for (const file of drift[status]) output.write(`${status}\t${file}\n`);
+    }
+    return { list: true, drift };
+  }
+  if (!relativePath) throw new Error("bw diff requires a tracked scaffold <relpath>, or pass --list.");
+  const normalized = path.normalize(relativePath).replace(/^\.\//, "");
+  if (path.isAbsolute(relativePath) || normalized.startsWith(`..${path.sep}`)) throw new Error(`Scaffold path must be relative to the app: ${relativePath}`);
+  const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const located = await findTrackedTemplate({ relativePath: normalized, manifest, targetDir, workspaceRoot });
+  if (!located.record) throw new Error(`${normalized} is not a tracked scaffold file.`);
+  if (!located.templatePath) {
+    const warning = `WARN Installed-package template unavailable for ${normalized}; diff is unsupported.`;
+    output.write(`${warning}\n`);
+    return { supported: false, warning };
+  }
+  const appPath = path.join(targetDir, normalized);
+  const [templateContent, appContent] = await Promise.all([
+    fs.readFile(located.templatePath, "utf8"),
+    pathExists(appPath) ? fs.readFile(appPath, "utf8") : Promise.resolve(""),
+  ]);
+  if (templateContent === appContent) {
+    output.write(`${normalized}: identical\n`);
+    return { supported: true, identical: true, diff: "" };
+  }
+  const diff = unifiedLineDiff(templateContent, appContent, `template/${normalized}`, normalized);
+  output.write(diff);
+  return { supported: true, identical: false, diff };
+}
+
+export { HELP as DIFF_HELP };

package/src/doctor.mjs

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { cursorMigrationStatus } from "./migrations.mjs";
+import { findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, readConfiguredModuleFlags, satisfiesVersion, validateAppManifest, writeAppManifest } from "./app-manifest.mjs";
+import { pathExists, readJsonIfPresent } from "./generator.mjs";
+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  --strict                  Treat warnings as failures\n  --report                  Stamp lastDoctor in the app manifest\n  --help                    Show this help`;
+
+export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
+  if (argvOptions.help) { output.write(`${HELP}\n`); return { help: true, ok: true }; }
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const checks = [];
+  const add = (status, id, message) => checks.push({ status, id, message });
+  let appManifest;
+  try { appManifest = await readAppManifest(targetDir); } catch (error) {
+    add("FAIL", "manifest", error instanceof Error ? error.message : String(error));
+    return finish(checks, argvOptions, null, targetDir);
+  }
+  const validationErrors = validateAppManifest(appManifest);
+  if (validationErrors.length > 0) add("FAIL", "manifest", validationErrors.join("; "));
+  else add("PASS", "manifest", "App manifest is valid.");
+
+  const packageJson = await readJsonIfPresent(path.join(targetDir, "package.json"));
+  const dependencyMap = { ...(packageJson?.dependencies || {}), ...(packageJson?.devDependencies || {}) };
+  const packageProblems = [];
+  for (const [key, entry] of Object.entries(appManifest.modules || {})) {
+    const packageName = MODULE_PACKAGES[key];
+    if (!packageName || !dependencyMap[packageName]) packageProblems.push(`${key}: ${packageName || "unknown package"} is missing`);
+    else if (!satisfiesVersion(entry.version, dependencyMap[packageName])) packageProblems.push(`${key}@${entry.version} does not satisfy package.json ${dependencyMap[packageName]}`);
+  }
+  for (const [key, packageName] of Object.entries(MODULE_PACKAGES)) {
+    if (dependencyMap[packageName] && !appManifest.modules[key]) packageProblems.push(`${packageName} is installed but absent from manifest.modules`);
+  }
+  add(packageProblems.length ? "FAIL" : "PASS", "packages", packageProblems.join("; ") || "Installed module packages agree with the manifest.");
+
+  const flags = await readConfiguredModuleFlags(targetDir);
+  const exposureProblems = Object.entries(appManifest.modules || {}).filter(([key, entry]) => typeof flags[key] === "boolean" && flags[key] !== entry.exposed).map(([key, entry]) => `${key}: manifest exposed=${entry.exposed}, config enabled=${String(flags[key])}`);
+  add(exposureProblems.length ? "FAIL" : "PASS", "exposure", exposureProblems.join("; ") || "Module exposure flags agree.");
+
+  const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
+  const available = { core: catalog.core.version, admin: catalog.admin.version, ...Object.fromEntries(Object.entries(appManifest.modules || {}).map(([key, entry]) => [key, entry.version])) };
+  const topologyProblems = [];
+  for (const key of Object.keys(appManifest.modules || {})) {
+    for (const [requiredKey, range] of Object.entries(catalog[key]?.requires || {})) {
+      if (!available[requiredKey]) topologyProblems.push(`${key} requires missing ${requiredKey}@${range}`);
+      else if (!satisfiesVersion(available[requiredKey], range)) topologyProblems.push(`${key} requires ${requiredKey}@${range}, found ${available[requiredKey]}`);
+    }
+  }
+  add(topologyProblems.length ? "FAIL" : "PASS", "topology", topologyProblems.join("; ") || "Module requirements are satisfied.");
+
+  const scaffold = await scaffoldDrift(targetDir, appManifest.scaffoldFiles);
+  add(scaffold.drifted.length || scaffold.missing.length ? "FAIL" : "PASS", "scaffold", `${scaffold.current.length} current, ${scaffold.drifted.length} drifted, ${scaffold.missing.length} missing; drifted scaffold files: ${scaffold.drifted.length} (see bw diff --list)${scaffold.missing.length ? `; missing: ${scaffold.missing.join(", ")}` : ""}`);
+  add("INFO", "owned-surfaces", `Owned surfaces: ${(appManifest.ownedSurfaces || []).join(", ") || "none"}.`);
+
+  const envNames = new Set(Object.keys(process.env));
+  const envPath = path.join(targetDir, ".env.local");
+  if (await pathExists(envPath)) {
+    for (const line of (await fs.readFile(envPath, "utf8")).split(/\r?\n/)) {
+      const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+      if (match) envNames.add(match[1]);
+    }
+  }
+  const missingEnv = [];
+  for (const key of Object.keys(appManifest.modules || {})) for (const entry of catalog[key]?.manifest?.env || []) if (entry.required && !envNames.has(entry.name)) missingEnv.push(`${key}:${entry.name}`);
+  add(missingEnv.length ? "FAIL" : "PASS", "env", missingEnv.length ? `Missing required names: ${missingEnv.join(", ")}` : "Required environment variable names are present.");
+
+  const migrationProblems = [];
+  const migrationKeys = appManifest.app.template === "platform"
+    ? Array.from(new Set(["core", "admin", ...Object.keys(appManifest.modules || {})]))
+    : [];
+  for (const key of migrationKeys) {
+    const cursor = appManifest.migrationCursor?.[key];
+    const status = await cursorMigrationStatus({ targetDir, moduleKey: key, cursor, catalogEntry: catalog[key] });
+    if (status.shipsMigrations && cursor == null) {
+      if (appManifest.adoptionNotes?.allowUncursored) add("WARN", `migration-cursor-${key}`, `${key}: migration cursor is null; adoption explicitly allowed uncursored operation.`);
+      else migrationProblems.push(`${key}: migration cursor is null (run bw adopt --force --cursor ${key}=<migrationFilename>, or explicitly adopt with --allow-uncursored)`);
+      continue;
+    }
+    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.");
+  add("WARN", "db-objects", "SKIP live database checks are not available yet.");
+  return finish(checks, argvOptions, appManifest, targetDir);
+}
+
+async function finish(checks, options, appManifest, targetDir) {
+  for (const check of checks) output.write(`${check.status} ${check.id}: ${check.message}\n`);
+  const hasFailure = checks.some((check) => check.status === "FAIL") || (options.strict && checks.some((check) => check.status === "WARN"));
+  if (options.report && appManifest) {
+    appManifest.lastDoctor = { at: new Date().toISOString(), ok: !hasFailure };
+    await writeAppManifest(targetDir, appManifest);
+  }
+  return { ok: !hasFailure, checks };
+}
+
+export { HELP as DOCTOR_HELP };

package/src/generator.mjs

@@ -10,11 +10,13 @@ import {
   CLI_DISPLAY_NAME,
   CORE_PACKAGES,
   DEFAULTS,
+  ORGS_PACKAGE_NAME,
   SELECTABLE_MODULES,
   SITE_DEPENDENCY_DEFAULTS,
   SITE_DEV_DEPENDENCY_DEFAULTS,
   TEMPLATE_OPTIONS,
 } from "./constants.mjs";
+import { createInitialAppManifest, writeAppManifest } from "./app-manifest.mjs";
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
@@ -24,8 +26,9 @@ const DEFAULT_DB_MODULE_REGISTRY = {
   modules: {
     core: { label: "Core", dependsOn: [] },
     admin: { label: "Admin", dependsOn: ["core"] },
-    crm: { label: "CRM", dependsOn: ["core", "admin"] },
-    projects: { label: "Projects", dependsOn: ["core", "admin", "crm"] },
+    orgs: { label: "Organizations", dependsOn: ["core", "admin"] },
+    crm: { label: "CRM", dependsOn: ["core", "admin", "orgs"] },
+    projects: { label: "Projects", dependsOn: ["core", "admin", "orgs"] },
   },
 };
 
@@ -131,7 +134,8 @@ export async function getDbModuleRegistry(workspaceRoot) {
   return DEFAULT_DB_MODULE_REGISTRY;
 }
 
-function resolveModuleOrder(registry, enabledModules) {
+// Duplicated by design: scripts/_db-modules.mjs — keep in sync.
+export function resolveModuleOrder(registry, enabledModules) {
   const resolved = [];
   const visited = new Set();
   const visiting = new Set();
@@ -247,7 +251,9 @@ export async function getVersionMap(workspaceRoot) {
     "@brightweblabs/infra",
     "@brightweblabs/module-admin",
     "@brightweblabs/module-crm",
+    "@brightweblabs/module-orgs",
     "@brightweblabs/module-projects",
+    "@brightweblabs/theme",
     "@brightweblabs/ui",
   ]) {
     const folderName = packageName.replace("@brightweblabs/", "");
@@ -270,7 +276,6 @@ function createDerivedBrandValues(slug) {
     tagline: DEFAULTS.tagline,
     contactEmail: DEFAULTS.contactEmail,
     supportEmail: DEFAULTS.supportEmail,
-    primaryHex: DEFAULTS.primaryHex,
   };
 }
 
@@ -283,7 +288,6 @@ function createPlatformBrandConfigFile({ slug, brandValues }) {
     "  tagline: string;",
     "  contactEmail: string;",
     "  supportEmail: string;",
-    "  primaryHex: string;",
     "};",
     "",
     "export const starterBrandConfig: StarterBrandConfig = {",
@@ -293,7 +297,6 @@ function createPlatformBrandConfigFile({ slug, brandValues }) {
     `  tagline: ${JSON.stringify(brandValues.tagline)},`,
     `  contactEmail: ${JSON.stringify(brandValues.contactEmail)},`,
     `  supportEmail: ${JSON.stringify(brandValues.supportEmail)},`,
-    `  primaryHex: ${JSON.stringify(brandValues.primaryHex)},`,
     "};",
     "",
   ].join("\n");
@@ -301,9 +304,10 @@ function createPlatformBrandConfigFile({ slug, brandValues }) {
 
 export function createPlatformModulesConfigFile(selectedModules) {
   const selected = new Set(selectedModules);
+  const orgsEnabled = selected.has("crm") || selected.has("projects");
 
   return [
-    'export type StarterModuleKey = "core-auth" | "crm" | "projects" | "admin";',
+    'export type StarterModuleKey = "core-auth" | "orgs" | "crm" | "projects" | "admin";',
     "",
     "export type StarterModuleConfig = {",
     "  key: StarterModuleKey;",
@@ -312,7 +316,7 @@ export function createPlatformModulesConfigFile(selectedModules) {
     "  enabled: boolean;",
     "  packageName: string;",
     "  playgroundHref?: string;",
-    '  placement: "core" | "primary" | "admin";',
+    '  placement: "core" | "primary" | "admin" | "hidden";',
     "};",
     "",
     "export const starterModuleConfig: StarterModuleConfig[] = [",
@@ -326,12 +330,20 @@ export function createPlatformModulesConfigFile(selectedModules) {
     '    placement: "core",',
     "  },",
     "  {",
+    '    key: "orgs",',
+    '    label: "Organizations",',
+    '    description: "Shared organizations, membership, and invitation foundation for CRM and Projects.",',
+    `    enabled: ${String(orgsEnabled)},`,
+    '    packageName: "@brightweblabs/module-orgs",',
+    '    placement: "hidden",',
+    "  },",
+    "  {",
     '    key: "crm",',
     '    label: "CRM",',
-    '    description: "Contacts, marketing audience, and CRM server/data layer.",',
+    '    description: "Contacts and CRM server/data layer, with marketing-adjacent operational data stored in Supabase.",',
     `    enabled: ${String(selected.has("crm"))},`,
     '    packageName: "@brightweblabs/module-crm",',
-    '    playgroundHref: "/playground/crm",',
+    '    playgroundHref: "/crm",',
     '    placement: "primary",',
     "  },",
     "  {",
@@ -431,7 +443,7 @@ function getPlatformStarterRoutes(selectedModules) {
     "/bootstrap",
     "/preview/app-shell",
     "/playground/auth",
-    ...selectedModules.map((moduleKey) => `/playground/${moduleKey}`),
+    ...selectedModules.map((moduleKey) => moduleKey === "crm" ? "/crm" : `/playground/${moduleKey}`),
   ];
 }
 
@@ -636,11 +648,13 @@ export function createAppContextFile({
           "AGENTS.md",
           "docs/ai/README.md",
           "README.md",
+          "app/globals.css",
           "config/brand.ts",
           "config/modules.ts",
           "config/client.ts",
           "config/bootstrap.ts",
           "config/shell.ts",
+          "config/shell.overrides.ts",
           ".env.local",
         ],
         appRoutesRoot: "app",
@@ -661,6 +675,7 @@ export function createAppContextFile({
         ],
         packageOwned: [
           ...CORE_PACKAGES,
+          ...(selectedModules.includes("crm") || selectedModules.includes("projects") ? [ORGS_PACKAGE_NAME] : []),
           ...SELECTABLE_MODULES
             .filter((moduleDefinition) => selectedModules.includes(moduleDefinition.key))
             .map((moduleDefinition) => moduleDefinition.packageName),
@@ -722,6 +737,7 @@ export function createPackageJson({
     "@brightweblabs/app-shell": internalDependencyVersion("@brightweblabs/app-shell"),
     "@brightweblabs/core-auth": internalDependencyVersion("@brightweblabs/core-auth"),
     "@brightweblabs/infra": internalDependencyVersion("@brightweblabs/infra"),
+    "@brightweblabs/theme": internalDependencyVersion("@brightweblabs/theme"),
     "@brightweblabs/ui": internalDependencyVersion("@brightweblabs/ui"),
     "lucide-react": versionMap["lucide-react"],
     "next": versionMap.next,
@@ -734,6 +750,9 @@ export function createPackageJson({
       dependencies[moduleDefinition.packageName] = internalDependencyVersion(moduleDefinition.packageName);
     }
   }
+  if (selectedModules.includes("crm") || selectedModules.includes("projects")) {
+    dependencies[ORGS_PACKAGE_NAME] = internalDependencyVersion(ORGS_PACKAGE_NAME);
+  }
 
   return {
     name: slug,
@@ -770,6 +789,9 @@ export function createNextConfig({ template, selectedModules }) {
   }
 
   const transpilePackages = [...CORE_PACKAGES];
+  if (selectedModules.includes("crm") || selectedModules.includes("projects")) {
+    transpilePackages.push(ORGS_PACKAGE_NAME);
+  }
 
   for (const moduleDefinition of SELECTABLE_MODULES) {
     if (selectedModules.includes(moduleDefinition.key)) {
@@ -795,6 +817,11 @@ export function createShellConfig(selectedModules) {
   const importLines = [];
   const registrationLines = [];
 
+  if (selectedModules.includes("crm") || selectedModules.includes("projects")) {
+    importLines.push('import { orgsModuleRegistration } from "@brightweblabs/module-orgs/registration";');
+    registrationLines.push('  if (enabled.has("orgs")) registrations.push(orgsModuleRegistration);');
+  }
+
   if (selectedModules.includes("admin")) {
     importLines.push('import { adminModuleRegistration } from "@brightweblabs/module-admin/registration";');
     registrationLines.push('  if (enabled.has("admin")) registrations.push(adminModuleRegistration);');
@@ -811,8 +838,10 @@ export function createShellConfig(selectedModules) {
   }
 
   return [
+    "// MANAGED BY BRIGHTWEB — regenerated by create-bw-app update; put customizations in config/shell.overrides.ts",
     'import { LayoutDashboard, Wrench } from "lucide-react";',
     "import {",
+    "  applyShellRegistrationOverrides,",
     "  buildClientAppShellRegistration,",
     "  resolveClientAppShellConfig,",
     "  type ClientAppShellRegistration,",
@@ -822,6 +851,7 @@ export function createShellConfig(selectedModules) {
     ...importLines,
     'import { starterBrandConfig } from "./brand";',
     'import { getEnabledStarterModules } from "./modules";',
+    'import { shellRegistrationOverrides } from "./shell.overrides";',
     "",
     "const dashboardModuleRegistration: ShellModuleRegistration<ShellContextualAction> = {",
     '  key: "dashboard",',
@@ -841,6 +871,10 @@ export function createShellConfig(selectedModules) {
     "",
     "export function getStarterShellConfig() {",
     "  const enabledModules = getEnabledStarterModules();",
+    "  const modules = applyShellRegistrationOverrides(",
+    "    getStarterModuleRegistrations(),",
+    "    shellRegistrationOverrides,",
+    "  );",
     "  const shellRegistration: ClientAppShellRegistration<ShellContextualAction> = {",
     "    brand: {",
     '      href: "/",',
@@ -868,7 +902,7 @@ export function createShellConfig(selectedModules) {
     "      icon: Wrench,",
     '      collapsedHref: enabledModules.find((moduleConfig) => moduleConfig.playgroundHref)?.playgroundHref || "/",',
     "    },",
-    "    modules: getStarterModuleRegistrations(),",
+    "    modules,",
     "  };",
     "",
     "  const builtRegistration = buildClientAppShellRegistration(shellRegistration);",
@@ -1257,6 +1291,7 @@ async function scaffoldPlatformProject({
 
   if (workspaceMode) {
     await writeClientStack(workspaceRoot, answers.slug, dbInstallPlan, { workspaceMode: true });
+    await writeSupabaseCliMigrations({ targetDir, dbInstallPlan });
   } else {
     await writeBundledSupabaseBaseline({
       targetDir,
@@ -1265,6 +1300,17 @@ async function scaffoldPlatformProject({
       registry: dbRegistry,
     });
   }
+
+  const cliPackage = await readJsonIfPresent(path.join(PACKAGE_ROOT, "package.json"));
+  await writeAppManifest(targetDir, await createInitialAppManifest({
+    targetDir,
+    slug: answers.slug,
+    template: "platform",
+    selectedModules,
+    versionMap,
+    dbInstallPlan,
+    cliVersion: cliPackage?.version || "0.0.0",
+  }));
 }
 
 async function scaffoldSiteProject({
@@ -1316,6 +1362,16 @@ async function scaffoldSiteProject({
       packageManager,
     }),
   );
+  const cliPackage = await readJsonIfPresent(path.join(PACKAGE_ROOT, "package.json"));
+  await writeAppManifest(targetDir, await createInitialAppManifest({
+    targetDir,
+    slug: answers.slug,
+    template: "site",
+    selectedModules: [],
+    versionMap,
+    dbInstallPlan: { resolvedOrder: [] },
+    cliVersion: cliPackage?.version || "0.0.0",
+  }));
 }
 
 function printCompletionMessage({ targetDir, workspaceMode, slug, packageManager, install }) {

package/src/migrations.mjs

@@ -0,0 +1,92 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { TEMPLATE_ROOT, pathExists } from "./generator.mjs";
+
+export async function findAppMigrationsDirectory(targetDir) {
+  let current = path.resolve(targetDir);
+  while (true) {
+    const candidate = path.join(current, "supabase", "migrations");
+    if (await pathExists(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return path.join(path.resolve(targetDir), "supabase", "migrations");
+    current = parent;
+  }
+}
+
+export async function getModuleMigrations(moduleKey, catalogEntry = {}) {
+  const candidates = [];
+  const configuredPath = catalogEntry.manifest?.database?.migrations;
+  if (catalogEntry.packageRoot && configuredPath) candidates.push(path.resolve(catalogEntry.packageRoot, configuredPath));
+  if (catalogEntry.packageRoot) candidates.push(path.join(catalogEntry.packageRoot, "migrations"));
+  candidates.push(path.join(TEMPLATE_ROOT, "supabase", "modules", moduleKey, "migrations"));
+  for (const directory of candidates) {
+    if (!(await pathExists(directory))) continue;
+    const fileNames = (await fs.readdir(directory)).filter((fileName) => fileName.endsWith(".sql")).sort();
+    if (fileNames.length > 0) return fileNames.map((fileName) => ({ fileName, sourcePath: path.join(directory, fileName) }));
+  }
+  return [];
+}
+
+export async function planMigrationAppends({ targetDir, moduleKeys, catalog, migrationCursor = {} }) {
+  const migrationsDir = await findAppMigrationsDirectory(targetDir);
+  const existing = (await pathExists(migrationsDir))
+    ? (await fs.readdir(migrationsDir)).filter((fileName) => fileName.endsWith(".sql")).sort()
+    : [];
+  let sequence = existing.reduce((maximum, fileName) => {
+    const match = fileName.match(/^(\d+)_/);
+    return Math.max(maximum, Number(match?.[1] || 0));
+  }, 0);
+  const writes = [];
+  const nextCursor = { ...migrationCursor };
+  for (const moduleKey of moduleKeys) {
+    const migrations = await getModuleMigrations(moduleKey, catalog[moduleKey]);
+    const cursor = migrationCursor[moduleKey];
+    const pending = cursor ? migrations.filter((entry) => entry.fileName > cursor) : migrations;
+    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";
+      writes.push({
+        moduleKey,
+        originalFileName: entry.fileName,
+        targetFileName,
+        targetPath: path.join(migrationsDir, targetFileName),
+        content: `-- bw-module: ${moduleKey}@${version} ${entry.fileName}\n${source}`,
+      });
+    }
+    if (migrations.length > 0) nextCursor[moduleKey] = migrations.at(-1).fileName;
+  }
+  return { writes, 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");
+  }
+}
+
+export async function cursorMigrationStatus({ targetDir, moduleKey, cursor, catalogEntry }) {
+  const migrations = await getModuleMigrations(moduleKey, catalogEntry);
+  if (migrations.length === 0) return { shipsMigrations: false, missing: [] };
+  if (!cursor) return { shipsMigrations: true, missing: ["migration cursor"] };
+  const expected = migrations.filter((entry) => entry.fileName <= cursor);
+  const migrationsDir = await findAppMigrationsDirectory(targetDir);
+  const installed = [];
+  if (await pathExists(migrationsDir)) {
+    for (const fileName of await fs.readdir(migrationsDir)) {
+      if (!fileName.endsWith(".sql")) continue;
+      const content = await fs.readFile(path.join(migrationsDir, fileName), "utf8");
+      installed.push({ fileName, content });
+    }
+  }
+  return {
+    shipsMigrations: true,
+    missing: expected.filter((entry) => !installed.some(({ fileName, content }) => {
+      if (fileName === entry.fileName || fileName.endsWith(`_${moduleKey}__${entry.fileName}`)) return true;
+      const header = content.match(/^\s*--\s*bw-module:\s*([^@\s]+)@[^\s]+\s+([^\s]+)/im);
+      return header?.[1] === moduleKey && header?.[2] === entry.fileName;
+    })).map((entry) => entry.fileName),
+  };
+}