create-volt 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `create-volt` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.16.0] - 2026-06-29
+
+### Added
+- **`media` add-on** — file uploads with a swappable storage driver: `local`
+  (disk, served at `/media`) or `s3` (any S3-compatible store: AWS S3,
+  DigitalOcean Spaces, …). `POST /api/media` is auth-gated (depends on the auth
+  add-on); uploads are size-capped (`MEDIA_MAX_MB`, default 10), restricted to
+  raster images + PDF (SVG rejected), stored under a random key, and returned as
+  a public URL. Driver + S3 settings are configured in the setup wizard. Pulls in
+  `busboy` (and `@aws-sdk/client-s3` when `MEDIA_DRIVER=s3`), both tracked by the
+  dependency auto-updater and exercised by the smoke gate.
+
+## [0.15.1] - 2026-06-29
+
+### Fixed
+- `volt.js` no longer touches `window` at import time — the hot-reload client is
+  guarded with `typeof window`, so the library is safe to import in Node (SSR,
+  tests), not just the browser.
+
+### Changed
+- The `pages` add-on imports `express`/`marked` lazily (only when mounted), so
+  its pure helpers load without those packages present.
+
+### Added (repo tooling — not shipped in scaffolded apps)
+- A `node --test` unit suite (reactive core, memory store, pages helpers), a
+  `smoke` script (scaffold → install → boot → hit endpoints), a CI workflow, and
+  a smoke-test **gate** on the dependency auto-updater: a version bump is
+  committed only if unit tests + smoke pass on the bumped versions.
+
 ## [0.15.0] - 2026-06-28
 
 ### Added
@@ -213,6 +242,8 @@ All notable changes to `create-volt` are documented here. The format follows
   watching and full-page hot reload. Supports `--skip-install` and `--force`,
   and auto-detects npm / pnpm / yarn / bun for the install step.
 
+[0.16.0]: https://github.com/MIR-2025/volt/releases/tag/v0.16.0
+[0.15.1]: https://github.com/MIR-2025/volt/releases/tag/v0.15.1
 [0.15.0]: https://github.com/MIR-2025/volt/releases/tag/v0.15.0
 [0.14.0]: https://github.com/MIR-2025/volt/releases/tag/v0.14.0
 [0.13.0]: https://github.com/MIR-2025/volt/releases/tag/v0.13.0

package/addons/media/files/lib/media.js

@@ -0,0 +1,99 @@
+// media.js — media uploads with a swappable storage driver: `local` (disk,
+// served at /media) or `s3` (any S3-compatible store: AWS S3, DigitalOcean
+// Spaces, etc.). POST /api/media is auth-gated; objects are stored under a
+// random key and a public URL is returned. express/busboy/aws-sdk are imported
+// lazily so the pure helpers below load without those deps installed.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+// allowlist — raster images + PDF (no SVG: it can carry script). Extend via code.
+const ALLOWED = { "image/jpeg": "jpg", "image/png": "png", "image/gif": "gif", "image/webp": "webp", "image/avif": "avif", "application/pdf": "pdf" };
+export const extFor = (mime) => ALLOWED[mime] || null;
+export const isAllowed = (mime) => !!ALLOWED[mime];
+export const genKey = (mime) => `${crypto.randomBytes(10).toString("hex")}.${extFor(mime)}`;
+
+function localDriver({ dir }) {
+  fs.mkdirSync(dir, { recursive: true });
+  return {
+    name: "local",
+    async put(key, buf) {
+      fs.writeFileSync(path.join(dir, key), buf);
+      return `/media/${key}`;
+    },
+  };
+}
+
+async function s3Driver(env) {
+  const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
+  const endpoint = (env.S3_ENDPOINT || "").replace(/\/$/, "");
+  const bucket = env.S3_BUCKET;
+  const client = new S3Client({
+    endpoint: endpoint || undefined,
+    region: env.S3_REGION || "us-east-1",
+    credentials: { accessKeyId: env.S3_KEY, secretAccessKey: env.S3_SECRET },
+    forcePathStyle: true, // safest across S3-compatible endpoints (e.g. Spaces)
+  });
+  const base = (env.S3_PUBLIC_BASE || (endpoint ? `${endpoint}/${bucket}` : "")).replace(/\/$/, "");
+  return {
+    name: "s3",
+    async put(key, buf, mime) {
+      await client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: buf, ContentType: mime, ACL: "public-read" }));
+      return `${base}/${key}`;
+    },
+  };
+}
+
+export async function mediaRouter({ requireAuth, dir, env = process.env }) {
+  const express = (await import("express")).default;
+  const busboy = (await import("busboy")).default;
+  const driver = env.MEDIA_DRIVER === "s3" ? await s3Driver(env) : localDriver({ dir });
+  const maxMb = Number(env.MEDIA_MAX_MB) || 10;
+  const r = express.Router();
+
+  if (driver.name === "local") r.use("/media", express.static(dir)); // public reads
+
+  r.post("/api/media", requireAuth, (req, res) => {
+    let bb;
+    try {
+      bb = busboy({ headers: req.headers, limits: { files: 1, fileSize: maxMb * 1024 * 1024 } });
+    } catch {
+      return res.status(400).json({ ok: false, error: "bad upload" });
+    }
+    let done = false;
+    const finish = (code, body) => {
+      if (!done) {
+        done = true;
+        res.status(code).json(body);
+      }
+    };
+    bb.on("file", (_name, stream, info) => {
+      if (!isAllowed(info.mimeType)) {
+        stream.resume();
+        return finish(415, { ok: false, error: "unsupported file type" });
+      }
+      const chunks = [];
+      let tooBig = false;
+      stream.on("data", (c) => chunks.push(c));
+      stream.on("limit", () => {
+        tooBig = true;
+        finish(413, { ok: false, error: `file exceeds ${maxMb}MB` });
+      });
+      stream.on("end", async () => {
+        if (tooBig || done) return;
+        try {
+          const key = genKey(info.mimeType);
+          const url = await driver.put(key, Buffer.concat(chunks), info.mimeType);
+          finish(200, { ok: true, url, key, driver: driver.name });
+        } catch (e) {
+          finish(500, { ok: false, error: e.message });
+        }
+      });
+    });
+    bb.on("error", () => finish(500, { ok: false, error: "upload failed" }));
+    bb.on("close", () => finish(400, { ok: false, error: "no file uploaded" }));
+    req.pipe(bb);
+  });
+
+  return r;
+}

package/addons/media/meta.json

@@ -0,0 +1,8 @@
+{
+  "description": "Media uploads to local disk or any S3-compatible store (AWS S3, DigitalOcean Spaces, etc.). POST /api/media (signed-in only) returns a public URL. Choose the driver in the wizard.",
+  "dependsOn": ["auth"],
+  "sentinel": "lib/media.js",
+  "install": ["busboy"],
+  "optional": { "s3": ["@aws-sdk/client-s3"] },
+  "wiring": "Set MEDIA_DRIVER=local|s3. For s3 set S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_KEY, S3_SECRET (and optionally S3_PUBLIC_BASE for a CDN URL). Uploads require a signed-in user; uploaded objects are public-read."
+}

package/addons/pages/files/lib/pages.js

@@ -3,8 +3,8 @@
 // Pages are code-owned files (trusted), so their markdown HTML is served as-is.
 import fs from "node:fs";
 import path from "node:path";
-import express from "express";
-import { marked } from "marked";
+// express + marked are imported lazily in pagesRouter() so this module's pure
+// helpers (parseFrontMatter, isSafeSlug) load without those deps installed.
 
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
 
@@ -36,7 +36,7 @@ function ensure(dir) {
 }
 
 const FM = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
-function parse(src) {
+export function parseFrontMatter(src) {
   const m = src.match(FM);
   if (!m) return { meta: {}, body: src };
   const meta = {};
@@ -47,6 +47,9 @@ function parse(src) {
   return { meta, body: src.slice(m[0].length) };
 }
 
+// slugs are restricted to a safe charset — no dots/slashes → no path traversal
+export const isSafeSlug = (s) => /^[a-z0-9][a-z0-9-]*$/i.test(s);
+
 function shell(title, inner) {
   return `<!doctype html><html lang="en"><head><meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -64,15 +67,17 @@ table { border-collapse: collapse } td, th { border: 1px solid #ccc; padding: .4
 </style></head><body>${inner}</body></html>`;
 }
 
-export function pagesRouter({ dir }) {
+export async function pagesRouter({ dir }) {
+  const express = (await import("express")).default;
+  const { marked } = await import("marked");
   ensure(dir);
   const r = express.Router();
   r.get("/:slug", (req, res, next) => {
     const slug = req.params.slug;
-    if (!/^[a-z0-9][a-z0-9-]*$/i.test(slug)) return next(); // safe slug only — no traversal
+    if (!isSafeSlug(slug)) return next(); // safe slug only — no traversal
     const file = path.join(dir, slug + ".md");
     if (!fs.existsSync(file)) return next();
-    const { meta, body } = parse(fs.readFileSync(file, "utf8"));
+    const { meta, body } = parseFrontMatter(fs.readFileSync(file, "utf8"));
     res.type("html").send(shell(meta.title || slug, marked.parse(body)));
   });
   return r;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {

package/templates/default/public/volt.js

@@ -254,6 +254,7 @@ function bindNodeHole(comment, value) {
 // ---------------------------------------------------------------------------
 
 (function startHotReload() {
+  if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
   const connect = () => {
     if (!window.io) return false;
     const socket = window.io();

package/templates/default/server.js

@@ -21,8 +21,8 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
-const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js" };
+const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", media: "media.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -111,8 +111,14 @@ async function startApp() {
 
   app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
 
+  // media uploads (POST /api/media, auth-gated; local files served at /media)
+  if (enabled.has("media") && store) {
+    const requireAuth = (await addonMod("auth")).requireAuth(store);
+    app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
+  }
+
   // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
-  if (enabled.has("pages")) app.use((await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
+  if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
   const server = http.createServer(app);
   const io = new SocketServer(server);
@@ -160,6 +166,8 @@ function neededPackages(env) {
   if (driver === "postgres") want.push("pg");
   if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
   if (/^\s*VOLT_ADDONS\s*=.*\bpages\b/m.test(env)) want.push("marked");
+  if (/^\s*VOLT_ADDONS\s*=.*\bmedia\b/m.test(env)) want.push("busboy");
+  if (/^\s*MEDIA_DRIVER\s*=\s*s3\b/m.test(env)) want.push("@aws-sdk/client-s3");
   return want.filter((p) => !deps[p]);
 }
 

package/templates/default/setup/setup.js

@@ -17,6 +17,13 @@ const state = signal({
   dbUrl: current.DATABASE_URL || "",
   smtpUrl: current.SMTP_URL || "",
   mailFrom: current.MAIL_FROM || "",
+  mediaDriver: current.MEDIA_DRIVER || "local",
+  s3Endpoint: current.S3_ENDPOINT || "",
+  s3Region: current.S3_REGION || "",
+  s3Bucket: current.S3_BUCKET || "",
+  s3Key: current.S3_KEY || "",
+  s3Secret: current.S3_SECRET || "",
+  s3PublicBase: current.S3_PUBLIC_BASE || "",
   port: current.PORT || String(defaultPort),
 });
 const set = (patch) => state({ ...state(), ...patch });
@@ -53,6 +60,17 @@ function genEnv(s) {
     else out.push("# SMTP_URL=        # unset → emails print to the console");
     if (s.mailFrom) out.push(`MAIL_FROM=${clean(s.mailFrom)}`);
   }
+  if (eff.includes("media")) {
+    out.push(`MEDIA_DRIVER=${clean(s.mediaDriver)}`);
+    if (s.mediaDriver === "s3") {
+      out.push(`S3_ENDPOINT=${clean(s.s3Endpoint)}`);
+      out.push(`S3_REGION=${clean(s.s3Region)}`);
+      out.push(`S3_BUCKET=${clean(s.s3Bucket)}`);
+      out.push(`S3_KEY=${clean(s.s3Key)}`);
+      out.push(`S3_SECRET=${clean(s.s3Secret)}`);
+      if (s.s3PublicBase) out.push(`S3_PUBLIC_BASE=${clean(s.s3PublicBase)}`);
+    }
+  }
   return out.join("\n") + "\n";
 }
 const env = computed(() => genEnv(state()));
@@ -134,6 +152,19 @@ const dbSettings = () =>
           : null}
     ${() => (state().dbDriver !== "memory" ? html`<button class="btn btn-sm btn-outline-secondary mb-2" onclick=${testDb}>Test connection</button>` : null)}`;
 
+const mediaSettings = () =>
+  html`<div class="mb-2">
+      <label class="form-label small mb-1">Media storage (MEDIA_DRIVER)</label>
+      <select class="form-select" value=${() => state().mediaDriver} onchange=${(e) => set({ mediaDriver: e.target.value })}>
+        <option value="local">local (disk)</option>
+        <option value="s3">s3 — AWS S3 / DigitalOcean Spaces</option>
+      </select>
+    </div>
+    ${() =>
+      state().mediaDriver === "s3"
+        ? html`${field("S3_ENDPOINT", "s3Endpoint", "https://nyc3.digitaloceanspaces.com")}${field("S3_REGION", "s3Region", "us-east-1")}${field("S3_BUCKET", "s3Bucket", "my-space")}${field("S3_KEY", "s3Key", "access key")}${field("S3_SECRET", "s3Secret", "secret key")}${field("S3_PUBLIC_BASE (optional CDN base)", "s3PublicBase", "https://cdn.example.com")}`
+        : null}`;
+
 mount(
   "#app",
   available.length
@@ -148,6 +179,7 @@ mount(
     ${field("PORT", "port", String(defaultPort))}
     ${() => (eff().includes("db") ? dbSettings() : null)}
     ${() => (eff().includes("mailer") ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+    ${() => (eff().includes("media") ? mediaSettings() : null)}
   </div>`,
   html`<div class="card-x p-4 mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">

package/templates/guestbook/public/volt.js

@@ -254,6 +254,7 @@ function bindNodeHole(comment, value) {
 // ---------------------------------------------------------------------------
 
 (function startHotReload() {
+  if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
   const connect = () => {
     if (!window.io) return false;
     const socket = window.io();

package/templates/starter/public/volt.js

@@ -254,6 +254,7 @@ function bindNodeHole(comment, value) {
 // ---------------------------------------------------------------------------
 
 (function startHotReload() {
+  if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
   const connect = () => {
     if (!window.io) return false;
     const socket = window.io();

package/templates/starter/server.js

@@ -22,8 +22,8 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
-const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js" };
+const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", media: "media.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -137,8 +137,14 @@ async function startApp() {
 
   app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
 
+  // media uploads (POST /api/media, auth-gated; local files served at /media)
+  if (enabled.has("media") && store) {
+    const requireAuth = (await addonMod("auth")).requireAuth(store);
+    app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
+  }
+
   // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
-  if (enabled.has("pages")) app.use((await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
+  if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
   const server = http.createServer(app);
   const io = new SocketServer(server);
@@ -186,6 +192,8 @@ function neededPackages(env) {
   if (driver === "postgres") want.push("pg");
   if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
   if (/^\s*VOLT_ADDONS\s*=.*\bpages\b/m.test(env)) want.push("marked");
+  if (/^\s*VOLT_ADDONS\s*=.*\bmedia\b/m.test(env)) want.push("busboy");
+  if (/^\s*MEDIA_DRIVER\s*=\s*s3\b/m.test(env)) want.push("@aws-sdk/client-s3");
   return want.filter((p) => !deps[p]);
 }
 

package/templates/starter/setup/setup.js

@@ -17,6 +17,13 @@ const state = signal({
   dbUrl: current.DATABASE_URL || "",
   smtpUrl: current.SMTP_URL || "",
   mailFrom: current.MAIL_FROM || "",
+  mediaDriver: current.MEDIA_DRIVER || "local",
+  s3Endpoint: current.S3_ENDPOINT || "",
+  s3Region: current.S3_REGION || "",
+  s3Bucket: current.S3_BUCKET || "",
+  s3Key: current.S3_KEY || "",
+  s3Secret: current.S3_SECRET || "",
+  s3PublicBase: current.S3_PUBLIC_BASE || "",
   port: current.PORT || String(defaultPort),
 });
 const set = (patch) => state({ ...state(), ...patch });
@@ -53,6 +60,17 @@ function genEnv(s) {
     else out.push("# SMTP_URL=        # unset → emails print to the console");
     if (s.mailFrom) out.push(`MAIL_FROM=${clean(s.mailFrom)}`);
   }
+  if (eff.includes("media")) {
+    out.push(`MEDIA_DRIVER=${clean(s.mediaDriver)}`);
+    if (s.mediaDriver === "s3") {
+      out.push(`S3_ENDPOINT=${clean(s.s3Endpoint)}`);
+      out.push(`S3_REGION=${clean(s.s3Region)}`);
+      out.push(`S3_BUCKET=${clean(s.s3Bucket)}`);
+      out.push(`S3_KEY=${clean(s.s3Key)}`);
+      out.push(`S3_SECRET=${clean(s.s3Secret)}`);
+      if (s.s3PublicBase) out.push(`S3_PUBLIC_BASE=${clean(s.s3PublicBase)}`);
+    }
+  }
   return out.join("\n") + "\n";
 }
 const env = computed(() => genEnv(state()));
@@ -134,6 +152,19 @@ const dbSettings = () =>
           : null}
     ${() => (state().dbDriver !== "memory" ? html`<button class="btn btn-sm btn-outline-secondary mb-2" onclick=${testDb}>Test connection</button>` : null)}`;
 
+const mediaSettings = () =>
+  html`<div class="mb-2">
+      <label class="form-label small mb-1">Media storage (MEDIA_DRIVER)</label>
+      <select class="form-select" value=${() => state().mediaDriver} onchange=${(e) => set({ mediaDriver: e.target.value })}>
+        <option value="local">local (disk)</option>
+        <option value="s3">s3 — AWS S3 / DigitalOcean Spaces</option>
+      </select>
+    </div>
+    ${() =>
+      state().mediaDriver === "s3"
+        ? html`${field("S3_ENDPOINT", "s3Endpoint", "https://nyc3.digitaloceanspaces.com")}${field("S3_REGION", "s3Region", "us-east-1")}${field("S3_BUCKET", "s3Bucket", "my-space")}${field("S3_KEY", "s3Key", "access key")}${field("S3_SECRET", "s3Secret", "secret key")}${field("S3_PUBLIC_BASE (optional CDN base)", "s3PublicBase", "https://cdn.example.com")}`
+        : null}`;
+
 mount(
   "#app",
   available.length
@@ -148,6 +179,7 @@ mount(
     ${field("PORT", "port", String(defaultPort))}
     ${() => (eff().includes("db") ? dbSettings() : null)}
     ${() => (eff().includes("mailer") ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+    ${() => (eff().includes("media") ? mediaSettings() : null)}
   </div>`,
   html`<div class="card-x p-4 mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">