create-payload-stack 0.3.0 → 0.4.0

package/README.md

@@ -6,11 +6,11 @@ Scaffold a SaaS on Payload CMS in one command.
 npx create-payload-stack@latest
 ```
 
-Seven prompts: project name, database (PostgreSQL, MongoDB, SQLite, Vercel Postgres), connection string, sign-in methods, organizations, billing, media storage (skip for local disk, or Vercel Blob, AWS S3, Cloudflare R2, Azure Blob Storage, Google Cloud Storage, Uploadthing). The CLI downloads [Payload Stack](https://www.payloadstack.com), writes your answers into `src/stack.config.ts`, swaps the Payload database adapter, wires the storage adapter into `payload.config.ts`, generates `.env` with fresh secrets, installs dependencies and initializes git.
+Nine prompts: project name, database (PostgreSQL, MongoDB, SQLite, Vercel Postgres), connection string, sign-in methods, organizations, billing, media storage (skip for local disk, or Vercel Blob, AWS S3, Cloudflare R2, Azure Blob Storage, Google Cloud Storage, Uploadthing), transactional emails (edit copy in the Payload admin, or keep React Email components in code) and cookie consent (banner with audited legal pages, or plain legal pages). The CLI downloads [Payload Stack](https://www.payloadstack.com), writes your answers into `src/stack.config.ts`, swaps the Payload database adapter, wires the storage adapter into `payload.config.ts`, generates `.env` with fresh secrets, installs dependencies and initializes git.
 
 ```bash
 # non-interactive
-npx create-payload-stack@latest ridgeline -d postgres --auth email-password,magic-link,passkey --social github --billing organization --storage vercel-blob -y
+npx create-payload-stack@latest ridgeline -d postgres --auth email-password,magic-link,passkey --social github --billing organization --storage vercel-blob --emails --consent -y
 ```
 
 Run `npx create-payload-stack@latest --help` for every flag. Documentation: https://payload.solutions/docs/payload-stack

package/dist/index.js

@@ -249,6 +249,10 @@ function helpText(version2) {
         --no-organizations        Disable organizations
         --billing <mode>          organization | user | none
         --storage <adapter>       ${STORAGE_KEYS.join(" | ")} (none = local disk)
+        --emails                  Edit transactional email copy in the Payload admin
+        --no-emails               Keep emails as React Email components in code
+        --consent                 Cookie banner and audited legal pages (Payload Consent)
+        --no-consent              Plain legal pages, no banner
         --use-pnpm | --use-npm | --use-yarn | --use-bun
         --no-install              Skip dependency installation
         --no-git                  Skip git init
@@ -281,6 +285,8 @@ function parse(argv) {
       organizations: { type: "boolean" },
       billing: { type: "string" },
       storage: { type: "string" },
+      emails: { type: "boolean" },
+      consent: { type: "boolean" },
       "use-pnpm": { type: "boolean" },
       "use-npm": { type: "boolean" },
       "use-yarn": { type: "boolean" },
@@ -306,6 +312,8 @@ function parse(argv) {
       organizations: values.organizations,
       billing: values.billing,
       storage: values.storage,
+      emails: values.emails,
+      consent: values.consent,
       packageManager,
       install: values.install ?? true,
       git: values.git ?? true,
@@ -323,18 +331,174 @@ function parse(argv) {
 // src/cli.ts
 import * as p from "@clack/prompts";
 import { execa as execa2 } from "execa";
-import { existsSync as existsSync3 } from "fs";
-import path3 from "path";
+import { existsSync as existsSync5 } from "fs";
+import path6 from "path";
 import pc2 from "picocolors";
 
 // src/configure.ts
 import { readFile, writeFile } from "fs/promises";
+import path4 from "path";
+
+// src/consent.ts
+import { cp, rm as rm2, rmdir } from "fs/promises";
+import { existsSync } from "fs";
+import path2 from "path";
+
+// src/variants.ts
+import { rm } from "fs/promises";
 import path from "path";
+var VARIANT_DIR = "variants";
+function variantPath(step) {
+  return path.join(VARIANT_DIR, step);
+}
+async function removeVariants(directory) {
+  await rm(path.join(directory, VARIANT_DIR), { force: true, recursive: true });
+}
+
+// src/consent.ts
+var CONSENT_PACKAGE = "@payload-solutions/plugin-consent";
+var CONSENT_REACT_PACKAGE = "@payload-solutions/consent-react";
+var CONSENT_VERSION = "0.1.0";
+var CONSENT_PACKAGES = {
+  [CONSENT_PACKAGE]: CONSENT_VERSION,
+  [CONSENT_REACT_PACKAGE]: CONSENT_VERSION
+};
+var VARIANT_CONSENT = variantPath("consent-plugin");
+var SEAM_FILES = [
+  "plugin.ts",
+  "collections.ts",
+  "seed.ts",
+  "consent-root.tsx",
+  "consent-settings-link.tsx",
+  "legal-page.tsx",
+  "legal-setup-notice.tsx"
+];
+var BANNER_FILES = ["consent-banner.tsx", "consent-preferences-dialog.tsx"];
+var TEMPLATE_LEGAL_FILES = ["src/collections/LegalPages.ts", "src/seed/legal.ts", "tests/unit/seed-legal.spec.ts"];
+function swapConsentPackages(packageJson, enabled) {
+  const deps = { ...packageJson.dependencies };
+  const devDeps = { ...packageJson.devDependencies };
+  for (const pkg of Object.keys(CONSENT_PACKAGES)) {
+    delete devDeps[pkg];
+    if (enabled) deps[pkg] = CONSENT_PACKAGES[pkg];
+    else delete deps[pkg];
+  }
+  return { ...packageJson, dependencies: sortKeys(deps), devDependencies: sortKeys(devDeps) };
+}
+function sortKeys(obj) {
+  return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
+async function applyConsentChoice(directory, enabled) {
+  if (!enabled) return;
+  const variant = path2.join(directory, VARIANT_CONSENT);
+  if (!existsSync(variant)) {
+    throw new Error(`The template is missing ${VARIANT_CONSENT}; it cannot scaffold with consent.`);
+  }
+  for (const name of [...SEAM_FILES, ...BANNER_FILES]) {
+    await cp(path2.join(variant, name), path2.join(directory, "src/consent", name), { recursive: true });
+  }
+  await cp(path2.join(variant, "tests/consent.spec.ts"), path2.join(directory, "tests/unit/consent.spec.ts"));
+  for (const name of TEMPLATE_LEGAL_FILES) {
+    await rm2(path2.join(directory, name), { force: true, recursive: true });
+  }
+  await rmdir(path2.join(directory, "src/seed")).catch(() => {
+  });
+}
+
+// src/emails.ts
+import { cp as cp2, rm as rm3 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import path3 from "path";
+var EMAILS_PACKAGE = "@payload-solutions/plugin-emails";
+var EMAILS_VERSION = "0.1.0";
+var REACT_EMAIL_COMPONENTS = ["@react-email/components", "^1.0.12"];
+var REACT_EMAIL_ONLY_PACKAGES = {
+  "@react-email/render": "^2.1.0",
+  "react-email": "^6.9.3"
+};
+var EMAIL_DEV_SCRIPT = ["email:dev", "email dev --dir src/components/auth/email --port 3001"];
+var VARIANT_EMAILS = variantPath("emails-plugin");
+var IMPORT_MARKER = "// emails-plugin-import";
+var CONFIG_START = "// emails-plugin-config-start";
+var CONFIG_END = "// emails-plugin-config-end";
+var IMPORTS = `${IMPORT_MARKER}
+import { emailsPlugin } from '${EMAILS_PACKAGE}'
+import { emailDefinitions } from '@/emails/definitions'
+import { StackEmailTemplate } from '@/emails/template'
+import { globalVariableManifest, globalVariables } from '@/emails/variables'`;
+var REGISTRATION = `plugins.push(
+  emailsPlugin({
+    // The catalogue, filtered by the features in stack.config.ts (src/emails/definitions).
+    emails: emailDefinitions,
+    // Branding lives in code; editors own the words (src/emails/template.tsx).
+    templates: { default: StackEmailTemplate },
+    // {{site.name}}, {{support.email}}, {{url.dashboard}} \u2026 in every email (src/emails/variables.ts).
+    globalVariables,
+    globalVariableManifest,
+    // Every send recorded, for 90 days. Set enabled: false to keep no record at all.
+    log: { enabled: true, retentionDays: 90 },
+    settings: { mediaCollection: 'media' },
+  }),
+)`;
+function addEmailsPlugin(payloadConfigSource) {
+  if (!payloadConfigSource.includes(IMPORT_MARKER)) {
+    throw new Error(`payload.config.ts is missing the "${IMPORT_MARKER}" marker`);
+  }
+  const start = payloadConfigSource.indexOf(CONFIG_START);
+  const end = payloadConfigSource.indexOf(CONFIG_END);
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`payload.config.ts is missing the emails plugin markers`);
+  }
+  const withImports = payloadConfigSource.replace(IMPORT_MARKER, IMPORTS);
+  const at = withImports.indexOf(CONFIG_START);
+  const to = withImports.indexOf(CONFIG_END);
+  return `${withImports.slice(0, at)}${CONFIG_START}
+${REGISTRATION}
+${withImports.slice(to)}`;
+}
+function swapEmailsPackages(packageJson, enabled) {
+  const deps = { ...packageJson.dependencies };
+  const devDeps = { ...packageJson.devDependencies };
+  const scripts = { ...packageJson.scripts };
+  delete devDeps[EMAILS_PACKAGE];
+  delete devDeps[REACT_EMAIL_COMPONENTS[0]];
+  if (enabled) {
+    deps[EMAILS_PACKAGE] = EMAILS_VERSION;
+    deps[REACT_EMAIL_COMPONENTS[0]] = REACT_EMAIL_COMPONENTS[1];
+    for (const pkg of Object.keys(REACT_EMAIL_ONLY_PACKAGES)) delete deps[pkg];
+    delete scripts[EMAIL_DEV_SCRIPT[0]];
+  } else {
+    delete deps[EMAILS_PACKAGE];
+    delete deps[REACT_EMAIL_COMPONENTS[0]];
+    Object.assign(deps, REACT_EMAIL_ONLY_PACKAGES);
+    scripts[EMAIL_DEV_SCRIPT[0]] = EMAIL_DEV_SCRIPT[1];
+  }
+  return { ...packageJson, dependencies: sortKeys2(deps), devDependencies: sortKeys2(devDeps), scripts: sortKeys2(scripts) };
+}
+function sortKeys2(obj) {
+  return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
+var REACT_EMAIL_FILES = ["src/emails/send.ts", "src/components/auth/email"];
+async function applyEmailsChoice(directory, enabled) {
+  const variant = path3.join(directory, VARIANT_EMAILS);
+  if (enabled) {
+    if (!existsSync2(variant)) {
+      throw new Error(`The template is missing ${VARIANT_EMAILS}; it cannot scaffold with emails.`);
+    }
+    for (const name of ["index.ts", "hooks.ts", "template.tsx", "variables.ts", "definitions"]) {
+      await cp2(path3.join(variant, name), path3.join(directory, "src/emails", name), { recursive: true });
+    }
+    await cp2(path3.join(variant, "tests/emails.spec.ts"), path3.join(directory, "tests/unit/emails.spec.ts"));
+    for (const name of REACT_EMAIL_FILES) {
+      await rm3(path3.join(directory, name), { force: true, recursive: true });
+    }
+  }
+}
 
 // src/utils.ts
 import slugifyBase from "@sindresorhus/slugify";
 import { randomBytes } from "crypto";
-import { existsSync, readdirSync } from "fs";
+import { existsSync as existsSync3, readdirSync } from "fs";
 import { execa } from "execa";
 function slugify(input) {
   return slugifyBase(input.trim()).replace(/^-+|-+$/g, "") || "my-saas";
@@ -343,7 +507,7 @@ function generateSecret(bytes = 32) {
   return randomBytes(bytes).toString("base64url");
 }
 function isDirectoryEmpty(dir) {
-  if (!existsSync(dir)) return true;
+  if (!existsSync3(dir)) return true;
   const entries = readdirSync(dir).filter((e) => ![".git", ".DS_Store"].includes(e));
   return entries.length === 0;
 }
@@ -408,6 +572,18 @@ function renderStackConfig(o) {
       },
     ],
   },`;
+  const legalBlock = o.consent ? `  legal: {
+    company: '${o.name.replace(/'/g, "\\'")} Ltd',
+    jurisdiction: 'Ireland',
+    // The seeded legal pages are written from here. Fill these in before you publish them:
+    // \`npx payload-consent scan\` lists every value still left as a placeholder.
+    // https://payload.solutions/docs/plugins/payload-consent/audit
+    legalName: '${o.name.replace(/'/g, "\\'")} Ltd',
+    address: '[REGISTERED ADDRESS]',
+  },` : `  legal: {
+    company: '${o.name.replace(/'/g, "\\'")} Ltd',
+    jurisdiction: 'Ireland',
+  },`;
   return `import { defineStack } from '@/lib/stack'
 
 /**
@@ -450,10 +626,7 @@ ${billingBlock}
     sendPII: false,
   },
 
-  legal: {
-    company: '${o.name.replace(/'/g, "\\'")} Ltd',
-    jurisdiction: 'Ireland',
-  },
+${legalBlock}
 
   nav: [${o.billing !== "none" ? "{ label: 'Pricing', href: '/pricing' }, " : ""}{ label: 'Docs', href: 'https://payload.solutions/docs/payload-stack' }],
 
@@ -461,24 +634,24 @@ ${billingBlock}
 })
 `;
 }
-var IMPORT_MARKER = "// database-adapter-import";
-var CONFIG_START = "// database-adapter-config-start";
-var CONFIG_END = "// database-adapter-config-end";
+var IMPORT_MARKER2 = "// database-adapter-import";
+var CONFIG_START2 = "// database-adapter-config-start";
+var CONFIG_END2 = "// database-adapter-config-end";
 function swapDatabaseAdapter(payloadConfigSource, db) {
-  const importLine = `${IMPORT_MARKER}
+  const importLine = `${IMPORT_MARKER2}
 import { ${db.importName} } from '${db.packageName}'`;
   const withImport = payloadConfigSource.replace(
-    new RegExp(`${escapeRegExp(IMPORT_MARKER)}\\nimport [^\\n]+\\n`),
+    new RegExp(`${escapeRegExp(IMPORT_MARKER2)}\\nimport [^\\n]+\\n`),
     `${importLine}
 `
   );
   if (withImport === payloadConfigSource && !payloadConfigSource.includes(importLine)) {
-    throw new Error(`payload.config.ts is missing the "${IMPORT_MARKER}" marker`);
+    throw new Error(`payload.config.ts is missing the "${IMPORT_MARKER2}" marker`);
   }
-  const start = withImport.indexOf(CONFIG_START);
-  const end = withImport.indexOf(CONFIG_END);
+  const start = withImport.indexOf(CONFIG_START2);
+  const end = withImport.indexOf(CONFIG_END2);
   if (start === -1 || end === -1) throw new Error(`payload.config.ts is missing the database adapter markers`);
-  return `${withImport.slice(0, start)}${CONFIG_START}
+  return `${withImport.slice(0, start)}${CONFIG_START2}
   ${db.config}
   ${withImport.slice(end)}`;
 }
@@ -523,7 +696,7 @@ function swapStoragePackage(packageJson, storage) {
     if (pkg !== storage?.packageName) delete deps[pkg];
   }
   if (storage) deps[storage.packageName] = payloadVersion;
-  return { ...packageJson, dependencies: sortKeys(deps) };
+  return { ...packageJson, dependencies: sortKeys3(deps) };
 }
 function storageChoice(key) {
   return key === "none" ? null : STORAGE_CHOICES[key];
@@ -535,7 +708,16 @@ function swapDatabasePackage(packageJson, db) {
     if (other.packageName !== db.packageName) delete deps[other.packageName];
   }
   deps[db.packageName] = payloadVersion;
-  return { ...packageJson, dependencies: sortKeys(deps) };
+  return { ...packageJson, dependencies: sortKeys3(deps) };
+}
+function stripWorkspaceDependencies(packageJson) {
+  const next = { ...packageJson };
+  for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const deps = next[field];
+    if (!deps) continue;
+    next[field] = Object.fromEntries(Object.entries(deps).filter(([, version2]) => !version2.startsWith("workspace:")));
+  }
+  return next;
 }
 function renameProject(packageJson, slug) {
   const next = { ...packageJson, name: slug, version: "0.1.0", private: true };
@@ -560,7 +742,7 @@ function renderEnv(example, o) {
   });
   return lines.join("\n");
 }
-function sortKeys(obj) {
+function sortKeys3(obj) {
   return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
 }
 function escapeRegExp(s) {
@@ -568,16 +750,24 @@ function escapeRegExp(s) {
 }
 async function configureProject(o) {
   const db = DB_CHOICES[o.db];
-  const read = (rel) => readFile(path.join(o.directory, rel), "utf8");
-  const write = (rel, content) => writeFile(path.join(o.directory, rel), content);
+  const read = (rel) => readFile(path4.join(o.directory, rel), "utf8");
+  const write = (rel, content) => writeFile(path4.join(o.directory, rel), content);
   await write("src/stack.config.ts", renderStackConfig(o));
   const storage = storageChoice(o.storage);
   const payloadConfig = await read("src/payload.config.ts");
-  await write("src/payload.config.ts", swapStorageAdapter(swapDatabaseAdapter(payloadConfig, db), storage));
+  const withAdapters = swapStorageAdapter(swapDatabaseAdapter(payloadConfig, db), storage);
+  await write("src/payload.config.ts", o.emails ? addEmailsPlugin(withAdapters) : withAdapters);
+  await applyEmailsChoice(o.directory, o.emails);
+  await applyConsentChoice(o.directory, o.consent);
+  await removeVariants(o.directory);
   const pkg = JSON.parse(await read("package.json"));
+  const configured = swapConsentPackages(
+    swapEmailsPackages(swapStoragePackage(swapDatabasePackage(pkg, db), storage), o.emails),
+    o.consent
+  );
   await write(
     "package.json",
-    JSON.stringify(renameProject(swapStoragePackage(swapDatabasePackage(pkg, db), storage), o.slug), null, 2) + "\n"
+    JSON.stringify(renameProject(stripWorkspaceDependencies(configured), o.slug), null, 2) + "\n"
   );
   const example = await read(".env.example");
   await write(".env", renderEnv(example, { connectionString: o.connectionString }));
@@ -588,9 +778,9 @@ var AUTH_METHODS = ["email-password", "magic-link", "passkey"];
 var SOCIAL_PROVIDERS = ["google", "github"];
 
 // src/template.ts
-import { cp, mkdir, rm } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
-import path2 from "path";
+import { cp as cp3, mkdir, rm as rm4 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import path5 from "path";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import * as tar from "tar";
@@ -618,29 +808,30 @@ Check your network, or pass --local-template <path> to scaffold from a local che
       }
     })
   );
-  if (!existsSync2(path2.join(dest, "package.json"))) {
+  if (!existsSync4(path5.join(dest, "package.json"))) {
     throw new Error(`The downloaded archive did not contain ${TEMPLATE_PATH}/package.json (branch "${branch}").`);
   }
 }
 async function copyLocalTemplate({ from, dest }) {
-  const source = path2.resolve(from);
-  if (!existsSync2(path2.join(source, "package.json"))) {
+  const source = path5.resolve(from);
+  if (!existsSync4(path5.join(source, "package.json"))) {
     throw new Error(`--local-template must point at a directory containing package.json (got ${source})`);
   }
   await mkdir(dest, { recursive: true });
-  await cp(source, dest, {
+  await cp3(source, dest, {
     recursive: true,
     filter: (src) => {
-      const rel = path2.relative(source, src);
-      const top = rel.split(path2.sep)[0];
+      const rel = path5.relative(source, src);
+      const top = rel.split(path5.sep)[0];
       return !["node_modules", ".next", ".turbo", ".env", "test-results", "playwright-report", "next-env.d.ts", "tsconfig.tsbuildinfo", "CLAUDE.md"].includes(top ?? "");
     }
   });
-  await rm(path2.join(dest, "CLAUDE.md"), { force: true });
+  await rm4(path5.join(dest, "CLAUDE.md"), { force: true });
 }
 
 // src/cli.ts
 var DOCS = "https://payload.solutions/docs/payload-stack";
+var CONSENT_DOCS = "https://payload.solutions/docs/plugins/payload-consent/audit";
 function bail(message = "Cancelled.") {
   p.cancel(message);
   process.exit(1);
@@ -674,7 +865,7 @@ async function run(flags, positionalName) {
     })
   );
   const slug = slugify(name);
-  const directory = path3.resolve(process.cwd(), slug);
+  const directory = path6.resolve(process.cwd(), slug);
   if (!isDirectoryEmpty(directory)) {
     bail(`Directory ./${slug} already exists and is not empty.`);
   }
@@ -759,6 +950,22 @@ async function run(flags, positionalName) {
       ]
     })
   ));
+  const emails = flags.emails ?? (flags.defaults ? true : guard(
+    await p.confirm({
+      message: "Transactional emails",
+      initialValue: true,
+      active: "Editable in the admin (Payload Emails)",
+      inactive: "React Email components in code"
+    })
+  ));
+  const consent = flags.consent ?? (flags.defaults ? true : guard(
+    await p.confirm({
+      message: "Cookie consent and legal pages",
+      initialValue: true,
+      active: "Banner, consent records and audited legal pages (Payload Consent)",
+      inactive: "Plain legal pages, no banner"
+    })
+  ));
   const packageManager = flags.packageManager ?? await detectPackageManager();
   const options = {
     name,
@@ -771,6 +978,8 @@ async function run(flags, positionalName) {
     organizations,
     billing,
     storage,
+    emails,
+    consent,
     packageManager,
     install: flags.install,
     git: flags.git
@@ -806,7 +1015,7 @@ async function run(flags, positionalName) {
 ${error instanceof Error ? error.message.split("\n")[0] : ""}`);
     }
   }
-  if (options.git && !existsSync3(path3.join(directory, ".git"))) {
+  if (options.git && !existsSync5(path6.join(directory, ".git"))) {
     try {
       await execa2("git", ["init", "-b", "main"], { cwd: directory });
       await execa2("git", ["add", "-A"], { cwd: directory });
@@ -823,7 +1032,12 @@ ${error instanceof Error ? error.message.split("\n")[0] : ""}`);
     ...billing !== "none" ? ["# add STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET and NEXT_PUBLIC_STRIPE_PRICE_* to .env when you are ready for billing"] : [],
     ...storage !== "none" ? [`# add ${listWords(STORAGE_CHOICES[storage].envVars)} to .env to store uploads in ${STORAGE_CHOICES[storage].label} (local disk until then)`] : [],
     runCommand(packageManager, "dev"),
-    "open http://localhost:3000/admin"
+    "open http://localhost:3000/admin",
+    ...emails ? ["# email copy is under Emails in the admin; the design is src/emails/template.tsx"] : [],
+    ...consent ? [
+      "# the seeded legal pages are templates, not policy: the homepage shows the six steps in development",
+      `# ${CONSENT_DOCS}`
+    ] : []
   ];
   p.note(steps.join("\n"), "Done. Next steps:");
   p.outro(`Docs: ${pc2.underline(DOCS)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-payload-stack",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Scaffold a SaaS on Payload CMS: Better Auth, organizations, Stripe subscriptions and a shadcn dashboard, in one command.",
   "keywords": [
     "payload",