create-bw-app 0.3.0

package/template/base/app/page.tsx

@@ -0,0 +1,144 @@
+import Link from "next/link";
+import { getStarterClientConfig } from "../config/client";
+
+export default function HomePage() {
+  const config = getStarterClientConfig();
+
+  return (
+    <main className="shell starter-home">
+      <div className="frame">
+        <section className="starter-hero">
+          <div className="starter-hero-copy">
+            <span className="eyebrow">{config.brand.companyName}</span>
+            <h1 className="title">{config.brand.productName}</h1>
+            <p className="lead">{config.brand.tagline}</p>
+            <div className="actions">
+              <Link href="/preview/app-shell" className="action">Preview App Shell</Link>
+              <Link href="/bootstrap" className="action secondary">Open Bootstrap Checklist</Link>
+              <Link href="/playground/auth" className="action secondary">Open Module Playgrounds</Link>
+            </div>
+          </div>
+
+          <div className="starter-hero-card panel">
+            <div className="panel-inner">
+              <p className={`status ${config.envReadiness.allReady ? "ok" : "warn"}`}>
+                {config.envReadiness.allReady ? "Starter ready" : "Setup in progress"}
+              </p>
+              <div className="starter-stat-grid">
+                <div>
+                  <span className="stat-number">{config.enabledModules.length}</span>
+                  <p className="muted">enabled modules</p>
+                </div>
+                <div>
+                  <span className="stat-number">{config.envStatus.filter((item) => item.present).length}</span>
+                  <p className="muted">configured env keys</p>
+                </div>
+              </div>
+              <div className="starter-hero-note">
+                <strong>What this template gives you</strong>
+                <p className="muted">
+                  One place to brand, provision, preview, and validate a new client before the first deployment.
+                </p>
+              </div>
+            </div>
+          </div>
+        </section>
+
+        <section className="grid starter-signal-grid">
+          <article className="panel preview-glass-card">
+            <div className="panel-inner">
+              <p className="eyebrow">Brand</p>
+              <h2>{config.brand.companyName}</h2>
+              <p className="muted">{config.brand.contactEmail} · {config.brand.supportEmail}</p>
+              <p className="package-name">{config.brand.slug}</p>
+            </div>
+          </article>
+
+          <article className="panel preview-glass-card">
+            <div className="panel-inner">
+              <p className="eyebrow">Infrastructure</p>
+              <h2>{config.envReadiness.allReady ? "Ready to validate" : "Needs provisioning"}</h2>
+              <p className="muted">
+                {config.envReadiness.allReady
+                  ? "Core env and service wiring are present."
+                  : `${config.envReadiness.missing.length} required environment key(s) are still missing.`}
+              </p>
+            </div>
+          </article>
+        </section>
+
+        <section className="panel" style={{ marginTop: 18 }}>
+          <div className="panel-inner">
+            <h2>Enabled platform modules</h2>
+            <div className="grid">
+              {config.enabledModules.map((moduleConfig) => (
+                <article key={moduleConfig.key} className="panel preview-glass-card" style={{ background: "rgba(255,255,255,0.72)" }}>
+                  <div className="panel-inner">
+                    <p className={`status ${moduleConfig.enabled ? "ok" : "warn"}`}>{moduleConfig.placement}</p>
+                    <h3>{moduleConfig.label}</h3>
+                    <p className="muted">{moduleConfig.description}</p>
+                    <p className="package-name">{moduleConfig.packageName}</p>
+                    {moduleConfig.playgroundHref ? (
+                      <Link href={moduleConfig.playgroundHref} className="inline-link">
+                        Open module playground
+                      </Link>
+                    ) : null}
+                  </div>
+                </article>
+              ))}
+            </div>
+          </div>
+        </section>
+
+        <section className="grid" style={{ marginTop: 18 }}>
+          <article className="panel preview-glass-card">
+            <div className="panel-inner">
+              <h2>App-shell surfaces</h2>
+              <ul className="list">
+                {config.shellPreview.primaryNav.map((item) => (
+                  <li key={item.href}>{item.label} · {item.href}</li>
+                ))}
+                {config.shellPreview.moduleGroups.map((group) => (
+                  <li key={group.key}>
+                    {group.label} · {group.children.length} item(s)
+                  </li>
+                ))}
+                {config.shellPreview.adminNavItem ? <li>{config.shellPreview.adminNavItem.label} · {config.shellPreview.adminNavItem.href}</li> : null}
+              </ul>
+            </div>
+          </article>
+
+          <article className="panel preview-glass-card">
+            <div className="panel-inner">
+              <h2>Starter controls</h2>
+              <ul className="list">
+                <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>
+              </ul>
+            </div>
+          </article>
+        </section>
+
+        <section className="panel" style={{ marginTop: 18 }}>
+          <div className="panel-inner">
+            <h2>Infrastructure checklist</h2>
+            <div className="grid">
+              {config.envStatus.map((item) => (
+                <article key={item.key} className="panel preview-glass-card" style={{ background: "rgba(255,255,255,0.72)" }}>
+                  <div className="panel-inner">
+                    <p className={`status ${item.present ? "ok" : "warn"}`}>{item.present ? "Configured" : "Missing"}</p>
+                    <h3>{item.key}</h3>
+                    <p className="muted">{item.description}</p>
+                    <p className="package-name">{item.scope} · {item.requiredFor.join(", ")}</p>
+                  </div>
+                </article>
+                ))}
+              </div>
+          </div>
+        </section>
+      </div>
+    </main>
+  );
+}

package/template/base/app/playground/auth/auth-playground.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import {
+  AUTH_RESEND_COOLDOWN_SECONDS,
+  buildResetPasswordRedirectUrl,
+  buildSignupCallbackUrl,
+  useCooldownTimer,
+  validateEmail,
+  validatePassword,
+} from "@brightweblabs/core-auth/client";
+
+export function AuthPlayground() {
+  const [email, setEmail] = useState("hello@brightweblabs.pt");
+  const [password, setPassword] = useState("Brightweb2026");
+  const passwordResult = useMemo(() => validatePassword(password), [password]);
+  const emailIsValid = useMemo(() => validateEmail(email), [email]);
+  const cooldown = useCooldownTimer(AUTH_RESEND_COOLDOWN_SECONDS);
+  const authUrls = useMemo(() => {
+    try {
+      return {
+        signupCallbackUrl: buildSignupCallbackUrl(),
+        resetPasswordUrl: buildResetPasswordRedirectUrl(),
+        error: null,
+      };
+    } catch (error) {
+      return {
+        signupCallbackUrl: null,
+        resetPasswordUrl: null,
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }, []);
+
+  return (
+    <>
+      <article className="panel">
+        <div className="panel-inner">
+          <p className="eyebrow">Core Auth</p>
+          <h1>Auth package playground</h1>
+          <p className="muted">
+            This page exercises the external `@brightweblabs/core-auth` client package directly.
+          </p>
+        </div>
+      </article>
+
+      <article className="panel">
+        <div className="panel-inner form-grid">
+          <div className="field">
+            <label htmlFor="email">Email validator</label>
+            <input id="email" value={email} onChange={(event) => setEmail(event.target.value)} />
+          </div>
+
+          <p className={`status ${emailIsValid ? "ok" : "error"}`}>
+            {emailIsValid ? "Valid email" : "Invalid email"}
+          </p>
+
+          <div className="field">
+            <label htmlFor="password">Password validator</label>
+            <input id="password" value={password} onChange={(event) => setPassword(event.target.value)} />
+          </div>
+
+          <div className="result-box">
+            <strong>{passwordResult.isValid ? "Password accepted" : "Password rejected"}</strong>
+            <ul>
+              {passwordResult.errors.length === 0 ? <li>No validation errors.</li> : null}
+              {passwordResult.errors.map((error) => <li key={error}>{error}</li>)}
+            </ul>
+          </div>
+        </div>
+      </article>
+
+      <article className="panel">
+        <div className="panel-inner stack">
+          <div>
+            <h2>Derived URLs</h2>
+            <p className="muted">These values come from the auth package and depend on `NEXT_PUBLIC_APP_URL`.</p>
+          </div>
+          <div className="code-box">
+            {authUrls.error ? (
+              <div>
+                <strong>Configuration required:</strong> {authUrls.error}
+              </div>
+            ) : (
+              <>
+                <div><strong>Signup callback:</strong> {authUrls.signupCallbackUrl}</div>
+                <div><strong>Reset password:</strong> {authUrls.resetPasswordUrl}</div>
+              </>
+            )}
+          </div>
+        </div>
+      </article>
+
+      <article className="panel">
+        <div className="panel-inner stack">
+          <div>
+            <h2>Cooldown hook</h2>
+            <p className="muted">Useful for resend-email and rate-limited auth actions.</p>
+          </div>
+          <div className="actions">
+            <button className="action" onClick={() => cooldown.start()} disabled={cooldown.isCoolingDown}>
+              {cooldown.isCoolingDown ? `Cooling down: ${cooldown.remaining}s` : "Start cooldown"}
+            </button>
+            <button className="action secondary" onClick={() => cooldown.reset()}>
+              Reset
+            </button>
+          </div>
+        </div>
+      </article>
+    </>
+  );
+}

package/template/base/app/playground/auth/page.tsx

@@ -0,0 +1,5 @@
+import { AuthPlayground } from "./auth-playground";
+
+export default function AuthPlaygroundPage() {
+  return <AuthPlayground />;
+}

package/template/base/app/playground/layout.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+import Link from "next/link";
+import { getEnabledStarterModules } from "../../config/modules";
+
+const links = getEnabledStarterModules()
+  .filter((moduleConfig) => moduleConfig.playgroundHref)
+  .map((moduleConfig) => ({
+    href: moduleConfig.playgroundHref!,
+    label: moduleConfig.label,
+  }));
+
+export default function PlaygroundLayout({ children }: { children: ReactNode }) {
+  return (
+    <main className="shell">
+      <div className="frame playground-layout">
+        <aside className="panel sidebar">
+          <div className="panel-inner stack">
+            <div>
+              <span className="eyebrow">Sandbox</span>
+              <h2 style={{ marginBottom: 8 }}>Module Playground</h2>
+              <p className="muted">
+                Use these routes to inspect package behavior while editing the shared repo.
+              </p>
+            </div>
+            <nav className="nav-list">
+              {links.map((link) => (
+                <Link key={link.href} href={link.href} className="nav-item">
+                  {link.label}
+                </Link>
+              ))}
+              <Link href="/" className="nav-item">
+                Back to overview
+              </Link>
+            </nav>
+          </div>
+        </aside>
+        <section className="stack">{children}</section>
+      </div>
+    </main>
+  );
+}

package/template/base/app/preview/app-shell/page.tsx

@@ -0,0 +1,11 @@
+import { AppShellPreview } from "../app-shell-preview";
+
+export default function AppShellPreviewPage() {
+  return (
+    <main className="shell shell-preview-page">
+      <div className="frame">
+        <AppShellPreview />
+      </div>
+    </main>
+  );
+}

package/template/base/app/preview/app-shell-preview.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import {
+  AccountMenu,
+  AppHeader,
+  DesktopSidebar,
+  MobileNav,
+  computeInitials,
+  getShellNavGroup,
+  type NavGroupConfig,
+  type ResolvedClientAppShellConfig,
+} from "@brightweblabs/app-shell";
+import { LayoutTemplate, Sparkles, Users } from "lucide-react";
+import { starterBrandConfig } from "../../config/brand";
+import { getStarterShellConfig } from "../../config/shell";
+
+const mockUser = {
+  email: "admin@starter-client.test",
+  user_metadata: {
+    first_name: "Starter",
+    last_name: "Admin",
+  },
+};
+
+const mockSurfaceCards = [
+  {
+    title: "Module activation",
+    description: "Nav, admin access, and tools placement are resolved from the starter client config.",
+    icon: LayoutTemplate,
+  },
+  {
+    title: "Shared updates",
+    description: "The shell primitives come from `@brightweblabs/app-shell`, so new clients keep the same integration contract.",
+    icon: Sparkles,
+  },
+  {
+    title: "User governance",
+    description: "Admin placement stays visible because the preview assumes an admin/staff viewer.",
+    icon: Users,
+  },
+];
+
+export function AppShellPreview() {
+  const { shellPreview: config } = getStarterShellConfig() as { shellPreview: ResolvedClientAppShellConfig };
+  const [isSidebarCollapsed, setIsSidebarCollapsed] = useState(false);
+  const [toolsExpanded, setToolsExpanded] = useState(true);
+  const [crmExpanded, setCrmExpanded] = useState(true);
+  const [activeHref, setActiveHref] = useState(config.primaryNav[0]?.href ?? "/dashboard");
+
+  const crmNavGroup = useMemo(
+    () =>
+      getShellNavGroup(config, "crm")
+      ?? ({
+        label: "CRM",
+        icon: Users,
+        children: [{ href: "/crm", label: "CRM", icon: Users }],
+      } satisfies NavGroupConfig),
+    [config],
+  );
+  const collapsedToolsHref = config.toolsSection.items[0]?.href ?? "/";
+  const displayName = "Starter Admin";
+  const userInitials = computeInitials(displayName);
+  const isNavItemActive = (href: string) => activeHref === href;
+  const isToolLinkActive = (href: string) => activeHref === href;
+  const isCrmChildActive = (href: string) => activeHref === href;
+  const isCrmGroupActive = crmNavGroup.children.some((item) => activeHref === item.href);
+  const isToolActive = config.toolsSection.items.some((item) => activeHref === item.href);
+
+  return (
+    <div className="app-preview-shell">
+      <DesktopSidebar
+        className="app-preview-sidebar"
+        brand={config.brand}
+        collapsedToolsHref={collapsedToolsHref}
+        isSidebarCollapsed={isSidebarCollapsed}
+        isToolActive={isToolActive}
+        toolsExpanded={toolsExpanded}
+        visiblePrimaryNav={config.primaryNav}
+        adminNavItem={config.adminNavItem}
+        visibleToolNav={config.toolsSection.items}
+        crmNavGroup={crmNavGroup}
+        crmGroupExpanded={crmExpanded}
+        isCrmGroupActive={isCrmGroupActive}
+        isNavItemActive={isNavItemActive}
+        isToolLinkActive={isToolLinkActive}
+        isCrmChildActive={isCrmChildActive}
+        onToggleSidebar={() => setIsSidebarCollapsed((current) => !current)}
+        onToggleTools={() => setToolsExpanded((current) => !current)}
+        onToggleCrmGroup={() => setCrmExpanded((current) => !current)}
+      />
+
+      <div className="app-preview-main">
+        <AppHeader className="app-preview-header">
+          <div className="app-preview-header-copy">
+            <span className="eyebrow">{starterBrandConfig.companyName}</span>
+            <h1>Logged-in shell preview</h1>
+            <p className="muted">This is the packaged shell running with the starter client registration.</p>
+          </div>
+          <div className="app-preview-header-actions">
+            <div className="status ok">Admin preview</div>
+            <AccountMenu
+              displayName={displayName}
+              isStaff
+              onSignOut={async () => {}}
+              user={mockUser}
+              userInitials={userInitials}
+            />
+          </div>
+        </AppHeader>
+
+        <div className="app-preview-mobile-nav">
+          <MobileNav
+            className="panel"
+            toolsExpanded={toolsExpanded}
+            visiblePrimaryNav={config.primaryNav}
+            visibleToolNav={config.toolsSection.items}
+            isNavItemActive={isNavItemActive}
+            isToolLinkActive={isToolLinkActive}
+            onToggleTools={() => setToolsExpanded((current) => !current)}
+          />
+        </div>
+
+        <section className="app-preview-content">
+          <div className="app-preview-stage">
+            <div className="grid">
+              {mockSurfaceCards.map((card) => (
+                <article key={card.title} className="panel preview-glass-card">
+                  <div className="panel-inner">
+                    <div className="preview-card-icon">
+                      <card.icon className="size-4" />
+                    </div>
+                    <h2>{card.title}</h2>
+                    <p className="muted">{card.description}</p>
+                  </div>
+                </article>
+              ))}
+            </div>
+
+            <article className="panel preview-stage-panel">
+              <div className="panel-inner">
+                <div className="preview-stage-head">
+                  <div>
+                    <span className="eyebrow">Active path</span>
+                    <h2>{activeHref}</h2>
+                  </div>
+                  <div className="actions">
+                    {[...config.primaryNav, ...crmNavGroup.children, ...(config.adminNavItem ? [config.adminNavItem] : []), ...config.toolsSection.items].map((item) => (
+                      <button
+                        key={item.href}
+                        type="button"
+                        className={`nav-chip ${activeHref === item.href ? "active" : ""}`}
+                        onClick={() => setActiveHref(item.href)}
+                      >
+                        {item.label}
+                      </button>
+                    ))}
+                  </div>
+                </div>
+
+                <div className="preview-surface-grid">
+                  <div className="preview-surface-card">
+                    <p className="preview-label">Primary navigation</p>
+                    <strong>{config.primaryNav.length} item(s)</strong>
+                    <span>{config.primaryNav.map((item) => item.label).join(" · ")}</span>
+                  </div>
+                  <div className="preview-surface-card">
+                    <p className="preview-label">CRM group</p>
+                    <strong>{crmNavGroup.children.length} item(s)</strong>
+                    <span>{crmNavGroup.children.map((item) => item.label).join(" · ")}</span>
+                  </div>
+                  <div className="preview-surface-card">
+                    <p className="preview-label">Tools section</p>
+                    <strong>{config.toolsSection.items.length} item(s)</strong>
+                    <span>{config.toolsSection.items.map((item) => item.label).join(" · ") || "No tools enabled"}</span>
+                  </div>
+                </div>
+              </div>
+            </article>
+          </div>
+        </section>
+      </div>
+    </div>
+  );
+}

package/template/base/config/bootstrap.ts

@@ -0,0 +1,125 @@
+import { getStarterClientConfig } from "./client";
+
+export type StarterChecklistItem = {
+  label: string;
+  done: boolean;
+  detail?: string;
+};
+
+export type StarterChecklistSection = {
+  key: string;
+  title: string;
+  items: StarterChecklistItem[];
+};
+
+function hasModule(moduleKeys: string[], key: string) {
+  return moduleKeys.includes(key);
+}
+
+export function getStarterBootstrapChecklist() {
+  const config = getStarterClientConfig();
+  const moduleKeys = config.enabledModules.map((moduleConfig) => moduleConfig.key);
+
+  const identitySection: StarterChecklistSection = {
+    key: "identity",
+    title: "Client identity",
+    items: [
+      {
+        label: "Define company and product name",
+        done: config.brand.companyName !== "Starter Client" && config.brand.productName !== "Operations Platform",
+        detail: `${config.brand.companyName} / ${config.brand.productName}`,
+      },
+      {
+        label: "Set client slug",
+        done: config.brand.slug !== "starter-client",
+        detail: config.brand.slug,
+      },
+      {
+        label: "Set client contact and support inboxes",
+        done: config.brand.contactEmail !== "hello@example.com" && config.brand.supportEmail !== "support@example.com",
+        detail: `${config.brand.contactEmail} · ${config.brand.supportEmail}`,
+      },
+    ],
+  };
+
+  const envSection: StarterChecklistSection = {
+    key: "environment",
+    title: "Environment and infrastructure",
+    items: config.envStatus.map((item) => ({
+      label: `Configure ${item.key}`,
+      done: item.present,
+      detail: `${item.scope} · ${item.requiredFor.join(", ")}`,
+    })),
+  };
+
+  const dataSection: StarterChecklistSection = {
+    key: "services",
+    title: "Client services",
+    items: [
+      {
+        label: "Provision dedicated Supabase project",
+        done: config.envStatus.filter((item) => item.key.includes("SUPABASE")).every((item) => item.present),
+        detail: "Database, auth, storage, and RPC functions should be client-specific.",
+      },
+      {
+        label: "Configure Resend for the client sender domain",
+        done: Boolean(config.envStatus.find((item) => item.key === "RESEND_API_KEY")?.present),
+        detail: "Use a sender/domain owned by this client instance.",
+      },
+      {
+        label: "Create per-client environment variables",
+        done: config.envReadiness.allReady,
+        detail: "Copy `.env.example` into `.env.local` and fill the real values.",
+      },
+    ],
+  };
+
+  const modulesSection: StarterChecklistSection = {
+    key: "modules",
+    title: "Enabled modules",
+    items: config.enabledModules.map((moduleConfig) => ({
+      label: `Validate ${moduleConfig.label}`,
+      done: Boolean(moduleConfig.playgroundHref),
+      detail: moduleConfig.playgroundHref
+        ? `Preview at ${moduleConfig.playgroundHref}`
+        : `Package ${moduleConfig.packageName}`,
+    })),
+  };
+
+  const rolloutSection: StarterChecklistSection = {
+    key: "rollout",
+    title: "Launch readiness",
+    items: [
+      {
+        label: "Preview Auth flows",
+        done: true,
+        detail: "/playground/auth",
+      },
+      {
+        label: "Preview CRM module",
+        done: hasModule(moduleKeys, "crm"),
+        detail: hasModule(moduleKeys, "crm") ? "/playground/crm" : "CRM not enabled",
+      },
+      {
+        label: "Preview Projects module",
+        done: hasModule(moduleKeys, "projects"),
+        detail: hasModule(moduleKeys, "projects") ? "/playground/projects" : "Projects not enabled",
+      },
+      {
+        label: "Preview Admin module",
+        done: hasModule(moduleKeys, "admin"),
+        detail: hasModule(moduleKeys, "admin") ? "/playground/admin" : "Admin not enabled",
+      },
+      {
+        label: "Deploy only after env readiness is green",
+        done: config.envReadiness.allReady,
+        detail: config.envReadiness.allReady ? "Ready for deploy validation." : `${config.envReadiness.missing.length} env key(s) still missing.`,
+      },
+    ],
+  };
+
+  return {
+    client: config,
+    sections: [identitySection, envSection, dataSection, modulesSection, rolloutSection],
+  };
+}

package/template/base/config/brand.ts

@@ -0,0 +1,21 @@
+export type StarterBrandConfig = {
+  companyName: string;
+  productName: string;
+  slug: string;
+  tagline: string;
+  contactEmail: string;
+  supportEmail: string;
+  primaryHex: string;
+};
+
+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",
+};

package/template/base/config/client.ts

@@ -0,0 +1,18 @@
+import { starterBrandConfig } from "./brand";
+import { getStarterEnvStatus, isStarterEnvReady } from "./env";
+import { getStarterShellConfig } from "./shell";
+
+export function getStarterClientConfig() {
+  const shell = getStarterShellConfig();
+  const enabledModules = shell.enabledModules;
+  const moduleKeys = enabledModules.map((moduleConfig) => moduleConfig.key);
+
+  return {
+    brand: starterBrandConfig,
+    enabledModules,
+    envStatus: getStarterEnvStatus(),
+    envReadiness: isStarterEnvReady(moduleKeys),
+    shellPreview: shell.shellPreview,
+    toolbarRoutes: shell.toolbarRoutes,
+  };
+}