create-bw-app 0.7.0 → 0.9.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.local`, `AGENTS.md`, `docs/ai/README.md`, and generated config files for brand and module state
 - 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.7.0",
+  "version": "0.9.0",
   "type": "module",
   "bin": "bin/create-bw-app.mjs",
   "files": [

package/src/constants.mjs

@@ -20,21 +20,18 @@ export const SELECTABLE_MODULES = [
     label: "CRM",
     packageName: "@brightweblabs/module-crm",
     templateFolder: "crm",
-    envKey: "NEXT_PUBLIC_ENABLE_CRM",
   },
   {
     key: "projects",
     label: "Projects",
     packageName: "@brightweblabs/module-projects",
     templateFolder: "projects",
-    envKey: "NEXT_PUBLIC_ENABLE_PROJECTS",
   },
   {
     key: "admin",
     label: "Admin",
     packageName: "@brightweblabs/module-admin",
     templateFolder: "admin",
-    envKey: "NEXT_PUBLIC_ENABLE_ADMIN",
   },
 ];
 

package/src/generator.mjs

@@ -189,7 +189,7 @@ function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
   const notes = [];
 
   if (!selectedModules.includes("admin") && resolvedOrder.includes("admin")) {
-    notes.push("Admin governance stays enabled for platform auth/RBAC even if the admin UI module is not selected.");
+    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) {
@@ -256,13 +256,6 @@ async function getVersionMap(workspaceRoot) {
   return versionMap;
 }
 
-function createModuleFlags(selectedModules) {
-  const selected = new Set(selectedModules);
-  return Object.fromEntries(
-    SELECTABLE_MODULES.map((moduleDefinition) => [moduleDefinition.key, selected.has(moduleDefinition.key)]),
-  );
-}
-
 function createDerivedBrandValues(slug) {
   const projectName = titleizeSlug(slug);
 
@@ -276,7 +269,94 @@ function createDerivedBrandValues(slug) {
   };
 }
 
-function createEnvFileContent({ slug, brandValues, moduleFlags }) {
+function createPlatformBrandConfigFile({ slug, brandValues }) {
+  return [
+    "export type StarterBrandConfig = {",
+    "  companyName: string;",
+    "  productName: string;",
+    "  slug: string;",
+    "  tagline: string;",
+    "  contactEmail: string;",
+    "  supportEmail: string;",
+    "  primaryHex: string;",
+    "};",
+    "",
+    "export const starterBrandConfig: StarterBrandConfig = {",
+    `  companyName: ${JSON.stringify(brandValues.companyName)},`,
+    `  productName: ${JSON.stringify(brandValues.productName)},`,
+    `  slug: ${JSON.stringify(slug)},`,
+    `  tagline: ${JSON.stringify(brandValues.tagline)},`,
+    `  contactEmail: ${JSON.stringify(brandValues.contactEmail)},`,
+    `  supportEmail: ${JSON.stringify(brandValues.supportEmail)},`,
+    `  primaryHex: ${JSON.stringify(brandValues.primaryHex)},`,
+    "};",
+    "",
+  ].join("\n");
+}
+
+function createPlatformModulesConfigFile(selectedModules) {
+  const selected = new Set(selectedModules);
+
+  return [
+    'export type StarterModuleKey = "core-auth" | "crm" | "projects" | "admin";',
+    "",
+    "export type StarterModuleConfig = {",
+    "  key: StarterModuleKey;",
+    "  label: string;",
+    "  description: string;",
+    "  enabled: boolean;",
+    "  packageName: string;",
+    "  playgroundHref?: string;",
+    '  placement: "core" | "primary" | "admin";',
+    "};",
+    "",
+    "export const starterModuleConfig: StarterModuleConfig[] = [",
+    "  {",
+    '    key: "core-auth",',
+    '    label: "Core Auth",',
+    '    description: "Login, reset-password, callback URLs, and shared auth validation utilities.",',
+    "    enabled: true,",
+    '    packageName: "@brightweblabs/core-auth",',
+    '    playgroundHref: "/playground/auth",',
+    '    placement: "core",',
+    "  },",
+    "  {",
+    '    key: "crm",',
+    '    label: "CRM",',
+    '    description: "Contacts, marketing audience, and CRM server/data layer.",',
+    `    enabled: ${String(selected.has("crm"))},`,
+    '    packageName: "@brightweblabs/module-crm",',
+    '    playgroundHref: "/playground/crm",',
+    '    placement: "primary",',
+    "  },",
+    "  {",
+    '    key: "projects",',
+    '    label: "Projects",',
+    '    description: "Project portfolio, detail routes, and work-management server logic.",',
+    `    enabled: ${String(selected.has("projects"))},`,
+    '    packageName: "@brightweblabs/module-projects",',
+    '    playgroundHref: "/playground/projects",',
+    '    placement: "primary",',
+    "  },",
+    "  {",
+    '    key: "admin",',
+    '    label: "Admin",',
+    '    description: "User role governance, admin tools, and access-control surfaces.",',
+    `    enabled: ${String(selected.has("admin"))},`,
+    '    packageName: "@brightweblabs/module-admin",',
+    '    playgroundHref: "/playground/admin",',
+    '    placement: "admin",',
+    "  },",
+    "];",
+    "",
+    "export function getEnabledStarterModules() {",
+    "  return starterModuleConfig.filter((moduleConfig) => moduleConfig.enabled);",
+    "}",
+    "",
+  ].join("\n");
+}
+
+function createEnvFileContent() {
   return [
     "NEXT_PUBLIC_APP_URL=http://localhost:3000",
     "NEXT_PUBLIC_SUPABASE_URL=",
@@ -284,18 +364,6 @@ function createEnvFileContent({ slug, brandValues, moduleFlags }) {
     "SUPABASE_SERVICE_ROLE_KEY=",
     "RESEND_API_KEY=",
     "",
-    `NEXT_PUBLIC_CLIENT_COMPANY_NAME=${brandValues.companyName}`,
-    `NEXT_PUBLIC_CLIENT_PRODUCT_NAME=${brandValues.productName}`,
-    `NEXT_PUBLIC_CLIENT_SLUG=${slug}`,
-    `NEXT_PUBLIC_CLIENT_TAGLINE=${brandValues.tagline}`,
-    `NEXT_PUBLIC_CLIENT_CONTACT_EMAIL=${brandValues.contactEmail}`,
-    `NEXT_PUBLIC_CLIENT_SUPPORT_EMAIL=${brandValues.supportEmail}`,
-    `NEXT_PUBLIC_CLIENT_PRIMARY_HEX=${brandValues.primaryHex}`,
-    "",
-    `NEXT_PUBLIC_ENABLE_CRM=${String(moduleFlags.crm)}`,
-    `NEXT_PUBLIC_ENABLE_PROJECTS=${String(moduleFlags.projects)}`,
-    `NEXT_PUBLIC_ENABLE_ADMIN=${String(moduleFlags.admin)}`,
-    "",
   ].join("\n");
 }
 
@@ -333,9 +401,8 @@ function createGitignore() {
     "yarn-error.log*",
     ".pnpm-debug.log*",
     "",
-    "# env files (can opt-in for committing if needed)",
+    "# env files",
     ".env*",
-    "!.env.example",
     "",
     "# vercel",
     ".vercel",
@@ -363,12 +430,12 @@ function createPlatformReadme({
 
   const localSteps = workspaceMode
     ? [
-        "1. Review `.env.example`, then fill `.env.local` with real service credentials.",
+        "1. Review `.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.local` and fill in real service credentials.",
         `2. Run \`${packageManager} install\`.`,
         `3. Run \`${packageManager} dev\`.`,
       ];
@@ -716,7 +783,7 @@ async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
           "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(" -> ")}.`,
-          "Admin governance stays enabled for platform auth/RBAC even if the admin UI module is not selected.",
+          "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.",
         ],
       },
@@ -871,7 +938,6 @@ async function scaffoldPlatformProject({
   answers,
   dbInstallPlan,
 }) {
-  const moduleFlags = createModuleFlags(selectedModules);
   const brandValues = createDerivedBrandValues(answers.slug);
   const baseTemplateDir = path.join(TEMPLATE_ROOT, "base");
 
@@ -899,11 +965,15 @@ async function scaffoldPlatformProject({
     )}\n`,
   );
   await fs.writeFile(path.join(targetDir, "next.config.ts"), createNextConfig({ template: "platform", selectedModules }));
+  await fs.writeFile(
+    path.join(targetDir, "config", "brand.ts"),
+    createPlatformBrandConfigFile({ slug: answers.slug, brandValues }),
+  );
+  await fs.writeFile(path.join(targetDir, "config", "modules.ts"), createPlatformModulesConfigFile(selectedModules));
   await fs.writeFile(path.join(targetDir, "config", "shell.ts"), createShellConfig(selectedModules));
 
-  const envFileContent = createEnvFileContent({ slug: answers.slug, brandValues, moduleFlags });
+  const envFileContent = createEnvFileContent();
 
-  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(

package/template/base/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+This generated project is a BrightWeb platform starter. Use this file as the local entrypoint for AI agents working inside the app.
+
+## Start here
+
+- `README.md`: local setup commands and starter routes.
+- `docs/ai/README.md`: app-specific routing guide for agents.
+- `config/brand.ts`: client identity, naming, and contact defaults.
+- `config/modules.ts`: selected module set and runtime enablement.
+- `config/client.ts`: starter-facing derived state used by the home page and setup surfaces.
+- `.env.local`: runtime service values for local development.
+
+## Working rules
+
+- Treat `/bootstrap`, `/preview/app-shell`, and `/playground/*` as starter validation surfaces. They are app-owned and can be removed after setup if links and references are cleaned up too.
+- Check `config/modules.ts` before assuming CRM, Projects, or Admin routes exist.
+- Prefer composing app-level routes and config before forking logic from `@brightweblabs/*` packages.
+- Keep edits local to this app unless the change is intentionally shared across multiple BrightWeb projects.
+
+## First validation pass
+
+1. Run the local dev server from this project or workspace.
+2. Open `/`, `/bootstrap`, `/preview/app-shell`, and `/playground/auth`.
+3. If optional modules are enabled, open the matching `/playground/*` route for each one.
+4. Confirm `.env.local` contains real service values before debugging runtime behavior.

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.local` for per-client service credentials and local runtime overrides.</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: "Fill `.env.local` with the real service values for this client.",
       },
     ],
   };

package/template/base/config/brand.ts

@@ -9,13 +9,11 @@ export type StarterBrandConfig = {
 };
 
 export const starterBrandConfig: StarterBrandConfig = {
-  companyName: process.env.NEXT_PUBLIC_CLIENT_COMPANY_NAME?.trim() || "Starter Client",
-  productName: process.env.NEXT_PUBLIC_CLIENT_PRODUCT_NAME?.trim() || "Operations Platform",
-  slug: process.env.NEXT_PUBLIC_CLIENT_SLUG?.trim() || "starter-client",
-  tagline:
-    process.env.NEXT_PUBLIC_CLIENT_TAGLINE?.trim()
-    || "A configurable Brightweb starter app for shipping new client instances without rebuilding the platform.",
-  contactEmail: process.env.NEXT_PUBLIC_CLIENT_CONTACT_EMAIL?.trim() || "hello@example.com",
-  supportEmail: process.env.NEXT_PUBLIC_CLIENT_SUPPORT_EMAIL?.trim() || "support@example.com",
-  primaryHex: process.env.NEXT_PUBLIC_CLIENT_PRIMARY_HEX?.trim() || "#1f7a45",
+  companyName: "Starter Client",
+  productName: "Operations Platform",
+  slug: "starter-client",
+  tagline: "A configurable Brightweb starter app for shipping new client instances without rebuilding the platform.",
+  contactEmail: "hello@example.com",
+  supportEmail: "support@example.com",
+  primaryHex: "#1f7a45",
 };

package/template/base/config/modules.ts

@@ -10,14 +10,6 @@ export type StarterModuleConfig = {
   placement: "core" | "primary" | "admin";
 };
 
-function envFlag(value: string | undefined, defaultValue: boolean) {
-  if (typeof value !== "string") return defaultValue;
-  const normalized = value.trim().toLowerCase();
-  if (["1", "true", "yes", "on"].includes(normalized)) return true;
-  if (["0", "false", "no", "off"].includes(normalized)) return false;
-  return defaultValue;
-}
-
 export const starterModuleConfig: StarterModuleConfig[] = [
   {
     key: "core-auth",
@@ -32,7 +24,7 @@ export const starterModuleConfig: StarterModuleConfig[] = [
     key: "crm",
     label: "CRM",
     description: "Contacts, marketing audience, and CRM server/data layer.",
-    enabled: envFlag(process.env.NEXT_PUBLIC_ENABLE_CRM, true),
+    enabled: true,
     packageName: "@brightweblabs/module-crm",
     playgroundHref: "/playground/crm",
     placement: "primary",
@@ -41,7 +33,7 @@ export const starterModuleConfig: StarterModuleConfig[] = [
     key: "projects",
     label: "Projects",
     description: "Project portfolio, detail routes, and work-management server logic.",
-    enabled: envFlag(process.env.NEXT_PUBLIC_ENABLE_PROJECTS, true),
+    enabled: true,
     packageName: "@brightweblabs/module-projects",
     playgroundHref: "/playground/projects",
     placement: "primary",
@@ -50,7 +42,7 @@ export const starterModuleConfig: StarterModuleConfig[] = [
     key: "admin",
     label: "Admin",
     description: "User role governance, admin tools, and access-control surfaces.",
-    enabled: envFlag(process.env.NEXT_PUBLIC_ENABLE_ADMIN, true),
+    enabled: true,
     packageName: "@brightweblabs/module-admin",
     playgroundHref: "/playground/admin",
     placement: "admin",

package/template/base/docs/ai/README.md

@@ -0,0 +1,44 @@
+# Agent Guide
+
+This file is the local routing guide for AI agents working inside a generated BrightWeb platform app.
+
+It is intentionally app-scoped. It explains the generated project you are in, not the maintainer-only BrightWeb monorepo internals.
+
+## Project shape
+
+This app is a normal Next.js App Router project with BrightWeb runtime wiring layered on top.
+
+- `app/`: route tree, layouts, pages, starter previews, and playground routes.
+- `config/`: generated app configuration for brand, env readiness, enabled modules, bootstrap content, and shell registration.
+- `public/brand/`: starter logos used by the shell lockups.
+- `.env.local`: local service configuration for Supabase, Resend, and runtime URLs.
+
+## Fast routing map
+
+- `README.md`: first-run setup steps.
+- `config/brand.ts`: client name, product name, support inboxes, and brand color.
+- `config/modules.ts`: module metadata and enablement flags for CRM, Projects, and Admin.
+- `config/client.ts`: aggregated state consumed by starter pages.
+- `config/bootstrap.ts`: bootstrap checklist content for `/bootstrap`.
+- `config/shell.ts`: app-shell registration and navigation wiring.
+- `app/page.tsx`: starter landing page for the generated app.
+- `app/bootstrap/page.tsx`: setup checklist surface.
+- `app/preview/app-shell/page.tsx`: shell preview validation route.
+- `app/playground/auth/page.tsx`: auth validation route.
+- `app/playground/*`: optional module playgrounds when those modules were selected at scaffold time.
+
+## Editing strategy
+
+- Change client identity first in `config/brand.ts`.
+- Check module presence in `config/modules.ts` before editing or creating module-specific routes.
+- Use `config/shell.ts` when navigation or toolbar behavior needs to change.
+- Use `config/bootstrap.ts` and `config/client.ts` when the setup checklist or readiness messaging is wrong.
+- Keep starter validation routes until the real product routes replace their purpose.
+
+## Validation checklist
+
+1. Confirm `.env.local` is populated with real values.
+2. Run the app locally.
+3. Validate `/`, `/bootstrap`, `/preview/app-shell`, and `/playground/auth`.
+4. Validate the playground route for each enabled optional module.
+5. If a starter route is removed, also remove any links or config references that still point to it.

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>

package/template/modules/crm/app/api/crm/contacts/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmContactsGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmContactsGetRequest(request);
+}

package/template/modules/crm/app/api/crm/organizations/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmOrganizationsGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmOrganizationsGetRequest(request);
+}

package/template/modules/crm/app/api/crm/owners/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmOwnersGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmOwnersGetRequest(request);
+}

package/template/modules/crm/app/api/crm/stats/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmStatsGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmStatsGetRequest(request);
+}