create-bw-app 0.10.1 → 0.12.0

package/src/remove.mjs

@@ -0,0 +1,100 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import {
+  MODULE_PACKAGES,
+  findWorkspaceRoot,
+  hashFile,
+  loadModuleCatalog,
+  readAppManifest,
+  writeAppManifest,
+} from "./app-manifest.mjs";
+import {
+  createAppContextFile,
+  createDbInstallPlan,
+  createNextConfig,
+  createPlatformModulesConfigFile,
+  createShellConfig,
+  getDbModuleRegistry,
+  pathExists,
+  readJsonIfPresent,
+} from "./generator.mjs";
+
+const HELP = `Usage: bw remove <moduleKey> [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --dry-run                 Print the removal plan without writing\n  --yes                     Apply the removal plan\n  --help                    Show this help`;
+
+function databaseNotice(moduleKey, ownedObjects) {
+  const names = ownedObjects.length > 0 ? ownedObjects.join(", ") : "none declared";
+  return [
+    `-- Database objects owned by ${moduleKey}: ${names}`,
+    "-- No database objects or migration files were changed.",
+    "-- Dropping owned objects is a deliberate manual data-removal act.",
+    "-- Applied migrations remain in app history under the append-only migration principle.",
+  ];
+}
+
+export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtimeOptions = {}) {
+  if (!moduleKey || argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const appManifest = await readAppManifest(targetDir);
+  if (!appManifest.modules[moduleKey]) throw new Error(`Module ${moduleKey} is not installed according to .brightweb/app-manifest.json.`);
+  const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
+  const dependents = Object.keys(appManifest.modules)
+    .filter((key) => key !== moduleKey && catalog[key]?.requires?.[moduleKey]);
+  if (dependents.length > 0) throw new Error(`Cannot remove ${moduleKey}; installed module${dependents.length === 1 ? "" : "s"} ${dependents.join(", ")} require${dependents.length === 1 ? "s" : ""} it.`);
+
+  const packagePath = path.join(targetDir, "package.json");
+  const packageJson = await readJsonIfPresent(packagePath);
+  if (!packageJson) throw new Error(`Target directory does not contain package.json: ${targetDir}`);
+  const nextPackageJson = structuredClone(packageJson);
+  const packageName = MODULE_PACKAGES[moduleKey];
+  for (const section of ["dependencies", "devDependencies"]) if (nextPackageJson[section]) delete nextPackageJson[section][packageName];
+
+  const remainingModules = Object.keys(appManifest.modules).filter((key) => key !== moduleKey);
+  const dbRegistry = await getDbModuleRegistry(workspaceRoot);
+  const dbInstallPlan = createDbInstallPlan({
+    selectedModules: remainingModules.filter((key) => key !== "orgs"),
+    workspaceMode: Object.values(nextPackageJson.dependencies || {}).some((value) => String(value).startsWith("workspace:")),
+    registry: dbRegistry,
+  });
+  const managedWrites = {
+    "next.config.ts": createNextConfig({ template: "platform", selectedModules: remainingModules }),
+    "config/modules.ts": createPlatformModulesConfigFile(remainingModules),
+    "config/shell.ts": createShellConfig(remainingModules),
+    "docs/ai/app-context.json": createAppContextFile({ slug: appManifest.app.slug, template: "platform", selectedModules: remainingModules.filter((key) => key !== "orgs"), dbInstallPlan }),
+  };
+
+  const cleanFiles = [];
+  const driftedFiles = [];
+  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles || {})) {
+    if (record.module !== moduleKey) continue;
+    const filePath = path.join(targetDir, relativePath);
+    if (!(await pathExists(filePath))) continue;
+    if ((record.intent || "managed") === "managed" && await hashFile(filePath) === record.hash) cleanFiles.push(relativePath);
+    else driftedFiles.push(relativePath);
+  }
+  const notice = databaseNotice(moduleKey, catalog[moduleKey]?.manifest?.database?.ownedObjects || []);
+  const apply = argvOptions.yes === true && argvOptions.dryRun !== true;
+  output.write(`bw remove ${moduleKey}${apply ? "" : " (plan only; pass --yes to apply)"}\n`);
+  output.write(`Dependency to remove: ${packageName}\n`);
+  output.write(`Clean scaffold files to remove: ${cleanFiles.join(", ") || "none"}\n`);
+  output.write(`Drifted scaffold files left in place: ${driftedFiles.join(", ") || "none"}\n`);
+  for (const relativePath of driftedFiles) output.write(`WARN ${relativePath} is drifted and will be left in place.\n`);
+  for (const line of notice) output.write(`${line}\n`);
+  if (!apply) return { dryRun: true, moduleKey, cleanFiles, driftedFiles, notice };
+
+  await fs.writeFile(packagePath, `${JSON.stringify(nextPackageJson, null, 2)}\n`, "utf8");
+  for (const relativePath of cleanFiles) await fs.rm(path.join(targetDir, relativePath));
+  for (const [relativePath, content] of Object.entries(managedWrites)) {
+    const targetPath = path.join(targetDir, relativePath);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content, "utf8");
+  }
+  delete appManifest.modules[moduleKey];
+  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles || {})) if (record.module === moduleKey) delete appManifest.scaffoldFiles[relativePath];
+  await writeAppManifest(targetDir, appManifest);
+  output.write(`Removed ${moduleKey} package wiring and ${cleanFiles.length} clean scaffold file${cleanFiles.length === 1 ? "" : "s"}. Install dependencies next.\n`);
+  return { dryRun: false, moduleKey, cleanFiles, driftedFiles, notice };
+}
+
+export { HELP as REMOVE_HELP };

package/src/scaffold-cmd.mjs

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { findWorkspaceRoot, hashFile, readAppManifest, writeAppManifest } from "./app-manifest.mjs";
+import { pathExists } from "./generator.mjs";
+import { findTrackedTemplate, scaffoldDrift } from "./scaffold.mjs";
+
+const HELP = `Usage: bw scaffold <action> [paths...] [options]\n\nActions:\n  list                List tracked files, live status, and intent\n  own <path>...       Mark existing tracked files as app-owned\n  skip <path>...      Mark missing tracked files as intentionally absent\n  manage <path>...    Return tracked files to BrightWeb management\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --help                    Show this help`;
+
+function normalizeTrackedPath(relativePath) {
+  const normalized = path.normalize(String(relativePath)).replace(/^\.\//, "");
+  if (path.isAbsolute(String(relativePath)) || normalized === ".." || normalized.startsWith(`..${path.sep}`)) {
+    throw new Error(`Scaffold path must be relative to the app: ${relativePath}`);
+  }
+  return normalized;
+}
+
+export async function scaffoldBrightwebApp(action, paths = [], argvOptions = {}, runtimeOptions = {}) {
+  if (argvOptions.help || !action) { output.write(`${HELP}\n`); return { help: true }; }
+  if (!Array.isArray(paths)) paths = [paths];
+  if (!["list", "own", "skip", "manage"].includes(action)) throw new Error(`Unknown bw scaffold action: ${action}\n\n${HELP}`);
+  if (action !== "list" && paths.length === 0) throw new Error(`bw scaffold ${action} requires at least one tracked <path>.`);
+  if (action === "list" && paths.length > 0) throw new Error("bw scaffold list does not accept file paths.");
+
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const manifest = await readAppManifest(targetDir);
+  const live = await scaffoldDrift(targetDir, manifest.scaffoldFiles);
+  if (action === "list") {
+    output.write("PATH\tMODULE\tSTATUS\tINTENT\n");
+    for (const entry of live.entries) output.write(`${entry.relativePath}\t${entry.module}\t${entry.status}\t${entry.intent}\n`);
+    return { action, entries: live.entries };
+  }
+
+  const normalizedPaths = Array.from(new Set(paths.map(normalizeTrackedPath)));
+  for (const relativePath of normalizedPaths) {
+    if (!manifest.scaffoldFiles?.[relativePath]) throw new Error(`${relativePath} is not a tracked scaffold file.`);
+  }
+  const liveByPath = new Map(live.entries.map((entry) => [entry.relativePath, entry]));
+  for (const relativePath of normalizedPaths) {
+    const status = liveByPath.get(relativePath)?.status;
+    if (action === "own" && status === "missing") throw new Error(`Cannot own missing scaffold file: ${relativePath}`);
+    if (action === "skip" && status !== "missing") throw new Error(`Cannot skip existing scaffold file: ${relativePath}`);
+  }
+
+  const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const changes = [];
+  for (const relativePath of normalizedPaths) {
+    const record = manifest.scaffoldFiles[relativePath];
+    const previousIntent = record.intent || "managed";
+    const nextIntent = action === "manage" ? "managed" : action === "own" ? "owned" : "skipped";
+    const appPath = path.join(targetDir, relativePath);
+    const exists = await pathExists(appPath);
+    if (action === "manage") {
+      const located = await findTrackedTemplate({ relativePath, manifest, targetDir, workspaceRoot });
+      if (!located.templatePath) throw new Error(`Installed-package template unavailable for ${relativePath}; cannot manage it safely.`);
+      const templateHash = await hashFile(located.templatePath);
+      if (exists) {
+        record.hash = await hashFile(appPath);
+        record.status = record.hash === templateHash ? "current" : "drifted";
+      } else {
+        record.status = "missing";
+      }
+    } else {
+      record.status = liveByPath.get(relativePath).status;
+    }
+    if (nextIntent === "managed") delete record.intent;
+    else record.intent = nextIntent;
+    changes.push({ relativePath, previousIntent, intent: nextIntent, status: record.status });
+  }
+  await writeAppManifest(targetDir, manifest);
+  for (const change of changes) output.write(`${change.relativePath}: intent ${change.previousIntent} -> ${change.intent} (${change.status})\n`);
+  return { action, changes, manifest };
+}
+
+export { HELP as SCAFFOLD_HELP };

package/src/scaffold.mjs

@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MODULE_STARTER_FILES, PLATFORM_STARTER_FILES, SELECTABLE_MODULES } from "./constants.mjs";
+import { hashFile } from "./app-manifest.mjs";
+import { pathExists } from "./generator.mjs";
+
+const BUNDLED_TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "template");
+
+export async function resolveTemplateRoot({ targetDir, workspaceRoot } = {}) {
+  const candidates = [
+    workspaceRoot && path.join(path.resolve(workspaceRoot), "packages", "create-bw-app", "template"),
+    targetDir && path.join(path.resolve(targetDir), "node_modules", "create-bw-app", "template"),
+    BUNDLED_TEMPLATE_ROOT,
+  ].filter(Boolean);
+  for (const candidate of candidates) if (await pathExists(candidate)) return candidate;
+  return null;
+}
+
+export function trackedScaffoldDefinitions(moduleKeys = []) {
+  const definitions = PLATFORM_STARTER_FILES.map((relativePath) => ({
+    moduleKey: "platform-base",
+    relativePath,
+    templateRelativePath: path.join("base", relativePath),
+  }));
+  for (const moduleKey of moduleKeys) {
+    const folder = SELECTABLE_MODULES.find((entry) => entry.key === moduleKey)?.templateFolder;
+    if (!folder) continue;
+    for (const relativePath of MODULE_STARTER_FILES[moduleKey] || []) {
+      definitions.push({ moduleKey, relativePath, templateRelativePath: path.join("modules", folder, relativePath) });
+    }
+  }
+  return definitions.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+
+export async function inventoryScaffoldFiles({ targetDir, moduleKeys, templateRoot }) {
+  const records = {};
+  const unsupported = [];
+  for (const definition of trackedScaffoldDefinitions(moduleKeys)) {
+    const templatePath = templateRoot && path.join(templateRoot, definition.templateRelativePath);
+    if (!templatePath || !(await pathExists(templatePath))) {
+      unsupported.push(definition.relativePath);
+      continue;
+    }
+    const appPath = path.join(targetDir, definition.relativePath);
+    const templateHash = await hashFile(templatePath);
+    const exists = await pathExists(appPath);
+    records[definition.relativePath] = {
+      module: definition.moduleKey,
+      hash: templateHash,
+      status: !exists ? "missing" : await hashFile(appPath) === templateHash ? "current" : "drifted",
+    };
+  }
+  return { records, unsupported };
+}
+
+export async function scaffoldDrift(targetDir, scaffoldFiles = {}) {
+  const current = [];
+  const drifted = [];
+  const missing = [];
+  const entries = [];
+  for (const [relativePath, record] of Object.entries(scaffoldFiles)) {
+    const appPath = path.join(targetDir, relativePath);
+    const intent = record.intent || "managed";
+    let status = "missing";
+    if (await pathExists(appPath)) {
+      const matchesRecordedHash = await hashFile(appPath) === record.hash;
+      status = matchesRecordedHash && record.status !== "drifted" ? "current" : "drifted";
+    }
+    entries.push({ relativePath, module: record.module, status, intent });
+    if (status === "missing") missing.push(relativePath);
+    else if (status === "current") current.push(relativePath);
+    else drifted.push(relativePath);
+  }
+  return { current, drifted, missing, entries };
+}
+
+export async function findTrackedTemplate({ relativePath, manifest, targetDir, workspaceRoot }) {
+  const record = manifest.scaffoldFiles?.[relativePath];
+  if (!record) return { record: null, templatePath: null, templateRoot: null };
+  const definition = trackedScaffoldDefinitions(Object.keys(manifest.modules || {}))
+    .find((entry) => entry.relativePath === relativePath && entry.moduleKey === record.module);
+  const templateRoot = await resolveTemplateRoot({ targetDir, workspaceRoot });
+  const templatePath = definition && templateRoot ? path.join(templateRoot, definition.templateRelativePath) : null;
+  return { record, templatePath: templatePath && await pathExists(templatePath) ? templatePath : null, templateRoot };
+}
+
+export async function readTextFile(filePath) {
+  return fs.readFile(filePath, "utf8");
+}

package/src/update.mjs

@@ -5,6 +5,8 @@ import {
   BRIGHTWEB_PACKAGE_NAMES,
   CLI_DISPLAY_NAME,
   MODULE_STARTER_FILES,
+  ORGS_PACKAGE_NAME,
+  PLATFORM_STARTER_FILES,
   SELECTABLE_MODULES,
 } from "./constants.mjs";
 import {
@@ -146,7 +148,7 @@ function parseConfiguredModules(content) {
   return enabledModules;
 }
 
-async function detectTemplate(targetDir, installedBrightwebPackages) {
+export async function detectTemplate(targetDir, installedBrightwebPackages) {
   if (await pathExists(path.join(targetDir, "config", "modules.ts"))) {
     return "platform";
   }
@@ -154,7 +156,7 @@ async function detectTemplate(targetDir, installedBrightwebPackages) {
   return installedBrightwebPackages.size > 0 ? "platform" : "site";
 }
 
-function detectDependencyMode(installedBrightwebPackages) {
+export function detectDependencyMode(installedBrightwebPackages) {
   for (const { version } of installedBrightwebPackages.values()) {
     if (typeof version === "string" && version.startsWith("workspace:")) {
       return "workspace";
@@ -220,6 +222,19 @@ function mergeManagedPackageUpdates({ manifest, targetVersions, installedBrightw
     changed = true;
   }
 
+  const requiredOrgsVersion = targetVersions[ORGS_PACKAGE_NAME];
+  if (requiredOrgsVersion && !installedBrightwebPackages.has(ORGS_PACKAGE_NAME)) {
+    nextManifest.dependencies = nextManifest.dependencies || {};
+    nextManifest.dependencies[ORGS_PACKAGE_NAME] = requiredOrgsVersion;
+    packageUpdates.push({
+      packageName: ORGS_PACKAGE_NAME,
+      from: null,
+      to: requiredOrgsVersion,
+      section: "dependencies",
+    });
+    changed = true;
+  }
+
   return {
     changed,
     packageUpdates,
@@ -230,6 +245,38 @@ function mergeManagedPackageUpdates({ manifest, targetVersions, installedBrightw
 async function getStarterFileStatus(targetDir, installedModules) {
   const starterFiles = [];
 
+  for (const relativePath of PLATFORM_STARTER_FILES) {
+    const sourcePath = path.join(TEMPLATE_ROOT, "base", relativePath);
+    const targetPath = path.join(targetDir, relativePath);
+    const exists = await pathExists(targetPath);
+
+    if (!exists) {
+      starterFiles.push({
+        moduleKey: "platform-base",
+        relativePath,
+        sourcePath,
+        targetPath,
+        status: "missing",
+        refreshable: false,
+      });
+      continue;
+    }
+
+    const [sourceContent, targetContent] = await Promise.all([
+      fs.readFile(sourcePath, "utf8"),
+      fs.readFile(targetPath, "utf8"),
+    ]);
+
+    starterFiles.push({
+      moduleKey: "platform-base",
+      relativePath,
+      sourcePath,
+      targetPath,
+      status: sourceContent === targetContent ? "current" : "drifted",
+      refreshable: false,
+    });
+  }
+
   for (const moduleKey of installedModules) {
     const templateFolder = SELECTABLE_MODULES.find((moduleDefinition) => moduleDefinition.key === moduleKey)?.templateFolder;
     if (!templateFolder) continue;
@@ -498,7 +545,8 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   const starterFilesDrifted = starterFiles.filter((entry) => entry.status === "drifted");
 
   if (argvOptions.refreshStarters) {
-    for (const entry of starterFiles.filter((candidate) => candidate.status !== "current")) {
+    for (const entry of starterFiles.filter((candidate) =>
+      candidate.status !== "current" && (candidate.status === "missing" || candidate.refreshable !== false))) {
       fileWrites.push({
         relativePath: entry.relativePath,
         targetPath: entry.targetPath,

package/src/upgrade.mjs

@@ -0,0 +1,78 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { hashFile, findWorkspaceRoot, loadModuleCatalog, readAppManifest, writeAppManifest, cleanVersion } from "./app-manifest.mjs";
+import { pathExists, runInstall } from "./generator.mjs";
+import { applyMigrationWrites, getModuleMigrations, planMigrationAppends } from "./migrations.mjs";
+import { buildBrightwebAppUpdatePlan } from "./update.mjs";
+
+const HELP = `Usage: bw upgrade [moduleKey] [options]\n\nOptions:\n  --target-dir <path>          App directory (defaults to cwd)\n  --workspace-root <path>      BrightWeb workspace root\n  --allow-stale-fallback       Use baked-in versions if npm lookup fails\n  --install                    Install changed dependencies\n  --refresh-starters           Refresh unchanged starter files\n  --dry-run                    Print the upgrade plan without writing\n  --help                       Show this help`;
+
+export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOptions = {}) {
+  if (argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const appManifest = await readAppManifest(targetDir);
+  if (moduleKey && !appManifest.modules[moduleKey]) throw new Error(`Module ${moduleKey} is not installed according to ${path.join(".brightweb", "app-manifest.json")}.`);
+  const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const updateOptions = { ...argvOptions, targetDir, ...(workspaceRoot ? { workspaceRoot } : {}) };
+  const plan = await buildBrightwebAppUpdatePlan(updateOptions, runtimeOptions);
+  const drifted = [];
+  const missing = [];
+  const intentional = [];
+  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles)) {
+    if (["owned", "skipped"].includes(record.intent)) intentional.push(relativePath);
+    const filePath = path.join(targetDir, relativePath);
+    if (!(await pathExists(filePath))) { missing.push(relativePath); continue; }
+    if (await hashFile(filePath) !== record.hash) drifted.push(relativePath);
+  }
+  const protectedPaths = new Set([...drifted, ...intentional]);
+  plan.fileWrites = plan.fileWrites.filter((entry) => entry.type !== "starter" || !protectedPaths.has(entry.relativePath));
+  plan.starterFilesToRefresh = plan.fileWrites.filter((entry) => entry.type === "starter").map((entry) => entry.relativePath);
+  plan.starterFilesDrifted = Array.from(new Set([...plan.starterFilesDrifted, ...drifted]));
+  plan.starterFilesMissing = Array.from(new Set([...plan.starterFilesMissing, ...missing]));
+
+  const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
+  for (const update of plan.packageUpdates) {
+    const key = Object.keys(catalog).find((candidate) => catalog[candidate].packageName === update.packageName);
+    if (key) catalog[key].version = cleanVersion(update.to) || catalog[key].version;
+  }
+  const moduleKeys = moduleKey ? [moduleKey] : Object.keys(appManifest.modules);
+  const uncursored = [];
+  for (const key of moduleKeys) {
+    if (appManifest.migrationCursor?.[key] == null && (await getModuleMigrations(key, catalog[key])).length > 0) uncursored.push(key);
+  }
+  if (uncursored.length > 0) throw new Error(`Migration upgrade blocked: ${uncursored.join(", ")} ${uncursored.length === 1 ? "has" : "have"} a null migration cursor. Set an explicit cursor with bw adopt --force --cursor before upgrading.`);
+  const migrationPlan = await planMigrationAppends({ targetDir, moduleKeys, catalog, migrationCursor: appManifest.migrationCursor });
+  output.write(`bw upgrade\nPackages to update: ${plan.packageUpdates.length}\nManaged files to write: ${plan.fileWrites.length}\nMigrations to append: ${migrationPlan.writes.length}\n`);
+  for (const relativePath of missing) output.write(`- missing: ${relativePath}\n`);
+  for (const relativePath of drifted) output.write(`- drifted: ${relativePath}\n`);
+  for (const relativePath of intentional) output.write(`- intent-protected: ${relativePath}\n`);
+  if (argvOptions.dryRun) return { dryRun: true, plan, migrationPlan, drifted, missing };
+
+  for (const write of plan.fileWrites) {
+    await fs.mkdir(path.dirname(write.targetPath), { recursive: true });
+    await fs.writeFile(write.targetPath, write.content, "utf8");
+  }
+  await applyMigrationWrites(migrationPlan.writes);
+  appManifest.migrationCursor = migrationPlan.nextCursor;
+  for (const update of plan.packageUpdates) {
+    const key = Object.keys(catalog).find((candidate) => catalog[candidate].packageName === update.packageName);
+    if (key && appManifest.modules[key]) appManifest.modules[key].version = cleanVersion(update.to) || appManifest.modules[key].version;
+  }
+  for (const relativePath of plan.starterFilesToRefresh || []) {
+    if (!protectedPaths.has(relativePath) && appManifest.scaffoldFiles[relativePath] && await pathExists(path.join(targetDir, relativePath))) {
+      appManifest.scaffoldFiles[relativePath].hash = await hashFile(path.join(targetDir, relativePath));
+      appManifest.scaffoldFiles[relativePath].status = "current";
+    }
+  }
+  await writeAppManifest(targetDir, appManifest);
+  const packageChanged = plan.fileWrites.some((entry) => entry.relativePath === "package.json");
+  if (argvOptions.install && packageChanged) {
+    const runner = runtimeOptions.installRunner || runInstall;
+    await runner(plan.packageManager, plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : targetDir);
+  }
+  output.write(`Applied ${plan.fileWrites.length} managed change${plan.fileWrites.length === 1 ? "" : "s"} and ${migrationPlan.writes.length} migration${migrationPlan.writes.length === 1 ? "" : "s"}.\n`);
+  return { dryRun: false, plan, migrationPlan, drifted, missing };
+}
+
+export { HELP as UPGRADE_HELP };

package/template/base/app/globals.css

@@ -1,4 +1,5 @@
 @import "tailwindcss";
+@import "@brightweblabs/theme/css";
 
 :root {
   color-scheme: light;

package/template/base/config/bootstrap.ts

@@ -104,7 +104,7 @@ export function getStarterBootstrapChecklist() {
       {
         label: "Preview CRM module",
         done: hasModule(moduleKeys, "crm"),
-        detail: hasModule(moduleKeys, "crm") ? "/playground/crm" : "CRM not enabled",
+        detail: hasModule(moduleKeys, "crm") ? "/crm" : "CRM not enabled",
       },
       {
         label: "Preview Projects module",

package/template/base/config/modules.ts

@@ -26,7 +26,7 @@ export const starterModuleConfig: StarterModuleConfig[] = [
     description: "Contacts and CRM server/data layer, with marketing-adjacent operational data stored in Supabase.",
     enabled: true,
     packageName: "@brightweblabs/module-crm",
-    playgroundHref: "/playground/crm",
+    playgroundHref: "/crm",
     placement: "primary",
   },
   {

package/template/base/config/shell.overrides.ts

@@ -0,0 +1,16 @@
+import type { ShellRegistrationOverrides } from "@brightweblabs/app-shell";
+
+/**
+ * App-owned shell customizations. This scaffolded file is never overwritten by
+ * `create-bw-app update`.
+ *
+ * @example Rewrite a module href wherever it appears in its registration:
+ * ```ts
+ * import { overrideNavHref } from "@brightweblabs/app-shell";
+ *
+ * const overrides: ShellRegistrationOverrides = {
+ *   crm: (registration) => overrideNavHref(registration, "/admin/marketing", "/crm/marketing"),
+ * };
+ * ```
+ */
+export const shellRegistrationOverrides: ShellRegistrationOverrides = {};

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

@@ -24,7 +24,8 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 - `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.
+- `config/shell.ts`: managed app-shell registration and navigation wiring.
+- `config/shell.overrides.ts`: app-owned shell registration customizations preserved across updates.
 - `app/globals.css`: color tokens (raw brand + semantic mappings), typography, and global surface styling.
 - `app/page.tsx`: starter landing page for the generated app.
 - `app/bootstrap/page.tsx`: setup checklist surface.
@@ -38,7 +39,7 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 - Change colors and theme tokens in `app/globals.css`.
 - 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/shell.overrides.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

@@ -12,7 +12,7 @@ Goal: get the generated starter running with real credentials.
 - Review `config/modules.ts` before touching module routes.
 - Run the local dev server for this app or workspace.
 - Validate `/`, `/bootstrap`, `/preview/app-shell`, and `/playground/auth`.
-- Validate `/playground/crm`, `/playground/projects`, and `/playground/admin` only when those modules are enabled.
+- Validate `/crm`, `/playground/projects`, and `/playground/admin` only when those modules are enabled.
 
 ## Change brand identity
 
@@ -30,7 +30,7 @@ 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.
+- Update `config/shell.overrides.ts` if navigation or toolbar behavior changes.
 - Remove `/bootstrap`, `/preview/app-shell`, or `/playground/*` only after links and config references are cleaned up.
 
 ## Make a module-aware change

package/template/base/public/brand/logo-dark.svg

@@ -1,7 +1,7 @@
 <svg width="176" height="44" viewBox="0 0 176 44" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="44" height="44" rx="12" fill="#F5F4EC"/>
-  <path d="M12 30V14H21.72C25.24 14 27.68 16.08 27.68 19.24C27.68 21.78 26.22 23.63 23.99 24.32L29.3 30H24.9L20.15 24.86H15.8V30H12Z" fill="#102015"/>
-  <circle cx="32.5" cy="12.5" r="3.5" fill="#2C8A53"/>
+  <path d="M12 32V12H22.2C26.18 12 28.52 13.94 28.52 17.06C28.52 19.04 27.56 20.48 25.86 21.22C28.08 21.88 29.4 23.54 29.4 25.94C29.4 29.7 26.68 32 22.22 32H12ZM16.42 20.04H21.48C23.1 20.04 24.02 19.24 24.02 17.86C24.02 16.46 23.1 15.68 21.48 15.68H16.42V20.04ZM16.42 28.28H21.96C23.82 28.28 24.86 27.42 24.86 25.86C24.86 24.32 23.82 23.46 21.96 23.46H16.42V28.28Z" fill="#102015"/>
+  <path d="M30.2 12H34.58L36.72 23.86L39.32 12H43.1L39 32H34.88L32.38 19.64L29.9 32H25.82L25.1 28.56H29.1L30.2 12Z" fill="#2C8A53"/>
   <text x="58" y="19" fill="#F5F4EC" font-family="Georgia, serif" font-size="11" letter-spacing="2">BRIGHTWEB</text>
   <text x="58" y="33" fill="#C8D0C9" font-family="'IBM Plex Sans', sans-serif" font-size="15">starter client</text>
 </svg>

package/template/base/public/brand/logo-light.svg

@@ -1,7 +1,7 @@
 <svg width="176" height="44" viewBox="0 0 176 44" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="44" height="44" rx="12" fill="#13251A"/>
-  <path d="M12 30V14H21.72C25.24 14 27.68 16.08 27.68 19.24C27.68 21.78 26.22 23.63 23.99 24.32L29.3 30H24.9L20.15 24.86H15.8V30H12Z" fill="#F5F4EC"/>
-  <circle cx="32.5" cy="12.5" r="3.5" fill="#71C48B"/>
+  <path d="M12 32V12H22.2C26.18 12 28.52 13.94 28.52 17.06C28.52 19.04 27.56 20.48 25.86 21.22C28.08 21.88 29.4 23.54 29.4 25.94C29.4 29.7 26.68 32 22.22 32H12ZM16.42 20.04H21.48C23.1 20.04 24.02 19.24 24.02 17.86C24.02 16.46 23.1 15.68 21.48 15.68H16.42V20.04ZM16.42 28.28H21.96C23.82 28.28 24.86 27.42 24.86 25.86C24.86 24.32 23.82 23.46 21.96 23.46H16.42V28.28Z" fill="#F5F4EC"/>
+  <path d="M30.2 12H34.58L36.72 23.86L39.32 12H43.1L39 32H34.88L32.38 19.64L29.9 32H25.82L25.1 28.56H29.1L30.2 12Z" fill="#71C48B"/>
   <text x="58" y="19" fill="#13251A" font-family="Georgia, serif" font-size="11" letter-spacing="2">BRIGHTWEB</text>
   <text x="58" y="33" fill="#516252" font-family="'IBM Plex Sans', sans-serif" font-size="15">starter client</text>
 </svg>

package/template/base/public/brand/logo-mark.svg

@@ -1,5 +1,5 @@
 <svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="64" height="64" rx="18" fill="#13251A"/>
-  <path d="M19 42V22H31.8C36.4 22 39.6 24.7 39.6 28.8C39.6 32.1 37.7 34.5 34.8 35.4L41.8 42H36L29.7 36H24V42H19ZM24 31.9H31.1C33.5 31.9 34.7 30.8 34.7 29C34.7 27.2 33.5 26.1 31.1 26.1H24V31.9Z" fill="#F5F4EC"/>
-  <circle cx="46.5" cy="18.5" r="4.5" fill="#71C48B"/>
+  <path d="M15 44V20H28.02C32.8 20 35.76 22.42 35.76 26.24C35.76 28.58 34.62 30.28 32.58 31.18C35.22 32.02 36.84 34.04 36.84 36.86C36.84 41.36 33.42 44 28.02 44H15ZM20.36 29.58H27.08C29.08 29.58 30.24 28.62 30.24 26.96C30.24 25.3 29.08 24.36 27.08 24.36H20.36V29.58ZM20.36 39.62H27.64C29.98 39.62 31.28 38.56 31.28 36.68C31.28 34.84 29.98 33.78 27.64 33.78H20.36V39.62Z" fill="#F5F4EC"/>
+  <path d="M38.72 20H44.18L46.58 34.74L49.72 20H54.5L49.32 44H44.12L41.18 29.34L38.24 44H33.16L32.26 39.72H37.22L38.72 20Z" fill="#71C48B"/>
 </svg>

package/template/module-manifests/admin/brightweb.module.json

@@ -0,0 +1,6 @@
+{
+  "contractVersion": 1,
+  "key": "admin",
+  "requires": { "core": ">=0.3" },
+  "env": []
+}

package/template/module-manifests/crm/brightweb.module.json

@@ -0,0 +1,7 @@
+{
+  "contractVersion": 1,
+  "key": "crm",
+  "requires": { "core": ">=0.3", "admin": ">=0.3", "orgs": ">=0.1" },
+  "env": [],
+  "tokens": "./tokens.css"
+}

package/template/module-manifests/orgs/brightweb.module.json

@@ -0,0 +1,6 @@
+{
+  "contractVersion": 1,
+  "key": "orgs",
+  "requires": { "core": ">=0.3", "admin": ">=0.3" },
+  "env": []
+}

package/template/module-manifests/projects/brightweb.module.json

@@ -0,0 +1,6 @@
+{
+  "contractVersion": 1,
+  "key": "projects",
+  "requires": { "core": ">=0.3", "admin": ">=0.3", "orgs": ">=0.1" },
+  "env": []
+}

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

@@ -6,3 +6,13 @@ export const GET = createModuleRouteHandler(
   () => import("@brightweblabs/module-crm"),
   "handleCrmContactsGetRequest",
 );
+
+export const POST = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmContactsPostRequest",
+);
+
+export const PATCH = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmContactsPatchRequest",
+);

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

@@ -0,0 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
+export const dynamic = "force-dynamic";
+
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmTimelineGetRequest",
+);

package/template/modules/crm/app/crm/layout.tsx

@@ -0,0 +1,5 @@
+import "@brightweblabs/module-crm/tokens.css";
+
+export default function CrmLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+  return children;
+}

package/template/modules/crm/app/crm/page.tsx

@@ -0,0 +1,5 @@
+import { CrmDashboard } from "@brightweblabs/module-crm/ui";
+
+export default function CrmPage() {
+  return <CrmDashboard />;
+}