uniweb 0.12.20 → 0.12.21

package/README.md

@@ -351,7 +351,7 @@ A future version will let markdown in a git repo and content in the Uniweb apps
 | `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
 | `uniweb publish @org/name` | Publish a foundation to the registry (path 2). |
 | `uniweb build` | Inspect a build locally. For shipping, use `deploy` or `export`. |
-| `uniweb update` | Reconcile workspace state with the CLI: self-update the global install, align `@uniweb/*` deps in every `package.json` to the CLI's matrix, refresh `AGENTS.md`. Refuses to outpace declared deps with a stale doc. |
+| `uniweb update` | Align this project with the CLI you're running: bump `@uniweb/*` deps in every `package.json` to the CLI's matrix (then install), and refresh `AGENTS.md`. Pins to *this* CLI's matrix — run `npx uniweb@latest update` to align to the latest release. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`). |
 
 `--host=<adapter>` is the same option across `deploy`, `export`, and `add ci`. Built-in adapters: `cloudflare-pages`, `netlify`, `github-pages`, `vercel`, `s3-cloudfront`, `generic-static`. Each adapter implements only the operations it supports — `add ci` is currently `github-pages`-only because it's the only one that needs a workflow file in the repo.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.20",
+  "version": "0.12.21",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,8 +41,8 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.7.11",
     "@uniweb/runtime": "0.8.14",
+    "@uniweb/core": "0.7.11",
     "@uniweb/kit": "0.9.13"
   },
   "peerDependencies": {

package/src/commands/doctor.js

@@ -10,6 +10,8 @@ import { loadDeployYml } from '@uniweb/build/site'
 import { listAdapters } from '@uniweb/build/hosts'
 import { getCliVersion } from '../versions.js'
 import { readAgentsVersion } from '../utils/agents-stamp.js'
+import { writeJsonPreservingStyle } from '../utils/json-file.js'
+import { surveyWorkspaceDeps } from '../utils/dep-survey.js'
 import { discoverFoundations, discoverSites } from '../utils/discover.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 
@@ -204,9 +206,10 @@ export async function doctor(args = []) {
         const union = Array.from(new Set([...ymlPackages, ...pkgWorkspaces])).sort()
         writeFileSync(ymlPath, yaml.dump({ packages: union }, { flowLevel: -1, quotingType: '"' }))
         const rootPkgPath = join(workspaceDir, 'package.json')
-        const rootPkg = JSON.parse(readFileSync(rootPkgPath, 'utf-8'))
+        const rootPkgSrc = readFileSync(rootPkgPath, 'utf-8')
+        const rootPkg = JSON.parse(rootPkgSrc)
         rootPkg.workspaces = union
-        writeFileSync(rootPkgPath, JSON.stringify(rootPkg, null, 2) + '\n')
+        writeJsonPreservingStyle(rootPkgPath, rootPkg, rootPkgSrc)
         issue.fixed = true
         fixed(`wrote union [${union.join(', ')}] to both manifests`)
       } else {
@@ -364,7 +367,7 @@ export async function doctor(args = []) {
         const sitePkgPath = join(sitePath, 'package.json')
         const updatedPkg = { ...sitePkg }
         updatedPkg.dependencies = { ...(updatedPkg.dependencies || {}), [foundationName]: expectedPath }
-        writeFileSync(sitePkgPath, JSON.stringify(updatedPkg, null, 2) + '\n')
+        writeJsonPreservingStyle(sitePkgPath, updatedPkg)
         issue.fixed = true
         fixed(`added "${foundationName}": "${expectedPath}" to ${relative(workspaceDir, sitePkgPath)}`)
       } else {
@@ -391,7 +394,7 @@ export async function doctor(args = []) {
           const sitePkgPath = join(sitePath, 'package.json')
           const updatedPkg = { ...sitePkg }
           updatedPkg.dependencies = { ...(updatedPkg.dependencies || {}), [foundationName]: expectedPath }
-          writeFileSync(sitePkgPath, JSON.stringify(updatedPkg, null, 2) + '\n')
+          writeJsonPreservingStyle(sitePkgPath, updatedPkg)
           issue.fixed = true
           fixed(`updated "${foundationName}" to "${expectedPath}" in ${relative(workspaceDir, sitePkgPath)}`)
         } else {
@@ -672,11 +675,27 @@ export async function doctor(args = []) {
     }
   }
 
+  const cliVersion = getCliVersion()
+
+  // Check @uniweb/* dep alignment with the running CLI
+  log('')
+  const depSurvey = await surveyWorkspaceDeps(workspaceDir)
+  const behindDeps = depSurvey.rows.filter(r => r.status === 'behind')
+  if (behindDeps.length > 0) {
+    const names = [...new Set(behindDeps.map(r => r.name))].sort()
+    warn(`${behindDeps.length} workspace dep declaration${behindDeps.length === 1 ? '' : 's'} lag the CLI (v${cliVersion}): ${names.join(', ')}`)
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: `${behindDeps.length} @uniweb/* dep declaration(s) behind CLI v${cliVersion}` })
+  } else if (depSurvey.anyAhead) {
+    success(`@uniweb/* deps are aligned or ahead of the CLI (v${cliVersion})`)
+  } else {
+    success(`@uniweb/* deps are aligned with the CLI (v${cliVersion})`)
+  }
+
   // Check AGENTS.md freshness
   log('')
   const agentsPath = join(workspaceDir, 'AGENTS.md')
   const agentsVersion = readAgentsVersion(agentsPath)
-  const cliVersion = getCliVersion()
 
   if (!existsSync(agentsPath)) {
     warn('AGENTS.md not found')

package/src/commands/publish.js

@@ -34,7 +34,7 @@
  */
 
 import { existsSync } from 'node:fs'
-import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { readFile, mkdir } from 'node:fs/promises'
 import { resolve, join } from 'node:path'
 import { execSync } from 'node:child_process'
 
@@ -42,6 +42,7 @@ import { resolveFoundationSrcPath, classifyPackage } from '@uniweb/build'
 import { createLocalRegistry, RemoteRegistry } from '../utils/registry.js'
 import { ensureAuth, readAuth, writeAuth, decodeJwtPayload } from '../utils/auth.js'
 import { getRegistryUrl, getBackendUrl } from '../utils/config.js'
+import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
 import { findWorkspaceRoot, findFoundations, findSites, promptSelect } from '../utils/workspace.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
 
@@ -681,7 +682,7 @@ export async function publish(args = []) {
   if (writeBackId) {
     pkg.uniweb = pkg.uniweb || {}
     pkg.uniweb.id = foundationName
-    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+    await writeJsonPreservingStyleAsync(pkgPath, pkg)
     info(`Wrote ${colors.cyan}uniweb.id: "${foundationName}"${colors.reset} to ${colors.dim}package.json${colors.reset}`)
   }
 
@@ -851,7 +852,7 @@ export async function publish(args = []) {
       if (writeBackId) {
         pkg.uniweb = pkg.uniweb || {}
         pkg.uniweb.id = foundationName
-        await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+        await writeJsonPreservingStyleAsync(pkgPath, pkg)
         info(`Wrote ${colors.cyan}uniweb.id: "${foundationName}"${colors.reset} to ${colors.dim}package.json${colors.reset}`)
       }
       console.log('')

package/src/commands/rename.js

@@ -54,6 +54,7 @@ import {
   updateRootScripts,
 } from '../utils/config.js'
 import { discoverFoundations, discoverSites } from '../utils/discover.js'
+import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
 import { getExistingPackageNames, validatePackageName } from '../utils/names.js'
 import { detectPackageManager, installCmd } from '../utils/pm.js'
 import { getCliPrefix } from '../utils/interactive.js'
@@ -184,9 +185,10 @@ async function validateRenameName(rootDir, newName) {
  * Rewrite the `name` field in a package.json file.
  */
 async function rewritePackageJsonName(pkgPath, newName) {
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+  const src = await readFile(pkgPath, 'utf-8')
+  const pkg = JSON.parse(src)
   pkg.name = newName
-  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  await writeJsonPreservingStyleAsync(pkgPath, pkg, src)
 }
 
 // ─── Foundation rename ───────────────────────────────────────────
@@ -234,11 +236,13 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
   for (const site of sites) {
     const sitePkgPath = join(rootDir, site.path, 'package.json')
     const siteYmlPath = join(rootDir, site.path, 'site.yml')
-    let pkg, ymlData
+    let pkg, pkgSrc, ymlData
     try {
-      pkg = JSON.parse(await readFile(sitePkgPath, 'utf-8'))
+      pkgSrc = await readFile(sitePkgPath, 'utf-8')
+      pkg = JSON.parse(pkgSrc)
     } catch {
       pkg = null
+      pkgSrc = null
     }
     try {
       ymlData = yaml.load(await readFile(siteYmlPath, 'utf-8')) || {}
@@ -252,6 +256,7 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
         path: site.path,
         name: site.name,
         pkg,
+        pkgSrc,
         sitePkgPath,
         siteYmlPath,
         ymlData,
@@ -295,7 +300,7 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
       s.pkg.dependencies[newName] = oldValue.startsWith('file:')
         ? `file:${newRel}`
         : oldValue  // npm-pinned, leave it; rename-then-republish is out of scope.
-      await writeFile(s.sitePkgPath, JSON.stringify(s.pkg, null, 2) + '\n')
+      await writeJsonPreservingStyleAsync(s.sitePkgPath, s.pkg, s.pkgSrc)
     }
     if (s.ymlMatches) {
       const newYmlData = { ...s.ymlData, foundation: newName }

package/src/commands/update.js

@@ -1,32 +1,40 @@
 /**
- * uniweb update — Reconcile a Uniweb workspace's state with the running
- * CLI's expectations. Three convergence steps, in order:
+ * uniweb update — Reconcile a Uniweb workspace's state with the CLI that's
+ * running this command. One job, two convergence steps:
  *
- *   1. Self-update the global CLI install (npm / pnpm / yarn auto-detected).
- *   2. Align workspace `@uniweb/*` + `uniweb` deps to the CLI's bundled
- *      version matrix (`getResolvedVersions`), then run `<pm> install`.
- *   3. Refresh AGENTS.md from the CLI's bundled partial.
+ *   1. Align workspace `@uniweb/*` + `uniweb` deps to this CLI's bundled
+ *      version matrix (`getResolvedVersions`) — only deps that *lag* the
+ *      matrix are touched; deps that are *ahead* are left alone (no
+ *      downgrades) — then run `<pm> install`.
+ *   2. Refresh AGENTS.md from this CLI's bundled partial.
  *
- * Why steps 2 and 3 belong together: AGENTS.md is regenerated from the
- * CLI's *current* partials and stamped with `cliVersion`. Refreshing it
- * while declared deps in `package.json` lag the CLI silently produces a
- * doc that documents features the installed code doesn't have. The
- * verb's drift gate refuses that combination unless `--allow-mismatch`
- * is explicit.
+ * Why those two belong together: AGENTS.md is regenerated from the CLI's
+ * *current* partials and stamped with `cliVersion`. Refreshing it while
+ * the installed `@uniweb/*` packages still lag the CLI silently produces a
+ * doc that documents features the installed code doesn't have. So step 2
+ * refuses to run unless step 1 actually completed (deps aligned *and*
+ * installed). `--allow-mismatch` overrides the declared-deps half of that
+ * gate; nothing overrides "you skipped the install" — run the install and
+ * re-run `update`.
+ *
+ * What this command does NOT do: update the CLI itself. A globally
+ * installed `uniweb` is updated through its package manager
+ * (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`, …); the version
+ * notification machinery (`utils/update-check.js`, `uniweb --version`)
+ * surfaces when that's needed. To reconcile a project against the *latest*
+ * release without touching a global install, run `npx uniweb@latest
+ * update` — npx fetches the latest CLI, which carries its own matrix.
  *
  * Flags:
- *   --agents-only       Skip self-update + deps; only refresh AGENTS.md.
- *   --deps-only         Skip self-update + AGENTS.md; only align deps.
+ *   --agents-only       Only refresh AGENTS.md (skip the deps step).
+ *   --deps-only         Only align deps (skip the AGENTS.md step).
  *   --no-agents         Skip the AGENTS.md step.
  *   --no-deps           Skip the deps-alignment step.
  *   --dry-run           Print survey + would-be writes; no mutations.
- *   --allow-mismatch    Permit AGENTS.md refresh when declared deps lag.
- *   --yes               Skip confirmation prompts (still respects gates).
- *   --non-interactive   Auto-detected; never auto-installs from a script.
- *
- * Project-local case (CLI lives in node_modules, not global): self-update
- * is a no-op (the version is pinned by package.json). Deps + AGENTS.md
- * paths still run.
+ *   --allow-mismatch    Refresh AGENTS.md even if declared deps lag.
+ *   --yes               Don't prompt — apply edits and run the install.
+ *   --non-interactive   Auto-detected; prints the plan, never mutates
+ *                       (combine with --yes to apply non-interactively).
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
@@ -34,11 +42,13 @@ import { join } from 'node:path'
 import { spawn } from 'node:child_process'
 import prompts from 'prompts'
 
-import { findWorkspaceRoot, getWorkspacePackages } from '../utils/workspace.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
 import { readAgentsVersion, generateAgentsContent } from '../utils/agents-stamp.js'
-import { getCliVersion, getResolvedVersions, updatePackageVersions } from '../versions.js'
+import { getCliVersion } from '../versions.js'
 import { isNonInteractive } from '../utils/interactive.js'
-import { detectWorkspacePm, installCmd } from '../utils/pm.js'
+import { detectWorkspacePm, installCmd, detectGlobalCliPm, globalCliUpdateCmd } from '../utils/pm.js'
+import { writeJsonPreservingStyle } from '../utils/json-file.js'
+import { surveyWorkspaceDeps, compareSemver } from '../utils/dep-survey.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -57,9 +67,9 @@ const info = (msg) => console.log(`${colors.cyan}ℹ${colors.reset} ${msg}`)
 const log = console.log
 
 /**
- * Detect whether this CLI is running from a global install. Mirrors the
- * logic in index.js::isGlobalInstall — when global, process.argv[1]
- * points outside any node_modules.
+ * Detect whether this CLI is running from a global install — when global,
+ * process.argv[1] points outside any node_modules. Mirrors
+ * index.js::isGlobalInstall.
  */
 function isGlobalInstall() {
   const scriptPath = process.argv[1]
@@ -68,6 +78,17 @@ function isGlobalInstall() {
          !scriptPath.split('\\').includes('node_modules')
 }
 
+/**
+ * Detect whether this CLI was launched via `npx uniweb …` (or `npm exec`).
+ * npx materializes the package under `…/_npx/<hash>/node_modules/uniweb/…`,
+ * which `isGlobalInstall()` can't distinguish from a real project-local
+ * dependency (both contain `node_modules`).
+ */
+function isNpxInvocation() {
+  const p = (process.argv[1] || '').replace(/\\/g, '/')
+  return p.includes('/_npx/')
+}
+
 /**
  * Find a *Uniweb* workspace root from cwd. Stricter than findWorkspaceRoot
  * — also requires that the workspace's root package.json declares uniweb
@@ -88,32 +109,7 @@ function findUniwebWorkspace(cwd) {
   }
 }
 
-/**
- * Detect the package manager that owns the *global* CLI install.
- * Path-based (different signal than detectWorkspacePm, which reads
- * lockfiles in the workspace).
- *
- * @returns {'pnpm'|'yarn'|'npm'}
- */
-function detectGlobalPm() {
-  const path = (process.argv[1] || '').toLowerCase()
-  if (path.includes('/pnpm/') || path.includes('\\pnpm\\')) return 'pnpm'
-  if (path.includes('/yarn/') || path.includes('\\yarn\\')) return 'yarn'
-  return 'npm'
-}
-
-/**
- * Build the global-install command for a given PM.
- */
-function globalInstallCmd(pm) {
-  if (pm === 'pnpm') return 'pnpm add -g uniweb@latest'
-  if (pm === 'yarn') return 'yarn global add uniweb@latest'
-  return 'npm i -g uniweb@latest'
-}
-
-/**
- * Fetch the latest published version. Returns null on network error.
- */
+/** Fetch the latest published CLI version. Returns null on network error. */
 async function fetchLatestVersion() {
   try {
     const res = await fetch('https://registry.npmjs.org/uniweb/latest')
@@ -125,32 +121,7 @@ async function fetchLatestVersion() {
   }
 }
 
-/**
- * Strip a leading semver range operator (^, ~, >=, <, etc.) so two specs
- * can be compared by their underlying version. Range expressions like
- * ">=0.5 <0.7" aren't fully parsed — we take the first version-shaped
- * token. Sufficient for `@uniweb/*` deps which use `^x.y.z` consistently.
- */
-function stripRange(spec) {
-  return (spec || '').replace(/^[\^~>=<\s]+/, '').trim().split(/\s+/)[0] || ''
-}
-
-/**
- * Compare two version specs (range prefix tolerated). Returns 1/-1/0.
- */
-function compareSemver(a, b) {
-  const pa = stripRange(a).split('.').map(Number)
-  const pb = stripRange(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
-}
-
-/**
- * Run a shell command, inheriting stdio. Resolves with the exit code.
- */
+/** Run a shell command, inheriting stdio. Resolves with the exit code. */
 function runCommand(cmd, cwd) {
   return new Promise((resolve) => {
     const [bin, ...rest] = cmd.split(' ')
@@ -160,60 +131,7 @@ function runCommand(cmd, cwd) {
   })
 }
 
-/**
- * Survey workspace `@uniweb/*` and `uniweb` deps against the CLI's
- * bundled version matrix. Returns a structured report with one row per
- * (package directory, dep section, dep name).
- *
- * Comparison is on *declared* versions (package.json), not installed
- * (node_modules) — that's what the user committed and what they'll
- * `git diff` after `applyDepUpdates`.
- */
-async function surveyVersions(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,
-        })
-      }
-    }
-  }
-
-  return { targets, rows, anyDrift, anyAhead }
-}
-
-/**
- * Print the survey report grouped by package directory.
- */
+/** Print the survey report grouped by package directory. */
 function printSurvey(report, cliVersion, agentsVersion) {
   log('')
   log(`${colors.bright}uniweb CLI:${colors.reset}             v${cliVersion}`)
@@ -256,17 +174,23 @@ function printSurvey(report, cliVersion, agentsVersion) {
 }
 
 /**
- * Apply the CLI's bundled matrix to every workspace package.json.
- * `updatePackageVersions` only touches `@uniweb/*` + `uniweb` keys, so
- * unrelated deps (`react`, `vite`, `file:../foundation`, etc.) are left
- * untouched. Returns the list of paths that actually changed.
+ * Apply the CLI's matrix to workspace package.json files — but only to
+ * deps that *lag* the matrix (survey status `behind`). Deps that are
+ * `ahead` are left alone: `update` never downgrades. Indentation and the
+ * trailing newline of each file are preserved (a one-key bump shouldn't
+ * reflow the whole file). Returns the list of paths that actually changed.
  */
-async function applyDepUpdates(workspaceDir, dryRun) {
-  const packages = await getWorkspacePackages(workspaceDir)
-  const dirs = ['', ...packages]
-  const edited = []
+function applyDepUpdates(workspaceDir, surveyRows, dryRun) {
+  const behind = surveyRows.filter(r => r.status === 'behind')
+  const byDir = {}
+  for (const row of behind) {
+    const dir = row.relDir === '(root)' ? '' : row.relDir
+    if (!byDir[dir]) byDir[dir] = []
+    byDir[dir].push(row)
+  }
 
-  for (const relDir of dirs) {
+  const edited = []
+  for (const [relDir, dirRows] of Object.entries(byDir)) {
     const pkgDir = relDir ? join(workspaceDir, relDir) : workspaceDir
     const pkgPath = join(pkgDir, 'package.json')
     if (!existsSync(pkgPath)) continue
@@ -274,12 +198,18 @@ async function applyDepUpdates(workspaceDir, dryRun) {
     let pkg
     try { pkg = JSON.parse(original) } catch { continue }
 
-    const updated = updatePackageVersions(pkg)
-    const newContent = JSON.stringify(updated, null, 2) + (original.endsWith('\n') ? '\n' : '')
+    let changed = false
+    for (const row of dirRows) {
+      const section = pkg[row.section]
+      if (section && section[row.name] !== undefined && section[row.name] !== row.target) {
+        section[row.name] = row.target
+        changed = true
+      }
+    }
 
-    if (newContent !== original) {
+    if (changed) {
       edited.push(pkgPath)
-      if (!dryRun) writeFileSync(pkgPath, newContent)
+      if (!dryRun) writeJsonPreservingStyle(pkgPath, pkg, original)
     }
   }
 
@@ -297,9 +227,10 @@ export async function update(args = []) {
   const skipDeps = args.includes('--no-deps') || agentsOnly
   const dryRun = args.includes('--dry-run')
   const allowMismatch = args.includes('--allow-mismatch')
+  const hasYes = args.includes('--yes')
   const nonInteractive = isNonInteractive(args)
-  const skipPrompt = args.includes('--yes') || nonInteractive || dryRun
   const isGlobal = isGlobalInstall()
+  const isNpx = isNpxInvocation()
   const workspaceDir = findUniwebWorkspace(process.cwd())
   const inProject = !!workspaceDir
   const cliVersion = getCliVersion()
@@ -314,88 +245,73 @@ export async function update(args = []) {
   let survey = null
   let agentsVersion = null
   if (inProject) {
-    survey = await surveyVersions(workspaceDir)
+    survey = await surveyWorkspaceDeps(workspaceDir)
     agentsVersion = readAgentsVersion(join(workspaceDir, 'AGENTS.md'))
     printSurvey(survey, cliVersion, agentsVersion)
   }
 
-  // ── Step 1: Self-update path ─────────────────────────────────────
-  if (!agentsOnly && !depsOnly) {
-    if (!isGlobal) {
-      log(`${colors.dim}Running the project-local CLI (v${cliVersion}). This copy is pinned by your${colors.reset}`)
-      log(`${colors.dim}project's package.json. To update it, bump${colors.reset} ${colors.cyan}uniweb${colors.reset}${colors.dim} in${colors.reset} ${colors.cyan}package.json${colors.reset}${colors.dim} and re-install.${colors.reset}`)
+  // ── This command reconciles the *project*, not the CLI ───────────
+  // Surface (but don't act on) a newer published CLI: this run aligns
+  // the project to *this* CLI's matrix.
+  let installPm = inProject ? detectWorkspacePm(workspaceDir) : null
+  if (isNpx) {
+    log(`${colors.dim}Running${colors.reset} ${colors.cyan}uniweb@${cliVersion}${colors.reset} ${colors.dim}via npx — aligning this project to v${cliVersion}'s matrix.${colors.reset}`)
+    log(`${colors.dim}(To install the CLI:${colors.reset} ${colors.cyan}npm i -g uniweb${colors.reset}${colors.dim}.)${colors.reset}`)
+    log('')
+  } else if (isGlobal) {
+    const latest = await fetchLatestVersion()
+    if (latest && compareSemver(latest, cliVersion) > 0) {
+      const pm = detectGlobalCliPm()
+      log(`${colors.yellow}A newer uniweb is available:${colors.reset} ${colors.dim}v${cliVersion}${colors.reset} → ${colors.cyan}v${latest}${colors.reset}`)
+      log(`${colors.dim}This run aligns the project to v${cliVersion}. To update the CLI:${colors.reset} ${colors.cyan}${globalCliUpdateCmd(pm)}${colors.reset}`)
+      log(`${colors.dim}Or, to align to the latest release without a global install:${colors.reset} ${colors.cyan}npx uniweb@latest update${colors.reset}`)
       log('')
-    } else {
-      const latest = await fetchLatestVersion()
-      if (latest === null) {
-        warn('Could not reach the npm registry to check for updates.')
-        log(`${colors.dim}Current: ${cliVersion}. Try later, or run${colors.reset} ${colors.cyan}${globalInstallCmd(detectGlobalPm())}${colors.reset}${colors.dim} manually.${colors.reset}`)
-        log('')
-      } else if (compareSemver(latest, cliVersion) <= 0) {
-        success(`uniweb is up to date (v${cliVersion}).`)
-        log('')
-      } else {
-        const pm = detectGlobalPm()
-        const cmd = globalInstallCmd(pm)
-        log(`${colors.yellow}Update available:${colors.reset} ${colors.dim}${cliVersion}${colors.reset} → ${colors.cyan}${latest}${colors.reset}`)
-        log(`${colors.dim}Detected package manager:${colors.reset} ${pm}`)
-        log(`${colors.dim}Will run:${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
-        log('')
-
-        if (dryRun) {
-          info(`${colors.dim}--dry-run: would run \`${cmd}\`.${colors.reset}`)
-          log('')
-        } else if (skipPrompt) {
-          log(`${colors.dim}Non-interactive — skipping self-update. Run the command above to update.${colors.reset}`)
-          log('')
-        } else {
-          const { go } = await prompts({
-            type: 'confirm',
-            name: 'go',
-            message: `Run \`${cmd}\` now?`,
-            initial: true,
-          })
-          if (go) {
-            const code = await runCommand(cmd)
-            if (code === 0) {
-              success(`Self-update complete.`)
-            } else {
-              error(`Self-update failed (exit ${code}). Run the command above manually if needed.`)
-            }
-            log('')
-          } else {
-            log(`${colors.dim}Skipped self-update.${colors.reset}`)
-            log('')
-          }
-        }
-      }
     }
+  } else {
+    // Project-local copy (lives in this project's node_modules).
+    log(`${colors.dim}Running the project-local CLI (v${cliVersion}) — pinned by your project's${colors.reset} ${colors.cyan}package.json${colors.reset}${colors.dim}.${colors.reset}`)
+    log(`${colors.dim}To use a newer CLI, bump${colors.reset} ${colors.cyan}uniweb${colors.reset}${colors.dim} in${colors.reset} ${colors.cyan}package.json${colors.reset}${colors.dim} and re-install, or run${colors.reset} ${colors.cyan}npx uniweb@latest update${colors.reset}${colors.dim}.${colors.reset}`)
+    log('')
+  }
+
+  if (!inProject) {
+    log(`${colors.dim}Not inside a Uniweb project — nothing to reconcile.${colors.reset}`)
+    log(`${colors.dim}Run this from a project created by${colors.reset} ${colors.cyan}uniweb create${colors.reset}${colors.dim}.${colors.reset}`)
+    log('')
+    return
   }
 
-  // ── Step 2: Deps alignment ───────────────────────────────────────
-  if (!skipDeps && inProject && survey) {
+  // ── Step 1: Deps alignment ───────────────────────────────────────
+  let depsEdited = false      // package.json files were rewritten
+  let installRan = false      // `<pm> install` ran and succeeded
+  let editedPaths = []
+
+  if (!skipDeps && survey) {
     if (!survey.anyDrift) {
       success('Workspace deps are aligned with the CLI.')
       if (survey.anyAhead) {
         log(`${colors.dim}(Some deps are ahead of the CLI's bundled matrix — left untouched.)${colors.reset}`)
       }
+      if (!existsSync(join(workspaceDir, 'node_modules'))) {
+        warn(`No ${colors.bright}node_modules${colors.reset} in the workspace — run ${colors.cyan}${installCmd(installPm || 'pnpm')}${colors.reset} to install.`)
+      }
       log('')
     } else {
       log(`${colors.yellow}⚠${colors.reset}  Some workspace deps lag the CLI's bundled matrix.`)
       log('')
 
+      // Decide whether to write the package.json edits.
       let proceed
       if (dryRun) {
         proceed = false
-      } else if (skipPrompt) {
-        proceed = !nonInteractive || args.includes('--yes')
-        // In CI without --yes, refuse to mutate. The survey above is the report.
-        if (!proceed) {
-          info(`${colors.dim}Non-interactive — printing the alignment plan; not editing files.${colors.reset}`)
-          log(`${colors.dim}To apply, re-run with${colors.reset} ${colors.cyan}--yes${colors.reset}${colors.dim}, or align manually:${colors.reset}`)
-          log(`  ${colors.cyan}pnpm update "@uniweb/*" uniweb -r${colors.reset}`)
-          log('')
-        }
+      } else if (hasYes) {
+        proceed = true
+      } else if (nonInteractive) {
+        proceed = false
+        info(`${colors.dim}Non-interactive — printing the alignment plan; not editing files.${colors.reset}`)
+        log(`${colors.dim}To apply, re-run with${colors.reset} ${colors.cyan}--yes${colors.reset}${colors.dim}, or align manually:${colors.reset}`)
+        log(`  ${colors.cyan}pnpm update "@uniweb/*" uniweb -r${colors.reset}`)
+        log('')
       } else {
         const { go } = await prompts({
           type: 'confirm',
@@ -407,32 +323,29 @@ export async function update(args = []) {
       }
 
       if (dryRun) {
-        const wouldEdit = await applyDepUpdates(workspaceDir, true)
+        const wouldEdit = applyDepUpdates(workspaceDir, survey.rows, true)
         if (wouldEdit.length > 0) {
           info('Dry-run: would update package.json in:')
           for (const path of wouldEdit) log(`  ${colors.dim}- ${relativize(path, workspaceDir)}${colors.reset}`)
-          const pm = detectWorkspacePm(workspaceDir)
-          if (pm) {
-            log(`${colors.dim}Then would run:${colors.reset} ${colors.cyan}${installCmd(pm)}${colors.reset}`)
+          if (installPm) {
+            log(`${colors.dim}Then would run:${colors.reset} ${colors.cyan}${installCmd(installPm)}${colors.reset}`)
           } else {
             log(`${colors.dim}Then would prompt for an install command (no lockfile detected).${colors.reset}`)
           }
           log('')
         }
       } else if (proceed) {
-        const edited = await applyDepUpdates(workspaceDir, false)
-        if (edited.length === 0) {
+        editedPaths = applyDepUpdates(workspaceDir, survey.rows, false)
+        depsEdited = editedPaths.length > 0
+        if (!depsEdited) {
           info('No package.json files needed changes.')
           log('')
         } else {
-          for (const path of edited) {
-            success(`Updated ${relativize(path, workspaceDir)}`)
-          }
+          for (const path of editedPaths) success(`Updated ${relativize(path, workspaceDir)}`)
           log('')
 
           // Resolve the workspace PM (lockfile-driven). If absent, ask.
-          let pm = detectWorkspacePm(workspaceDir)
-          if (!pm) {
+          if (!installPm) {
             if (nonInteractive) {
               warn('No lockfile in workspace root — cannot pick an install command for you.')
               log(`${colors.dim}Run one of:${colors.reset} ${colors.cyan}pnpm install${colors.reset} ${colors.dim}/${colors.reset} ${colors.cyan}yarn install${colors.reset} ${colors.dim}/${colors.reset} ${colors.cyan}npm install${colors.reset}`)
@@ -449,20 +362,19 @@ export async function update(args = []) {
                   { title: 'skip — I\'ll install manually', value: null },
                 ],
               })
-              pm = picked || null
+              installPm = picked || null
             }
           }
 
-          if (pm) {
-            const cmd = installCmd(pm)
+          if (installPm) {
+            const cmd = installCmd(installPm)
             let runInstall
-            if (nonInteractive) {
+            if (hasYes) {
+              runInstall = true
+            } else if (nonInteractive) {
               runInstall = false
-              info(`${colors.dim}Non-interactive — printing install command:${colors.reset}`)
-              log(`  ${colors.cyan}${cmd}${colors.reset}`)
+              info(`${colors.dim}Non-interactive — run the install yourself:${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
               log('')
-            } else if (skipPrompt) {
-              runInstall = true
             } else {
               const { go } = await prompts({
                 type: 'confirm',
@@ -476,18 +388,19 @@ export async function update(args = []) {
             if (runInstall) {
               const code = await runCommand(cmd, workspaceDir)
               if (code === 0) {
+                installRan = true
                 success('Install complete.')
                 log('')
               } else {
                 error(`Install failed (exit ${code}). package.json edits are intact.`)
-                const editedRel = edited.map(p => relativize(p, workspaceDir)).join(' ')
+                const editedRel = editedPaths.map(p => relativize(p, workspaceDir)).join(' ')
                 log(`${colors.dim}To revert:${colors.reset} ${colors.cyan}git checkout -- ${editedRel}${colors.reset}`)
                 log(`${colors.dim}To retry: ${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
                 log('')
                 process.exit(code)
               }
             } else {
-              log(`${colors.dim}Skipped install. Edits saved; run${colors.reset} ${colors.cyan}${cmd}${colors.reset} ${colors.dim}to apply.${colors.reset}`)
+              log(`${colors.dim}Skipped install. Edits saved; run${colors.reset} ${colors.cyan}${cmd}${colors.reset} ${colors.dim}to apply them.${colors.reset}`)
               log('')
             }
           }
@@ -499,52 +412,105 @@ export async function update(args = []) {
     }
   }
 
-  // ── Step 3: AGENTS.md ────────────────────────────────────────────
-  if (skipAgents) return
-  if (!inProject) {
-    // Self-update-only invocation outside a Uniweb project: quietly skip.
-    return
+  // ── Step 2: AGENTS.md ────────────────────────────────────────────
+  let agentsResult = null     // 'created' | 'updated' | 'current' | 'skipped'
+
+  if (!skipAgents) {
+    agentsResult = await refreshAgents({
+      workspaceDir, cliVersion, allowMismatch, dryRun,
+      hasYes, nonInteractive, agentsOnly, depsEdited, installRan, installPm,
+    })
+  }
+
+  // ── Closing summary ──────────────────────────────────────────────
+  if (!dryRun && (depsEdited || agentsResult === 'created' || agentsResult === 'updated')) {
+    printSummary({ editedPaths, depsEdited, installRan, installPm, agentsResult, cliVersion })
+  }
+}
+
+/**
+ * Step 2 — regenerate AGENTS.md from the CLI's bundled partial, stamped
+ * with the CLI version. Guarded: won't run if the deps were edited but
+ * not installed (the doc would describe code that isn't on disk yet), and
+ * won't run if declared deps still lag the CLI unless --allow-mismatch.
+ *
+ * @returns {'created'|'updated'|'current'|'skipped'} what happened.
+ */
+async function refreshAgents(ctx) {
+  const {
+    workspaceDir, cliVersion, allowMismatch, dryRun,
+    hasYes, nonInteractive, agentsOnly, depsEdited, installRan, installPm,
+  } = ctx
+
+  // Deps were rewritten but not installed → node_modules is now behind
+  // package.json. Refreshing the doc here would document features the
+  // installed code doesn't have. No override — run the install first.
+  if (depsEdited && !installRan) {
+    const cmd = installCmd(installPm || 'pnpm')
+    warn('AGENTS.md refresh skipped: package.json was updated but not installed.')
+    log(`${colors.dim}Your${colors.reset} ${colors.bright}node_modules${colors.reset} ${colors.dim}is behind your${colors.reset} ${colors.bright}package.json${colors.reset}${colors.dim}. Run${colors.reset} ${colors.cyan}${cmd}${colors.reset}${colors.dim}, then re-run${colors.reset} ${colors.cyan}uniweb update${colors.reset}${colors.dim}.${colors.reset}`)
+    log('')
+    return 'skipped'
   }
 
-  // Re-survey: deps may have just been edited, which clears the gate.
-  const finalSurvey = await surveyVersions(workspaceDir)
+  // Re-survey: deps may have just been edited+installed, which clears the
+  // declared-deps gate.
+  const finalSurvey = await surveyWorkspaceDeps(workspaceDir)
   if (finalSurvey.anyDrift && !allowMismatch) {
     warn('AGENTS.md refresh skipped: workspace deps still lag the CLI.')
     log(`${colors.dim}AGENTS.md from v${cliVersion} would document features not in your installed packages.${colors.reset}`)
     log(`${colors.dim}Re-run without ${colors.reset}${colors.cyan}--no-deps${colors.reset}${colors.dim}, or pass ${colors.reset}${colors.cyan}--allow-mismatch${colors.reset}${colors.dim} to override.${colors.reset}`)
     log('')
     if (agentsOnly) process.exit(1)
-    return
+    return 'skipped'
   }
 
   const agentsPath = join(workspaceDir, 'AGENTS.md')
   const currentAgentsVersion = readAgentsVersion(agentsPath)
   if (currentAgentsVersion === cliVersion) {
     success(`AGENTS.md is already up to date (v${cliVersion}).`)
-    return
+    return 'current'
   }
 
   if (dryRun) {
     info(`Dry-run: would ${currentAgentsVersion ? `update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})` : `create AGENTS.md (v${cliVersion})`}.`)
-    return
+    return 'skipped'
   }
 
-  if (!skipPrompt && !agentsOnly) {
+  if (!hasYes && !nonInteractive && !agentsOnly) {
     const action = currentAgentsVersion
       ? `Update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})?`
       : `Create AGENTS.md (v${cliVersion})?`
     const { yes } = await prompts({ type: 'confirm', name: 'yes', message: action, initial: true })
     if (!yes) {
       log(`${colors.dim}Skipped AGENTS.md.${colors.reset}`)
-      return
+      return 'skipped'
     }
   }
 
-  const content = generateAgentsContent()
-  writeFileSync(agentsPath, content)
+  writeFileSync(agentsPath, generateAgentsContent())
   if (currentAgentsVersion) {
     success(`Updated AGENTS.md (v${currentAgentsVersion} → v${cliVersion}).`)
-  } else {
-    success(`Created AGENTS.md (v${cliVersion}).`)
+    return 'updated'
   }
+  success(`Created AGENTS.md (v${cliVersion}).`)
+  return 'created'
+}
+
+/** Print a compact recap of what changed, plus a review hint. */
+function printSummary({ editedPaths, depsEdited, installRan, installPm, agentsResult, cliVersion }) {
+  log(`${colors.bright}Summary${colors.reset}`)
+  if (depsEdited) {
+    log(`  ${colors.green}✓${colors.reset} package.json updated in ${editedPaths.length} file${editedPaths.length === 1 ? '' : 's'}`)
+    if (installRan) {
+      log(`  ${colors.green}✓${colors.reset} ${installCmd(installPm || 'pnpm')} completed`)
+    } else {
+      log(`  ${colors.yellow}⚠${colors.reset} install NOT run — run ${colors.cyan}${installCmd(installPm || 'pnpm')}${colors.reset} to apply`)
+    }
+  }
+  if (agentsResult === 'created') log(`  ${colors.green}✓${colors.reset} AGENTS.md created (v${cliVersion})`)
+  else if (agentsResult === 'updated') log(`  ${colors.green}✓${colors.reset} AGENTS.md updated (v${cliVersion})`)
+  else if (agentsResult === 'skipped' && depsEdited) log(`  ${colors.dim}·${colors.reset} AGENTS.md not refreshed (see above)`)
+  log(`${colors.dim}Review changes with${colors.reset} ${colors.cyan}git diff${colors.reset}${colors.dim}, then commit.${colors.reset}`)
+  log('')
 }

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-05-12T15:22:16.890Z",
+  "generatedAt": "2026-05-13T05:21:17.590Z",
   "packages": {
     "@uniweb/build": {
       "version": "0.14.5",
@@ -49,7 +49,7 @@
       ]
     },
     "@uniweb/loom": {
-      "version": "0.2.2",
+      "version": "0.2.3",
       "path": "framework/loom",
       "deps": []
     },
@@ -92,7 +92,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.9",
+      "version": "0.4.10",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -128,9 +128,10 @@ function getCliVersion() {
  * Commands that always run from the global CLI (no project context needed)
  */
 // Commands that always run from the global CLI, never delegating to a
-// project-local copy. `update` is here because its primary job is to
-// self-update the GLOBAL install — delegating it to project-local would
-// short-circuit that intent.
+// project-local copy. `update` is here because it reconciles the project
+// against *this* CLI's version matrix — when run from a (newer) global
+// install that's the whole point; delegating to the project-local copy
+// would align the project to the version it already has, i.e. a no-op.
 const STANDALONE_COMMANDS = new Set([
   'create', '--help', '-h', '--version', '-v', 'login', 'update',
 ])
@@ -1284,39 +1285,47 @@ Prints the parsed content shape of a markdown file or folder — the
 Useful for debugging "why isn't my section getting X?".
 `,
     update: `
-${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Reconcile workspace state with the running CLI${colors.reset}
+${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Align this project with the running CLI${colors.reset}
 
 ${colors.bright}Usage:${colors.reset}
-  uniweb update                     Self-update + align deps + refresh AGENTS.md
+  uniweb update                     Align deps + refresh AGENTS.md
   uniweb update --deps-only         Only align workspace @uniweb/* deps
   uniweb update --agents-only       Only refresh AGENTS.md
   uniweb update --no-deps           Skip the deps-alignment step
   uniweb update --no-agents         Skip the AGENTS.md step
   uniweb update --dry-run           Print survey + would-be writes; no mutations
   uniweb update --allow-mismatch    Refresh AGENTS.md even if declared deps lag
-  uniweb update --yes               Skip confirmation prompts
+  uniweb update --yes               Don't prompt — apply edits and run the install
 
 ${colors.bright}What it does:${colors.reset}
   Prints a version survey first (CLI version, AGENTS.md stamp, every
   @uniweb/* + uniweb dep declared in workspace package.json files,
-  marked aligned / behind / ahead). Then three steps:
-
-  1. ${colors.bright}Self-update${colors.reset} the global install via npm / pnpm / yarn
-     (auto-detected). TTY prompts; non-interactive prints the command.
-  2. ${colors.bright}Align workspace deps${colors.reset} to the CLI's bundled version matrix —
-     edits every workspace package.json (only @uniweb/* + uniweb keys),
-     then offers to run the workspace's package manager (lockfile-detected:
-     pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm).
-     If the install fails, package.json edits are kept and a revert
-     command is printed.
-  3. ${colors.bright}Refresh AGENTS.md${colors.reset} from the CLI's bundled partial. Refuses to
-     run while declared deps still lag the CLI (would document features
-     not in your installed packages); pass --allow-mismatch to override.
+  marked aligned / behind / ahead). Then two steps:
+
+  1. ${colors.bright}Align workspace deps${colors.reset} to this CLI's bundled version matrix —
+     rewrites the @uniweb/* + uniweb keys in each package.json that lags
+     (deps ahead of the matrix are left alone — never downgraded;
+     existing indentation is preserved), then offers to run the
+     workspace's package manager (lockfile-detected: pnpm-lock.yaml →
+     pnpm, yarn.lock → yarn, package-lock.json → npm). If the install
+     fails, the package.json edits are kept and a revert command printed.
+  2. ${colors.bright}Refresh AGENTS.md${colors.reset} from this CLI's bundled partial. Won't run
+     if deps were edited but not installed (node_modules would be behind
+     package.json), or while declared deps still lag the CLI (would
+     document features not in your packages) — pass --allow-mismatch for
+     the latter.
+
+${colors.bright}Which matrix?${colors.reset}
+  \`update\` pins to the version matrix *this* CLI shipped with — not
+  necessarily the latest release. To reconcile against the latest release
+  without touching a global install, run \`npx uniweb@latest update\`. This
+  command does NOT update the CLI itself; use your package manager
+  (\`npm i -g uniweb@latest\`, \`pnpm add -g uniweb@latest\`, …).
 
 ${colors.bright}Project-local installs:${colors.reset}
-  When the running CLI is project-local (lives in node_modules), self-
-  update is a no-op — the version is pinned by your project's
-  package.json. The deps + AGENTS.md steps still run.
+  When run from a project-local CLI (in node_modules), it aligns the
+  project to that pinned version — bump \`uniweb\` in package.json (or use
+  \`npx uniweb@latest update\`) to align to something newer.
 `,
   }
 
@@ -1346,7 +1355,7 @@ ${colors.bright}Commands:${colors.reset}
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation
   doctor             Diagnose project configuration issues
-  update             Update AGENTS.md to match installed CLI version
+  update             Align workspace deps + AGENTS.md to the running CLI
   i18n <cmd>         Internationalization (extract, sync, status)
   template publish   Publish a site as a cloud template
   login              Log in to your Uniweb account

package/src/utils/config.js

@@ -20,6 +20,7 @@ import { join } from 'node:path'
 import { homedir } from 'node:os'
 import yaml from 'js-yaml'
 import { filterCmd } from './pm.js'
+import { writeJsonPreservingStyleAsync } from './json-file.js'
 
 // ── Platform URLs ──────────────────────────────────────────────
 
@@ -154,13 +155,19 @@ export async function readRootPackageJson(rootDir) {
 }
 
 /**
- * Write root package.json (2-space indent)
+ * Write root package.json, preserving the file's existing indentation
+ * (newly scaffolded workspaces use 2-space; we don't reflow whatever's
+ * already there).
  * @param {string} rootDir - Workspace root directory
  * @param {Object} pkg - Package.json object
  */
 export async function writeRootPackageJson(rootDir, pkg) {
   const pkgPath = join(rootDir, 'package.json')
-  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  if (existsSync(pkgPath)) {
+    await writeJsonPreservingStyleAsync(pkgPath, pkg)
+  } else {
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  }
 }
 
 /**

package/src/utils/dep-survey.js

@@ -0,0 +1,99 @@
+/**
+ * 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] || ''
+}
+
+/**
+ * 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 })
+      }
+    }
+  }
+
+  return { targets, rows, anyDrift, anyAhead }
+}

package/src/utils/json-file.js

@@ -0,0 +1,68 @@
+/**
+ * Style-preserving JSON file writes.
+ *
+ * The CLI rewrites `package.json` in several places (`update`, `doctor`,
+ * `rename`, `add`). A naive `JSON.stringify(obj, null, 2)` reflows the
+ * *entire* file whenever the project happened to use tabs or 4-space
+ * indentation — turning a one-key version bump into a hundred-line diff
+ * (and a needless merge-conflict surface). `framework/CLAUDE.md` calls
+ * this out as an anti-pattern for human commits; the tooling shouldn't do
+ * it either. These helpers detect the file's existing indentation and
+ * trailing-newline convention and preserve both.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+
+/**
+ * Detect the indentation unit a JSON source string uses.
+ * @param {string} src
+ * @returns {number|string} A space count, or '\t' for tab-indented files.
+ *   Defaults to 2 when the file has no indented lines (e.g. `{}`).
+ */
+export function detectJsonIndent(src) {
+  const m = src.match(/\n([ \t]+)\S/)
+  if (!m) return 2
+  const lead = m[1]
+  if (lead.includes('\t')) return '\t'
+  return lead.length
+}
+
+/**
+ * Serialize `obj` to JSON using the indentation and trailing-newline
+ * convention of `originalSrc` (or of the file currently at `filePath`).
+ * @param {object} obj
+ * @param {string} originalSrc - The file's current text.
+ * @returns {string}
+ */
+export function stringifyJsonLike(obj, originalSrc) {
+  const indent = detectJsonIndent(originalSrc)
+  const body = JSON.stringify(obj, null, indent)
+  return originalSrc.endsWith('\n') ? body + '\n' : body
+}
+
+/**
+ * Write `obj` to `filePath` as JSON, preserving the file's existing
+ * indentation and trailing-newline convention. Pass `originalSrc` when
+ * the caller already has the file contents in hand (avoids a re-read);
+ * otherwise the file is read to sniff its style.
+ * @param {string} filePath
+ * @param {object} obj
+ * @param {string|null} [originalSrc]
+ */
+export function writeJsonPreservingStyle(filePath, obj, originalSrc = null) {
+  const src = originalSrc ?? readFileSync(filePath, 'utf8')
+  writeFileSync(filePath, stringifyJsonLike(obj, src))
+}
+
+/**
+ * Async counterpart to {@link writeJsonPreservingStyle}, for the CLI's
+ * many `node:fs/promises`-based call sites.
+ * @param {string} filePath
+ * @param {object} obj
+ * @param {string|null} [originalSrc]
+ */
+export async function writeJsonPreservingStyleAsync(filePath, obj, originalSrc = null) {
+  const src = originalSrc ?? await readFile(filePath, 'utf8')
+  await writeFile(filePath, stringifyJsonLike(obj, src))
+}

package/src/utils/pm.js

@@ -40,6 +40,35 @@ export function detectWorkspacePm(workspaceRoot) {
   return null
 }
 
+/**
+ * Detect which package manager owns a *globally installed* `uniweb` CLI
+ * binary, by inspecting its install path (`process.argv[1]`). pnpm and
+ * yarn keep global packages under recognizable directory segments;
+ * everything else is assumed to be npm. Only meaningful when the CLI is
+ * actually a global install (see index.js::isGlobalInstall) — a
+ * project-local or npx-launched copy is updated differently.
+ *
+ * @returns {'pnpm' | 'yarn' | 'npm'}
+ */
+export function detectGlobalCliPm() {
+  const path = (process.argv[1] || '').toLowerCase().replace(/\\/g, '/')
+  if (path.includes('/pnpm/')) return 'pnpm'
+  if (path.includes('/yarn/')) return 'yarn'
+  return 'npm'
+}
+
+/**
+ * The command to (re)install the latest `uniweb` CLI globally with a
+ * given package manager.
+ * @param {'pnpm' | 'yarn' | 'npm'} pm
+ * @returns {string}
+ */
+export function globalCliUpdateCmd(pm) {
+  if (pm === 'pnpm') return 'pnpm add -g uniweb@latest'
+  if (pm === 'yarn') return 'yarn global add uniweb@latest'
+  return 'npm i -g uniweb@latest'
+}
+
 /**
  * Generate a workspace-filtered command.
  * pnpm: "pnpm --filter site dev"

package/src/utils/scaffold.js

@@ -13,6 +13,7 @@ import yaml from 'js-yaml'
 import Handlebars from 'handlebars'
 import { copyTemplateDirectory, enumerateTemplateOutputs, registerVersions } from '../templates/processor.js'
 import { getVersionsForTemplates, getCliVersion } from '../versions.js'
+import { writeJsonPreservingStyleAsync } from './json-file.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates')
@@ -380,12 +381,13 @@ function resolveDependencyVersion(rawValue) {
  */
 export async function mergeTemplateDependencies(packageJsonPath, deps) {
   if (!deps || Object.keys(deps).length === 0) return
-  const pkg = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'))
+  const src = await fs.readFile(packageJsonPath, 'utf-8')
+  const pkg = JSON.parse(src)
   if (!pkg.dependencies) pkg.dependencies = {}
   for (const [name, version] of Object.entries(deps)) {
     if (!pkg.dependencies[name] && !pkg.devDependencies?.[name]) {
       pkg.dependencies[name] = resolveDependencyVersion(version)
     }
   }
-  await fs.writeFile(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n')
+  await writeJsonPreservingStyleAsync(packageJsonPath, pkg, src)
 }

package/src/utils/update-check.js

@@ -9,6 +9,7 @@
 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')
@@ -62,14 +63,15 @@ function printNotification(current, latest, tone = 'soft') {
   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} npm i -g uniweb`)
+    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} npm i -g uniweb ${dim}to update${reset}`)
+    console.error(`${dim}Run${reset} ${updateCmd} ${dim}to update the CLI${reset}`)
   }
 }
 

package/src/versions.js

@@ -76,9 +76,16 @@ function getFrameworkRoot() {
 
 /**
  * Read the current on-disk version of a specific `@uniweb/*` package by
- * looking up `framework/<last-segment>/package.json`. Returns a caret
- * range string like `^0.6.0`, or null if the package isn't present on
- * disk (i.e. the CLI is running from npm, not from the workspace).
+ * looking up `framework/<last-segment>/package.json`. Returns the version
+ * string verbatim (e.g. `0.7.11`), or null if the package isn't present
+ * on disk (i.e. the CLI is running from npm, not from the workspace).
+ *
+ * Returns the version *exact*, not as a caret range, to match the shape
+ * published-CLI direct deps take after pnpm resolves `workspace:*` at
+ * publish time. Both modes converge on identical specs in
+ * `getResolvedVersions()`, so `uniweb update` and the scaffolder produce
+ * the same `package.json` whether the CLI ran from npm or from this
+ * monorepo.
  */
 function readWorkspaceVersion(packageName) {
   const root = getFrameworkRoot()
@@ -90,7 +97,7 @@ function readWorkspaceVersion(packageName) {
   try {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
     if (pkg.name === packageName && pkg.version) {
-      return `^${pkg.version}`
+      return pkg.version
     }
   } catch {}
   return null