create-raredays-app 0.1.0

package/bin/index.js

@@ -0,0 +1,1024 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { cp, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import * as p from "@clack/prompts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const templatesDir = resolve(packageRoot, "templates");
+const fragmentsDir = resolve(packageRoot, "scaffold-fragments");
+
+// ─── Presets ─────────────────────────────────────────────────────────────
+// Pre-configured template + module combinations for common app types.
+// These are offered in interactive mode and via --preset in non-interactive mode.
+
+const PRESETS = {
+  courseware: {
+    label: "Courseware",
+    hint: "Full course platform — identity, billing, CMS, video, courseware modules pre-wired.",
+    template: "full-stack",
+    modules: ["billing"],
+    vendors: [],
+    brandPrimary: "#7c3aed",
+    navigation: {
+      primary: [
+        { label: "Home", href: "/" },
+        { label: "Courses", href: "/courses" },
+        { label: "Pricing", href: "/#pricing" },
+      ],
+      footer: [
+        { label: "Privacy", href: "/privacy" },
+        { label: "Terms", href: "/terms" },
+        { label: "Contact", href: "/contact" },
+      ],
+    },
+  },
+  "internal-tool": {
+    label: "Internal Tool",
+    hint: "Admin dashboard — identity + jobs. Stat cards, data tables, no public-facing pages.",
+    template: "full-stack",
+    modules: ["jobs"],
+    vendors: [],
+    brandPrimary: "#0f172a",
+    navigation: {
+      primary: [
+        { label: "Dashboard", href: "/" },
+        { label: "Users", href: "/users" },
+        { label: "Jobs", href: "/jobs" },
+      ],
+      footer: [],
+    },
+  },
+  demo: {
+    label: "Demo",
+    hint: "Lightweight demo — static template, core + components only. No identity or billing.",
+    template: "static",
+    modules: [],
+    vendors: [],
+    brandPrimary: "#10b981",
+    navigation: {
+      primary: [{ label: "Home", href: "/" }],
+      footer: [{ label: "Built with RareDays", href: "https://raredays.com" }],
+    },
+  },
+};
+
+function availableModuleKeys() {
+  if (!existsSync(fragmentsDir)) return [];
+  try {
+    return readdirSync(fragmentsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .filter((name) => existsSync(resolve(fragmentsDir, name, "module.json")))
+      .toSorted();
+  } catch {
+    return [];
+  }
+}
+
+function printHelp() {
+  const modules = availableModuleKeys();
+  const modulesLine =
+    modules.length > 0 ? modules.join(",") : "(none — scaffold-fragments directory missing)";
+  console.log(`Usage: create-raredays-app [<project-directory>] [options]
+
+When invoked with no project directory, runs interactive mode (TUI).
+When invoked with a project directory, runs non-interactively with the supplied flags.
+
+Options:
+  --template <name>    "full-stack" (default), "client", or "static"
+  --preset <name>      Pre-configured app type: courseware, internal-tool, demo
+                       Sets template, modules, and branding. Overrides --template/--modules.
+  --modules <list>     Comma-separated. Discovered dynamically from scaffold-fragments:
+                       ${modulesLine}
+                       (full-stack + client templates)
+  --vendors <list>     Comma-separated module:vendor pairs, e.g.
+                       billing:stripe,cms:hygraph,email:resend,identity:better-auth
+  --remote-url <url>   Set git remote origin to this URL after scaffolding
+  --no-git             Skip git init
+  --no-install         Skip pnpm install at the end
+  --dev                Link @raredays/* deps as workspace:* (for in-repo dogfooding)
+  --harness <name>     Wire @raredays/mcp into an MCP-aware IDE.
+                       One of: claude-code, cursor, windsurf, none (default).
+                       Adds @raredays/mcp to devDependencies and writes the IDE
+                       config file pointing at the local install.
+  --deploy <target>    Scaffold deploy config for a target host.
+                       One of: vercel, none (default).
+                       Writes vercel.json, .env.example, docs/DEPLOY.md, and
+                       (full-stack only) .github/workflows/deploy-migrations.yml.
+  -h, --help           Show this help
+
+Presets:
+  courseware            Full course platform (full-stack + billing)
+  internal-tool         Admin dashboard (full-stack + jobs)
+  demo                  Lightweight demo (static, no modules)
+`);
+}
+
+function fail(message) {
+  console.error(`✗ ${message}`);
+  process.exit(1);
+}
+
+function cancelExit() {
+  p.cancel("Cancelled.");
+  process.exit(0);
+}
+
+function toSlug(name) {
+  const slug = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (slug.length === 0 || slug.length > 64) {
+    fail(
+      `Cannot derive a valid kebab-case slug from "${name}". Pick a project name with letters, digits, or hyphens.`,
+    );
+  }
+  return slug;
+}
+
+function isValidDomain(s) {
+  return /^[a-z0-9.-]+\.[a-z]{2,}$/i.test(s);
+}
+
+async function substituteSlug(filePath, slug) {
+  if (!existsSync(filePath)) return;
+  const original = await readFile(filePath, "utf8");
+  const replaced = original.replaceAll("__SLUG__", slug);
+  if (replaced !== original) {
+    await writeFile(filePath, replaced);
+  }
+}
+
+// ─── Fragment loading ────────────────────────────────────────────────────
+
+async function loadFragment(key) {
+  const dir = resolve(fragmentsDir, key);
+  const manifestPath = resolve(dir, "module.json");
+  if (!existsSync(manifestPath)) return null;
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  const runtime = {};
+  for (const slot of ["imports", "config", "ports", "exports"]) {
+    const path = resolve(dir, "runtime", `${slot}.ts`);
+    if (existsSync(path)) runtime[slot] = (await readFile(path, "utf8")).trimEnd();
+  }
+  const filesDir = resolve(dir, "files");
+  // Per-vendor file dirs at vendors/<key>/files/ — copied when the vendor is selected.
+  const vendors = (manifest.vendors ?? []).map((v) => {
+    const vendorFilesDir = resolve(dir, "vendors", v.key, "files");
+    return { ...v, filesDir: existsSync(vendorFilesDir) ? vendorFilesDir : null };
+  });
+  return {
+    ...manifest,
+    vendors,
+    dir,
+    runtime,
+    filesDir: existsSync(filesDir) ? filesDir : null,
+  };
+}
+
+async function loadAllFragments() {
+  if (!existsSync(fragmentsDir)) return [];
+  const entries = await readdir(fragmentsDir, { withFileTypes: true });
+  const fragments = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const f = await loadFragment(e.name);
+    if (f) fragments.push(f);
+  }
+  return fragments;
+}
+
+// ─── Runtime.ts composition ──────────────────────────────────────────────
+
+function composeRuntime(source, fragments) {
+  const slots = { imports: [], config: [], ports: [], exports: [] };
+  for (const f of fragments) {
+    for (const slot of Object.keys(slots)) {
+      if (f.runtime[slot]) slots[slot].push(f.runtime[slot]);
+    }
+  }
+  return source
+    .replace(
+      "// CRDA:imports",
+      slots.imports.length > 0 ? slots.imports.join("\n") : "// CRDA:imports",
+    )
+    .replace(
+      "// CRDA:config",
+      slots.config.length > 0
+        ? slots.config.join("\n\n")
+        : "// CRDA:config (no additional modules wired)",
+    )
+    .replace(
+      "  // CRDA:ports",
+      slots.ports.length > 0 ? slots.ports.join("\n").trimEnd() : "  // CRDA:ports",
+    )
+    .replace(
+      "// CRDA:exports",
+      slots.exports.length > 0 ? slots.exports.join("\n\n") : "// CRDA:exports",
+    );
+}
+
+// ─── Mock handlers composition ───────────────────────────────────────────
+
+function composeHandlers(source, vendorMocks) {
+  const imports = vendorMocks.map(
+    (m) => `import { ${m.named} } from ${JSON.stringify(m.package)};`,
+  );
+  const spread = vendorMocks.map((m) => `  ${m.named},`);
+  return source
+    .replace(
+      "// CRDA:mocks-imports",
+      imports.length > 0 ? imports.join("\n") : "// CRDA:mocks-imports",
+    )
+    .replace(
+      "  // CRDA:mocks-spread",
+      spread.length > 0 ? spread.join("\n") : "  // CRDA:mocks-spread",
+    );
+}
+
+// ─── Site spec customisation ─────────────────────────────────────────────
+
+async function customiseSiteSpec(filePath, opts) {
+  if (!existsSync(filePath)) return;
+  let content = await readFile(filePath, "utf8");
+  if (opts.displayName) {
+    content = content.replace(/name:\s*"[^"]*"/, `name: ${JSON.stringify(opts.displayName)}`);
+  }
+  if (opts.canonicalDomain) {
+    content = content.replace(
+      /canonicalDomain:\s*"[^"]*"/,
+      `canonicalDomain: ${JSON.stringify(opts.canonicalDomain)}`,
+    );
+  }
+  if (opts.brandPrimary) {
+    content = content.replace(
+      /primary:\s*"#[0-9a-fA-F]+"/,
+      `primary: ${JSON.stringify(opts.brandPrimary)}`,
+    );
+  }
+  await writeFile(filePath, content);
+}
+
+// ─── Env example ─────────────────────────────────────────────────────────
+
+async function writeEnvExample(targetDir, envVars) {
+  if (envVars.length === 0) return;
+  const path = resolve(targetDir, ".env.example");
+  const hasDbUrl = envVars.includes("DATABASE_URL");
+  const lines = [
+    "# Environment variables required by the modules you selected.",
+    "# Copy to .env.local and fill in real values before running.",
+    "",
+  ];
+  if (!hasDbUrl) {
+    lines.push("# Database (uncomment when wiring Drizzle queries)", "# DATABASE_URL=", "");
+  }
+  lines.push(...envVars.map((v) => `${v}=`), "");
+  await writeFile(path, lines.join("\n"));
+}
+
+// ─── Module/vendor flag parsing ──────────────────────────────────────────
+
+function parseCsv(value) {
+  if (!value) return [];
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+// ─── Deploy prompt (shared by interactive paths) ─────────────────────────
+
+async function promptDeploy() {
+  const choice = await p.select({
+    message: "Where will you deploy?",
+    options: [
+      {
+        value: "vercel",
+        label: "Vercel",
+        hint: "Recommended for Next.js — generous free tier, GitHub-integrated previews",
+      },
+      { value: "none", label: "Other / decide later" },
+    ],
+    initialValue: "vercel",
+  });
+  if (p.isCancel(choice)) cancelExit();
+  return choice === "none" ? null : choice;
+}
+
+// ─── Interactive mode ────────────────────────────────────────────────────
+
+async function runInteractive(allFragments) {
+  p.intro("create-raredays-app");
+
+  const projectName = await p.text({
+    message: "Project name (used as the directory + slug):",
+    placeholder: "my-app",
+    validate: (v) => {
+      if (!v) return "Required.";
+      if (existsSync(resolve(process.cwd(), v))) return `Directory ${v} already exists.`;
+      return undefined;
+    },
+  });
+  if (p.isCancel(projectName)) cancelExit();
+
+  const presetOrCustom = await p.select({
+    message: "What are you building?",
+    options: [
+      ...Object.entries(PRESETS).map(([key, preset]) => ({
+        value: key,
+        label: preset.label,
+        hint: preset.hint,
+      })),
+      { value: "custom", label: "Custom", hint: "Pick template and modules yourself" },
+    ],
+  });
+  if (p.isCancel(presetOrCustom)) cancelExit();
+
+  if (presetOrCustom !== "custom") {
+    const preset = PRESETS[presetOrCustom];
+    const displayName = await p.text({
+      message: "Display name (shown to users):",
+      placeholder: projectName,
+      defaultValue: projectName,
+    });
+    if (p.isCancel(displayName)) cancelExit();
+
+    const deploy = await promptDeploy();
+
+    const gitInit = await p.confirm({
+      message: "Initialize a git repo?",
+      initialValue: true,
+    });
+    if (p.isCancel(gitInit)) cancelExit();
+
+    const runInstall = await p.confirm({
+      message: "Run `pnpm install` after scaffolding?",
+      initialValue: true,
+    });
+    if (p.isCancel(runInstall)) cancelExit();
+
+    return {
+      projectName,
+      template: preset.template,
+      displayName: displayName || projectName,
+      canonicalDomain: undefined,
+      brandPrimary: preset.brandPrimary,
+      selectedModules: preset.modules,
+      selectedVendors: preset.vendors,
+      remoteUrl: undefined,
+      gitInit,
+      runInstall,
+      deploy,
+    };
+  }
+
+  const template = await p.select({
+    message: "Template:",
+    options: [
+      {
+        value: "static",
+        label: "static — truly static, deployable to CDN/edge (no SSR, no APIs)",
+      },
+      {
+        value: "client",
+        label: "client — Next.js BFF + SPA, proxies to an external backend",
+      },
+      {
+        value: "full-stack",
+        label: "full-stack — Next.js + Drizzle + framework modules",
+      },
+    ],
+    initialValue: "full-stack",
+  });
+  if (p.isCancel(template)) cancelExit();
+
+  const displayName = await p.text({
+    message: "Display name (shown to users):",
+    placeholder: projectName,
+    defaultValue: projectName,
+  });
+  if (p.isCancel(displayName)) cancelExit();
+
+  const canonicalDomain = await p.text({
+    message: "Canonical domain (optional, e.g. example.com):",
+    placeholder: `${projectName}.example.com`,
+    validate: (v) => (v && !isValidDomain(v) ? "Doesn't look like a domain." : undefined),
+  });
+  if (p.isCancel(canonicalDomain)) cancelExit();
+
+  const brandPrimary = await p.text({
+    message: "Brand primary color (hex):",
+    placeholder: "#10b981",
+    defaultValue: "#10b981",
+    validate: (v) => (v && !/^#[0-9a-fA-F]{3,8}$/.test(v) ? "Hex color, e.g. #10b981." : undefined),
+  });
+  if (p.isCancel(brandPrimary)) cancelExit();
+
+  let selectedModules = [];
+  let selectedVendors = [];
+  const applicable = allFragments.filter((f) => (f.templates ?? ["full-stack"]).includes(template));
+  if (template !== "static" && applicable.length > 0) {
+    const moduleChoice = await p.multiselect({
+      message:
+        "Modules to wire (space to toggle; identity is always wired with an in-memory dev provider — selecting it lets you pick a production vendor):",
+      options: applicable.map((f) => ({ value: f.key, label: f.label, hint: f.description })),
+      required: false,
+    });
+    if (p.isCancel(moduleChoice)) cancelExit();
+    selectedModules = moduleChoice;
+
+    for (const f of applicable) {
+      if (!selectedModules.includes(f.key)) continue;
+      if (!f.vendors || f.vendors.length === 0) continue;
+      const vendorChoice = await p.select({
+        message: `${f.label} — production provider:`,
+        options: [
+          { value: "none", label: "None", hint: "Use the in-memory dev adapter" },
+          ...f.vendors.map((v) => ({ value: `${f.key}:${v.key}`, label: v.label })),
+        ],
+      });
+      if (p.isCancel(vendorChoice)) cancelExit();
+      if (vendorChoice !== "none") selectedVendors.push(vendorChoice);
+    }
+  }
+
+  const deploy = await promptDeploy();
+
+  const remoteUrl = await p.text({
+    message: "Upstream git remote URL (optional):",
+    placeholder: "git@github.com:org/repo.git",
+  });
+  if (p.isCancel(remoteUrl)) cancelExit();
+
+  const gitInit = await p.confirm({
+    message: "Initialize a git repo?",
+    initialValue: true,
+  });
+  if (p.isCancel(gitInit)) cancelExit();
+
+  const runInstall = await p.confirm({
+    message: "Run `pnpm install` after scaffolding?",
+    initialValue: true,
+  });
+  if (p.isCancel(runInstall)) cancelExit();
+
+  return {
+    projectName,
+    template,
+    displayName: displayName || projectName,
+    canonicalDomain: canonicalDomain || undefined,
+    brandPrimary: brandPrimary || undefined,
+    selectedModules,
+    selectedVendors,
+    remoteUrl: remoteUrl || undefined,
+    gitInit,
+    runInstall,
+    deploy,
+  };
+}
+
+// ─── Scaffold ────────────────────────────────────────────────────────────
+
+async function scaffold(opts) {
+  const targetDir = resolve(process.cwd(), opts.projectName);
+  if (existsSync(targetDir)) fail(`Directory already exists: ${targetDir}`);
+  const templateDir = resolve(templatesDir, opts.template);
+  if (!existsSync(templateDir)) fail(`Unknown template: ${opts.template}`);
+
+  const slug = toSlug(opts.projectName);
+
+  await cp(templateDir, targetDir, { recursive: true });
+
+  // Rename underscore-prefixed files/dirs (root .gitignore would
+  // otherwise filter dot-prefixed ones out of the published template).
+  for (const [from, to] of [
+    ["_gitignore", ".gitignore"],
+    ["_npmrc", ".npmrc"],
+    ["_claude", ".claude"],
+    ["_github", ".github"],
+  ]) {
+    const fromPath = resolve(targetDir, from);
+    if (existsSync(fromPath)) await rename(fromPath, resolve(targetDir, to));
+  }
+
+  // Substitute __SLUG__ in site.spec.ts, then apply brand/identity prompts.
+  await substituteSlug(resolve(targetDir, "site.spec.ts"), slug);
+  await customiseSiteSpec(resolve(targetDir, "site.spec.ts"), {
+    displayName: opts.displayName,
+    canonicalDomain: opts.canonicalDomain,
+    brandPrimary: opts.brandPrimary,
+  });
+
+  // Load + apply selected fragments. Static templates don't have a
+  // composition root, so skip module composition entirely there.
+  const collectedDeps = {};
+  const envVars = [];
+  const vendorMocks = [];
+  if (opts.template !== "static" && opts.selectedModules.length > 0) {
+    const fragments = await Promise.all(opts.selectedModules.map(loadFragment));
+    const valid = fragments.filter(Boolean);
+
+    for (const f of valid) {
+      Object.assign(collectedDeps, f.deps ?? {});
+      if (f.filesDir) await cp(f.filesDir, targetDir, { recursive: true });
+    }
+
+    for (const pair of opts.selectedVendors) {
+      const [moduleKey, vendorKey] = pair.split(":");
+      const f = valid.find((x) => x.key === moduleKey);
+      const vendor = f?.vendors?.find((v) => v.key === vendorKey);
+      if (!vendor) continue;
+      Object.assign(collectedDeps, vendor.deps ?? {});
+      for (const v of vendor.env ?? []) envVars.push(v);
+      if (vendor.mocks) {
+        vendorMocks.push(vendor.mocks);
+        Object.assign(collectedDeps, vendor.mocks.peerDeps ?? {});
+      }
+      if (vendor.filesDir) await cp(vendor.filesDir, targetDir, { recursive: true });
+    }
+
+    const runtimePath = resolve(targetDir, "app/lib/runtime.ts");
+    const source = await readFile(runtimePath, "utf8");
+    await writeFile(runtimePath, composeRuntime(source, valid));
+  }
+
+  // Compose mocks/handlers.ts for any template that ships it (full-stack + client).
+  if (opts.template !== "static") {
+    const handlersPath = resolve(targetDir, "mocks/handlers.ts");
+    if (existsSync(handlersPath)) {
+      const source = await readFile(handlersPath, "utf8");
+      await writeFile(handlersPath, composeHandlers(source, vendorMocks));
+    }
+  }
+
+  // Merge deps into package.json + rename + dev-link.
+  const pkgPath = resolve(targetDir, "package.json");
+  const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  pkg.name = slug;
+  pkg.dependencies = { ...pkg.dependencies, ...collectedDeps };
+  if (opts.dev) {
+    for (const field of ["dependencies", "devDependencies"]) {
+      const deps = pkg[field];
+      if (!deps) continue;
+      for (const name of Object.keys(deps)) {
+        if (name.startsWith("@raredays/")) deps[name] = "workspace:*";
+      }
+    }
+  }
+  // Apply MCP harness wiring (devDep + IDE config) before writing pkg out.
+  await applyHarness(targetDir, pkg, opts.harness, opts.dev);
+
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+  // Apply deploy-target scaffolding (vercel.json, DEPLOY.md, migrations workflow, etc.).
+  // Must run before .env.example so deploy can request additional vars (e.g. DATABASE_URL).
+  const deployEnvVars = await applyDeploy(targetDir, opts);
+  for (const v of deployEnvVars) if (!envVars.includes(v)) envVars.push(v);
+
+  if (envVars.length > 0) await writeEnvExample(targetDir, envVars);
+
+  // Optional git init + remote.
+  if (opts.gitInit) {
+    spawnSync("git", ["init", "--quiet", "--initial-branch=main"], { cwd: targetDir });
+    if (opts.remoteUrl) {
+      spawnSync("git", ["remote", "add", "origin", opts.remoteUrl], { cwd: targetDir });
+    }
+  }
+
+  // Optional install.
+  if (opts.runInstall) {
+    p.note("Running `pnpm install` — this can take a minute.", "Installing");
+    const result = spawnSync("pnpm", ["install"], { cwd: targetDir, stdio: "inherit" });
+    if (result.status !== 0) {
+      p.log.warn("pnpm install failed. Run it manually in the project directory.");
+    }
+
+    p.note("Initializing skillex skill registry.", "Skillex");
+    spawnSync("skillex", ["init", "--yes"], { cwd: targetDir });
+  }
+
+  return { targetDir, slug, envVars };
+}
+
+// ─── MCP harness wiring ──────────────────────────────────────────────────
+
+const HARNESS_CONFIGS = {
+  "claude-code": ".claude/mcp.json",
+  cursor: ".cursor/mcp.json",
+  windsurf: ".windsurf/mcp.json",
+};
+
+const MCP_VERSION = "0.0.1";
+
+async function applyHarness(targetDir, pkg, harness, dev) {
+  if (!harness || harness === "none") return;
+  if (!(harness in HARNESS_CONFIGS)) {
+    p.log.warn(
+      `Unknown --harness "${harness}". Use one of: ${Object.keys(HARNESS_CONFIGS).join(", ")}, none.`,
+    );
+    return;
+  }
+
+  // Add @raredays/mcp to devDependencies.
+  pkg.devDependencies ??= {};
+  pkg.devDependencies["@raredays/mcp"] = dev ? "workspace:*" : `^${MCP_VERSION}`;
+
+  // Write the IDE config file.
+  const relConfig = HARNESS_CONFIGS[harness];
+  const configPath = resolve(targetDir, relConfig);
+  const configDir = dirname(configPath);
+  if (!existsSync(configDir)) {
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(configDir, { recursive: true });
+  }
+
+  const config = {
+    mcpServers: {
+      raredays: {
+        command: "pnpm",
+        args: ["exec", "raredays-mcp"],
+      },
+    },
+  };
+  const { writeFile: writeF } = await import("node:fs/promises");
+  await writeF(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+
+  p.note(
+    `MCP wired for ${harness}. Connect your IDE to see the @raredays/* tools.\nConfig: ${relConfig}`,
+    "MCP",
+  );
+}
+
+// ─── Deploy-target scaffolding ───────────────────────────────────────────
+
+// Module-level deploy env-var manifest. These are vars a module needs in
+// production regardless of the vendor selection (vendor-specific env vars
+// are already collected via fragment.vendors[].env).
+const DEPLOY_MODULE_ENV = {
+  identity: ["BETTER_AUTH_SECRET", "BETTER_AUTH_URL"],
+};
+
+const VERCEL_JSON = {
+  $schema: "https://openapi.vercel.sh/vercel.json",
+  framework: "nextjs",
+  buildCommand: "pnpm build",
+  installCommand: "pnpm install",
+  regions: ["iad1"],
+  functions: {
+    "app/api/**/*.ts": {
+      memory: 1024,
+    },
+  },
+};
+
+async function applyDeploy(targetDir, opts) {
+  if (!opts.deploy || opts.deploy === "none") return [];
+  if (opts.deploy !== "vercel") {
+    p.log?.warn?.(`Unknown --deploy "${opts.deploy}". Skipping deploy scaffolding.`);
+    return [];
+  }
+
+  const { mkdir } = await import("node:fs/promises");
+  const isFullStack = opts.template === "full-stack";
+  const hasApi = opts.template !== "static";
+
+  // 1. vercel.json — strip functions block for static templates (no API routes).
+  const vercelConfig = { ...VERCEL_JSON };
+  if (!hasApi) delete vercelConfig.functions;
+  await writeFile(resolve(targetDir, "vercel.json"), `${JSON.stringify(vercelConfig, null, 2)}\n`);
+
+  // 2. Append .vercel/ to .gitignore (so `vercel link` artefacts don't get committed).
+  const gitignorePath = resolve(targetDir, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    const existing = await readFile(gitignorePath, "utf8");
+    if (!existing.includes(".vercel")) {
+      await writeFile(gitignorePath, `${existing.trimEnd()}\n\n# Vercel\n.vercel/\n`);
+    }
+  }
+
+  // 3. docs/DEPLOY.md — one-page runbook.
+  const docsDir = resolve(targetDir, "docs");
+  if (!existsSync(docsDir)) await mkdir(docsDir, { recursive: true });
+  await writeFile(resolve(docsDir, "DEPLOY.md"), buildDeployMd(opts));
+
+  // 4. Migrations workflow — only for full-stack (static/client don't have a DB).
+  if (isFullStack) {
+    const workflowsDir = resolve(targetDir, ".github", "workflows");
+    if (!existsSync(workflowsDir)) await mkdir(workflowsDir, { recursive: true });
+    await writeFile(resolve(workflowsDir, "deploy-migrations.yml"), buildMigrationsWorkflow());
+  }
+
+  // 5. scripts/setup-vercel.sh — interactive linker.
+  const scriptsDir = resolve(targetDir, "scripts");
+  if (!existsSync(scriptsDir)) await mkdir(scriptsDir, { recursive: true });
+  const scriptPath = resolve(scriptsDir, "setup-vercel.sh");
+  await writeFile(scriptPath, buildSetupVercelScript());
+  const { chmod } = await import("node:fs/promises");
+  await chmod(scriptPath, 0o755);
+
+  // 6. Return the extra env-vars deploy implies.
+  const extra = [];
+  if (isFullStack) extra.push("DATABASE_URL");
+  for (const m of opts.selectedModules ?? []) {
+    for (const v of DEPLOY_MODULE_ENV[m] ?? []) extra.push(v);
+  }
+  return extra;
+}
+
+function buildDeployMd(opts) {
+  const isFullStack = opts.template === "full-stack";
+  const dbSections = isFullStack
+    ? `
+## 3. Provision a Postgres database (Neon)
+
+The full-stack template uses Postgres via the \`@raredays/postgres\` port. For
+managed production Postgres with branching previews, [Neon](https://neon.tech)
+pairs well with Vercel.
+
+1. Sign up at <https://console.neon.tech>.
+2. Create a project (free tier is fine to start).
+3. Copy the **Pooled connection** string — this is your \`DATABASE_URL\`.
+4. (Optional) Enable [Vercel-Neon integration](https://neon.tech/docs/guides/vercel)
+   for automatic preview-environment branching: each PR gets its own Postgres
+   branch with isolated data.
+
+`
+    : "";
+
+  const migrationsSection = isFullStack
+    ? `
+## 6. Run migrations
+
+The repo ships a workflow at \`.github/workflows/deploy-migrations.yml\` that
+runs \`pnpm db:migrate\` on push to \`main\`, gated behind a manual approval.
+
+To enable it:
+
+1. In your GitHub repo: **Settings → Environments → New environment** → name it \`production\`.
+2. Add a **required reviewer** (yourself, or your team).
+3. Add \`DATABASE_URL\` as an environment secret.
+4. On the next push to \`main\`, the workflow will pause for your approval before applying schema changes.
+
+For the first deploy, you can run migrations locally:
+
+\`\`\`sh
+DATABASE_URL="<your-prod-url>" pnpm db:migrate
+\`\`\`
+
+`
+    : "";
+
+  const envBlock = isFullStack
+    ? "DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, and any module-specific keys"
+    : "any module-specific keys listed in `.env.example`";
+
+  return `# Deploying to Vercel
+
+This app is configured for [Vercel](https://vercel.com), Next.js's reference
+host. Free tier is generous; previews and production both deploy from git.
+
+## 1. One-time: install the Vercel CLI
+
+\`\`\`sh
+pnpm add -g vercel
+vercel login
+\`\`\`
+
+Or use the convenience script:
+
+\`\`\`sh
+./scripts/setup-vercel.sh
+\`\`\`
+
+## 2. Link this repo to a Vercel project
+
+From the project root:
+
+\`\`\`sh
+vercel link
+\`\`\`
+
+Pick "Create a new project" when prompted. This writes \`.vercel/project.json\`
+locally (gitignored — each developer links to the same upstream project).
+${dbSections}
+## ${isFullStack ? "4" : "3"}. Set environment variables
+
+Open your project in the [Vercel dashboard → Settings → Environment Variables](https://vercel.com/dashboard).
+Add: ${envBlock}.
+
+See \`.env.example\` in this repo for the canonical list. Set each var for
+**Production**, **Preview**, and **Development** as appropriate.
+
+## ${isFullStack ? "5" : "4"}. First deploy
+
+\`\`\`sh
+vercel --prod
+\`\`\`
+
+This builds and deploys directly from your machine. Subsequent deploys can be
+fully automatic: connect the repo via the Vercel dashboard's **Git** tab, and
+every push to \`main\` ships to production, every PR gets a preview URL.
+${migrationsSection}
+## ${isFullStack ? "7" : "5"}. Custom domain
+
+In the Vercel dashboard → **Settings → Domains**, add your domain and follow
+the DNS instructions. Vercel handles SSL certificates automatically.
+
+## Notes & gotchas
+
+- **Function memory**: \`vercel.json\` defaults API routes to 1024 MB. Bump in \`functions["app/api/**/*.ts"].memory\` if you see OOMs.
+- **Regions**: defaults to \`iad1\` (US East). Co-locate with your database for lowest latency — change in \`vercel.json\` if your DB is elsewhere.
+- **Build size limits**: Vercel's serverless functions cap at 250 MB unzipped. If you hit this, audit dependencies or split into separate functions.
+- **Free tier limits**: 100 GB-hours/mo compute, 100 GB bandwidth. See <https://vercel.com/pricing>.
+
+## Alternative hosts
+
+This app is plain Next.js — it'll also run on:
+
+- **Railway** / **Fly.io** — \`pnpm build && pnpm start\`, set the same env vars
+- **Self-hosted** — \`pnpm start\` behind a reverse proxy (nginx, Caddy)
+- **Docker** — a \`Dockerfile\` target will land as a future CRDA \`--deploy docker\` option
+`;
+}
+
+function buildMigrationsWorkflow() {
+  return `# Runs database migrations against the production database after a manual
+# approval. Requires a GitHub Environment named "production" with DATABASE_URL
+# as a secret and a required reviewer.
+#
+# See docs/DEPLOY.md for setup instructions.
+name: Deploy migrations
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  migrate:
+    name: Apply pending migrations
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Run migrations
+        env:
+          DATABASE_URL: \${{ secrets.DATABASE_URL }}
+        run: pnpm db:migrate
+`;
+}
+
+function buildSetupVercelScript() {
+  return `#!/usr/bin/env bash
+# Interactive helper: links this repo to a new Vercel project.
+# See docs/DEPLOY.md for the manual equivalent.
+
+set -euo pipefail
+
+if ! command -v vercel >/dev/null 2>&1; then
+  echo "Vercel CLI not found."
+  echo "Install with: pnpm add -g vercel"
+  echo "Or via npm:   npm i -g vercel"
+  exit 1
+fi
+
+if ! vercel whoami >/dev/null 2>&1; then
+  echo "Not logged into Vercel. Running 'vercel login'…"
+  vercel login
+fi
+
+echo
+echo "Linking this repo to a Vercel project."
+echo "Pick 'Create a new project' when prompted, then accept defaults."
+echo
+vercel link
+
+echo
+echo "Linked. Next:"
+echo "  1. Set env vars: Vercel dashboard → Settings → Environment Variables"
+echo "  2. First deploy: vercel --prod"
+echo
+echo "See docs/DEPLOY.md for the full runbook."
+`;
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      template: { type: "string", default: "full-stack" },
+      preset: { type: "string" },
+      modules: { type: "string" },
+      vendors: { type: "string" },
+      "remote-url": { type: "string" },
+      "no-git": { type: "boolean", default: false },
+      "no-install": { type: "boolean", default: false },
+      dev: { type: "boolean", default: false },
+      harness: { type: "string", default: "none" },
+      deploy: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    printHelp();
+    return;
+  }
+
+  const allFragments = await loadAllFragments();
+  const target = positionals[0];
+
+  let opts;
+  if (target) {
+    // Non-interactive: positional given, use flags + defaults.
+    const preset = values.preset ? PRESETS[values.preset] : null;
+    if (values.preset && !preset) {
+      fail(
+        `Unknown preset "${values.preset}". Available presets: ${Object.keys(PRESETS).join(", ")}`,
+      );
+    }
+    const requestedModules = preset ? preset.modules : parseCsv(values.modules);
+    const availableModules = availableModuleKeys();
+    const known = [];
+    for (const m of requestedModules) {
+      if (availableModules.includes(m)) {
+        known.push(m);
+      } else {
+        console.warn(
+          `warning: --modules "${m}" has no scaffold-fragment under scaffold-fragments/${m}/, skipping. Available: ${availableModules.join(", ")}`,
+        );
+      }
+    }
+    opts = {
+      projectName: target,
+      template: preset ? preset.template : values.template,
+      displayName: undefined,
+      canonicalDomain: undefined,
+      brandPrimary: preset?.brandPrimary ?? undefined,
+      selectedModules: known,
+      selectedVendors: preset ? preset.vendors : parseCsv(values.vendors),
+      remoteUrl: values["remote-url"],
+      gitInit: !values["no-git"],
+      runInstall: !values["no-install"],
+      dev: values.dev,
+      harness: values.harness,
+      deploy: values.deploy && values.deploy !== "none" ? values.deploy : null,
+    };
+    if (values.deploy && values.deploy !== "none" && values.deploy !== "vercel") {
+      fail(`Unknown --deploy "${values.deploy}". Supported: vercel, none.`);
+    }
+    console.log(`→ Creating ${opts.projectName} at ${resolve(process.cwd(), opts.projectName)}`);
+  } else {
+    // Interactive.
+    opts = await runInteractive(allFragments);
+    opts.dev = values.dev;
+    opts.harness = values.harness;
+  }
+
+  const { targetDir, envVars } = await scaffold(opts);
+
+  const hasMocks = opts.template !== "static";
+  const nextSteps = [
+    `cd ${opts.projectName}`,
+    opts.runInstall ? "" : "pnpm install",
+    envVars.length > 0 ? "cp .env.example .env.local  # fill in real values" : "",
+    "pnpm dev",
+    hasMocks
+      ? "pnpm dev:mocks  # alternative: dev with MSW intercepting fetch (server + browser)"
+      : "",
+  ].filter(Boolean);
+
+  if (target) {
+    console.log(`\n✓ Created ${targetDir}\n`);
+    console.log(`Next steps:\n  ${nextSteps.join("\n  ")}\n`);
+  } else {
+    p.outro(`Created ${targetDir}\n\nNext steps:\n  ${nextSteps.join("\n  ")}`);
+  }
+}
+
+main().catch((err) => {
+  fail(err instanceof Error ? err.message : String(err));
+});