uniweb 1.0.0 → 1.0.2

package/src/utils/snapshot-settings.js

@@ -0,0 +1,112 @@
+/**
+ * `site/snapshot.yml` — how `uniweb snapshot` composes a site's preview image,
+ * kept with the site so the next run reproduces the same look.
+ *
+ * It is the command's defaults for this site, and flags override it. Nothing else
+ * reads it: the build, `push` and `pull` all leave a site's root files alone
+ * unless they name them.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import yaml from 'js-yaml'
+
+import { didYouMean } from './args.js'
+
+export const SETTINGS_FILE = 'snapshot.yml'
+
+/** In the order they are written. */
+export const SETTING_KEYS = [
+  'route',
+  'layout',
+  'tone',
+  'gap',
+  'overlap',
+  'strip',
+  'side',
+  'frame',
+  'size',
+  'scale',
+  'quality',
+  'hide',
+  'out'
+]
+
+const HEADER = [
+  '# How `uniweb snapshot` composes this site\'s preview image.',
+  '# Flags override these; `uniweb snapshot <flags> --save` writes them here.',
+  ''
+].join('\n')
+
+export class SettingsError extends Error {}
+
+/**
+ * The settings in `<siteDir>/snapshot.yml`, or `{}` when there is none. `out` comes
+ * back absolute, resolved against the site folder.
+ */
+export function readSnapshotSettings(siteDir) {
+  const file = join(siteDir, SETTINGS_FILE)
+  if (!existsSync(file)) return { file, settings: {} }
+
+  let data
+  try {
+    data = yaml.load(readFileSync(file, 'utf8'))
+  } catch (err) {
+    throw new SettingsError(`${SETTINGS_FILE} is not valid YAML: ${err.message.split('\n')[0]}`)
+  }
+  if (data === undefined || data === null) return { file, settings: {} }
+  if (typeof data !== 'object' || Array.isArray(data)) {
+    throw new SettingsError(`${SETTINGS_FILE} should be a list of settings, like \`gap: 48\`.`)
+  }
+
+  const settings = {}
+  for (const [key, value] of Object.entries(data)) {
+    if (!SETTING_KEYS.includes(key)) {
+      const suggestion = didYouMean(key, SETTING_KEYS)
+      throw new SettingsError(
+        `${SETTINGS_FILE} has an unknown setting \`${key}\`.` + (suggestion ? ` Did you mean \`${suggestion}\`?` : '')
+      )
+    }
+    if (value === null || value === undefined) continue
+    if (key === 'hide') settings.hide = Array.isArray(value) ? value.map(String) : [String(value)]
+    else if (key === 'out') settings.out = resolve(siteDir, String(value))
+    else settings[key] = value
+  }
+  return { file, settings }
+}
+
+/** Flags over the file. A gap or an overlap from the flags replaces either from the file. */
+export function mergeSettings(fromFile = {}, fromFlags = {}) {
+  const merged = { ...fromFile }
+  if (fromFlags.gap !== undefined || fromFlags.overlap !== undefined) {
+    delete merged.gap
+    delete merged.overlap
+  }
+  for (const [key, value] of Object.entries(fromFlags)) {
+    if (value !== undefined) merged[key] = value
+  }
+  return merged
+}
+
+/**
+ * Write the flags of this run into `<siteDir>/snapshot.yml`, over what it already
+ * holds. The file is rewritten in full, in `SETTING_KEYS` order, under a header.
+ *
+ * @returns {{ file: string, saved: string[] }} the keys this run set
+ */
+export function saveSnapshotSettings(siteDir, fromFlags, fromFile = readSnapshotSettings(siteDir).settings) {
+  const file = join(siteDir, SETTINGS_FILE)
+  const merged = mergeSettings(fromFile, fromFlags)
+  const ordered = {}
+  for (const key of SETTING_KEYS) {
+    if (merged[key] === undefined) continue
+    ordered[key] = key === 'out' ? toSitePath(siteDir, merged.out) : merged[key]
+  }
+  writeFileSync(file, HEADER + yaml.dump(ordered, { lineWidth: -1 }))
+  return { file, saved: SETTING_KEYS.filter((key) => fromFlags[key] !== undefined) }
+}
+
+function toSitePath(siteDir, path) {
+  const rel = relative(siteDir, path)
+  return isAbsolute(rel) ? path : rel.split(sep).join('/')
+}

package/src/utils/update-check.js

@@ -0,0 +1,302 @@
+/**
+ * Lightweight Update Notification
+ *
+ * Checks the npm registry for newer versions of the CLI.
+ * Runs at most once per day, caches results in ~/.uniweb/update-check.json.
+ * Uses Node 20+ built-in fetch — no external dependencies.
+ */
+
+import { homedir } from 'node:os'
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { detectGlobalCliPm, globalCliUpdateCmd } from './pm.js'
+
+const CHECK_INTERVAL = 24 * 60 * 60 * 1000 // 1 day
+const STATE_DIR = join(homedir(), '.uniweb')
+const STATE_FILE = join(STATE_DIR, 'update-check.json')
+
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function compareSemver(a, b) {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1
+  }
+  return 0
+}
+
+/**
+ * Read cached update check state.
+ */
+function readState() {
+  try {
+    if (existsSync(STATE_FILE)) {
+      return JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+    }
+  } catch {
+    /* ignore corrupt cache */
+  }
+  return {}
+}
+
+/**
+ * Write update check state to disk.
+ */
+function writeState(state) {
+  try {
+    if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true })
+    writeFileSync(STATE_FILE, JSON.stringify(state))
+  } catch {
+    /* ignore write errors */
+  }
+}
+
+/**
+ * Print update notification to stderr (doesn't interfere with piped output).
+ * A trailing notice for a finished command; `create` and `clone` do not get
+ * one, they stop first (refuseOutdatedProjectStart).
+ */
+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('')
+  console.error(
+    `${yellow}Update available:${reset} ${dim}${current}${reset} → ${cyan}${latest}${reset}`
+  )
+  console.error(
+    `${dim}Run${reset} ${updateCmd} ${dim}to update the CLI${reset}`
+  )
+}
+
+/**
+ * Synchronously read the cache and print a notification if a newer
+ * version is known. No network fetch — only reads what `startUpdateCheck`
+ * has previously cached. Returns true if a notification was printed.
+ *
+ * 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
+ * @returns {boolean} true if a notification was printed
+ */
+export function maybeNotifyFromCache(currentVersion) {
+  const state = readState()
+  if (!state.latestVersion) return false
+  if (compareSemver(state.latestVersion, currentVersion) <= 0) return false
+  printNotification(currentVersion, state.latestVersion)
+  return true
+}
+
+/**
+ * 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.
+ *
+ * The notify helpers in this module own both the lookup and the message.
+ * That's right for callers who want the house notice, and wrong for callers
+ * whose remedy differs — `uniweb update` running from a project's
+ * node_modules can't tell the user to `npm i -g uniweb`, because the version
+ * they're on is pinned by their own package.json. Those callers need the
+ * fact, not the sentence.
+ *
+ * Caching and the timeout live here rather than at the call site so every
+ * lookup gets them. `update.js` previously had its own copy with neither: an
+ * unbounded `await fetch()` before the command did any work, which turns a
+ * flaky network into a hang on a routine verb.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=1500] Network cap. Slow/offline returns
+ *   whatever the cache holds rather than blocking.
+ * @param {boolean} [opts.allowNetwork=true] False = cache-only. Pass false
+ *   for non-TTY callers; scripts must stay fast and offline-safe (the same
+ *   convention `--version` follows).
+ * @param {number} [opts.maxAgeMs] How old a cache entry may be before a
+ *   refetch is attempted. Defaults to the module's 1-day interval.
+ * @returns {Promise<string|null>} The latest version, or null if unknown.
+ */
+export async function getLatestVersion({
+  timeoutMs = 1500,
+  allowNetwork = true,
+  maxAgeMs = CHECK_INTERVAL
+} = {}) {
+  const state = readState()
+  const cached = state.latestVersion || null
+  const fresh = state.lastCheck && Date.now() - state.lastCheck < maxAgeMs
+  if (fresh && cached) return cached
+  // A stale cache entry still beats nothing for an advisory, so it's the
+  // fallback for every failure path below rather than a hard null.
+  if (!allowNetwork) return cached
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetch('https://registry.npmjs.org/uniweb/latest', {
+      signal: controller.signal
+    })
+    if (!res.ok) return cached
+    const data = await res.json()
+    const latest = data?.version || null
+    if (!latest) return cached
+    writeState({ lastCheck: Date.now(), latestVersion: latest })
+    return latest
+  } catch {
+    return cached
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Fetch the latest version (with a tight timeout) and print a notice if
+ * a newer version is found. Updates the on-disk cache as a side effect
+ * so future cache-only callers benefit too.
+ *
+ * Use this for TTY invocations of `--version` / `-v` where the user is
+ * interactively asking about the version and a brief network wait is
+ * acceptable. Don't use it for non-TTY callers — scripts capturing
+ * stdout (`version=$(uniweb -v)`) need a fast, offline-safe path.
+ *
+ * @param {string} currentVersion
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=1500] Network timeout. Slow / offline
+ *   calls return silently — never block the verb for long.
+ * @returns {Promise<boolean>} true if a notice was printed.
+ */
+export async function fetchAndNotifyIfNewer(
+  currentVersion,
+  { timeoutMs = 1500 } = {}
+) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  let latest = null
+  try {
+    const res = await fetch('https://registry.npmjs.org/uniweb/latest', {
+      signal: controller.signal
+    })
+    if (res.ok) {
+      const data = await res.json()
+      latest = data?.version || null
+    }
+  } catch {
+    // Aborted, network error, parse error — all silent. The verb
+    // shouldn't block on update-check failures.
+  } finally {
+    clearTimeout(timer)
+  }
+  if (!latest) return false
+  // 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)
+  return true
+}
+
+/**
+ * Start a non-blocking update check.
+ *
+ * Returns a function that, when called (optionally awaited), prints
+ * the notification if a newer version was found.
+ *
+ * @param {string} currentVersion - The currently running CLI version
+ * @returns {Function} Call at the end of command execution to show notification
+ */
+export function startUpdateCheck(currentVersion) {
+  let notification = null
+  const state = readState()
+
+  // Use cached result if checked recently
+  if (state.lastCheck && Date.now() - state.lastCheck < CHECK_INTERVAL) {
+    if (
+      state.latestVersion &&
+      compareSemver(state.latestVersion, currentVersion) > 0
+    ) {
+      notification = state.latestVersion
+    }
+    return () => {
+      if (notification) printNotification(currentVersion, notification)
+    }
+  }
+
+  // Background fetch (non-blocking)
+  const fetchPromise = fetch('https://registry.npmjs.org/uniweb/latest')
+    .then((r) => r.json())
+    .then((data) => {
+      const latest = data.version
+      writeState({ lastCheck: Date.now(), latestVersion: latest })
+      if (compareSemver(latest, currentVersion) > 0) {
+        notification = latest
+      }
+    })
+    .catch(() => {
+      /* network error — ignore silently */
+    })
+
+  return async () => {
+    await fetchPromise
+    if (notification) printNotification(currentVersion, notification)
+  }
+}

package/src/utils/uwx-read.js

@@ -0,0 +1,157 @@
+/**
+ * Minimal `.uwx` reader — for the commands that run BEFORE a project exists.
+ *
+ * ## Why this exists rather than importing the real one
+ *
+ * Every other `.uwx` reader in the CLI (`pull.js`, `site-sync.js`, `content.js`)
+ * imports `readZip` from `@uniweb/build/uwx`. That is correct for them: they run
+ * *inside* a project, where `@uniweb/build` resolves from the project's own
+ * `node_modules`.
+ *
+ * **`@uniweb/build` is not a dependency of this package** (see `package.json`),
+ * so a command that runs where no project exists cannot reach it — statically or
+ * dynamically. `uniweb clone` is exactly that command: its whole job is to turn a
+ * backend site into a local project that does not exist yet.
+ *
+ * So this is a deliberate second implementation, kept minimal and dependency-free
+ * (`node:zlib` is a builtin), the same way `clone.js` keeps its own
+ * `extractDocument` for the same reason. **Do not import this from a command that
+ * runs inside a project** — use `@uniweb/build/uwx`'s `readZip` there, so the
+ * producer and the consumer of a `.uwx` stay one implementation wherever they can.
+ *
+ * ## Two things measured on a real payload, both of which would break a naive reader
+ *
+ * 1. ⛔ **The archive is NOT "stored".** `pull.js` describes the format as *"our
+ *    Stored ZIP"*, and that is true of `manifest.json` and false of the entity
+ *    files — measured on a live pull: `manifest.json` method 0 (STORED), the
+ *    entity JSON method 8 (DEFLATED). A stored-only reader silently yields the
+ *    manifest and drops the document, i.e. it returns success and no entities.
+ *    **Both methods are handled below and the tests cover a mixed archive.**
+ * 2. The entity payload is the *only* thing wanted; `manifest.json` is skipped, as
+ *    every other reader in the tree does.
+ *
+ * We read the **central directory** rather than walking local file headers,
+ * because a local header may carry zeroed sizes when the general-purpose bit 3
+ * flag defers them to a trailing data descriptor. The central directory always
+ * carries the real sizes.
+ */
+
+import { inflateRawSync } from 'node:zlib'
+
+const SIG_EOCD = 0x06054b50
+const SIG_CENTRAL = 0x02014b50
+const SIG_LOCAL = 0x04034b50
+const METHOD_STORED = 0
+const METHOD_DEFLATED = 8
+
+/** ZIP local-file-header magic, "PK\x03\x04" — the first two bytes are enough. */
+export function looksLikeZip(buf) {
+  return Boolean(buf) && buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b
+}
+
+/**
+ * Locate the end-of-central-directory record.
+ *
+ * Scanned backwards because the record is last and variable-length (it carries an
+ * optional trailing comment).
+ *
+ * @param {Buffer} buf
+ * @returns {number} offset of the EOCD, or -1
+ */
+function findEocd(buf) {
+  const min = Math.max(0, buf.length - 22 - 0xffff)
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) === SIG_EOCD) return i
+  }
+  return -1
+}
+
+/**
+ * Read every entry out of a ZIP as `[name, Buffer]` pairs.
+ *
+ * @param {Buffer} buf
+ * @returns {Array<[string, Buffer]>} empty when the buffer is not a readable ZIP
+ */
+export function readUwxZip(buf) {
+  if (!looksLikeZip(buf)) return []
+  const eocd = findEocd(buf)
+  if (eocd < 0) return []
+
+  const count = buf.readUInt16LE(eocd + 10)
+  let ptr = buf.readUInt32LE(eocd + 16)
+  const out = []
+
+  for (let i = 0; i < count; i++) {
+    if (ptr + 46 > buf.length || buf.readUInt32LE(ptr) !== SIG_CENTRAL) break
+
+    const method = buf.readUInt16LE(ptr + 10)
+    const csize = buf.readUInt32LE(ptr + 20)
+    const nameLen = buf.readUInt16LE(ptr + 28)
+    const extraLen = buf.readUInt16LE(ptr + 30)
+    const commentLen = buf.readUInt16LE(ptr + 32)
+    const localOff = buf.readUInt32LE(ptr + 42)
+    const name = buf.subarray(ptr + 46, ptr + 46 + nameLen).toString('utf8')
+
+    // The local header's name/extra lengths are independent of the central
+    // directory's — read them where the data actually starts, not from above.
+    if (localOff + 30 <= buf.length && buf.readUInt32LE(localOff) === SIG_LOCAL) {
+      const lNameLen = buf.readUInt16LE(localOff + 26)
+      const lExtraLen = buf.readUInt16LE(localOff + 28)
+      const start = localOff + 30 + lNameLen + lExtraLen
+      const raw = buf.subarray(start, start + csize)
+      try {
+        if (method === METHOD_STORED) out.push([name, Buffer.from(raw)])
+        else if (method === METHOD_DEFLATED) out.push([name, inflateRawSync(raw)])
+        // any other method: skip rather than guess
+      } catch {
+        /* a corrupt entry must not lose the readable ones */
+      }
+    }
+
+    ptr += 46 + nameLen + extraLen + commentLen
+  }
+
+  return out
+}
+
+/**
+ * The entity `$`-documents inside a `.uwx`, or a JSON body's documents.
+ *
+ * Mirrors `pull.js`'s `readPullDocuments` in behaviour — including its JSON
+ * fallback, so a future envelope change does not break this lane either — but
+ * without the `@uniweb/build` import. See the header for why that matters.
+ *
+ * @param {Buffer} buf
+ * @returns {object[]} parsed documents, possibly empty
+ */
+export function readUwxDocuments(buf) {
+  if (!buf || buf.length === 0) return []
+
+  if (looksLikeZip(buf)) {
+    const docs = []
+    for (const [name, data] of readUwxZip(buf)) {
+      if (name === 'manifest.json' || !name.endsWith('.json')) continue
+      try {
+        docs.push(JSON.parse(data.toString('utf8')))
+      } catch {
+        /* skip a non-document entry */
+      }
+    }
+    return docs
+  }
+
+  let payload
+  try {
+    payload = JSON.parse(buf.toString('utf8'))
+  } catch {
+    return []
+  }
+  if (Array.isArray(payload)) return payload.filter(Boolean)
+  const list = Array.isArray(payload?.entities)
+    ? payload.entities
+    : Array.isArray(payload?.documents)
+      ? payload.documents
+      : null
+  if (list) return list.filter(Boolean)
+  return payload ? [payload] : []
+}