create-bw-app 0.9.4 → 0.9.5

package/README.md

@@ -41,6 +41,8 @@ pnpm dlx create-bw-app update --target-dir ./apps/client-portal
 Current updater behavior:
 
 - updates installed `@brightweblabs/*` packages only
+- in published mode, resolves those `@brightweblabs/*` target versions from npm at update time
+- fails the update if npm resolution fails unless you pass `--allow-stale-fallback`
 - re-syncs managed BrightWeb config files such as `next.config.ts`, `config/modules.ts`, and `config/shell.ts`
 - reports missing or drifted starter files and only rewrites them with `--refresh-starters`
 - prints the follow-up install command unless `--install` is passed
@@ -54,6 +56,7 @@ Current updater behavior:
 - prompts to install dependencies immediately
 - 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
 - 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

package/package.json

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

package/src/cli.mjs

@@ -42,6 +42,11 @@ function parseArgv(argv) {
       continue;
     }
 
+    if (token === "--allow-stale-fallback") {
+      options.allowStaleFallback = true;
+      continue;
+    }
+
     const [rawKey, inlineValue] = token.slice(2).split("=", 2);
     const key = toCamelCase(rawKey);
     const nextValue = inlineValue ?? argv[index + 1];

package/src/constants.mjs

@@ -136,6 +136,7 @@ Update options:
   --target-dir <path>            Existing app directory to update (defaults to cwd)
   --workspace-root <path>        BrightWeb workspace root for workspace:* apps
   --package-manager <name>       Override package manager: pnpm, npm, yarn, or bun
+  --allow-stale-fallback         Use baked-in BrightWeb package versions if npm lookup fails
   --install                      Run install after writing package changes
   --refresh-starters             Rewrite starter route files from the latest template
   --dry-run                      Print the update plan without writing files

package/src/generator.mjs

@@ -631,6 +631,7 @@ export function createAppContextFile({
           ".env.local",
         ],
         appRoutesRoot: "app",
+        componentsRoot: "components",
         configRoot: "config",
         brandAssetsRoot: "public/brand",
       },
@@ -638,6 +639,7 @@ export function createAppContextFile({
       ownership: {
         appOwned: [
           "app/**",
+          "components/**",
           "config/**",
           "docs/ai/**",
           "public/brand/**",

package/src/update.mjs

@@ -76,6 +76,62 @@ function collectInstalledBrightwebPackages(manifest) {
   return installed;
 }
 
+async function resolvePublishedBrightwebVersions(installedBrightwebPackages, options = {}) {
+  const packageNames = Array.from(installedBrightwebPackages.keys()).sort();
+
+  if (packageNames.length === 0) {
+    return {};
+  }
+
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("Published updates require fetch support to resolve BrightWeb package versions from npm.");
+  }
+
+  const fallbackVersionMap = options.fallbackVersionMap || {};
+  const allowStaleFallback = options.allowStaleFallback === true;
+  const resolvedVersions = {};
+  const failures = [];
+
+  await Promise.all(
+    packageNames.map(async (packageName) => {
+      try {
+        const response = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`);
+        if (!response?.ok) {
+          throw new Error(`npm registry responded with ${response?.status ?? "an unknown error"}`);
+        }
+
+        const payload = await response.json();
+        if (!payload?.version || typeof payload.version !== "string") {
+          throw new Error("npm registry response did not include a version");
+        }
+
+        resolvedVersions[packageName] = `^${payload.version}`;
+      } catch (error) {
+        const fallbackVersion = fallbackVersionMap[packageName];
+        if (allowStaleFallback && fallbackVersion) {
+          resolvedVersions[packageName] = fallbackVersion;
+          return;
+        }
+
+        const message = error instanceof Error ? error.message : "Unknown error";
+        failures.push(`${packageName}: ${message}`);
+      }
+    }),
+  );
+
+  if (failures.length > 0) {
+    const fallbackHint = allowStaleFallback
+      ? "No baked-in fallback version was available for at least one package."
+      : "Re-run with --allow-stale-fallback to use the CLI's baked-in BrightWeb package versions instead.";
+    throw new Error(
+      `Failed to resolve published BrightWeb package versions from npm.\n${failures.join("\n")}\n${fallbackHint}`,
+    );
+  }
+
+  return resolvedVersions;
+}
+
 function parseConfiguredModules(content) {
   const enabledModules = [];
 
@@ -339,6 +395,13 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   const packageManager = detectPackageManager(argvOptions.packageManager || runtimeOptions.packageManager);
   const installedModules = detectInstalledModules(installedBrightwebPackagesMap);
   const versionMap = await getVersionMap(workspaceRoot);
+  const brightwebVersionOverrides = dependencyMode === "published"
+    ? await resolvePublishedBrightwebVersions(installedBrightwebPackagesMap, {
+      fetchImpl: runtimeOptions.fetchImpl,
+      fallbackVersionMap: versionMap,
+      allowStaleFallback: argvOptions.allowStaleFallback || runtimeOptions.allowStaleFallback,
+    })
+    : {};
   const dbRegistry = await getDbModuleRegistry(workspaceRoot);
   const dbInstallPlan = template === "platform"
     ? createDbInstallPlan({
@@ -356,7 +419,10 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
     template,
     dependencyMode,
     installedModules,
-    versionMap,
+    versionMap: {
+      ...versionMap,
+      ...brightwebVersionOverrides,
+    },
   });
   const packageJsonUpdate = mergeManagedPackageUpdates({
     manifest,

package/template/base/AGENTS.md

@@ -8,6 +8,7 @@ This generated project is a BrightWeb platform starter. Use this file as the loc
 - `docs/ai/README.md`: app-specific routing guide for agents.
 - `docs/ai/examples.md`: common setup and customization flows.
 - `docs/ai/app-context.json`: machine-readable app summary for quick discovery.
+- `components/`: local app components used by starter routes and future product surfaces.
 - `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.

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

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

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

@@ -1,4 +1,4 @@
-import { AppShellPreview } from "../app-shell-preview";
+import { AppShellPreview } from "../../../components/app-shell-preview";
 
 export default function AppShellPreviewPage() {
   return (

package/template/base/{app/preview → components}/app-shell-preview.tsx

@@ -12,8 +12,8 @@ import {
   type ResolvedClientAppShellConfig,
 } from "@brightweblabs/app-shell";
 import { LayoutTemplate, Sparkles, Users } from "lucide-react";
-import { starterBrandConfig } from "../../config/brand";
-import { getStarterShellConfig } from "../../config/shell";
+import { starterBrandConfig } from "../config/brand";
+import { getStarterShellConfig } from "../config/shell";
 
 const mockUser = {
   email: "admin@starter-client.test",

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

@@ -9,6 +9,7 @@ It is intentionally app-scoped. It explains the generated project you are in, no
 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.
+- `components/`: local React components used by starter routes and app-owned product work.
 - `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.
@@ -18,6 +19,7 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 - `docs/ai/app-context.json`: machine-readable summary of this app's template, starter routes, and first-read files.
 - `docs/ai/examples.md`: common setup and customization workflows.
 - `README.md`: first-run setup steps.
+- `components/`: local app component layer for starter surfaces and future product UI.
 - `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.
@@ -33,6 +35,7 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 
 - Change client identity first in `config/brand.ts`.
 - Check module presence in `config/modules.ts` before editing or creating module-specific routes.
+- Add app-specific UI in `components/` before forking shared package code.
 - 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.

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

@@ -18,6 +18,7 @@ Goal: get the generated starter running with real credentials.
 Goal: update the starter to the real client name and support details.
 
 - Edit `config/brand.ts`.
+- Move route-specific presentation into `components/` when the home or preview surfaces need app-owned UI.
 - Check `config/client.ts` or `config/bootstrap.ts` if starter copy still references old defaults.
 - Validate the home page and `/preview/app-shell` after the change.
 
@@ -26,6 +27,7 @@ Goal: update the starter to the real client name and support details.
 Goal: move from validation surfaces to product-owned pages.
 
 - Build the real routes in `app/` first.
+- Keep reusable route UI in `components/` so the app follows the expected Next.js folder split.
 - Update `config/shell.ts` if navigation or toolbar behavior changes.
 - Remove `/bootstrap`, `/preview/app-shell`, or `/playground/*` only after links and config references are cleaned up.
 

package/template/modules/crm/app/api/crm/_shared/create-module-route-handler.ts

@@ -0,0 +1,13 @@
+type RouteHandler = (request: Request) => Response | Promise<Response>;
+
+type ModuleWithHandler<THandlerName extends string> = Record<THandlerName, RouteHandler>;
+
+export function createModuleRouteHandler<THandlerName extends string>(
+  loadModule: () => Promise<ModuleWithHandler<THandlerName>>,
+  handlerName: THandlerName,
+): RouteHandler {
+  return async function moduleRouteHandler(request: Request) {
+    const module = await loadModule();
+    return module[handlerName](request);
+  };
+}

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmContactsGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmContactsGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmContactsGetRequest",
+);

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmOrganizationsGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmOrganizationsGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmOrganizationsGetRequest",
+);

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmOwnersGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmOwnersGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmOwnersGetRequest",
+);

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmStatsGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmStatsGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmStatsGetRequest",
+);