create-volt 0.5.0 → 0.9.0

package/index.js

@@ -35,12 +35,15 @@ ${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              # open the app's setup wizard (edit add-ons + settings)
 
 ${bold("Options")}
   --template <name>  Starter template: default | guestbook  (default: default)
   --port <number>    Dev port for the app (default: derived from today's date)
   --skip-install   Don't run the package manager install step
   --no-git         Don't initialize a git repository
+  --start          After scaffolding, run the dev server (opens the setup page)
+  --no-open        Don't auto-open the browser on start
   --dry-run        Show what would be created without writing anything
   --force          Scaffold into an existing non-empty directory
   -h, --help       Show this help
@@ -81,6 +84,11 @@ const force = flags.has("--force");
 const dryRun = flags.has("--dry-run");
 const noGit = flags.has("--no-git");
 
+// The `add` command was replaced by `config` — catch old muscle memory.
+if (positionals[0] === "add") {
+  die(`${cyan("add")} was replaced by ${cyan("create-volt config")} — run that to add integrations.`);
+}
+
 // --- `update` subcommand: refresh public/volt.js in the current app to the
 // version bundled with this create-volt (so `npx create-volt@latest update`
 // pulls the latest library). Only touches the library file — never the user's
@@ -107,6 +115,22 @@ if (positionals[0] === "update") {
   process.exit(0);
 }
 
+// --- `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();
+  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,
+  });
+  process.exit(res.status ?? 0);
+}
+
 // Resolve the dev port: --port wins, else derive it from today's date as
 // two-digit-year + month (no leading zero) + two-digit-day (house convention),
 // so apps scaffolded on different days don't collide on the same port.
@@ -206,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"));
@@ -214,10 +244,10 @@ fs.writeFileSync(appPkgPath, JSON.stringify(appPkg, null, 2) + "\n");
 
 // --- stamp the chosen dev port into server.js + README ---
 const serverPath = path.join(targetDir, "server.js");
-fs.writeFileSync(
-  serverPath,
-  fs.readFileSync(serverPath, "utf8").replace(/(Number\(process\.env\.PORT\)\s*\|\|\s*)\d+/, `$1${port}`),
-);
+let serverSrc = fs.readFileSync(serverPath, "utf8");
+serverSrc = serverSrc.replace(/(const DEFAULT_PORT\s*=\s*)\d+/, `$1${port}`); // default template
+serverSrc = serverSrc.replace(/(Number\(process\.env\.PORT\)\s*\|\|\s*)\d+/, `$1${port}`); // other templates
+fs.writeFileSync(serverPath, serverSrc);
 const appReadme = path.join(targetDir, "README.md");
 if (fs.existsSync(appReadme)) {
   fs.writeFileSync(appReadme, fs.readFileSync(appReadme, "utf8").replace(/localhost:\d+/g, `localhost:${port}`));
@@ -287,4 +317,18 @@ console.log(`\n${green("✔")} ${bold("Done!")} Next steps:\n`);
 console.log(`  ${cyan("cd")} ${projectName}`);
 if (!installed) console.log(`  ${cyan(installCmd)}`);
 console.log(`  ${cyan(runCmd)}`);
-console.log(`\nThen open ${cyan("http://localhost:" + port)} and edit ${bold("public/app.js")}.\n`);
+console.log(`\nFirst run opens a quick ${bold("setup")} page at ${cyan("http://localhost:" + port)}, then your app starts.\n`);
+
+if (flags.has("--start")) {
+  if (!installed) {
+    console.log(dim(`(--start needs dependencies — run ${installCmd}, then ${runCmd}.)\n`));
+  } else {
+    console.log(`${bold("Starting…")}\n`);
+    spawnSync(pm, ["run", "dev"], {
+      cwd: targetDir,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: flags.has("--no-open") ? { ...process.env, VOLT_NO_OPEN: "1" } : process.env,
+    });
+  }
+}

package/package.json

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

package/templates/default/README.md

@@ -10,9 +10,15 @@ Not React: no JSX, no virtual DOM, no re-render-the-world. State lives in
 
 ```bash
 npm install        # if you scaffolded with --skip-install
-npm run dev        # → http://localhost:26628   (PORT env to override)
+npm run dev        # → http://localhost:26628
 ```
 
+The **first run opens a quick setup page** in your browser (configure settings,
+click Apply, and the app starts — the setup page then disappears). On a headless
+or remote box it prints the link instead. Reopen settings anytime with
+`npm run dev -- --edit` (`-e`). `.env` is auto-loaded, so no `--env-file` flag
+is needed — it works the same on Windows.
+
 Edit anything in `public/` or `views/` and save — the dev server pushes a
 reload over Socket.io and the page refreshes itself.
 

package/templates/default/server.js

@@ -1,64 +1,295 @@
-// server.js — minimal dev server for a Volt app. Express serves the static
-// client and the index view; Socket.io carries the hot-reload signal; a file
-// watcher on views/ and public/ broadcasts a (debounced) reload on any save.
+// server.js — dev server with a built-in first-run setup wizard.
 //
-// Cross-platform: paths are resolved relative to this file, and the watcher
-// falls back to a manual recursive walk where native recursive fs.watch is
-// unavailable (older Linux Node builds).
+// First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
+// 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.
 //
-//   npm run dev            # start the dev server
-//   PORT=4000 npm run dev  # override the port
+// 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 { fileURLToPath } from "node:url";
+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 PORT = Number(process.env.PORT) || 26628;
-
-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 bursts, broadcast a reload ---
-const watchDirs = ["views", "public"].map((d) => path.join(__dirname, d));
-let timer = null;
-function onChange(file) {
-  clearTimeout(timer);
-  timer = setTimeout(() => {
-    console.log(`[volt] change: ${file ?? "?"} → reload`);
-    io.emit("volt:reload");
-  }, 80);
+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() {
+  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;
+}
+
+// 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 || [] };
+    });
 }
 
-// Watch a directory recursively. Tries native recursive fs.watch first; if the
-// platform/runtime doesn't support it, walks the tree and watches each dir.
-function watchRecursive(dir) {
+// 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;
+  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 {
-    fs.watch(dir, { recursive: true }, (_event, file) => onChange(file));
-    return;
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.unref();
+    return true;
   } catch {
-    // Native recursive watch unsupported — fall back to per-directory watchers.
+    return false;
   }
-  const watchDir = (d) => {
+}
+
+// --- 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 });
+
+  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(d, (_event, file) => onChange(file));
+      fs.watch(dir, { recursive: true }, (_e, f) => onChange(f));
+      return;
     } catch {
-      /* directory vanished between walk and watch — ignore */
-    }
-    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
-      if (entry.isDirectory()) watchDir(path.join(d, entry.name));
+      /* per-dir fallback */
     }
+    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);
   };
-  watchDir(dir);
+  for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
+
+  const on = [...enabled];
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
 }
 
-for (const dir of watchDirs) watchRecursive(dir);
+// 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]);
+}
 
-server.listen(PORT, () => console.log(`⚡ Volt dev server → http://localhost:${PORT}`));
+// --- the disposable setup wizard (localhost only) ---
+function startSetup() {
+  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"))],
+  };
+  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({ available: availableAddons(), 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 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) {
+          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");
+
+          // 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, installing: added }));
+
+          // 3) install (if needed), then hand off to the app
+          res.on("finish", () => {
+            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;
+          res.end(JSON.stringify({ ok: false, error: e.message }));
+        }
+      });
+      return;
+    }
+    res.statusCode = 404;
+    res.end("not found");
+  });
+
+  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;
+    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");
+  });
+}
+
+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)) {
+  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,159 @@
+// 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 { 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({
+  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 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}`);
+      if (s.mongoDb) out.push(`MONGODB_DATABASE=${s.mongoDb}`);
+    } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
+      out.push(`DATABASE_URL=${s.dbUrl}`);
+    }
+  }
+  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}`);
+  }
+  return out.join("\n") + "\n";
+}
+const env = computed(() => genEnv(state()));
+const eff = computed(() => effective(state()));
+
+async function testDb() {
+  const s = state();
+  const e = { DB_DRIVER: s.dbDriver };
+  if (s.dbDriver === "mongodb") {
+    e.MONGODB_URI = s.mongoUri;
+    e.MONGODB_DATABASE = s.mongoDb;
+  } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
+    e.DATABASE_URL = s.dbUrl;
+  }
+  status("Testing connection…");
+  try {
+    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>
+      <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",
+  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))}
+    ${() => (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">
+      <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),
+);