create-bw-app 0.26.2 → 0.27.0

package/README.md

@@ -106,3 +106,36 @@ The scaffold records `SUPABASE_PROJECT_REGION` in `.env.local` and infrastructur
 - `packages/create-bw-app/template/site/base`
 - `packages/create-bw-app/template/modules`
 - `packages/create-bw-app/template/supabase`
+
+### Opt-in social media viewer
+
+For a platform app with marketing enabled, first install a marketing release that
+exports `social-media` and `withSocialMediaNavigation`, then run:
+
+```sh
+bw setup social-media --dry-run
+bw setup social-media
+```
+
+Use `--target-dir <path>` to select another app directory. Setup creates
+`config/social-media-plan.json` with an empty, neutral plan and the thin page at
+`app/(shell)/marketing/social-media/page.tsx`. All client copy belongs in that
+app-owned JSON; components, styles, validation, and interactions stay in marketing.
+No database or publishing service is created.
+
+Setup appends navigation wiring to the standard app-owned
+`config/shell.overrides.ts`, which must declare
+`export const shellRegistrationOverrides: ShellRegistrationOverrides = { ... };`.
+Existing marketing overrides are composed through the shared helper:
+
+```ts
+import { withSocialMediaNavigation } from "@brightweblabs/module-marketing/registration";
+shellRegistrationOverrides.marketing = withSocialMediaNavigation(shellRegistrationOverrides.marketing);
+```
+
+Custom shell export shapes require manual wiring before adopting the standard
+shape. Setup checks prerequisites and paths before writing and rejects symlinks
+on generated paths. Existing JSON and page files are never replaced, even when
+empty or customized; reruns preserve them. These files are not managed templates
+or refreshable starters, and `bw update --refresh-starters` preserves them and
+shell overrides. New marketing apps do not receive this feature until opted in.

package/package.json

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

package/src/bw.mjs

@@ -1,3 +1,4 @@
+import { setupBrightwebFeature } from "./setup.mjs";
 import { addBrightwebModule } from "./add.mjs";
 import { createFirstAdmin } from "./admin.mjs";
 import { adoptBrightwebApp } from "./adopt.mjs";
@@ -8,7 +9,7 @@ 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  admin create          Bootstrap a passwordless administrator safely\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.`;
+const HELP = `Usage: bw <command> [options]\n\nCommands:\n  setup social-media   Create app-owned social media content and wiring\n  add <moduleKey>       Install a module and its requirements\n  admin create          Bootstrap a passwordless administrator safely\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 = {};
@@ -36,7 +37,8 @@ export async function runBwCli(argv = process.argv.slice(2), runtimeOptions = {}
   if (!command || command === "--help" || command === "help") { process.stdout.write(`${HELP}\n`); return; }
   const { options, positionals } = parseOptions(argv.slice(1));
   try {
-    if (command === "add") await addBrightwebModule(positionals[0], options, runtimeOptions);
+    if (command === "setup") await setupBrightwebFeature(positionals[0], options, runtimeOptions);
+    else if (command === "add") await addBrightwebModule(positionals[0], options, runtimeOptions);
     else if (command === "admin") await createFirstAdmin(positionals[0], options, runtimeOptions);
     else if (command === "adopt") await adoptBrightwebApp(options, runtimeOptions);
     else if (command === "diff") await diffBrightwebScaffold(positionals[0], options, runtimeOptions);

package/src/constants.mjs

@@ -191,7 +191,7 @@ export const APP_DEPENDENCY_DEFAULTS = {
   "@brightweblabs/infra": "^0.7.0",
   "@brightweblabs/module-admin": "^0.9.5",
   "@brightweblabs/module-crm": "^0.18.2",
-  "@brightweblabs/module-marketing": "^0.4.25",
+  "@brightweblabs/module-marketing": "^0.5.0",
   "@brightweblabs/module-orgs": "^0.7.1",
   "@brightweblabs/module-projects": "^0.19.1",
   "@brightweblabs/theme": "^0.8.3",

package/src/setup.mjs

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { readAppManifest, readConfiguredModuleFlags } from "./app-manifest.mjs";
+
+const HELP = `Usage: bw setup social-media [options]
+
+Create an app-owned empty social media plan, page, and navigation.
+Existing plan and page files are preserved. Requires installed marketing support.
+
+Options:
+  --target-dir <path>  App directory (defaults to cwd)
+  --dry-run            Show changes without writing
+  --help               Show this help`;
+const PLAN_PATH = "config/social-media-plan.json";
+const PAGE_PATH = "app/(shell)/marketing/social-media/page.tsx";
+const SHELL_PATH = "config/shell.overrides.ts";
+const ASSIGNMENT = "shellRegistrationOverrides.marketing = withSocialMediaNavigation(shellRegistrationOverrides.marketing);";
+const IMPORT = 'import { withSocialMediaNavigation } from "@brightweblabs/module-marketing/registration";';
+const PLAN = { title: "Social media", period: "", sections: [{ id: "calendario", title: "Calendário" }], types: {}, events: [] };
+const PAGE = `import { SocialMediaPage } from "@brightweblabs/module-marketing/social-media";
+import plan from "../../../../config/social-media-plan.json";
+
+export default function Page() {
+  return <SocialMediaPage plan={plan} />;
+}
+`;
+
+// Generated paths must remain real directories/files inside the app, even when
+// an intermediate directory or an existing target is a symlink.
+async function inspectTarget(root, relativePath) {
+  let current = root;
+  const parts = relativePath.split("/");
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part);
+    let stat;
+    try { stat = await fs.lstat(current); } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) throw new Error(`Setup does not follow symlinks: ${relativePath}`);
+    if (index < parts.length - 1 && !stat.isDirectory()) throw new Error(`Expected a directory at ${current}`);
+    if (index === parts.length - 1 && !stat.isFile()) throw new Error(`Expected a file at ${relativePath}`);
+  }
+  return fs.readFile(current, "utf8");
+}
+
+function navigationSource(source) {
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+  if (!/^export const shellRegistrationOverrides\s*:\s*ShellRegistrationOverrides\s*=\s*\{/m.test(code)) {
+    throw new Error(`Cannot safely identify the standard exported const shellRegistrationOverrides: ShellRegistrationOverrides in ${SHELL_PATH}. Wire withSocialMediaNavigation manually before rerunning setup.`);
+  }
+  if (code.includes(ASSIGNMENT) && code.includes(IMPORT)) return source;
+  if (/\bwithSocialMediaNavigation\b/.test(code)) {
+    throw new Error(`Existing custom withSocialMediaNavigation wiring in ${SHELL_PATH}; use the documented import and assignment before rerunning setup.`);
+  }
+  return `${source}${source.endsWith("\n") ? "" : "\n"}\n${IMPORT}\n${ASSIGNMENT}\n`;
+}
+
+export async function setupBrightwebFeature(feature, options = {}, runtimeOptions = {}) {
+  if (options.help) { process.stdout.write(`${HELP}\n`); return; }
+  if (feature !== "social-media") throw new Error(`Unknown setup feature: ${feature || "(missing)"}\n${HELP}`);
+  const targetDir = await fs.realpath(path.resolve(runtimeOptions.targetDir || options.targetDir || process.cwd()));
+  const manifest = await readAppManifest(targetDir);
+  const flags = await readConfiguredModuleFlags(targetDir);
+  if (manifest.app.template !== "platform" || !manifest.modules.marketing || flags.marketing !== true) {
+    throw new Error("Social media setup requires a platform app with marketing installed and enabled. Run bw add marketing first.");
+  }
+  try {
+    const require = createRequire(path.join(targetDir, "package.json"));
+    require.resolve("@brightweblabs/module-marketing/social-media");
+    const registration = await fs.readFile(require.resolve("@brightweblabs/module-marketing/registration"), "utf8");
+    if (!/export\s+(?:function|const)\s+withSocialMediaNavigation\b/.test(registration)) throw new Error("Missing navigation helper");
+  } catch {
+    throw new Error("Install or upgrade @brightweblabs/module-marketing to a release with social-media and withSocialMediaNavigation support, then rerun setup.");
+  }
+  const plan = await inspectTarget(targetDir, PLAN_PATH);
+  const page = await inspectTarget(targetDir, PAGE_PATH);
+  const shell = await inspectTarget(targetDir, SHELL_PATH);
+  if (shell === null) throw new Error(`Missing ${SHELL_PATH}; restore the app-owned shell overrides file before setup.`);
+  const nextShell = navigationSource(shell);
+  const changes = [
+    ...(plan === null ? [{ path: PLAN_PATH, content: `${JSON.stringify(PLAN, null, 2)}\n`, create: true }] : []),
+    ...(page === null ? [{ path: PAGE_PATH, content: PAGE, create: true }] : []),
+    ...(nextShell !== shell ? [{ path: SHELL_PATH, content: nextShell, create: false }] : []),
+  ];
+  for (const change of changes) {
+    process.stdout.write(`${options.dryRun ? "Would " : ""}${change.create ? "Create" : "Update"} ${change.path}\n`);
+  }
+  if (!options.dryRun) for (const change of changes) {
+    await fs.mkdir(path.dirname(path.join(targetDir, change.path)), { recursive: true });
+    await fs.writeFile(path.join(targetDir, change.path), change.content, { flag: change.create ? "wx" : "w" });
+  }
+  process.stdout.write(changes.length ? "Social media setup ready. Content belongs to this app.\n" : "Social media is already configured; existing files preserved.\n");
+  return { changes: changes.map(({ path: relativePath }) => relativePath), dryRun: !!options.dryRun };
+}