create-bw-app 0.11.0 → 0.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "bin": {
     "create-bw-app": "bin/create-bw-app.mjs",

package/src/add.mjs

@@ -91,7 +91,8 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
   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;
-  appManifest.scaffoldFiles = { ...appManifest.scaffoldFiles, ...await collectScaffoldFiles(targetDir, installedModuleKeys) };
+  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 };

package/src/adopt.mjs

@@ -18,7 +18,7 @@ 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  --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`;
+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 [];
@@ -123,10 +123,24 @@ export async function adoptBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
   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") warnings.push(`WARN drifted scaffold file: ${relativePath}`);
-    if (record.status === "missing") warnings.push(`WARN missing scaffold file: ${relativePath} (not created; use bw diff and the current template as guidance).`);
+    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);

package/src/app-manifest.mjs

@@ -89,7 +89,14 @@ export async function readAppManifest(targetDir, { required = true } = {}) {
 export async function writeAppManifest(targetDir, manifest) {
   const manifestPath = path.join(targetDir, APP_MANIFEST_PATH);
   await fs.mkdir(path.dirname(manifestPath), { recursive: true });
-  await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  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) {
@@ -107,7 +114,7 @@ export function validateAppManifest(manifest) {
     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)) errors.push(`scaffoldFiles.${relativePath} is invalid`);
+    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;

package/src/bw.mjs

@@ -3,16 +3,17 @@ import { adoptBrightwebApp } from "./adopt.mjs";
 import { diffBrightwebScaffold } from "./diff.mjs";
 import { doctorBrightwebApp } from "./doctor.mjs";
 import { removeBrightwebModule } from "./remove.mjs";
+import { scaffoldBrightwebApp } from "./scaffold-cmd.mjs";
 import { updateBrightwebApp } from "./update.mjs";
 import { upgradeBrightwebApp } from "./upgrade.mjs";
 
-const HELP = `Usage: bw <command> [options]\n\nCommands:\n  add <moduleKey>       Install a module and its requirements\n  adopt                 Create an honest manifest for a legacy app\n  diff <relpath>        Compare a tracked scaffold file with its template\n  remove <moduleKey>    Conservatively remove module package wiring\n  upgrade [moduleKey]   Upgrade packages, managed files, and migrations\n  update                Alias for the legacy create-bw-app update flow\n  doctor                Validate app health and manifest consistency\n\nRun bw <command> --help for command-specific options.`;
+const HELP = `Usage: bw <command> [options]\n\nCommands:\n  add <moduleKey>       Install a module and its requirements\n  adopt                 Create an honest manifest for a legacy app\n  diff <relpath>        Compare a tracked scaffold file with its template\n  scaffold <action>     List or record per-file scaffold intent\n  remove <moduleKey>    Conservatively remove module package wiring\n  upgrade [moduleKey]   Upgrade packages, managed files, and migrations\n  update                Alias for the legacy create-bw-app update flow\n  doctor                Validate app health and manifest consistency\n\nRun bw <command> --help for command-specific options.`;
 
 function parseOptions(argv) {
   const options = {};
   const positionals = [];
   const booleanFlags = new Set(["help", "dry-run", "strict", "report", "install", "refresh-starters", "allow-stale-fallback", "allow-uncursored", "force", "list", "yes"]);
-  const repeatableFlags = new Set(["cursor", "owned-surface"]);
+  const repeatableFlags = new Set(["cursor", "owned-surface", "own", "skip"]);
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (!token.startsWith("--")) { positionals.push(token); continue; }
@@ -37,6 +38,7 @@ export async function runBwCli(argv = process.argv.slice(2), runtimeOptions = {}
     if (command === "add") await addBrightwebModule(positionals[0], options, runtimeOptions);
     else if (command === "adopt") await adoptBrightwebApp(options, runtimeOptions);
     else if (command === "diff") await diffBrightwebScaffold(positionals[0], options, runtimeOptions);
+    else if (command === "scaffold") await scaffoldBrightwebApp(positionals[0], positionals.slice(1), options, runtimeOptions);
     else if (command === "remove") await removeBrightwebModule(positionals[0], options, runtimeOptions);
     else if (command === "upgrade") await upgradeBrightwebApp(positionals[0], options, runtimeOptions);
     else if (command === "update") await updateBrightwebApp(options, runtimeOptions);

package/src/constants.mjs

@@ -76,15 +76,15 @@ export const PLATFORM_STARTER_FILES = [
 ];
 
 export const APP_DEPENDENCY_DEFAULTS = {
-  "@brightweblabs/app-shell": "^0.4.0",
+  "@brightweblabs/app-shell": "^0.4.1",
   "@brightweblabs/core-auth": "^0.3.4",
   "@brightweblabs/infra": "^0.3.1",
-  "@brightweblabs/module-admin": "^0.3.4",
-  "@brightweblabs/module-crm": "^0.5.0",
-  "@brightweblabs/module-orgs": "^0.2.0",
-  "@brightweblabs/module-projects": "^0.4.2",
-  "@brightweblabs/theme": "^0.2.0",
-  "@brightweblabs/ui": "^1.0.0",
+  "@brightweblabs/module-admin": "^0.3.5",
+  "@brightweblabs/module-crm": "^0.5.2",
+  "@brightweblabs/module-orgs": "^0.2.2",
+  "@brightweblabs/module-projects": "^0.4.3",
+  "@brightweblabs/theme": "^0.2.1",
+  "@brightweblabs/ui": "^1.0.1",
   "lucide-react": "^1.8.0",
   "next": "16.1.6",
   "react": "19.2.3",

package/src/doctor.mjs

@@ -52,7 +52,21 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
   add(topologyProblems.length ? "FAIL" : "PASS", "topology", topologyProblems.join("; ") || "Module requirements are satisfied.");
 
   const scaffold = await scaffoldDrift(targetDir, appManifest.scaffoldFiles);
-  add(scaffold.drifted.length || scaffold.missing.length ? "FAIL" : "PASS", "scaffold", `${scaffold.current.length} current, ${scaffold.drifted.length} drifted, ${scaffold.missing.length} missing; drifted scaffold files: ${scaffold.drifted.length} (see bw diff --list)${scaffold.missing.length ? `; missing: ${scaffold.missing.join(", ")}` : ""}`);
+  const scaffoldGroups = {
+    current: scaffold.entries.filter((entry) => entry.status === "current" && entry.intent !== "skipped"),
+    owned: scaffold.entries.filter((entry) => entry.intent === "owned" && entry.status === "drifted"),
+    skipped: scaffold.entries.filter((entry) => entry.intent === "skipped" && entry.status === "missing"),
+    undecidedDrift: scaffold.entries.filter((entry) => entry.intent === "managed" && entry.status === "drifted"),
+    undecidedMissing: scaffold.entries.filter((entry) => entry.intent === "managed" && entry.status === "missing"),
+    mismatched: scaffold.entries.filter((entry) => (entry.intent === "owned" && entry.status === "missing") || (entry.intent === "skipped" && entry.status !== "missing")),
+  };
+  if (scaffoldGroups.owned.length) add("INFO", "scaffold-owned", `App-owned scaffold files: ${scaffoldGroups.owned.map((entry) => entry.relativePath).join(", ")}.`);
+  if (scaffoldGroups.skipped.length) add("INFO", "scaffold-skipped", `Intentionally skipped scaffold files: ${scaffoldGroups.skipped.map((entry) => entry.relativePath).join(", ")}.`);
+  if (scaffoldGroups.undecidedDrift.length) add("WARN", "scaffold-undecided-drift", `Unacknowledged drift: ${scaffoldGroups.undecidedDrift.map((entry) => entry.relativePath).join(", ")} (use bw scaffold own or bw diff).`);
+  if (scaffoldGroups.undecidedMissing.length) add("WARN", "scaffold-undecided-missing", `Unacknowledged missing files: ${scaffoldGroups.undecidedMissing.map((entry) => entry.relativePath).join(", ")} (use bw scaffold skip after review).`);
+  if (scaffoldGroups.mismatched.length) add("FAIL", "scaffold-intent-mismatch", `Recorded scaffold intent no longer matches reality: ${scaffoldGroups.mismatched.map((entry) => `${entry.relativePath} (${entry.intent}, ${entry.status})`).join(", ")}.`);
+  const scaffoldStatus = scaffoldGroups.mismatched.length ? "FAIL" : scaffoldGroups.undecidedDrift.length || scaffoldGroups.undecidedMissing.length ? "WARN" : "PASS";
+  add(scaffoldStatus, "scaffold", `${scaffoldGroups.current.length} current, ${scaffoldGroups.owned.length} owned, ${scaffoldGroups.skipped.length} skipped, ${scaffoldGroups.undecidedDrift.length} undecided-drift, ${scaffoldGroups.undecidedMissing.length} undecided-missing, ${scaffoldGroups.mismatched.length} intent-mismatch.`);
   add("INFO", "owned-surfaces", `Owned surfaces: ${(appManifest.ownedSurfaces || []).join(", ") || "none"}.`);
 
   const envNames = new Set(Object.keys(process.env));

package/src/remove.mjs

@@ -70,7 +70,7 @@ export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtime
     if (record.module !== moduleKey) continue;
     const filePath = path.join(targetDir, relativePath);
     if (!(await pathExists(filePath))) continue;
-    if (await hashFile(filePath) === record.hash) cleanFiles.push(relativePath);
+    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 || []);

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

@@ -58,13 +58,21 @@ 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);
-    if (!(await pathExists(appPath))) missing.push(relativePath);
-    else if (await hashFile(appPath) === record.hash) current.push(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 };
+  return { current, drifted, missing, entries };
 }
 
 export async function findTrackedTemplate({ relativePath, manifest, targetDir, workspaceRoot }) {

package/src/upgrade.mjs

@@ -18,13 +18,16 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   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);
+  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]));
 
@@ -43,6 +46,7 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   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) {
@@ -58,6 +62,7 @@ export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOp
   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);