uniweb 0.12.11 → 0.12.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.11",
+  "version": "0.12.12",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/runtime": "0.8.13",
     "@uniweb/core": "0.7.11",
+    "@uniweb/runtime": "0.8.13",
     "@uniweb/kit": "0.9.11"
   },
   "peerDependencies": {
     "@uniweb/build": "0.14.2",
-    "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/content-reader": "1.1.10"
+    "@uniweb/content-reader": "1.1.10",
+    "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/commands/update.js

@@ -1,16 +1,47 @@
 /**
- * uniweb update - Update generated project files
+ * uniweb update — Update the CLI itself, and (in a Uniweb project) the
+ * project's AGENTS.md.
  *
- * Regenerates AGENTS.md from the installed CLI version.
+ * Two responsibilities, in priority order:
+ *
+ * 1. **Self-update the global install.** Most users running `uniweb update`
+ *    expect the verb to update the CLI binary itself (this is what `npm
+ *    update -g`, `gh update`, `claude update`, etc. all do). The CLI
+ *    detects the relevant package manager and runs the global-install
+ *    command for it (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`,
+ *    `yarn global add uniweb@latest`). In TTY, prompts before executing.
+ *    In non-interactive mode, prints the command and exits — never runs an
+ *    unconfirmed self-update from a script.
+ *
+ * 2. **Refresh AGENTS.md** (only when the cwd resolves to a *Uniweb*
+ *    project — checked via `package.json::devDependencies::uniweb` or
+ *    `dependencies::uniweb` at the workspace root). The previous
+ *    implementation walked up looking for ANY pnpm-workspace.yaml or
+ *    `package.json::workspaces` root, which falsely identified unrelated
+ *    monorepos as Uniweb projects and wrote AGENTS.md into them.
+ *
+ * Flags:
+ *   --agents-only        Skip self-update; only refresh AGENTS.md.
+ *   --no-agents          Skip AGENTS.md; only self-update.
+ *   --yes                Skip the confirmation prompt before self-update.
+ *   --non-interactive    Auto-detected; never runs unconfirmed self-update.
+ *
+ * Project-local case (CLI lives in node_modules, not global): self-update
+ * isn't possible — that's a project decision (bump the dep in
+ * package.json). The verb prints that explanation and proceeds with the
+ * AGENTS.md refresh path only.
  */
 
-import { existsSync, writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawn } from 'node:child_process'
+import prompts from 'prompts'
+
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import { readAgentsVersion, generateAgentsContent } from '../utils/agents-stamp.js'
 import { getCliVersion } from '../versions.js'
+import { isNonInteractive } from '../utils/interactive.js'
 
-// ANSI colors
 const colors = {
   reset: '\x1b[0m',
   bright: '\x1b[1m',
@@ -18,7 +49,7 @@ const colors = {
   red: '\x1b[31m',
   green: '\x1b[32m',
   yellow: '\x1b[33m',
-  blue: '\x1b[36m'
+  cyan: '\x1b[36m',
 }
 
 const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
@@ -26,30 +57,196 @@ const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
 const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
 const log = console.log
 
-export async function update(args = []) {
-  const workspaceDir = findWorkspaceRoot(process.cwd())
+/**
+ * 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.
+ */
+function isGlobalInstall() {
+  const scriptPath = process.argv[1]
+  if (!scriptPath) return false
+  return !scriptPath.split('/').includes('node_modules') &&
+         !scriptPath.split('\\').includes('node_modules')
+}
 
-  if (!workspaceDir) {
-    error('Not in a Uniweb workspace')
-    log(`${colors.dim}Run this command from your project root or a package directory.${colors.reset}`)
-    process.exit(1)
+/**
+ * Find a *Uniweb* workspace root from cwd. Stricter than findWorkspaceRoot
+ * — also requires that the workspace's root package.json declares uniweb
+ * as a dep or devDep. Otherwise the previous behavior (walking up to any
+ * pnpm-workspace.yaml) writes AGENTS.md into unrelated monorepos.
+ */
+function findUniwebWorkspace(cwd) {
+  const workspaceDir = findWorkspaceRoot(cwd)
+  if (!workspaceDir) return null
+  const pkgPath = join(workspaceDir, 'package.json')
+  if (!existsSync(pkgPath)) return null
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    const hasUniwebDep = !!(pkg.devDependencies?.uniweb || pkg.dependencies?.uniweb)
+    return hasUniwebDep ? workspaceDir : null
+  } catch {
+    return null
   }
+}
 
+/**
+ * Detect the package manager that owns the global install. Heuristic
+ * based on the CLI's filesystem path — pnpm and yarn berry use distinctive
+ * directory layouts; npm is the fallback.
+ *
+ * @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.
+ */
+async function fetchLatestVersion() {
+  try {
+    const res = await fetch('https://registry.npmjs.org/uniweb/latest')
+    if (!res.ok) return null
+    const data = await res.json()
+    return data?.version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Compare two semver strings: 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
+}
+
+/**
+ * Run a shell command, inheriting stdio. Resolves with the exit code.
+ */
+function runCommand(cmd) {
+  return new Promise((resolve) => {
+    const [bin, ...rest] = cmd.split(' ')
+    const child = spawn(bin, rest, { stdio: 'inherit' })
+    child.on('close', code => resolve(code ?? 0))
+    child.on('error', () => resolve(1))
+  })
+}
+
+export async function update(args = []) {
+  const agentsOnly = args.includes('--agents-only')
+  const skipAgents = args.includes('--no-agents')
+  const skipPrompt = args.includes('--yes') || isNonInteractive(args)
+  const isGlobal = isGlobalInstall()
+  const workspaceDir = findUniwebWorkspace(process.cwd())
+  const inProject = !!workspaceDir
   const cliVersion = getCliVersion()
-  const agentsPath = join(workspaceDir, 'AGENTS.md')
-  const currentVersion = readAgentsVersion(agentsPath)
 
-  if (currentVersion === cliVersion) {
-    success(`AGENTS.md is already up to date (v${cliVersion})`)
+  // ─── Step 1: Self-update path ─────────────────────────────────
+  if (!agentsOnly) {
+    if (!isGlobal) {
+      // Project-local: can't self-update meaningfully.
+      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}`)
+      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 (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('')
+          }
+        }
+      }
+    }
+  }
+
+  // ─── Step 2: AGENTS.md refresh path ───────────────────────────
+  if (skipAgents) return
+  if (!inProject) {
+    if (agentsOnly) {
+      error('Not in a Uniweb project (no `uniweb` dep in the workspace root package.json).')
+      log(`${colors.dim}Run this command from inside a project created by${colors.reset} ${colors.cyan}uniweb create${colors.reset}${colors.dim}.${colors.reset}`)
+      process.exit(1)
+    }
+    // Self-update-only path. Quietly skip AGENTS.md.
     return
   }
 
+  const agentsPath = join(workspaceDir, 'AGENTS.md')
+  const currentAgentsVersion = readAgentsVersion(agentsPath)
+  if (currentAgentsVersion === cliVersion) {
+    success(`AGENTS.md is already up to date (v${cliVersion}).`)
+    return
+  }
+
+  // Prompt before writing in TTY, unless --yes / non-interactive (in which
+  // case we err on the side of doing the right thing — refresh — since the
+  // user explicitly invoked `uniweb update` from a Uniweb project).
+  if (!skipPrompt && !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
+    }
+  }
+
   const content = generateAgentsContent()
   writeFileSync(agentsPath, content)
-
-  if (currentVersion) {
-    success(`Updated AGENTS.md (v${currentVersion} → v${cliVersion})`)
+  if (currentAgentsVersion) {
+    success(`Updated AGENTS.md (v${currentAgentsVersion} → v${cliVersion}).`)
   } else {
-    success(`Created AGENTS.md (v${cliVersion})`)
+    success(`Created AGENTS.md (v${cliVersion}).`)
   }
 }

package/src/index.js

@@ -103,8 +103,12 @@ 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.
 const STANDALONE_COMMANDS = new Set([
-  'create', '--help', '-h', '--version', '-v', 'login',
+  'create', '--help', '-h', '--version', '-v', 'login', 'update',
 ])
 
 /**
@@ -441,8 +445,20 @@ async function main() {
   const pm = detectPackageManager()
 
   // Handle --version / -v
+  //
+  // Output convention: the version goes to stdout (parseable, scriptable —
+  // `version=$(uniweb --version)` should keep working). Any staleness
+  // notice goes to stderr, so it shows in interactive terminals but
+  // doesn't pollute captured output. Cache-only — never makes a network
+  // call from this path.
   if (command === '--version' || command === '-v') {
     console.log(`uniweb ${getCliVersion()}`)
+    if (isGlobalInstall()) {
+      try {
+        const { maybeNotifyFromCache } = await import('./utils/update-check.js')
+        maybeNotifyFromCache(getCliVersion(), 'soft')
+      } catch { /* ignore */ }
+    }
     return
   }
 
@@ -1139,14 +1155,28 @@ 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}— Update AGENTS.md to match installed CLI version${colors.reset}
+${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Update the CLI itself, plus AGENTS.md when in a project${colors.reset}
 
 ${colors.bright}Usage:${colors.reset}
-  uniweb update
-
-Refreshes the project's AGENTS.md from the CLI's bundled version. Run
-after upgrading the \`uniweb\` package to pick up new content authoring
-patterns and platform documentation.
+  uniweb update                Self-update + (in project) refresh AGENTS.md
+  uniweb update --agents-only  Only refresh AGENTS.md (skip self-update)
+  uniweb update --no-agents    Only self-update (skip AGENTS.md)
+  uniweb update --yes          Skip the confirmation prompts
+
+${colors.bright}What it does:${colors.reset}
+  1. Self-update the global install via npm / pnpm / yarn (auto-detected).
+     In TTY, prompts before running. In CI / non-interactive, prints the
+     command and exits without running it.
+  2. If the cwd resolves to a Uniweb project (root package.json declares
+     \`uniweb\` as a dep), refreshes AGENTS.md from the CLI's bundled
+     version. Outside a Uniweb project, this step is skipped — the
+     command will not write AGENTS.md into unrelated directories.
+
+${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 verb prints that explanation and proceeds with the
+  AGENTS.md refresh path only.
 `,
   }
 

package/src/utils/update-check.js

@@ -74,26 +74,33 @@ function printNotification(current, latest, tone = 'soft') {
 }
 
 /**
- * Synchronously read the cache and print an eager notification if a newer
+ * 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.
  *
- * Use this for staleness-sensitive verbs (`create`) BEFORE the verb does
- * its work, so the user sees the warning before any files are written
- * from CLI-bundled templates. For other verbs, the trailing soft
- * notification from startUpdateCheck() is sufficient.
+ * Two call sites today, with different tone needs:
+ *   - `create` (tone='eager'): loud leading notice — templates ship with
+ *     the CLI, the user is about to scaffold files, this matters.
+ *   - `--version` / `-v` (tone='soft'): brief trailing notice — the user
+ *     was already asking about version, mention staleness while we're
+ *     here. Goes to stderr so scripts capturing stdout aren't affected.
  *
  * @param {string} currentVersion
+ * @param {'eager'|'soft'} [tone='eager']
  * @returns {boolean} true if a notification was printed
  */
-export function maybeEagerNotification(currentVersion) {
+export function maybeNotifyFromCache(currentVersion, tone = 'eager') {
   const state = readState()
   if (!state.latestVersion) return false
   if (compareSemver(state.latestVersion, currentVersion) <= 0) return false
-  printNotification(currentVersion, state.latestVersion, 'eager')
+  printNotification(currentVersion, state.latestVersion, tone)
   return true
 }
 
+// Old name preserved as alias — `create` calls it without a tone arg
+// and gets the eager default. Keeps that call site unchanged.
+export const maybeEagerNotification = maybeNotifyFromCache
+
 /**
  * Start a non-blocking update check.
  *