npm - create-lacspace-app - Versions diffs - 2.8.0 → 2.10.0 - Mend

create-lacspace-app 2.8.0 → 2.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -20,6 +20,16 @@ npx create-lacspace-app my-app --template saas --fullstack
 You choose the *kind* of site you're building. It writes a **real Next.js 15 + React 19 + Tailwind v4 app** — not a hello-world, but a genuinely **polished, modern site**: a fluid `clamp()` type scale, tight display headings, a refined light **and** dark palette, glass chrome, soft layered shadows, a smooth logo marquee, animated counters, scroll reveals and a shimmering primary CTA — every page filled in, an SEO stack wired end-to-end, and a **26-component UI kit** you can drop in anywhere.
+> **New in v2.10 — three more add-ons (11 total).**
+> - **`uploads`** — authenticated file uploads stored in MongoDB, served via **signed, expiring URLs** (`@lacspace/signed-url`) — no S3 required.
+> - **`i18n`** — multi-language UI: a tiny dependency-free `t()` translator + a language switcher, with English + Nepali locales and an `i18n:check` lint script.
+> - **`quality`** — one-command quality gates from the Lacspace dev-tools (bundle-size budget, dependency audit, fake fixtures) **plus a ready GitHub Actions CI workflow** (dropped at the repo root, monorepo-aware).
+> **New in v2.9 — guided & discoverable.** Made for newcomers:
+> - **Guided start** — the interactive prompt now offers a **recipe** first ("what are you building?"), so you can ship a whole product without knowing the flags.
+> - **`list`** — `npx create-lacspace-app list` shows every template, add-on and recipe. **`explain <name>`** describes what any add-on or recipe gives you (packages, next steps, docs link).
+> - **`--dry-run`** prints the exact files a command would create without writing anything. `--brand "#hex"` is an alias for `--theme`.
 > **New in v2.8 — recipes.** Scaffold a whole *kind of product* in one command with `--recipe <key>` (a curated template + full-stack mode + add-on stack):
 > - **`ai-saas`** → SaaS + accounts + payments + AI chat + analytics
 > - **`store`** → e-commerce + eSewa/Khalti checkout + email + analytics

package/dist/index.js CHANGED Viewed

@@ -1997,6 +1997,11 @@ function applyFeatures(files, ctx) {
       files[rel] = content;
     }
   }
+  if (ctx.mode === "static") {
+    for (const feat of features) {
+      for (const [rel, content] of Object.entries(feat.rootFiles?.(ctx) ?? {})) files[rel] = content;
+    }
+  }
   const addDeps = {};
   const addScripts = {};
   for (const feat of features) {
@@ -2275,6 +2280,68 @@ var FEATURES = [
       "Reuse the helpers in backend/src/mail/mailer.ts: sendWelcome / sendVerify / sendReset."
     ],
     learn: "https://developer.lacspace.com/packages/mailer"
+  },
+  {
+    key: "i18n",
+    label: "i18n (multi-language)",
+    description: "Multi-language UI: a tiny runtime translator (t() + a language switcher) with English + Nepali locales, plus an i18n:check lint script.",
+    deps: {},
+    scripts: { "i18n:check": "npx lacspace-i18n@0.2.0 check locales" },
+    files: () => ({
+      "lib/i18n.ts": i18nLib(),
+      "components/language-provider.tsx": i18nProvider(),
+      "app/i18n-demo/page.tsx": i18nDemoPage(),
+      "locales/en.json": i18nEn(),
+      "locales/ne.json": i18nNe()
+    }),
+    nextSteps: [
+      "Wrap app/layout.tsx's <body> with <LanguageProvider> (from @/components/language-provider).",
+      'Use it in a client component: const { t } = useT();  then {t("hello", { name })}.',
+      "Add keys in locales/*.json, then lint them with `npm run i18n:check`."
+    ],
+    learn: "https://developer.lacspace.com/tools/i18n"
+  },
+  {
+    key: "quality",
+    label: "Quality & CI",
+    description: "One-command quality gates from the Lacspace dev-tools \u2014 bundle-size budget, dependency audit and fake fixtures \u2014 plus a ready GitHub Actions CI workflow.",
+    deps: {},
+    scripts: {
+      "size:check": "npx lacspace-size@0.2.0 .next/static --metric gzip --max 500kb",
+      "deps:audit": "npx lacspace-deps@0.2.0 . --fail-on duplicates",
+      "fixtures:gen": 'npx lacspace-fake@0.2.0 --fields "id:autoincrement,name:fullName,email:unique(email)" -n 50 --pretty -o fixtures/users.json'
+    },
+    files: () => ({}),
+    rootFiles: (ctx) => ({ ".github/workflows/ci.yml": qualityCiWorkflow(ctx) }),
+    nextSteps: [
+      "Run `npm run size:check` (bundle-size budget) and `npm run deps:audit` (dependency audit) \u2014 both fail loudly in CI.",
+      "Generate sample data: `npm run fixtures:gen` \u2192 fixtures/users.json.",
+      "The GitHub Actions workflow (.github/workflows/ci.yml) runs the checks on every push."
+    ],
+    learn: "https://developer.lacspace.com/tools/size"
+  },
+  {
+    key: "uploads",
+    label: "File uploads",
+    description: "Authenticated file uploads stored in MongoDB, served via signed, expiring URLs (@lacspace/signed-url). No S3 required. Full-stack.",
+    requiresBackend: true,
+    deps: {},
+    files: () => ({ "app/uploads/page.tsx": uploadsPage() }),
+    backend: () => ({
+      deps: { "@lacspace/signed-url": "^1.1.0" },
+      files: {
+        "src/models/upload.ts": uploadModel(),
+        "src/routes/uploads.ts": uploadsRoutes()
+      },
+      routes: [{ path: "/uploads", handler: "uploadRoutes", auth: false, importLine: 'import uploadRoutes from "./uploads.js";' }],
+      env: { UPLOAD_URL_SECRET: "Secret for signing file download URLs (blank = reuse JWT_SECRET)." }
+    }),
+    nextSteps: [
+      "Sign in, then open http://localhost:3000/uploads and upload an image or file.",
+      "Files are stored in MongoDB and served via signed, expiring links \u2014 no S3 required.",
+      "For large files or production, swap the Mongo storage for disk or object storage."
+    ],
+    learn: "https://developer.lacspace.com/packages/signed-url"
   }
 ];
 var aiChatRoute = (_ctx) => `import { resolveConfig } from "@lacspace/providers";
@@ -6259,6 +6326,291 @@ export default function EmailTestPage() {
   );
 }
 `;
+var i18nLib = () => `import en from "@/locales/en.json";
+import ne from "@/locales/ne.json";
+// how this works: a tiny, dependency-free translator. Locale files live in locales/,
+// keys are flat strings, and {vars} are interpolated. A missing key falls back to
+// English, then to the key itself. Lint the files with \`npm run i18n:check\`.
+export const locales = ["en", "ne"] as const;
+export type Locale = (typeof locales)[number];
+export const defaultLocale: Locale = "en";
+const dicts: Record<Locale, Record<string, string>> = {
+  en: en as Record<string, string>,
+  ne: ne as Record<string, string>,
+};
+export function translate(locale: Locale, key: string, vars?: Record<string, string | number>): string {
+  const table = dicts[locale] ?? dicts[defaultLocale];
+  let str = table[key] ?? dicts[defaultLocale][key] ?? key;
+  if (vars) for (const [k, v] of Object.entries(vars)) str = str.split("{" + k + "}").join(String(v));
+  return str;
+}
+`;
+var i18nProvider = () => `"use client";
+import { createContext, useContext, useEffect, useState } from "react";
+import { locales, defaultLocale, translate, type Locale } from "@/lib/i18n";
+// how this works: holds the current locale (persisted in localStorage) and exposes
+// t() via the useT() hook. Wrap your app in <LanguageProvider> once (in layout.tsx).
+interface LocaleCtxValue { locale: Locale; setLocale: (l: Locale) => void; }
+const LocaleCtx = createContext<LocaleCtxValue>({ locale: defaultLocale, setLocale: () => {} });
+export function LanguageProvider({ children }: { children: React.ReactNode }) {
+  const [locale, setLocaleState] = useState<Locale>(defaultLocale);
+  useEffect(() => {
+    try {
+      const saved = localStorage.getItem("locale");
+      if (saved && (locales as readonly string[]).includes(saved)) setLocaleState(saved as Locale);
+    } catch {}
+  }, []);
+  const setLocale = (l: Locale) => { setLocaleState(l); try { localStorage.setItem("locale", l); } catch {} };
+  return <LocaleCtx.Provider value={{ locale, setLocale }}>{children}</LocaleCtx.Provider>;
+}
+export function useT() {
+  const { locale, setLocale } = useContext(LocaleCtx);
+  return {
+    t: (key: string, vars?: Record<string, string | number>) => translate(locale, key, vars),
+    locale,
+    setLocale,
+  };
+}
+export function LanguageSwitcher() {
+  const { locale, setLocale } = useT();
+  return (
+    <div className="inline-flex gap-1 rounded-full border border-hairline p-1">
+      {locales.map((l) => (
+        <button
+          key={l}
+          onClick={() => setLocale(l)}
+          className={"rounded-full px-3 py-1 text-sm transition " + (l === locale ? "gradient-bg on-accent" : "text-muted hover:text-fg")}
+        >
+          {l.toUpperCase()}
+        </button>
+      ))}
+    </div>
+  );
+}
+`;
+var i18nDemoPage = () => `"use client";
+import { LanguageProvider, LanguageSwitcher, useT } from "@/components/language-provider";
+function Demo() {
+  const { t } = useT();
+  return (
+    <div className="space-y-4">
+      <h1 className="text-3xl font-bold">{t("hello", { name: "world" })}</h1>
+      <p className="text-muted">{t("tagline")}</p>
+      <LanguageSwitcher />
+    </div>
+  );
+}
+export default function I18nDemoPage() {
+  return (
+    <main className="mx-auto max-w-md px-6 py-16">
+      <LanguageProvider>
+        <Demo />
+      </LanguageProvider>
+    </main>
+  );
+}
+`;
+var i18nEn = () => JSON.stringify(
+  { hello: "Hello, {name}!", tagline: "This text switches language instantly \u2014 no reload.", "nav.home": "Home", "nav.about": "About" },
+  null,
+  2
+) + "\n";
+var i18nNe = () => JSON.stringify(
+  { hello: "\u0928\u092E\u0938\u094D\u0924\u0947, {name}!", tagline: "\u092F\u094B \u092A\u093E\u0920 \u0924\u0941\u0930\u0941\u0928\u094D\u0924\u0948 \u092D\u093E\u0937\u093E \u092B\u0947\u0930\u094D\u091B \u2014 \u0930\u093F\u0932\u094B\u0921 \u092C\u093F\u0928\u093E\u0964", "nav.home": "\u0917\u0943\u0939", "nav.about": "\u092C\u093E\u0930\u0947\u092E\u093E" },
+  null,
+  2
+) + "\n";
+var qualityCiWorkflow = (ctx) => {
+  const sizePath = ctx.mode === "dynamic" ? "frontend/.next/static" : ".next/static";
+  const depsGate = ctx.mode === "dynamic" ? "duplicates" : "missing,duplicates";
+  return `name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - name: Bundle-size budget
+        run: npx lacspace-size@0.2.0 ${sizePath} --metric gzip --max 500kb
+      - name: Dependency audit
+        run: npx lacspace-deps@0.2.0 . --fail-on ${depsGate}
+`;
+};
+var uploadModel = () => `import mongoose from "mongoose";
+import { uuidv7 } from "@lacspace/id";
+// how this works: files are stored base64-in-Mongo so it works with NO S3/disk setup.
+// For large files or production, swap this for disk or object storage.
+export interface UploadDoc {
+  _id: string;
+  userId: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  data: string; // base64
+  createdAt: Date;
+}
+const schema = new mongoose.Schema<UploadDoc>(
+  {
+    _id: { type: String, default: () => uuidv7() },
+    userId: { type: String, required: true, index: true },
+    filename: { type: String, required: true },
+    contentType: { type: String, default: "application/octet-stream" },
+    size: { type: Number, default: 0 },
+    data: { type: String, required: true },
+  },
+  { timestamps: { createdAt: true, updatedAt: false } },
+);
+export const Upload =
+  (mongoose.models.Upload as mongoose.Model<UploadDoc>) ?? mongoose.model<UploadDoc>("Upload", schema);
+`;
+var uploadsRoutes = () => `import express from "express";
+import { signUrl, verifyUrl } from "@lacspace/signed-url";
+import { v } from "@lacspace/validate";
+import { asyncHandler, HttpError } from "../http.js";
+import { requireAuth } from "../middleware/auth.js";
+import { env } from "../env.js";
+import { Upload } from "../models/upload.js";
+// how this works: uploads live in Mongo; each file is served from a PUBLIC route
+// protected by a signed, expiring URL (@lacspace/signed-url) \u2014 so <img src> works
+// without a bearer token, yet the link can't be forged or shared forever.
+const router = express.Router();
+const SECRET = process.env.UPLOAD_URL_SECRET ?? env.JWT_SECRET;
+const MAX_BYTES = 5 * 1024 * 1024; // 5 MB \u2014 base64-in-Mongo, keep it small
+const UploadInput = v.object({ filename: v.string().min(1).max(200), dataUrl: v.string().min(1) });
+// Sign a RELATIVE URL; the frontend prefixes it with the API base. Verified as-is.
+function signed(id: string): Promise<string> {
+  return signUrl("/uploads/" + id + "/raw", { secret: SECRET, expiresIn: 3600 });
+}
+// GET /uploads/:id/raw \u2014 PUBLIC, but the signed query params must verify.
+router.get("/:id/raw", asyncHandler(async (req, res) => {
+  const check = await verifyUrl(req.originalUrl, { secret: SECRET, clockToleranceSec: 60 });
+  if (!check.valid) throw new HttpError(check.reason === "expired" ? 410 : 403, "Link expired or invalid");
+  const file = await Upload.findById(req.params.id);
+  if (!file) throw new HttpError(404, "Not found");
+  res.setHeader("Content-Type", file.contentType);
+  res.send(Buffer.from(file.data, "base64"));
+}));
+// POST /uploads \u2014 protected: store a base64 data URL.
+router.post("/", requireAuth, asyncHandler(async (req, res) => {
+  const { filename, dataUrl } = UploadInput.parse(req.body);
+  const m = /^data:(.+?);base64,(.*)$/.exec(dataUrl);
+  if (!m) throw new HttpError(400, "Expected a base64 data URL");
+  const contentType = m[1]!;
+  const data = m[2]!;
+  const size = Math.floor((data.length * 3) / 4);
+  if (size > MAX_BYTES) throw new HttpError(413, "File too large (max 5 MB)");
+  const file = await Upload.create({ userId: req.user!.sub, filename, contentType, size, data });
+  res.status(201).json({ id: String(file._id), filename, contentType, size, url: await signed(String(file._id)) });
+}));
+// GET /uploads \u2014 protected: this user's files (with fresh signed URLs).
+router.get("/", requireAuth, asyncHandler(async (req, res) => {
+  const files = await Upload.find({ userId: req.user!.sub }).sort({ createdAt: -1 }).select("filename contentType size");
+  const out = await Promise.all(
+    files.map(async (f) => ({ id: String(f._id), filename: f.filename, contentType: f.contentType, size: f.size, url: await signed(String(f._id)) })),
+  );
+  res.json(out);
+}));
+export default router;
+`;
+var uploadsPage = () => `"use client";
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { getToken } from "@/lib/api";
+const API = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+interface FileItem { id: string; filename: string; contentType: string; size: number; url: string; }
+function readAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const r = new FileReader();
+    r.onload = () => resolve(String(r.result));
+    r.onerror = () => reject(new Error("read failed"));
+    r.readAsDataURL(file);
+  });
+}
+export default function UploadsPage() {
+  const router = useRouter();
+  const [files, setFiles] = useState<FileItem[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  async function load() {
+    const token = getToken();
+    if (!token) { router.push("/login"); return; }
+    const res = await fetch(API + "/uploads", { headers: { Authorization: "Bearer " + token } });
+    if (res.ok) setFiles(await res.json());
+  }
+  useEffect(() => { void load(); }, []);
+  async function onPick(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    setBusy(true); setError(null);
+    try {
+      const dataUrl = await readAsDataUrl(file);
+      const token = getToken();
+      const res = await fetch(API + "/uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(token ? { Authorization: "Bearer " + token } : {}) },
+        body: JSON.stringify({ filename: file.name, dataUrl }),
+      });
+      const data: unknown = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error((data as { error?: string }).error ?? "Upload failed");
+      await load();
+    } catch (err) { setError(err instanceof Error ? err.message : "Upload failed"); }
+    finally { setBusy(false); }
+  }
+  return (
+    <main className="mx-auto max-w-lg px-6 py-16">
+      <h1 className="text-2xl font-bold">Uploads</h1>
+      <p className="mt-1 text-muted">Stored in MongoDB, served via signed, expiring links.</p>
+      <label className="mt-6 flex cursor-pointer items-center justify-center rounded-2xl border border-dashed border-hairline p-8 text-muted transition hover:bg-surface">
+        <input type="file" className="hidden" onChange={onPick} disabled={busy} />
+        {busy ? "Uploading\u2026" : "Choose a file (max 5 MB)"}
+      </label>
+      {error && <p className="mt-3 text-sm text-red-400">{error}</p>}
+      <ul className="mt-6 space-y-2">
+        {files.map((f) => (
+          <li key={f.id} className="flex items-center justify-between rounded-xl border border-hairline p-3">
+            <a href={API + f.url} target="_blank" rel="noreferrer" className="truncate underline">{f.filename}</a>
+            <span className="ml-3 shrink-0 text-sm text-muted">{Math.max(1, Math.round(f.size / 1024))} KB</span>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+`;
 var scope = (ctx) => `@${ctx.name}`;
 var typesPkgJson = (ctx) => JSON.stringify({
   name: `${scope(ctx)}/types`,
@@ -6658,6 +7010,9 @@ function buildFullStack(ctx) {
   out[".gitignore"] = rootGitignore();
   out[".env.example"] = rootEnvExample(ctx);
   out["README.md"] = rootReadme(ctx);
+  for (const f of ctx.features) {
+    for (const [rel, content] of Object.entries(f.rootFiles?.(ctx) ?? {})) out[rel] = content;
+  }
   const envBase = out[".env.example"];
   const seen = new Set(
     (envBase.match(/^#?\s*([A-Z0-9_]+)=/gm) ?? []).map((l) => l.replace(/^#?\s*/, "").replace(/=.*/, ""))
@@ -7217,7 +7572,7 @@ function backendFiles(ctx) {
 }
 var splitList = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 function parseArgs(list) {
-  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false };
+  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false, dryRun: false };
   for (let i = 0; i < list.length; i++) {
     const arg = list[i];
     const next = () => list[++i] ?? "";
@@ -7225,8 +7580,9 @@ function parseArgs(list) {
     else if (arg === "-y" || arg === "--yes") a.yes = true;
     else if (arg === "--no-install") a.install = false;
     else if (arg === "--no-git") a.git = false;
+    else if (arg === "--dry-run" || arg === "--dry") a.dryRun = true;
     else if (arg === "--pm") a.pm = next();
-    else if (arg === "--theme" || arg === "--accent") a.theme = next();
+    else if (arg === "--theme" || arg === "--accent" || arg === "--brand") a.theme = next();
     else if (arg === "--with" || arg === "--features") a.features.push(...splitList(next()));
     else if (arg === "--fullstack" || arg === "--full-stack" || arg === "--dynamic") a.mode = "dynamic";
     else if (arg === "--static") a.mode = "static";
@@ -7242,6 +7598,7 @@ function parseArgs(list) {
     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);
+    else if (arg.startsWith("--brand=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--with=")) a.features.push(...splitList(arg.slice(7)));
     else if (arg.startsWith("--features=")) a.features.push(...splitList(arg.slice(11)));
     else if (!arg.startsWith("-") && !a.name) a.name = arg;
@@ -7332,6 +7689,8 @@ ${c("bold", "Usage")}
   npm create lacspace-app@latest <name> [options]
   npx create-lacspace-app <name> --template <key>
   npx create-lacspace-app add <section...>   ${c("dim", "# grow an existing app")}
+  npx create-lacspace-app list                ${c("dim", "# templates, add-ons & recipes")}
+  npx create-lacspace-app explain <name>      ${c("dim", "# what an add-on/recipe gives you")}
 ${c("bold", "Templates")}
 ${TEMPLATES.map((t) => `  ${t.key.padEnd(10)} ${t.description}`).join("\n")}
@@ -7343,8 +7702,9 @@ ${c("bold", "Options")}
                          ${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)
+  --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (alias --brand)
   --pm <npm|pnpm|yarn|bun>  Package manager (default npm)
+  --dry-run              Print the files that would be created; write nothing
   --no-install           Skip installing dependencies
   --no-git               Skip git init
   -y, --yes              Accept defaults (needs <name>)
@@ -7720,12 +8080,103 @@ ${c("bold", "Use them")} \u2014 import into any page:
     return;
   }
 }
+function runList() {
+  stdout.write(`
+${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 what you can build")}
+`);
+  stdout.write(`
+${c("bold", "Templates")} ${c("dim", "(-t / --template)")}
+`);
+  for (const t of TEMPLATES) stdout.write(`  ${c("cyan", t.key.padEnd(12))} ${c("dim", t.description)}
+`);
+  stdout.write(`
+${c("bold", "Add-ons")} ${c("dim", "(--with) \u2014 free & keyless")}
+`);
+  for (const f of FEATURES) stdout.write(`  ${c("cyan", f.key.padEnd(12))} ${c("dim", f.description)}${f.requiresBackend ? c("green", "  [full-stack]") : ""}
+`);
+  stdout.write(`
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+`);
+  for (const r of RECIPES) stdout.write(`  ${c("cyan", r.key.padEnd(14))} ${c("dim", r.description)}
+`);
+  stdout.write(`
+  ${c("dim", "Learn one:")} ${c("cyan", "npx create-lacspace-app explain <name>")}
+`);
+}
+function runExplain(rawNames) {
+  const name = rawNames.find((n) => !n.startsWith("-"))?.toLowerCase();
+  if (!name) {
+    stdout.write(`Usage: ${c("cyan", "npx create-lacspace-app explain <template|add-on|recipe>")}
+`);
+    runList();
+    return;
+  }
+  const feat = FEATURES.find((f) => f.key === name);
+  const recipe = RECIPES.find((r) => r.key === name);
+  const tmpl = TEMPLATES.find((t) => t.key === name);
+  stdout.write("\n");
+  if (feat) {
+    stdout.write(`${c("bold", c("magenta", "add-on: " + feat.key))} ${feat.requiresBackend ? c("green", "[full-stack]") : c("dim", "[frontend]")}
+${feat.description}
+`);
+    const deps = { ...feat.deps, ...feat.backend?.({ name: "app", template: TEMPLATES[0], features: [], mode: "dynamic" })?.deps ?? {} };
+    if (Object.keys(deps).length) stdout.write(`
+${c("bold", "Packages")}: ${Object.keys(deps).map((d) => c("cyan", d)).join(", ")}
+`);
+    stdout.write(`
+${c("bold", "Next steps")}:
+`);
+    for (const s of feat.nextSteps) stdout.write(`  ${c("dim", "\u2022")} ${s}
+`);
+    if (feat.learn) stdout.write(`
+Learn more \u2192 ${c("cyan", feat.learn)}
+`);
+    stdout.write(`
+Add it: ${c("cyan", "npx create-lacspace-app my-app --with " + feat.key)}
+`);
+  } else if (recipe) {
+    stdout.write(`${c("bold", c("magenta", "recipe: " + recipe.key))}
+${recipe.description}
+${c("bold", "Template")}: ${c("cyan", recipe.template)}${recipe.mode ? c("dim", " \xB7 " + recipe.mode) : ""}
+${c("bold", "Add-ons")}: ${recipe.features.map((f) => c("cyan", f)).join(", ")}
+Use it: ${c("cyan", "npx create-lacspace-app my-app --recipe " + recipe.key)}
+`);
+  } else if (tmpl) {
+    stdout.write(`${c("bold", c("magenta", "template: " + tmpl.key))}
+${tmpl.description}
+Use it: ${c("cyan", "npx create-lacspace-app my-app --template " + tmpl.key)}
+`);
+  } else {
+    stdout.write(c("yellow", `Unknown "${name}".
+`));
+    runList();
+  }
+}
 async function main() {
   const raw = argv.slice(2);
   if (raw[0] === "add") {
     runAdd(raw.slice(1));
     return;
   }
+  if (raw[0] === "list" || raw[0] === "ls") {
+    runList();
+    return;
+  }
+  if (raw[0] === "explain" || raw[0] === "info") {
+    runExplain(raw.slice(1));
+    return;
+  }
   const args = parseArgs(raw);
   if (args.help) {
     stdout.write(HELP + "\n");
@@ -7744,10 +8195,32 @@ ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a go
   let templateKey = args.template ?? recipe?.template;
   let mode = args.mode ?? recipe?.mode ?? "static";
   const featureKeys = [...recipe?.features ?? [], ...args.features];
+  let usedRecipe = Boolean(recipe);
   if (!args.yes && stdin.isTTY) {
     const rl = createInterface({ input: stdin, output: stdout });
     try {
       if (!name) name = (await rl.question(`${c("green", "?")} Project name ${c("dim", "(my-app)")}: `)).trim() || "my-app";
+      if (!usedRecipe && !templateKey && featureKeys.length === 0) {
+        stdout.write(`
+  Start from a recipe? ${c("dim", "(a template + add-ons, ready to go)")}
+`);
+        RECIPES.forEach((r, i) => stdout.write(`   ${c("cyan", String(i + 1))}. ${c("bold", r.label)} ${c("dim", "\u2014 " + r.description)}
+`));
+        stdout.write(`   ${c("cyan", "0")}. ${c("dim", "No recipe \u2014 I'll choose a template myself")}
+`);
+        const ans = (await rl.question(`
+${c("green", "?")} Recipe ${c("dim", "(0)")}: `)).trim() || "0";
+        const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : RECIPES.findIndex((r) => r.key === ans);
+        const chosen = ans === "0" ? void 0 : RECIPES[idx];
+        if (chosen) {
+          usedRecipe = true;
+          templateKey = chosen.template;
+          mode = chosen.mode ?? mode;
+          for (const k of chosen.features) if (!featureKeys.includes(k)) featureKeys.push(k);
+          stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", chosen.key)}
+`);
+        }
+      }
       if (!templateKey) {
         stdout.write(`
   Choose a template:
@@ -7759,7 +8232,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 && !recipe) {
+      if (args.mode === void 0 && !usedRecipe) {
         stdout.write(`
   What kind of app?
 `);
@@ -7818,6 +8291,19 @@ ${c("green", "?")} Add features? ${c("dim", "(comma-separated numbers, or Enter
 `);
   }
   const files = buildFiles({ name: projectName, template, features, mode });
+  if (args.dryRun) {
+    const keys = Object.keys(files).sort();
+    stdout.write(`
+  ${c("bold", "Dry run")} ${c("dim", `\u2014 ${keys.length} files (${mode}${features.length ? ", +" + features.map((f) => f.key).join(",") : ""}), nothing written`)}
+`);
+    for (const rel of keys) stdout.write(`    ${c("dim", "+ " + rel)}
+`);
+    stdout.write(`
+  ${c("dim", "Remove --dry-run to create the project.")}
+`);
+    return;
+  }
   for (const [rel, content] of Object.entries(files)) {
     const full = join(dir, rel);
     mkdirSync(dirname(full), { recursive: true });