dxai-cli 1.0.0

package/src/registry/validate.js

@@ -0,0 +1,209 @@
+// Validation for registry-supplied values that flow into shell/exec/URL sinks.
+//
+// The catalog is fetched over the network (cache-over-bundled, see loader.js) and
+// is only shape-checked on fetch. Any field that ends up in a spawned command, an
+// installed package name, or a fetch URL must be validated here first, so a
+// poisoned or redirected registry cannot achieve command execution or repoint a
+// fetch.
+
+// owner/name — exactly two path-safe segments (e.g. "anthropics/skills").
+const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+// A skill's sub-path within its repo: "." or slash-separated safe segments,
+// never absolute, never containing a ".." traversal segment.
+const SKILL_PATH_RE = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+
+// npm package specifier (optionally scoped), no shell metacharacters.
+const PACKAGE_SPEC_RE = /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i;
+
+// Same, but allowing a trailing `@version` (e.g. "@scope/pkg@1.2.3", "pkg@latest").
+const PACKAGE_SPEC_VERSIONED_RE = /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*(@[\w.-]+)?$/i;
+
+// Version / branch ref used to repoint the registry base URL. Path-safe, no
+// traversal — a "../.." here would repoint the fetch at a different repo.
+const VERSION_REF_RE = /^[A-Za-z0-9._-]+$/;
+
+// Official MCP Registry server name: reverse-DNS namespace, one slash, name
+// (schema pattern). E.g. "io.github.upstash/context7", "com.supabase/mcp".
+const REGISTRY_NAME_RE = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+
+// Catalog fields the registry resolver may own (see mcp-registry.js). Anything
+// else on an entry is curated by hand and never touched by a sync.
+export const RESOLVABLE_FIELDS = ['transport', 'requiresEnv', 'requiresInput', 'version', 'stale', 'staleReason'];
+const PREFER_TRANSPORTS = new Set(['remote', 'package']);
+
+// A bare binary name (no path separators, no shell metacharacters). Used for
+// registry fields that name a command to *probe* for (e.g. a tool's
+// `detectCommand`) — probing must never be able to execute anything else.
+const BINARY_NAME_RE = /^[A-Za-z0-9._-]+$/;
+
+// Binaries we are willing to spawn from registry data. Everything else is a
+// command we don't recognize and won't execute on the user's behalf.
+const COMMAND_ALLOWLIST = new Set([
+  'npx', 'node', 'npm', 'bunx', 'bun', 'pnpm', 'yarn', 'deno',
+  'uvx', 'uv', 'pipx', 'pip', 'pip3', 'python', 'python3', 'docker', 'claude',
+]);
+
+export function isValidRepo(repo) {
+  return typeof repo === 'string' && REPO_RE.test(repo);
+}
+
+export function isValidSkillPath(p) {
+  if (typeof p !== 'string') return false;
+  if (p === '.') return true;
+  return SKILL_PATH_RE.test(p) && !p.split('/').includes('..');
+}
+
+export function isPackageSpec(tok) {
+  return typeof tok === 'string' && PACKAGE_SPEC_RE.test(tok);
+}
+
+export function isAllowedCommand(cmd) {
+  return typeof cmd === 'string' && COMMAND_ALLOWLIST.has(cmd);
+}
+
+export function isSafeVersionRef(v) {
+  return typeof v === 'string' && VERSION_REF_RE.test(v) && !v.split('/').includes('..');
+}
+
+export function isSafeBinaryName(name) {
+  return typeof name === 'string' && BINARY_NAME_RE.test(name);
+}
+
+export function isValidRegistryName(name) {
+  return typeof name === 'string' && REGISTRY_NAME_RE.test(name);
+}
+
+// Registry-supplied remote URLs are written into user configs and probed by
+// catalog-health; only accept https so a poisoned record can't point a client
+// at a plaintext endpoint.
+export function isHttpsUrl(value) {
+  if (typeof value !== 'string') return false;
+  try {
+    return new URL(value).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+// Shape-check an entry's optional `registry` block (the link to the official
+// MCP Registry). Returns problem strings; empty when clean or absent.
+export function validateRegistryBlock(id, block) {
+  if (block === undefined) return [];
+  const problems = [];
+  if (!block || typeof block !== 'object') return [`server ${id}: registry must be an object`];
+  if (!isValidRegistryName(block.name)) problems.push(`server ${id}: invalid registry name "${block.name}"`);
+  const { prefer, resolved } = block;
+  if (prefer !== undefined) {
+    if (!prefer || typeof prefer !== 'object') problems.push(`server ${id}: registry.prefer must be an object`);
+    else {
+      if (prefer.transport !== undefined && !PREFER_TRANSPORTS.has(prefer.transport)) {
+        problems.push(`server ${id}: registry.prefer.transport must be remote|package`);
+      }
+      if (prefer.remote !== undefined && typeof prefer.remote !== 'string') {
+        problems.push(`server ${id}: registry.prefer.remote must be a string`);
+      }
+      if (prefer.pin !== undefined && typeof prefer.pin !== 'boolean') {
+        problems.push(`server ${id}: registry.prefer.pin must be a boolean`);
+      }
+    }
+  }
+  if (resolved !== undefined) {
+    if (!resolved || typeof resolved !== 'object' || !Array.isArray(resolved.fields)) {
+      problems.push(`server ${id}: registry.resolved must carry a fields array`);
+    } else {
+      for (const f of resolved.fields) {
+        if (!RESOLVABLE_FIELDS.includes(f)) problems.push(`server ${id}: registry.resolved.fields has unknown field "${f}"`);
+      }
+    }
+  }
+  return problems;
+}
+
+// Reject registry ids that could pollute Object.prototype when used as a map key.
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+export function isSafeId(id) {
+  return typeof id === 'string' && id.length > 0 && !UNSAFE_KEYS.has(id);
+}
+
+// Split a registry-supplied install command string into argv for shell-free
+// execution. Rejects any shell metacharacter so the string can never be
+// interpreted as more than a single command + plain arguments. Throws on an
+// unsafe command or a disallowed leading binary.
+const SHELL_META_RE = /[;&|`$(){}<>\\"'*?~\n\r]/;
+export function parseSafeCommand(str) {
+  if (typeof str !== 'string' || !str.trim()) {
+    throw new Error('empty command');
+  }
+  if (SHELL_META_RE.test(str)) {
+    throw new Error(`command contains shell metacharacters: ${str}`);
+  }
+  const parts = str.trim().split(/\s+/);
+  const [command, ...args] = parts;
+  if (!isAllowedCommand(command)) {
+    throw new Error(`command not in allowlist: ${command}`);
+  }
+  return { command, args };
+}
+
+// Validate a server's spawn/transport spec before it is executed (handshake) or
+// recorded. Returns true only when the command is allowlisted and every npm
+// package argument is a clean package spec.
+// Defense-in-depth at the fetch boundary: vet a freshly-fetched registry payload
+// before it is cached and trusted by every later run. Returns an array of problem
+// strings (empty = clean). Each entry's id must be map-key-safe; command-bearing
+// fields must use an allowlisted binary; skills' repo/path must be clean. A bad
+// file is rejected wholesale (caller falls back to the bundled snapshot) rather
+// than silently caching a poisoned entry.
+export function validateRegistryPayload(listKey, items) {
+  const problems = [];
+  for (const item of items) {
+    const id = item?.id;
+    if (!isSafeId(id)) {
+      problems.push(`entry with invalid id: ${JSON.stringify(id)}`);
+      continue;
+    }
+    if (listKey === 'skills') {
+      if (!isValidRepo(item.repo)) problems.push(`skill ${id}: invalid repo "${item.repo}"`);
+      if (!isValidSkillPath(item.path)) problems.push(`skill ${id}: invalid path "${item.path}"`);
+    } else if (listKey === 'tools') {
+      for (const cmd of Object.values(item.installCommand || {})) {
+        try { parseSafeCommand(cmd); }
+        catch (err) { problems.push(`tool ${id}: ${err.message}`); }
+      }
+      // detectCommand is probed for existence on the user's PATH; a poisoned
+      // value must not be able to smuggle anything past that probe.
+      if (item.detectCommand !== undefined && !isSafeBinaryName(item.detectCommand)) {
+        problems.push(`tool ${id}: detectCommand is not a bare binary name "${item.detectCommand}"`);
+      }
+    } else if (listKey === 'servers') {
+      problems.push(...validateRegistryBlock(id, item.registry));
+      const cmd = item.transport?.command;
+      if (cmd !== undefined && !isAllowedCommand(cmd)) {
+        problems.push(`server ${id}: transport command not allowlisted "${cmd}"`);
+      }
+      for (const [agent, cfg] of Object.entries(item.configs || {})) {
+        if (cfg && typeof cfg.command === 'string' && cfg.command !== 'claude' && !isAllowedCommand(cfg.command)) {
+          problems.push(`server ${id} (${agent}): command not allowlisted "${cfg.command}"`);
+        }
+      }
+      if (item.excludeAgents !== undefined && !(Array.isArray(item.excludeAgents) && item.excludeAgents.every(isSafeId))) {
+        problems.push(`server ${id}: excludeAgents must be a list of agent ids`);
+      }
+    }
+  }
+  return problems;
+}
+
+const PACKAGE_LAUNCHERS = new Set(['npx', 'bunx', 'uvx', 'pnpm']);
+export function isSafeSpawnSpec(spec) {
+  if (!spec || !isAllowedCommand(spec.command)) return false;
+  const args = spec.args || [];
+  if (!Array.isArray(args)) return false;
+  // For npx/uvx-style launchers the package name is the payload — vet it.
+  if (PACKAGE_LAUNCHERS.has(spec.command)) {
+    const pkg = args.find((a) => typeof a === 'string' && !a.startsWith('-') && a !== 'dlx');
+    if (pkg && !PACKAGE_SPEC_VERSIONED_RE.test(pkg)) return false;
+  }
+  return true;
+}

package/src/rollback.js

@@ -0,0 +1,182 @@
+// `dxai rollback` — restore a config/project file from the most recent
+// `.bak.<ts>` snapshot dxai wrote before it last modified that file.
+//
+// Every writer backs up the target as `<file>.bak.<ts>` (see backupFile in
+// config-writer.js). This command finds those snapshots next to the files dxai
+// manages, picks the newest per file, and restores it — snapshotting the current
+// file first so the rollback is itself reversible.
+
+import inquirer from 'inquirer';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+import {
+  printBanner, sectionHeader, successMsg, warnMsg, infoMsg, theme,
+} from './branding.js';
+import { AGENT_DEFINITIONS } from './detect.js';
+import { scanBackupFiles, scanProjectFiles } from './config-remover.js';
+
+// Timestamp suffix of a `<name>.bak.<ts>` file (`YYYY-MM-DDTHH-MM-SS`), or '' if
+// the name doesn't carry one.
+const BAK_RE = /\.bak\.([0-9T-]+)$/;
+export function backupTimestamp(backupPath) {
+  const m = path.basename(backupPath).match(BAK_RE);
+  return m ? m[1] : '';
+}
+
+// The most recent `.bak.<ts>` sibling of `originalPath`, or null if none exist.
+// The timestamp format is lexicographically ordered, so a string max is
+// chronological — no date parsing needed.
+export function latestBackupFor(originalPath) {
+  const backups = scanBackupFiles([originalPath]).filter((b) => BAK_RE.test(b));
+  if (backups.length === 0) return null;
+  let best = null;
+  let bestTs = '';
+  for (const b of backups) {
+    const ts = backupTimestamp(b);
+    if (ts >= bestTs) { bestTs = ts; best = b; }
+  }
+  return { backup: best, ts: bestTs };
+}
+
+// For each candidate original path, find its newest backup. Returns
+// [{ original, backup, ts }] only for paths that actually have a backup.
+export function collectRestorable(originalPaths) {
+  const out = [];
+  const seen = new Set();
+  for (const original of originalPaths) {
+    if (!original || seen.has(original)) continue;
+    seen.add(original);
+    const latest = latestBackupFor(original);
+    if (latest) out.push({ original, backup: latest.backup, ts: latest.ts });
+  }
+  return out;
+}
+
+// Fresh backup timestamp, mirroring config-writer's backupFile format.
+function nowTs() {
+  return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+// Restore `backup` over `original`, first snapshotting the current `original`
+// (when it exists) to `<original>.bak.<ts>` so the rollback can be undone.
+export function restoreBackup(original, backup, { dryRun = false } = {}) {
+  const result = { original, backup, savedCurrentTo: null };
+  if (dryRun) return result;
+  if (fs.existsSync(original)) {
+    const snapshot = `${original}.bak.${nowTs()}`;
+    fs.copySync(original, snapshot);
+    result.savedCurrentTo = snapshot;
+  }
+  fs.copySync(backup, original, { overwrite: true });
+  return result;
+}
+
+// The files dxai may have backed up: file-based agent global configs (CLI agents
+// write no files) plus dxai-generated project files in the cwd.
+function candidateOriginals(home, cwd) {
+  const agentPaths = AGENT_DEFINITIONS
+    .filter((a) => a.configFormat !== 'cli')
+    .map((a) => { try { return a.globalMcpPath(home); } catch { return null; } })
+    .filter(Boolean);
+  const projectPaths = scanProjectFiles(cwd).map((f) => f.absolutePath);
+  return [...agentPaths, ...projectPaths];
+}
+
+// Render an absolute path with the home dir collapsed to `~` for readability.
+function displayPath(p, home) {
+  return p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p;
+}
+
+export async function rollbackCmd(opts = {}) {
+  const json = !!opts.json;
+  const dryRun = !!opts.dryRun || process.env.DXAI_DRY_RUN === '1';
+  const listOnly = !!opts.list;
+  const home = os.homedir();
+  const cwd = process.cwd();
+
+  const restorable = collectRestorable(candidateOriginals(home, cwd));
+
+  if (!json) {
+    printBanner();
+    sectionHeader('Rollback — restore config backups');
+  }
+
+  if (restorable.length === 0) {
+    if (json) {
+      process.stdout.write(JSON.stringify({ ok: true, restored: [], available: [] }, null, 2) + '\n');
+    } else {
+      infoMsg('No dxai backup files (.bak.*) found to restore from.');
+      console.log();
+    }
+    return;
+  }
+
+  // List-only: report available backups and stop.
+  if (listOnly) {
+    if (json) {
+      process.stdout.write(JSON.stringify({ ok: true, available: restorable }, null, 2) + '\n');
+      return;
+    }
+    for (const r of restorable) {
+      console.log(`  ${theme.label(displayPath(r.original, home))}`);
+      console.log(`    ${theme.dim(`↩ ${path.basename(r.backup)}`)}`);
+    }
+    console.log();
+    infoMsg('Run `dxai rollback` to restore, or `--dry-run` to preview.');
+    console.log();
+    return;
+  }
+
+  // Select which files to restore. Non-interactive (--yes / --json) restores the
+  // latest backup for every file; interactive lets the user pick.
+  let selected = restorable;
+  if (!opts.yes && !json) {
+    const { picks } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'picks',
+        message: 'Select files to restore from their latest backup:',
+        choices: restorable.map((r) => ({
+          name: `${displayPath(r.original, home)}  ${theme.dim(`(${path.basename(r.backup)})`)}`,
+          value: r.original,
+          checked: true,
+        })),
+      },
+    ]);
+    selected = restorable.filter((r) => picks.includes(r.original));
+  }
+
+  if (selected.length === 0) {
+    if (!json) { infoMsg('Nothing selected.'); console.log(); }
+    else process.stdout.write(JSON.stringify({ ok: true, restored: [] }, null, 2) + '\n');
+    return;
+  }
+
+  const restored = [];
+  for (const r of selected) {
+    const res = restoreBackup(r.original, r.backup, { dryRun });
+    restored.push({ ...res, ts: r.ts });
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ ok: true, dryRun, restored }, null, 2) + '\n');
+    return;
+  }
+
+  console.log();
+  for (const r of restored) {
+    if (dryRun) {
+      infoMsg(`Would restore ${displayPath(r.original, home)} ← ${path.basename(r.backup)}`);
+    } else {
+      successMsg(`Restored ${displayPath(r.original, home)} ← ${path.basename(r.backup)}`);
+      if (r.savedCurrentTo) {
+        console.log(`    ${theme.dim(`(previous version saved to ${path.basename(r.savedCurrentTo)})`)}`);
+      }
+    }
+  }
+  console.log();
+  if (dryRun) warnMsg('Dry run — no files were changed.');
+  console.log();
+}

package/src/runtime.js

@@ -0,0 +1,40 @@
+import { normalizeAgentIds } from './detect.js';
+// Runtime options + non-interactive helpers.
+// Centralizes how we decide whether to prompt or use flag-provided values.
+
+export function normalizeOptions(opts = {}) {
+  const ci = process.env.CI === 'true' || process.env.CI === '1';
+  const dryRun = !!opts.dryRun || process.env.DXAI_DRY_RUN === '1';
+  const json = !!opts.json;
+  // --yes implies non-interactive. CI=true also implies non-interactive (and json output).
+  const yes = !!opts.yes || ci;
+  const nonInteractive = yes;
+  return {
+    yes,
+    ci,
+    dryRun,
+    json: json || ci,
+    nonInteractive,
+    // --no-update sets opts.update === false (commander negation).
+    update: opts.update !== false,
+    agents: opts.agents ? normalizeAgentIds(opts.agents) : opts.agents,
+    mcp: opts.mcp,
+    skills: opts.skills,
+    tools: opts.tools,
+    features: opts.features,
+    stack: opts.stack,
+  };
+}
+
+// Validate that user-supplied IDs exist in the registry. Returns { valid, invalid }.
+export function partitionByKnown(ids, knownIds) {
+  if (!ids || ids.length === 0) return { valid: [], invalid: [] };
+  const set = new Set(knownIds);
+  const valid = [];
+  const invalid = [];
+  for (const id of ids) {
+    if (set.has(id)) valid.push(id);
+    else invalid.push(id);
+  }
+  return { valid, invalid };
+}

package/src/select.js

@@ -0,0 +1,72 @@
+// Shared selection resolution for the setup flows.
+//
+// Every selectable registry (agents, MCP servers, skills, automation tools,
+// stacks, features) resolves the same way, in the same precedence order:
+//   1. explicit flag values  → validate against known IDs, throw with a hint
+//   2. non-interactive mode  → computed defaults
+//   3. interactive mode      → prompt
+// This module centralizes that flow so the wizard code declares *what* each
+// selection looks like instead of re-implementing the triplet per registry.
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { partitionByKnown } from './runtime.js';
+
+// Resolve one selection. `flag` is the raw CLI flag value (undefined = not
+// passed), `defaults`/`prompt` are lazy so they only run when actually needed.
+export async function resolveSelection({
+  flag,
+  knownIds,
+  label,
+  requireNonEmpty = false,
+  nonInteractive,
+  defaults,
+  prompt,
+}) {
+  if (flag !== undefined) {
+    const { valid, invalid } = partitionByKnown(flag, knownIds);
+    if (invalid.length > 0) {
+      throw new Error(`Unknown ${label}(s): ${invalid.join(', ')}. Known: ${knownIds.join(', ')}`);
+    }
+    if (requireNonEmpty && valid.length === 0) {
+      throw new Error(`No valid ${label}s specified.`);
+    }
+    return valid;
+  }
+  if (nonInteractive) return defaults();
+  return prompt();
+}
+
+// Build inquirer checkbox choices for a categorized catalog (MCP servers,
+// skills, automation tools): a cyan separator per category, ★ on recommended
+// entries, checked-by-default when recommended. `decorate(item)` may return
+// { status, note, checked } to append per-item annotations or override the
+// default checked state.
+export function buildCatalogChoices(categories, items, { decorate } = {}) {
+  const choices = [];
+  for (const cat of categories) {
+    const catItems = items.filter((i) => i.category === cat.id);
+    if (catItems.length === 0) continue;
+
+    const header = chalk.cyan(`\n  ${cat.label}  `) + (cat.description ? chalk.dim(cat.description) : '');
+    choices.push(new inquirer.Separator(header));
+    for (const item of catItems) {
+      const rec = item.recommended ? chalk.yellow(' ★') : '';
+      const extra = decorate ? decorate(item) || {} : {};
+      choices.push({
+        name: `${item.name}${rec}${extra.status || ''} — ${chalk.dim(item.description)}${extra.note || ''}`,
+        value: item.id,
+        checked: extra.checked ?? !!item.recommended,
+      });
+    }
+  }
+  return choices;
+}
+
+// Yes/no prompt. Returns the boolean answer.
+export async function confirm(message, { defaultValue = true } = {}) {
+  const { answer } = await inquirer.prompt([
+    { type: 'confirm', name: 'answer', message, default: defaultValue },
+  ]);
+  return answer;
+}

package/src/update.js

@@ -0,0 +1,126 @@
+import {
+  fetchRegistry, writeRegistryCache, loadRegistry,
+  diffRegistry, registryBaseFor,
+} from './registry/loader.js';
+import { validateRegistryPayload } from './registry/validate.js';
+import { resolveEntries } from './registry/mcp-registry.js';
+import {
+  printBanner, sectionHeader, successMsg, warnMsg, errorMsg, infoMsg, theme,
+} from './branding.js';
+
+const REGISTRY_FILES = [
+  { name: 'mcp-servers', listKey: 'servers' },
+  { name: 'skills', listKey: 'skills' },
+  { name: 'automation-tools', listKey: 'tools' },
+];
+
+// Re-resolve the registry-linked MCP servers live from the official MCP
+// Registry. The fetched snapshot was already resolved by the maintainer-side
+// sync, so this only matters for users who want the very latest; any failure
+// (offline, a bad record, a resolver problem) keeps the snapshot values.
+// Returns { data, summary } where summary is null when nothing was attempted.
+async function resolveLive(data, { timeoutMs, resolveFn }) {
+  const { entries, results } = await resolveFn(data.servers, { timeoutMs, retries: 0 });
+  if (results.length === 0) return { data, summary: null };
+  const problems = validateRegistryPayload('servers', entries);
+  const summary = {
+    resolved: results.filter((r) => r.ok).length,
+    failed: results.filter((r) => !r.ok).map((r) => ({ id: r.id, error: r.error })),
+    changed: results.filter((r) => r.ok && r.changed).map((r) => r.id),
+  };
+  if (problems.length) {
+    summary.error = `live resolution rejected: ${problems.slice(0, 3).join('; ')}`;
+    return { data, summary };
+  }
+  return { data: { ...data, servers: entries }, summary };
+}
+
+// Fetch every registry file from `base`, validate shape, write the cache, and diff
+// against the previously-resolved registry. Returns a results array (one per file);
+// a per-file fetch/validation failure is captured as { ok: false, error } rather than
+// thrown, so one bad file doesn't sink the rest. Pure of any output — callers print.
+// `resolve` (default true) re-resolves registry-linked MCP servers live after the
+// snapshot is fetched; the background auto-refresh passes false to stay cheap.
+export async function refreshRegistry({
+  base = registryBaseFor({}), timeoutMs, retries, resolve = true,
+  fetch = fetchRegistry, resolveFn = resolveEntries, writeCache = writeRegistryCache, loadPrev = loadRegistry,
+} = {}) {
+  const results = [];
+  for (const { name, listKey } of REGISTRY_FILES) {
+    const before = (() => {
+      try { return loadPrev(name); } catch { return null; }
+    })();
+    try {
+      let { url, data } = await fetch(name, base, { timeoutMs, retries });
+      // Basic shape check — must have an array under listKey.
+      if (!Array.isArray(data?.[listKey])) {
+        throw new Error(`Registry payload missing "${listKey}" array`);
+      }
+      // Security: vet untrusted fields (ids, commands, repo/path) before caching,
+      // so a poisoned/redirected registry can't seed a malicious entry that later
+      // drives command execution. A bad file is rejected; bundled fallback stands.
+      const problems = validateRegistryPayload(listKey, data[listKey]);
+      if (problems.length) {
+        throw new Error(`Registry payload failed validation: ${problems.slice(0, 3).join('; ')}${problems.length > 3 ? ` (+${problems.length - 3} more)` : ''}`);
+      }
+      let live = null;
+      if (name === 'mcp-servers' && resolve) {
+        try {
+          ({ data, summary: live } = await resolveLive(data, { timeoutMs, resolveFn }));
+        } catch (err) {
+          live = { resolved: 0, failed: [], changed: [], error: err.message };
+        }
+      }
+      const cachePath = writeCache(name, data);
+      const diff = diffRegistry(before, data, listKey);
+      results.push({ name, url, cachePath, ok: true, count: data[listKey].length, ...diff, ...(live ? { live } : {}) });
+    } catch (err) {
+      results.push({ name, ok: false, error: err.message });
+    }
+  }
+  return results;
+}
+
+export async function updateCmd(opts = {}) {
+  const json = !!opts.json;
+  const base = registryBaseFor({ version: opts.registryVersion, url: opts.registryUrl });
+  if (!json) {
+    printBanner();
+    sectionHeader('Update — refreshing registry');
+    infoMsg(`Source: ${base}`);
+    console.log();
+  }
+
+  const results = await refreshRegistry({ base, resolve: opts.resolve !== false });
+
+  if (!json) {
+    for (const r of results) {
+      if (r.ok) {
+        const liveNote = r.live ? `, ${r.live.resolved} re-resolved from the MCP Registry` : '';
+        successMsg(`${r.name}: cached (${r.count} entries${liveNote}) → ${r.cachePath}`);
+        if (r.added.length) console.log(`  ${theme.label('+ added:')} ${r.added.join(', ')}`);
+        if (r.removed.length) console.log(`  ${theme.label('- removed:')} ${r.removed.join(', ')}`);
+        if (r.live?.changed.length) console.log(`  ${theme.label('~ updated live:')} ${r.live.changed.join(', ')}`);
+        if (r.live?.error) warnMsg(`${r.name}: ${r.live.error}; kept the snapshot values`);
+        for (const f of r.live?.failed || []) warnMsg(`${r.name}/${f.id}: ${f.error}; kept the snapshot values`);
+      } else {
+        errorMsg(`${r.name}: ${r.error}`);
+      }
+    }
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ ok: results.every((r) => r.ok), results }, null, 2) + '\n');
+    if (results.some((r) => !r.ok)) process.exit(1);
+    return;
+  }
+
+  console.log();
+  const failed = results.filter((r) => !r.ok);
+  if (failed.length === 0) {
+    successMsg('Registry up to date.');
+  } else {
+    warnMsg(`${failed.length} fetch(es) failed; using bundled fallback for those.`);
+  }
+  console.log();
+}