create-payload-stack 0.5.1 → 0.6.0

package/README.md

@@ -6,11 +6,11 @@ Scaffold a SaaS on Payload CMS in one command.
 npx create-payload-stack@latest
 ```
 
-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.
+Twelve 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) cookie consent (banner with audited legal pages, or plain legal pages), scheduled actions and what runs them, and the coding agents you use (Claude Code, Codex, Cursor: task skills and MCP servers on top of `AGENTS.md`). 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 --emails --consent -y
+npx create-payload-stack@latest ridgeline -d postgres --auth email-password,magic-link,passkey --social github --billing organization --storage vercel-blob --emails --consent --agents claude,cursor -y
 ```
 
 Run `npx create-payload-stack@latest --help` for every flag. Documentation: https://payload.solutions/docs/payload-stack

package/dist/index.js

@@ -8,6 +8,74 @@ import pc3 from "picocolors";
 import { parseArgs } from "util";
 import pc from "picocolors";
 
+// src/agents.ts
+import { cp, mkdir, rm, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import path from "path";
+var AGENT_KEYS = ["claude", "codex", "cursor"];
+var AGENT_CHOICES = {
+  claude: { label: "Claude Code", hint: "CLAUDE.md, skills, MCP servers in .mcp.json" },
+  codex: { label: "Codex", hint: "skills in .agents/skills" },
+  cursor: { label: "Cursor", hint: "skills, MCP servers in .cursor/mcp.json" }
+};
+var CLAUDE_SKILLS_DIR = ".claude/skills";
+var AGENTS_SKILLS_DIR = ".agents/skills";
+function mcpServers({ consent }) {
+  return {
+    "next-devtools": { command: "npx", args: ["-y", "next-devtools-mcp@latest"] },
+    playwright: { command: "npx", args: ["-y", "@playwright/mcp@latest"] },
+    shadcn: { command: "npx", args: ["-y", "shadcn@latest", "mcp"] },
+    ...consent ? { "payload-consent": { command: "npx", args: ["payload-consent", "mcp"] } } : {}
+  };
+}
+function renderMcpJson(servers) {
+  return `${JSON.stringify({ mcpServers: servers }, null, 2)}
+`;
+}
+function parseAgents(raw) {
+  if (raw === void 0) return {};
+  const items = raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (items.length === 1 && items[0] === "none") return { agents: [] };
+  for (const item of items) {
+    if (!AGENT_KEYS.includes(item)) {
+      return { error: `Unknown value "${item}" for --agents. Allowed: ${AGENT_KEYS.join(", ")}, none` };
+    }
+  }
+  return { agents: AGENT_KEYS.filter((key) => items.includes(key)) };
+}
+function agentFiles(agents) {
+  const has = (key) => agents.includes(key);
+  return [
+    "AGENTS.md",
+    ...has("claude") ? ["CLAUDE.md", CLAUDE_SKILLS_DIR, ".claude/settings.json", ".mcp.json"] : [],
+    ...has("codex") || has("cursor") && !has("claude") ? [AGENTS_SKILLS_DIR] : [],
+    ...has("cursor") ? [".cursor/mcp.json"] : []
+  ];
+}
+async function applyAgentsChoice(directory, agents, { consent }) {
+  const has = (key) => agents.includes(key);
+  const at = (rel) => path.join(directory, rel);
+  const servers = renderMcpJson(mcpServers({ consent }));
+  if (agentFiles(agents).includes(AGENTS_SKILLS_DIR)) {
+    if (!existsSync(at(CLAUDE_SKILLS_DIR))) {
+      throw new Error(`The template is missing ${CLAUDE_SKILLS_DIR}; it cannot scaffold agent skills.`);
+    }
+    await mkdir(path.dirname(at(AGENTS_SKILLS_DIR)), { recursive: true });
+    await cp(at(CLAUDE_SKILLS_DIR), at(AGENTS_SKILLS_DIR), { recursive: true });
+  }
+  if (has("claude")) {
+    await writeFile(at(".mcp.json"), servers);
+  } else {
+    for (const rel of ["CLAUDE.md", ".claude", ".mcp.json"]) {
+      await rm(at(rel), { force: true, recursive: true });
+    }
+  }
+  if (has("cursor")) {
+    await mkdir(at(".cursor"), { recursive: true });
+    await writeFile(at(".cursor/mcp.json"), servers);
+  }
+}
+
 // src/databases.ts
 var DB_CHOICES = {
   postgres: {
@@ -69,19 +137,19 @@ function defaultConnectionString(db, projectSlug) {
 }
 
 // src/scheduler.ts
-import { cp } from "fs/promises";
-import { existsSync } from "fs";
-import path2 from "path";
+import { cp as cp2 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import path3 from "path";
 
 // src/variants.ts
-import { rm } from "fs/promises";
-import path from "path";
+import { rm as rm2 } from "fs/promises";
+import path2 from "path";
 var VARIANT_DIR = "variants";
 function variantPath(step) {
-  return path.join(VARIANT_DIR, step);
+  return path2.join(VARIANT_DIR, step);
 }
 async function removeVariants(directory) {
-  await rm(path.join(directory, VARIANT_DIR), { force: true, recursive: true });
+  await rm2(path2.join(directory, VARIANT_DIR), { force: true, recursive: true });
 }
 
 // src/scheduler.ts
@@ -160,15 +228,15 @@ function sortKeys(obj) {
 }
 async function applySchedulerChoice(directory, enabled) {
   if (!enabled) return;
-  const variant = path2.join(directory, VARIANT_SCHEDULER);
-  if (!existsSync(variant)) {
+  const variant = path3.join(directory, VARIANT_SCHEDULER);
+  if (!existsSync2(variant)) {
     throw new Error(`The template is missing ${VARIANT_SCHEDULER}; it cannot scaffold with the scheduler.`);
   }
   for (const name of SEAM_FILES) {
-    await cp(path2.join(variant, name), path2.join(directory, "src/scheduler", name));
+    await cp2(path3.join(variant, name), path3.join(directory, "src/scheduler", name));
   }
-  await cp(path2.join(variant, ACTION_DIR), path2.join(directory, "src/scheduler", ACTION_DIR), { recursive: true });
-  await cp(path2.join(variant, "tests/scheduler.spec.ts"), path2.join(directory, "tests/unit/scheduler.spec.ts"));
+  await cp2(path3.join(variant, ACTION_DIR), path3.join(directory, "src/scheduler", ACTION_DIR), { recursive: true });
+  await cp2(path3.join(variant, "tests/scheduler.spec.ts"), path3.join(directory, "tests/unit/scheduler.spec.ts"));
 }
 function renderVercelJson() {
   return `${JSON.stringify(
@@ -370,6 +438,7 @@ function helpText(version2) {
         --scheduler               Scheduled and recurring actions (Payload Action Scheduler)
         --no-scheduler            No scheduler
         --runner <kind>           ${RUNNER_KEYS.join(" | ")} (what runs the queue; default: clock)
+        --agents <list>           Comma-separated: ${AGENT_KEYS.join(", ")}, or none (skills and MCP servers)
         --use-pnpm | --use-npm | --use-yarn | --use-bun
         --no-install              Skip dependency installation
         --no-git                  Skip git init
@@ -384,6 +453,7 @@ function helpText(version2) {
     $ npx create-payload-stack@latest ridgeline
     $ npx create-payload-stack@latest ridgeline -d sqlite --auth email-password,passkey --billing none -y
     $ npx create-payload-stack@latest ridgeline --storage vercel-blob -y
+    $ npx create-payload-stack@latest ridgeline --agents claude,cursor -y
 
   Docs: https://payload.solutions/docs/payload-stack
 `;
@@ -406,6 +476,7 @@ function parse(argv) {
       consent: { type: "boolean" },
       scheduler: { type: "boolean" },
       runner: { type: "string" },
+      agents: { type: "string" },
       "use-pnpm": { type: "boolean" },
       "use-npm": { type: "boolean" },
       "use-yarn": { type: "boolean" },
@@ -435,6 +506,7 @@ function parse(argv) {
       consent: values.consent,
       scheduler: values.scheduler,
       runner: values.runner,
+      agents: values.agents,
       packageManager,
       install: values.install ?? true,
       git: values.git ?? true,
@@ -452,18 +524,18 @@ function parse(argv) {
 // src/cli.ts
 import * as p from "@clack/prompts";
 import { execa as execa2 } from "execa";
-import { existsSync as existsSync6 } from "fs";
-import path7 from "path";
+import { existsSync as existsSync7 } from "fs";
+import path8 from "path";
 import pc2 from "picocolors";
 
 // src/configure.ts
-import { readFile, writeFile } from "fs/promises";
-import path5 from "path";
+import { readFile, writeFile as writeFile2 } from "fs/promises";
+import path6 from "path";
 
 // src/consent.ts
-import { cp as cp2, rm as rm2, rmdir } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
-import path3 from "path";
+import { cp as cp3, rm as rm3, rmdir } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import path4 from "path";
 var CONSENT_PACKAGE = "@payload-solutions/plugin-consent";
 var CONSENT_REACT_PACKAGE = "@payload-solutions/consent-react";
 var CONSENT_VERSION = "0.1.1";
@@ -498,25 +570,25 @@ function sortKeys2(obj) {
 }
 async function applyConsentChoice(directory, enabled) {
   if (!enabled) return;
-  const variant = path3.join(directory, VARIANT_CONSENT);
-  if (!existsSync2(variant)) {
+  const variant = path4.join(directory, VARIANT_CONSENT);
+  if (!existsSync3(variant)) {
     throw new Error(`The template is missing ${VARIANT_CONSENT}; it cannot scaffold with consent.`);
   }
   for (const name of [...SEAM_FILES2, ...BANNER_FILES]) {
-    await cp2(path3.join(variant, name), path3.join(directory, "src/consent", name), { recursive: true });
+    await cp3(path4.join(variant, name), path4.join(directory, "src/consent", name), { recursive: true });
   }
-  await cp2(path3.join(variant, "tests/consent.spec.ts"), path3.join(directory, "tests/unit/consent.spec.ts"));
+  await cp3(path4.join(variant, "tests/consent.spec.ts"), path4.join(directory, "tests/unit/consent.spec.ts"));
   for (const name of TEMPLATE_LEGAL_FILES) {
-    await rm2(path3.join(directory, name), { force: true, recursive: true });
+    await rm3(path4.join(directory, name), { force: true, recursive: true });
   }
-  await rmdir(path3.join(directory, "src/seed")).catch(() => {
+  await rmdir(path4.join(directory, "src/seed")).catch(() => {
   });
 }
 
 // src/emails.ts
-import { cp as cp3, rm as rm3 } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
-import path4 from "path";
+import { cp as cp4, rm as rm4 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import path5 from "path";
 var EMAILS_PACKAGE = "@payload-solutions/plugin-emails";
 var EMAILS_VERSION = "0.1.1";
 var REACT_EMAIL_COMPONENTS = ["@react-email/components", "^1.0.12"];
@@ -588,17 +660,17 @@ function sortKeys3(obj) {
 }
 var REACT_EMAIL_FILES = ["src/emails/send.ts", "src/components/auth/email"];
 async function applyEmailsChoice(directory, enabled) {
-  const variant = path4.join(directory, VARIANT_EMAILS);
+  const variant = path5.join(directory, VARIANT_EMAILS);
   if (enabled) {
-    if (!existsSync3(variant)) {
+    if (!existsSync4(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 cp3(path4.join(variant, name), path4.join(directory, "src/emails", name), { recursive: true });
+      await cp4(path5.join(variant, name), path5.join(directory, "src/emails", name), { recursive: true });
     }
-    await cp3(path4.join(variant, "tests/emails.spec.ts"), path4.join(directory, "tests/unit/emails.spec.ts"));
+    await cp4(path5.join(variant, "tests/emails.spec.ts"), path5.join(directory, "tests/unit/emails.spec.ts"));
     for (const name of REACT_EMAIL_FILES) {
-      await rm3(path4.join(directory, name), { force: true, recursive: true });
+      await rm4(path5.join(directory, name), { force: true, recursive: true });
     }
   }
 }
@@ -606,7 +678,7 @@ async function applyEmailsChoice(directory, enabled) {
 // src/utils.ts
 import slugifyBase from "@sindresorhus/slugify";
 import { randomBytes } from "crypto";
-import { existsSync as existsSync4, readdirSync } from "fs";
+import { existsSync as existsSync5, readdirSync } from "fs";
 import { execa } from "execa";
 function slugify(input) {
   return slugifyBase(input.trim()).replace(/^-+|-+$/g, "") || "my-saas";
@@ -615,7 +687,7 @@ function generateSecret(bytes = 32) {
   return randomBytes(bytes).toString("base64url");
 }
 function isDirectoryEmpty(dir) {
-  if (!existsSync4(dir)) return true;
+  if (!existsSync5(dir)) return true;
   const entries = readdirSync(dir).filter((e) => ![".git", ".DS_Store"].includes(e));
   return entries.length === 0;
 }
@@ -881,8 +953,8 @@ function escapeRegExp(s) {
 }
 async function configureProject(o) {
   const db = DB_CHOICES[o.db];
-  const read = (rel) => readFile(path5.join(o.directory, rel), "utf8");
-  const write = (rel, content) => writeFile(path5.join(o.directory, rel), content);
+  const read = (rel) => readFile(path6.join(o.directory, rel), "utf8");
+  const write = (rel, content) => writeFile2(path6.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");
@@ -892,6 +964,7 @@ async function configureProject(o) {
   await applyConsentChoice(o.directory, o.consent);
   await applySchedulerChoice(o.directory, o.scheduler);
   await removeVariants(o.directory);
+  await applyAgentsChoice(o.directory, o.agents, { consent: o.consent });
   if (o.scheduler && o.runner === "vercel") {
     await write("vercel.json", renderVercelJson());
   }
@@ -936,9 +1009,9 @@ var AUTH_METHODS = ["email-password", "magic-link", "passkey"];
 var SOCIAL_PROVIDERS = ["google", "github"];
 
 // src/template.ts
-import { cp as cp4, mkdir, rm as rm4 } from "fs/promises";
-import { existsSync as existsSync5 } from "fs";
-import path6 from "path";
+import { cp as cp5, mkdir as mkdir2 } from "fs/promises";
+import { existsSync as existsSync6 } from "fs";
+import path7 from "path";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import * as tar from "tar";
@@ -953,7 +1026,7 @@ async function downloadTemplate({ dest, branch }) {
 Check your network, or pass --local-template <path> to scaffold from a local checkout.`
     );
   }
-  await mkdir(dest, { recursive: true });
+  await mkdir2(dest, { recursive: true });
   const prefixDepth = 1 + TEMPLATE_PATH.split("/").length;
   await pipeline(
     Readable.fromWeb(response.body),
@@ -966,25 +1039,25 @@ Check your network, or pass --local-template <path> to scaffold from a local che
       }
     })
   );
-  if (!existsSync5(path6.join(dest, "package.json"))) {
+  if (!existsSync6(path7.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 = path6.resolve(from);
-  if (!existsSync5(path6.join(source, "package.json"))) {
+  const source = path7.resolve(from);
+  if (!existsSync6(path7.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 cp4(source, dest, {
+  await mkdir2(dest, { recursive: true });
+  await cp5(source, dest, {
     recursive: true,
     filter: (src) => {
-      const rel = path6.relative(source, src);
-      const top = rel.split(path6.sep)[0];
-      return !["node_modules", ".next", ".turbo", ".env", "test-results", "playwright-report", "next-env.d.ts", "tsconfig.tsbuildinfo", "CLAUDE.md"].includes(top ?? "");
+      const rel = path7.relative(source, src);
+      const top = rel.split(path7.sep)[0];
+      if (rel === path7.join(".claude", "settings.local.json")) return false;
+      return !["node_modules", ".next", ".turbo", ".env", "test-results", "playwright-report", "next-env.d.ts", "tsconfig.tsbuildinfo"].includes(top ?? "");
     }
   });
-  await rm4(path6.join(dest, "CLAUDE.md"), { force: true });
 }
 
 // src/cli.ts
@@ -1023,7 +1096,7 @@ async function run(flags, positionalName) {
     })
   );
   const slug = slugify(name);
-  const directory = path7.resolve(process.cwd(), slug);
+  const directory = path8.resolve(process.cwd(), slug);
   if (!isDirectoryEmpty(directory)) {
     bail(`Directory ./${slug} already exists and is not empty.`);
   }
@@ -1148,6 +1221,16 @@ async function run(flags, positionalName) {
       }))
     })
   ));
+  const agentsFlag = parseAgents(flags.agents);
+  if (agentsFlag.error) bail(agentsFlag.error);
+  const agents = agentsFlag.agents ?? (flags.defaults ? [...AGENT_KEYS] : guard(
+    await p.multiselect({
+      message: "Coding agents",
+      required: false,
+      initialValues: [...AGENT_KEYS],
+      options: AGENT_KEYS.map((key) => ({ value: key, label: AGENT_CHOICES[key].label, hint: AGENT_CHOICES[key].hint }))
+    })
+  ));
   const packageManager = flags.packageManager ?? await detectPackageManager();
   const options = {
     name,
@@ -1164,6 +1247,7 @@ async function run(flags, positionalName) {
     consent,
     scheduler,
     runner,
+    agents,
     packageManager,
     install: flags.install,
     git: flags.git
@@ -1200,7 +1284,7 @@ async function run(flags, positionalName) {
 ${error instanceof Error ? error.message.split("\n")[0] : ""}`);
     }
   }
-  if (options.git && !existsSync6(path7.join(directory, ".git"))) {
+  if (options.git && !existsSync7(path8.join(directory, ".git"))) {
     try {
       await execa2("git", ["init", "-b", "main"], { cwd: directory });
       await execa2("git", ["add", "-A"], { cwd: directory });
@@ -1223,7 +1307,11 @@ ${error instanceof Error ? error.message.split("\n")[0] : ""}`);
       "# the seeded legal pages are templates, not policy: the homepage shows the six steps in development",
       `# ${CONSENT_DOCS}`
     ] : [],
-    ...scheduler ? ["# scheduled actions are under System -> Scheduled Actions in the admin", ...RUNNER_CHOICES[runner].next()] : []
+    ...scheduler ? ["# scheduled actions are under System -> Scheduled Actions in the admin", ...RUNNER_CHOICES[runner].next()] : [],
+    ...agents.length ? [
+      `# agents: AGENTS.md and the stack-* skills are set up for ${listWords(agents.map((key) => AGENT_CHOICES[key].label))}`,
+      `# agents finish with ${runCommand(packageManager, "verify")} (typecheck, lint, unit tests)`
+    ] : []
   ];
   p.note(steps.join("\n"), "Done. Next steps:");
   p.outro(`Docs: ${pc2.underline(DOCS2)}`);

package/package.json

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