create-bw-app 0.6.0 → 0.8.0

package/README.md

@@ -1,22 +1,26 @@
 # create-bw-app
 
-Create a new BrightWeb app from either the platform or site starter.
+Scaffold a new BrightWeb app from either the `platform` or `site` starter.
 
-## Local workspace usage
+## Workspace usage
 
 From the BrightWeb platform repo root:
 
 ```bash
 pnpm create:client
+pnpm create:client -- --help
 pnpm create:client -- --template site
 ```
 
-## Future published usage
+The workspace wrapper delegates to this package with `workspace:*` dependency wiring and BrightWeb-specific output rules.
+
+## Published usage
 
 Once this package is published to npm:
 
 ```bash
 pnpm dlx create-bw-app
+pnpm dlx create-bw-app --template site
 npm create bw-app@latest
 ```
 
@@ -24,11 +28,30 @@ npm create bw-app@latest
 
 - prompts for app type: `platform` or `site`
 - prompts for project name
-- prompts for optional modules with a checkbox list when using the platform template
+- prompts for optional platform modules: `admin`, `crm`, and `projects`
 - prompts to install dependencies immediately
-- copies a clean Next.js starter template
-- platform apps include BrightWeb auth, shell, and optional business modules
-- site apps include Next.js, Tailwind CSS, and local shadcn-style component primitives
+- copies a clean Next.js App Router starter template
+- platform apps include BrightWeb auth, shell wiring, and optional module starter surfaces
+- 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.example` and `.env.local`
+- platform apps also write `.env.example`, generated config files, and module feature flags
 - supports repo-local `workspace:*` wiring and future published dependency wiring
+
+## Workspace mode extras
+
+When this package runs in BrightWeb workspace mode, it can:
+
+- write the new app under `apps/<slug>`
+- keep internal dependencies on `workspace:*`
+- create `supabase/clients/<slug>/stack.json`
+- create a client-only migrations folder so database planning stays aligned with scaffolded modules
+
+Platform mode always resolves to the `Core + Admin` database baseline. Selecting `admin` affects the Admin starter UI and package wiring, not whether the Admin database layer exists.
+
+## Related references
+
+- `packages/create-bw-app/src/generator.mjs`
+- `packages/create-bw-app/src/constants.mjs`
+- `packages/create-bw-app/template/base`
+- `packages/create-bw-app/template/site/base`
+- `packages/create-bw-app/template/modules`

package/package.json

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

package/src/generator.mjs

@@ -19,6 +19,14 @@ import {
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
 const TEMPLATE_KEY_SET = new Set(TEMPLATE_OPTIONS.map((templateOption) => templateOption.key));
+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"] },
+  },
+};
 
 function slugify(value) {
   return value
@@ -103,6 +111,113 @@ async function readJsonIfPresent(filePath) {
   return JSON.parse(await fs.readFile(filePath, "utf8"));
 }
 
+async function getDbModuleRegistry(workspaceRoot) {
+  if (!workspaceRoot) {
+    return DEFAULT_DB_MODULE_REGISTRY;
+  }
+
+  const registryPath = path.join(workspaceRoot, "supabase", "module-registry.json");
+  return (await readJsonIfPresent(registryPath)) || DEFAULT_DB_MODULE_REGISTRY;
+}
+
+function resolveModuleOrder(registry, enabledModules) {
+  const resolved = [];
+  const visited = new Set();
+  const visiting = new Set();
+
+  function visit(moduleKey) {
+    if (visited.has(moduleKey)) return;
+    if (visiting.has(moduleKey)) {
+      throw new Error(`Circular module dependency detected at "${moduleKey}".`);
+    }
+
+    const moduleConfig = registry.modules?.[moduleKey];
+    if (!moduleConfig) {
+      throw new Error(`Unknown database module "${moduleKey}".`);
+    }
+
+    visiting.add(moduleKey);
+    for (const dependency of moduleConfig.dependsOn || []) {
+      visit(dependency);
+    }
+    visiting.delete(moduleKey);
+    visited.add(moduleKey);
+    resolved.push(moduleKey);
+  }
+
+  for (const moduleKey of enabledModules) {
+    visit(moduleKey);
+  }
+
+  return resolved;
+}
+
+function getSelectedModuleLabels(selectedModules) {
+  return selectedModules.map((moduleKey) => {
+    return getModuleLabel(moduleKey);
+  });
+}
+
+function getModuleLabel(moduleKey) {
+  const moduleDefinition = SELECTABLE_MODULES.find((candidate) => candidate.key === moduleKey);
+  if (moduleDefinition) {
+    return moduleDefinition.label;
+  }
+
+  if (moduleKey === "core") {
+    return "Core";
+  }
+
+  return titleizeSlug(moduleKey);
+}
+
+function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
+  if (!workspaceMode) {
+    return {
+      selectedLabels: getSelectedModuleLabels(selectedModules),
+      resolvedOrder: [],
+      notes: [],
+    };
+  }
+
+  const requestedModules = Array.from(new Set(["core", ...selectedModules]));
+  if (!requestedModules.includes("admin")) {
+    requestedModules.push("admin");
+  }
+
+  const resolvedOrder = resolveModuleOrder(registry, requestedModules);
+  const notes = [];
+
+  if (!selectedModules.includes("admin") && resolvedOrder.includes("admin")) {
+    notes.push("Platform always resolves to the Core + Admin database baseline; selecting Admin only controls whether the Admin starter UI and package wiring are scaffolded.");
+  }
+
+  for (const moduleKey of resolvedOrder) {
+    if (moduleKey === "core" || selectedModules.includes(moduleKey) || moduleKey === "admin") {
+      continue;
+    }
+
+    const dependents = resolvedOrder.filter((candidateKey) => {
+      const dependencyList = registry.modules?.[candidateKey]?.dependsOn || [];
+      return dependencyList.includes(moduleKey);
+    });
+
+    if (dependents.length === 0) continue;
+
+    const dependentLabels = dependents
+      .map((candidateKey) => registry.modules?.[candidateKey]?.label || getModuleLabel(candidateKey))
+      .join(", ");
+    const moduleLabel = registry.modules?.[moduleKey]?.label || getModuleLabel(moduleKey);
+    notes.push(`${moduleLabel} is included because ${dependentLabels} depends on it.`);
+  }
+
+  return {
+    selectedLabels: getSelectedModuleLabels(selectedModules),
+    resolvedOrder,
+    notes,
+  };
+}
+
 async function getVersionMap(workspaceRoot) {
   const versionMap = {
     ...APP_DEPENDENCY_DEFAULTS,
@@ -237,20 +352,23 @@ function createPlatformReadme({
   selectedModules,
   workspaceMode,
   packageManager,
+  dbInstallPlan,
 }) {
   const moduleLines = SELECTABLE_MODULES.map((moduleDefinition) => {
     const enabled = selectedModules.includes(moduleDefinition.key);
     return `- ${moduleDefinition.key}: ${enabled ? "enabled" : "disabled"}`;
   });
+  const resolvedDbStackLines = dbInstallPlan.resolvedOrder.map((moduleKey) => `- ${getModuleLabel(moduleKey)}`);
+  const dependencyNotes = dbInstallPlan.notes.map((note) => `- ${note}`);
 
   const localSteps = workspaceMode
     ? [
-        "1. Review `.env.example`, then fill `.env.local` with real service credentials.",
+        "1. Review `.env.example`, then copy it to `.env.local` and fill in real service credentials.",
         "2. Run `pnpm install` from the BrightWeb workspace root.",
         `3. Run \`pnpm --filter ${slug} dev\`.`,
       ]
     : [
-        "1. Review `.env.example`, then fill `.env.local` with real service credentials.",
+        "1. Review `.env.example`, then copy it to `.env.local` and fill in real service credentials.",
         `2. Run \`${packageManager} install\`.`,
         `3. Run \`${packageManager} dev\`.`,
       ];
@@ -268,6 +386,22 @@ function createPlatformReadme({
     "",
     ...moduleLines,
     "",
+    ...(workspaceMode
+      ? [
+          "## Resolved database stack",
+          "",
+          ...resolvedDbStackLines,
+          "",
+          ...(dependencyNotes.length > 0
+            ? [
+                "## Dependency notes",
+                "",
+                ...dependencyNotes,
+                "",
+              ]
+            : []),
+        ]
+      : []),
     "## Starter routes",
     "",
     "- `/`",
@@ -548,6 +682,50 @@ async function ensureDirectory(targetDir) {
   await fs.mkdir(targetDir, { recursive: true });
 }
 
+async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
+  const clientDir = path.join(workspaceRoot, "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)) {
+    throw new Error(`Client stack already exists: ${stackPath}`);
+  }
+
+  await ensureDirectory(migrationsDir);
+  await fs.writeFile(path.join(migrationsDir, ".gitkeep"), "", "utf8");
+  await fs.writeFile(
+    stackPath,
+    `${JSON.stringify(
+      {
+        client: {
+          slug,
+          label: titleizeSlug(slug),
+        },
+        historyMode: "greenfield-modular",
+        futureMode: "forward-only-modular",
+        enabledModules,
+        clientMigrationPath: `supabase/clients/${slug}/migrations`,
+        notes: [
+          "Generated by create-bw-app in workspace 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.",
+          "The database install order is resolved from supabase/module-registry.json.",
+        ],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
 async function runInstall(command, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, ["install"], {
@@ -568,15 +746,36 @@ async function runInstall(command, cwd) {
   });
 }
 
-function renderPlanSummary({ targetDir, dependencyMode, selectedModules, packageManager, workspaceMode, install, template }) {
+function renderPlanSummary({
+  targetDir,
+  dependencyMode,
+  selectedModules,
+  packageManager,
+  workspaceMode,
+  install,
+  template,
+  dbInstallPlan,
+}) {
   const installLocation = workspaceMode ? "workspace root" : "project directory";
   const templateLabel = TEMPLATE_OPTIONS.find((templateOption) => templateOption.key === template)?.label || template;
+  const selectedModuleSummary =
+    template === "platform"
+      ? dbInstallPlan.selectedLabels.length > 0
+        ? dbInstallPlan.selectedLabels.join(", ")
+        : "none"
+      : "n/a";
 
   return [
     `Template: ${templateLabel}`,
     `Target directory: ${targetDir}`,
     `Dependency mode: ${dependencyMode}`,
-    `Selected modules: ${template === "platform" ? (selectedModules.length > 0 ? selectedModules.join(", ") : "none") : "n/a"}`,
+    `Selected modules: ${selectedModuleSummary}`,
+    ...(template === "platform" && workspaceMode
+      ? [
+          `Resolved database stack: ${dbInstallPlan.resolvedOrder.map((moduleKey) => getModuleLabel(moduleKey)).join(" -> ")}`,
+          ...dbInstallPlan.notes.map((note) => `- ${note}`),
+        ]
+      : []),
     `Install dependencies: ${install ? `yes (${packageManager} in ${installLocation})` : "no"}`,
   ].join("\n");
 }
@@ -668,7 +867,9 @@ async function scaffoldPlatformProject({
   dependencyMode,
   packageManager,
   workspaceMode,
+  workspaceRoot,
   answers,
+  dbInstallPlan,
 }) {
   const moduleFlags = createModuleFlags(selectedModules);
   const brandValues = createDerivedBrandValues(answers.slug);
@@ -703,7 +904,6 @@ async function scaffoldPlatformProject({
   const envFileContent = createEnvFileContent({ slug: answers.slug, brandValues, moduleFlags });
 
   await fs.writeFile(path.join(targetDir, ".env.example"), envFileContent);
-  await fs.writeFile(path.join(targetDir, ".env.local"), envFileContent);
   await fs.writeFile(path.join(targetDir, ".gitignore"), createGitignore());
   await fs.writeFile(
     path.join(targetDir, "README.md"),
@@ -712,8 +912,13 @@ async function scaffoldPlatformProject({
       selectedModules,
       workspaceMode,
       packageManager,
+      dbInstallPlan,
     }),
   );
+
+  if (workspaceMode) {
+    await writeWorkspaceClientStack(workspaceRoot, answers.slug, selectedModules);
+  }
 }
 
 async function scaffoldSiteProject({
@@ -799,6 +1004,12 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
   }
 
   const versionMap = await getVersionMap(workspaceRoot);
+  const dbModuleRegistry = await getDbModuleRegistry(workspaceRoot);
+  const dbInstallPlan = createDbInstallPlan({
+    selectedModules: answers.selectedModules,
+    workspaceMode,
+    registry: dbModuleRegistry,
+  });
   const install = answers.install && !argvOptions.dryRun;
 
   if (argvOptions.dryRun) {
@@ -810,6 +1021,7 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
       workspaceMode,
       install: answers.install,
       template: answers.template,
+      dbInstallPlan,
     })}\n\n`);
     return {
       answers,
@@ -821,6 +1033,17 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
     };
   }
 
+  output.write(`${renderPlanSummary({
+    targetDir,
+    dependencyMode,
+    selectedModules: answers.selectedModules,
+    packageManager,
+    workspaceMode,
+    install: answers.install,
+    template: answers.template,
+    dbInstallPlan,
+  })}\n\n`);
+
   if (answers.template === "site") {
     await scaffoldSiteProject({
       targetDir,
@@ -838,7 +1061,9 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
       dependencyMode,
       packageManager,
       workspaceMode,
+      workspaceRoot,
       answers,
+      dbInstallPlan,
     });
   }
 

package/template/base/app/page.tsx

@@ -115,7 +115,7 @@ export default function HomePage() {
                 <li>`config/brand.ts` for client identity and contact details.</li>
                 <li>`config/modules.ts` for enabled platform modules.</li>
                 <li>`config/env.ts` for infra requirements and readiness checks.</li>
-                <li>`.env.local` from `.env.example` for per-client secrets and flags.</li>
+                <li>`.env.example` for starter defaults; copy it to `.env.local` for per-client secrets and flags.</li>
               </ul>
             </div>
           </article>

package/template/base/config/bootstrap.ts

@@ -69,7 +69,7 @@ export function getStarterBootstrapChecklist() {
       {
         label: "Create per-client environment variables",
         done: config.envReadiness.allReady,
-        detail: "Copy `.env.example` into `.env.local` and fill the real values.",
+        detail: "Copy `.env.example` to `.env.local` and fill the real values.",
       },
     ],
   };

package/template/modules/admin/app/playground/admin/page.tsx

@@ -20,7 +20,7 @@ export default async function AdminPlaygroundPage() {
             <p className="eyebrow">Admin Module</p>
             <h1>Admin users and roles playground</h1>
             <p className="muted">
-              This route previews the shared admin governance module without relying on the BeGreen client app.
+              This route previews the shared admin governance module without relying on any client-specific app.
             </p>
           </div>
         </article>