create-zfb 0.1.0-next.8 → 0.1.0-next.80

package/README.md

@@ -11,3 +11,5 @@ npm create zfb@latest my-site
 ```
 
 This creates a new project directory `my-site/` bootstrapped from the built-in `basic-blog` template. For full documentation, configuration options, and CLI reference, see the [`@takazudo/zfb` docs](https://takazudomodular.com/pj/zudo-front-builder/).
+
+> **pnpm 11 note:** pnpm 11's `minimumReleaseAge` may install a previous release of `create-zfb` within ~48h of any new release. If `create-zfb` warns about a stale install at startup, re-run with `pnpm create zfb@latest --config.minimumReleaseAge=0` or `npm create zfb@latest`.

package/bin/create-zfb.mjs

@@ -1,13 +1,52 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
+import { constants as osConstants } from "node:os";
 import { dirname, join } from "node:path";
+import { checkForNewerVersion } from "./version-check.mjs";
+import { formatSpawnErrorMessage } from "./spawn-error-message.mjs";
 
 const require = createRequire(import.meta.url);
 
+try {
+  const ownPkg = require("../package.json");
+  const staleWarning = await checkForNewerVersion({ version: ownPkg.version });
+  if (staleWarning) {
+    process.stderr.write(staleWarning);
+  }
+} catch {
+  // silently skip on any error: network failure, timeout (AbortError), parse error, etc.
+}
+
 const zfbPkgJson = require.resolve("@takazudo/zfb/package.json");
 const zfbBin = join(dirname(zfbPkgJson), "bin", "zfb.mjs");
 
 const args = ["new", ...process.argv.slice(2)];
 const result = spawnSync(process.execPath, [zfbBin, ...args], { stdio: "inherit" });
+
+// Surface spawn failures clearly. Without this check, an ENOENT/EACCES
+// failure to even launch the resolved @takazudo/zfb bin/zfb.mjs (e.g. a
+// broken resolution, a wiped node_modules, an unreadable file) silently
+// exits 1 with no message — a broken @takazudo/zfb resolution looks like a
+// mystery exit. Mirrors packages/zfb/bin/zfb.mjs's child.on("error")
+// handling (issues #447/#441).
+if (result.error) {
+  process.stderr.write(formatSpawnErrorMessage(result.error, zfbBin));
+  process.exit(1);
+}
+
+if (result.signal) {
+  // Re-raise the child's termination signal on ourselves so the caller sees
+  // the real cause of death (e.g. WIFSIGNALED), not a plain exit code 1.
+  // Mirrors the wrapper behaviour in packages/zfb/bin/zfb.mjs.
+  try {
+    process.kill(process.pid, result.signal);
+  } catch {
+    // Signal cannot be re-raised on this platform (Windows emulation).
+  }
+  // Reached only if the re-raised signal did not terminate us — fall back
+  // to the shell's 128+n convention for death-by-signal.
+  const signum = osConstants.signals[result.signal];
+  process.exit(signum ? 128 + signum : 1);
+}
 process.exit(result.status ?? 1);

package/bin/spawn-error-message.mjs

@@ -0,0 +1,24 @@
+/**
+ * Build an actionable stderr message for a `spawnSync()` launch failure
+ * (`result.error` set — e.g. ENOENT/EACCES trying to invoke the resolved
+ * `@takazudo/zfb` launcher). Extracted as a pure function (no top-level
+ * side effects, unlike create-zfb.mjs) so it can be unit tested directly,
+ * mirroring the version-check.mjs pattern in this package.
+ *
+ * Mirrors packages/zfb/bin/zfb.mjs's `child.on("error", ...)` messaging
+ * (issues #447/#441) so both wrappers give the same reinstall guidance.
+ *
+ * @param {NodeJS.ErrnoException} error
+ * @param {string} zfbBin - absolute path to the resolved bin/zfb.mjs launcher
+ * @returns {string}
+ */
+export function formatSpawnErrorMessage(error, zfbBin) {
+  if (error.code === "EACCES") {
+    return (
+      "[create-zfb] not executable; was the install corrupt?\n" +
+      `      ${zfbBin}\n` +
+      "      Try reinstalling: npm install --include=optional\n"
+    );
+  }
+  return `[create-zfb] failed to spawn @takazudo/zfb: ${error.message}\n` + `      ${zfbBin}\n`;
+}

package/bin/version-check.mjs

@@ -0,0 +1,92 @@
+// Extracted from create-zfb.mjs so compareSemver and checkForNewerVersion can
+// be unit-tested directly. create-zfb.mjs has side-effecting top-level code
+// (fetch, spawnSync), so importing it in a test would run the whole CLI —
+// this module has none, and is safe to import.
+
+// Returns -1 if a < b, 0 if a === b, 1 if a > b.
+// Handles prerelease suffixes: 0.1.0-next.6 < 0.1.0-next.8 < 0.1.0
+export function compareSemver(a, b) {
+  const splitRelease = (v) => {
+    // Drop SemVer build metadata (`+...`) before splitting — it is ignored
+    // for precedence and would otherwise yield NaN numeric parts.
+    const [main, pre] = v.split("+")[0].split(/-(.+)/, 2);
+    return { parts: main.split(".").map(Number), pre: pre ?? null };
+  };
+  const ra = splitRelease(a);
+  const rb = splitRelease(b);
+  for (let i = 0; i < Math.max(ra.parts.length, rb.parts.length); i++) {
+    const pa = ra.parts[i] ?? 0;
+    const pb = rb.parts[i] ?? 0;
+    if (pa !== pb) return pa < pb ? -1 : 1;
+  }
+  // same numeric parts — prerelease is less than no prerelease (semver rule)
+  if (ra.pre !== null && rb.pre === null) return -1;
+  if (ra.pre === null && rb.pre !== null) return 1;
+  if (ra.pre !== null && rb.pre !== null) {
+    // Compare dot-separated prerelease identifiers per semver: numeric
+    // identifiers compare numerically (so next.9 < next.10), numeric ranks
+    // below alphanumeric, and a shorter prefix ranks lower. Plain string
+    // `<`/`>` would order next.10 before next.9 lexicographically.
+    const sa = ra.pre.split(".");
+    const sb = rb.pre.split(".");
+    for (let i = 0; i < Math.max(sa.length, sb.length); i++) {
+      if (sa[i] === undefined) return -1;
+      if (sb[i] === undefined) return 1;
+      const na = /^\d+$/.test(sa[i]);
+      const nb = /^\d+$/.test(sb[i]);
+      if (na && nb) {
+        const da = Number(sa[i]);
+        const db = Number(sb[i]);
+        if (da !== db) return da < db ? -1 : 1;
+      } else if (na !== nb) {
+        return na ? -1 : 1;
+      } else if (sa[i] !== sb[i]) {
+        return sa[i] < sb[i] ? -1 : 1;
+      }
+    }
+  }
+  return 0;
+}
+
+/**
+ * Checks the npm registry for a newer create-zfb release than `version` and
+ * returns a warning message if the installed version is stale, or null if
+ * up to date. Never throws — network failure, timeout (AbortError), and
+ * parse errors are all treated as "no warning" so a registry hiccup can
+ * never block scaffolding. `fetchFn` and `timeoutMs` are injectable so tests
+ * don't need to hit the real network or wait out the real timeout.
+ */
+export async function checkForNewerVersion({ version, fetchFn = fetch, timeoutMs = 1500 } = {}) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchFn("https://registry.npmjs.org/create-zfb/latest", {
+        signal: controller.signal,
+        headers: {
+          "User-Agent": `create-zfb/${version}`,
+          Accept: "application/json",
+        },
+      });
+      if (!res.ok) return null;
+      const data = await res.json();
+      const latest = data?.version;
+      if (typeof latest !== "string" || typeof version !== "string") return null;
+      if (compareSemver(version, latest) >= 0) return null;
+      return (
+        `[create-zfb] You are running create-zfb@${version} but @latest is ${latest}.\n` +
+        `[create-zfb] pnpm 11's minimumReleaseAge may have downgraded the install.\n` +
+        `[create-zfb] Re-run with: pnpm create zfb@latest --config.minimumReleaseAge=0\n` +
+        `[create-zfb] Or use: npm create zfb@latest\n`
+      );
+    } finally {
+      // Keep the abort signal armed across both the header and body reads.
+      // Only cancel the timer once the body has been fully consumed (or on
+      // any error path), so a proxy that stalls after headers cannot hang
+      // the scaffolder indefinitely.
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zfb",
-  "version": "0.1.0-next.8",
+  "version": "0.1.0-next.80",
   "private": false,
   "type": "module",
   "description": "Scaffold a new zfb static-site project: `npm create zfb@latest my-site`",
@@ -27,11 +27,22 @@
   },
   "files": [
     "bin",
+    "!bin/__tests__",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
-    "@takazudo/zfb": "0.1.0-next.8"
+    "@takazudo/zfb": "0.1.0-next.80"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }