create-wordjs 2.7.0 → 2.9.0

package/README.md

@@ -29,6 +29,9 @@ That single command takes you from nothing to the browser install wizard:
    `wordjs-<tag>.zip.sha256` asset published with the release before extracting anything
    (see [Integrity](#integrity)).
 2. Extracts it into `my-site/` and installs the runtime dependencies (`npm run release:install`).
+   A failed install (typically a timed-out prebuilt `better-sqlite3` download on a server without a
+   compiler) is retried with backoff; if it keeps failing you get a plain explanation, and running
+   the same command again resumes the install.
 3. Generates a one-time install token and starts the server (`npm run start:mono`), printing a
    clickable URL:
 
@@ -42,7 +45,7 @@ in CI — plus a pure-JS *SQLite (legacy / WASM)* fallback for hosts where the n
 
 ## Requirements
 
-- Node.js **>= 20.9** (Node 20 or 22 LTS recommended) with npm on your PATH.
+- Node.js **>= 22** (Node 22 or 24 LTS recommended) with npm on your PATH.
 
 ## Options
 
@@ -59,6 +62,7 @@ in CI — plus a pure-JS *SQLite (legacy / WASM)* fallback for hosts where the n
 | `--systemd` | (create, `upgrade`; Linux) Also write a systemd unit, `wordjs.service`, to a private staging directory outside the site and print how to install it. The unit runs WordJS as a dedicated non-root account with **no Linux capabilities**. With create it implies `--no-start`. See [Run it as a service](#run-it-as-a-service-linux). |
 | `--port <n>` | (with `--systemd`) Public port written into the unit (`PORT=<n>`); default: the site's configured port, else `3000`. Below 1024 it also stages `60-wordjs-ports.conf`. |
 | `--service-user <name>` | (with `--systemd`) The account the service runs as (default `wordjs`; `root` is refused). |
+| `--mail` | (with `--systemd`) The site will receive mail (mail-server plugin, SMTP on 25): the drop-in also allows 25. Implied on `upgrade` when that plugin is installed. |
 | `-h`, `--help` | Show usage. |
 
 Separate-mode options:
@@ -105,7 +109,10 @@ boot must run as the service account so that account owns the database and certi
 
 **Ports below 1024 (80/443).** The unit never grants `CAP_NET_BIND_SERVICE`. For a port below 1024,
 `--systemd` also stages `60-wordjs-ports.conf`, a `sysctl.d` drop-in that sets
-`net.ipv4.ip_unprivileged_port_start` to that port. Read its trade-off before installing it: it lets
+`net.ipv4.ip_unprivileged_port_start` low enough for every port the site will bind: that port, `80` too
+for an HTTPS site (Let's Encrypt HTTP-01, turned on later in the admin panel) and `25` with `--mail`
+(incoming mail; implied on `upgrade` when the mail-server plugin is installed). Read its trade-off before
+installing it: it lets
 **every** unprivileged process on the host bind ports from that value up to 1023, not just WordJS. On a
 shared host, prefer a reverse proxy (nginx, Caddy) on 80/443 forwarding to WordJS on a high port.
 

package/index.js

@@ -27,14 +27,14 @@
 const REPO = 'jaimemartinez/wordjs';
 
 // ---------------------------------------------------------------------------------------------
-// Node preflight — same floor as WordJS itself (Next 16 + native modules need >= 20.9). Failing
+// Node preflight — same floor as WordJS itself (Node >= 22: graphql 17 and the native modules declare it). Failing
 // here with a clear message beats the cryptic EBADENGINE/native-binding crash mid-install.
 // ---------------------------------------------------------------------------------------------
 {
-    const [maj, min] = process.versions.node.split('.').map(Number);
-    if (maj < 20 || (maj === 20 && min < 9)) {
-        console.error(`\n✖ WordJS requires Node.js >= 20.9 — you are running ${process.versions.node}.`);
-        console.error('  Install Node 20 LTS or 22 LTS from https://nodejs.org and try again.\n');
+    const maj = Number(process.versions.node.split('.')[0]);
+    if (maj < 22) {
+        console.error(`\n✖ WordJS requires Node.js >= 22 — you are running ${process.versions.node}.`);
+        console.error('  Install Node 22 LTS or 24 LTS from https://nodejs.org and try again.\n');
         process.exit(1);
     }
 }
@@ -84,8 +84,13 @@ Options:
                         the first boot must run as that account.
   --port <n>            (with --systemd) Public port, written into the unit as PORT=<n> (default:
                         the site's configured port, else 3000). Below 1024 it also stages
-                        60-wordjs-ports.conf (net.ipv4.ip_unprivileged_port_start), never a capability.
+                        60-wordjs-ports.conf (net.ipv4.ip_unprivileged_port_start), never a capability,
+                        low enough for every port the site will bind: with HTTPS also 80 (Let's
+                        Encrypt HTTP-01 from Admin -> Security), with --mail also 25.
   --service-user <name> (with --systemd) The account the service runs as (default: wordjs). Not root.
+  --mail                (with --systemd) The site will receive mail (the mail-server plugin, SMTP on
+                        port 25): the drop-in then lowers the floor to 25. Implied on upgrade when the
+                        mail-server plugin is installed.
   -h, --help            Show this help.
 
 Examples:
@@ -126,7 +131,7 @@ function parseArgs(argv) {
     const opts = {
         mode: 'create', dir: null, zip: null, version: null, http: false, start: true, yes: false, force: false, install: true,
         role: null, gateway: null, token: null, caHash: null, advertise: null, enrollPort: null, host: null,
-        systemd: false, port: null, serviceUser: null,
+        systemd: false, port: null, serviceUser: null, mail: false,
         sha256: null,
     };
     // A leading subcommand selects the mode (default is the monolith create flow).
@@ -159,11 +164,12 @@ function parseArgs(argv) {
         else if (a === '--systemd') opts.systemd = true;
         else if (a === '--port') opts.port = argv[++i] || fail('--port needs a value (1-65535).');
         else if (a === '--service-user') opts.serviceUser = argv[++i] || fail('--service-user needs an account name.');
+        else if (a === '--mail') opts.mail = true;
         else if (a.startsWith('-')) fail(`Unknown option: ${a}`, 'Run with --help to see the available options.');
         else positionals.push(a);
     }
-    if ((opts.port !== null || opts.serviceUser !== null) && !opts.systemd) {
-        fail('--port and --service-user only apply together with --systemd.',
+    if ((opts.port !== null || opts.serviceUser !== null || opts.mail) && !opts.systemd) {
+        fail('--port, --service-user and --mail only apply together with --systemd.',
             'Without a unit, the port comes from the PORT environment variable or the site config (default 3000).');
     }
     if (opts.systemd) {
@@ -581,17 +587,94 @@ async function obtainBundleZip(opts) {
     return { zipPath, tag, cleanup };
 }
 
-function runNpmScript(script, cwd, extraEnv) {
-    // A single command string with shell:true resolves npm/npm.cmd on every platform (and avoids
-    // Node's DEP0190 warning about args-array + shell). The string is fixed — no user input in it.
-    const r = spawnSync(`npm run ${script}`, {
-        cwd,
-        stdio: 'inherit',
-        shell: true,
-        env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
+// --- dependency install with retries -------------------------------------------------------------
+//
+// `release:install` downloads prebuilt native binaries (better-sqlite3 above all). When that download
+// times out (`prebuild-install warn install Request timed out`), npm falls back to compiling from
+// source, and a server without a C/C++ toolchain ends in a raw `gyp ERR!`. The same command run a
+// minute later usually succeeds, so it is retried with backoff; if it still fails, the operator gets a
+// plain explanation instead of the compiler log.
+
+const INSTALL_ATTEMPTS = 3;
+// Waits before the 2nd and 3rd attempts. CREATE_WORDJS_RETRY_BASE_MS scales them (tests use a few ms).
+const INSTALL_RETRY_BASE_MS = /^\d+$/.test(process.env.CREATE_WORDJS_RETRY_BASE_MS || '') ? Number(process.env.CREATE_WORDJS_RETRY_BASE_MS) : 15000;
+// Left in a site whose dependency install did not finish; `create-wordjs <dir>` resumes from it.
+const INCOMPLETE_MARKER = '.create-wordjs-incomplete';
+
+/** What a failed install's output says about why it failed. */
+function classifyInstallFailure(output) {
+    const text = String(output || '');
+    const prebuiltTimeout = /prebuild-install (warn|WARN|ERR!).*(timed out|ETIMEDOUT|ECONNRESET|ESOCKETTIMEDOUT|EAI_AGAIN|ENOTFOUND|socket hang up)/i.test(text);
+    const nativeBuild = /gyp ERR!|node-gyp|not found: (make|python)|No (C|C\+\+) compiler|g\+\+: (command )?not found|Could not find any Python/i.test(text);
+    const network = prebuiltTimeout || /\b(ETIMEDOUT|ECONNRESET|ESOCKETTIMEDOUT|EAI_AGAIN|ENOTFOUND|ECONNREFUSED)\b|network (timeout|request)|Request timed out/i.test(text);
+    return { prebuiltTimeout, nativeBuild, network };
+}
+
+/** The operator-facing explanation of an install that failed every attempt. */
+function installFailureAdvice(cwd, why, attempts) {
+    const lines = [`The runtime dependencies could not be installed (${attempts} attempt${attempts === 1 ? '' : 's'}).`];
+    if (why.prebuiltTimeout || why.nativeBuild) {
+        lines.push(
+            why.prebuiltTimeout
+                ? 'Downloading a prebuilt native module (better-sqlite3) timed out, and npm then tried to compile it'
+                : 'A native module (better-sqlite3) had to be compiled from source,',
+            why.prebuiltTimeout
+                ? 'from source, which needs a C/C++ toolchain and Python that this machine does not have.'
+                : 'which needs a C/C++ toolchain and Python that this machine does not have.',
+        );
+    } else if (why.network) {
+        lines.push('The package downloads kept failing on the network (timeouts or refused connections).');
+    }
+    lines.push(
+        '',
+        'Nothing is lost — the site files are in place. Either:',
+        `  • retry later (the download usually works on a second try):  cd ${cwd} && npm run release:install`,
+        '    (or run the same create-wordjs command again: it resumes this install), or',
+        '  • install a build toolchain so the module can be compiled locally, then retry:',
+        '      Debian/Ubuntu:  sudo apt-get install -y build-essential python3',
+        '      Fedora/RHEL:    sudo dnf install -y gcc-c++ make python3',
+        '      Alpine:         sudo apk add build-base python3',
+    );
+    return lines.join('\n');
+}
+
+/**
+ * `npm run release:install` with up to INSTALL_ATTEMPTS attempts and growing waits between them. The
+ * output still streams to the terminal; its tail is kept to explain a failure. Returns
+ * { ok, attempts, why } — never exits, so the caller can still write what the next attempt needs.
+ */
+async function installDependencies(cwd, { attempts = INSTALL_ATTEMPTS, baseDelayMs = INSTALL_RETRY_BASE_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+    let why = { prebuiltTimeout: false, nativeBuild: false, network: false };
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        if (attempt > 1) {
+            const wait = baseDelayMs * Math.pow(3, attempt - 2);   // 15 s, then 45 s
+            console.log(`\n  ↻ Retrying the dependency install in ${Math.round(wait / 1000)} s (attempt ${attempt} of ${attempts})…\n`);
+            await sleep(wait);
+        }
+        const r = await runReleaseInstallOnce(cwd);
+        if (r.ok) return { ok: true, attempts: attempt, why };
+        why = classifyInstallFailure(r.output);
+        const reason = why.prebuiltTimeout ? 'the prebuilt binary download timed out'
+            : why.nativeBuild ? 'a native module could not be compiled'
+                : why.network ? 'a network error' : (r.error ? r.error : `exit code ${r.status}`);
+        console.error(`\n  ⚠️  Dependency install attempt ${attempt} of ${attempts} failed: ${reason}.`);
+        if (r.status === 127 || (r.error && /ENOENT/.test(r.error))) return { ok: false, attempts: attempt, why, fatal: 'Is npm on your PATH?' };
+    }
+    return { ok: false, attempts, why };
+}
+
+function runReleaseInstallOnce(cwd) {
+    return new Promise((resolve) => {
+        let tail = '';
+        const keep = (b) => { tail = (tail + b.toString()).slice(-256 * 1024); };
+        // A single fixed command string with shell:true resolves npm/npm.cmd on every platform (and
+        // avoids Node's DEP0190 warning about args-array + shell). No user input goes into it.
+        const child = spawn('npm run release:install', { cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+        child.stdout.on('data', (b) => { process.stdout.write(b); keep(b); });
+        child.stderr.on('data', (b) => { process.stderr.write(b); keep(b); });
+        child.on('error', (e) => resolve({ ok: false, status: null, error: String(e && e.message || e), output: tail }));
+        child.on('close', (code) => resolve({ ok: code === 0, status: code, output: tail }));
     });
-    if (r.error) fail(`Could not run "npm run ${script}": ${r.error.message}`, 'Is npm on your PATH?');
-    if (r.status !== 0) fail(`"npm run ${script}" exited with code ${r.status}.`, `Fix the error above, then re-run it manually inside ${cwd}.`);
 }
 
 // First non-internal IPv4 — a sensible default advertise/host when the user doesn't pass one.
@@ -712,9 +795,10 @@ function underAny(p, roots) {
  * written into the file itself: whoever later finds it in /etc/sysctl.d/ should not have to guess why
  * it is there or what it costs.
  */
-function sysctlDropIn(start, { http = false } = {}) {
+function sysctlDropIn(start, { http = false, mail = false, ports = [] } = {}) {
     const lines = [
         `# WordJS: allow unprivileged processes to bind ports from ${start} up (written by create-wordjs --systemd).`,
+        ...ports.map((p) => `#   ${p.port}: ${p.why}`),
         '#',
         '# This is NOT a grant to WordJS alone. It lowers the privileged-port floor for EVERY unprivileged',
         `# process in this network namespace, so any local user or service may bind ports ${start}-1023 too, and`,
@@ -725,6 +809,9 @@ function sysctlDropIn(start, { http = false } = {}) {
     if (!http && start > 80) {
         lines.push(`# Let's Encrypt HTTP-01 (acme.http01Port: 80 in wordjs-config.json) needs this lowered to 80.`);
     }
+    if (!mail && start > 25) {
+        lines.push('# Receiving mail (the mail-server plugin, SMTP on port 25) needs this lowered to 25: re-run with --mail.');
+    }
     lines.push(
         '#',
         `# Install: sudo install -o root -g root -m 0644 ${SYSCTL_DROPIN_FILE} /etc/sysctl.d/ && sudo sysctl --system`,
@@ -744,8 +831,14 @@ function sysctlDropIn(start, { http = false } = {}) {
  *   configuredPort  the port the site's config already sets (gatewayPort), or null.
  *   acmeHttp01Port  acme.http01Port from the config, or null: monolith.js binds it beside an HTTPS
  *                   listener, so it counts toward the privileged-port floor.
+ *   mail            the site receives mail: the mail-server plugin listens for SMTP on 25.
+ *
+ * The floor goes as low as every port the site will bind, not only the ones configured today: the
+ * administrator turns on Let's Encrypt (HTTP-01 on 80) and installs the mail server from the panel,
+ * and neither may then need a file edited as root. An HTTPS site already on a port below 1024 counts
+ * 80 for that reason; a site on a high port gets no drop-in (it sits behind a proxy, or wants none).
  */
-function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER, port = null, configuredPort = null, acmeHttp01Port = null, http = false }) {
+function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER, port = null, configuredPort = null, acmeHttp01Port = null, http = false, mail = false }) {
     for (const [what, p] of [['site directory', installDir], ['node binary', nodePath]]) {
         if (!unitSafePath(p)) {
             const err = new Error(`The ${what} path "${p}" cannot go into a systemd unit as is: it must be absolute, without spaces, quotes, backslashes, "%" or "$".`);
@@ -759,10 +852,14 @@ function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER,
     if (problem) { const err = new Error(problem.message); err.hint = problem.hint; throw err; }
 
     const publicPort = port || configuredPort || 3000;
-    const bound = [publicPort];
-    if (!http && acmeHttp01Port) bound.push(acmeHttp01Port);
-    const privileged = bound.filter((p) => p < PRIVILEGED_PORT_LIMIT);
-    const sysctlStart = privileged.length ? Math.min(...privileged) : null;
+    const bound = [{ port: publicPort, why: 'the site (its public port)' }];
+    if (!http && acmeHttp01Port) bound.push({ port: acmeHttp01Port, why: "Let's Encrypt HTTP-01 (acme.http01Port)" });
+    if (!http && publicPort < PRIVILEGED_PORT_LIMIT && !bound.some((b) => b.port === 80)) {
+        bound.push({ port: 80, why: "Let's Encrypt HTTP-01, when it is turned on in Admin -> Security" });
+    }
+    if (mail) bound.push({ port: 25, why: 'incoming mail (the mail-server plugin, SMTP)' });
+    const privileged = bound.filter((b) => b.port < PRIVILEGED_PORT_LIMIT).sort((a, b) => a.port - b.port);
+    const sysctlStart = privileged.length ? privileged[0].port : null;
 
     // Two hardening directives depend on WHERE things are, and each is dropped (with a warning) rather
     // than shipped in a shape that cannot start: ProtectHome= hides /home, /root and /run/user, which
@@ -838,7 +935,9 @@ function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER,
 
     return {
         unit,
-        sysctl: sysctlStart ? { start: sysctlStart, content: sysctlDropIn(sysctlStart, { http }) } : null,
+        sysctl: sysctlStart
+            ? { start: sysctlStart, ports: privileged.map((b) => b.port), content: sysctlDropIn(sysctlStart, { http, mail, ports: privileged }) }
+            : null,
         publicPort,
         warnings,
     };
@@ -860,7 +959,7 @@ function systemdInstallSteps({ installDir, user = DEFAULT_SERVICE_USER, built, h
     // `install -o root -g root -m 0644` and not `cp`: root takes the staged file's CONTENT into a file it
     // creates itself, root-owned and not writable by anyone else, whatever the staged copy's mode was.
     if (built.sysctl) {
-        step(`Let it bind port ${built.publicPort} without a capability (read the trade-off in the file first):`,
+        step(`Let it bind ${built.sysctl.ports.length > 1 ? `ports ${built.sysctl.ports.join(', ')}` : `port ${built.sysctl.start}`} without a capability (read the trade-off in the file first):`,
             `sudo install -o root -g root -m 0644 ${staged(SYSCTL_DROPIN_FILE)} /etc/sysctl.d/${SYSCTL_DROPIN_FILE} && sudo sysctl --system`);
     } else if (upgrade) {
         // A site that moved to a high port (behind a proxy, say) no longer needs the floor lowered, and an
@@ -969,12 +1068,14 @@ function emitSystemd(installDir, opts) {
         configuredPort: Number(appConfig.gatewayPort || gwConfig.gatewayPort) || null,
         acmeHttp01Port: Number(appConfig.acme && appConfig.acme.http01Port) || null,
         http: opts.http,
+        // An installed mail server (an upgrade) receives on 25 whether or not --mail was given.
+        mail: !!opts.mail || fs.existsSync(path.join(installDir, 'backend', 'plugins', 'mail-server')),
     });
     const stageDir = createSystemdStagingDir();
     const written = writeSystemdFiles(stageDir, built);
     console.log('');
     console.log(`   systemd unit staged: ${written.unitPath}`);
-    if (written.sysctlPath) console.log(`   sysctl drop-in for port ${built.publicPort}: ${written.sysctlPath}`);
+    if (written.sysctlPath) console.log(`   sysctl drop-in for ports from ${built.sysctl.start} up (${built.sysctl.ports.join(', ')}): ${written.sysctlPath}`);
     console.log('   (staged outside the site on purpose: the service account will own the site, and must not be able to edit what root installs)');
     for (const w of built.warnings) console.log(`   ⚠️  ${w}`);
     console.log('');
@@ -1178,7 +1279,13 @@ async function upgrade(opts) {
         // Re-sync dependencies (a new version may add/upgrade packages). Skippable for a code-only swap.
         if (opts.install) {
             console.log('\n📦 Syncing runtime dependencies (npm run release:install)…\n');
-            runNpmScript('release:install', installDir);
+            const installed = await installDependencies(installDir);
+            if (!installed.ok) {
+                restoreInstallOwner(installDir, siteOwner);
+                // The new code is in place and the unit matches it: stage it for when the install is re-run.
+                if (opts.systemd) { try { emitSystemd(installDir, opts); } catch { /* the advice below still applies */ } }
+                fail(installFailureAdvice(opts.dir === '.' ? installDir : opts.dir, installed.why, installed.attempts), installed.fatal);
+            }
         } else {
             console.log('\n  --no-install: skipped dependency sync. Run "npm run release:install" yourself if deps changed.');
         }
@@ -1229,7 +1336,8 @@ async function scaffoldBundle(opts, targetDir) {
     }
 
     console.log('\n📦 Installing runtime dependencies (this downloads prebuilt binaries — a few minutes)…\n');
-    runNpmScript('release:install', targetDir);
+    const installed = await installDependencies(targetDir);
+    if (!installed.ok) fail(installFailureAdvice(opts.dir, installed.why, installed.attempts), installed.fatal);
 }
 
 // `create-wordjs gateway` — set this machine up as the cluster gateway: install, mint the cluster CA +
@@ -1347,28 +1455,37 @@ async function main() {
     if (opts.mode === 'join') return join(opts);
     const targetDir = path.resolve(process.cwd(), opts.dir);
 
+    // A site whose dependency install failed earlier is RESUMED: its release files are already extracted
+    // (and were verified then), so only the install and what follows it run again. The marker is only
+    // ever written by this installer, into a directory it extracted a bundle into.
+    const resuming = fs.existsSync(path.join(targetDir, INCOMPLETE_MARKER));
+
     // Refuse to scribble over anything that already exists (an existing EMPTY dir is fine).
-    if (fs.existsSync(targetDir)) {
+    if (!resuming && fs.existsSync(targetDir)) {
         if (!fs.statSync(targetDir).isDirectory()) fail(`"${opts.dir}" already exists and is not a directory.`);
         if (fs.readdirSync(targetDir).length > 0) {
             fail(`Directory "${opts.dir}" already exists and is not empty.`, 'Pick a new directory name, or empty it first.');
         }
-    } else {
+    } else if (!resuming) {
         fs.mkdirSync(targetDir, { recursive: true });
     }
 
     console.log('\n🚀 create-wordjs\n');
 
-    // 1) Obtain the release ZIP (local path, https URL, or GitHub latest/tagged release) and verify
-    //    its SHA-256 before anything is extracted.
-    const { zipPath, cleanup } = await obtainBundleZip(opts);
+    if (resuming) {
+        console.log(`  Resuming the unfinished install in ${targetDir} (the release files are already in place).`);
+    } else {
+        // 1) Obtain the release ZIP (local path, https URL, or GitHub latest/tagged release) and verify
+        //    its SHA-256 before anything is extracted.
+        const { zipPath, cleanup } = await obtainBundleZip(opts);
 
-    // 2) Extract + sanity-check that this really is a WordJS release bundle.
-    console.log(`  Extracting into ${targetDir}…`);
-    try {
-        extractZip(zipPath, targetDir);
-    } finally {
-        cleanup();
+        // 2) Extract + sanity-check that this really is a WordJS release bundle.
+        console.log(`  Extracting into ${targetDir}…`);
+        try {
+            extractZip(zipPath, targetDir);
+        } finally {
+            cleanup();
+        }
     }
     const pkgPath = path.join(targetDir, 'package.json');
     let pkg = {};
@@ -1378,13 +1495,26 @@ async function main() {
             `Expected a wordjs-*.zip from https://github.com/${REPO}/releases.`);
     }
 
-    // 3) Install runtime dependencies (pre-compiled bundle — no build step).
+    // 3) Install runtime dependencies (pre-compiled bundle — no build step), retried with backoff. The
+    //    marker stays until it succeeds, so running this same command again resumes from here.
+    fs.writeFileSync(path.join(targetDir, INCOMPLETE_MARKER), 'The dependency install of this site has not finished. Run "npm run release:install" here, or the same create-wordjs command again.\n');
     console.log('\n📦 Installing runtime dependencies (this downloads prebuilt binaries — a few minutes)…\n');
-    runNpmScript('release:install', targetDir);
+    const installed = await installDependencies(targetDir);
 
-    // 4) Default to self-signed HTTPS unless the user explicitly asked for HTTP.
+    // 4) Default to self-signed HTTPS unless the user explicitly asked for HTTP. Written whether or not
+    //    the install worked: the config belongs to the site, not to its node_modules.
     if (!opts.http) ensureHttpsConfig(targetDir);
 
+    if (!installed.ok) {
+        // Leave everything the next attempt needs: the files, the config and (with --systemd) the unit,
+        // none of which depends on node_modules. Only the install has to run again.
+        if (opts.systemd) {
+            try { emitSystemd(targetDir, opts); } catch (e) { console.error(`  (systemd unit not staged: ${e && e.message || e})`); }
+        }
+        fail(installFailureAdvice(opts.dir, installed.why, installed.attempts), installed.fatal);
+    }
+    fs.rmSync(path.join(targetDir, INCOMPLETE_MARKER), { force: true });
+
     const proto = opts.http ? 'http' : 'https';
     const line = '━'.repeat(64);
 
@@ -1471,4 +1601,5 @@ module.exports = {
     copyMerge, PRESERVE_ON_UPGRADE,
     sysctlDropIn, serviceUserProblem, systemdPreflight, createSystemdStagingDir, LOW_PORT_ADVICE, HELP, installedFileMode,
     installDirOwner, restoreInstallOwner,
+    installDependencies, classifyInstallFailure, installFailureAdvice, INCOMPLETE_MARKER,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-wordjs",
-    "version": "2.7.0",
+    "version": "2.9.0",
     "description": "Create a WordJS site with one command — the self-hosted CMS where third-party plugins run in an OS-isolated process with per-capability permission grants. SSR/SEO out of the box, SQLite by default, no PHP.",
     "license": "MIT",
     "author": "Jaime Martinez (https://github.com/jaimemartinez)",
@@ -14,7 +14,7 @@
         "LICENSE"
     ],
     "engines": {
-        "node": ">=20.9.0"
+        "node": ">=22.0.0"
     },
     "repository": {
         "type": "git",