create-volt 0.3.2 → 0.8.0

package/templates/default/server.js

@@ -0,0 +1,213 @@
+// server.js — dev server with a built-in first-run setup wizard.
+//
+// First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
+// config page; click Apply and it writes .env, loads it, and starts the app
+// in-process — then the setup page is gone. Normal runs just start the app.
+//
+// No build step, no env-file flag: .env is auto-loaded below.
+
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import express from "express";
+import { Server as SocketServer } from "socket.io";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ENV_PATH = path.join(__dirname, ".env");
+const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
+
+// --- tiny .env loader (no dependency); never overrides an existing env var ---
+function readEnvFile() {
+  const out = {};
+  if (!fs.existsSync(ENV_PATH)) return out;
+  for (const line of fs.readFileSync(ENV_PATH, "utf8").split("\n")) {
+    const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.*?)\s*$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+function loadEnv() {
+  for (const [k, v] of Object.entries(readEnvFile())) if (!(k in process.env)) process.env[k] = v;
+}
+
+// Which add-ons are present? (detected by their files, so the wizard only asks
+// for settings that actually apply.)
+function presentAddons() {
+  const has = (f) => fs.existsSync(path.join(__dirname, f));
+  return { db: has("lib/store.js"), auth: has("lib/auth.js"), mailer: has("lib/mailer.js"), realtime: has("lib/realtime.js") };
+}
+
+// Open the default browser at `url` — but only when there's a desktop to open
+// it on. Headless / remote (no DISPLAY) just keeps the printed link. Opt out
+// with VOLT_NO_OPEN=1 or --no-open.
+function openBrowser(url) {
+  if (process.env.VOLT_NO_OPEN || process.argv.includes("--no-open")) return false;
+  const plat = process.platform;
+  if (plat === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return false;
+  const cmd = plat === "darwin" ? "open" : plat === "win32" ? "cmd" : "xdg-open";
+  const args = plat === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // launcher missing (e.g. no xdg-open) emits async — don't crash
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- the actual app ---
+function startApp() {
+  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const app = express();
+  app.use(express.static(path.join(__dirname, "public")));
+  app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
+
+  const server = http.createServer(app);
+  const io = new SocketServer(server);
+
+  // hot reload: watch views/ + public/, debounce, broadcast a reload
+  let timer = null;
+  const onChange = (file) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      io.emit("volt:reload");
+    }, 80);
+  };
+  const watchRecursive = (dir) => {
+    try {
+      fs.watch(dir, { recursive: true }, (_e, f) => onChange(f));
+      return;
+    } catch {
+      /* fall back to per-directory watchers */
+    }
+    const w = (d) => {
+      try {
+        fs.watch(d, (_e, f) => onChange(f));
+      } catch {
+        /* ignore */
+      }
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) if (e.isDirectory()) w(path.join(d, e.name));
+    };
+    w(dir);
+  };
+  for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
+
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}`));
+}
+
+// --- the disposable setup wizard (localhost only) ---
+function startSetup() {
+  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const assets = {
+    "/setup.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "setup", "setup.js"))],
+    "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
+  };
+  const indexHtml = fs.readFileSync(path.join(__dirname, "setup", "index.html"));
+
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, "http://localhost");
+    const p = u.pathname;
+    if (req.method === "GET" && p === "/") {
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      return res.end(indexHtml);
+    }
+    if (req.method === "GET" && assets[p]) {
+      res.setHeader("Content-Type", assets[p][0]);
+      return res.end(assets[p][1]);
+    }
+    if (req.method === "GET" && p === "/setup/state") {
+      res.setHeader("Content-Type", "application/json");
+      return res.end(JSON.stringify({ present: presentAddons(), current: readEnvFile(), defaultPort: DEFAULT_PORT }));
+    }
+    if (req.method === "POST" && p === "/setup/test-db") {
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", async () => {
+        const keys = ["DB_DRIVER", "MONGODB_URI", "MONGODB_DATABASE", "DATABASE_URL"];
+        const saved = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+        try {
+          const { env = {} } = JSON.parse(body);
+          for (const k of keys) {
+            if (env[k]) process.env[k] = env[k];
+            else delete process.env[k];
+          }
+          const { createStore } = await import(pathToFileURL(path.join(__dirname, "lib", "store.js")).href);
+          const store = await createStore();
+          await store.collection("__voltcheck").all(); // actually touch the connection
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ ok: true, driver: store.name }));
+        } catch (e) {
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ ok: false, error: e.message }));
+        } finally {
+          for (const k of keys) {
+            if (saved[k] == null) delete process.env[k];
+            else process.env[k] = saved[k];
+          }
+        }
+      });
+      return;
+    }
+    if (req.method === "POST" && p === "/setup/apply") {
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", () => {
+        try {
+          const { env } = JSON.parse(body);
+          if (typeof env !== "string") throw new Error("missing env");
+          fs.writeFileSync(ENV_PATH, env);
+          // The app binds process.env.PORT if it's already set (loadEnv won't
+          // override it), else the .env PORT, else the default — redirect there.
+          const envPort = Number((env.match(/^\s*PORT\s*=\s*(\d+)/m) || [])[1]);
+          const newPort = process.env.PORT ? Number(process.env.PORT) : envPort || DEFAULT_PORT;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ ok: true, port: newPort }));
+          console.log("[volt] saved .env — starting the app…");
+          res.on("finish", () => {
+            server.close(() => {
+              loadEnv();
+              startApp();
+            });
+            server.closeIdleConnections?.(); // drop the keep-alive socket so close() fires now
+          });
+        } catch (e) {
+          res.statusCode = 400;
+          res.end(JSON.stringify({ ok: false, error: e.message }));
+        }
+      });
+      return;
+    }
+    res.statusCode = 404;
+    res.end("not found");
+  });
+
+  // localhost-only: an unauthenticated write endpoint shouldn't be on the network
+  server.listen(PORT, "127.0.0.1", () => {
+    const url = `http://localhost:${PORT}`;
+    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
+    const ssh = process.env.SSH_CONNECTION; // "clientIP clientPort serverIP serverPort"
+    if (ssh) {
+      const host = ssh.split(" ")[2];
+      const user = process.env.USER || process.env.USERNAME || "you";
+      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
+      console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+    }
+    console.log("");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+  });
+}
+
+// --- gate: setup on first run / --edit, otherwise the app ---
+const editMode = process.argv.includes("--edit") || process.argv.includes("-e");
+if (editMode || !fs.existsSync(ENV_PATH)) {
+  startSetup();
+} else {
+  loadEnv();
+  startApp();
+}

package/templates/default/setup/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Set up your Volt app</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+  <style>
+    body { background: #0f1115; color: #e7e9ee; }
+    .accent { color: #ffd24a; }
+    .card-x { background: #161a22; border: 1px solid #232a36; border-radius: 14px; }
+    .form-control, .form-select { background: #0f1115; color: #e7e9ee; border-color: #232a36; }
+    .form-control:focus, .form-select:focus { background: #0f1115; color: #e7e9ee; border-color: #ffd24a; box-shadow: none; }
+    code { color: #ffd24a; }
+  </style>
+</head>
+<body>
+  <main class="container py-5" style="max-width: 640px;">
+    <header class="mb-4">
+      <h1 class="h3"><span class="accent">⚡ Set up your Volt app</span></h1>
+      <p class="text-muted mb-0">Fill these in and the app starts. This page is disposable — it disappears once you click Apply. Re-open it anytime with <code>npm run dev -- --edit</code>.</p>
+    </header>
+    <div id="app"></div>
+  </main>
+  <script type="module" src="/setup.js"></script>
+</body>
+</html>

package/templates/default/setup/setup.js

@@ -0,0 +1,121 @@
+// setup.js — the first-run / --edit settings wizard, built with Volt. Asks only
+// for the settings the present add-ons need, writes .env, then the app starts.
+import { signal, computed, html, mount } from "/volt.js";
+
+const { present, current, defaultPort } = await (await fetch("/setup/state")).json();
+
+const state = signal({
+  port: current.PORT || String(defaultPort),
+  dbDriver: current.DB_DRIVER || "memory",
+  mongoUri: current.MONGODB_URI || "",
+  mongoDb: current.MONGODB_DATABASE || "",
+  dbUrl: current.DATABASE_URL || "",
+  smtpUrl: current.SMTP_URL || "",
+  mailFrom: current.MAIL_FROM || "",
+});
+const set = (patch) => state({ ...state(), ...patch });
+const status = signal("");
+
+function genEnv(s) {
+  const out = [`PORT=${s.port}`];
+  if (present.db) {
+    out.push(`DB_DRIVER=${s.dbDriver}`);
+    if (s.dbDriver === "mongodb") {
+      out.push(`MONGODB_URI=${s.mongoUri}`);
+      if (s.mongoDb) out.push(`MONGODB_DATABASE=${s.mongoDb}`);
+    } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
+      out.push(`DATABASE_URL=${s.dbUrl}`);
+    }
+  }
+  if (present.mailer) {
+    if (s.smtpUrl) out.push(`SMTP_URL=${s.smtpUrl}`);
+    else out.push("# SMTP_URL=        # unset → emails print to the console");
+    if (s.mailFrom) out.push(`MAIL_FROM=${s.mailFrom}`);
+  }
+  return out.join("\n") + "\n";
+}
+const env = computed(() => genEnv(state()));
+
+async function apply() {
+  status("Saving & starting…");
+  try {
+    const r = await fetch("/setup/apply", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ env: env() }) });
+    const d = await r.json();
+    if (!d.ok) return status("Error: " + d.error);
+    status("Starting the app…");
+    const target = `http://localhost:${d.port}/`;
+    const go = async (n) => {
+      try {
+        await fetch(target, { mode: "no-cors" }); // app is listening
+        location.href = target;
+      } catch {
+        if (n > 0) setTimeout(() => go(n - 1), 400);
+        else location.href = target;
+      }
+    };
+    setTimeout(() => go(20), 500);
+  } catch {
+    status("Network error — try again.");
+  }
+}
+
+async function testDb() {
+  const s = state();
+  const env = { DB_DRIVER: s.dbDriver };
+  if (s.dbDriver === "mongodb") {
+    env.MONGODB_URI = s.mongoUri;
+    env.MONGODB_DATABASE = s.mongoDb;
+  } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
+    env.DATABASE_URL = s.dbUrl;
+  }
+  status("Testing connection…");
+  try {
+    const r = await fetch("/setup/test-db", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ env }) });
+    const d = await r.json();
+    status(d.ok ? `✓ Connected (${d.driver}).` : `✗ ${d.error}`);
+  } catch {
+    status("Network error testing connection.");
+  }
+}
+
+const field = (label, key, placeholder = "") =>
+  html`<div class="mb-2">
+    <label class="form-label small mb-1">${label}</label>
+    <input class="form-control" placeholder=${placeholder} value=${() => state()[key]} oninput=${(e) => set({ [key]: e.target.value })} />
+  </div>`;
+
+const dbSettings = () =>
+  html`<div class="mb-2">
+      <label class="form-label small mb-1">Database (DB_DRIVER)</label>
+      <select class="form-select" value=${() => state().dbDriver} onchange=${(e) => set({ dbDriver: e.target.value })}>
+        <option value="memory">memory (no setup)</option>
+        <option value="mongodb">mongodb</option>
+        <option value="mysql">mysql</option>
+        <option value="postgres">postgres</option>
+      </select>
+    </div>
+    ${() =>
+      state().dbDriver === "mongodb"
+        ? html`${field("MONGODB_URI", "mongoUri", "mongodb://user:pass@host:27017/db")}${field("MONGODB_DATABASE", "mongoDb", "db")}`
+        : state().dbDriver === "mysql" || state().dbDriver === "postgres"
+          ? field("DATABASE_URL", "dbUrl", state().dbDriver + "://user:pass@host/db")
+          : null}
+    ${() => (state().dbDriver !== "memory" ? html`<button class="btn btn-sm btn-outline-secondary mb-2" onclick=${testDb}>Test connection</button>` : null)}`;
+
+mount(
+  "#app",
+  html`<div class="card-x p-4 mb-3">
+    <h2 class="h6 mb-3">Settings</h2>
+    ${field("PORT", "port", String(defaultPort))}
+    ${() => (present.db ? dbSettings() : null)}
+    ${() => (present.mailer ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+  </div>`,
+  html`<div class="card-x p-4 mb-3">
+    <div class="d-flex justify-content-between align-items-center mb-2">
+      <h2 class="h6 mb-0">.env</h2>
+      <button class="btn btn-primary btn-sm" onclick=${apply}>Apply & start →</button>
+    </div>
+    <pre class="mb-0" style="background:#0b0d11;border:1px solid #232a36;border-radius:10px;padding:12px;color:#cfe3ff;white-space:pre-wrap">${env}</pre>
+  </div>`,
+  () => (status() ? html`<p class="small accent">${status}</p>` : null),
+);

package/{template → templates/default}/views/index.html

@@ -30,6 +30,9 @@
 
     <footer class="text-center text-muted mt-5">
       <small>Both cards run on the same signal engine — one uses <code>el()</code>, the other <code>html``</code>.</small>
+      <div class="mt-2">
+        <small><a href="https://github.com/MIR-2025/volt#readme" target="_blank" rel="noopener">📖 How to build a Volt app →</a></small>
+      </div>
     </footer>
   </main>
 

package/templates/guestbook/README.md

@@ -0,0 +1,71 @@
+# 📖 Guestbook — a real Volt app
+
+A live message board built with [Volt](https://github.com/MIR-2025/volt):
+fine-grained signals on the frontend, **Socket.io** for real-time updates,
+**magic-link** sign-in (no passwords), and **pluggable storage** —
+in-memory by default, or MongoDB / MySQL / Postgres for persistence.
+
+## Run
+
+```bash
+npm install        # if you scaffolded with --skip-install
+npm run dev        # → http://localhost:26629
+```
+
+Out of the box it uses an **in-memory store** and prints magic-link emails to
+the **server console** — so you can try the whole flow with zero setup:
+
+1. Enter your email, click **Send magic link**.
+2. Copy the link printed in the terminal, open it.
+3. Click **Confirm login** (must be the same browser).
+4. Post a message — open a second tab to watch it appear live.
+
+## Storage backends
+
+Pick a backend with `DB_DRIVER` (default `memory`). Real drivers are lazy-loaded,
+so install only the one you use.
+
+```bash
+# MongoDB
+DB_DRIVER=mongodb MONGODB_URI="mongodb://user:<password>@host:27017/guestbook?authSource=admin" \
+  MONGODB_DATABASE=guestbook npm start
+
+# MySQL  (npm install mysql2)
+DB_DRIVER=mysql DATABASE_URL="mysql://user:<password>@host:3306/guestbook" npm start
+
+# Postgres  (npm install pg)
+DB_DRIVER=postgres DATABASE_URL="postgres://user:<password>@host:5432/guestbook" npm start
+```
+
+Tables/collections are created automatically on first run. Never hard-code the
+credential — keep it in your environment / `.env`.
+
+## Email (magic links)
+
+In dev, links are printed to the console. For real email, set `SMTP_URL` (and
+`MAIL_FROM`) and `npm install nodemailer`:
+
+```bash
+SMTP_URL="smtp://user:pass@smtp.example.com:587" MAIL_FROM="Guestbook <no-reply@you.com>" npm start
+```
+
+## Layout
+
+```
+server.js          Express + Socket.io + storage/mailer wiring
+router.js          routes; composes views with a header include
+lib/store.js       backend selector (memory | mongodb | mysql | postgres)
+lib/stores/        the adapters (same interface each)
+lib/auth.js        magic-link tokens + sessions
+lib/mailer.js      console (dev) or SMTP (prod)
+public/volt.js     the Volt library (no build step)
+public/app.js      the frontend — signals + Socket.io
+views/             index, confirm page, header partial
+```
+
+## Production
+
+Runs anywhere Node does. Under PM2: `pm2 start server.js --name guestbook`.
+Set `PORT`, `DB_DRIVER`, the connection string, and `SMTP_URL` in the environment.
+
+Scaffolded with [`create-volt`](https://www.npmjs.com/package/create-volt) — `--template guestbook`.

package/templates/guestbook/gitignore

@@ -0,0 +1,5 @@
+node_modules
+npm-debug.log*
+.DS_Store
+.env
+*.local

package/templates/guestbook/lib/auth.js

@@ -0,0 +1,63 @@
+// auth.js — magic-link login (no passwords), per the house auth convention:
+//   1. user submits email → we store a one-time token + the requesting UA,
+//      and email a link containing the token
+//   2. opening the link shows a confirm page (must be the same browser/UA)
+//   3. clicking "Confirm" consumes the token and starts a session cookie
+//
+// Tokens expire after TOKEN_TTL and are single-use. Sessions are random ids
+// kept in the store and carried in an httpOnly cookie.
+
+import crypto from "node:crypto";
+
+const TOKEN_TTL = 15 * 60 * 1000; // 15 minutes
+const SESSION_TTL = 30 * 24 * 60 * 60 * 1000; // 30 days
+export const SESSION_COOKIE = "gb_sid";
+
+const token = () => crypto.randomBytes(32).toString("hex");
+const normalizeEmail = (e) => String(e || "").trim().toLowerCase();
+const validEmail = (e) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e);
+
+// Step 1: create + email a magic link. Returns { ok } or throws on bad input.
+export async function requestLogin(store, mailer, { email, ua, baseUrl }) {
+  const addr = normalizeEmail(email);
+  if (!validEmail(addr)) throw new Error("Please enter a valid email address.");
+  const tok = token();
+  await store.putToken({ token: tok, email: addr, ua: ua || "", expiresAt: Date.now() + TOKEN_TTL });
+  const link = `${baseUrl}/verify?token=${tok}`;
+  await mailer.sendMagicLink(addr, link);
+  return { ok: true };
+}
+
+// Step 3: confirm a token → start a session. Returns { sessionId, email }.
+export async function confirmLogin(store, { token: tok, ua }) {
+  const rec = await store.getToken(tok);
+  if (!rec) throw new Error("This login link is invalid.");
+  if (rec.used) throw new Error("This login link was already used.");
+  if (rec.expiresAt < Date.now()) throw new Error("This login link has expired.");
+  if (rec.ua && ua && rec.ua !== ua) throw new Error("Open the link in the same browser you requested it from.");
+
+  await store.useToken(tok);
+  const sessionId = token();
+  await store.putSession({ id: sessionId, email: rec.email, expiresAt: Date.now() + SESSION_TTL });
+  return { sessionId, email: rec.email };
+}
+
+// Parse a cookie header into a plain object.
+export function parseCookies(header = "") {
+  const out = {};
+  for (const part of header.split(";")) {
+    const i = part.indexOf("=");
+    if (i === -1) continue;
+    out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
+  }
+  return out;
+}
+
+// Resolve the current session from a request, or null.
+export async function sessionFromReq(store, req) {
+  const sid = parseCookies(req.headers.cookie)[SESSION_COOKIE];
+  if (!sid) return null;
+  return await store.getSession(sid);
+}
+
+export const cookieMaxAgeSeconds = SESSION_TTL / 1000;

package/templates/guestbook/lib/mailer.js

@@ -0,0 +1,39 @@
+// mailer.js — sends the magic-link email. In dev (no SMTP configured) it just
+// prints the link to the console so you can copy it; in production it uses
+// nodemailer if SMTP_URL is set and the package is installed.
+
+export async function createMailer() {
+  const smtp = process.env.SMTP_URL;
+  const from = process.env.MAIL_FROM || "Guestbook <no-reply@example.com>";
+
+  if (smtp) {
+    let nodemailer;
+    try {
+      nodemailer = (await import("nodemailer")).default;
+    } catch {
+      console.warn("[mailer] SMTP_URL set but 'nodemailer' isn't installed — falling back to console. Run: npm install nodemailer");
+    }
+    if (nodemailer) {
+      const transport = nodemailer.createTransport(smtp);
+      return {
+        name: "smtp",
+        async sendMagicLink(email, link) {
+          await transport.sendMail({
+            to: email,
+            from,
+            subject: "Your guestbook login link",
+            text: `Click to sign in: ${link}\n\nThis link expires shortly and can only be used once.`,
+            html: `<p>Click to sign in:</p><p><a href="${link}">${link}</a></p><p>This link expires shortly and can only be used once.</p>`,
+          });
+        },
+      };
+    }
+  }
+
+  return {
+    name: "console",
+    async sendMagicLink(email, link) {
+      console.log(`\n📨  Magic link for ${email}:\n    ${link}\n    (dev mode — paste this into your browser)\n`);
+    },
+  };
+}

package/templates/guestbook/lib/store.js

@@ -0,0 +1,43 @@
+// store.js — pick a storage backend from the environment. Defaults to the
+// in-memory store so the app runs with zero setup; point DB_DRIVER at a real
+// database (mongodb | mysql | postgres) for persistence.
+//
+//   DB_DRIVER=memory                       (default)
+//   DB_DRIVER=mongodb  MONGODB_URI=...  [MONGODB_DATABASE=...]
+//   DB_DRIVER=mysql    DATABASE_URL=mysql://user:pass@host:3306/db
+//   DB_DRIVER=postgres DATABASE_URL=postgres://user:pass@host:5432/db
+
+import { createMemoryStore } from "./stores/memory.js";
+import { createMongoStore } from "./stores/mongo.js";
+import { createSqlStore } from "./stores/sql.js";
+
+export async function createStore() {
+  const driver = (process.env.DB_DRIVER || "memory").toLowerCase();
+
+  let store;
+  switch (driver) {
+    case "memory":
+      store = createMemoryStore();
+      break;
+    case "mongodb":
+    case "mongo":
+      store = await createMongoStore({
+        uri: process.env.MONGODB_URI,
+        dbName: process.env.MONGODB_DATABASE,
+      });
+      break;
+    case "mysql":
+      store = await createSqlStore({ dialect: "mysql", uri: process.env.DATABASE_URL });
+      break;
+    case "postgres":
+    case "postgresql":
+    case "pg":
+      store = await createSqlStore({ dialect: "postgres", uri: process.env.DATABASE_URL });
+      break;
+    default:
+      throw new Error(`Unknown DB_DRIVER "${driver}" (use memory | mongodb | mysql | postgres)`);
+  }
+
+  await store.init();
+  return store;
+}

package/templates/guestbook/lib/stores/memory.js

@@ -0,0 +1,49 @@
+// memory.js — in-memory store. The zero-dependency dev fallback so the app
+// runs out of the box; data is lost on restart. Same interface as the real
+// MongoDB / MySQL / Postgres adapters.
+
+export function createMemoryStore() {
+  const tokens = new Map(); // token -> { token, email, ua, expiresAt, used }
+  const sessions = new Map(); // id -> { id, email, expiresAt }
+  const messages = []; // { id, email, body, createdAt }
+
+  return {
+    name: "memory",
+    async init() {},
+
+    async putToken(t) {
+      tokens.set(t.token, { ...t, used: false });
+    },
+    async getToken(token) {
+      return tokens.get(token) || null;
+    },
+    async useToken(token) {
+      const t = tokens.get(token);
+      if (t) t.used = true;
+    },
+
+    async putSession(s) {
+      sessions.set(s.id, s);
+    },
+    async getSession(id) {
+      const s = sessions.get(id);
+      if (!s) return null;
+      if (s.expiresAt < Date.now()) {
+        sessions.delete(id);
+        return null;
+      }
+      return s;
+    },
+    async delSession(id) {
+      sessions.delete(id);
+    },
+
+    async addMessage(m) {
+      messages.push(m);
+      return m;
+    },
+    async listMessages(limit = 100) {
+      return messages.slice(-limit);
+    },
+  };
+}