create-bw-app 0.9.0 → 0.9.1

package/README.md

@@ -2,6 +2,8 @@
 
 Scaffold a new BrightWeb app from either the `platform` or `site` starter.
 
+The CLI can also update an existing generated platform app in place.
+
 ## Workspace usage
 
 From the BrightWeb platform repo root:
@@ -21,9 +23,29 @@ Once this package is published to npm:
 ```bash
 pnpm dlx create-bw-app
 pnpm dlx create-bw-app --template site
+pnpm dlx create-bw-app update
 npm create bw-app@latest
 ```
 
+## Update existing apps
+
+Run the updater from an existing generated app directory, or point it at one with `--target-dir`:
+
+```bash
+pnpm dlx create-bw-app update
+pnpm dlx create-bw-app update --dry-run
+pnpm dlx create-bw-app update --refresh-starters
+pnpm dlx create-bw-app update --target-dir ./apps/client-portal
+```
+
+Current updater behavior:
+
+- updates installed `@brightweblabs/*` packages only
+- 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
+- preserves unrelated third-party dependencies and app-owned product pages
+
 ## Template behavior
 
 - prompts for app type: `platform` or `site`

package/package.json

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

package/src/cli.mjs

@@ -1,5 +1,6 @@
 import { HELP_TEXT } from "./constants.mjs";
 import { createBrightwebClientApp } from "./generator.mjs";
+import { updateBrightwebApp } from "./update.mjs";
 
 function toCamelCase(flagName) {
   return flagName.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
@@ -56,7 +57,8 @@ function parseArgv(argv) {
 }
 
 export async function runCreateBwAppCli(argv = process.argv.slice(2), runtimeOptions = {}) {
-  const argvOptions = parseArgv(argv);
+  const isUpdateCommand = argv[0] === "update";
+  const argvOptions = parseArgv(isUpdateCommand ? argv.slice(1) : argv);
 
   if (argvOptions.help) {
     process.stdout.write(`${HELP_TEXT}\n`);
@@ -64,6 +66,11 @@ export async function runCreateBwAppCli(argv = process.argv.slice(2), runtimeOpt
   }
 
   try {
+    if (isUpdateCommand) {
+      await updateBrightwebApp(argvOptions, runtimeOptions);
+      return;
+    }
+
     await createBrightwebClientApp(argvOptions, runtimeOptions);
   } catch (error) {
     const message = error instanceof Error ? error.message : "Unknown error";

package/src/constants.mjs

@@ -42,6 +42,29 @@ export const CORE_PACKAGES = [
   "@brightweblabs/ui",
 ];
 
+export const BRIGHTWEB_PACKAGE_NAMES = [
+  ...CORE_PACKAGES,
+  ...SELECTABLE_MODULES.map((moduleDefinition) => moduleDefinition.packageName),
+];
+
+export const MODULE_STARTER_FILES = {
+  admin: [
+    "app/api/admin/users/route.ts",
+    "app/api/admin/users/roles/route.ts",
+    "app/playground/admin/page.tsx",
+  ],
+  crm: [
+    "app/api/crm/contacts/route.ts",
+    "app/api/crm/organizations/route.ts",
+    "app/api/crm/owners/route.ts",
+    "app/api/crm/stats/route.ts",
+    "app/playground/crm/page.tsx",
+  ],
+  projects: [
+    "app/playground/projects/page.tsx",
+  ],
+};
+
 export const APP_DEPENDENCY_DEFAULTS = {
   "@brightweblabs/app-shell": "^0.1.1",
   "@brightweblabs/core-auth": "^0.1.1",
@@ -93,8 +116,9 @@ export const DEFAULTS = {
 export const HELP_TEXT = `
 Usage:
   create-bw-app [options]
+  create-bw-app update [options]
 
-Options:
+Scaffold options:
   --template <platform|site>    Scaffold a platform app or a standalone site
   --name, --slug <name>          Project name and default directory name
   --modules <list>               Comma-separated modules: crm,projects,admin
@@ -107,4 +131,12 @@ Options:
   --yes                          Accept defaults for any missing optional prompt
   --dry-run                      Print planned actions without writing files
   --help                         Show this help message
+
+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
+  --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
 `.trim();

package/src/generator.mjs

@@ -16,8 +16,8 @@ import {
   TEMPLATE_OPTIONS,
 } from "./constants.mjs";
 
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
 const TEMPLATE_KEY_SET = new Set(TEMPLATE_OPTIONS.map((templateOption) => templateOption.key));
 const DEFAULT_DB_MODULE_REGISTRY = {
   modules: {
@@ -77,7 +77,7 @@ function parseTemplateInput(rawValue) {
   throw new Error(`Unknown template: ${rawValue}`);
 }
 
-function detectPackageManager(explicitManager) {
+export function detectPackageManager(explicitManager) {
   if (explicitManager) return explicitManager;
 
   const userAgent = process.env.npm_config_user_agent || "";
@@ -88,13 +88,13 @@ function detectPackageManager(explicitManager) {
   return "pnpm";
 }
 
-function sortObjectKeys(inputObject) {
+export function sortObjectKeys(inputObject) {
   return Object.fromEntries(
     Object.entries(inputObject).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey)),
   );
 }
 
-async function pathExists(targetPath) {
+export async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
     return true;
@@ -103,7 +103,7 @@ async function pathExists(targetPath) {
   }
 }
 
-async function readJsonIfPresent(filePath) {
+export async function readJsonIfPresent(filePath) {
   if (!(await pathExists(filePath))) {
     return null;
   }
@@ -111,7 +111,7 @@ async function readJsonIfPresent(filePath) {
   return JSON.parse(await fs.readFile(filePath, "utf8"));
 }
 
-async function getDbModuleRegistry(workspaceRoot) {
+export async function getDbModuleRegistry(workspaceRoot) {
   if (!workspaceRoot) {
     return DEFAULT_DB_MODULE_REGISTRY;
   }
@@ -171,7 +171,7 @@ function getModuleLabel(moduleKey) {
   return titleizeSlug(moduleKey);
 }
 
-function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
+export function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
   if (!workspaceMode) {
     return {
       selectedLabels: getSelectedModuleLabels(selectedModules),
@@ -218,7 +218,7 @@ function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
   };
 }
 
-async function getVersionMap(workspaceRoot) {
+export async function getVersionMap(workspaceRoot) {
   const versionMap = {
     ...APP_DEPENDENCY_DEFAULTS,
     ...APP_DEV_DEPENDENCY_DEFAULTS,
@@ -294,7 +294,7 @@ function createPlatformBrandConfigFile({ slug, brandValues }) {
   ].join("\n");
 }
 
-function createPlatformModulesConfigFile(selectedModules) {
+export function createPlatformModulesConfigFile(selectedModules) {
   const selected = new Set(selectedModules);
 
   return [
@@ -515,7 +515,7 @@ function createSiteReadme({ slug, workspaceMode, packageManager }) {
   ].join("\n");
 }
 
-function createPackageJson({
+export function createPackageJson({
   slug,
   dependencyMode,
   selectedModules,
@@ -595,7 +595,7 @@ function createPackageJson({
   };
 }
 
-function createNextConfig({ template, selectedModules }) {
+export function createNextConfig({ template, selectedModules }) {
   if (template === "site") {
     return [
       'import type { NextConfig } from "next";',
@@ -629,7 +629,7 @@ function createNextConfig({ template, selectedModules }) {
   ].join("\n");
 }
 
-function createShellConfig(selectedModules) {
+export function createShellConfig(selectedModules) {
   const importLines = [];
   const registrationLines = [];
 
@@ -745,7 +745,7 @@ async function copyDirectory(sourceDir, targetDir) {
   await fs.cp(sourceDir, targetDir, { recursive: true });
 }
 
-async function ensureDirectory(targetDir) {
+export async function ensureDirectory(targetDir) {
   await fs.mkdir(targetDir, { recursive: true });
 }
 
@@ -793,7 +793,7 @@ async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
   );
 }
 
-async function runInstall(command, cwd) {
+export async function runInstall(command, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, ["install"], {
       cwd,
@@ -1140,7 +1140,8 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
 
   if (install) {
     const installCwd = workspaceMode ? workspaceRoot : targetDir;
-    await runInstall(packageManager, installCwd);
+    const installRunner = runtimeOptions.installRunner || runInstall;
+    await installRunner(packageManager, installCwd);
   }
 
   printCompletionMessage({

package/src/update.mjs

@@ -0,0 +1,481 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import {
+  BRIGHTWEB_PACKAGE_NAMES,
+  CLI_DISPLAY_NAME,
+  MODULE_STARTER_FILES,
+  SELECTABLE_MODULES,
+} from "./constants.mjs";
+import {
+  TEMPLATE_ROOT,
+  createDbInstallPlan,
+  createNextConfig,
+  createPackageJson,
+  createPlatformModulesConfigFile,
+  createShellConfig,
+  detectPackageManager,
+  getDbModuleRegistry,
+  getVersionMap,
+  pathExists,
+  readJsonIfPresent,
+  runInstall,
+} from "./generator.mjs";
+
+const MANAGED_PLATFORM_FILES = [
+  "next.config.ts",
+  path.join("config", "modules.ts"),
+  path.join("config", "shell.ts"),
+];
+
+function resolveUpdateTargetDirectory(runtimeOptions, argvOptions) {
+  if (runtimeOptions.targetDir || argvOptions.targetDir) {
+    return path.resolve(runtimeOptions.targetDir || argvOptions.targetDir);
+  }
+
+  return process.cwd();
+}
+
+async function findWorkspaceRoot(startDir) {
+  let currentDir = path.resolve(startDir);
+
+  while (true) {
+    const registryPath = path.join(currentDir, "supabase", "module-registry.json");
+    const cliPackagePath = path.join(currentDir, "packages", "create-bw-app", "package.json");
+
+    if ((await pathExists(registryPath)) && (await pathExists(cliPackagePath))) {
+      return currentDir;
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+
+    currentDir = parentDir;
+  }
+}
+
+function collectInstalledBrightwebPackages(manifest) {
+  const installed = new Map();
+
+  for (const section of ["dependencies", "devDependencies"]) {
+    const sectionManifest = manifest[section] || {};
+    for (const [packageName, version] of Object.entries(sectionManifest)) {
+      if (!packageName.startsWith("@brightweblabs/")) continue;
+      installed.set(packageName, { section, version });
+    }
+  }
+
+  return installed;
+}
+
+function parseConfiguredModules(content) {
+  const enabledModules = [];
+
+  for (const moduleDefinition of SELECTABLE_MODULES) {
+    const matcher = new RegExp(`key:\\s*"${moduleDefinition.key}"[\\s\\S]*?enabled:\\s*(true|false)`);
+    const match = content.match(matcher);
+    if (match?.[1] === "true") {
+      enabledModules.push(moduleDefinition.key);
+    }
+  }
+
+  return enabledModules;
+}
+
+async function detectTemplate(targetDir, installedBrightwebPackages) {
+  if (await pathExists(path.join(targetDir, "config", "modules.ts"))) {
+    return "platform";
+  }
+
+  return installedBrightwebPackages.size > 0 ? "platform" : "site";
+}
+
+function detectDependencyMode(installedBrightwebPackages) {
+  for (const { version } of installedBrightwebPackages.values()) {
+    if (typeof version === "string" && version.startsWith("workspace:")) {
+      return "workspace";
+    }
+  }
+
+  return "published";
+}
+
+function detectInstalledModules(installedBrightwebPackages) {
+  return SELECTABLE_MODULES
+    .filter((moduleDefinition) => installedBrightwebPackages.has(moduleDefinition.packageName))
+    .map((moduleDefinition) => moduleDefinition.key);
+}
+
+function getCanonicalBrightwebVersions({ manifest, template, dependencyMode, installedModules, versionMap }) {
+  const canonicalManifest = createPackageJson({
+    slug: manifest.name || path.basename(process.cwd()),
+    dependencyMode,
+    selectedModules: installedModules,
+    versionMap,
+    template,
+  });
+
+  const versions = {};
+
+  for (const section of ["dependencies", "devDependencies"]) {
+    for (const [packageName, version] of Object.entries(canonicalManifest[section] || {})) {
+      if (BRIGHTWEB_PACKAGE_NAMES.includes(packageName)) {
+        versions[packageName] = version;
+      }
+    }
+  }
+
+  return versions;
+}
+
+function mergeManagedPackageUpdates({ manifest, targetVersions, installedBrightwebPackages }) {
+  let changed = false;
+  const nextManifest = {
+    ...manifest,
+    dependencies: manifest.dependencies ? { ...manifest.dependencies } : undefined,
+    devDependencies: manifest.devDependencies ? { ...manifest.devDependencies } : undefined,
+  };
+  const packageUpdates = [];
+
+  for (const [packageName, details] of installedBrightwebPackages.entries()) {
+    if (!BRIGHTWEB_PACKAGE_NAMES.includes(packageName)) continue;
+    const targetVersion = targetVersions[packageName];
+    if (!targetVersion) continue;
+
+    const currentSection = nextManifest[details.section] || {};
+    if (currentSection[packageName] === targetVersion) continue;
+
+    currentSection[packageName] = targetVersion;
+    nextManifest[details.section] = currentSection;
+    packageUpdates.push({
+      packageName,
+      from: details.version,
+      to: targetVersion,
+      section: details.section,
+    });
+    changed = true;
+  }
+
+  return {
+    changed,
+    packageUpdates,
+    content: `${JSON.stringify(nextManifest, null, 2)}\n`,
+  };
+}
+
+async function getStarterFileStatus(targetDir, installedModules) {
+  const starterFiles = [];
+
+  for (const moduleKey of installedModules) {
+    const templateFolder = SELECTABLE_MODULES.find((moduleDefinition) => moduleDefinition.key === moduleKey)?.templateFolder;
+    if (!templateFolder) continue;
+
+    for (const relativePath of MODULE_STARTER_FILES[moduleKey] || []) {
+      const sourcePath = path.join(TEMPLATE_ROOT, "modules", templateFolder, relativePath);
+      const targetPath = path.join(targetDir, relativePath);
+      const exists = await pathExists(targetPath);
+
+      if (!exists) {
+        starterFiles.push({
+          moduleKey,
+          relativePath,
+          sourcePath,
+          targetPath,
+          status: "missing",
+        });
+        continue;
+      }
+
+      const [sourceContent, targetContent] = await Promise.all([
+        fs.readFile(sourcePath, "utf8"),
+        fs.readFile(targetPath, "utf8"),
+      ]);
+
+      starterFiles.push({
+        moduleKey,
+        relativePath,
+        sourcePath,
+        targetPath,
+        status: sourceContent === targetContent ? "current" : "drifted",
+      });
+    }
+  }
+
+  return starterFiles;
+}
+
+async function detectModulesConfigMismatch(targetDir, installedModules) {
+  const modulesConfigPath = path.join(targetDir, "config", "modules.ts");
+  if (!(await pathExists(modulesConfigPath))) {
+    return null;
+  }
+
+  const content = await fs.readFile(modulesConfigPath, "utf8");
+  const configuredModules = parseConfiguredModules(content);
+  const installed = new Set(installedModules);
+  const configured = new Set(configuredModules);
+
+  const mismatch = installedModules.length !== configuredModules.length
+    || installedModules.some((moduleKey) => !configured.has(moduleKey))
+    || configuredModules.some((moduleKey) => !installed.has(moduleKey));
+
+  if (!mismatch) {
+    return null;
+  }
+
+  return {
+    installedModules,
+    configuredModules,
+  };
+}
+
+function renderInstallCommand({ packageManager, dependencyMode, targetDir, workspaceRoot }) {
+  if (dependencyMode === "workspace" && workspaceRoot) {
+    return `cd ${workspaceRoot} && ${packageManager} install`;
+  }
+
+  return `cd ${targetDir} && ${packageManager} install`;
+}
+
+function renderPlanSummary(plan, options = {}) {
+  const lines = [
+    `${CLI_DISPLAY_NAME} update`,
+    "",
+    `Detected app type: ${plan.template}`,
+    `Dependency mode: ${plan.dependencyMode}`,
+    `Installed BrightWeb packages: ${plan.installedBrightwebPackages.length > 0 ? plan.installedBrightwebPackages.join(", ") : "none"}`,
+    `Installed modules: ${plan.installedModules.length > 0 ? plan.installedModules.join(", ") : "none"}`,
+  ];
+
+  if (plan.modulesConfigMismatch) {
+    lines.push(
+      `Config mismatch: installed modules (${plan.modulesConfigMismatch.installedModules.join(", ") || "none"}) differ from config/modules.ts (${plan.modulesConfigMismatch.configuredModules.join(", ") || "none"}). Using installed packages as source of truth.`,
+    );
+  }
+
+  lines.push("");
+
+  if (plan.packageUpdates.length > 0) {
+    lines.push("Packages to update:");
+    for (const update of plan.packageUpdates) {
+      lines.push(`- ${update.packageName}: ${update.from} -> ${update.to}`);
+    }
+  } else {
+    lines.push("Packages to update: none");
+  }
+
+  lines.push("");
+
+  if (plan.configFilesToWrite.length > 0) {
+    lines.push("Config files to rewrite:");
+    for (const relativePath of plan.configFilesToWrite) {
+      lines.push(`- ${relativePath}`);
+    }
+  } else {
+    lines.push("Config files to rewrite: none");
+  }
+
+  lines.push("");
+
+  if (plan.starterFilesMissing.length > 0 || plan.starterFilesDrifted.length > 0) {
+    lines.push("Starter file status:");
+    for (const relativePath of plan.starterFilesMissing) {
+      lines.push(`- missing: ${relativePath}`);
+    }
+    for (const relativePath of plan.starterFilesDrifted) {
+      lines.push(`- drifted: ${relativePath}`);
+    }
+  } else {
+    lines.push("Starter file status: all current");
+  }
+
+  lines.push("");
+
+  if (plan.dbInstallPlan.resolvedOrder.length > 0) {
+    lines.push(`Resolved database stack: ${plan.dbInstallPlan.resolvedOrder.join(" -> ")}`);
+  }
+
+  if (plan.dbInstallPlan.notes.length > 0) {
+    lines.push("Database notes:");
+    for (const note of plan.dbInstallPlan.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+
+  if (options.installCommand) {
+    lines.push("", `Next install command: ${options.installCommand}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptions = {}) {
+  const targetDir = resolveUpdateTargetDirectory(runtimeOptions, argvOptions);
+  const packageJsonPath = path.join(targetDir, "package.json");
+  const manifest = await readJsonIfPresent(packageJsonPath);
+
+  if (!manifest) {
+    throw new Error(`Target directory does not contain package.json: ${targetDir}`);
+  }
+
+  const installedBrightwebPackagesMap = collectInstalledBrightwebPackages(manifest);
+  const template = await detectTemplate(targetDir, installedBrightwebPackagesMap);
+  const dependencyMode = detectDependencyMode(installedBrightwebPackagesMap);
+  const workspaceRoot = runtimeOptions.workspaceRoot
+    ? path.resolve(runtimeOptions.workspaceRoot)
+    : argvOptions.workspaceRoot
+      ? path.resolve(argvOptions.workspaceRoot)
+      : dependencyMode === "workspace"
+        ? await findWorkspaceRoot(targetDir)
+        : null;
+  const packageManager = detectPackageManager(argvOptions.packageManager || runtimeOptions.packageManager);
+  const installedModules = detectInstalledModules(installedBrightwebPackagesMap);
+  const versionMap = await getVersionMap(workspaceRoot);
+  const dbRegistry = await getDbModuleRegistry(workspaceRoot);
+  const dbInstallPlan = template === "platform"
+    ? createDbInstallPlan({
+      selectedModules: installedModules,
+      workspaceMode: true,
+      registry: dbRegistry,
+    })
+    : {
+      selectedLabels: [],
+      resolvedOrder: [],
+      notes: [],
+    };
+  const canonicalVersions = getCanonicalBrightwebVersions({
+    manifest,
+    template,
+    dependencyMode,
+    installedModules,
+    versionMap,
+  });
+  const packageJsonUpdate = mergeManagedPackageUpdates({
+    manifest,
+    targetVersions: canonicalVersions,
+    installedBrightwebPackages: installedBrightwebPackagesMap,
+  });
+
+  const fileWrites = [];
+  if (packageJsonUpdate.changed) {
+    fileWrites.push({
+      relativePath: "package.json",
+      targetPath: packageJsonPath,
+      content: packageJsonUpdate.content,
+      type: "config",
+    });
+  }
+
+  if (template === "platform") {
+    const canonicalConfigFiles = {
+      "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModules }),
+      [path.join("config", "modules.ts")]: createPlatformModulesConfigFile(installedModules),
+      [path.join("config", "shell.ts")]: createShellConfig(installedModules),
+    };
+
+    for (const relativePath of MANAGED_PLATFORM_FILES) {
+      const targetPath = path.join(targetDir, relativePath);
+      const currentContent = (await pathExists(targetPath)) ? await fs.readFile(targetPath, "utf8") : null;
+      const nextContent = canonicalConfigFiles[relativePath];
+
+      if (currentContent !== nextContent) {
+        fileWrites.push({
+          relativePath,
+          targetPath,
+          content: nextContent,
+          type: "config",
+        });
+      }
+    }
+  }
+
+  const starterFiles = template === "platform"
+    ? await getStarterFileStatus(targetDir, installedModules)
+    : [];
+  const starterFilesMissing = starterFiles.filter((entry) => entry.status === "missing");
+  const starterFilesDrifted = starterFiles.filter((entry) => entry.status === "drifted");
+
+  if (argvOptions.refreshStarters) {
+    for (const entry of starterFiles.filter((candidate) => candidate.status !== "current")) {
+      fileWrites.push({
+        relativePath: entry.relativePath,
+        targetPath: entry.targetPath,
+        content: await fs.readFile(entry.sourcePath, "utf8"),
+        type: "starter",
+      });
+    }
+  }
+
+  const modulesConfigMismatch = template === "platform"
+    ? await detectModulesConfigMismatch(targetDir, installedModules)
+    : null;
+
+  return {
+    targetDir,
+    workspaceRoot,
+    template,
+    dependencyMode,
+    packageManager,
+    manifest,
+    installedModules,
+    installedBrightwebPackages: Array.from(installedBrightwebPackagesMap.keys()).sort(),
+    packageUpdates: packageJsonUpdate.packageUpdates,
+    configFilesToWrite: fileWrites.filter((entry) => entry.type === "config").map((entry) => entry.relativePath),
+    starterFilesMissing: starterFilesMissing.map((entry) => entry.relativePath),
+    starterFilesDrifted: starterFilesDrifted.map((entry) => entry.relativePath),
+    starterFilesToRefresh: fileWrites.filter((entry) => entry.type === "starter").map((entry) => entry.relativePath),
+    dbInstallPlan,
+    modulesConfigMismatch,
+    fileWrites,
+  };
+}
+
+export async function updateBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
+  const plan = await buildBrightwebAppUpdatePlan(argvOptions, runtimeOptions);
+  const installCommand = renderInstallCommand({
+    packageManager: plan.packageManager,
+    dependencyMode: plan.dependencyMode,
+    targetDir: plan.targetDir,
+    workspaceRoot: plan.workspaceRoot,
+  });
+
+  output.write(renderPlanSummary(plan, { installCommand }));
+
+  if (argvOptions.dryRun) {
+    return {
+      dryRun: true,
+      plan,
+      installCommand,
+    };
+  }
+
+  for (const fileWrite of plan.fileWrites) {
+    await fs.mkdir(path.dirname(fileWrite.targetPath), { recursive: true });
+    await fs.writeFile(fileWrite.targetPath, fileWrite.content, "utf8");
+  }
+
+  const packageJsonChanged = plan.fileWrites.some((entry) => entry.relativePath === "package.json");
+  if (argvOptions.install && packageJsonChanged) {
+    const installRunner = runtimeOptions.installRunner || runInstall;
+    const installCwd = plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : plan.targetDir;
+    await installRunner(plan.packageManager, installCwd);
+  }
+
+  if (!argvOptions.install && packageJsonChanged) {
+    output.write(`Run \`${installCommand}\` to install updated package versions.\n`);
+  }
+
+  if (plan.fileWrites.length === 0) {
+    output.write("No managed changes were required.\n");
+  } else {
+    output.write(`Applied ${plan.fileWrites.length} managed change${plan.fileWrites.length === 1 ? "" : "s"}.\n`);
+  }
+
+  return {
+    dryRun: false,
+    plan,
+    installCommand,
+  };
+}