create-bw-app 0.11.0 → 0.13.0

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/update.mjs

@@ -15,6 +15,7 @@ import {
   createDbInstallPlan,
   createNextConfig,
   createPackageJson,
+  createPlatformGlobalsCss,
   createPlatformModulesConfigFile,
   createShellConfig,
   detectPackageManager,
@@ -27,6 +28,7 @@ import {
 
 const MANAGED_PLATFORM_FILES = [
   "next.config.ts",
+  path.join("app", "globals.css"),
   path.join("config", "modules.ts"),
   path.join("config", "shell.ts"),
   path.join("docs", "ai", "app-context.json"),
@@ -490,6 +492,7 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   if (template === "platform") {
     const canonicalConfigFiles = {
       "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModules }),
+      [path.join("app", "globals.css")]: await createPlatformGlobalsCss(installedModules),
       [path.join("config", "modules.ts")]: createPlatformModulesConfigFile(installedModules),
       [path.join("config", "shell.ts")]: createShellConfig(installedModules),
       [path.join("docs", "ai", "app-context.json")]: createAppContextFile({

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);

package/template/base/AGENTS.md

@@ -1,31 +1,27 @@
 # AGENTS.md
 
-This generated project is a BrightWeb platform starter. Use this file as the local entrypoint for AI agents working inside the app.
+This is a thin BrightWeb platform app. The app owns environment values and settings; reusable UI, domain behavior, and helpers belong in `@brightweblabs/*` packages.
 
 ## Start here
 
-- `README.md`: local setup commands and starter routes.
-- `docs/ai/README.md`: app-specific routing guide for agents.
-- `docs/ai/examples.md`: common setup and customization flows.
-- `docs/ai/app-context.json`: machine-readable app summary for quick discovery.
-- `components/`: local app components used by starter routes and future product surfaces.
-- `config/brand.ts`: client identity, naming, and contact defaults.
-- `app/globals.css`: global design tokens, theme mapping, and shared visual styling.
-- `config/modules.ts`: selected module set and runtime enablement.
-- `config/client.ts`: starter-facing derived state used by the home page and setup surfaces.
-- `.env.local`: runtime service values for local development.
+- `README.md`: setup commands and mounted package routes.
+- `docs/ai/app-context.json`: machine-readable module, path, and ownership summary.
+- `config/brand.ts`: client identity and contact defaults.
+- `config/modules.ts`: selected module set and route metadata.
+- `config/shell.overrides.ts`: app-owned shell customizations.
+- `app/theme.css`: app-owned theme token overrides.
+- `.env.local`: runtime service values.
 
 ## Working rules
 
-- Treat `/bootstrap`, `/preview/app-shell`, and `/playground/*` as starter validation surfaces. They are app-owned and can be removed after setup if links and references are cleaned up too.
-- Keep identity/contact in `config/brand.ts`, and keep all color/theme tokens in `app/globals.css`.
-- Check `config/modules.ts` before assuming CRM, Projects, or Admin routes exist.
-- Prefer composing app-level routes and config before forking logic from `@brightweblabs/*` packages.
-- Keep edits local to this app unless the change is intentionally shared across multiple BrightWeb projects.
+- Keep every `route.ts` as a direct package re-export; a `page.tsx` may instead import one package component and return only that mount.
+- Do not add feature components, demos, hooks, data access, or helper libraries to this app.
+- Put reusable behavior in the owning package, then mount its export here.
+- Keep identity and theme changes in config and theme files.
+- Check `config/modules.ts` before assuming an optional route exists. Projects currently has no default UI route.
 
 ## First validation pass
 
-1. Run the local dev server from this project or workspace.
-2. Open `/`, `/bootstrap`, `/preview/app-shell`, and `/playground/auth`.
-3. If optional modules are enabled, open the matching `/playground/*` route for each one.
-4. Confirm `.env.local` contains real service values before debugging runtime behavior.
+1. Fill `.env.local` with real service values.
+2. Run the local type check or build.
+3. Validate `/crm` and `/admin/users` only when their modules are enabled.