create-bw-app 0.9.5 → 0.9.6

package/README.md

@@ -57,6 +57,7 @@ Current updater behavior:
 - copies a clean Next.js App Router starter template
 - platform apps include BrightWeb auth, shell wiring, and optional module starter surfaces
 - platform apps include a local `components/` folder for app-owned UI alongside the shared BrightWeb packages
+- platform apps in published mode also write `supabase/module-registry.json`, `supabase/clients/<slug>/stack.json`, and the resolved shared SQL migrations under `supabase/modules/<module>/migrations`
 - site apps include Next.js, Tailwind CSS v4, and local component primitives
 - writes `package.json`, `next.config.ts`, `.gitignore`, and `README.md` for both templates
 - platform apps also write `.env.local`, `AGENTS.md`, `docs/ai/README.md`, `docs/ai/examples.md`, `docs/ai/app-context.json`, and generated config files for brand and module state
@@ -81,3 +82,4 @@ Platform mode always resolves to the `Core + Admin` database baseline. Selecting
 - `packages/create-bw-app/template/base`
 - `packages/create-bw-app/template/site/base`
 - `packages/create-bw-app/template/modules`
+- `packages/create-bw-app/template/supabase`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.9.5",
+  "version": "0.9.6",
   "type": "module",
   "bin": "bin/create-bw-app.mjs",
   "files": [

package/src/generator.mjs

@@ -18,6 +18,7 @@ import {
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
+const TEMPLATE_SUPABASE_ROOT = path.join(TEMPLATE_ROOT, "supabase");
 const TEMPLATE_KEY_SET = new Set(TEMPLATE_OPTIONS.map((templateOption) => templateOption.key));
 const DEFAULT_DB_MODULE_REGISTRY = {
   modules: {
@@ -112,12 +113,22 @@ export async function readJsonIfPresent(filePath) {
 }
 
 export async function getDbModuleRegistry(workspaceRoot) {
-  if (!workspaceRoot) {
-    return DEFAULT_DB_MODULE_REGISTRY;
+  const candidatePaths = [];
+
+  if (workspaceRoot) {
+    candidatePaths.push(path.join(workspaceRoot, "supabase", "module-registry.json"));
+  }
+
+  candidatePaths.push(path.join(TEMPLATE_SUPABASE_ROOT, "module-registry.json"));
+
+  for (const registryPath of candidatePaths) {
+    const registry = await readJsonIfPresent(registryPath);
+    if (registry) {
+      return registry;
+    }
   }
 
-  const registryPath = path.join(workspaceRoot, "supabase", "module-registry.json");
-  return (await readJsonIfPresent(registryPath)) || DEFAULT_DB_MODULE_REGISTRY;
+  return DEFAULT_DB_MODULE_REGISTRY;
 }
 
 function resolveModuleOrder(registry, enabledModules) {
@@ -172,20 +183,14 @@ function getModuleLabel(moduleKey) {
 }
 
 export function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
-  if (!workspaceMode) {
-    return {
-      selectedLabels: getSelectedModuleLabels(selectedModules),
-      resolvedOrder: [],
-      notes: [],
-    };
-  }
-
+  void workspaceMode;
+  const activeRegistry = registry?.modules ? registry : DEFAULT_DB_MODULE_REGISTRY;
   const requestedModules = Array.from(new Set(["core", ...selectedModules]));
   if (!requestedModules.includes("admin")) {
     requestedModules.push("admin");
   }
 
-  const resolvedOrder = resolveModuleOrder(registry, requestedModules);
+  const resolvedOrder = resolveModuleOrder(activeRegistry, requestedModules);
   const notes = [];
 
   if (!selectedModules.includes("admin") && resolvedOrder.includes("admin")) {
@@ -198,16 +203,16 @@ export function createDbInstallPlan({ selectedModules, workspaceMode, registry }
     }
 
     const dependents = resolvedOrder.filter((candidateKey) => {
-      const dependencyList = registry.modules?.[candidateKey]?.dependsOn || [];
+      const dependencyList = activeRegistry.modules?.[candidateKey]?.dependsOn || [];
       return dependencyList.includes(moduleKey);
     });
 
     if (dependents.length === 0) continue;
 
     const dependentLabels = dependents
-      .map((candidateKey) => registry.modules?.[candidateKey]?.label || getModuleLabel(candidateKey))
+      .map((candidateKey) => activeRegistry.modules?.[candidateKey]?.label || getModuleLabel(candidateKey))
       .join(", ");
-    const moduleLabel = registry.modules?.[moduleKey]?.label || getModuleLabel(moduleKey);
+    const moduleLabel = activeRegistry.modules?.[moduleKey]?.label || getModuleLabel(moduleKey);
     notes.push(`${moduleLabel} is included because ${dependentLabels} depends on it.`);
   }
 
@@ -467,20 +472,22 @@ function createPlatformReadme({
     "",
     ...moduleLines,
     "",
+    "## Resolved database stack",
+    "",
+    ...resolvedDbStackLines,
+    "",
     ...(workspaceMode
+      ? []
+      : [
+          "Bundled Supabase SQL migrations live under `supabase/modules/<module>/migrations`.",
+          "",
+        ]),
+    ...(dependencyNotes.length > 0
       ? [
-          "## Resolved database stack",
+          "## Dependency notes",
           "",
-          ...resolvedDbStackLines,
+          ...dependencyNotes,
           "",
-          ...(dependencyNotes.length > 0
-            ? [
-                "## Dependency notes",
-                "",
-                ...dependencyNotes,
-                "",
-              ]
-            : []),
         ]
       : []),
     "## Starter routes",
@@ -894,20 +901,34 @@ async function copyDirectory(sourceDir, targetDir) {
   await fs.cp(sourceDir, targetDir, { recursive: true });
 }
 
+async function copyFileIfPresent(sourcePath, targetPath) {
+  if (!(await pathExists(sourcePath))) {
+    return;
+  }
+
+  await ensureDirectory(path.dirname(targetPath));
+  await fs.copyFile(sourcePath, targetPath);
+}
+
 export async function ensureDirectory(targetDir) {
   await fs.mkdir(targetDir, { recursive: true });
 }
 
-async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
-  const clientDir = path.join(workspaceRoot, "supabase", "clients", slug);
+function createScopedDbModuleRegistry(registry, moduleKeys) {
+  return {
+    modules: Object.fromEntries(
+      moduleKeys
+        .map((moduleKey) => [moduleKey, registry.modules?.[moduleKey]])
+        .filter(([, moduleConfig]) => Boolean(moduleConfig)),
+    ),
+  };
+}
+
+async function writeClientStack(baseRoot, slug, dbInstallPlan, options = {}) {
+  const generatedInWorkspaceMode = options.workspaceMode === true;
+  const clientDir = path.join(baseRoot, "supabase", "clients", slug);
   const stackPath = path.join(clientDir, "stack.json");
   const migrationsDir = path.join(clientDir, "migrations");
-  const registry = await getDbModuleRegistry(workspaceRoot);
-  const dbInstallPlan = createDbInstallPlan({
-    selectedModules,
-    workspaceMode: true,
-    registry,
-  });
   const enabledModules = dbInstallPlan.resolvedOrder;
 
   if (await pathExists(stackPath)) {
@@ -929,7 +950,9 @@ async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
         enabledModules,
         clientMigrationPath: `supabase/clients/${slug}/migrations`,
         notes: [
-          "Generated by create-bw-app in workspace mode.",
+          generatedInWorkspaceMode
+            ? "Generated by create-bw-app in workspace mode."
+            : "Generated by create-bw-app in published mode.",
           `Selected app modules: ${dbInstallPlan.selectedLabels.length > 0 ? dbInstallPlan.selectedLabels.join(", ") : "none"}.`,
           `Resolved database stack: ${enabledModules.map((moduleKey) => getModuleLabel(moduleKey)).join(" -> ")}.`,
           "Platform always resolves to the Core + Admin database baseline; selecting Admin only controls whether the Admin starter UI and package wiring are scaffolded.",
@@ -942,6 +965,38 @@ async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
   );
 }
 
+async function writeBundledSupabaseBaseline({ targetDir, slug, dbInstallPlan, registry }) {
+  const shippedModuleKeys = dbInstallPlan.resolvedOrder;
+  if (shippedModuleKeys.length === 0) {
+    return;
+  }
+
+  const targetSupabaseDir = path.join(targetDir, "supabase");
+  const targetModulesDir = path.join(targetSupabaseDir, "modules");
+  const scopedRegistry = createScopedDbModuleRegistry(registry, shippedModuleKeys);
+
+  await ensureDirectory(targetModulesDir);
+  await copyFileIfPresent(path.join(TEMPLATE_SUPABASE_ROOT, "README.md"), path.join(targetSupabaseDir, "README.md"));
+  await copyFileIfPresent(
+    path.join(TEMPLATE_SUPABASE_ROOT, "clients", "README.md"),
+    path.join(targetSupabaseDir, "clients", "README.md"),
+  );
+  await fs.writeFile(
+    path.join(targetSupabaseDir, "module-registry.json"),
+    `${JSON.stringify(scopedRegistry, null, 2)}\n`,
+    "utf8",
+  );
+
+  for (const moduleKey of shippedModuleKeys) {
+    await copyDirectory(
+      path.join(TEMPLATE_SUPABASE_ROOT, "modules", moduleKey),
+      path.join(targetModulesDir, moduleKey),
+    );
+  }
+
+  await writeClientStack(targetDir, slug, dbInstallPlan);
+}
+
 export async function runInstall(command, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, ["install"], {
@@ -1086,6 +1141,7 @@ async function scaffoldPlatformProject({
   workspaceRoot,
   answers,
   dbInstallPlan,
+  dbRegistry,
 }) {
   const brandValues = createDerivedBrandValues(answers.slug);
   const baseTemplateDir = path.join(TEMPLATE_ROOT, "base");
@@ -1146,7 +1202,14 @@ async function scaffoldPlatformProject({
   );
 
   if (workspaceMode) {
-    await writeWorkspaceClientStack(workspaceRoot, answers.slug, selectedModules);
+    await writeClientStack(workspaceRoot, answers.slug, dbInstallPlan, { workspaceMode: true });
+  } else {
+    await writeBundledSupabaseBaseline({
+      targetDir,
+      slug: answers.slug,
+      dbInstallPlan,
+      registry: dbRegistry,
+    });
   }
 }
 
@@ -1301,6 +1364,7 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
       workspaceRoot,
       answers,
       dbInstallPlan,
+      dbRegistry: dbModuleRegistry,
     });
   }
 

package/template/supabase/README.md

@@ -0,0 +1,74 @@
+# Brightweb Supabase Structure
+
+This directory is the canonical home for the Brightweb database baseline and its forward migrations.
+
+## Directory map
+
+- `module-registry.json`: shared module dependency graph and migration source paths
+- `modules/core`: always-on platform foundations
+- `modules/admin`: RBAC and privileged governance behavior
+- `modules/crm`: organizations, CRM contacts, and invitation flows
+- `modules/projects`: project and work-management data
+- `clients/<client-slug>`: true client-only schema deltas plus the client stack plan
+- `.generated/<client-slug>`: materialized Supabase workdirs produced by `pnpm db:materialize`
+
+## Ownership rule
+
+Shared database changes should be authored by ownership area, not by client app:
+
+- `core` is applied to every client
+- shared module migrations are applied only when that module is enabled for the client
+- client-specific migrations are the exception, not the default
+
+In workspace scaffold mode, `create-bw-app` writes `supabase/clients/<slug>/stack.json` so the generated app modules and the database install plan stay aligned.
+
+The module baselines in this repo are the canonical Brightweb v1 install path. Future schema work should extend them with forward migrations instead of carrying historical cleanup sequences.
+
+Maintainer references:
+
+- `docs/internal/architecture/database-module-migration-structure.md`
+- `docs/internal/architecture/database-migration-authoring-workflow.md`
+- `docs/internal/architecture/database-migration-safety-policy.md`
+
+## Authoring workflow
+
+Create a new shared module migration:
+
+```bash
+pnpm db:new core profile_notification_cursor
+pnpm db:new admin role_change_guard
+pnpm db:new crm organization_invite_expiry
+pnpm db:new projects task_due_date_index
+```
+
+Create a client-only migration:
+
+```bash
+pnpm db:new client:acme bespoke_reporting_table
+```
+
+Print the effective apply order for a client:
+
+```bash
+pnpm db:plan acme
+```
+
+Materialize an installable Supabase workdir for a client stack:
+
+```bash
+pnpm db:materialize acme
+```
+
+This writes a generated workdir under `supabase/.generated/<client-slug>` with:
+
+- ordered migrations merged from `core`, enabled modules, and client-only deltas
+- a generated `config.toml`
+- a `manifest.json` showing the source file for each materialized migration
+
+## Related READMEs
+
+- `supabase/modules/core/README.md`
+- `supabase/modules/admin/README.md`
+- `supabase/modules/crm/README.md`
+- `supabase/modules/projects/README.md`
+- `supabase/clients/README.md`

package/template/supabase/clients/README.md

@@ -0,0 +1,19 @@
+# Client-Specific Migrations
+
+This directory is reserved for true client-only schema deltas.
+
+## Rule
+
+Only place SQL here when the change:
+
+- cannot be reused by other clients
+- should not be part of a shared module
+- is intentionally isolated to a single client deployment
+
+## Expected shape
+
+- `clients/<slug>/...`
+
+Temporary smoke-test client stacks should be removed after generator verification. This directory is for real client-specific deltas only.
+
+If a client-specific migration later proves reusable, move the concept into the appropriate shared module and stop extending the client-only path.

package/template/supabase/module-registry.json

@@ -0,0 +1,28 @@
+{
+  "modules": {
+    "core": {
+      "label": "Core",
+      "path": "supabase/modules/core/migrations",
+      "dependsOn": [],
+      "description": "Shared auth/profile, events, rate limits, and always-on platform foundations."
+    },
+    "admin": {
+      "label": "Admin",
+      "path": "supabase/modules/admin/migrations",
+      "dependsOn": ["core"],
+      "description": "RBAC, user governance, and privileged role-management behavior."
+    },
+    "crm": {
+      "label": "CRM",
+      "path": "supabase/modules/crm/migrations",
+      "dependsOn": ["core", "admin"],
+      "description": "Organizations, CRM contacts, org membership, and invitation flows."
+    },
+    "projects": {
+      "label": "Projects",
+      "path": "supabase/modules/projects/migrations",
+      "dependsOn": ["core", "admin", "crm"],
+      "description": "Projects, tasks, milestones, members, links, and project activity policies."
+    }
+  }
+}

package/template/supabase/modules/admin/README.md

@@ -0,0 +1,18 @@
+# Admin Migrations
+
+`admin` owns user governance, RBAC, and privileged role-management behavior.
+
+## Owns
+
+- `roles`
+- `user_role_assignments`
+- `role_change_audit`
+- admin-only helper functions like `admin_set_user_role(...)`
+- privileged profile-field guards
+- default role-assignment triggers/backfills
+
+## Dependency
+
+Depends on:
+
+- `core` (`profiles`, `current_profile_id()`, auth linkage)

package/template/supabase/modules/admin/migrations/.gitkeep

@@ -0,0 +1 @@
+