uniweb 1.0.0 → 1.0.2

package/src/utils/dep-survey.js

@@ -0,0 +1,176 @@
+/**
+ * Workspace `@uniweb/*` dependency survey.
+ *
+ * Compares the `@uniweb/*` + `uniweb` versions *declared* in every
+ * package.json across a workspace against the running CLI's bundled
+ * version matrix (`getResolvedVersions`). Shared by `uniweb update`
+ * (which fixes the drift) and `uniweb doctor` (which only reports it) so
+ * the two never disagree about what "out of date" means.
+ *
+ * Comparison is on declared specs, not installed (node_modules) versions
+ * — that's what's committed and what `git diff` will show after a fix.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getResolvedVersions } from '../versions.js'
+import { getWorkspacePackages } from './workspace.js'
+
+/**
+ * Strip a leading semver range operator (^, ~, >=, <, …) so two specs can
+ * be compared by their underlying version. Range expressions like
+ * ">=0.5 <0.7" aren't fully parsed — the first version-shaped token wins.
+ * Sufficient for `@uniweb/*` deps, which use `^x.y.z` / `x.y.z`.
+ * @param {string} spec
+ * @returns {string}
+ */
+export function stripVersionRange(spec) {
+  return (
+    (spec || '')
+      .replace(/^[\^~>=<\s]+/, '')
+      .trim()
+      .split(/\s+/)[0] || ''
+  )
+}
+
+/**
+ * How far a bump moves, in the terms our versioning actually uses.
+ *
+ * ⭐ **The MINOR slot is the breaking one — in 1.x as in 0.x** *[ruled
+ * 2026-10-11]*. `scripts/framework/publish.js` derives a package's bump from its own
+ * commits: a breaking marker means minor, everything else patch. So
+ * `^0.14.1 → ^0.16.0` is two breaking releases and `^0.15.0 → ^0.15.2` is not —
+ * and until 2026-09-02 `update` printed both as `behind`, in the same colour,
+ * and `--yes` applied them without a word.
+ *
+ * That is the one signal the version scheme exists to send, discarded by the
+ * command we tell every project to run — `AGENTS.md` ships that instruction
+ * into every scaffold. The `flows` lane crossed `@uniweb/core` `^0.14.1 →
+ * ^0.15.0` this way and learned it afterwards, from a changelog.
+ *
+ * @param {string} from - the currently declared range or version
+ * @param {string} to   - the version the matrix carries
+ * @returns {'patch'|'minor'|'major'|'none'}
+ */
+export function bumpClass(from, to) {
+  const [aMaj = 0, aMin = 0, aPat = 0] = stripVersionRange(from).split('.').map(Number)
+  const [bMaj = 0, bMin = 0, bPat = 0] = stripVersionRange(to).split('.').map(Number)
+  if (bMaj !== aMaj) return 'major'
+  if (bMin !== aMin) return 'minor'
+  if (bPat !== aPat) return 'patch'
+  return 'none'
+}
+
+/**
+ * Is this crossing one a consumer must act on?
+ *
+ * A major, or a minor — at every major. Our scheme ships a breaking change as a minor
+ * bump, in 1.x as in 0.x *[ruled 2026-10-11]*, and the ranges a project carries (`~`)
+ * treat the minor slot as the wall: `~1.4.0` admits 1.4.x and refuses 1.5.0, as
+ * `^0.14.1` refuses 0.15.0. ⛔ Until then a minor counted only below 1.0, where a caret
+ * refuses it — so this would have stopped warning at the first 1.x minor.
+ *
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function isBreakingBump(from, to) {
+  const cls = bumpClass(from, to)
+  return cls === 'major' || cls === 'minor'
+}
+
+/**
+ * Compare two version specs (range prefix tolerated). Returns 1 / -1 / 0.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function compareSemver(a, b) {
+  const pa = stripVersionRange(a).split('.').map(Number)
+  const pb = stripVersionRange(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
+}
+
+/**
+ * @typedef {object} DepRow
+ * @property {string} relDir   Workspace-relative dir, or '(root)'.
+ * @property {string} section  'dependencies' | 'devDependencies' | 'peerDependencies'
+ * @property {string} name     Package name (e.g. '@uniweb/core' or 'uniweb').
+ * @property {string} current  The spec declared in package.json.
+ * @property {string} target   The spec the running CLI's matrix wants.
+ * @property {'aligned'|'behind'|'ahead'} status  current vs target.
+ */
+
+/**
+ * Survey a workspace's declared `@uniweb/*` + `uniweb` deps against the
+ * running CLI's bundled matrix.
+ *
+ * @param {string} workspaceDir Absolute path to the workspace root.
+ * @returns {Promise<{ targets: Record<string,string>, rows: DepRow[], anyDrift: boolean, anyAhead: boolean }>}
+ *   `anyDrift` — at least one dep lags the matrix. `anyAhead` — at least
+ *   one dep is newer than the matrix.
+ */
+export async function surveyWorkspaceDeps(workspaceDir) {
+  const targets = getResolvedVersions()
+  const packages = await getWorkspacePackages(workspaceDir)
+  const dirs = ['', ...packages]
+  const rows = []
+  let anyDrift = false
+  let anyAhead = false
+
+  for (const relDir of dirs) {
+    const pkgDir = relDir ? join(workspaceDir, relDir) : workspaceDir
+    const pkgPath = join(pkgDir, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    let pkg
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    } catch {
+      continue
+    }
+
+    for (const sectionName of [
+      'dependencies',
+      'devDependencies',
+      'peerDependencies'
+    ]) {
+      const section = pkg[sectionName]
+      if (!section) continue
+      for (const [name, current] of Object.entries(section)) {
+        if (!(name.startsWith('@uniweb/') || name === 'uniweb')) continue
+        const target = targets[name]
+        if (!target) continue
+        const cmp = compareSemver(target, current)
+        let status
+        if (cmp > 0) {
+          status = 'behind'
+          anyDrift = true
+        } else if (cmp < 0) {
+          status = 'ahead'
+          anyAhead = true
+        } else {
+          status = 'aligned'
+        }
+        rows.push({
+          relDir: relDir || '(root)',
+          section: sectionName,
+          name,
+          current,
+          target,
+          status,
+          // Classified here rather than at print time so every consumer of a
+          // survey row gets the same answer — the report, the summary, and any
+          // gate a caller applies.
+          bump: status === 'behind' ? bumpClass(current, target) : 'none',
+          breaking: status === 'behind' && isBreakingBump(current, target)
+        })
+      }
+    }
+  }
+
+  return { targets, rows, anyDrift, anyAhead }
+}

package/src/utils/destination-prompt.js

@@ -0,0 +1,146 @@
+/**
+ * The deploy wizard — "Where should this site go?"
+ *
+ * Distinct from `host-prompt.js`, and the split matters. `promptForHost`
+ * answers a *build* question — which host-specific helper files should
+ * land in `dist/` — so it lists every registered adapter, including
+ * shape-only entries like `generic-static`. This module answers a
+ * *shipping* question, so it lists destinations you can actually act on
+ * and says what acting will do.
+ *
+ * The bug that motivated the split: the deploy path used to reuse
+ * `promptForHost`, offering six adapters when only one implemented a
+ * deploy hook. Five of six choices dead-ended on "does not implement a
+ * deploy step". A picker must never offer a door that doesn't open — so
+ * entries are derived from real adapter capability (`deploy` / `initCi`),
+ * not from a registry key list.
+ *
+ * Two synthetic entries round out the menu:
+ *   - Uniweb Cloud — not an adapter; it delegates to `uniweb publish`.
+ *     Listed after the third-party hosts rather than first: the framework
+ *     is backend-optional and standalone-first, so leading a generic
+ *     `deploy` with the paid product would read as an upsell.
+ *   - Somewhere else — delegates to `uniweb export`.
+ */
+
+import { promptSelect } from './workspace.js'
+import { isNonInteractive } from './interactive.js'
+
+export const UNIWEB_DESTINATION = {
+  value: { kind: 'uniweb' },
+  title: 'Uniweb Cloud · paid, dynamic + visual editing',
+  description:
+    'Sync + dynamic SSR, visual editing for content authors, foundation propagation. Runs `uniweb publish`.'
+}
+
+export const EXPORT_DESTINATION = {
+  value: { kind: 'export' },
+  title: 'Somewhere else · export a folder',
+  description:
+    'Builds a self-contained dist/ you upload yourself. Runs `uniweb export`.'
+}
+
+/**
+ * Build the destination list from the adapter registry.
+ *
+ * @returns {Promise<Array<{value: object, title: string, description: string}>>}
+ */
+export async function buildDestinationChoices() {
+  const { listAdapters, getAdapter } = await import('@uniweb/build/hosts')
+
+  const adapters = listAdapters()
+    .map((name) => getAdapter(name))
+    .filter((a) => a.display?.wizard !== false)
+    // Never offer a door that doesn't open.
+    .filter(
+      (a) => typeof a.deploy === 'function' || typeof a.initCi === 'function'
+    )
+    .sort((a, b) => (a.display?.order ?? 999) - (b.display?.order ?? 999))
+
+  const choices = adapters.map((a) => ({
+    value: { kind: 'adapter', host: a.name },
+    title: `${a.display?.title || a.name} · ${a.display?.qualifier || ''}`
+      .trim()
+      .replace(/ ·\s*$/, ''),
+    description: a.display?.summary || ''
+  }))
+
+  return [...choices, UNIWEB_DESTINATION, EXPORT_DESTINATION]
+}
+
+/**
+ * Ask *how* to ship to an adapter that supports both paths. Skipped when
+ * the adapter only supports one — no point asking a question with a
+ * single answer.
+ *
+ * @returns {Promise<'ci'|'deploy'|null>} null when cancelled.
+ */
+async function promptForAction(adapter) {
+  const canCi = typeof adapter.initCi === 'function'
+  const canDeploy = typeof adapter.deploy === 'function'
+
+  if (canCi && !canDeploy) return 'ci'
+  if (canDeploy && !canCi) return 'deploy'
+
+  const label = adapter.display?.title || adapter.name
+  const previews = adapter.display?.previews
+    ? ' Pull requests get their own preview URL.'
+    : ''
+
+  return promptSelect(`${label} — how?`, [
+    {
+      value: 'ci',
+      title: 'Set it up to deploy on every push · recommended',
+      description: `Writes a GitHub Actions workflow. One-time setup — after this, pushing to the default branch deploys.${previews}`
+    },
+    {
+      value: 'deploy',
+      title: 'Upload from this machine now',
+      description: `Builds dist/ here and pushes it with ${adapter.display?.pushWith || 'the host CLI'}.`
+    }
+  ])
+}
+
+/**
+ * Run the wizard.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.args — Argv, used only to gate non-interactive mode.
+ * @param {string|null} [opts.preselect] — Host name to float to the top, so
+ *   Enter repeats what deploy.yml already records.
+ * @returns {Promise<{kind: string, host?: string, action?: string}|null>}
+ *   null when the user cancels.
+ * @throws {Error} When non-interactive — the caller prints the guidance.
+ */
+export async function promptForDestination({
+  args = [],
+  preselect = null
+} = {}) {
+  if (isNonInteractive(args)) {
+    throw new Error(
+      'Cannot prompt for a destination when running non-interactively.'
+    )
+  }
+
+  let choices = await buildDestinationChoices()
+
+  // Float the remembered target so Enter does the obvious thing.
+  if (preselect) {
+    const idx = choices.findIndex(
+      (c) => c.value.kind === 'adapter' && c.value.host === preselect
+    )
+    if (idx > 0)
+      choices = [choices[idx], ...choices.filter((_, i) => i !== idx)]
+  }
+
+  const picked = await promptSelect('Where should this site go?', choices)
+  if (!picked) return null
+  if (picked.kind !== 'adapter') return picked
+
+  const { getAdapter } = await import('@uniweb/build/hosts')
+  const adapter = getAdapter(picked.host)
+  const action = await promptForAction(adapter)
+  if (!action) return null
+
+  return { ...picked, action }
+}

package/src/utils/discover.js

@@ -0,0 +1,75 @@
+/**
+ * Workspace package discovery
+ *
+ * Walks the workspace globs and classifies each package as a site or
+ * foundation using `classifyPackage` from `@uniweb/build` — the canonical
+ * classifier shared with the build pipeline. It keys on real signals
+ * (site.yml for sites, generated entry for foundations) rather than which
+ * `@uniweb/*` packages happen to be in dependencies, so templates whose
+ * sites pull runtime transitively through the foundation (e.g., marketing)
+ * are classified correctly.
+ *
+ * Why this lives in its own file: `@uniweb/build` is an OPTIONAL peer
+ * dependency of the CLI. The CLI's startup path (`src/index.js` and
+ * everything it statically imports) MUST run in environments where
+ * `@uniweb/build` is not installed — `npx uniweb create` in a scratch
+ * dir, `npm i -g uniweb` before any project exists, etc. Anything that
+ * imports `@uniweb/build` therefore must NOT be reachable from the
+ * startup graph; it must be loaded dynamically by commands that already
+ * require a project context. Keeping discovery in this dedicated module
+ * makes that boundary structural rather than conventional.
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { classifyPackage } from '@uniweb/build'
+import { readWorkspaceConfig, resolveGlob } from './config.js'
+
+/**
+ * Discover foundations in the workspace.
+ * @param {string} rootDir - Workspace root directory
+ * @returns {Promise<Array<{name: string, path: string}>>}
+ */
+export async function discoverFoundations(rootDir) {
+  return discoverByKind(rootDir, 'foundation')
+}
+
+/**
+ * Discover sites in the workspace.
+ * @param {string} rootDir - Workspace root directory
+ * @returns {Promise<Array<{name: string, path: string}>>}
+ */
+export async function discoverSites(rootDir) {
+  return discoverByKind(rootDir, 'site')
+}
+
+async function discoverByKind(rootDir, kind) {
+  const { packages } = await readWorkspaceConfig(rootDir)
+  const out = []
+
+  for (const pattern of packages) {
+    const dirs = await resolveGlob(rootDir, pattern)
+    for (const dir of dirs) {
+      const fullPath = join(rootDir, dir)
+      if (classifyPackage(fullPath) !== kind) continue
+
+      // Read package.json for the package name. Synthesize one from
+      // the directory if it's missing or malformed — we still want
+      // the package to surface in pickers.
+      const pkgPath = join(fullPath, 'package.json')
+      let name = dir.split('/').pop()
+      if (existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+          if (pkg.name) name = pkg.name
+        } catch {
+          // keep directory-derived name
+        }
+      }
+      out.push({ name, path: dir })
+    }
+  }
+
+  return out
+}

package/src/utils/env.js

@@ -0,0 +1,22 @@
+/**
+ * Internal env-var helpers.
+ *
+ * UNIWEB_* env vars are escape hatches for developers, operators, and the
+ * platform test team — not user-facing settings. Documented in
+ * `framework/cli/docs/env-vars.md`. Anything truly user-facing should be a
+ * flag, not an env var.
+ */
+
+/**
+ * Parse a boolean-shaped env var. Returns true for "1", "true", "yes" (any
+ * case); false otherwise (including unset, empty, or any other string).
+ *
+ * @param {string} name - Env var name (e.g., "UNIWEB_SKIP_BUILD").
+ * @returns {boolean}
+ */
+export function parseBoolEnv(name) {
+  const raw = process.env[name]
+  if (!raw) return false
+  const v = String(raw).trim().toLowerCase()
+  return v === '1' || v === 'true' || v === 'yes'
+}

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/fetch-retry.js

@@ -0,0 +1,109 @@
+/**
+ * `fetch` with bounded retry and a timeout. **The one implementation.**
+ *
+ * ## Why this file exists
+ *
+ * There were three, byte-identical apart from a timeout constant — one each in
+ * `templates/fetchers/{npm,release,github}.js` — and **none of them was reachable
+ * from the code that needed it most.** The three upload paths (`code-upload`,
+ * `asset-upload`, `site-data-upload`) had no retry at all, so a single
+ * connection-level failure on any one file failed the whole `register` / `push`
+ * / `publish` after every other file had already gone up.
+ *
+ * ⭐ **Measured by the `flows` lane, 2026-09-02:** roughly one red per full suite
+ * run, landing on a *different flow each time* and passing on re-run every time —
+ * the signature of an unretried transient, with the network as the variable
+ * rather than any flow. Their symptom was recorded as "not diagnosed, may be the
+ * manor, the CDN, or the connection"; it was none of those. It was us.
+ *
+ * ## ⚠️ What a retry does NOT do
+ *
+ * It masks whatever drops the connection. That is the right trade for a genuine
+ * transient and the wrong one for a systematic fault: if the failure rate ever
+ * climbs, a retry turns a fast red into a slow one and hides the cause. **Do not
+ * read a green run as evidence the network is healthy.**
+ *
+ * ## Retrying a PUT is safe HERE, and not in general
+ *
+ * These uploads are idempotent by construction — the same bytes to the same
+ * target, with an `x-uniweb-sha256` integrity guard the far side verifies. That
+ * is why `retryOnStatus` is **opt-in** rather than the default: a caller has to
+ * assert its own idempotence, because this helper cannot know it.
+ */
+
+const DEFAULT_RETRIES = 3
+const DEFAULT_TIMEOUT_MS = 30_000
+const MAX_BACKOFF_MS = 10_000
+
+/** Exponential backoff, capped. Attempt is 1-based. */
+const backoffMs = (attempt) => Math.min(1000 * Math.pow(2, attempt), MAX_BACKOFF_MS)
+
+/**
+ * @param {string|URL} url
+ * @param {RequestInit} [options] - passed to `fetch`; `signal` is supplied here.
+ * @param {Object} [config]
+ * @param {number} [config.retries=3] - total attempts, not extra ones.
+ * @param {number} [config.timeoutMs=30000] - per ATTEMPT, not for the whole call.
+ *   ⚠️ For an upload this bounds the time to send a whole body, so a large file
+ *   on a slow link needs a generous value — too short and a legitimately slow
+ *   upload is aborted and then retried, which is worse than no timeout at all.
+ * @param {(status: number) => boolean} [config.retryOnStatus] - opt-in. Without
+ *   it only a THROWN fetch is retried (a connection-level failure, which is what
+ *   surfaces as `status: 0` in the upload paths). A caller passing this asserts
+ *   its request is safe to repeat.
+ * @param {(info: {attempt: number, of: number, reason: string, delayMs: number}) => void} [config.onRetry]
+ *   Called before each wait. ⭐ Worth passing: a retry that no one can see turns
+ *   a visible failure into an invisible slowdown, which is its own defect.
+ * @returns {Promise<Response>}
+ */
+export async function fetchWithRetry(url, options = {}, config = {}) {
+  const {
+    retries = DEFAULT_RETRIES,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    retryOnStatus = null,
+    onRetry = null,
+  } = config
+
+  let lastErr = null
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, {
+        ...options,
+        signal: options.signal ?? AbortSignal.timeout(timeoutMs),
+      })
+
+      if (attempt < retries && retryOnStatus && retryOnStatus(res.status)) {
+        const delayMs = backoffMs(attempt)
+        onRetry?.({ attempt, of: retries, reason: `HTTP ${res.status}`, delayMs })
+        await new Promise((r) => setTimeout(r, delayMs))
+        continue
+      }
+
+      return res
+    } catch (err) {
+      lastErr = err
+      // The last attempt throws to the caller, which keeps this a drop-in for
+      // the three template fetchers whose contract was "throws like fetch".
+      if (attempt === retries) throw err
+      const delayMs = backoffMs(attempt)
+      onRetry?.({ attempt, of: retries, reason: err.message, delayMs })
+      await new Promise((r) => setTimeout(r, delayMs))
+    }
+  }
+
+  /* c8 ignore next 2 -- unreachable: the loop returns or throws on the last attempt */
+  throw lastErr
+}
+
+/**
+ * The statuses worth repeating an idempotent request for: a server that failed
+ * to answer this time, or asked us to slow down.
+ *
+ * ⛔ Never a 4xx other than 429 — a rejection does not improve on repetition,
+ * and retrying one turns a clear error into a delayed clear error.
+ *
+ * @param {number} status
+ * @returns {boolean}
+ */
+export const isTransientStatus = (status) => status === 429 || status >= 500