create-lacspace-app 2.6.0 → 2.8.0

package/dist/lib.cjs

@@ -33,14 +33,15 @@ var TEMPLATES = [
   { key: "marketplace", label: "Marketplace / commerce", description: "A real storefront wired to the Lacspace commerce packages \u2014 cart, checkout, tax, shipping, orders, invoices and Nepal payments.", accent: ["#0d9488", "#6366f1"], siteName: "LSBazaar", siteDescription: "A modern storefront \u2014 cart to checkout, wired end to end." }
 ];
 function resolveContext(options = {}) {
-  const base = TEMPLATES.find((t) => t.key === options.template) ?? TEMPLATES[0];
+  const recipe = options.recipe ? RECIPES.find((r) => r.key === String(options.recipe).toLowerCase()) : void 0;
+  const base = TEMPLATES.find((t) => t.key === (options.template ?? recipe?.template)) ?? TEMPLATES[0];
   const accent = resolveAccent(options.theme);
   const template = accent ? { ...base, accent } : base;
   const raw = options.name ?? "my-app";
   const seg = raw.split(/[\\/]/).filter(Boolean).pop() ?? "my-app";
   const name = seg.toLowerCase().replace(/[^a-z0-9-_]/g, "-").replace(/^-+|-+$/g, "") || "my-app";
-  const features = normalizeFeatures(options.features);
-  let mode = options.mode === "dynamic" ? "dynamic" : "static";
+  const features = normalizeFeatures([...recipe?.features ?? [], ...options.features ?? []]);
+  let mode = options.mode === "dynamic" ? "dynamic" : options.mode === "static" ? "static" : recipe?.mode ?? "static";
   if (mode === "static" && features.some((f) => f.requiresBackend)) mode = "dynamic";
   return { name, template, features, mode };
 }
@@ -2213,6 +2214,71 @@ var FEATURES = [
       "It's cookieless and stores no personal data \u2014 privacy-first by default."
     ],
     learn: "https://developer.lacspace.com/packages/analytics-lite"
+  },
+  {
+    key: "payments",
+    label: "Payments (Nepal)",
+    description: "A checkout wired to eSewa & Khalti \u2014 orders, the signed eSewa flow (works in TEST with NO credentials), Khalti when keyed, integer-safe money. Full-stack.",
+    requiresBackend: true,
+    deps: {},
+    files: () => ({
+      "app/checkout/page.tsx": checkoutPage(),
+      "app/checkout/success/page.tsx": checkoutSuccessPage(),
+      "app/checkout/failed/page.tsx": checkoutFailedPage()
+    }),
+    backend: () => ({
+      deps: { "@lacspace/esewa": "^1.2.0", "@lacspace/khalti": "^1.1.0", "@lacspace/money": "^1.1.0" },
+      files: {
+        "src/models/order.ts": ordersModel(),
+        "src/routes/checkout.ts": checkoutRoutes()
+      },
+      routes: [{ path: "/checkout", handler: "checkoutRoutes", auth: true, importLine: 'import checkoutRoutes from "./checkout.js";' }],
+      env: {
+        ESEWA_MERCHANT_CODE: "eSewa merchant/product code (blank = eSewa TEST sandbox).",
+        ESEWA_SECRET: "eSewa secret key (blank = TEST sandbox \u2014 payments work end-to-end in test).",
+        KHALTI_SECRET: "Khalti secret key (required to enable Khalti; blank shows a 'configure Khalti' message)."
+      }
+    }),
+    nextSteps: [
+      "Sign in, then open http://localhost:3000/checkout and pay with eSewa \u2014 it works in TEST mode with no credentials.",
+      "Enable Khalti by setting KHALTI_SECRET in .env (get a test key from https://khalti.com).",
+      "Go live: set ESEWA_MERCHANT_CODE + ESEWA_SECRET (and a live KHALTI_SECRET)."
+    ],
+    learn: "https://developer.lacspace.com/packages/esewa"
+  },
+  {
+    key: "email",
+    label: "Email",
+    description: "Transactional email \u2014 a ready mail service (@lacspace/mailer) with beautiful templates + address validation. Logs to the console until you add SMTP. Full-stack.",
+    requiresBackend: true,
+    deps: {},
+    files: () => ({ "app/email-test/page.tsx": emailTestPage() }),
+    backend: (ctx) => ({
+      deps: {
+        "@lacspace/mailer": "^1.2.0",
+        "@lacspace/email-templates": "^1.1.0",
+        "@lacspace/email-validate": "^1.1.0"
+      },
+      files: {
+        "src/mail/mailer.ts": mailerLib(ctx),
+        "src/routes/email.ts": emailRoutes()
+      },
+      routes: [{ path: "/email", handler: "emailRoutes", auth: true, importLine: 'import emailRoutes from "./email.js";' }],
+      env: {
+        SMTP_HOST: "SMTP host (blank in dev \u2014 emails are logged to the API console instead of sent).",
+        SMTP_PORT: "SMTP port (default 587).",
+        SMTP_SECURE: "true for implicit TLS on port 465; otherwise false.",
+        SMTP_USER: "SMTP username.",
+        SMTP_PASS: "SMTP password.",
+        SMTP_FROM: 'Default From address, e.g. "Acme <no-reply@acme.com>".'
+      }
+    }),
+    nextSteps: [
+      "Sign in, then open http://localhost:3000/email-test and send yourself a sample email.",
+      "With no SMTP_* set, the email is printed to the API console (dev). Set SMTP_* in .env to send for real.",
+      "Reuse the helpers in backend/src/mail/mailer.ts: sendWelcome / sendVerify / sendReset."
+    ],
+    learn: "https://developer.lacspace.com/packages/mailer"
   }
 ];
 var aiChatRoute = (_ctx) => `import { resolveConfig } from "@lacspace/providers";
@@ -5191,6 +5257,13 @@ var faqSection = (ctx) => {
         </div>
       </section>`;
 };
+var RECIPES = [
+  { key: "ai-saas", label: "AI SaaS", description: "SaaS landing + accounts + payments + a streaming AI chat + analytics.", template: "saas", mode: "dynamic", features: ["auth-pages", "payments", "ai-chat", "analytics"] },
+  { key: "store", label: "Online store", description: "E-commerce storefront + eSewa/Khalti checkout + transactional email + analytics.", template: "ecommerce", mode: "dynamic", features: ["payments", "email", "analytics"] },
+  { key: "blog", label: "Blog", description: "A blog with a Markdown content section, RSS/llms.txt and instant search.", template: "blog", features: ["content", "search"] },
+  { key: "internal-tool", label: "Internal tool", description: "An admin dashboard with accounts (2FA), analytics and email \u2014 full-stack.", template: "dashboard", mode: "dynamic", features: ["auth-pages", "analytics", "email"] },
+  { key: "docs-ai", label: "AI docs", description: "A documentation site with chat-with-your-docs RAG and instant search.", template: "docs", features: ["rag", "search"] }
+];
 var contentLib = () => `import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter, markdownToHtml, excerpt } from "@lacspace/markdown";
@@ -5831,6 +5904,365 @@ export default function AnalyticsPage() {
   );
 }
 `;
+var ordersModel = () => `import mongoose from "mongoose";
+import { uuidv7 } from "@lacspace/id";
+
+export interface OrderDoc {
+  _id: string;
+  userId: string;
+  label: string;
+  amountPaisa: number;
+  currency: string;
+  status: "pending" | "paid" | "failed";
+  gateway: string;
+  ref: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const schema = new mongoose.Schema<OrderDoc>(
+  {
+    _id: { type: String, default: () => uuidv7() },
+    userId: { type: String, required: true, index: true },
+    label: { type: String, required: true },
+    amountPaisa: { type: Number, required: true },
+    currency: { type: String, default: "NPR" },
+    status: { type: String, enum: ["pending", "paid", "failed"], default: "pending" },
+    gateway: { type: String, default: "" },
+    ref: { type: String, default: "" },
+  },
+  { timestamps: true },
+);
+
+export const Order =
+  (mongoose.models.Order as mongoose.Model<OrderDoc>) ?? mongoose.model<OrderDoc>("Order", schema);
+`;
+var checkoutRoutes = () => `import express from "express";
+import {
+  buildForm, verifyResponse, paisaToRupees, generateTransactionUuid,
+  ESEWA_TEST_SECRET, ESEWA_TEST_PRODUCT_CODE,
+} from "@lacspace/esewa";
+import { initiate, lookup } from "@lacspace/khalti";
+import { Money, formatBasic } from "@lacspace/money";
+import { v } from "@lacspace/validate";
+import { asyncHandler, HttpError } from "../http.js";
+import { env } from "../env.js";
+import { Order } from "../models/order.js";
+
+// how this works: create an order, then start a gateway payment. eSewa works in TEST
+// mode with the package's baked-in sandbox keys (no credentials!). Khalti needs a real
+// secret. After the customer returns, the frontend calls /verify \u2014 never trust the
+// redirect alone, always confirm server-side.
+const router = express.Router();
+const web = () => env.CORS_ORIGIN.split(",")[0]!.trim();
+
+const CreateInput = v.object({ label: v.string().min(1).max(120), amount: v.number().positive() });
+
+// POST /checkout \u2014 create a pending order (amount in RUPEES from the UI \u2192 stored as paisa).
+router.post("/", asyncHandler(async (req, res) => {
+  const { label, amount } = CreateInput.parse(req.body);
+  const amountPaisa = Money.of(amount, "NPR").toMinor();
+  const order = await Order.create({ userId: req.user!.sub, label, amountPaisa });
+  res.status(201).json({ id: String(order._id), label, amountPaisa, display: formatBasic(Money.fromMinor(amountPaisa, "NPR")) });
+}));
+
+// POST /checkout/:id/esewa \u2014 build the signed eSewa form to auto-POST from the browser.
+router.post("/:id/esewa", asyncHandler(async (req, res) => {
+  const order = await Order.findOne({ _id: req.params.id, userId: req.user!.sub });
+  if (!order) throw new HttpError(404, "Order not found");
+  const secret = process.env.ESEWA_SECRET ?? ESEWA_TEST_SECRET;
+  const productCode = process.env.ESEWA_MERCHANT_CODE ?? ESEWA_TEST_PRODUCT_CODE;
+  const esewaEnv: "test" | "prod" = process.env.ESEWA_SECRET ? "prod" : "test";
+  const uuid = generateTransactionUuid();
+  order.ref = uuid;
+  order.gateway = "esewa";
+  await order.save();
+  const form = await buildForm(
+    {
+      amount: paisaToRupees(order.amountPaisa),
+      transactionUuid: uuid,
+      productCode,
+      successUrl: web() + "/checkout/success?orderId=" + String(order._id),
+      failureUrl: web() + "/checkout/failed?orderId=" + String(order._id),
+    },
+    { secret, env: esewaEnv },
+  );
+  res.json(form);
+}));
+
+// POST /checkout/:id/esewa/verify \u2014 verify the base64 \`data\` eSewa returned; mark paid.
+router.post("/:id/esewa/verify", asyncHandler(async (req, res) => {
+  const { data } = v.object({ data: v.string().min(1) }).parse(req.body);
+  const order = await Order.findOne({ _id: req.params.id, userId: req.user!.sub });
+  if (!order) throw new HttpError(404, "Order not found");
+  const secret = process.env.ESEWA_SECRET ?? ESEWA_TEST_SECRET;
+  const result = await verifyResponse(data, secret);
+  const status = String((result.data as { status?: string }).status ?? "");
+  if (!result.valid || status !== "COMPLETE") throw new HttpError(400, "Payment could not be verified");
+  order.status = "paid";
+  await order.save();
+  res.json({ id: String(order._id), status: "paid" });
+}));
+
+// POST /checkout/:id/khalti \u2014 start a Khalti payment (needs KHALTI_SECRET, else 501).
+router.post("/:id/khalti", asyncHandler(async (req, res) => {
+  const secretKey = process.env.KHALTI_SECRET;
+  if (!secretKey) throw new HttpError(501, "Set KHALTI_SECRET in .env to enable Khalti (see .env.example).");
+  const order = await Order.findOne({ _id: req.params.id, userId: req.user!.sub });
+  if (!order) throw new HttpError(404, "Order not found");
+  order.gateway = "khalti";
+  await order.save();
+  const r = await initiate(
+    {
+      return_url: web() + "/checkout/success?orderId=" + String(order._id),
+      website_url: web(),
+      amount: order.amountPaisa,
+      purchase_order_id: String(order._id),
+      purchase_order_name: order.label,
+    },
+    { secretKey, env: "test" },
+  );
+  order.ref = r.pidx;
+  await order.save();
+  res.json({ paymentUrl: r.payment_url, pidx: r.pidx });
+}));
+
+// POST /checkout/:id/khalti/verify \u2014 authoritative lookup by pidx; mark paid.
+router.post("/:id/khalti/verify", asyncHandler(async (req, res) => {
+  const secretKey = process.env.KHALTI_SECRET;
+  if (!secretKey) throw new HttpError(501, "Khalti is not configured");
+  const { pidx } = v.object({ pidx: v.string().min(1) }).parse(req.body);
+  const order = await Order.findOne({ _id: req.params.id, userId: req.user!.sub });
+  if (!order) throw new HttpError(404, "Order not found");
+  const r = await lookup(pidx, { secretKey, env: "test" });
+  if (r.status !== "Completed") throw new HttpError(400, "Payment status: " + String(r.status));
+  order.status = "paid";
+  await order.save();
+  res.json({ id: String(order._id), status: "paid" });
+}));
+
+export default router;
+`;
+var checkoutPage = () => `"use client";
+import { useState } from "react";
+import { getToken } from "@/lib/api";
+
+const API = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+const msgOf = (e: unknown) => (e instanceof Error ? e.message : "Something went wrong");
+
+async function call<T>(path: string, body: unknown): Promise<T> {
+  const token = getToken();
+  const res = await fetch(API + path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...(token ? { Authorization: "Bearer " + token } : {}) },
+    body: JSON.stringify(body),
+  });
+  const data: unknown = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error((data as { error?: string }).error ?? "Request failed");
+  return data as T;
+}
+
+export default function CheckoutPage() {
+  const [label, setLabel] = useState("Pro plan");
+  const [amount, setAmount] = useState(1000);
+  const [orderId, setOrderId] = useState<string | null>(null);
+  const [msg, setMsg] = useState<string | null>(null);
+
+  async function createOrder(e: React.FormEvent) {
+    e.preventDefault();
+    try {
+      const o = await call<{ id: string; display: string }>("/checkout", { label, amount });
+      setOrderId(o.id);
+      setMsg("Order " + o.display + " created \u2014 choose how to pay.");
+    } catch (err) { setMsg(msgOf(err)); }
+  }
+  async function payEsewa() {
+    if (!orderId) return;
+    try {
+      const form = await call<{ action: string; fields: Record<string, string> }>("/checkout/" + orderId + "/esewa", {});
+      const f = document.createElement("form");
+      f.method = "POST";
+      f.action = form.action;
+      for (const [k, val] of Object.entries(form.fields)) {
+        const i = document.createElement("input");
+        i.type = "hidden"; i.name = k; i.value = val;
+        f.appendChild(i);
+      }
+      document.body.appendChild(f);
+      f.submit();
+    } catch (err) { setMsg(msgOf(err)); }
+  }
+  async function payKhalti() {
+    if (!orderId) return;
+    try {
+      const r = await call<{ paymentUrl: string }>("/checkout/" + orderId + "/khalti", {});
+      window.location.href = r.paymentUrl;
+    } catch (err) { setMsg(msgOf(err)); }
+  }
+
+  return (
+    <main className="mx-auto max-w-md px-6 py-16">
+      <h1 className="text-2xl font-bold">Checkout</h1>
+      <p className="mt-1 text-sm text-muted">Sign in first, then create an order and pay.</p>
+      <form onSubmit={createOrder} className="mt-6 space-y-3 rounded-2xl border border-hairline p-5">
+        <input value={label} onChange={(e) => setLabel(e.target.value)} placeholder="What are you buying?" className="w-full rounded-xl border border-hairline bg-surface px-4 py-2 outline-none" />
+        <input type="number" min={10} value={amount} onChange={(e) => setAmount(Number(e.target.value))} placeholder="Amount (NPR)" className="w-full rounded-xl border border-hairline bg-surface px-4 py-2 outline-none" />
+        <button className="w-full rounded-full gradient-bg px-4 py-2 font-semibold on-accent">Create order</button>
+      </form>
+      {msg && <p className="mt-4 text-sm text-muted">{msg}</p>}
+      {orderId && (
+        <div className="mt-6 space-y-3">
+          <button onClick={payEsewa} className="w-full rounded-full border border-hairline px-4 py-3 font-semibold transition hover:bg-surface">Pay with eSewa <span className="text-muted">(works in test)</span></button>
+          <button onClick={payKhalti} className="w-full rounded-full border border-hairline px-4 py-3 font-semibold transition hover:bg-surface">Pay with Khalti</button>
+        </div>
+      )}
+      <p className="mt-6 text-xs text-muted">eSewa works out-of-the-box in test mode. Khalti needs KHALTI_SECRET in .env.</p>
+    </main>
+  );
+}
+`;
+var checkoutSuccessPage = () => `"use client";
+import { useEffect, useState } from "react";
+import Link from "next/link";
+import { getToken } from "@/lib/api";
+
+const API = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+
+export default function CheckoutSuccessPage() {
+  const [status, setStatus] = useState<"verifying" | "paid" | "failed">("verifying");
+  const [detail, setDetail] = useState("");
+
+  useEffect(() => {
+    const q = new URLSearchParams(window.location.search);
+    const orderId = q.get("orderId");
+    const data = q.get("data");   // eSewa returns a base64 \`data\` param
+    const pidx = q.get("pidx");   // Khalti returns \`pidx\`
+    const token = getToken();
+    if (!orderId || !token) { setStatus("failed"); setDetail("Missing order or session \u2014 please sign in."); return; }
+    (async () => {
+      let path = ""; let body: Record<string, string> = {};
+      if (data) { path = "/checkout/" + orderId + "/esewa/verify"; body = { data }; }
+      else if (pidx) { path = "/checkout/" + orderId + "/khalti/verify"; body = { pidx }; }
+      else { setStatus("failed"); setDetail("No payment token was returned."); return; }
+      try {
+        const res = await fetch(API + path, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
+          body: JSON.stringify(body),
+        });
+        if (!res.ok) { const e: unknown = await res.json().catch(() => ({})); throw new Error((e as { error?: string }).error ?? "Verification failed"); }
+        setStatus("paid");
+      } catch (e) { setStatus("failed"); setDetail(e instanceof Error ? e.message : "Verification failed"); }
+    })();
+  }, []);
+
+  return (
+    <main className="mx-auto max-w-md px-6 py-24 text-center">
+      {status === "verifying" && <p className="text-muted">Verifying your payment\u2026</p>}
+      {status === "paid" && (<><h1 className="text-3xl font-bold">Payment successful \u{1F389}</h1><p className="mt-2 text-muted">Thank you \u2014 your order is paid.</p></>)}
+      {status === "failed" && (<><h1 className="text-2xl font-bold">Payment not completed</h1><p className="mt-2 text-muted">{detail}</p></>)}
+      <Link href="/checkout" className="mt-6 inline-block rounded-full border border-hairline px-4 py-2 text-sm">Back to checkout</Link>
+    </main>
+  );
+}
+`;
+var checkoutFailedPage = () => `import Link from "next/link";
+
+export default function CheckoutFailedPage() {
+  return (
+    <main className="mx-auto max-w-md px-6 py-24 text-center">
+      <h1 className="text-2xl font-bold">Payment cancelled</h1>
+      <p className="mt-2 text-muted">Your payment was not completed.</p>
+      <Link href="/checkout" className="mt-6 inline-block rounded-full border border-hairline px-4 py-2 text-sm">Try again</Link>
+    </main>
+  );
+}
+`;
+var mailerLib = (ctx) => `import { createTransport, createJsonTransport, mailerFromEnv, type Transport } from "@lacspace/mailer";
+import { welcomeEmail, verifyEmail, passwordResetEmail, toPlainText } from "@lacspace/email-templates";
+
+// how this works: if SMTP_* env vars are set, it sends real email over SMTP; otherwise
+// it logs the full message to the console (so the app runs with NO credentials). Adding
+// SMTP_* later switches to real delivery with no code change.
+export const transport: Transport = process.env.SMTP_HOST
+  ? createTransport(mailerFromEnv())
+  : createJsonTransport((json) => console.log("\\n[email:dev] set SMTP_* in .env to deliver for real:\\n" + json + "\\n"));
+
+const FROM = process.env.SMTP_FROM ?? ${JSON.stringify(ctx.name + " <no-reply@example.com>")};
+const brand = { brandName: ${JSON.stringify(ctx.name)} };
+
+export function sendWelcome(to: string, name?: string) {
+  const html = welcomeEmail({ name, message: "Thanks for joining " + brand.brandName + "!", ...brand });
+  return transport.send({ from: FROM, to, subject: "Welcome to " + brand.brandName, html, text: toPlainText(html) });
+}
+export function sendVerify(to: string, verifyUrl: string) {
+  const html = verifyEmail({ verifyUrl, expiresMinutes: 30, ...brand });
+  return transport.send({ from: FROM, to, subject: "Verify your email", html, text: toPlainText(html) });
+}
+export function sendReset(to: string, resetUrl: string) {
+  const html = passwordResetEmail({ resetUrl, expiresMinutes: 30, ...brand });
+  return transport.send({ from: FROM, to, subject: "Reset your password", html, text: toPlainText(html) });
+}
+`;
+var emailRoutes = () => `import express from "express";
+import { validateEmail } from "@lacspace/email-validate";
+import { asyncHandler, HttpError } from "../http.js";
+import { sendWelcome } from "../mail/mailer.js";
+
+const router = express.Router();
+
+// POST /email/test \u2014 send a sample welcome email (validates the address first).
+router.post("/test", asyncHandler(async (req, res) => {
+  const to = String((req.body ?? {}).to ?? "").trim();
+  const check = validateEmail(to);
+  if (!check.valid) throw new HttpError(400, check.reason ?? "Invalid email address");
+  const result = await sendWelcome(check.normalized ?? to);
+  res.json({ ok: true, messageId: result.messageId });
+}));
+
+export default router;
+`;
+var emailTestPage = () => `"use client";
+import { useState } from "react";
+import { getToken } from "@/lib/api";
+
+const API = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+
+export default function EmailTestPage() {
+  const [to, setTo] = useState("");
+  const [msg, setMsg] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function send(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true); setMsg(null);
+    try {
+      const token = getToken();
+      const res = await fetch(API + "/email/test", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(token ? { Authorization: "Bearer " + token } : {}) },
+        body: JSON.stringify({ to }),
+      });
+      const data: unknown = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error((data as { error?: string }).error ?? "Failed to send");
+      setMsg("Sent! If no SMTP is configured, check the API console for the email.");
+    } catch (err) { setMsg(err instanceof Error ? err.message : "Failed"); }
+    finally { setBusy(false); }
+  }
+
+  return (
+    <main className="mx-auto max-w-md px-6 py-16">
+      <h1 className="text-2xl font-bold">Send a test email</h1>
+      <p className="mt-1 text-muted">With no SMTP configured, the email is logged to the API console.</p>
+      <form onSubmit={send} className="mt-6 space-y-3">
+        <input type="email" required value={to} onChange={(e) => setTo(e.target.value)} placeholder="you@example.com" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        <button disabled={busy} className="w-full rounded-full gradient-bg px-4 py-3 font-semibold on-accent disabled:opacity-60">{busy ? "Sending\u2026" : "Send test email"}</button>
+      </form>
+      {msg && <p className="mt-4 text-sm text-muted">{msg}</p>}
+    </main>
+  );
+}
+`;
 var scope = (ctx) => `@${ctx.name}`;
 var typesPkgJson = (ctx) => JSON.stringify({
   name: `${scope(ctx)}/types`,
@@ -6808,7 +7240,9 @@ function parseArgs(list) {
     } else if (arg.startsWith("--mode=")) {
       const m = arg.slice(7).toLowerCase();
       a.mode = m === "dynamic" ? "dynamic" : "static";
-    } else if (arg === "-h" || arg === "--help") a.help = true;
+    } else if (arg === "--recipe") a.recipe = next();
+    else if (arg.startsWith("--recipe=")) a.recipe = arg.slice(9);
+    else if (arg === "-h" || arg === "--help") a.help = true;
     else if (arg.startsWith("--template=")) a.template = arg.slice(11);
     else if (arg.startsWith("--theme=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--accent=")) a.theme = arg.slice(9);
@@ -6912,6 +7346,7 @@ ${c("bold", "Options")}
                          MongoDB/Redis backend (JWT auth + CRUD) + shared types
                          ${c("dim", "(alias --dynamic; default is --static, a single Next.js app)")}
   --with <a,b>           Feature add-ons, comma-separated (alias --features)
+  --recipe <key>         Start from a curated stack (${RECIPES.map((r) => r.key).join(" | ")})
   --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (e.g. --theme lacspace)
   --pm <npm|pnpm|yarn|bun>  Package manager (default npm)
   --no-install           Skip installing dependencies
@@ -6920,9 +7355,13 @@ ${c("bold", "Options")}
   -h, --help             Show this help
 
 ${c("bold", "Feature add-ons")} ${c("dim", "(--with) \u2014 free & keyless, local by default")}
-${FEATURES.map((f) => `  ${f.key.padEnd(10)} ${f.description}`).join("\n")}
+${FEATURES.map((f) => `  ${f.key.padEnd(11)} ${f.description}`).join("\n")}
   ${c("dim", "e.g. npx create-lacspace-app my-app --template saas --with ai-chat,rag")}
 
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+${RECIPES.map((r) => `  ${r.key.padEnd(14)} ${r.description}`).join("\n")}
+  ${c("dim", "e.g. npx create-lacspace-app my-app --recipe ai-saas")}
+
 ${c("bold", "Themes")} ${c("dim", "(--theme)")}
   ${Object.keys(THEMES).join(" \xB7 ")}
   ${c("dim", 'or a custom colour: --theme "#ff6a00"  \xB7  --theme "#0bb9d9,#7c3aed"')}
@@ -7299,11 +7738,16 @@ async function main() {
   process$1.stdout.write(`
 ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a gorgeous Next.js starter, batteries wired")}
 
+`);
+  const recipe = args.recipe ? RECIPES.find((r) => r.key === args.recipe.toLowerCase()) : void 0;
+  if (args.recipe && !recipe) process$1.stdout.write(c("yellow", `  ! Unknown recipe "${args.recipe}" \u2014 ignoring. Try: ${RECIPES.map((r) => r.key).join(", ")}
+`));
+  if (recipe) process$1.stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", recipe.key)} ${c("dim", "\u2014 " + recipe.description)}
 `);
   let name = args.name;
-  let templateKey = args.template;
-  let mode = args.mode ?? "static";
-  const featureKeys = [...args.features];
+  let templateKey = args.template ?? recipe?.template;
+  let mode = args.mode ?? recipe?.mode ?? "static";
+  const featureKeys = [...recipe?.features ?? [], ...args.features];
   if (!args.yes && process$1.stdin.isTTY) {
     const rl = promises.createInterface({ input: process$1.stdin, output: process$1.stdout });
     try {
@@ -7319,7 +7763,7 @@ ${c("green", "?")} Template ${c("dim", "(1)")}: `)).trim() || "1";
         const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : TEMPLATES.findIndex((t) => t.key === ans);
         templateKey = TEMPLATES[idx]?.key ?? "personal";
       }
-      if (args.mode === void 0) {
+      if (args.mode === void 0 && !recipe) {
         process$1.stdout.write(`
   What kind of app?
 `);
@@ -7372,6 +7816,11 @@ ${c("green", "?")} Add features? ${c("dim", "(comma-separated numbers, or Enter
     return;
   }
   const features = normalizeFeatures(featureKeys);
+  if (mode === "static" && features.some((f) => f.requiresBackend)) {
+    mode = "dynamic";
+    process$1.stdout.write(`  ${c("dim", "\u2191 a selected add-on needs a backend \u2014 building full-stack")}
+`);
+  }
   const files = buildFiles({ name: projectName, template, features, mode });
   for (const [rel, content] of Object.entries(files)) {
     const full = path.join(dir, rel);
@@ -7483,6 +7932,13 @@ function getFeature(key) {
   const f = FEATURES.find((x) => x.key === key);
   return f ? { ...f } : void 0;
 }
+function listRecipes() {
+  return RECIPES.map((r) => ({ ...r, features: [...r.features] }));
+}
+function getRecipe(key) {
+  const r = RECIPES.find((x) => x.key === key);
+  return r ? { ...r, features: [...r.features] } : void 0;
+}
 function generateProject(options = {}) {
   return buildFiles(resolveContext(options));
 }
@@ -7500,9 +7956,11 @@ async function scaffold(options = {}) {
 
 exports.generateProject = generateProject;
 exports.getFeature = getFeature;
+exports.getRecipe = getRecipe;
 exports.getSection = getSection;
 exports.getTemplate = getTemplate;
 exports.listFeatures = listFeatures;
+exports.listRecipes = listRecipes;
 exports.listSections = listSections;
 exports.listTemplates = listTemplates;
 exports.scaffold = scaffold;

package/dist/lib.d.cts

@@ -104,6 +104,28 @@ interface GenerateOptions {
      * changes.
      */
     mode?: "static" | "dynamic";
+    /**
+     * A one-shot **recipe** (see {@link RECIPES}) — a curated bundle of template +
+     * mode + feature add-ons for a whole kind of product, e.g. `"ai-saas"` or
+     * `"store"`. Explicit `template`/`features`/`mode` still win and are merged on
+     * top. Omit for no recipe.
+     */
+    recipe?: string;
+}
+/**
+ * A one-command **recipe**: a curated template + mode + add-on stack for a whole
+ * kind of product. `npx create-lacspace-app my-app --recipe ai-saas`.
+ */
+interface RecipeDef {
+    key: string;
+    label: string;
+    description: string;
+    /** The template this recipe starts from. */
+    template: string;
+    /** Force full-stack when the stack needs a backend (add-ons can also force it). */
+    mode?: "static" | "dynamic";
+    /** The add-ons this recipe layers on. */
+    features: string[];
 }
 
 /** A project file map: relative path → file contents. */
@@ -131,6 +153,13 @@ declare function getSection(name: string): string | undefined;
 declare function listFeatures(): FeatureDef[];
 /** Look up one feature add-on's definition by key, or `undefined`. */
 declare function getFeature(key: string): FeatureDef | undefined;
+/**
+ * The built-in one-shot recipes (see {@link RecipeDef}) — curated template + mode +
+ * add-on bundles you can pass as `options.recipe` or request with `--recipe <key>`.
+ */
+declare function listRecipes(): RecipeDef[];
+/** Look up one recipe's definition by key, or `undefined`. */
+declare function getRecipe(key: string): RecipeDef | undefined;
 /**
  * Generate a full project as an in-memory file map (relative path → contents).
  *
@@ -162,4 +191,4 @@ interface ScaffoldResult {
  */
 declare function scaffold(options?: ScaffoldOptions): Promise<ScaffoldResult>;
 
-export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getSection, getTemplate, listFeatures, listSections, listTemplates, scaffold, templateKeys, templates };
+export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type RecipeDef, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getRecipe, getSection, getTemplate, listFeatures, listRecipes, listSections, listTemplates, scaffold, templateKeys, templates };

package/dist/lib.d.ts

@@ -104,6 +104,28 @@ interface GenerateOptions {
      * changes.
      */
     mode?: "static" | "dynamic";
+    /**
+     * A one-shot **recipe** (see {@link RECIPES}) — a curated bundle of template +
+     * mode + feature add-ons for a whole kind of product, e.g. `"ai-saas"` or
+     * `"store"`. Explicit `template`/`features`/`mode` still win and are merged on
+     * top. Omit for no recipe.
+     */
+    recipe?: string;
+}
+/**
+ * A one-command **recipe**: a curated template + mode + add-on stack for a whole
+ * kind of product. `npx create-lacspace-app my-app --recipe ai-saas`.
+ */
+interface RecipeDef {
+    key: string;
+    label: string;
+    description: string;
+    /** The template this recipe starts from. */
+    template: string;
+    /** Force full-stack when the stack needs a backend (add-ons can also force it). */
+    mode?: "static" | "dynamic";
+    /** The add-ons this recipe layers on. */
+    features: string[];
 }
 
 /** A project file map: relative path → file contents. */
@@ -131,6 +153,13 @@ declare function getSection(name: string): string | undefined;
 declare function listFeatures(): FeatureDef[];
 /** Look up one feature add-on's definition by key, or `undefined`. */
 declare function getFeature(key: string): FeatureDef | undefined;
+/**
+ * The built-in one-shot recipes (see {@link RecipeDef}) — curated template + mode +
+ * add-on bundles you can pass as `options.recipe` or request with `--recipe <key>`.
+ */
+declare function listRecipes(): RecipeDef[];
+/** Look up one recipe's definition by key, or `undefined`. */
+declare function getRecipe(key: string): RecipeDef | undefined;
 /**
  * Generate a full project as an in-memory file map (relative path → contents).
  *
@@ -162,4 +191,4 @@ interface ScaffoldResult {
  */
 declare function scaffold(options?: ScaffoldOptions): Promise<ScaffoldResult>;
 
-export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getSection, getTemplate, listFeatures, listSections, listTemplates, scaffold, templateKeys, templates };
+export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type RecipeDef, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getRecipe, getSection, getTemplate, listFeatures, listRecipes, listSections, listTemplates, scaffold, templateKeys, templates };