create-zerotal 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -8,6 +8,27 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.6.3] — 2026-08-15
+
+### Added
+
+- **The scaffolder says when it is not the published one.** `bun create zerotal` can serve a
+  copy cached from a previous run instead of fetching the current scaffolder, and a stale
+  scaffolder is worse than an old one: it stamps the dependency ranges *it* shipped with, so
+  the new project is created against versions that were current months ago — while the install
+  log shows today's framework resolving happily inside those ranges. Everything reads as
+  correct and the wrong packages are installed.
+
+  Observed with a cached 1.5.0, which pinned an Inertia major whose client-side DevTools hooks
+  do not exist, on a machine whose registry had 1.6.2. Nothing said so, because nothing was
+  looking.
+
+  The check now runs against the registry, and names the fix:
+  `bunx create-zerotal@latest <name>`. It costs no perceived time — the request goes out before
+  the banner and is read after the prompts — and it is advisory: an offline machine, a
+  firewalled registry and a slow network all mean "no answer", and no answer never stops
+  anyone creating an app.
+
 ## [1.6.1] — 2026-08-15
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zerotal",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "Create a new Zerotal application",
   "license": "MIT",
   "maturity": "stable",

package/src/index.ts

@@ -10,8 +10,18 @@
 import { resolve } from 'node:path';
 import { printBanner, ask, choose, log, info, warn, step, dim, c } from './prompts.ts';
 import { scaffold, install, type Template, type Database } from './scaffold.ts';
+import { newerScaffolderVersion } from './staleness.ts';
+
+/** This scaffolder's own version, read from the manifest that ships beside it. */
+const ZT_SELF_VERSION: string = (
+  (await Bun.file(new URL('../package.json', import.meta.url)).json()) as { version: string }
+).version;
 
 async function main(): Promise<void> {
+  // Started before the banner and awaited after the prompts, so the check costs
+  // no perceived time at all — the answer arrives while a human is reading.
+  const newerScaffolder = newerScaffolderVersion(ZT_SELF_VERSION);
+
   printBanner();
 
   // ── Project name ────────────────────────────────────────────────────────────
@@ -89,6 +99,19 @@ async function main(): Promise<void> {
 
   // ── Scaffold ────────────────────────────────────────────────────────────────
   log('');
+
+  // Answered by now: the request went out before the first prompt, and the
+  // prompts take human time. Said before anything is written, so re-running with
+  // the current scaffolder costs nothing but a Ctrl-C.
+  const newer = await newerScaffolder;
+  if (newer) {
+    warn(`This scaffolder is ${ZT_SELF_VERSION}; ${newer} is published.`);
+    dim(`A cached copy stamps the dependency ranges it shipped with, so a new`);
+    dim(`project can be created against versions that are no longer current.`);
+    dim(`${c.bold}bunx create-zerotal@latest ${name}${c.reset}${c.gray} always fetches the published one.`);
+    log('');
+  }
+
   step(`Scaffolding ${c.bold}${name}${c.reset} (${template})…`);
 
   await scaffold({ name, template, db, target });

package/src/scaffold.ts

@@ -13,7 +13,7 @@ export type Template = 'minimal' | 'api' | 'admin' | 'flow' | 'react' | 'vue';
 // "^1.1.0" found for specifier "zerotal"` — the first thing anyone trying the
 // framework saw. `scaffold.test.ts` now asserts the two agree, so CI fails rather
 // than the user's install.
-export const ZT_VERSION = "^1.6.1";
+export const ZT_VERSION = "^1.6.3";
 
 export interface ScaffoldOptions {
   name:     string;

package/src/staleness.ts

@@ -0,0 +1,77 @@
+/**
+ * Noticing that this scaffolder is not the current one.
+ *
+ * `bun create zerotal` can serve a copy cached from a previous run rather than
+ * fetching the published scaffolder, and a stale scaffolder is worse than an old
+ * one: it stamps the dependency ranges *it* was built with, so a new project is
+ * created against versions that were current months ago while the install log
+ * shows today's framework resolving inside those ranges. Everything looks right
+ * and the wrong adapter is installed.
+ *
+ * That happened with a cached 1.5.0, which pinned an Inertia major the DevTools
+ * extension cannot read. Nothing said so, because nothing was looking.
+ *
+ * @module
+ */
+
+/** Where the published version is read from. */
+export const REGISTRY_LATEST_URL = "https://registry.npmjs.org/create-zerotal/latest";
+
+/** How long to wait before scaffolding without an answer. */
+export const REGISTRY_TIMEOUT_MS = 2_000;
+
+/**
+ * Compare two dot-separated versions numerically.
+ *
+ * Pre-release suffixes are ignored — `1.6.3-rc.1` compares as `1.6.3` — because
+ * the only decision this drives is whether to suggest re-running, and suggesting
+ * it once too often is cheaper than reimplementing SemVer here.
+ *
+ * @returns Negative when `a` is older, positive when newer, `0` when equal.
+ */
+export function compareVersions(a: string, b: string): number {
+  const parts = (v: string): number[] =>
+    v
+      .split("-")[0]!
+      .split(".")
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * The published version, when it is newer than the one running.
+ *
+ * @param current - This scaffolder's own version.
+ * @param options - Seams for tests, and for pointing at a private registry.
+ * @returns The newer version, or `null` — including whenever the check cannot be
+ *   made. An offline machine, a firewalled registry and a slow network all mean
+ *   "no answer", and no answer must never stop someone creating an app.
+ *
+ * @example
+ * const newer = await newerScaffolderVersion(ZT_VERSION);
+ * if (newer) warn(`A newer scaffolder exists (${newer}).`);
+ */
+export async function newerScaffolderVersion(
+  current: string,
+  options: { fetchImpl?: typeof fetch; timeoutMs?: number; url?: string } = {},
+): Promise<string | null> {
+  const doFetch = options.fetchImpl ?? fetch;
+  const url = options.url ?? REGISTRY_LATEST_URL;
+  const timeoutMs = options.timeoutMs ?? REGISTRY_TIMEOUT_MS;
+
+  try {
+    const response = await doFetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) return null;
+    const { version } = (await response.json()) as { version?: unknown };
+    if (typeof version !== "string" || version === "") return null;
+    return compareVersions(version, current) > 0 ? version : null;
+  } catch {
+    return null;
+  }
+}