create-volt 0.3.1 → 0.5.0

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

@@ -0,0 +1,120 @@
+// sql.js — shared SQL adapter for MySQL and Postgres. Lazy-loads the relevant
+// driver (mysql2 or pg) and normalizes the two differences that matter:
+//   • placeholders:  MySQL uses `?`,  Postgres uses `$1, $2, …`
+//   • query call:    mysql2 returns [rows],  pg returns { rows }
+
+export async function createSqlStore({ dialect, uri }) {
+  if (!uri) throw new Error(`DB_DRIVER=${dialect} requires a connection string (DATABASE_URL)`);
+
+  let run; // (sql, params) => Promise<rows[]>
+  if (dialect === "mysql") {
+    let mysql;
+    try {
+      mysql = (await import("mysql2/promise")).default;
+    } catch {
+      throw new Error("DB_DRIVER=mysql but 'mysql2' isn't installed. Run: npm install mysql2");
+    }
+    const pool = mysql.createPool(uri);
+    run = async (sql, params = []) => {
+      const [rows] = await pool.query(sql, params);
+      return rows;
+    };
+  } else {
+    let pg;
+    try {
+      pg = await import("pg");
+    } catch {
+      throw new Error("DB_DRIVER=postgres but 'pg' isn't installed. Run: npm install pg");
+    }
+    const pool = new pg.default.Pool({ connectionString: uri });
+    run = async (sql, params = []) => (await pool.query(sql, params)).rows;
+  }
+
+  // Placeholder for the i-th (1-based) parameter.
+  const ph = dialect === "mysql" ? () => "?" : (i) => `$${i}`;
+  const BOOL = dialect === "mysql" ? "TINYINT(1)" : "BOOLEAN";
+
+  return {
+    name: dialect,
+
+    async init() {
+      await run(
+        `CREATE TABLE IF NOT EXISTS login_tokens (
+           token VARCHAR(128) PRIMARY KEY,
+           email VARCHAR(320) NOT NULL,
+           ua TEXT,
+           expires_at BIGINT NOT NULL,
+           used ${BOOL} NOT NULL DEFAULT 0
+         )`,
+      );
+      await run(
+        `CREATE TABLE IF NOT EXISTS sessions (
+           id VARCHAR(128) PRIMARY KEY,
+           email VARCHAR(320) NOT NULL,
+           expires_at BIGINT NOT NULL
+         )`,
+      );
+      await run(
+        `CREATE TABLE IF NOT EXISTS messages (
+           id VARCHAR(64) PRIMARY KEY,
+           email VARCHAR(320) NOT NULL,
+           body TEXT NOT NULL,
+           created_at BIGINT NOT NULL
+         )`,
+      );
+    },
+
+    async putToken(t) {
+      await run(
+        `INSERT INTO login_tokens (token, email, ua, expires_at, used)
+         VALUES (${ph(1)}, ${ph(2)}, ${ph(3)}, ${ph(4)}, 0)`,
+        [t.token, t.email, t.ua, t.expiresAt],
+      );
+    },
+    async getToken(token) {
+      const rows = await run(`SELECT token, email, ua, expires_at, used FROM login_tokens WHERE token = ${ph(1)}`, [token]);
+      const r = rows[0];
+      if (!r) return null;
+      return { token: r.token, email: r.email, ua: r.ua, expiresAt: Number(r.expires_at), used: !!r.used };
+    },
+    async useToken(token) {
+      await run(`UPDATE login_tokens SET used = 1 WHERE token = ${ph(1)}`, [token]);
+    },
+
+    async putSession(s) {
+      await run(`INSERT INTO sessions (id, email, expires_at) VALUES (${ph(1)}, ${ph(2)}, ${ph(3)})`, [
+        s.id,
+        s.email,
+        s.expiresAt,
+      ]);
+    },
+    async getSession(id) {
+      const rows = await run(`SELECT id, email, expires_at FROM sessions WHERE id = ${ph(1)}`, [id]);
+      const r = rows[0];
+      if (!r) return null;
+      const s = { id: r.id, email: r.email, expiresAt: Number(r.expires_at) };
+      if (s.expiresAt < Date.now()) {
+        await this.delSession(id);
+        return null;
+      }
+      return s;
+    },
+    async delSession(id) {
+      await run(`DELETE FROM sessions WHERE id = ${ph(1)}`, [id]);
+    },
+
+    async addMessage(m) {
+      await run(`INSERT INTO messages (id, email, body, created_at) VALUES (${ph(1)}, ${ph(2)}, ${ph(3)}, ${ph(4)})`, [
+        m.id,
+        m.email,
+        m.body,
+        m.createdAt,
+      ]);
+      return m;
+    },
+    async listMessages(limit = 100) {
+      const rows = await run(`SELECT id, email, body, created_at FROM messages ORDER BY created_at ASC LIMIT ${Number(limit)}`);
+      return rows.map((r) => ({ id: r.id, email: r.email, body: r.body, createdAt: Number(r.created_at) }));
+    },
+  };
+}

package/templates/guestbook/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "volt-guestbook",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Live guestbook — a real Volt app: magic-link auth, Socket.io real-time, pluggable MongoDB/MySQL/Postgres storage (with an in-memory dev fallback).",
+  "type": "module",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node server.js"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "socket.io": "^4.7.5"
+  },
+  "optionalDependencies": {
+    "mongodb": "^6.8.0",
+    "mysql2": "^3.11.0",
+    "pg": "^8.12.0"
+  }
+}

package/templates/guestbook/public/app.js

@@ -0,0 +1,112 @@
+// app.js — the guestbook frontend, built with Volt signals. Renders the live
+// message list, the sign-in (magic-link) form, and the post box, all driven by
+// a handful of signals. New messages arrive over Socket.io and update in place.
+
+import { signal, computed, html, mount } from "/volt.js";
+
+// --- state ---
+const me = signal(null); // signed-in email, or null
+const messages = signal([]); // [{ id, email, body, createdAt }]
+const draft = signal(""); // post box
+const emailDraft = signal(""); // sign-in box
+const notice = signal(""); // status line
+
+const api = async (url, body) => {
+  const res = await fetch(url, {
+    method: body ? "POST" : "GET",
+    headers: body ? { "Content-Type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  return res.json();
+};
+
+const fmtWho = (email) => email.replace(/@.*/, ""); // show the local part only
+const fmtTime = (ts) => new Date(ts).toLocaleString();
+
+// --- actions ---
+async function sendLink() {
+  const email = emailDraft().trim();
+  if (!email) return;
+  notice("Sending…");
+  const r = await api("/api/login", { email });
+  notice(r.ok ? (r.dev ? "Magic link printed to the server console — open it to sign in." : `Magic link sent to ${email}.`) : r.error);
+}
+async function post() {
+  const body = draft().trim();
+  if (!body) return;
+  const r = await api("/api/messages", { body });
+  if (r.ok) draft("");
+  else notice(r.error);
+}
+async function logout() {
+  await api("/api/logout", {});
+  me(null);
+}
+
+// --- views ---
+const signIn = () =>
+  html`
+    <div class="card-x p-4 mb-4">
+      <h2 class="h6 mb-3">Sign in to post</h2>
+      <div class="input-group">
+        <input class="form-control" type="email" placeholder="you@example.com"
+               value=${emailDraft}
+               oninput=${(e) => emailDraft(e.target.value)}
+               onkeydown=${(e) => e.key === "Enter" && sendLink()} />
+        <button class="btn btn-primary" onclick=${sendLink}>Send magic link</button>
+      </div>
+    </div>`;
+
+const composer = () =>
+  html`
+    <div class="card-x p-4 mb-4">
+      <div class="d-flex justify-content-between align-items-center mb-2">
+        <span class="small text-muted">Signed in as <span class="who">${() => fmtWho(me())}</span></span>
+        <button class="btn btn-sm btn-outline-secondary" onclick=${logout}>Sign out</button>
+      </div>
+      <div class="input-group">
+        <input class="form-control" placeholder="Leave a message…"
+               value=${draft}
+               oninput=${(e) => draft(e.target.value)}
+               onkeydown=${(e) => e.key === "Enter" && post()} />
+        <button class="btn btn-primary" onclick=${post}>Post</button>
+      </div>
+    </div>`;
+
+const messageRow = (m) =>
+  html`
+    <div class="msg py-2">
+      <div class="d-flex justify-content-between">
+        <span class="who">${fmtWho(m.email)}</span>
+        <small class="text-muted">${fmtTime(m.createdAt)}</small>
+      </div>
+      <div>${m.body}</div>
+    </div>`;
+
+const board = () =>
+  html`
+    <div class="card-x p-4">
+      <h2 class="h6 mb-3">${computed(() => `${messages().length} message${messages().length === 1 ? "" : "s"}`)}</h2>
+      ${() => (messages().length ? messages().map(messageRow) : html`<p class="text-muted mb-0">No messages yet — be the first.</p>`)}
+    </div>`;
+
+mount(
+  "#app",
+  // sign-in box OR composer, depending on auth state
+  () => (me() ? composer() : signIn()),
+  () => (notice() ? html`<p class="small text-muted">${notice}</p>` : null),
+  board(),
+);
+
+// --- load + live updates ---
+async function boot() {
+  const [{ email }, { messages: list }] = await Promise.all([api("/api/me"), api("/api/messages")]);
+  me(email);
+  messages(list || []);
+
+  if (window.io) {
+    const socket = window.io();
+    socket.on("message:new", (m) => messages([...messages(), m]));
+  }
+}
+boot();

package/templates/guestbook/public/volt.js

@@ -0,0 +1,265 @@
+// volt.js — a tiny, no-build, signals-based UI library.
+//
+// Not React: there is no JSX, no virtual DOM, and no "re-render the whole
+// component" step. State lives in *signals*; reading a signal inside a piece of
+// UI subscribes that exact piece; writing the signal re-runs only those
+// subscribers and touches only the precise text node / attribute that changed.
+//
+// Two ways to author UI, same engine underneath:
+//   1. html``  — tagged-template markup with ${signal} holes
+//   2. el(...)  — imperative DOM helpers with function-children
+// They interoperate freely (drop an el() node into an html`` template, etc.).
+//
+// Public API: signal, computed, effect, el, html, mount.
+
+// ---------------------------------------------------------------------------
+// Reactive core (signals + effects with ownership-based disposal)
+// ---------------------------------------------------------------------------
+
+let activeEffect = null;
+
+// A signal is a function: call with no args to read, one arg to write.
+//   const n = signal(0);  n();      // read  → 0
+//                         n(n()+1); // write → notifies subscribers
+export function signal(value) {
+  const subs = new Set();
+  return function sig(...args) {
+    if (args.length) {
+      const next = args[0];
+      if (next === value) return value; // no-op on identical value
+      value = next;
+      for (const eff of [...subs]) eff.run(); // copy: run() mutates subs
+      return value;
+    }
+    if (activeEffect) {
+      subs.add(activeEffect);
+      activeEffect.deps.add(subs);
+    }
+    return value;
+  };
+}
+
+// effect(fn) runs fn now, tracks every signal it reads, and re-runs it whenever
+// any of those change. Effects created *inside* another effect are owned by it
+// and disposed before each re-run — so dynamic regions clean up after themselves.
+export function effect(fn) {
+  const eff = {
+    deps: new Set(),
+    children: new Set(),
+    parent: activeEffect,
+    run() {
+      disposeChildren(eff);
+      cleanupDeps(eff);
+      const prev = activeEffect;
+      activeEffect = eff;
+      try {
+        fn();
+      } finally {
+        activeEffect = prev;
+      }
+    },
+    dispose() {
+      disposeChildren(eff);
+      cleanupDeps(eff);
+      if (eff.parent) eff.parent.children.delete(eff);
+    },
+  };
+  if (activeEffect) activeEffect.children.add(eff);
+  eff.run();
+  return () => eff.dispose();
+}
+
+// computed(fn) is a read-only derived signal: () => value, auto-updating.
+export function computed(fn) {
+  const s = signal(undefined);
+  effect(() => s(fn()));
+  return () => s();
+}
+
+function cleanupDeps(eff) {
+  for (const subs of eff.deps) subs.delete(eff);
+  eff.deps.clear();
+}
+
+function disposeChildren(eff) {
+  for (const child of [...eff.children]) child.dispose();
+  eff.children.clear();
+}
+
+// ---------------------------------------------------------------------------
+// DOM helpers
+// ---------------------------------------------------------------------------
+
+// el(tag, props?, ...children) → a real DOM element.
+//   props: { onClick: fn }        → event listener
+//          { class: () => ... }   → reactive attribute (function = live)
+//          { id: 'x' }            → static attribute
+//   children: strings, numbers, nodes, arrays, or functions (functions = live)
+export function el(tag, props, ...children) {
+  const node = document.createElement(tag);
+  if (props) {
+    for (const [key, val] of Object.entries(props)) {
+      if (key.startsWith("on") && typeof val === "function") {
+        node.addEventListener(key.slice(2).toLowerCase(), val);
+      } else if (typeof val === "function") {
+        effect(() => setAttr(node, key, val()));
+      } else {
+        setAttr(node, key, val);
+      }
+    }
+  }
+  for (const child of children) appendChild(node, child);
+  return node;
+}
+
+// mount(target, ...children) appends children into target (selector or element).
+// Top-level function-children are reactive too.
+export function mount(target, ...children) {
+  const parent = typeof target === "string" ? document.querySelector(target) : target;
+  for (const child of children) appendChild(parent, child);
+  return parent;
+}
+
+function setAttr(node, name, value) {
+  if (name === "value") {
+    node.value = value ?? "";
+    return;
+  }
+  if (name === "checked" || name === "disabled" || name === "selected") {
+    node[name] = !!value && value !== "false";
+    return;
+  }
+  if (value === false || value == null) {
+    node.removeAttribute(name);
+    return;
+  }
+  node.setAttribute(name, value);
+}
+
+// Append a child, making function-children into self-updating dynamic regions
+// bounded by two comment anchors (so they can render text, nodes, or lists).
+function appendChild(parent, child) {
+  if (typeof child === "function") {
+    const start = document.createComment("");
+    const end = document.createComment("");
+    parent.appendChild(start);
+    parent.appendChild(end);
+    effect(() => renderRange(start, end, child()));
+    return;
+  }
+  for (const node of toNodes(child)) parent.appendChild(node);
+}
+
+// Replace everything between the start/end anchors with `value`'s nodes.
+function renderRange(start, end, value) {
+  let n = start.nextSibling;
+  while (n && n !== end) {
+    const t = n.nextSibling;
+    n.remove();
+    n = t;
+  }
+  for (const node of toNodes(value)) end.parentNode.insertBefore(node, end);
+}
+
+// Normalize any child value into an array of DOM nodes.
+function toNodes(value) {
+  if (value == null || value === false || value === true) return [];
+  if (Array.isArray(value)) return value.flatMap(toNodes);
+  if (value instanceof Node) return [value];
+  return [document.createTextNode(String(value))];
+}
+
+// ---------------------------------------------------------------------------
+// html`` template layer (parses once, wires holes to the same primitives)
+// ---------------------------------------------------------------------------
+
+const PH = (i) => `__voltph${i}__`;
+const PH_RE = /__voltph(\d+)__/g;
+
+// We're inside an open tag (attribute context) if the last '<' comes after the
+// last '>' in the accumulated string.
+function isAttrContext(str) {
+  return str.lastIndexOf("<") > str.lastIndexOf(">");
+}
+
+export function html(strings, ...values) {
+  let acc = "";
+  strings.forEach((str, i) => {
+    acc += str;
+    if (i < values.length) {
+      acc += isAttrContext(acc) ? PH(i) : `<!--${PH(i)}-->`;
+    }
+  });
+
+  const tpl = document.createElement("template");
+  tpl.innerHTML = acc.trim();
+
+  // Bind attribute holes.
+  for (const node of tpl.content.querySelectorAll("*")) {
+    for (const attr of [...node.attributes]) {
+      PH_RE.lastIndex = 0;
+      if (PH_RE.test(attr.value)) bindAttr(node, attr, values);
+    }
+  }
+
+  // Bind node holes (comment placeholders).
+  const walker = document.createTreeWalker(tpl.content, NodeFilter.SHOW_COMMENT);
+  const holes = [];
+  let c;
+  while ((c = walker.nextNode())) {
+    const m = c.data.match(/^__voltph(\d+)__$/);
+    if (m) holes.push([c, Number(m[1])]);
+  }
+  for (const [comment, i] of holes) bindNodeHole(comment, values[i]);
+
+  const nodes = [...tpl.content.childNodes];
+  return nodes.length === 1 ? nodes[0] : nodes;
+}
+
+function bindAttr(node, attr, values) {
+  const name = attr.name;
+  const raw = attr.value;
+  const single = raw.match(/^__voltph(\d+)__$/);
+  node.removeAttribute(name);
+
+  // onX=${fn} → event listener
+  if (name.startsWith("on") && single) {
+    node.addEventListener(name.slice(2).toLowerCase(), values[Number(single[1])]);
+    return;
+  }
+
+  // Otherwise a (possibly mixed) attribute value. If any hole is a function it
+  // is read inside the effect, so the attribute stays live.
+  effect(() => {
+    const text = raw.replace(PH_RE, (_, j) => {
+      const v = values[Number(j)];
+      return String(typeof v === "function" ? v() : v ?? "");
+    });
+    setAttr(node, name, text);
+  });
+}
+
+function bindNodeHole(comment, value) {
+  const start = document.createComment("");
+  comment.parentNode.insertBefore(start, comment); // `comment` becomes the end anchor
+  if (typeof value === "function") {
+    effect(() => renderRange(start, comment, value()));
+  } else {
+    renderRange(start, comment, value);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hot reload client — listens for the dev server's reload event over Socket.io
+// ---------------------------------------------------------------------------
+
+(function startHotReload() {
+  const connect = () => {
+    if (!window.io) return false;
+    const socket = window.io();
+    socket.on("volt:reload", () => location.reload());
+    console.log("[volt] hot reload connected");
+    return true;
+  };
+  if (!connect()) window.addEventListener("load", connect);
+})();

package/templates/guestbook/router.js

@@ -0,0 +1,110 @@
+// router.js — all HTTP routes for the guestbook. The index view is composed
+// with a server-side header include (per the house convention: the index file
+// pulls its header from an include defined here in the router).
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import {
+  requestLogin,
+  confirmLogin,
+  sessionFromReq,
+  SESSION_COOKIE,
+  cookieMaxAgeSeconds,
+} from "./lib/auth.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const viewsDir = path.join(__dirname, "views");
+
+// Render a view, expanding `<!--#include name-->` against views/partials/name.html.
+function render(name) {
+  let html = fs.readFileSync(path.join(viewsDir, name), "utf8");
+  return html.replace(/<!--#include\s+([\w-]+)-->/g, (_m, partial) => {
+    const file = path.join(viewsDir, "partials", `${partial}.html`);
+    return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  });
+}
+
+const baseUrl = (req) => `${req.protocol}://${req.get("host")}`;
+const setSessionCookie = (res, sid) =>
+  res.setHeader(
+    "Set-Cookie",
+    `${SESSION_COOKIE}=${encodeURIComponent(sid)}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${cookieMaxAgeSeconds}`,
+  );
+
+export function createRouter({ store, mailer, io }) {
+  const router = express.Router();
+  router.use(express.json());
+
+  // --- pages ---
+  router.get("/", (_req, res) => res.type("html").send(render("index.html")));
+  router.get("/verify", (req, res) => {
+    const token = String(req.query.token || "");
+    res.type("html").send(render("confirm.html").replaceAll("{{TOKEN}}", encodeURIComponent(token)));
+  });
+
+  // --- auth ---
+  router.post("/api/login", async (req, res) => {
+    try {
+      await requestLogin(store, mailer, {
+        email: req.body?.email,
+        ua: req.headers["user-agent"],
+        baseUrl: baseUrl(req),
+      });
+      res.json({ ok: true, sent: true, dev: mailer.name === "console" });
+    } catch (err) {
+      res.status(400).json({ ok: false, error: err.message });
+    }
+  });
+
+  router.post("/api/confirm", async (req, res) => {
+    try {
+      const { sessionId, email } = await confirmLogin(store, {
+        token: req.body?.token,
+        ua: req.headers["user-agent"],
+      });
+      setSessionCookie(res, sessionId);
+      res.json({ ok: true, email });
+    } catch (err) {
+      res.status(400).json({ ok: false, error: err.message });
+    }
+  });
+
+  router.post("/api/logout", async (req, res) => {
+    const session = await sessionFromReq(store, req);
+    if (session) await store.delSession(session.id);
+    res.setHeader("Set-Cookie", `${SESSION_COOKIE}=; HttpOnly; Path=/; Max-Age=0`);
+    res.json({ ok: true });
+  });
+
+  router.get("/api/me", async (req, res) => {
+    const session = await sessionFromReq(store, req);
+    res.json({ email: session?.email || null });
+  });
+
+  // --- messages ---
+  router.get("/api/messages", async (_req, res) => {
+    res.json({ messages: await store.listMessages(100) });
+  });
+
+  router.post("/api/messages", async (req, res) => {
+    const session = await sessionFromReq(store, req);
+    if (!session) return res.status(401).json({ ok: false, error: "Sign in to post." });
+    const body = String(req.body?.body || "").trim();
+    if (!body) return res.status(400).json({ ok: false, error: "Message is empty." });
+    if (body.length > 500) return res.status(400).json({ ok: false, error: "Message too long (max 500)." });
+
+    const message = await store.addMessage({
+      id: crypto.randomBytes(8).toString("hex"),
+      email: session.email,
+      body,
+      createdAt: Date.now(),
+    });
+    io.emit("message:new", message); // push to every open page
+    res.json({ ok: true, message });
+  });
+
+  return router;
+}

package/templates/guestbook/server.js

@@ -0,0 +1,36 @@
+// server.js — guestbook dev/prod server. Express serves the static client and
+// the views; Socket.io pushes new messages live; storage is pluggable
+// (memory | mongodb | mysql | postgres) via the DB_DRIVER env var.
+//
+//   npm run dev                         # in-memory store, magic links to console
+//   DB_DRIVER=postgres DATABASE_URL=... npm start
+//
+// Run under PM2 in production:  pm2 start server.js --name guestbook ; pm2 log
+
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import { Server as SocketServer } from "socket.io";
+import { createStore } from "./lib/store.js";
+import { createMailer } from "./lib/mailer.js";
+import { createRouter } from "./router.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PORT = Number(process.env.PORT) || 26629;
+
+const store = await createStore();
+const mailer = await createMailer();
+
+const app = express();
+app.use(express.static(path.join(__dirname, "public")));
+
+const server = http.createServer(app);
+const io = new SocketServer(server);
+
+app.use("/", createRouter({ store, mailer, io }));
+
+server.listen(PORT, () => {
+  console.log(`📖 Guestbook → http://localhost:${PORT}`);
+  console.log(`   storage: ${store.name}   mail: ${mailer.name}`);
+});