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/dist/lib.cjs CHANGED Viewed

@@ -2001,6 +2001,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) {
@@ -2279,6 +2284,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";
@@ -6263,6 +6330,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`,
@@ -6662,6 +7014,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(/=.*/, ""))
@@ -7221,7 +7576,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] ?? "";
@@ -7229,8 +7584,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";
@@ -7246,6 +7602,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;
@@ -7336,6 +7693,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")}
@@ -7347,8 +7706,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>)
@@ -7724,12 +8084,103 @@ ${c("bold", "Use them")} \u2014 import into any page:
     return;
   }
 }
+function runList() {
+  process$1.stdout.write(`
+${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 what you can build")}
+`);
+  process$1.stdout.write(`
+${c("bold", "Templates")} ${c("dim", "(-t / --template)")}
+`);
+  for (const t of TEMPLATES) process$1.stdout.write(`  ${c("cyan", t.key.padEnd(12))} ${c("dim", t.description)}
+`);
+  process$1.stdout.write(`
+${c("bold", "Add-ons")} ${c("dim", "(--with) \u2014 free & keyless")}
+`);
+  for (const f of FEATURES) process$1.stdout.write(`  ${c("cyan", f.key.padEnd(12))} ${c("dim", f.description)}${f.requiresBackend ? c("green", "  [full-stack]") : ""}
+`);
+  process$1.stdout.write(`
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+`);
+  for (const r of RECIPES) process$1.stdout.write(`  ${c("cyan", r.key.padEnd(14))} ${c("dim", r.description)}
+`);
+  process$1.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) {
+    process$1.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);
+  process$1.stdout.write("\n");
+  if (feat) {
+    process$1.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) process$1.stdout.write(`
+${c("bold", "Packages")}: ${Object.keys(deps).map((d) => c("cyan", d)).join(", ")}
+`);
+    process$1.stdout.write(`
+${c("bold", "Next steps")}:
+`);
+    for (const s of feat.nextSteps) process$1.stdout.write(`  ${c("dim", "\u2022")} ${s}
+`);
+    if (feat.learn) process$1.stdout.write(`
+Learn more \u2192 ${c("cyan", feat.learn)}
+`);
+    process$1.stdout.write(`
+Add it: ${c("cyan", "npx create-lacspace-app my-app --with " + feat.key)}
+`);
+  } else if (recipe) {
+    process$1.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) {
+    process$1.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 {
+    process$1.stdout.write(c("yellow", `Unknown "${name}".
+`));
+    runList();
+  }
+}
 async function main() {
   const raw = process$1.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) {
     process$1.stdout.write(HELP + "\n");
@@ -7748,10 +8199,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 && process$1.stdin.isTTY) {
     const rl = promises.createInterface({ input: process$1.stdin, output: process$1.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) {
+        process$1.stdout.write(`
+  Start from a recipe? ${c("dim", "(a template + add-ons, ready to go)")}
+`);
+        RECIPES.forEach((r, i) => process$1.stdout.write(`   ${c("cyan", String(i + 1))}. ${c("bold", r.label)} ${c("dim", "\u2014 " + r.description)}
+`));
+        process$1.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);
+          process$1.stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", chosen.key)}
+`);
+        }
+      }
       if (!templateKey) {
         process$1.stdout.write(`
   Choose a template:
@@ -7763,7 +8236,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) {
         process$1.stdout.write(`
   What kind of app?
 `);
@@ -7822,6 +8295,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();
+    process$1.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) process$1.stdout.write(`    ${c("dim", "+ " + rel)}
+`);
+    process$1.stdout.write(`
+  ${c("dim", "Remove --dry-run to create the project.")}
+`);
+    return;
+  }
   for (const [rel, content] of Object.entries(files)) {
     const full = path.join(dir, rel);
     fs.mkdirSync(path.dirname(full), { recursive: true });

package/dist/lib.d.cts CHANGED Viewed

@@ -26,6 +26,12 @@ interface FeatureDef {
     deps: Record<string, string>;
     /** The files this feature drops in, given the resolved {@link Ctx}. */
     files: (ctx: Ctx) => Record<string, string>;
+    /**
+     * Files placed at the PROJECT ROOT — in static mode that's the app root; in
+     * dynamic mode it's the monorepo root (not `frontend/`). Use it for things a
+     * repo needs at the top, like a CI workflow.
+     */
+    rootFiles?: (ctx: Ctx) => Record<string, string>;
     /** Optional `.env.example` entries — `NAME: "explanatory comment"`. */
     env?: Record<string, string>;
     /** Optional `package.json` scripts, merged in. */

package/dist/lib.d.ts CHANGED Viewed

@@ -26,6 +26,12 @@ interface FeatureDef {
     deps: Record<string, string>;
     /** The files this feature drops in, given the resolved {@link Ctx}. */
     files: (ctx: Ctx) => Record<string, string>;
+    /**
+     * Files placed at the PROJECT ROOT — in static mode that's the app root; in
+     * dynamic mode it's the monorepo root (not `frontend/`). Use it for things a
+     * repo needs at the top, like a CI workflow.
+     */
+    rootFiles?: (ctx: Ctx) => Record<string, string>;
     /** Optional `.env.example` entries — `NAME: "explanatory comment"`. */
     env?: Record<string, string>;
     /** Optional `package.json` scripts, merged in. */