create-volt 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.9.0] - 2026-06-28
+
+### Changed
+- The setup wizard is now the single place to configure an app, and it shows
+  **all** add-ons: tick db/auth/realtime/mailer + fill their settings. Enabling
+  is pure config — **Apply writes `.env`** (a `VOLT_ADDONS` list + settings) and
+  **adds any needed packages to `package.json` + runs `npm install`**, then
+  starts the app, which **auto-wires** whatever `.env` enables (auth routes,
+  realtime sockets, db). Add-on code ships bundled under `.volt/addons`; nothing
+  is copied into your `lib/`.
+- `create-volt config` now just opens that in-app wizard (`server.js --edit`) —
+  one implementation, localhost-only (shell/SSH access is the auth).
+
+### Removed
+- The standalone create-volt config page and its `--host`/key flags (superseded
+  by the in-app wizard, which is localhost-only + SSH-tunnel for remote).
+
+### Note
+- Backend of an enabled add-on is wired automatically; the frontend UI (login
+  form, chat) is yours to build — or start from `--template guestbook`.
+
 ## [0.8.0] - 2026-06-28
 
 ### Added
@@ -108,6 +129,7 @@ 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.9.0]: https://github.com/MIR-2025/volt/releases/tag/v0.9.0
 [0.8.0]: https://github.com/MIR-2025/volt/releases/tag/v0.8.0
 [0.7.0]: https://github.com/MIR-2025/volt/releases/tag/v0.7.0
 [0.6.0]: https://github.com/MIR-2025/volt/releases/tag/v0.6.0

package/README.md

@@ -42,27 +42,29 @@ Edit `public/app.js` and save — the page hot-reloads itself.
 
 ## Add-on integrations
 
-Layer features into an existing app from a disposable local page — pick the
-add-ons, fill in their settings, and it copies the files **and** writes your
-`.env`. Run from the app directory:
+Apps ship with the add-ons **bundled** (under `.volt/addons`) but off. The
+**setup wizard** turns them on — it opens on first run, or anytime with:
 
 ```bash
-npx create-volt@latest config
+npm run dev -- --edit      # or: npx create-volt config
 ```
 
-It prints a `localhost` link (plus LAN links and an SSH-tunnel hint for remote
-boxes), key-gated for safety. Available add-ons:
+Tick the features you want, fill in their settings, and **Apply**. Enabling is
+pure config: it writes `.env` (a `VOLT_ADDONS` list + settings) and adds any
+needed packages to `package.json` + runs `npm install`. The app then auto-wires
+whatever's enabled. Available add-ons:
 
 | Add-on     | What it gives you                                                    |
 | ---------- | ------------------------------------------------------------------- |
 | `db`       | document store: memory / MongoDB / MySQL / Postgres, one interface  |
 | `mailer`   | console (dev) / SMTP (prod) email                                   |
-| `auth`     | magic-link login + sessions (uses db + mailer)                      |
-| `realtime` | Socket.io chat: rooms, presence, typing (uses db)                  |
+| `auth`     | magic-link login + sessions (pulls in db + mailer)                  |
+| `realtime` | Socket.io chat: rooms, presence, typing (pulls in db)              |
 
-Tick **All** to add the whole stack at once. The page only writes into the
-current folder, applies once, and disappears when you Ctrl-C it. Afterwards run
-your app with `node --env-file=.env server.js`.
+The wizard is localhost-only (shell/SSH access is the auth; it prints an
+SSH-tunnel hint on a remote box). Enabling an add-on wires its **backend**
+automatically — the **frontend** UI (login form, chat) is yours to build, or
+start from `--template guestbook`, which has it wired end-to-end.
 
 ## Updating Volt
 

package/index.js

@@ -10,9 +10,6 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import http from "node:http";
-import os from "node:os";
-import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
@@ -38,7 +35,7 @@ ${bold("Usage")}
   npm create volt@latest <project-directory> [options]
   npx create-volt <project-directory> [options]
   npx create-volt@latest update              # refresh public/volt.js in an existing app
-  npx create-volt@latest config              # disposable page: add db/auth/realtime/mailer + write .env
+  npx create-volt@latest config              # open the app's setup wizard (edit add-ons + settings)
 
 ${bold("Options")}
   --template <name>  Starter template: default | guestbook  (default: default)
@@ -63,15 +60,12 @@ const flags = new Set();
 const positionals = [];
 let portArg = null;
 let templateArg = null;
-let hostArg = null;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === "--port") portArg = argv[++i];
   else if (a.startsWith("--port=")) portArg = a.slice("--port=".length);
   else if (a === "--template") templateArg = argv[++i];
   else if (a.startsWith("--template=")) templateArg = a.slice("--template=".length);
-  else if (a === "--host") hostArg = argv[++i];
-  else if (a.startsWith("--host=")) hostArg = a.slice("--host=".length);
   else if (a.startsWith("-")) flags.add(a);
   else positionals.push(a);
 }
@@ -121,163 +115,20 @@ if (positionals[0] === "update") {
   process.exit(0);
 }
 
-// --- `config` subcommand: a disposable local page to configure add-ons and
-// write a .env. Dependency-free (node:http); the page is built with Volt. ---
+// --- `config` subcommand: open the app's setup wizard to edit add-ons/settings.
+// One implementation — delegates to the in-app wizard via `server.js --edit`. ---
 if (positionals[0] === "config") {
   const cwd = process.cwd();
-  const addonsDir = path.join(__dirname, "addons");
-  const addonList = fs
-    .readdirSync(addonsDir, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
-    .map((e) => {
-      const m = JSON.parse(fs.readFileSync(path.join(addonsDir, e.name, "meta.json"), "utf8"));
-      return {
-        name: e.name,
-        description: m.description,
-        install: m.install || [],
-        dependsOn: m.dependsOn || [],
-        wiring: m.wiring,
-        installed: fs.existsSync(path.join(cwd, m.sentinel)),
-      };
-    });
-  const assets = {
-    "/config-app.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "config", "config-app.js"))],
-    "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "templates", "default", "public", "volt.js"))],
-  };
-  const indexHtml = fs.readFileSync(path.join(__dirname, "config", "index.html"));
-  // localhost by default — shell/SSH access is the auth. --host exposes it on the
-  // network, and only then do we mint a random key to gate it.
-  const host = hostArg || "127.0.0.1";
-  const exposed = host !== "127.0.0.1" && host !== "localhost";
-  const key = exposed ? crypto.randomBytes(12).toString("hex") : null;
-
-  const server = http.createServer((req, res) => {
-    const u = new URL(req.url, "http://localhost");
-    const p = u.pathname;
-    if (req.method === "GET" && p === "/") {
-      if (key && u.searchParams.get("key") !== key) {
-        res.statusCode = 403;
-        return res.end("Forbidden — open the ?key=… link printed in the terminal.");
-      }
-      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 === "/addons.json") {
-      res.setHeader("Content-Type", "application/json");
-      return res.end(JSON.stringify(addonList));
-    }
-    if (req.method === "GET" && p === "/current.json") {
-      const current = {};
-      const envPath = path.join(cwd, ".env");
-      if (fs.existsSync(envPath)) {
-        for (const line of fs.readFileSync(envPath, "utf8").split("\n")) {
-          const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.*?)\s*$/);
-          if (m) current[m[1]] = m[2];
-        }
-      }
-      res.setHeader("Content-Type", "application/json");
-      return res.end(JSON.stringify(current));
-    }
-    if (req.method === "POST" && p === "/apply") {
-      if (key && req.headers["x-config-key"] !== key) {
-        res.statusCode = 403;
-        return res.end(JSON.stringify({ ok: false, error: "bad or missing key" }));
-      }
-      let body = "";
-      req.on("data", (c) => (body += c));
-      req.on("end", () => {
-        try {
-          const { addons = [], env } = JSON.parse(body);
-          const valid = new Set(addonList.map((a) => a.name));
-          const depsOf = Object.fromEntries(addonList.map((a) => [a.name, a.dependsOn]));
-          // expand selection to include required dependencies (deps before dependents)
-          const want = [];
-          const seen = new Set();
-          const visit = (n) => {
-            if (!valid.has(n) || seen.has(n)) return;
-            seen.add(n);
-            for (const d of depsOf[n] || []) visit(d);
-            want.push(n);
-          };
-          for (const n of addons) visit(n);
-
-          const copied = [];
-          const skipped = [];
-          for (const n of want) {
-            const filesDir = path.join(addonsDir, n, "files");
-            for (const f of listTemplateFiles(filesDir)) {
-              const dest = path.join(cwd, f);
-              if (fs.existsSync(dest)) {
-                skipped.push(f);
-                continue;
-              }
-              fs.mkdirSync(path.dirname(dest), { recursive: true });
-              fs.copyFileSync(path.join(filesDir, f), dest);
-              copied.push(f);
-            }
-          }
-          if (typeof env === "string") {
-            // preserve any custom keys already in .env that this form doesn't manage
-            const envPath = path.join(cwd, ".env");
-            let finalEnv = env;
-            if (fs.existsSync(envPath)) {
-              const managed = new Set([...env.matchAll(/^\s*([A-Za-z0-9_]+)\s*=/gm)].map((m) => m[1]));
-              const extra = fs
-                .readFileSync(envPath, "utf8")
-                .split("\n")
-                .filter((line) => {
-                  const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=/);
-                  return m && !managed.has(m[1]);
-                });
-              if (extra.length) finalEnv = env.replace(/\n*$/, "\n") + extra.join("\n") + "\n";
-            }
-            fs.writeFileSync(envPath, finalEnv);
-          }
-          console.log(`${green("✔")} applied [${want.join(", ")}] — ${copied.length} file(s) copied, .env written`);
-          res.setHeader("Content-Type", "application/json");
-          res.end(JSON.stringify({ ok: true, copied, skipped, applied: want }));
-        } catch (e) {
-          res.statusCode = 400;
-          res.end(JSON.stringify({ ok: false, error: e.message }));
-        }
-      });
-      return;
-    }
-    res.statusCode = 404;
-    res.end("not found");
-  });
-
-  const wanted = portArg ? Number(portArg) : 0;
-  server.listen(Number.isInteger(wanted) && wanted > 0 ? wanted : 0, host, () => {
-    const port = server.address().port;
-    const q = key ? `/?key=${key}` : "/";
-    console.log(`\n${bold("⚡ create-volt config")} — add-ons for ${dim(cwd)}\n`);
-    if (exposed) {
-      const lan = [];
-      for (const iface of Object.values(os.networkInterfaces())) {
-        for (const a of iface || []) if (a.family === "IPv4" && !a.internal) lan.push(a.address);
-      }
-      console.log("  Open (key-gated, reachable on your network):");
-      for (const ip of lan) console.log("    " + cyan(`http://${ip}:${port}${q}`));
-      console.log("    " + cyan(`http://localhost:${port}${q}`) + dim("   (this box)"));
-    } else {
-      const url = `http://localhost:${port}${q}`;
-      console.log("  Open: " + cyan(url));
-      const ssh = process.env.SSH_CONNECTION; // "clientIP clientPort serverIP serverPort"
-      const user = process.env.USER || process.env.USERNAME || "you";
-      const sshHost = ssh ? ssh.split(" ")[2] : os.hostname();
-      console.log(`  ${dim(ssh ? "Remote box — the server is up here; from your LOCAL machine run:" : "Remote box? from your local machine run:")}`);
-      console.log("    " + dim(`ssh -N -L 127.0.0.1:${port}:localhost:${port} ${user}@${sshHost}`));
-      console.log(`  ${dim(`…then open ${url} on your machine — shell access is the auth.`)}`);
-      console.log(`  ${dim("(LAN access instead: --host 0.0.0.0 — adds a key)")}`);
-    }
-    console.log(`\n  ${dim("Applies add-ons + writes .env here · Ctrl-C when done (disposable).")}\n`);
+  if (!fs.existsSync(path.join(cwd, "server.js"))) {
+    die(`No ${cyan("server.js")} here — run ${cyan("create-volt config")} from inside a Volt app.`);
+  }
+  if (portArg) process.env.PORT = String(Number(portArg) || "");
+  const res = spawnSync(process.execPath, ["server.js", "--edit"], {
+    cwd,
+    stdio: "inherit",
+    env: flags.has("--no-open") ? { ...process.env, VOLT_NO_OPEN: "1" } : process.env,
   });
-  await new Promise(() => {}); // keep the server up; never fall through to scaffolding
+  process.exit(res.status ?? 0);
 }
 
 // Resolve the dev port: --port wins, else derive it from today's date as
@@ -379,6 +230,12 @@ if (fs.existsSync(shippedGitignore)) {
   fs.renameSync(shippedGitignore, path.join(targetDir, ".gitignore"));
 }
 
+// Bundle the add-on sources so the app's setup wizard can enable them later
+// (only for templates that ship the wizard, i.e. have a setup/ dir).
+if (fs.existsSync(path.join(targetDir, "setup"))) {
+  fs.cpSync(path.join(__dirname, "addons"), path.join(targetDir, ".volt", "addons"), { recursive: true });
+}
+
 // --- stamp the project name into package.json ---
 const appPkgPath = path.join(targetDir, "package.json");
 const appPkg = JSON.parse(fs.readFileSync(appPkgPath, "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {
@@ -10,7 +10,6 @@
     "index.js",
     "templates",
     "addons",
-    "config",
     "CHANGELOG.md"
   ],
   "engines": {

package/templates/default/server.js

@@ -1,8 +1,10 @@
 // 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.
+// config page: tick add-ons, fill settings, Apply. Apply writes .env (a
+// VOLT_ADDONS list + settings) and adds any needed packages to package.json,
+// runs npm install, then starts the app — which wires whatever .env enables.
+// Add-on code is bundled under .volt/addons; nothing is copied into your code.
 //
 // No build step, no env-file flag: .env is auto-loaded below.
 
@@ -16,7 +18,11 @@ import { Server as SocketServer } from "socket.io";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 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.8.0", mysql2: "^3.11.0", pg: "^8.12.0", nodemailer: "^6.9.0" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -32,16 +38,34 @@ 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") };
+// Add-ons available to enable (bundled under .volt/addons by create-volt).
+function availableAddons() {
+  if (!fs.existsSync(ADDONS_DIR)) return [];
+  return fs
+    .readdirSync(ADDONS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const m = JSON.parse(fs.readFileSync(path.join(ADDONS_DIR, e.name, "meta.json"), "utf8"));
+      return { name: e.name, description: m.description, dependsOn: m.dependsOn || [] };
+    });
 }
 
-// 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.
+// Which add-ons does VOLT_ADDONS turn on (dependencies expanded)?
+function enabledFrom(env) {
+  const metas = Object.fromEntries(availableAddons().map((a) => [a.name, a]));
+  const out = new Set();
+  const visit = (n) => {
+    if (!metas[n] || out.has(n)) return;
+    out.add(n);
+    for (const d of metas[n].dependsOn) visit(d);
+  };
+  for (const n of String(env.VOLT_ADDONS || "").split(",").map((s) => s.trim()).filter(Boolean)) visit(n);
+  return out;
+}
+
+const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
+const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
+
 function openBrowser(url) {
   if (process.env.VOLT_NO_OPEN || process.argv.includes("--no-open")) return false;
   const plat = process.platform;
@@ -50,7 +74,7 @@ function openBrowser(url) {
   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.on("error", () => {}); // launcher missing — emits async, don't crash
     child.unref();
     return true;
   } catch {
@@ -58,17 +82,25 @@ function openBrowser(url) {
   }
 }
 
-// --- the actual app ---
-function startApp() {
+// --- the actual app: wires whichever add-ons .env enables ---
+async function startApp() {
   const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const enabled = enabledFrom(process.env);
   const app = express();
   app.use(express.static(path.join(__dirname, "public")));
+
+  let store = null;
+  let mailer = null;
+  if (enabled.has("db")) store = await (await addonMod("db")).createStore();
+  if (enabled.has("mailer")) mailer = await (await addonMod("mailer")).createMailer();
+  if (enabled.has("auth") && store && mailer) app.use((await addonMod("auth")).authRouter({ store, mailer }));
+
   app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
 
   const server = http.createServer(app);
   const io = new SocketServer(server);
+  if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
-  // hot reload: watch views/ + public/, debounce, broadcast a reload
   let timer = null;
   const onChange = (file) => {
     clearTimeout(timer);
@@ -82,7 +114,7 @@ function startApp() {
       fs.watch(dir, { recursive: true }, (_e, f) => onChange(f));
       return;
     } catch {
-      /* fall back to per-directory watchers */
+      /* per-dir fallback */
     }
     const w = (d) => {
       try {
@@ -96,12 +128,26 @@ function startApp() {
   };
   for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
 
-  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}`));
+  const on = [...enabled];
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+}
+
+// Packages an .env's selections need, beyond what package.json already has.
+function neededPackages(env) {
+  const pkg = JSON.parse(fs.readFileSync(PKG_PATH, "utf8"));
+  const deps = pkg.dependencies || {};
+  const want = [];
+  const driver = (env.match(/^\s*DB_DRIVER\s*=\s*(\w+)/m) || [])[1];
+  if (driver === "mongodb") want.push("mongodb");
+  if (driver === "mysql") want.push("mysql2");
+  if (driver === "postgres") want.push("pg");
+  if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
+  return want.filter((p) => !deps[p]);
 }
 
 // --- the disposable setup wizard (localhost only) ---
 function startSetup() {
-  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const PORT = Number(process.env.PORT) || Number(readEnvFile().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"))],
@@ -121,7 +167,7 @@ function startSetup() {
     }
     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 }));
+      return res.end(JSON.stringify({ available: availableAddons(), current: readEnvFile(), defaultPort: DEFAULT_PORT }));
     }
     if (req.method === "POST" && p === "/setup/test-db") {
       let body = "";
@@ -135,9 +181,8 @@ function startSetup() {
             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
+          const store = await (await addonMod("db")).createStore();
+          await store.collection("__voltcheck").all();
           res.setHeader("Content-Type", "application/json");
           res.end(JSON.stringify({ ok: true, driver: store.name }));
         } catch (e) {
@@ -159,20 +204,54 @@ function startSetup() {
         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.
+
+          // 1) write .env, preserving any custom keys the form doesn't manage
+          let finalEnv = env;
+          if (fs.existsSync(ENV_PATH)) {
+            const managed = new Set([...env.matchAll(/^\s*([A-Za-z0-9_]+)\s*=/gm)].map((m) => m[1]));
+            const extra = readEnvFileLines().filter((line) => {
+              const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=/);
+              return m && !managed.has(m[1]);
+            });
+            if (extra.length) finalEnv = env.replace(/\n*$/, "\n") + extra.join("\n") + "\n";
+          }
+          fs.writeFileSync(ENV_PATH, finalEnv);
+
+          // 2) declare any needed packages in package.json
+          const added = neededPackages(env);
+          if (added.length) {
+            const pkg = JSON.parse(fs.readFileSync(PKG_PATH, "utf8"));
+            pkg.dependencies = pkg.dependencies || {};
+            for (const name of added) pkg.dependencies[name] = PKG_VERSIONS[name] || "latest";
+            fs.writeFileSync(PKG_PATH, JSON.stringify(pkg, null, 2) + "\n");
+          }
+
           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.end(JSON.stringify({ ok: true, port: newPort, installing: added }));
+
+          // 3) install (if needed), then hand off to the app
           res.on("finish", () => {
-            server.close(() => {
-              loadEnv();
-              startApp();
-            });
-            server.closeIdleConnections?.(); // drop the keep-alive socket so close() fires now
+            const handoff = () => {
+              server.close(() => {
+                loadEnv();
+                startApp();
+              });
+              server.closeIdleConnections?.();
+            };
+            if (added.length) {
+              console.log(`[volt] installing ${added.join(", ")}…`);
+              const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
+              npm.on("error", () => handoff());
+              npm.on("close", () => {
+                console.log("[volt] saved .env — starting the app…");
+                handoff();
+              });
+            } else {
+              console.log("[volt] saved .env — starting the app…");
+              handoff();
+            }
           });
         } catch (e) {
           res.statusCode = 400;
@@ -185,12 +264,11 @@ function startSetup() {
     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"
+    const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
@@ -203,6 +281,10 @@ function startSetup() {
   });
 }
 
+function readEnvFileLines() {
+  return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\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)) {

package/templates/default/setup/setup.js

@@ -1,24 +1,44 @@
-// 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.
+// setup.js — first-run / --edit wizard, built with Volt. Tick add-ons + fill
+// settings → writes .env (a VOLT_ADDONS list + settings), adds any needed
+// packages, installs, and starts the app. Add-on code is bundled; enabling is
+// just config.
 import { signal, computed, html, mount } from "/volt.js";
 
-const { present, current, defaultPort } = await (await fetch("/setup/state")).json();
+const { available, current, defaultPort } = await (await fetch("/setup/state")).json();
+const depsOf = Object.fromEntries(available.map((a) => [a.name, a.dependsOn || []]));
+const order = available.map((a) => a.name);
+const enabledNow = new Set(String(current.VOLT_ADDONS || "").split(",").map((s) => s.trim()).filter(Boolean));
 
 const state = signal({
-  port: current.PORT || String(defaultPort),
+  addons: Object.fromEntries(available.map((a) => [a.name, enabledNow.has(a.name)])),
   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 || "",
+  port: current.PORT || String(defaultPort),
 });
 const set = (patch) => state({ ...state(), ...patch });
+const toggle = (n) => state({ ...state(), addons: { ...state().addons, [n]: !state().addons[n] } });
 const status = signal("");
 
+// selected add-ons, dependencies expanded, in display order
+function effective(s) {
+  const want = new Set();
+  const visit = (n) => {
+    if (want.has(n)) return;
+    want.add(n);
+    (depsOf[n] || []).forEach(visit);
+  };
+  for (const n of order) if (s.addons[n]) visit(n);
+  return order.filter((n) => want.has(n));
+}
+
 function genEnv(s) {
-  const out = [`PORT=${s.port}`];
-  if (present.db) {
+  const eff = effective(s);
+  const out = [`VOLT_ADDONS=${eff.join(",")}`, `PORT=${s.port}`];
+  if (eff.includes("db")) {
     out.push(`DB_DRIVER=${s.dbDriver}`);
     if (s.dbDriver === "mongodb") {
       out.push(`MONGODB_URI=${s.mongoUri}`);
@@ -27,7 +47,7 @@ function genEnv(s) {
       out.push(`DATABASE_URL=${s.dbUrl}`);
     }
   }
-  if (present.mailer) {
+  if (eff.includes("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}`);
@@ -35,55 +55,66 @@ function genEnv(s) {
   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.");
-  }
-}
+const eff = computed(() => effective(state()));
 
 async function testDb() {
   const s = state();
-  const env = { DB_DRIVER: s.dbDriver };
+  const e = { DB_DRIVER: s.dbDriver };
   if (s.dbDriver === "mongodb") {
-    env.MONGODB_URI = s.mongoUri;
-    env.MONGODB_DATABASE = s.mongoDb;
+    e.MONGODB_URI = s.mongoUri;
+    e.MONGODB_DATABASE = s.mongoDb;
   } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
-    env.DATABASE_URL = s.dbUrl;
+    e.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}`);
+    const r = await (await fetch("/setup/test-db", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ env: e }) })).json();
+    status(r.ok ? `✓ Connected (${r.driver}).` : `✗ ${r.error}`);
   } catch {
     status("Network error testing connection.");
   }
 }
 
+async function apply() {
+  status("Saving…");
+  let d;
+  try {
+    d = await (await fetch("/setup/apply", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ addons: eff(), env: env() }) })).json();
+  } catch {
+    return status("Network error.");
+  }
+  if (!d.ok) return status("Error: " + d.error);
+  status(d.installing?.length ? `Installing ${d.installing.join(", ")}, then starting…` : "Starting the app…");
+  const target = `http://localhost:${d.port}/`;
+  const tries = d.installing?.length ? 90 : 20; // npm install can take a while
+  const go = async (n) => {
+    try {
+      await fetch(target, { mode: "no-cors" });
+      location.href = target;
+    } catch {
+      if (n > 0) setTimeout(() => go(n - 1), 500);
+      else location.href = target;
+    }
+  };
+  setTimeout(() => go(tries), 600);
+}
+
+// --- views ---
 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 addonRow = (a) =>
+  html`<div class="form-check mb-2">
+    <input class="form-check-input" type="checkbox" id=${"x-" + a.name} checked=${() => state().addons[a.name]} onchange=${() => toggle(a.name)} />
+    <label class="form-check-label" for=${"x-" + a.name}>
+      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}
+      <div class="small text-muted">${a.description}</div>
+    </label>
+  </div>`;
+
 const dbSettings = () =>
   html`<div class="mb-2">
       <label class="form-label small mb-1">Database (DB_DRIVER)</label>
@@ -104,11 +135,18 @@ const dbSettings = () =>
 
 mount(
   "#app",
+  available.length
+    ? html`<div class="card-x p-4 mb-3">
+        <h2 class="h6 mb-3">Features</h2>
+        ${available.map(addonRow)}
+        <p class="small text-muted mb-0">Enabling a feature wires its backend automatically. Frontend UI (login form, chat) is yours to build — or start from <code>--template guestbook</code>.</p>
+      </div>`
+    : null,
   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)}
+    ${() => (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)}
   </div>`,
   html`<div class="card-x p-4 mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">

package/config/config-app.js

@@ -1,168 +0,0 @@
-// config-app.js — the disposable add-on configurator, built with Volt itself.
-import { signal, computed, html, mount } from "/volt.js";
-
-const datePort = () => {
-  const d = new Date();
-  return `${String(d.getFullYear()).slice(-2)}${d.getMonth() + 1}${String(d.getDate()).padStart(2, "0")}`;
-};
-
-const addons = await (await fetch("/addons.json")).json();
-const current = await (await fetch("/current.json")).json(); // existing .env, so Apply doesn't clobber it
-const byName = (n) => addons.find((a) => a.name === n);
-
-const state = signal({
-  addons: Object.fromEntries(addons.map((a) => [a.name, a.installed])),
-  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 || "",
-  port: current.PORT || datePort(),
-});
-const set = (patch) => state({ ...state(), ...patch });
-const toggle = (n) => state({ ...state(), addons: { ...state().addons, [n]: !state().addons[n] } });
-const status = signal("");
-
-// --- generators ---
-function genEnv(s) {
-  const out = [];
-  if (s.port) out.push(`PORT=${s.port}`);
-  if (s.addons.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 (s.addons.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";
-}
-function genInstall(s) {
-  const deps = new Set();
-  for (const a of addons) if (s.addons[a.name]) (a.install || []).forEach((d) => deps.add(d));
-  if (s.addons.db) {
-    if (s.dbDriver === "mongodb") deps.add("mongodb");
-    if (s.dbDriver === "mysql") deps.add("mysql2");
-    if (s.dbDriver === "postgres") deps.add("pg");
-  }
-  if (s.addons.mailer && s.smtpUrl) deps.add("nodemailer");
-  return deps.size ? `npm install ${[...deps].join(" ")}` : "# no extra packages needed";
-}
-function genWiring(s) {
-  const parts = [];
-  for (const name of ["db", "mailer", "auth", "realtime"]) {
-    if (s.addons[name]) parts.push(`// ── ${name} ──\n${byName(name).wiring}`);
-  }
-  return parts.join("\n\n") || "// select add-ons above";
-}
-function warnings(s) {
-  const w = [];
-  if (s.addons.auth && (!s.addons.db || !s.addons.mailer)) w.push("auth needs db + mailer");
-  if (s.addons.realtime && !s.addons.db) w.push("realtime needs db (for message persistence)");
-  return w;
-}
-
-const env = computed(() => genEnv(state()));
-
-const KEY = new URLSearchParams(location.search).get("key") || "";
-const copy = (text) => navigator.clipboard.writeText(text).then(() => (status("Copied."), setTimeout(() => status(""), 1500)));
-const setAll = (v) => state({ ...state(), addons: Object.fromEntries(addons.map((a) => [a.name, v])) });
-async function apply() {
-  const selected = Object.keys(state().addons).filter((n) => state().addons[n]);
-  status("Applying…");
-  const r = await fetch("/apply", { method: "POST", headers: { "Content-Type": "application/json", "x-config-key": KEY }, body: JSON.stringify({ addons: selected, env: env() }) });
-  const d = await r.json();
-  status(d.ok ? `Applied ${selected.join(", ") || "(none)"} — copied ${d.copied.length} file(s) + wrote .env. Next: ${genInstall(state())} · npm run dev` : `Error: ${d.error}`);
-  setTimeout(() => status(""), 9000);
-}
-
-// --- views ---
-const addonToggles = () =>
-  html`<div class="card-x p-4 mb-3">
-    <div class="d-flex justify-content-between align-items-center mb-3">
-      <h2 class="h6 mb-0">Add-ons</h2>
-      <div>
-        <button class="btn btn-sm btn-outline-secondary" onclick=${() => setAll(true)}>All</button>
-        <button class="btn btn-sm btn-outline-secondary ms-1" onclick=${() => setAll(false)}>None</button>
-      </div>
-    </div>
-    ${addons.map(
-      (a) => html`<div class="form-check mb-2">
-        <input class="form-check-input" type="checkbox" id=${"x-" + a.name}
-               checked=${() => state().addons[a.name]} onchange=${() => toggle(a.name)} />
-        <label class="form-check-label" for=${"x-" + a.name}>
-          <span class="accent">${a.name}</span>${a.installed ? " · installed" : ""}
-          <div class="small text-muted">${a.description}</div>
-        </label>
-      </div>`,
-    )}
-  </div>`;
-
-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 settings = () =>
-  html`<div class="card-x p-4 mb-3">
-    <h2 class="h6 mb-3">Settings</h2>
-    ${field("PORT", "port", "26628")}
-    ${() =>
-      state().addons.db
-        ? html`<div class="mb-2">
-              <label class="form-label small mb-1">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}`
-        : null}
-    ${() => (state().addons.mailer ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
-  </div>`;
-
-const warnRow = () =>
-  html`${() => {
-    const w = warnings(state());
-    return w.length ? html`<div class="alert alert-warning py-2 small">⚠ ${w.join(" · ")}</div>` : null;
-  }}`;
-
-const output = (title, getText, withWrite = false) =>
-  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">${title}</h2>
-      <div>
-        <button class="btn btn-sm btn-outline-secondary" onclick=${() => copy(getText())}>Copy</button>
-        ${withWrite ? html`<button class="btn btn-sm btn-primary ms-2" onclick=${apply}>Apply</button>` : null}
-      </div>
-    </div>
-    <pre class="mb-0">${getText}</pre>
-  </div>`;
-
-mount(
-  "#app",
-  addonToggles(),
-  settings(),
-  warnRow(),
-  output(".env", env, true),
-  html`<p class="small text-muted mb-3">The app auto-loads <code>.env</code> on start — just run <code>npm run dev</code> (no flags; same on Windows).</p>`,
-  output("Install", computed(() => genInstall(state()))),
-  output("server.js wiring", computed(() => genWiring(state()))),
-  () => (status() ? html`<p class="small accent">${status}</p>` : null),
-);

package/config/index.html

@@ -1,29 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>create-volt · configure add-ons</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; }
-    pre { background: #0b0d11; border: 1px solid #232a36; border-radius: 10px; padding: 12px; color: #cfe3ff; white-space: pre-wrap; }
-    a { color: #ffd24a; }
-    code { color: #ffd24a; }
-  </style>
-</head>
-<body>
-  <main class="container py-5" style="max-width: 760px;">
-    <header class="mb-4">
-      <h1 class="h3"><span class="accent">⚡ create-volt</span> · configure add-ons</h1>
-      <p class="text-muted mb-0">Pick add-ons, fill in settings, write your <code>.env</code>. This page is disposable — close the terminal when you're done.</p>
-    </header>
-    <div id="app"></div>
-  </main>
-  <script type="module" src="/config-app.js"></script>
-</body>
-</html>