create-volt 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.29.0] - 2026-06-29
+
+### Fixed
+- **Date-derived default port is now valid year-round.** For Oct–Dec the
+  readable YY+M+DD form is 6 digits (e.g. `261010`) and exceeds the max TCP port
+  65535, so create-volt previously refused to scaffold without `--port`. It now
+  falls back to a deterministic in-range port `1024 + (YYYYMMDD % 64512)` when the
+  readable form overflows; Jan–Sep keep the readable port unchanged. Extracted to
+  `lib/date-port.js` and unit-tested.
+
+## [0.28.0] - 2026-06-29
+
+### Fixed
+- Wizard **Test connection** now installs the selected DB driver on demand
+  (mongodb / mysql2 / pg, at the pinned version) before testing — it used to fail
+  with "<driver> isn't installed" because the package is only added on Apply.
+  Also adds the missing `spawnSync` import.
+
 ## [0.27.0] - 2026-06-29
 
 ### Fixed
@@ -381,6 +399,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.29.0]: https://github.com/MIR-2025/volt/releases/tag/v0.29.0
+[0.28.0]: https://github.com/MIR-2025/volt/releases/tag/v0.28.0
 [0.27.0]: https://github.com/MIR-2025/volt/releases/tag/v0.27.0
 [0.26.0]: https://github.com/MIR-2025/volt/releases/tag/v0.26.0
 [0.25.0]: https://github.com/MIR-2025/volt/releases/tag/v0.25.0

package/index.js

@@ -13,6 +13,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
+import { datePort } from "./lib/date-port.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -364,12 +365,6 @@ if (positionals[0] === "studio") {
 // 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.
-function datePort(d) {
-  const yy = String(d.getFullYear()).slice(-2);
-  const mm = String(d.getMonth() + 1);
-  const dd = String(d.getDate()).padStart(2, "0");
-  return Number(`${yy}${mm}${dd}`);
-}
 let port;
 if (portArg != null) {
   port = Number(portArg);
@@ -377,10 +372,7 @@ if (portArg != null) {
     die(`Invalid --port "${portArg}" — use a whole number between 1 and 65535.`);
   }
 } else {
-  port = datePort(new Date());
-  if (port > 65535) {
-    die(`The date-derived port (${port}) is above 65535 — pass --port <1-65535>.`);
-  }
+  port = datePort(new Date()); // always 1–65535 (see lib/date-port.js)
 }
 
 const rawName = positionals[0];

package/lib/date-port.js

@@ -0,0 +1,21 @@
+// date-port.js — derive an app's dev port from its start date.
+//
+// Convention: two-digit year + month (no leading zero) + two-digit day,
+// concatenated → e.g. 2026-06-28 → 26628. Readable, and unique per date
+// (year and day are fixed-width, so the month's 1-vs-2-digit width is
+// unambiguous).
+//
+// Caveat: for Oct–Dec the month is two digits, so the value is 6 digits
+// (e.g. 2026-10-10 → 261010) — above the max TCP port (65535). When the
+// readable form overflows, fall back to a deterministic in-range port
+// derived from the full date: 1024 + (YYYYMMDD % 64512) ∈ [1024, 65535].
+// Always valid, always the same for a given date.
+export function datePort(d) {
+  const yy = String(d.getFullYear()).slice(-2);
+  const mm = String(d.getMonth() + 1); // no leading zero
+  const dd = String(d.getDate()).padStart(2, "0");
+  const readable = Number(`${yy}${mm}${dd}`);
+  if (readable <= 65535) return readable;
+  const ymd = d.getFullYear() * 10000 + (d.getMonth() + 1) * 100 + d.getDate();
+  return 1024 + (ymd % 64512);
+}

package/lib/import-wp-db.js

@@ -0,0 +1,77 @@
+// import-wp-db.js — import WordPress content by reading its MySQL/MariaDB
+// database directly. The niche path for when the REST API is disabled but you
+// have DB access (e.g. on the server or over an SSH tunnel). Reuses the WXR
+// converter (transform → markdown). mysql2 is loaded lazily so create-volt stays
+// dependency-free; the DB connection is injectable for testing.
+import { transform } from "./import-wxr.js";
+
+// Table prefix goes into table names (which can't be parameterized), so it must
+// be a safe SQL identifier — this is the one injection vector. Validate hard.
+export function validatePrefix(p) {
+  if (!/^[A-Za-z0-9_]+$/.test(p)) throw new Error(`Invalid --prefix "${p}" — only letters, numbers, and underscore are allowed.`);
+  return p;
+}
+
+// Shape DB rows (posts + flat term rows) into the common item shape.
+export function rowsToItems(posts, terms) {
+  const byPost = new Map();
+  for (const t of terms || []) {
+    const m = byPost.get(t.object_id) || { categories: [], tags: [] };
+    (t.taxonomy === "post_tag" ? m.tags : m.categories).push(t.name);
+    byPost.set(t.object_id, m);
+  }
+  return (posts || []).map((p) => {
+    const t = byPost.get(p.ID) || { categories: [], tags: [] };
+    return {
+      type: p.post_type || "post",
+      title: p.post_title || p.post_name || "Untitled",
+      slug: p.post_name || "",
+      status: p.post_status || "publish",
+      date: p.post_date ? String(p.post_date).replace("T", " ").replace(/\.\d+$/, "") : "",
+      content: p.post_content || "",
+      categories: t.categories,
+      tags: t.tags,
+    };
+  });
+}
+
+async function defaultConnect(dbUrl) {
+  let mysql;
+  try {
+    mysql = await import("mysql2/promise");
+  } catch {
+    throw new Error("mysql2 is required for import-wp-db — install it: npm i mysql2");
+  }
+  const c = await mysql.createConnection(dbUrl);
+  return {
+    query: async (sql) => {
+      const [rows] = await c.query(sql);
+      return rows;
+    },
+    end: () => c.end(),
+  };
+}
+
+// Read posts + pages (and their terms) from a WordPress database.
+export async function fetchWPFromDB(dbUrl, { prefix = "wp_", drafts = false, connect = defaultConnect } = {}) {
+  validatePrefix(prefix);
+  const statuses = (drafts ? ["publish", "draft", "pending", "private", "future"] : ["publish"]).map((s) => `'${s}'`).join(","); // fixed allowlist, safe
+  const conn = await connect(dbUrl);
+  try {
+    const posts = await conn.query(
+      `SELECT ID, post_title, post_name, post_content, post_status, post_type, post_date FROM \`${prefix}posts\` WHERE post_type IN ('post','page') AND post_status IN (${statuses})`,
+    );
+    const terms = await conn.query(
+      `SELECT tr.object_id AS object_id, tt.taxonomy AS taxonomy, t.name AS name FROM \`${prefix}term_relationships\` tr` +
+        ` JOIN \`${prefix}term_taxonomy\` tt ON tr.term_taxonomy_id = tt.term_taxonomy_id` +
+        ` JOIN \`${prefix}terms\` t ON tt.term_id = t.term_id WHERE tt.taxonomy IN ('category','post_tag')`,
+    );
+    return rowsToItems(posts, terms);
+  } finally {
+    await conn.end?.();
+  }
+}
+
+export async function runImportFromDB(dbUrl, opts = {}) {
+  return transform(await fetchWPFromDB(dbUrl, opts), opts);
+}

package/lib/import-wxr.js

@@ -0,0 +1,152 @@
+// import-wxr.js — import a WordPress export (WXR XML) into Volt markdown pages.
+// Zero-dep: WXR is a consistent, machine-generated format, so a focused parser
+// is more honest than pulling a general XML library. Pure functions (parseWXR,
+// toMarkdown, runImport) so they're unit-testable; file I/O lives in the CLI.
+
+const unCdata = (s) => s.replace(/^\s*<!\[CDATA\[([\s\S]*?)\]\]>\s*$/, "$1");
+
+const decode = (s) =>
+  String(s)
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#0?39;|&#x27;|&apos;/g, "'")
+    .replace(/&#8217;/g, "’")
+    .replace(/&#8216;/g, "‘")
+    .replace(/&#8220;/g, "“")
+    .replace(/&#8221;/g, "”")
+    .replace(/&#8211;/g, "–")
+    .replace(/&#8212;/g, "—")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&");
+
+const tagOf = (block, name) => {
+  const m = block.match(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`));
+  return m ? unCdata(m[1]).trim() : "";
+};
+
+const catsOf = (block, domain) =>
+  [...block.matchAll(new RegExp(`<category domain="${domain}"[^>]*>([\\s\\S]*?)</category>`, "g"))].map((m) => decode(unCdata(m[1]).trim())).filter(Boolean);
+
+// Parse a WXR document into raw items.
+export function parseWXR(xml) {
+  const items = [];
+  for (const m of String(xml).matchAll(/<item>([\s\S]*?)<\/item>/g)) {
+    const b = m[1];
+    items.push({
+      type: tagOf(b, "wp:post_type") || "post",
+      title: decode(tagOf(b, "title")),
+      slug: tagOf(b, "wp:post_name"),
+      status: tagOf(b, "wp:status") || "publish",
+      date: tagOf(b, "wp:post_date") || tagOf(b, "pubDate"),
+      content: unCdata((b.match(/<content:encoded>([\s\S]*?)<\/content:encoded>/) || [, ""])[1]).trim(),
+      categories: catsOf(b, "category"),
+      tags: catsOf(b, "post_tag"),
+    });
+  }
+  return items;
+}
+
+export const slugify = (s) =>
+  String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || "page";
+
+// WP content is HTML (often with Gutenberg block comments). Strip the block
+// comments; the rest is valid HTML that the pages add-on's `marked` passes
+// through. Pages are author-trusted files.
+const cleanBody = (html) =>
+  String(html)
+    .replace(/<!--\s*\/?wp:[\s\S]*?-->/g, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+
+// Render one item to a markdown file body (front-matter + content).
+export function toMarkdown(item) {
+  const fm = ["---", `title: ${String(item.title || "Untitled").replace(/[\r\n]+/g, " ").trim()}`];
+  if (item.date) fm.push(`date: ${item.date}`);
+  if (item.tags && item.tags.length) fm.push(`tags: ${item.tags.join(", ")}`);
+  fm.push("---", "");
+  return fm.join("\n") + cleanBody(item.content) + "\n";
+}
+
+// Map a WP REST API object (?_embed=1) into the same item shape as parseWXR.
+function mapREST(p, type) {
+  const flat = ((p._embedded && p._embedded["wp:term"]) || []).flat();
+  const byTax = (tax) => flat.filter((t) => t && t.taxonomy === tax).map((t) => decode(t.name)).filter(Boolean);
+  return {
+    type,
+    title: decode((p.title && p.title.rendered) || p.slug || "Untitled"),
+    slug: p.slug || "",
+    status: p.status || "publish",
+    date: String(p.date || "").replace("T", " ").replace(/\.\d+$/, ""),
+    content: (p.content && p.content.rendered) || "",
+    categories: byTax("category"),
+    tags: byTax("post_tag"),
+  };
+}
+
+// Fetch posts + pages from a live WordPress site over the REST API. Credentials
+// (Application Password) are only needed for non-published content. fetchImpl is
+// injectable for testing.
+export async function fetchWP(baseUrl, { user, appPassword, drafts = false, fetchImpl = fetch } = {}) {
+  const base = String(baseUrl).replace(/\/+$/, "");
+  const headers = { Accept: "application/json" };
+  if (user && appPassword) headers.Authorization = "Basic " + Buffer.from(`${user}:${appPassword}`).toString("base64");
+  const statuses = drafts ? "publish,draft,pending,private,future" : "publish";
+  const items = [];
+  for (const [kind, type] of [["posts", "post"], ["pages", "page"]]) {
+    let page = 1;
+    let totalPages = 1;
+    do {
+      const url = `${base}/wp-json/wp/v2/${kind}?per_page=100&page=${page}&status=${statuses}&_embed=1`;
+      const res = await fetchImpl(url, { headers });
+      if (res.status === 400 && page > 1) break; // WP 400s past the last page
+      if (res.status === 401 || res.status === 403) throw new Error(`WP REST ${kind}: ${res.status} — credentials needed/insufficient for status=${statuses}`);
+      if (!res.ok) throw new Error(`WP REST ${kind} page ${page}: ${res.status} ${res.statusText || ""}`.trim());
+      totalPages = Number(res.headers && res.headers.get && res.headers.get("X-WP-TotalPages")) || 1;
+      const arr = await res.json();
+      if (!Array.isArray(arr) || arr.length === 0) break;
+      for (const p of arr) items.push(mapREST(p, type));
+      page++;
+    } while (page <= totalPages);
+  }
+  return items;
+}
+
+// Select + transform raw items into importable markdown pages. Returns { imported, stats }.
+export function transform(all, { types = ["page", "post"], drafts = false } = {}) {
+  const stats = { total: all.length, byType: {}, draftsSkipped: 0, otherTypeSkipped: 0 };
+  for (const i of all) stats.byType[i.type] = (stats.byType[i.type] || 0) + 1;
+
+  const used = new Set();
+  const imported = [];
+  for (const i of all) {
+    if (!types.includes(i.type)) {
+      stats.otherTypeSkipped++;
+      continue;
+    }
+    if (i.status !== "publish" && !drafts) {
+      stats.draftsSkipped++;
+      continue;
+    }
+    let slug = i.slug && /^[a-z0-9][a-z0-9-]*$/i.test(i.slug) ? i.slug.toLowerCase() : slugify(i.title || i.slug);
+    let s = slug;
+    for (let n = 2; used.has(s); n++) s = `${slug}-${n}`;
+    used.add(s);
+    imported.push({ slug: s, type: i.type, title: i.title, filename: `${s}.md`, markdown: toMarkdown(i) });
+  }
+  return { imported, stats };
+}
+
+// Import from a WXR export string (offline file path).
+export function runImport(xml, opts = {}) {
+  return transform(parseWXR(xml), opts);
+}
+
+// Import from a live WordPress site over the REST API.
+export async function runImportFromWP(baseUrl, opts = {}) {
+  return transform(await fetchWP(baseUrl, opts), opts);
+}

package/package.json

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

package/templates/default/server.js

@@ -11,7 +11,7 @@
 import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import express from "express";
 import { Server as SocketServer } from "socket.io";
@@ -208,6 +208,15 @@ function neededPackages(env) {
   return want.filter((p) => !deps[p]);
 }
 
+// Install a DB driver's package on demand (pinned), so the wizard's "Test
+// connection" works before Apply has installed it.
+function ensureDriverInstalled(driver) {
+  const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
+  if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
+  console.log(`[volt] installing ${pkg} for the connection test…`);
+  spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
+}
+
 // --- the disposable setup wizard (localhost only) ---
 function startSetup() {
   const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
@@ -244,6 +253,7 @@ function startSetup() {
             if (env[k]) process.env[k] = env[k];
             else delete process.env[k];
           }
+          ensureDriverInstalled(process.env.DB_DRIVER); // install the driver first, so the test can connect
           const store = await (await addonMod("db")).createStore();
           await store.collection("__voltcheck").all();
           res.setHeader("Content-Type", "application/json");

package/templates/starter/server.js

@@ -12,7 +12,7 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import express from "express";
 import { Server as SocketServer } from "socket.io";
@@ -234,6 +234,15 @@ function neededPackages(env) {
   return want.filter((p) => !deps[p]);
 }
 
+// Install a DB driver's package on demand (pinned), so the wizard's "Test
+// connection" works before Apply has installed it.
+function ensureDriverInstalled(driver) {
+  const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
+  if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
+  console.log(`[volt] installing ${pkg} for the connection test…`);
+  spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
+}
+
 // --- the disposable setup wizard (localhost only) ---
 function startSetup() {
   const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
@@ -270,6 +279,7 @@ function startSetup() {
             if (env[k]) process.env[k] = env[k];
             else delete process.env[k];
           }
+          ensureDriverInstalled(process.env.DB_DRIVER); // install the driver first, so the test can connect
           const store = await (await addonMod("db")).createStore();
           await store.collection("__voltcheck").all();
           res.setHeader("Content-Type", "application/json");