create-bw-app 0.10.1 → 0.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 Scaffold a new BrightWeb app from either the `platform` or `site` starter.
 
-The CLI can also update an existing generated platform app in place.
+The package also installs the `bw` lifecycle CLI for generated apps.
 
 ## Workspace usage
 
@@ -27,6 +27,19 @@ pnpm dlx create-bw-app update
 npm create bw-app@latest
 ```
 
+From a generated app, use `bw` to manage the machine-readable `.brightweb/app-manifest.json` contract:
+
+```bash
+bw add projects
+bw upgrade
+bw doctor
+```
+
+- `bw add <moduleKey>` resolves requirements, installs module wiring and starter overlays, and appends migrations.
+- `bw upgrade [moduleKey]` includes the existing managed update flow plus forward-only module migrations.
+- `bw doctor` checks package, config, scaffold, environment-name, and migration consistency. Add `--report` to stamp the result in the app manifest.
+- All mutating commands support `--dry-run`.
+
 ## Update existing apps
 
 Run the updater from an existing generated app directory, or point it at one with `--target-dir`:
@@ -44,6 +57,7 @@ Current updater behavior:
 - 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`
+- preserves app-owned shell customizations in the scaffolded `config/shell.overrides.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
@@ -63,6 +77,7 @@ Current updater behavior:
 - 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
 - site apps also write `AGENTS.md`, `docs/ai/README.md`, `docs/ai/examples.md`, and `docs/ai/app-context.json` for app-local AI handoff
 - supports repo-local `workspace:*` wiring and future published dependency wiring
+- writes `.brightweb/app-manifest.json` as the machine-authoritative scaffold and module record
 
 ## Workspace mode extras
 

package/bin/bw.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runBwCli } from "../src/bw.mjs";
+
+runBwCli(process.argv.slice(2)).catch((error) => {
+  console.error(`\nbw failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.10.1",
+  "version": "0.12.0",
   "type": "module",
-  "bin": "bin/create-bw-app.mjs",
+  "bin": {
+    "create-bw-app": "bin/create-bw-app.mjs",
+    "bw": "bin/bw.mjs"
+  },
   "files": [
     "bin",
     "src",

package/src/add.mjs

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { SELECTABLE_MODULES } from "./constants.mjs";
+import { TEMPLATE_ROOT, createAppContextFile, createDbInstallPlan, createNextConfig, createPlatformModulesConfigFile, createShellConfig, getDbModuleRegistry, getVersionMap, pathExists, readJsonIfPresent } from "./generator.mjs";
+import { collectScaffoldFiles, findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, resolveModuleClosure, satisfiesVersion, writeAppManifest } from "./app-manifest.mjs";
+import { applyMigrationWrites, planMigrationAppends } from "./migrations.mjs";
+
+const HELP = `Usage: bw add <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 install plan without writing\n  --help                    Show this help`;
+
+export async function addBrightwebModule(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.app.template !== "platform") throw new Error("bw add is only available for platform apps.");
+  const packageJsonPath = path.join(targetDir, "package.json");
+  const packageJson = await readJsonIfPresent(packageJsonPath);
+  if (!packageJson) throw new Error(`Target directory does not contain package.json: ${targetDir}`);
+  const workspaceRootCandidate = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const workspaceRoot = workspaceRootCandidate ? path.resolve(workspaceRootCandidate) : null;
+  const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
+  if (!catalog[moduleKey] || moduleKey === "core") throw new Error(`Unknown installable module key: ${moduleKey}`);
+
+  const resolved = resolveModuleClosure(catalog, [moduleKey]);
+  const installedVersions = { core: catalog.core.version, admin: catalog.admin.version };
+  for (const [key, entry] of Object.entries(appManifest.modules)) installedVersions[key] = entry.version;
+  const conflicts = [];
+  for (const key of resolved) {
+    for (const [requiredKey, range] of Object.entries(catalog[key].requires || {})) {
+      if (installedVersions[requiredKey] && !satisfiesVersion(installedVersions[requiredKey], range)) conflicts.push(`${key} requires ${requiredKey}@${range}, but ${requiredKey}@${installedVersions[requiredKey]} is installed`);
+    }
+  }
+  if (conflicts.length > 0) {
+    let compatibility = "Compatibility-set check skipped (published mode).";
+    if (workspaceRoot) {
+      const release = await readJsonIfPresent(path.join(workspaceRoot, "brightweb-release.json"));
+      compatibility = `Compatibility set: ${JSON.stringify(release?.packages || {})}`;
+    }
+    throw new Error(`Module version conflict:\n- ${conflicts.join("\n- ")}\n${compatibility}`);
+  }
+
+  const newModules = resolved.filter((key) => !appManifest.modules[key]);
+  const versionMap = await getVersionMap(workspaceRoot);
+  const dependencyMode = Object.values(packageJson.dependencies || {}).some((value) => String(value).startsWith("workspace:")) ? "workspace" : "published";
+  const nextPackageJson = structuredClone(packageJson);
+  nextPackageJson.dependencies ||= {};
+  for (const key of newModules) {
+    const packageName = MODULE_PACKAGES[key];
+    if (!packageName) continue;
+    nextPackageJson.dependencies[packageName] = dependencyMode === "workspace" ? "workspace:*" : versionMap[packageName];
+  }
+  nextPackageJson.dependencies = Object.fromEntries(Object.entries(nextPackageJson.dependencies).sort(([a], [b]) => a.localeCompare(b)));
+
+  const installedModuleKeys = Array.from(new Set([...Object.keys(appManifest.modules), ...newModules]));
+  const dbRegistry = await getDbModuleRegistry(workspaceRoot);
+  const dbInstallPlan = createDbInstallPlan({ selectedModules: installedModuleKeys.filter((key) => key !== "orgs"), workspaceMode: dependencyMode === "workspace", registry: dbRegistry });
+  const migrationPlan = await planMigrationAppends({ targetDir, moduleKeys: newModules, catalog, migrationCursor: appManifest.migrationCursor });
+  const overlays = [];
+  for (const key of newModules) {
+    const definition = SELECTABLE_MODULES.find((entry) => entry.key === key);
+    if (definition && await pathExists(path.join(TEMPLATE_ROOT, "modules", definition.templateFolder))) overlays.push({ key, source: path.join(TEMPLATE_ROOT, "modules", definition.templateFolder) });
+  }
+  const managedWrites = {
+    "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModuleKeys }),
+    "config/modules.ts": createPlatformModulesConfigFile(installedModuleKeys),
+    "config/shell.ts": createShellConfig(installedModuleKeys),
+    "docs/ai/app-context.json": createAppContextFile({ slug: appManifest.app.slug, template: "platform", selectedModules: installedModuleKeys.filter((key) => key !== "orgs"), dbInstallPlan }),
+  };
+
+  const summary = [
+    "bw add",
+    `Modules to install: ${newModules.join(" -> ") || "none"}`,
+    `Migrations to append: ${migrationPlan.writes.map((entry) => entry.targetFileName).join(", ") || "none"}`,
+    `Files to write: ${[...(newModules.length ? ["package.json"] : []), ...Object.keys(managedWrites), ...overlays.map((entry) => `template/modules/${entry.key}`)].join(", ") || "none"}`,
+  ];
+  if (!workspaceRoot) summary.push("WARN Compatibility-set check skipped in published mode.");
+  output.write(`${summary.join("\n")}\n`);
+  if (argvOptions.dryRun) return { dryRun: true, newModules, migrationPlan };
+
+  if (newModules.length > 0) await fs.writeFile(packageJsonPath, `${JSON.stringify(nextPackageJson, null, 2)}\n`, "utf8");
+  for (const overlay of overlays) await fs.cp(overlay.source, targetDir, { recursive: true });
+  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");
+  }
+  await applyMigrationWrites(migrationPlan.writes);
+  const now = new Date().toISOString();
+  for (const key of newModules) appManifest.modules[key] = { version: catalog[key].version, installedAt: now, exposed: true };
+  appManifest.migrationCursor = migrationPlan.nextCursor;
+  const collectedScaffoldFiles = await collectScaffoldFiles(targetDir, installedModuleKeys);
+  appManifest.scaffoldFiles = { ...collectedScaffoldFiles, ...appManifest.scaffoldFiles };
+  await writeAppManifest(targetDir, appManifest);
+  output.write(`Installed ${newModules.length} module${newModules.length === 1 ? "" : "s"}. ${migrationPlan.writes.length > 0 ? "Run your Supabase migration apply command. " : ""}Run your package manager install command next.\n`);
+  return { dryRun: false, newModules, migrationPlan };
+}
+
+export { HELP as ADD_HELP };

package/src/adopt.mjs

@@ -0,0 +1,190 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { fileURLToPath } from "node:url";
+import {
+  APP_MANIFEST_PATH,
+  MANAGED_APP_FILES,
+  MODULE_PACKAGES,
+  cleanVersion,
+  findWorkspaceRoot,
+  loadModuleCatalog,
+  readConfiguredModuleFlags,
+  writeAppManifest,
+} from "./app-manifest.mjs";
+import { pathExists, readJsonIfPresent } from "./generator.mjs";
+import { findAppMigrationsDirectory, getModuleMigrations } from "./migrations.mjs";
+import { inventoryScaffoldFiles, resolveTemplateRoot } from "./scaffold.mjs";
+import { detectDependencyMode, detectTemplate } from "./update.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const HELP = `Usage: bw adopt [options]\n\nOptions:\n  --target-dir <path>                 App directory (defaults to cwd)\n  --workspace-root <path>             BrightWeb workspace root\n  --cursor <key>=<migrationFilename>  Override a migration cursor (repeatable)\n  --owned-surface <name>              Record an app-owned surface (repeatable)\n  --own <path>                        Mark an existing scaffold file app-owned (repeatable)\n  --skip <path>                       Mark a missing scaffold file intentionally absent (repeatable)\n  --allow-uncursored                   Allow doctor to warn instead of fail on null cursors\n  --force                              Replace an existing app manifest\n  --dry-run                            Print the manifest and warnings without writing\n  --help                               Show this help`;
+
+function asList(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function parseCursorOverrides(values) {
+  const overrides = {};
+  for (const value of asList(values)) {
+    const separator = String(value).indexOf("=");
+    if (separator < 1 || separator === String(value).length - 1) throw new Error(`Invalid --cursor value: ${value}. Expected <key>=<migrationFilename>.`);
+    overrides[String(value).slice(0, separator)] = String(value).slice(separator + 1);
+  }
+  return overrides;
+}
+
+async function migrationFiles(targetDir) {
+  const directory = await findAppMigrationsDirectory(targetDir);
+  if (!(await pathExists(directory))) return [];
+  const files = [];
+  for (const fileName of (await fs.readdir(directory)).filter((entry) => entry.endsWith(".sql")).sort()) {
+    files.push({ fileName, content: await fs.readFile(path.join(directory, fileName), "utf8") });
+  }
+  return files;
+}
+
+function latestShippedMatch(shipped, predicate) {
+  return shipped.filter((entry) => predicate(entry.fileName)).at(-1)?.fileName || null;
+}
+
+function leadingBaselineDomain(content) {
+  const line = content.split(/\r?\n/).find((entry) => entry.trim().length > 0);
+  return line?.match(/^\s*--\s*Brightweb\s+(.+?)\s+v1\s+baseline\.?\s*$/i)?.[1]?.trim().toLowerCase() || null;
+}
+
+async function bootstrapCursor({ moduleKey, catalogEntry, appMigrations, override, warnings }) {
+  const shipped = await getModuleMigrations(moduleKey, catalogEntry);
+  if (shipped.length === 0) return { shipsMigrations: false, cursor: undefined, strategy: "none" };
+  if (override) {
+    if (!shipped.some((entry) => entry.fileName === override)) throw new Error(`Cursor override for ${moduleKey} does not name a shipped migration: ${override}`);
+    return { shipsMigrations: true, cursor: override, strategy: "override" };
+  }
+
+  const escapedKey = moduleKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const provenance = latestShippedMatch(shipped, (shippedName) => appMigrations.some(({ content }) => {
+    const match = content.match(new RegExp(`^\\s*--\\s*bw-module:\\s*${escapedKey}@[^\\s]+\\s+([^\\s]+)`, "im"));
+    return match?.[1] === shippedName;
+  }));
+  if (provenance) return { shipsMigrations: true, cursor: provenance, strategy: "provenance" };
+
+  const filename = latestShippedMatch(shipped, (shippedName) => appMigrations.some(({ fileName }) =>
+    fileName.endsWith(`_${moduleKey}__${shippedName}`)));
+  if (filename) return { shipsMigrations: true, cursor: filename, strategy: "filename" };
+
+  const domains = new Set([moduleKey.toLowerCase(), catalogEntry?.manifest?.title?.toLowerCase()].filter(Boolean));
+  const baselineFound = appMigrations.some(({ content }) => domains.has(leadingBaselineDomain(content)));
+  if (baselineFound) {
+    const v1 = shipped.filter((entry) => /(?:^|_)v1(?:_|\.sql$)/i.test(entry.fileName));
+    const cursor = (v1.length > 0 ? v1 : shipped.slice(0, 1)).at(-1).fileName;
+    const later = shipped.filter((entry) => entry.fileName > cursor).map((entry) => entry.fileName);
+    warnings.push(`WARN ${moduleKey}: baseline header matched; cursor set to ${cursor}.${later.length ? ` Later package migrations are UNAPPLIED and the next bw upgrade will plan: ${later.join(", ")}.` : ""}`);
+    return { shipsMigrations: true, cursor, strategy: "baseline-header" };
+  }
+
+  warnings.push(`WARN BLOCKED ${moduleKey}: no migration provenance, filename, or baseline-header match. Cursor is null; module migration upgrades are blocked until a cursor is set.`);
+  return { shipsMigrations: true, cursor: null, strategy: "uncursored" };
+}
+
+export async function adoptBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
+  if (argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const existingManifestPath = path.join(targetDir, APP_MANIFEST_PATH);
+  if (await pathExists(existingManifestPath) && !argvOptions.force) throw new Error(`Refusing to overwrite existing ${APP_MANIFEST_PATH}; pass --force to replace it.`);
+  const packageJson = await readJsonIfPresent(path.join(targetDir, "package.json"));
+  if (!packageJson) throw new Error(`Target directory does not contain package.json: ${targetDir}`);
+
+  const dependencies = { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) };
+  const installedBrightwebPackages = new Map(Object.entries(dependencies)
+    .filter(([name]) => name.startsWith("@brightweblabs/"))
+    .map(([name, version]) => [name, { version }]));
+  const template = await detectTemplate(targetDir, installedBrightwebPackages);
+  const dependencyMode = detectDependencyMode(installedBrightwebPackages);
+  const workspaceRootCandidate = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const workspaceRoot = workspaceRootCandidate ? path.resolve(workspaceRootCandidate) : null;
+  const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
+  const warnings = [];
+  const now = (runtimeOptions.now ? new Date(runtimeOptions.now) : new Date()).toISOString();
+  const flags = await readConfiguredModuleFlags(targetDir);
+  const modules = {};
+  for (const [moduleKey, packageName] of Object.entries(MODULE_PACKAGES)) {
+    if (!dependencies[packageName]) continue;
+    const exposed = typeof flags[moduleKey] === "boolean" ? flags[moduleKey] : true;
+    if (typeof flags[moduleKey] !== "boolean") warnings.push(`WARN ${moduleKey}: config/modules.ts exposure was not parseable; defaulting exposed=true.`);
+    modules[moduleKey] = {
+      version: cleanVersion(dependencies[packageName]) || catalog[moduleKey]?.version,
+      installedAt: now,
+      exposed,
+    };
+  }
+
+  const templateRoot = await resolveTemplateRoot({ targetDir, workspaceRoot });
+  const scaffold = template === "platform"
+    ? await inventoryScaffoldFiles({ targetDir, moduleKeys: Object.keys(modules), templateRoot })
+    : { records: {}, unsupported: [] };
+  const ownedPaths = new Set(asList(argvOptions.own).map(String));
+  const skippedPaths = new Set(asList(argvOptions.skip).map(String));
+  for (const relativePath of [...ownedPaths, ...skippedPaths]) {
+    if (!scaffold.records[relativePath]) throw new Error(`${relativePath} is not a tracked scaffold file.`);
+  }
+  for (const relativePath of ownedPaths) {
+    if (skippedPaths.has(relativePath)) throw new Error(`${relativePath} cannot be both --own and --skip.`);
+    if (scaffold.records[relativePath].status === "missing") throw new Error(`Cannot own missing scaffold file: ${relativePath}`);
+    scaffold.records[relativePath].intent = "owned";
+  }
+  for (const relativePath of skippedPaths) {
+    if (scaffold.records[relativePath].status !== "missing") throw new Error(`Cannot skip existing scaffold file: ${relativePath}`);
+    scaffold.records[relativePath].intent = "skipped";
+  }
+  for (const relativePath of scaffold.unsupported) warnings.push(`WARN ${relativePath}: installed-version template is unavailable; scaffold comparison is unsupported.`);
+  for (const [relativePath, record] of Object.entries(scaffold.records)) {
+    if (record.status === "drifted" && record.intent !== "owned") warnings.push(`WARN drifted scaffold file: ${relativePath}`);
+    if (record.status === "missing" && record.intent !== "skipped") warnings.push(`WARN missing scaffold file: ${relativePath} (not created; use bw diff and the current template as guidance).`);
+  }
+
+  const overrides = parseCursorOverrides(argvOptions.cursor);
+  const unknownOverride = Object.keys(overrides).find((key) => !catalog[key]);
+  if (unknownOverride) throw new Error(`Unknown module key in --cursor: ${unknownOverride}`);
+  const appMigrations = template === "platform" ? await migrationFiles(targetDir) : [];
+  const migrationCursor = {};
+  const cursorStrategies = {};
+  const migrationKeys = template === "platform" ? Array.from(new Set(["core", "admin", ...Object.keys(modules)])) : [];
+  for (const moduleKey of migrationKeys) {
+    const result = await bootstrapCursor({ moduleKey, catalogEntry: catalog[moduleKey], appMigrations, override: overrides[moduleKey], warnings });
+    if (result.shipsMigrations) {
+      migrationCursor[moduleKey] = result.cursor;
+      cursorStrategies[moduleKey] = result.strategy;
+    }
+  }
+
+  const cliPackage = await readJsonIfPresent(path.join(PACKAGE_ROOT, "package.json"));
+  const manifest = {
+    contractVersion: 1,
+    app: {
+      slug: packageJson.name || path.basename(targetDir),
+      template,
+      scaffoldedWith: `create-bw-app@${cliPackage?.version || "unknown"}`,
+      dependencyMode,
+      adoptedAt: now,
+    },
+    modules,
+    scaffoldFiles: scaffold.records,
+    managedFiles: template === "platform" ? MANAGED_APP_FILES : ["docs/ai/app-context.json"],
+    migrationCursor,
+    ownedSurfaces: Array.from(new Set(asList(argvOptions.ownedSurface).map(String))),
+    adoptionNotes: {
+      allowUncursored: argvOptions.allowUncursored === true,
+      cursorStrategies,
+    },
+  };
+
+  output.write(`bw adopt${argvOptions.dryRun ? " --dry-run" : ""}\n${JSON.stringify(manifest, null, 2)}\n`);
+  for (const warning of warnings) output.write(`${warning}\n`);
+  if (argvOptions.dryRun) return { dryRun: true, manifest, warnings };
+  await writeAppManifest(targetDir, manifest);
+  output.write(`Adopted ${manifest.app.slug}; wrote ${APP_MANIFEST_PATH}. No migration files or database objects were changed.\n`);
+  return { dryRun: false, manifest, warnings };
+}
+
+export { HELP as ADOPT_HELP };

package/src/app-manifest.mjs

@@ -0,0 +1,257 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { APP_DEPENDENCY_DEFAULTS, MODULE_STARTER_FILES, PLATFORM_STARTER_FILES, SELECTABLE_MODULES } from "./constants.mjs";
+
+const TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "template");
+
+async function pathExists(targetPath) {
+  try { await fs.access(targetPath); return true; } catch { return false; }
+}
+
+async function readJsonIfPresent(filePath) {
+  if (!(await pathExists(filePath))) return null;
+  return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
+export const APP_MANIFEST_PATH = path.join(".brightweb", "app-manifest.json");
+export const MANAGED_APP_FILES = [
+  "next.config.ts",
+  "config/modules.ts",
+  "config/shell.ts",
+  "docs/ai/app-context.json",
+];
+
+export const MODULE_PACKAGES = {
+  admin: "@brightweblabs/module-admin",
+  crm: "@brightweblabs/module-crm",
+  orgs: "@brightweblabs/module-orgs",
+  projects: "@brightweblabs/module-projects",
+};
+
+const FALLBACK_REQUIRES = {
+  core: {},
+  admin: { core: ">=0.3" },
+  orgs: { core: ">=0.3", admin: ">=0.3" },
+  crm: { core: ">=0.3", admin: ">=0.3", orgs: ">=0.1" },
+  projects: { core: ">=0.3", admin: ">=0.3", orgs: ">=0.1" },
+};
+
+export function cleanVersion(version) {
+  if (typeof version !== "string") return null;
+  const match = version.match(/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+  return match?.[1] || null;
+}
+
+function compareVersions(left, right) {
+  const a = cleanVersion(left)?.split("-")[0].split(".").map(Number) || [];
+  const b = cleanVersion(right)?.split("-")[0].split(".").map(Number) || [];
+  for (let index = 0; index < 3; index += 1) {
+    if ((a[index] || 0) !== (b[index] || 0)) return (a[index] || 0) - (b[index] || 0);
+  }
+  return 0;
+}
+
+export function satisfiesVersion(version, range) {
+  const normalized = cleanVersion(version);
+  if (!normalized || typeof range !== "string") return false;
+  if (range === "*" || range === "workspace:*") return true;
+  const expectedMatch = range.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  const expected = expectedMatch ? `${expectedMatch[1]}.${expectedMatch[2] || "0"}.${expectedMatch[3] || "0"}` : null;
+  if (!expected) return false;
+  if (range.trim().startsWith(">=")) return compareVersions(normalized, expected) >= 0;
+  if (range.trim().startsWith("^")) {
+    return normalized.split(".")[0] === expected.split(".")[0] && compareVersions(normalized, expected) >= 0;
+  }
+  if (range.trim().startsWith("~")) {
+    const actualParts = normalized.split(".");
+    const expectedParts = expected.split(".");
+    return actualParts[0] === expectedParts[0] && actualParts[1] === expectedParts[1] && compareVersions(normalized, expected) >= 0;
+  }
+  return normalized === expected;
+}
+
+export async function hashFile(filePath) {
+  const content = await fs.readFile(filePath);
+  return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
+}
+
+export async function readAppManifest(targetDir, { required = true } = {}) {
+  const manifestPath = path.join(targetDir, APP_MANIFEST_PATH);
+  const manifest = await readJsonIfPresent(manifestPath);
+  if (!manifest && required) {
+    throw new Error(`No BrightWeb app manifest found at ${APP_MANIFEST_PATH}. Pre-manifest apps must be adopted before using bw.`);
+  }
+  return manifest;
+}
+
+export async function writeAppManifest(targetDir, manifest) {
+  const manifestPath = path.join(targetDir, APP_MANIFEST_PATH);
+  await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+  const temporaryPath = `${manifestPath}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await fs.writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    await fs.rename(temporaryPath, manifestPath);
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+export function validateAppManifest(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return ["manifest must be an object"];
+  if (manifest.contractVersion !== 1) errors.push("contractVersion must equal 1");
+  if (!manifest.app || typeof manifest.app.slug !== "string" || !["platform", "site"].includes(manifest.app.template) || typeof manifest.app.scaffoldedWith !== "string") {
+    errors.push("app must contain slug, template, and scaffoldedWith");
+  }
+  for (const key of ["modules", "scaffoldFiles", "migrationCursor"]) {
+    if (!manifest[key] || typeof manifest[key] !== "object" || Array.isArray(manifest[key])) errors.push(`${key} must be an object`);
+  }
+  if (!Array.isArray(manifest.managedFiles) || manifest.managedFiles.some((entry) => typeof entry !== "string")) errors.push("managedFiles must be an array of paths");
+  for (const [key, entry] of Object.entries(manifest.modules || {})) {
+    if (!entry || !cleanVersion(entry.version) || typeof entry.installedAt !== "string" || typeof entry.exposed !== "boolean") errors.push(`modules.${key} is invalid`);
+  }
+  for (const [relativePath, entry] of Object.entries(manifest.scaffoldFiles || {})) {
+    if (!entry || typeof entry.module !== "string" || !/^sha256:[a-f0-9]{64}$/.test(entry.hash || "") || !["current", "drifted", "missing"].includes(entry.status) || (entry.intent != null && !["managed", "owned", "skipped"].includes(entry.intent))) errors.push(`scaffoldFiles.${relativePath} is invalid`);
+  }
+  if (manifest.lastDoctor != null && (typeof manifest.lastDoctor.at !== "string" || typeof manifest.lastDoctor.ok !== "boolean")) errors.push("lastDoctor is invalid");
+  return errors;
+}
+
+export function moduleVersion(moduleKey, versionMap = {}) {
+  if (moduleKey === "core") return cleanVersion(versionMap["@brightweblabs/core-auth"] || APP_DEPENDENCY_DEFAULTS["@brightweblabs/core-auth"]);
+  const packageName = MODULE_PACKAGES[moduleKey];
+  return cleanVersion(versionMap[packageName] || APP_DEPENDENCY_DEFAULTS[packageName]);
+}
+
+export async function collectScaffoldFiles(targetDir, selectedModules) {
+  const files = new Map();
+  for (const relativePath of PLATFORM_STARTER_FILES) files.set(relativePath, "platform-base");
+  for (const moduleKey of selectedModules) {
+    const definition = SELECTABLE_MODULES.find((candidate) => candidate.key === moduleKey);
+    if (!definition) continue;
+    const root = path.join(TEMPLATE_ROOT, "modules", definition.templateFolder);
+    if (!(await pathExists(root))) continue;
+    const pending = [root];
+    while (pending.length > 0) {
+      const current = pending.pop();
+      for (const entry of await fs.readdir(current, { withFileTypes: true })) {
+        const fullPath = path.join(current, entry.name);
+        if (entry.isDirectory()) pending.push(fullPath);
+        else files.set(path.relative(root, fullPath), moduleKey);
+      }
+    }
+    for (const relativePath of MODULE_STARTER_FILES[moduleKey] || []) files.set(relativePath, moduleKey);
+  }
+  const result = {};
+  for (const [relativePath, moduleKey] of Array.from(files.entries()).sort()) {
+    const targetPath = path.join(targetDir, relativePath);
+    if (await pathExists(targetPath)) result[relativePath] = { module: moduleKey, hash: await hashFile(targetPath), status: "current" };
+  }
+  return result;
+}
+
+export async function createInitialAppManifest({ targetDir, slug, template, selectedModules, versionMap, dbInstallPlan, cliVersion }) {
+  const now = new Date().toISOString();
+  const modules = {};
+  if (template === "platform") {
+    for (const moduleKey of selectedModules) modules[moduleKey] = { version: moduleVersion(moduleKey, versionMap), installedAt: now, exposed: true };
+    if ((selectedModules.includes("crm") || selectedModules.includes("projects")) && !modules.orgs) {
+      modules.orgs = { version: moduleVersion("orgs", versionMap), installedAt: now, exposed: true };
+    }
+  }
+  const migrationCursor = {};
+  for (const moduleKey of dbInstallPlan?.resolvedOrder || []) {
+    const directory = path.join(TEMPLATE_ROOT, "supabase", "modules", moduleKey, "migrations");
+    if (!(await pathExists(directory))) continue;
+    const migrations = (await fs.readdir(directory)).filter((name) => name.endsWith(".sql")).sort();
+    if (migrations.length > 0) migrationCursor[moduleKey] = migrations.at(-1);
+  }
+  return {
+    contractVersion: 1,
+    app: { slug, template, scaffoldedWith: `create-bw-app@${cliVersion}` },
+    modules,
+    scaffoldFiles: template === "platform" ? await collectScaffoldFiles(targetDir, selectedModules) : {},
+    managedFiles: template === "platform" ? MANAGED_APP_FILES : ["docs/ai/app-context.json"],
+    migrationCursor,
+  };
+}
+
+export async function findWorkspaceRoot(startDir) {
+  let current = path.resolve(startDir);
+  while (true) {
+    if ((await pathExists(path.join(current, "brightweb-release.json"))) && (await pathExists(path.join(current, "packages")))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export async function loadModuleCatalog({ targetDir, workspaceRoot }) {
+  const release = workspaceRoot
+    ? await readJsonIfPresent(path.join(workspaceRoot, "brightweb-release.json"))
+    : null;
+  const coreVersion = cleanVersion(release?.packages?.["@brightweblabs/core-auth"])
+    || moduleVersion("core");
+  const catalog = { core: { key: "core", requires: {}, version: coreVersion, packageName: "@brightweblabs/core-auth" } };
+  for (const [moduleKey, packageName] of Object.entries(MODULE_PACKAGES)) {
+    const folderName = packageName.replace("@brightweblabs/", "");
+    const candidates = [
+      workspaceRoot && path.join(workspaceRoot, "packages", folderName),
+      path.join(targetDir, "node_modules", ...packageName.split("/")),
+    ].filter(Boolean);
+    let packageRoot = null;
+    let moduleManifest = null;
+    let packageManifest = null;
+    for (const candidate of candidates) {
+      moduleManifest = await readJsonIfPresent(path.join(candidate, "brightweb.module.json"));
+      packageManifest = await readJsonIfPresent(path.join(candidate, "package.json"));
+      if (moduleManifest) { packageRoot = candidate; break; }
+    }
+    moduleManifest ||= await readJsonIfPresent(path.join(TEMPLATE_ROOT, "module-manifests", moduleKey, "brightweb.module.json"));
+    catalog[moduleKey] = {
+      key: moduleKey,
+      packageName,
+      packageRoot,
+      manifest: moduleManifest || { key: moduleKey, requires: FALLBACK_REQUIRES[moduleKey], env: [] },
+      requires: moduleManifest?.requires || FALLBACK_REQUIRES[moduleKey],
+      version: cleanVersion(packageManifest?.version) || moduleVersion(moduleKey),
+    };
+  }
+  return catalog;
+}
+
+export function resolveModuleClosure(catalog, requestedKeys) {
+  const order = [];
+  const visited = new Set(["core", "admin"]);
+  const visiting = new Set();
+  function visit(key) {
+    if (visited.has(key)) return;
+    if (!catalog[key]) throw new Error(`Unknown module key: ${key}`);
+    if (visiting.has(key)) throw new Error(`Circular module dependency detected at ${key}`);
+    visiting.add(key);
+    for (const dependency of Object.keys(catalog[key].requires || {})) visit(dependency);
+    visiting.delete(key);
+    visited.add(key);
+    order.push(key);
+  }
+  for (const key of requestedKeys) {
+    if (key === "admin") order.push("admin");
+    else visit(key);
+  }
+  return order;
+}
+
+export async function readConfiguredModuleFlags(targetDir) {
+  const filePath = path.join(targetDir, "config", "modules.ts");
+  if (!(await pathExists(filePath))) return {};
+  const content = await fs.readFile(filePath, "utf8");
+  const flags = {};
+  for (const key of ["core-auth", "orgs", "crm", "projects", "admin"]) {
+    const match = content.match(new RegExp(`key:\\s*"${key}"[\\s\\S]*?enabled:\\s*(true|false)`));
+    if (match) flags[key === "core-auth" ? "core" : key] = match[1] === "true";
+  }
+  return flags;
+}