create-bw-app 0.10.1 → 0.12.0

package/src/bw.mjs

@@ -0,0 +1,55 @@
+import { addBrightwebModule } from "./add.mjs";
+import { adoptBrightwebApp } from "./adopt.mjs";
+import { diffBrightwebScaffold } from "./diff.mjs";
+import { doctorBrightwebApp } from "./doctor.mjs";
+import { removeBrightwebModule } from "./remove.mjs";
+import { scaffoldBrightwebApp } from "./scaffold-cmd.mjs";
+import { updateBrightwebApp } from "./update.mjs";
+import { upgradeBrightwebApp } from "./upgrade.mjs";
+
+const HELP = `Usage: bw <command> [options]\n\nCommands:\n  add <moduleKey>       Install a module and its requirements\n  adopt                 Create an honest manifest for a legacy app\n  diff <relpath>        Compare a tracked scaffold file with its template\n  scaffold <action>     List or record per-file scaffold intent\n  remove <moduleKey>    Conservatively remove module package wiring\n  upgrade [moduleKey]   Upgrade packages, managed files, and migrations\n  update                Alias for the legacy create-bw-app update flow\n  doctor                Validate app health and manifest consistency\n\nRun bw <command> --help for command-specific options.`;
+
+function parseOptions(argv) {
+  const options = {};
+  const positionals = [];
+  const booleanFlags = new Set(["help", "dry-run", "strict", "report", "install", "refresh-starters", "allow-stale-fallback", "allow-uncursored", "force", "list", "yes"]);
+  const repeatableFlags = new Set(["cursor", "owned-surface", "own", "skip"]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) { positionals.push(token); continue; }
+    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (booleanFlags.has(rawKey)) options[key] = true;
+    else {
+      const value = inlineValue ?? argv[index + 1];
+      if (inlineValue == null) index += 1;
+      if (repeatableFlags.has(rawKey)) options[key] = [...(options[key] || []), value];
+      else options[key] = value;
+    }
+  }
+  return { options, positionals };
+}
+
+export async function runBwCli(argv = process.argv.slice(2), runtimeOptions = {}) {
+  const command = argv[0];
+  if (!command || command === "--help" || command === "help") { process.stdout.write(`${HELP}\n`); return; }
+  const { options, positionals } = parseOptions(argv.slice(1));
+  try {
+    if (command === "add") await addBrightwebModule(positionals[0], options, runtimeOptions);
+    else if (command === "adopt") await adoptBrightwebApp(options, runtimeOptions);
+    else if (command === "diff") await diffBrightwebScaffold(positionals[0], options, runtimeOptions);
+    else if (command === "scaffold") await scaffoldBrightwebApp(positionals[0], positionals.slice(1), options, runtimeOptions);
+    else if (command === "remove") await removeBrightwebModule(positionals[0], options, runtimeOptions);
+    else if (command === "upgrade") await upgradeBrightwebApp(positionals[0], options, runtimeOptions);
+    else if (command === "update") await updateBrightwebApp(options, runtimeOptions);
+    else if (command === "doctor") {
+      const result = await doctorBrightwebApp(options, runtimeOptions);
+      if (!result.ok) process.exitCode = 1;
+    } else throw new Error(`Unknown command: ${command}\n\n${HELP}`);
+  } catch (error) {
+    console.error(`\nbw failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+    process.exitCode = 1;
+  }
+}
+
+export { HELP as BW_HELP };

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.3",
-  "@brightweblabs/infra": "^0.3.0",
-  "@brightweblabs/module-admin": "^0.3.2",
-  "@brightweblabs/module-crm": "^0.3.3",
-  "@brightweblabs/module-projects": "^0.3.2",
-  "@brightweblabs/ui": "^0.3.1",
-  "lucide-react": "^0.562.0",
+  "@brightweblabs/app-shell": "^0.4.1",
+  "@brightweblabs/core-auth": "^0.3.4",
+  "@brightweblabs/infra": "^0.3.1",
+  "@brightweblabs/module-admin": "^0.3.5",
+  "@brightweblabs/module-crm": "^0.5.2",
+  "@brightweblabs/module-orgs": "^0.2.2",
+  "@brightweblabs/module-projects": "^0.4.3",
+  "@brightweblabs/theme": "^0.2.1",
+  "@brightweblabs/ui": "^1.0.1",
+  "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",

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,113 @@
+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);
+  const scaffoldGroups = {
+    current: scaffold.entries.filter((entry) => entry.status === "current" && entry.intent !== "skipped"),
+    owned: scaffold.entries.filter((entry) => entry.intent === "owned" && entry.status === "drifted"),
+    skipped: scaffold.entries.filter((entry) => entry.intent === "skipped" && entry.status === "missing"),
+    undecidedDrift: scaffold.entries.filter((entry) => entry.intent === "managed" && entry.status === "drifted"),
+    undecidedMissing: scaffold.entries.filter((entry) => entry.intent === "managed" && entry.status === "missing"),
+    mismatched: scaffold.entries.filter((entry) => (entry.intent === "owned" && entry.status === "missing") || (entry.intent === "skipped" && entry.status !== "missing")),
+  };
+  if (scaffoldGroups.owned.length) add("INFO", "scaffold-owned", `App-owned scaffold files: ${scaffoldGroups.owned.map((entry) => entry.relativePath).join(", ")}.`);
+  if (scaffoldGroups.skipped.length) add("INFO", "scaffold-skipped", `Intentionally skipped scaffold files: ${scaffoldGroups.skipped.map((entry) => entry.relativePath).join(", ")}.`);
+  if (scaffoldGroups.undecidedDrift.length) add("WARN", "scaffold-undecided-drift", `Unacknowledged drift: ${scaffoldGroups.undecidedDrift.map((entry) => entry.relativePath).join(", ")} (use bw scaffold own or bw diff).`);
+  if (scaffoldGroups.undecidedMissing.length) add("WARN", "scaffold-undecided-missing", `Unacknowledged missing files: ${scaffoldGroups.undecidedMissing.map((entry) => entry.relativePath).join(", ")} (use bw scaffold skip after review).`);
+  if (scaffoldGroups.mismatched.length) add("FAIL", "scaffold-intent-mismatch", `Recorded scaffold intent no longer matches reality: ${scaffoldGroups.mismatched.map((entry) => `${entry.relativePath} (${entry.intent}, ${entry.status})`).join(", ")}.`);
+  const scaffoldStatus = scaffoldGroups.mismatched.length ? "FAIL" : scaffoldGroups.undecidedDrift.length || scaffoldGroups.undecidedMissing.length ? "WARN" : "PASS";
+  add(scaffoldStatus, "scaffold", `${scaffoldGroups.current.length} current, ${scaffoldGroups.owned.length} owned, ${scaffoldGroups.skipped.length} skipped, ${scaffoldGroups.undecidedDrift.length} undecided-drift, ${scaffoldGroups.undecidedMissing.length} undecided-missing, ${scaffoldGroups.mismatched.length} intent-mismatch.`);
+  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/", "");
@@ -298,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;",
@@ -309,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[] = [",
@@ -323,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 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",',
     "  },",
     "  {",
@@ -428,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}`),
   ];
 }
 
@@ -639,6 +654,7 @@ export function createAppContextFile({
           "config/client.ts",
           "config/bootstrap.ts",
           "config/shell.ts",
+          "config/shell.overrides.ts",
           ".env.local",
         ],
         appRoutesRoot: "app",
@@ -659,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),
@@ -720,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,
@@ -732,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,
@@ -768,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)) {
@@ -793,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);');
@@ -809,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,",
@@ -820,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",',
@@ -839,6 +871,10 @@ export function createShellConfig(selectedModules) {
     "",
     "export function getStarterShellConfig() {",
     "  const enabledModules = getEnabledStarterModules();",
+    "  const modules = applyShellRegistrationOverrides(",
+    "    getStarterModuleRegistrations(),",
+    "    shellRegistrationOverrides,",
+    "  );",
     "  const shellRegistration: ClientAppShellRegistration<ShellContextualAction> = {",
     "    brand: {",
     '      href: "/",',
@@ -866,7 +902,7 @@ export function createShellConfig(selectedModules) {
     "      icon: Wrench,",
     '      collapsedHref: enabledModules.find((moduleConfig) => moduleConfig.playgroundHref)?.playgroundHref || "/",',
     "    },",
-    "    modules: getStarterModuleRegistrations(),",
+    "    modules,",
     "  };",
     "",
     "  const builtRegistration = buildClientAppShellRegistration(shellRegistration);",
@@ -1255,6 +1291,7 @@ async function scaffoldPlatformProject({
 
   if (workspaceMode) {
     await writeClientStack(workspaceRoot, answers.slug, dbInstallPlan, { workspaceMode: true });
+    await writeSupabaseCliMigrations({ targetDir, dbInstallPlan });
   } else {
     await writeBundledSupabaseBaseline({
       targetDir,
@@ -1263,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({
@@ -1314,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),
+  };
+}