create-payload-stack 0.4.0 → 0.5.0

package/dist/index.js

@@ -68,6 +68,120 @@ function defaultConnectionString(db, projectSlug) {
   return `${db.connectionPrefix}${projectSlug}${db.connectionSuffix}`;
 }
 
+// src/scheduler.ts
+import { cp } 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/scheduler.ts
+var SCHEDULER_PACKAGE = "@payload-solutions/plugin-action-scheduler";
+var SCHEDULER_VERSION = "0.2.0";
+var VARIANT_SCHEDULER = variantPath("scheduler-plugin");
+var SEAM_FILES = ["plugin.ts", "jobs.ts", "hooks.ts"];
+var ACTION_DIR = "actions";
+var RUNNER_KEYS = ["clock", "vercel", "server", "later"];
+var DOCS = "https://payload.solutions/docs/payload-stack/scheduling";
+var ALTERNATIVES = [
+  "#   - Payload Clock: https://payloadclock.com (free; retries and alerts, works on any host)",
+  '#   - Vercel cron: a "crons" entry in vercel.json hitting the same path',
+  "#   - Long-lived server: RUN_JOBS_IN_PROCESS=true (never on serverless)",
+  "#   - Any cron you already have: curl the endpoint with the CRON_SECRET bearer token",
+  "#   - By hand: Scheduled Actions -> Run queue, in the admin",
+  `#   ${DOCS}`
+];
+var RUNNER_CHOICES = {
+  clock: {
+    label: "Payload Clock",
+    hint: "free hosted clock, retries and alerts, any host",
+    cronSecret: true,
+    inProcess: false,
+    next: () => [
+      "# scheduled actions need a clock. Sign up at https://payloadclock.com (free), point it at",
+      "#   POST/GET /api/payload-jobs/run?allQueues=true  with the CRON_SECRET in .env",
+      "# or use one of the others:",
+      ...ALTERNATIVES.slice(1)
+    ]
+  },
+  vercel: {
+    label: "Vercel cron",
+    hint: "vercel.json; once a minute on Pro, once a day on Hobby",
+    cronSecret: true,
+    inProcess: false,
+    next: () => [
+      "# vercel.json runs the queue every minute (Hobby plans get one run a day, which is coarse",
+      "#   for a scheduler: https://payloadclock.com is free and runs every minute on any plan)",
+      "# add CRON_SECRET from .env to the Vercel project: Vercel sends it as the bearer token",
+      ...ALTERNATIVES
+    ]
+  },
+  server: {
+    label: "This server",
+    hint: "RUN_JOBS_IN_PROCESS=true; docker, Fly, Railway, a VM",
+    cronSecret: true,
+    inProcess: true,
+    next: () => [
+      "# RUN_JOBS_IN_PROCESS=true in .env runs the queue in this process, every minute.",
+      "#   Never set it on Vercel or another serverless host, and run one instance with it.",
+      ...ALTERNATIVES
+    ]
+  },
+  later: {
+    label: "Decide later",
+    hint: "nothing runs the queue; the admin Run queue button still does",
+    cronSecret: false,
+    inProcess: false,
+    next: () => [
+      "# nothing runs the queue yet, so scheduled actions wait. Pick one when you deploy:",
+      ...ALTERNATIVES
+    ]
+  }
+};
+function swapSchedulerPackages(packageJson, enabled) {
+  const deps = { ...packageJson.dependencies };
+  const devDeps = { ...packageJson.devDependencies };
+  delete devDeps[SCHEDULER_PACKAGE];
+  if (enabled) deps[SCHEDULER_PACKAGE] = SCHEDULER_VERSION;
+  else delete deps[SCHEDULER_PACKAGE];
+  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 applySchedulerChoice(directory, enabled) {
+  if (!enabled) return;
+  const variant = path2.join(directory, VARIANT_SCHEDULER);
+  if (!existsSync(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 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"));
+}
+function renderVercelJson() {
+  return `${JSON.stringify(
+    {
+      $schema: "https://openapi.vercel.sh/vercel.json",
+      crons: [{ path: "/api/payload-jobs/run?allQueues=true", schedule: "* * * * *" }]
+    },
+    null,
+    2
+  )}
+`;
+}
+
 // src/storage.ts
 var LOCAL_STORAGE_CONFIG = `// Local disk (./media): fine for development, lost on redeploy on Vercel and other ephemeral hosts.
 // Move uploads to Vercel Blob, S3, R2, Azure, GCS or Uploadthing: https://payload.solutions/docs/payload-stack/storage`;
@@ -253,6 +367,9 @@ function helpText(version2) {
         --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
+        --scheduler               Scheduled and recurring actions (Payload Action Scheduler)
+        --no-scheduler            No scheduler
+        --runner <kind>           ${RUNNER_KEYS.join(" | ")} (what runs the queue; default: clock)
         --use-pnpm | --use-npm | --use-yarn | --use-bun
         --no-install              Skip dependency installation
         --no-git                  Skip git init
@@ -287,6 +404,8 @@ function parse(argv) {
       storage: { type: "string" },
       emails: { type: "boolean" },
       consent: { type: "boolean" },
+      scheduler: { type: "boolean" },
+      runner: { type: "string" },
       "use-pnpm": { type: "boolean" },
       "use-npm": { type: "boolean" },
       "use-yarn": { type: "boolean" },
@@ -314,6 +433,8 @@ function parse(argv) {
       storage: values.storage,
       emails: values.emails,
       consent: values.consent,
+      scheduler: values.scheduler,
+      runner: values.runner,
       packageManager,
       install: values.install ?? true,
       git: values.git ?? true,
@@ -331,31 +452,18 @@ function parse(argv) {
 // src/cli.ts
 import * as p from "@clack/prompts";
 import { execa as execa2 } from "execa";
-import { existsSync as existsSync5 } from "fs";
-import path6 from "path";
+import { existsSync as existsSync6 } from "fs";
+import path7 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 });
-}
+import path5 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";
 var CONSENT_PACKAGE = "@payload-solutions/plugin-consent";
 var CONSENT_REACT_PACKAGE = "@payload-solutions/consent-react";
 var CONSENT_VERSION = "0.1.0";
@@ -364,7 +472,7 @@ var CONSENT_PACKAGES = {
   [CONSENT_REACT_PACKAGE]: CONSENT_VERSION
 };
 var VARIANT_CONSENT = variantPath("consent-plugin");
-var SEAM_FILES = [
+var SEAM_FILES2 = [
   "plugin.ts",
   "collections.ts",
   "seed.ts",
@@ -383,32 +491,32 @@ function swapConsentPackages(packageJson, enabled) {
     if (enabled) deps[pkg] = CONSENT_PACKAGES[pkg];
     else delete deps[pkg];
   }
-  return { ...packageJson, dependencies: sortKeys(deps), devDependencies: sortKeys(devDeps) };
+  return { ...packageJson, dependencies: sortKeys2(deps), devDependencies: sortKeys2(devDeps) };
 }
-function sortKeys(obj) {
+function sortKeys2(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)) {
+  const variant = path3.join(directory, VARIANT_CONSENT);
+  if (!existsSync2(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 });
+  for (const name of [...SEAM_FILES2, ...BANNER_FILES]) {
+    await cp2(path3.join(variant, name), path3.join(directory, "src/consent", name), { recursive: true });
   }
-  await cp(path2.join(variant, "tests/consent.spec.ts"), path2.join(directory, "tests/unit/consent.spec.ts"));
+  await cp2(path3.join(variant, "tests/consent.spec.ts"), path3.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 rm2(path3.join(directory, name), { force: true, recursive: true });
   }
-  await rmdir(path2.join(directory, "src/seed")).catch(() => {
+  await rmdir(path3.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";
+import { cp as cp3, rm as rm3 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import path4 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"];
@@ -473,24 +581,24 @@ function swapEmailsPackages(packageJson, enabled) {
     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) };
+  return { ...packageJson, dependencies: sortKeys3(deps), devDependencies: sortKeys3(devDeps), scripts: sortKeys3(scripts) };
 }
-function sortKeys2(obj) {
+function sortKeys3(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);
+  const variant = path4.join(directory, VARIANT_EMAILS);
   if (enabled) {
-    if (!existsSync2(variant)) {
+    if (!existsSync3(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 cp3(path4.join(variant, name), path4.join(directory, "src/emails", name), { recursive: true });
     }
-    await cp2(path3.join(variant, "tests/emails.spec.ts"), path3.join(directory, "tests/unit/emails.spec.ts"));
+    await cp3(path4.join(variant, "tests/emails.spec.ts"), path4.join(directory, "tests/unit/emails.spec.ts"));
     for (const name of REACT_EMAIL_FILES) {
-      await rm3(path3.join(directory, name), { force: true, recursive: true });
+      await rm3(path4.join(directory, name), { force: true, recursive: true });
     }
   }
 }
@@ -498,7 +606,7 @@ async function applyEmailsChoice(directory, enabled) {
 // src/utils.ts
 import slugifyBase from "@sindresorhus/slugify";
 import { randomBytes } from "crypto";
-import { existsSync as existsSync3, readdirSync } from "fs";
+import { existsSync as existsSync4, readdirSync } from "fs";
 import { execa } from "execa";
 function slugify(input) {
   return slugifyBase(input.trim()).replace(/^-+|-+$/g, "") || "my-saas";
@@ -507,7 +615,7 @@ function generateSecret(bytes = 32) {
   return randomBytes(bytes).toString("base64url");
 }
 function isDirectoryEmpty(dir) {
-  if (!existsSync3(dir)) return true;
+  if (!existsSync4(dir)) return true;
   const entries = readdirSync(dir).filter((e) => ![".git", ".DS_Store"].includes(e));
   return entries.length === 0;
 }
@@ -696,7 +804,7 @@ function swapStoragePackage(packageJson, storage) {
     if (pkg !== storage?.packageName) delete deps[pkg];
   }
   if (storage) deps[storage.packageName] = payloadVersion;
-  return { ...packageJson, dependencies: sortKeys3(deps) };
+  return { ...packageJson, dependencies: sortKeys4(deps) };
 }
 function storageChoice(key) {
   return key === "none" ? null : STORAGE_CHOICES[key];
@@ -708,7 +816,7 @@ function swapDatabasePackage(packageJson, db) {
     if (other.packageName !== db.packageName) delete deps[other.packageName];
   }
   deps[db.packageName] = payloadVersion;
-  return { ...packageJson, dependencies: sortKeys3(deps) };
+  return { ...packageJson, dependencies: sortKeys4(deps) };
 }
 function stripWorkspaceDependencies(packageJson) {
   const next = { ...packageJson };
@@ -731,7 +839,10 @@ function renderEnv(example, o) {
     DATABASE_URL: o.connectionString,
     PAYLOAD_SECRET: generateSecret(24),
     BETTER_AUTH_SECRET: generateSecret(32),
-    NEXT_PUBLIC_APP_URL: o.appUrl ?? "http://localhost:3000"
+    NEXT_PUBLIC_APP_URL: o.appUrl ?? "http://localhost:3000",
+    // A clock needs a secret to get past jobs.access.run; without one that endpoint is admin-only.
+    ...o.cronSecret ? { CRON_SECRET: generateSecret(32) } : {},
+    ...o.inProcessRunner ? { RUN_JOBS_IN_PROCESS: "true" } : {}
   };
   const lines = example.split("\n").map((line) => {
     const m = /^#?\s?([A-Z0-9_]+)=(.*)$/.exec(line);
@@ -742,7 +853,7 @@ function renderEnv(example, o) {
   });
   return lines.join("\n");
 }
-function sortKeys3(obj) {
+function sortKeys4(obj) {
   return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
 }
 function escapeRegExp(s) {
@@ -750,8 +861,8 @@ function escapeRegExp(s) {
 }
 async function configureProject(o) {
   const db = DB_CHOICES[o.db];
-  const read = (rel) => readFile(path4.join(o.directory, rel), "utf8");
-  const write = (rel, content) => writeFile(path4.join(o.directory, rel), content);
+  const read = (rel) => readFile(path5.join(o.directory, rel), "utf8");
+  const write = (rel, content) => writeFile(path5.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");
@@ -759,18 +870,33 @@ async function configureProject(o) {
   await write("src/payload.config.ts", o.emails ? addEmailsPlugin(withAdapters) : withAdapters);
   await applyEmailsChoice(o.directory, o.emails);
   await applyConsentChoice(o.directory, o.consent);
+  await applySchedulerChoice(o.directory, o.scheduler);
   await removeVariants(o.directory);
+  if (o.scheduler && o.runner === "vercel") {
+    await write("vercel.json", renderVercelJson());
+  }
   const pkg = JSON.parse(await read("package.json"));
-  const configured = swapConsentPackages(
-    swapEmailsPackages(swapStoragePackage(swapDatabasePackage(pkg, db), storage), o.emails),
-    o.consent
+  const configured = swapSchedulerPackages(
+    swapConsentPackages(
+      swapEmailsPackages(swapStoragePackage(swapDatabasePackage(pkg, db), storage), o.emails),
+      o.consent
+    ),
+    o.scheduler
   );
   await write(
     "package.json",
     JSON.stringify(renameProject(stripWorkspaceDependencies(configured), o.slug), null, 2) + "\n"
   );
+  const runner = RUNNER_CHOICES[o.runner];
   const example = await read(".env.example");
-  await write(".env", renderEnv(example, { connectionString: o.connectionString }));
+  await write(
+    ".env",
+    renderEnv(example, {
+      connectionString: o.connectionString,
+      cronSecret: o.scheduler && runner.cronSecret,
+      inProcessRunner: o.scheduler && runner.inProcess
+    })
+  );
 }
 
 // src/options.ts
@@ -778,9 +904,9 @@ var AUTH_METHODS = ["email-password", "magic-link", "passkey"];
 var SOCIAL_PROVIDERS = ["google", "github"];
 
 // src/template.ts
-import { cp as cp3, mkdir, rm as rm4 } from "fs/promises";
-import { existsSync as existsSync4 } from "fs";
-import path5 from "path";
+import { cp as cp4, mkdir, rm as rm4 } from "fs/promises";
+import { existsSync as existsSync5 } from "fs";
+import path6 from "path";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import * as tar from "tar";
@@ -808,29 +934,29 @@ Check your network, or pass --local-template <path> to scaffold from a local che
       }
     })
   );
-  if (!existsSync4(path5.join(dest, "package.json"))) {
+  if (!existsSync5(path6.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 = path5.resolve(from);
-  if (!existsSync4(path5.join(source, "package.json"))) {
+  const source = path6.resolve(from);
+  if (!existsSync5(path6.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 cp3(source, dest, {
+  await cp4(source, dest, {
     recursive: true,
     filter: (src) => {
-      const rel = path5.relative(source, src);
-      const top = rel.split(path5.sep)[0];
+      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 ?? "");
     }
   });
-  await rm4(path5.join(dest, "CLAUDE.md"), { force: true });
+  await rm4(path6.join(dest, "CLAUDE.md"), { force: true });
 }
 
 // src/cli.ts
-var DOCS = "https://payload.solutions/docs/payload-stack";
+var DOCS2 = "https://payload.solutions/docs/payload-stack";
 var CONSENT_DOCS = "https://payload.solutions/docs/plugins/payload-consent/audit";
 function bail(message = "Cancelled.") {
   p.cancel(message);
@@ -865,7 +991,7 @@ async function run(flags, positionalName) {
     })
   );
   const slug = slugify(name);
-  const directory = path6.resolve(process.cwd(), slug);
+  const directory = path7.resolve(process.cwd(), slug);
   if (!isDirectoryEmpty(directory)) {
     bail(`Directory ./${slug} already exists and is not empty.`);
   }
@@ -966,6 +1092,30 @@ async function run(flags, positionalName) {
       inactive: "Plain legal pages, no banner"
     })
   ));
+  const scheduler = flags.scheduler ?? (flags.defaults ? true : guard(
+    await p.confirm({
+      message: "Scheduled and recurring actions",
+      initialValue: true,
+      active: "Trial reminders, dunning, sweeps, and a ledger in the admin (Payload Action Scheduler)",
+      inactive: "No scheduler"
+    })
+  ));
+  const runnerFlag = flags.runner;
+  if (runnerFlag && !RUNNER_KEYS.includes(runnerFlag)) {
+    bail(`Unknown value "${flags.runner}" for --runner. Allowed: ${RUNNER_KEYS.join(", ")}`);
+  }
+  if (runnerFlag && !scheduler) bail("--runner needs --scheduler. Nothing runs a queue that does not exist.");
+  const runner = !scheduler ? "later" : runnerFlag ?? (flags.defaults ? "clock" : guard(
+    await p.select({
+      message: "What runs the queue",
+      initialValue: "clock",
+      options: RUNNER_KEYS.map((key) => ({
+        value: key,
+        label: RUNNER_CHOICES[key].label,
+        hint: RUNNER_CHOICES[key].hint
+      }))
+    })
+  ));
   const packageManager = flags.packageManager ?? await detectPackageManager();
   const options = {
     name,
@@ -980,6 +1130,8 @@ async function run(flags, positionalName) {
     storage,
     emails,
     consent,
+    scheduler,
+    runner,
     packageManager,
     install: flags.install,
     git: flags.git
@@ -1015,7 +1167,7 @@ async function run(flags, positionalName) {
 ${error instanceof Error ? error.message.split("\n")[0] : ""}`);
     }
   }
-  if (options.git && !existsSync5(path6.join(directory, ".git"))) {
+  if (options.git && !existsSync6(path7.join(directory, ".git"))) {
     try {
       await execa2("git", ["init", "-b", "main"], { cwd: directory });
       await execa2("git", ["add", "-A"], { cwd: directory });
@@ -1037,10 +1189,11 @@ ${error instanceof Error ? error.message.split("\n")[0] : ""}`);
     ...consent ? [
       "# 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()] : []
   ];
   p.note(steps.join("\n"), "Done. Next steps:");
-  p.outro(`Docs: ${pc2.underline(DOCS)}`);
+  p.outro(`Docs: ${pc2.underline(DOCS2)}`);
 }
 
 // src/index.ts

package/package.json

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