create-bw-app 0.8.0 → 0.9.0

package/README.md

@@ -34,7 +34,7 @@ npm create bw-app@latest
 - 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`, generated config files, and module feature flags
+- 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.8.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

@@ -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 copy it to `.env.local` and fill in 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 copy it to `.env.local` and fill in real service credentials.",
+        "1. Review `.env.local` and fill in real service credentials.",
         `2. Run \`${packageManager} install\`.`,
         `3. Run \`${packageManager} dev\`.`,
       ];
@@ -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,16 @@ 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(
     path.join(targetDir, "README.md"),

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.example` for starter defaults; copy it to `.env.local` 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` to `.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/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);
+}