uniweb 0.87.3 → 0.88.0

package/src/templates/resolver.js

@@ -2,93 +2,48 @@
  * Template resolver - parses template identifiers and determines source type
  */
 
-import { readFileSync, statSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
+import { loadFrameworkIndex } from '../versions.js'
 
 // Built-in templates (programmatic, not file-based)
 export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
 
 /**
- * Load the official template metadata map — `{ id: { name, description,
- * tags } }`, keyed by template id.
- *
- * There are two sources of truth depending on where the CLI is running:
+ * THE OFFICIAL TEMPLATES THIS CLI SCAFFOLDS — one snapshot.
  *
- * 1. **Local dev inside the Uniweb monorepo** — the authoritative file
- *    is `framework/templates/manifest.json`. Adding a new template
- *    there makes it immediately reachable from any locally-run CLI
- *    without republishing. This is the only path that matters for
- *    `node scripts/framework/sandbox.js create`.
+ * `../framework-index.json` is written when the CLI is published: the
+ * templates' manifest (`{ id: { name, description, tags } }`) and, in
+ * `packages`, the `@uniweb/templates` version whose release holds their
+ * content. The interactive picker, `uniweb template list` and the download in
+ * `create` all read it, so the CLI offers exactly the templates it can fetch,
+ * and fetches the content released with the package versions it pins. A CLI
+ * goes on scaffolding the templates it was published with until it is
+ * updated — consistent, not newest.
  *
- * 2. **Published CLI (npm-installed)** — the monorepo isn't on disk, so
- *    we read the vendored framework index at `../framework-index.json`,
- *    which the publish pipeline rewrites just before `pnpm publish` runs,
- *    copying the manifest's `templates` verbatim. The framework index is a
- *    single snapshot file that also carries `@uniweb/*` package versions
- *    (consumed by versions.js), so both the template list and the version
- *    resolver share one source of truth.
+ * ⛔ Until 2026-10-08 a CLI run from a source checkout listed the templates
+ * repo's working manifest instead, and every CLI downloaded from the `latest`
+ * release. So a CLI could offer a template its release did not hold, and
+ * scaffold content newer than the packages it pinned: a template using a kit
+ * export the CLI's kit did not have yet failed to build.
  *
- * When both sources are available (local dev with a committed snapshot),
- * the live workspace manifest wins so newly-added templates are visible
- * without waiting for a CLI republish.
- *
- * Both files store `templates` as the same `{ id: { name, description,
- * tags } }` shape, so one map feeds both name-resolution
- * (OFFICIAL_TEMPLATES) and the interactive picker (buildTemplateChoices) —
- * neither hardcodes a list. (An earlier version returned only the keys and
- * left the `create` picker with its own hardcoded array, which silently
- * drifted out of sync whenever a template was added.)
+ * (An earlier version still hardcoded the picker's list, which silently
+ * drifted whenever a template was added — the reason no list is written here.)
  */
-function loadOfficialTemplateMap() {
-  // Local dev: framework/templates/manifest.json relative to this file
-  // at framework/cli/src/templates/resolver.js
-  const workspaceManifest = join(
-    __dirname,
-    '..',
-    '..',
-    '..',
-    'templates',
-    'manifest.json'
-  )
-  const picked = tryReadTemplateMap(workspaceManifest)
-  if (picked) return picked
-
-  // Published CLI fallback: the framework index snapshot, one directory
-  // up at framework/cli/src/framework-index.json.
-  const indexPath = join(__dirname, '..', 'framework-index.json')
-  const fromIndex = tryReadTemplateMap(indexPath)
-  if (fromIndex) return fromIndex
-
-  // If both sources fail, return an empty map rather than a stale
-  // hardcoded list. An unknown template name then falls through to
-  // the npm `@uniweb/template-<name>` lookup path, which is the
-  // intended behavior for third-party templates.
-  return {}
-}
-
-function tryReadTemplateMap(path) {
-  try {
-    if (!statSync(path).isFile()) return null
-    const data = JSON.parse(readFileSync(path, 'utf8'))
-    if (data && data.templates && typeof data.templates === 'object') {
-      return data.templates
-    }
-  } catch {}
-  return null
-}
+const INDEX = loadFrameworkIndex()
 
-// Official template metadata keyed by id. Derived from manifest.json (local
-// dev) or framework-index.json (published CLI) at module load time — see
-// loadOfficialTemplateMap() for details. Read once per process; to reflect a
-// just-added template, restart the CLI or rerun the scaffolder.
-export const OFFICIAL_TEMPLATE_MAP = loadOfficialTemplateMap()
+// Official template metadata keyed by id. Empty when the snapshot did not load:
+// an unknown name then falls through to the npm `@uniweb/template-<name>`
+// lookup, the path for third-party templates, rather than to a stale list.
+export const OFFICIAL_TEMPLATE_MAP =
+  INDEX?.templates && typeof INDEX.templates === 'object' ? INDEX.templates : {}
 
 // Official template ids, e.g. ['marketing', 'docs', 'academic', …].
 export const OFFICIAL_TEMPLATES = Object.keys(OFFICIAL_TEMPLATE_MAP)
 
+// The release the official templates download from — `v<@uniweb/templates
+// version>`, the repo's tag — or null when the snapshot names none.
+const TEMPLATES_VERSION = INDEX?.packages?.['@uniweb/templates']?.version
+export const OFFICIAL_TEMPLATES_RELEASE = TEMPLATES_VERSION ? `v${TEMPLATES_VERSION}` : null
+
 // Built-in (programmatic) picker entries — not in the manifest; the CLI
 // generates these itself. "Blank" trails the official templates.
 const BUILTIN_LEAD_CHOICES = [
@@ -128,6 +83,24 @@ export function buildTemplateChoices() {
   return [...BUILTIN_LEAD_CHOICES, ...official, BLANK_CHOICE]
 }
 
+/**
+ * How many options the `create` picker shows at once: all of them, when the
+ * terminal has the rows. prompts shows 10 by default and scrolls the rest, and
+ * past ten choices that put most of the official templates below the fold —
+ * a template you have to scroll to find reads as one that is not there.
+ *
+ * Seven rows are kept back: the question, and the highlighted choice's
+ * description, which wraps under it when it is long.
+ *
+ * @param {number} count - the picker's choices
+ * @param {number} [rows] - the terminal's height, when it reports one
+ * @returns {number}
+ */
+export function templatePickerPageSize(count, rows = process.stdout.rows) {
+  const room = Number.isFinite(rows) && rows > 0 ? rows - 7 : count
+  return Math.max(10, Math.min(count, room))
+}
+
 /**
  * Parse a template identifier and determine its source type
  *

package/src/templates/validator.js

@@ -1,84 +1,19 @@
 /**
- * Template validation - checks template.json and compatibility
+ * Template validation — reads template.json and finds the content directories
+ *
+ * ⛔ Two things this used to do are retired [2026-10-08]:
+ *   - `compatible` (alias `uniweb`), a CLI version range a template declared. It
+ *     was checked only when a caller passed the CLI's version, and none ever
+ *     did. An official template now comes from the release its CLI was
+ *     published with (resolver.js), so it cannot be newer than that CLI.
+ *   - Unwrapping the layout of the v0.7 releases (`foundation/src/foundation.js`).
+ *     The official templates are flat, and a CLI only downloads its own release.
  */
 
 import fs from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 
-/**
- * Simple semver satisfaction check
- * Supports: >=x.y.z, ^x.y.z, ~x.y.z, x.y.z, x.y.x, *, latest
- */
-export function satisfiesVersion(version, range) {
-  if (!range || range === '*' || range === 'latest') {
-    return true
-  }
-
-  const parseVersion = (v) => {
-    const match = v.match(/^(\d+)\.(\d+)\.(\d+)/)
-    if (!match) return null
-    return {
-      major: parseInt(match[1], 10),
-      minor: parseInt(match[2], 10),
-      patch: parseInt(match[3], 10)
-    }
-  }
-
-  const current = parseVersion(version)
-  if (!current) return true // Can't parse, assume compatible
-
-  // Handle different range formats
-  if (range.startsWith('>=')) {
-    const min = parseVersion(range.slice(2))
-    if (!min) return true
-    if (current.major > min.major) return true
-    if (current.major < min.major) return false
-    if (current.minor > min.minor) return true
-    if (current.minor < min.minor) return false
-    return current.patch >= min.patch
-  }
-
-  if (range.startsWith('^')) {
-    // ^x.y.z means >=x.y.z and <(x+1).0.0
-    const min = parseVersion(range.slice(1))
-    if (!min) return true
-    if (current.major !== min.major)
-      return current.major > min.major && min.major === 0
-    if (current.minor > min.minor) return true
-    if (current.minor < min.minor) return false
-    return current.patch >= min.patch
-  }
-
-  if (range.startsWith('~')) {
-    // ~x.y.z means >=x.y.z and <x.(y+1).0
-    const min = parseVersion(range.slice(1))
-    if (!min) return true
-    if (current.major !== min.major) return false
-    if (current.minor !== min.minor) return false
-    return current.patch >= min.patch
-  }
-
-  // Exact version or x.y.x pattern
-  if (range.includes('x')) {
-    const parts = range.split('.')
-    const min = parseVersion(range.replace(/x/g, '0'))
-    if (!min) return true
-    if (parts[0] !== 'x' && current.major !== min.major) return false
-    if (parts[1] !== 'x' && current.minor !== min.minor) return false
-    return true
-  }
-
-  // Exact match
-  const exact = parseVersion(range)
-  if (!exact) return true
-  return (
-    current.major === exact.major &&
-    current.minor === exact.minor &&
-    current.patch === exact.patch
-  )
-}
-
 /**
  * Validation error with structured details
  */
@@ -95,21 +30,16 @@ export const ErrorCodes = {
   MISSING_TEMPLATE_JSON: 'MISSING_TEMPLATE_JSON',
   INVALID_TEMPLATE_JSON: 'INVALID_TEMPLATE_JSON',
   MISSING_CONTENT_DIR: 'MISSING_CONTENT_DIR',
-  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
-  VERSION_MISMATCH: 'VERSION_MISMATCH'
+  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD'
 }
 
 /**
  * Validate a template directory structure and metadata
  *
  * @param {string} templateRoot - Path to the template root (contains template.json)
- * @param {Object} options - Validation options
- * @param {string} options.uniwebVersion - Current Uniweb version to check compatibility
  * @returns {Object} Parsed and validated template metadata
  */
-export async function validateTemplate(templateRoot, options = {}) {
-  const { uniwebVersion } = options
-
+export async function validateTemplate(templateRoot) {
   // Check for template.json
   const metadataPath = path.join(templateRoot, 'template.json')
   if (!existsSync(metadataPath)) {
@@ -142,18 +72,6 @@ export async function validateTemplate(templateRoot, options = {}) {
     )
   }
 
-  // Check version compatibility (support both `compatible` and `uniweb` fields)
-  const versionRange = metadata.compatible || metadata.uniweb
-  if (uniwebVersion && versionRange) {
-    if (!satisfiesVersion(uniwebVersion, versionRange)) {
-      throw new ValidationError(
-        `Template requires Uniweb ${versionRange}, but current version is ${uniwebVersion}`,
-        ErrorCodes.VERSION_MISMATCH,
-        { required: versionRange, current: uniwebVersion }
-      )
-    }
-  }
-
   // Format 2: content template — foundation/ and/or site/ directories alongside template.json
   const contentDirs = resolveContentDirs(templateRoot, metadata)
 
@@ -178,7 +96,7 @@ export async function validateTemplate(templateRoot, options = {}) {
  *
  * @param {string} templateRoot - Root of the template (contains template.json)
  * @param {Object} metadata - Parsed template.json
- * @returns {Array<Object>} Content directories: [{ type, name, dir, foundation?, renames? }]
+ * @returns {Array<Object>} Content directories: [{ type, name, dir, foundation? }]
  */
 export function resolveContentDirs(templateRoot, metadata) {
   const dirs = []
@@ -188,29 +106,19 @@ export function resolveContentDirs(templateRoot, metadata) {
     for (const pkg of metadata.packages) {
       const dir = path.join(templateRoot, pkg.name)
       if (existsSync(dir)) {
-        const entry = {
+        dirs.push({
           type: pkg.type,
           name: pkg.name,
           dir,
           ...(pkg.foundation ? { foundation: pkg.foundation } : {})
-        }
-        if (entry.type === 'foundation' || entry.type === 'extension') {
-          applyLegacyFoundationLayout(entry)
-        }
-        dirs.push(entry)
+        })
       }
     }
   } else {
     // Standard template: look for foundation/ and site/
     const foundationDir = path.join(templateRoot, 'foundation')
     if (existsSync(foundationDir)) {
-      const entry = {
-        type: 'foundation',
-        name: 'foundation',
-        dir: foundationDir
-      }
-      applyLegacyFoundationLayout(entry)
-      dirs.push(entry)
+      dirs.push({ type: 'foundation', name: 'foundation', dir: foundationDir })
     }
 
     const siteDir = path.join(templateRoot, 'site')
@@ -221,83 +129,3 @@ export function resolveContentDirs(templateRoot, metadata) {
 
   return dirs
 }
-
-/**
- * Detect and unwrap the legacy foundation layout.
- *
- * Old templates (published in the `uniweb/templates` releases up to
- * v0.7.x) shipped foundation content nested one level deeper, with the
- * package source under `foundation/src/` and the user-authored
- * declarations file named `foundation.js`:
- *
- *     <template>/foundation/src/foundation.js
- *     <template>/foundation/src/sections/...
- *     <template>/foundation/src/components/...
- *
- * The current layout is flat — the foundation package root contains
- * the source directly, and the declarations file is named `main.js`:
- *
- *     <template>/foundation/main.js
- *     <template>/foundation/sections/...
- *
- * The CLI scaffolds the new flat shape into the project's `src/`
- * directory, so an unmodified copy of an old-format template would
- * land at `src/src/foundation.js` (extra `src/` layer + old name).
- *
- * This helper detects the legacy marker (`<dir>/src/foundation.js`),
- * mutates the contentDir entry to point at the inner `src/` directory,
- * and records a top-level rename so `foundation.js` is written as
- * `main.js`. Once `uniweb/templates` is republished with the flat
- * layout, this branch becomes a no-op.
- */
-function applyLegacyFoundationLayout(entry) {
-  const innerSrc = path.join(entry.dir, 'src')
-  if (!existsSync(innerSrc)) return
-
-  const legacyMain = path.join(innerSrc, 'foundation.js')
-  const newMain = path.join(innerSrc, 'main.js')
-  if (!existsSync(legacyMain) && !existsSync(newMain)) return
-
-  entry.dir = innerSrc
-  if (existsSync(legacyMain)) {
-    entry.renames = { ...(entry.renames || {}), 'foundation.js': 'main.js' }
-  }
-}
-
-/**
- * Get list of available templates in a templates directory
- *
- * @param {string} templatesDir - Path to directory containing templates
- * @returns {Array<Object>} List of template metadata
- */
-export async function listTemplates(templatesDir) {
-  if (!existsSync(templatesDir)) {
-    return []
-  }
-
-  const entries = await fs.readdir(templatesDir, { withFileTypes: true })
-  const templates = []
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue
-
-    const templatePath = path.join(templatesDir, entry.name)
-    const metadataPath = path.join(templatePath, 'template.json')
-
-    if (existsSync(metadataPath)) {
-      try {
-        const content = await fs.readFile(metadataPath, 'utf8')
-        const metadata = JSON.parse(content)
-        templates.push({
-          id: entry.name,
-          ...metadata,
-          path: templatePath
-        })
-      } catch {
-        // Skip invalid templates
-      }
-    }
-  }
-
-  return templates
-}

package/src/utils/exit.js

@@ -0,0 +1,30 @@
+/**
+ * Exit once everything this process wrote to stdout and stderr has left it.
+ *
+ * ⛔ `process.exit()` does not wait for output a pipe has not taken yet. On macOS Node writes
+ * to a pipe asynchronously, and an exit drops whatever is still queued: `uniweb site list
+ * --json` reached a reading process as half a JSON document, cut at 8192 bytes, and a single
+ * 100 000-byte write followed by an exit delivered 65 536 — on stdout and on stderr alike
+ * (measured 2026-10-07). Into a terminal or a file, or on Linux, the writes are synchronous
+ * and nothing is lost, which is how it went unseen: the reader it bites is a script, `| jq`,
+ * or an agent capturing the output.
+ *
+ * ⭐ An empty write's callback runs once every write before it on that stream has been handed
+ * over, so waiting for one per stream is enough.
+ *
+ * Every exit in `index.js` goes through here — `test/exit-drain.test.js` holds it to that.
+ *
+ * @param {number} [code]
+ * @returns {Promise<never>}
+ */
+export async function exitWhenDrained(code = 0) {
+  await Promise.all([process.stdout, process.stderr].map(drained))
+  process.exit(code)
+}
+
+function drained(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.destroyed || stream.writableEnded) return resolve()
+    stream.write('', () => resolve())
+  })
+}

package/src/utils/scaffold.js

@@ -155,11 +155,6 @@ export async function scaffoldSite(targetDir, context, options = {}) {
  * @param {string} targetDir - Target directory to overlay onto
  * @param {Object} context - Handlebars context for .hbs files
  * @param {Object} [options] - Processing options
- * @param {Object} [options.renames] - Top-level filename remapping
- *   (e.g. `{ 'foundation.js': 'main.js' }`). Applied only at depth 0
- *   so renames don't accidentally rewrite same-named files in nested
- *   directories. Used to migrate legacy `foundation/foundation.js`
- *   templates onto the new flat `src/main.js` layout.
  */
 export async function applyContent(
   contentDir,
@@ -221,11 +216,8 @@ const INHERITED_STATE = new Set(['sync.json', 'deploy.yml', '.uniweb'])
 /**
  * Recursively copy content files, skipping structural files.
  *
- * `depth` is tracked so the `renames` map (passed via options) only
- * applies at depth 0 — the top of the content directory. Without this
- * guard, a rename like `foundation.js → main.js` would also rewrite a
- * nested `sections/foo/foundation.js` if one existed, which is not the
- * intent.
+ * `depth` is tracked so the project-state names (INHERITED_STATE) are
+ * skipped only at the top of the content directory.
  */
 async function copyContentRecursive(
   sourceDir,
@@ -239,7 +231,6 @@ async function copyContentRecursive(
   await fs.mkdir(targetDir, { recursive: true })
 
   const entries = readdirSync(sourceDir, { withFileTypes: true })
-  const renames = (depth === 0 && options.renames) || null
 
   for (const entry of entries) {
     const sourcePath = join(sourceDir, entry.name)
@@ -258,18 +249,10 @@ async function copyContentRecursive(
       )
     } else {
       // Determine the output filename (strip .hbs extension)
-      let outputName = entry.name.endsWith('.hbs')
+      const outputName = entry.name.endsWith('.hbs')
         ? entry.name.slice(0, -4)
         : entry.name
 
-      // Apply top-level rename (e.g. legacy `foundation.js` → `main.js`)
-      if (
-        renames &&
-        Object.prototype.hasOwnProperty.call(renames, outputName)
-      ) {
-        outputName = renames[outputName]
-      }
-
       // Skip structural files
       if (structuralFiles.has(outputName)) continue
       if (depth === 0 && INHERITED_STATE.has(outputName)) continue

package/src/utils/update-check.js

@@ -57,36 +57,22 @@ function writeState(state) {
 
 /**
  * Print update notification to stderr (doesn't interfere with piped output).
- * `tone` controls the lead-in: 'soft' (default — trailing notice for finished
- * commands) vs 'eager' (leading notice for staleness-sensitive commands like
- * `create`, where the user is about to scaffold files from CLI-bundled
- * templates and a stale CLI means stale starter content).
+ * A trailing notice for a finished command; `create` and `clone` do not get
+ * one, they stop first (refuseOutdatedProjectStart).
  */
-function printNotification(current, latest, tone = 'soft') {
+function printNotification(current, latest) {
   const yellow = '\x1b[33m'
   const cyan = '\x1b[36m'
   const dim = '\x1b[2m'
   const reset = '\x1b[0m'
   const updateCmd = globalCliUpdateCmd(detectGlobalCliPm())
   console.error('')
-  if (tone === 'eager') {
-    console.error(
-      `${yellow}Heads up:${reset} this CLI is ${dim}${current}${reset}; latest is ${cyan}${latest}${reset}.`
-    )
-    console.error(
-      `${dim}Templates ship with the CLI — consider updating first:${reset} ${updateCmd}`
-    )
-    console.error(
-      `${dim}Or run a one-shot fresh:${reset} npx uniweb@latest <command>`
-    )
-  } else {
-    console.error(
-      `${yellow}Update available:${reset} ${dim}${current}${reset} → ${cyan}${latest}${reset}`
-    )
-    console.error(
-      `${dim}Run${reset} ${updateCmd} ${dim}to update the CLI${reset}`
-    )
-  }
+  console.error(
+    `${yellow}Update available:${reset} ${dim}${current}${reset} → ${cyan}${latest}${reset}`
+  )
+  console.error(
+    `${dim}Run${reset} ${updateCmd} ${dim}to update the CLI${reset}`
+  )
 }
 
 /**
@@ -94,28 +80,78 @@ function printNotification(current, latest, tone = 'soft') {
  * version is known. No network fetch — only reads what `startUpdateCheck`
  * has previously cached. Returns true if a notification was printed.
  *
- * Two call sites today, with different tone needs:
- *   - `create` (tone='eager'): loud leading notice — templates ship with
- *     the CLI, the user is about to scaffold files, this matters.
- *   - `--version` / `-v` (tone='soft'): brief trailing notice — the user
- *     was already asking about version, mention staleness while we're
- *     here. Goes to stderr so scripts capturing stdout aren't affected.
+ * For `--version` / `-v` off a terminal: the user was already asking about
+ * the version, so staleness is mentioned while we're here. Goes to stderr so
+ * scripts capturing stdout aren't affected.
  *
  * @param {string} currentVersion
- * @param {'eager'|'soft'} [tone='eager']
  * @returns {boolean} true if a notification was printed
  */
-export function maybeNotifyFromCache(currentVersion, tone = 'eager') {
+export function maybeNotifyFromCache(currentVersion) {
   const state = readState()
   if (!state.latestVersion) return false
   if (compareSemver(state.latestVersion, currentVersion) <= 0) return false
-  printNotification(currentVersion, state.latestVersion, tone)
+  printNotification(currentVersion, state.latestVersion)
   return true
 }
 
-// Old name preserved as alias — `create` calls it without a tone arg
-// and gets the eager default. Keeps that call site unchanged.
-export const maybeEagerNotification = maybeNotifyFromCache
+/**
+ * Whether a release newer than `current` is published. Unknown (`latest` null:
+ * offline, or a slow registry) is not behind.
+ *
+ * @param {string} current
+ * @param {string|null} latest
+ * @returns {boolean}
+ */
+export function isBehind(current, latest) {
+  return Boolean(latest) && compareSemver(latest, current) > 0
+}
+
+/** Arguments as a shell would need them typed again. */
+export function shellJoin(args) {
+  return args
+    .map((a) => (/^[\w@%+=:,./-]+$/.test(a) ? a : `'${String(a).replace(/'/g, `'\\''`)}'`))
+    .join(' ')
+}
+
+/**
+ * Stop `create` or `clone` when a global CLI has been replaced by a newer
+ * release — before anything is written.
+ *
+ * ⭐ A PROJECT STARTS ON THE CLI THAT CREATES IT: its version table pins the
+ * `@uniweb/*` packages, and its official templates come from the release it was
+ * published with. Inside a project a global install only launches the project's
+ * own CLI; outside one, for `create` and `clone`, it does the work itself — so
+ * an outdated one starts the project outdated, and says nothing. `npx uniweb`
+ * with no version runs a global install too, which is how a 0.12 CLI went on
+ * offering the ten templates it knew while sixteen shipped (2026-10-08).
+ *
+ * Any newer release stops it, not only a newer minor: the version table moves
+ * whenever any package does — a patch of the CLI can pin a new breaking line of
+ * one — and the fix is one command either way. Unknown proceeds: this stops a
+ * known mistake, it does not require the network.
+ *
+ * @param {string} current - this CLI's version
+ * @param {string[]} argv - the command and its arguments, repeated in the fix
+ * @returns {Promise<boolean>} true when it refused, the reason printed
+ */
+export async function refuseOutdatedProjectStart(current, argv) {
+  const latest = await getLatestVersion({ maxAgeMs: 60 * 60 * 1000 })
+  if (!isBehind(current, latest)) return false
+  const red = '\x1b[31m'
+  const cyan = '\x1b[36m'
+  const dim = '\x1b[2m'
+  const reset = '\x1b[0m'
+  console.error(`${red}✗${reset} This uniweb is ${current}; the latest release is ${latest}.`)
+  console.error(
+    `  ${dim}A project starts on the packages and templates of the CLI that creates it.${reset}`
+  )
+  console.error(`  Run the latest:      ${cyan}npx uniweb@latest ${shellJoin(argv)}${reset}`)
+  console.error(
+    `  Or update this one:  ${cyan}${globalCliUpdateCmd(detectGlobalCliPm())}${reset}`
+  )
+  return true
+}
 
 /**
  * Resolve the latest published CLI version WITHOUT printing anything.
@@ -188,12 +224,11 @@ export async function getLatestVersion({
  * @param {object} [opts]
  * @param {number} [opts.timeoutMs=1500] Network timeout. Slow / offline
  *   calls return silently — never block the verb for long.
- * @param {'eager'|'soft'} [opts.tone='soft'] Notification copy.
  * @returns {Promise<boolean>} true if a notice was printed.
  */
 export async function fetchAndNotifyIfNewer(
   currentVersion,
-  { timeoutMs = 1500, tone = 'soft' } = {}
+  { timeoutMs = 1500 } = {}
 ) {
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), timeoutMs)
@@ -216,7 +251,7 @@ export async function fetchAndNotifyIfNewer(
   // Refresh the cache so other code paths see this fresh result.
   writeState({ lastCheck: Date.now(), latestVersion: latest })
   if (compareSemver(latest, currentVersion) <= 0) return false
-  printNotification(currentVersion, latest, tone)
+  printNotification(currentVersion, latest)
   return true
 }
 

package/src/versions.js

@@ -240,8 +240,11 @@ function readWorkspaceVersion(packageName) {
  * Returns null if the file doesn't exist, is unparseable, or has a
  * schema version we don't understand. Callers treat null as "no
  * snapshot available" and fall back to their next source.
+ *
+ * Also the official templates' one source (`templates/resolver.js`): their
+ * roster, and the `@uniweb/templates` release their content downloads from.
  */
-function loadFrameworkIndex() {
+export function loadFrameworkIndex() {
   const indexPath = join(__dirname, 'framework-index.json')
   try {
     const raw = readFileSync(indexPath, 'utf8')