wize-dev-kit 0.16.0 → 0.17.0

package/tools/installer/document-project/state.js

@@ -0,0 +1,110 @@
+// State file management for `wize-dev-kit document-project`.
+//
+// Tracks scan progress so long-running deep/exhaustive scans can resume.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const WORKFLOW_VERSION = '0.3.1';
+const STATE_FILE = 'project-scan-report.json';
+const ARCHIVE_DIR = '_archive';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, '.wize', 'knowledge', 'document-project', STATE_FILE);
+}
+
+function archivePath(projectRoot, timestamp) {
+  const dir = path.join(projectRoot, '.wize', 'knowledge', 'document-project', ARCHIVE_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const safe = timestamp.replace(/[:.]/g, '-');
+  return path.join(dir, `project-scan-report-${safe}.json`);
+}
+
+function initState(projectRoot, mode, scanLevel) {
+  const state = {
+    workflow_version: WORKFLOW_VERSION,
+    timestamps: { started: nowIso(), last_updated: nowIso() },
+    mode,
+    scan_level: scanLevel,
+    project_root: projectRoot,
+    project_knowledge: path.join(projectRoot, '.wize', 'knowledge', 'document-project'),
+    completed_steps: [],
+    current_step: 'step_1',
+    findings: {},
+    outputs_generated: [STATE_FILE],
+    resume_instructions: `Starting ${mode} (${scanLevel}) from step_1`
+  };
+  writeState(projectRoot, state);
+  return state;
+}
+
+function loadState(projectRoot) {
+  const p = statePath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const content = fs.readFileSync(p, 'utf-8');
+    const state = JSON.parse(content);
+    if (!state.workflow_version || !state.timestamps || !state.mode || !state.scan_level) {
+      return null;
+    }
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(projectRoot, state) {
+  const p = statePath(projectRoot);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  state.timestamps.last_updated = nowIso();
+  fs.writeFileSync(p, JSON.stringify(state, null, 2), 'utf-8');
+}
+
+function updateState(projectRoot, patch) {
+  const state = loadState(projectRoot) || initState(projectRoot, 'quick', 'quick');
+  for (const key of Object.keys(patch)) {
+    const val = patch[key];
+    if (Array.isArray(val) && Array.isArray(state[key])) {
+      state[key].push(...val);
+    } else if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+      state[key] = { ...(state[key] || {}), ...val };
+    } else {
+      state[key] = val;
+    }
+  }
+  writeState(projectRoot, state);
+  return state;
+}
+
+function archiveOldState(projectRoot) {
+  const p = statePath(projectRoot);
+  if (!fs.existsSync(p)) return false;
+  const content = fs.readFileSync(p, 'utf-8');
+  const archived = archivePath(projectRoot, nowIso());
+  fs.writeFileSync(archived, content, 'utf-8');
+  fs.rmSync(p);
+  return true;
+}
+
+function stateAgeDays(state) {
+  if (!state || !state.timestamps || !state.timestamps.last_updated) return null;
+  const then = Date.parse(state.timestamps.last_updated);
+  if (Number.isNaN(then)) return null;
+  return Math.floor((Date.now() - then) / (24 * 3600 * 1000));
+}
+
+module.exports = {
+  statePath,
+  initState,
+  loadState,
+  updateState,
+  archiveOldState,
+  stateAgeDays,
+  WORKFLOW_VERSION
+};

package/tools/installer/onboarding.js

@@ -1,31 +1,25 @@
 /*
  * Onboarding handoff — Wizer-driven triage after install.
  *
- * Stub: in v0.1 this just prints the first action Wizer would take.
- * In a real run this would be a workflow executed by the active IDE adapter.
+ * Returns a clean, minimal message (≤3 lines) that always ends with "→ /wize".
+ * The message adapts to brownfield detection and active profiles without
+ * turning into a wall of text.
  */
 'use strict';
 
 function compose(detection, profiles) {
-  const lines = [
-    '',
-    '╭─ Wizer ─────────────────────────────────────╮',
-    '│ Welcome back. What are we working on?       │',
-    '╰─────────────────────────────────────────────╯'
-  ];
-  if (detection.brownfield) {
-    lines.push('');
-    lines.push('I see this repo already has code. I can ask Pepper and Peggy to baseline it before we plan.');
-    lines.push('  → /wize-document-project');
+  const lines = [];
+  const profileCodes = new Set(profiles.map(p => p.code));
+
+  if (detection && detection.brownfield) {
+    lines.push('Brownfield detected — baseline ready.');
+  }
+
+  if (profileCodes.has('security-overlay')) {
+    lines.push('Security pentest available (/wize-sec-recon).');
   }
-  lines.push('');
-  lines.push('When ready, name the next step:');
-  lines.push('  → /wize-product-brief          (Pepper)');
-  lines.push('  → /wize-create-prd             (Maria Hill, if brief exists)');
-  lines.push('  → /wize-create-architecture    (Tony, if PRD exists)');
-  lines.push('  → /wize-quick-dev              (Shuri, for small fixes)');
-  if (profiles.find(p => p.code === 'web-overlay')) lines.push('  → /wize-web-scaffold           (overlay)');
-  if (profiles.find(p => p.code === 'app-overlay')) lines.push('  → /wize-app-scaffold           (overlay)');
+
+  lines.push('→ /wize');
   return lines.join('\n');
 }
 

package/tools/installer/render-shared.js

@@ -12,11 +12,51 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { walkAgents, walkWorkflows, walkSkills } = require('./validators/walk.js');
 
+// Shared block-scalar reader used by both readYamlField (agent.yaml) and
+// readFrontmatter (skill.md / workflow.md). Returns { value, nextIndex }.
+function readBlockScalar(lines, startIndex, folded) {
+  const collected = [];
+  let baseIndent = null;
+  let i = startIndex;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') { collected.push(''); continue; }
+    const indent = line.match(/^(\s*)/)[1].length;
+    if (indent === 0) break; // dedent to a sibling top-level key ends the block
+    if (baseIndent === null) baseIndent = indent;
+    collected.push(line.slice(baseIndent));
+  }
+  while (collected.length && collected[collected.length - 1] === '') collected.pop();
+  if (folded) {
+    const value = collected.reduce((acc, ln, idx) => {
+      if (idx === 0) return ln;
+      if (ln === '' || collected[idx - 1] === '') return acc + '\n' + ln;
+      return acc + ' ' + ln;
+    }, '').trim();
+    return { value, nextIndex: i };
+  }
+  return { value: collected.join('\n').trim(), nextIndex: i };
+}
+
 function readYamlField(content, field) {
-  const re = new RegExp('^' + field + ':\\s*(?:"([^"]*)"|\'([^\']*)\'|(.*?))\\s*$', 'm');
-  const m = content.match(re);
-  if (!m) return null;
-  return (m[1] || m[2] || m[3] || '').trim();
+  const lines = content.split('\n');
+  const keyRe = new RegExp('^' + field + ':\\s*(.*)$');
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    const inline = m[1].trim();
+
+    // Block scalar (| literal, > folded) with optional chomp/indent indicator.
+    const block = inline.match(/^([|>])[+-]?\d*\s*$/);
+    if (block) {
+      return readBlockScalar(lines, i + 1, block[1] === '>').value;
+    }
+
+    // Inline scalar: quoted or plain.
+    const q = inline.match(/^"([^"]*)"$/) || inline.match(/^'([^']*)'$/);
+    return (q ? q[1] : inline).trim();
+  }
+  return null;
 }
 
 function readFrontmatter(content) {
@@ -25,9 +65,25 @@ function readFrontmatter(content) {
   if (end === -1) return {};
   const lines = content.slice(3, end).split('\n');
   const out = {};
-  for (const line of lines) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
     const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
-    if (m) out[m[1]] = m[2].replace(/^"|"$/g, '').replace(/^'|'$/g, '');
+    if (!m) continue;
+    const key = m[1];
+    const inline = m[2].trim();
+
+    // Block scalar (| literal, > folded) with optional chomp/indent indicator.
+    const block = inline.match(/^([|>])[+-]?\d*\s*$/);
+    if (block) {
+      const result = readBlockScalar(lines, i + 1, block[1] === '>');
+      out[key] = result.value;
+      i = result.nextIndex - 1; // -1 because the for loop will increment
+      continue;
+    }
+
+    // Inline scalar: quoted or plain.
+    const q = inline.match(/^"([^"]*)"$/) || inline.match(/^'([^']*)'$/);
+    out[key] = (q ? q[1] : inline).trim();
   }
   return out;
 }
@@ -53,6 +109,42 @@ function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
 
+// Companion files (steps/, templates/, data/, *.csv, *-template.md,
+// customize.toml, research.template.md, etc.) that micro-file workflows
+// reference from their body. We must copy these alongside the SKILL.md so
+// the IDE can resolve paths like "./steps/step-01-init.md" at runtime.
+const SKIP_NAMES = new Set(['.DS_Store', 'Thumbs.db', 'node_modules', '.git']);
+const SKIP_FILES = new Set([
+  'skill.md', 'workflow.md', 'agent.yaml', 'persona.md',
+  'package.json', 'package-lock.json'
+]);
+
+function isCompanion(entry) {
+  if (entry.name.startsWith('.')) return false;
+  if (SKIP_NAMES.has(entry.name)) return false;
+  if (SKIP_FILES.has(entry.name)) return false;
+  if (entry.name.endsWith('.test.js')) return false;
+  return true;
+}
+
+function copyCompanionFiles(srcDir, destDir, written, relPrefix = '') {
+  if (!srcDir || !fs.existsSync(srcDir)) return;
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    if (!isCompanion(entry)) continue;
+    const s = path.join(srcDir, entry.name);
+    const d = path.join(destDir, entry.name);
+    const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      ensureDir(d);
+      copyCompanionFiles(s, d, written, rel);
+    } else if (entry.isFile()) {
+      ensureDir(path.dirname(d));
+      fs.copyFileSync(s, d);
+      written.push(rel);
+    }
+  }
+}
+
 // Walks the kit and returns a flat array of "assets" the adapters can render.
 // Each asset has: { kind: 'agent'|'workflow'|'skill', code, name, title, description, body, overlay }
 function collectAssets(kitRoot, { profiles = ['core'] } = {}) {
@@ -69,7 +161,7 @@ function collectAssets(kitRoot, { profiles = ['core'] } = {}) {
     if (!code || !name) continue;
     const personaPath = path.join(dir, 'persona.md');
     const persona = fs.existsSync(personaPath) ? fs.readFileSync(personaPath, 'utf-8') : '';
-    out.push({ kind: 'agent', code, name, title, description, body: persona || description, overlay: null });
+    out.push({ kind: 'agent', code, name, title, description, body: persona || description, overlay: null, srcDir: dir });
   }
 
   for (const wfPath of walkWorkflows(kitRoot)) {
@@ -78,14 +170,18 @@ function collectAssets(kitRoot, { profiles = ['core'] } = {}) {
     if (!fm.code) continue;
     if (fm.overlay === 'web' && !profSet.has('web-overlay')) continue;
     if (fm.overlay === 'app' && !profSet.has('app-overlay')) continue;
+    if (fm.overlay === 'security' && !profSet.has('security-overlay')) continue;
     out.push({
       kind: 'workflow',
       code: fm.code,
       name: fm.name || fm.code,
       title: fm.phase || fm.gate || '',
-      description: `${fm.phase || fm.gate || 'workflow'}: ${fm.name || fm.code}`,
+      description: fm.description || `${fm.phase || fm.gate || 'workflow'}: ${fm.name || fm.code}`,
       body: bodyAfterFrontmatter(content),
-      overlay: fm.overlay || null
+      overlay: fm.overlay || null,
+      owner: fm.owner || null,
+      subtask: fm.subtask === 'true',
+      srcDir: path.dirname(wfPath)
     });
   }
 
@@ -93,14 +189,20 @@ function collectAssets(kitRoot, { profiles = ['core'] } = {}) {
     const content = fs.readFileSync(skPath, 'utf-8');
     const fm = readFrontmatter(content);
     if (!fm.code) continue;
+    if (fm.overlay === 'web' && !profSet.has('web-overlay')) continue;
+    if (fm.overlay === 'app' && !profSet.has('app-overlay')) continue;
+    if (fm.overlay === 'security' && !profSet.has('security-overlay')) continue;
     out.push({
       kind: 'skill',
       code: fm.code,
       name: fm.name || fm.code,
       title: fm.module || '',
-      description: fm.module ? `${fm.module} skill: ${fm.name || fm.code}` : (fm.name || fm.code),
+      description: fm.description || (fm.module ? `${fm.module} skill: ${fm.name || fm.code}` : (fm.name || fm.code)),
       body: bodyAfterFrontmatter(content),
-      overlay: null
+      overlay: fm.overlay || null,
+      owner: fm.owner || null,
+      subtask: fm.subtask === 'true',
+      srcDir: path.dirname(skPath)
     });
   }
 
@@ -140,6 +242,10 @@ function renderAnthropicSkills(kitRoot, targetDir, opts = {}) {
       ensureDir(skillDir);
       fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
       written.push(`${a.code}/SKILL.md`);
+      // Copy companion files (steps/, templates/, data/, *.csv, customize.toml,
+      // *-template.md, research.template.md, etc.) so micro-file workflows can
+      // resolve relative paths from inside the SKILL body.
+      copyCompanionFiles(a.srcDir, skillDir, written, a.code);
     }
   }
   return { written, skipped: [] };
@@ -147,9 +253,30 @@ function renderAnthropicSkills(kitRoot, targetDir, opts = {}) {
 
 // Convenience emitter for a root-level AGENTS.md — read by Codex, Cursor,
 // Windsurf and Antigravity as a baseline pointer to the kit's deeper docs.
+// Canonical roster order so AGENTS.md is deterministic regardless of the
+// filesystem walk order. Codes not listed sort last, alphabetically.
+const AGENT_ORDER = [
+  'wize-orchestrator',
+  'wize-agent-analyst',
+  'wize-agent-tech-writer',
+  'wize-agent-pm',
+  'wize-agent-ux-designer',
+  'wize-agent-solution-strategist',
+  'wize-agent-architect',
+  'wize-agent-test-architect',
+  'wize-agent-dev',
+  'wize-sec-red-teamer'
+];
+
 function renderAgentsMd(kitRoot, projectRoot, opts = {}) {
   const assets = collectAssets(kitRoot, opts);
-  const agents = assets.filter(a => a.kind === 'agent');
+  const rank = (code) => {
+    const i = AGENT_ORDER.indexOf(code);
+    return i === -1 ? AGENT_ORDER.length : i;
+  };
+  const agents = assets
+    .filter(a => a.kind === 'agent')
+    .sort((a, b) => rank(a.code) - rank(b.code) || a.code.localeCompare(b.code));
   const file = path.join(projectRoot, 'AGENTS.md');
   if (fs.existsSync(file) && !opts.overwrite) {
     return { written: [], skipped: ['AGENTS.md (already present; not overwritten)'] };
@@ -159,15 +286,31 @@ function renderAgentsMd(kitRoot, projectRoot, opts = {}) {
     '',
     'This repo is wired with the [`wize-dev-kit`](https://www.npmjs.com/package/wize-dev-kit).',
     'Detailed artifacts live under `.wize/`. The agents below are activated through your AI IDE',
-    'using slash commands (Claude Code, Codex, Cursor, Windsurf, Antigravity all read this file).',
+    'using slash commands (Claude Code, Codex, Cursor, Windsurf, Antigravity, Hermes all read this file).',
+    '',
+    '## Operating context',
+    '',
+    'Treat `.wize/`, this `AGENTS.md`, and the installed `wize-*` skills as your operating',
+    'instructions and persistent memory — not background reading. Read project state before',
+    'acting; write what you change back into `.wize/` so the next session inherits it.',
+    '',
+    'Before editing, classify the demand via `/wize` (or `/wize-help`): **Quick Dev** (small, predictable,',
+    'trivially scoped, no new feature / architecture / UX / security) or **Full Lifecycle**. Never pick',
+    'Quick Dev just to skip artifacts.',
+    '',
+    'When a skill fans out to subagents, match the model tier to the task: a lightweight tier',
+    'for mechanical work (reads, greps, formatting, short summaries), the standard tier for',
+    'implementation and review, a high-capability tier only for architecture, critical',
+    'decisions, or final adversarial review.',
     '',
     '## Roster',
     ''
   ];
   for (const a of agents) {
-    lines.push(`- **${a.name}** (\`${a.code}\`) — ${a.title}. ${clipOneLine(a.description, 180)}`);
+    const optIn = a.code.startsWith('wize-sec-') ? ' _(security-overlay, opt-in)_' : '';
+    lines.push(`- **${a.name}** (\`${a.code}\`)${optIn} — ${a.title}. ${clipOneLine(a.description, 180)}`);
   }
-  lines.push('', '## Where to start', '', 'Activate the orchestrator: `wize-orchestrator` (Wizer). Then ask `/wize-help`.', '');
+  lines.push('', '## Where to start', '', 'Activate the orchestrator: `/wize` (or `/wize-help`). Wizer will guide you.', '');
 
   if (opts.dryRun) return { written: ['[dry-run] AGENTS.md'], skipped: [] };
   fs.writeFileSync(file, lines.join('\n'), 'utf-8');
@@ -178,6 +321,7 @@ module.exports = {
   collectAssets,
   renderAnthropicSkills,
   renderAgentsMd,
+  copyCompanionFiles,
   // Re-exports for adapter authors who need to roll their own format:
   readFrontmatter,
   bodyAfterFrontmatter,

package/tools/installer/setup-helpers.js

@@ -24,6 +24,8 @@ const GITIGNORE_BODY = [
   '.agent/skills/wize-*',
   '.agents/skills/wize-*',
   '.kimi/skills/wize-*',
+  '.hermes/skills/wize-*',
+  '.kiro/skills/wize-*',
   '.cursor/rules/wize-*.mdc',
   '.windsurf/rules/wize-*.md',
   '.continue/prompts/wize-*.prompt',

package/tools/installer/validators/run-all.js

@@ -13,7 +13,7 @@ const { walkAgents, walkWorkflows, walkSkills } = require('./walk.js');
 function checkAgent(file) {
   const content = fs.readFileSync(file, 'utf-8');
   const errs = [];
-  if (!/^code:\s+wize-/m.test(content)) errs.push('missing or invalid "code:" prefix');
+  if (!/^code:\s+wize(-|$)/m.test(content)) errs.push('missing or invalid "code:" prefix');
   if (!/^name:/m.test(content))         errs.push('missing "name:"');
   if (!/^title:/m.test(content))        errs.push('missing "title:"');
   if (!/^description:/m.test(content))  errs.push('missing "description:"');
@@ -24,9 +24,10 @@ function checkWorkflow(file) {
   const content = fs.readFileSync(file, 'utf-8');
   const errs = [];
   if (!/^---\s*$/m.test(content))    errs.push('missing YAML frontmatter');
-  if (!/^code:\s+wize-/m.test(content)) errs.push('missing or invalid "code:" prefix');
+  if (!/^code:\s+wize(-|$)/m.test(content)) errs.push('missing or invalid "code:" prefix');
   if (!/^name:/m.test(content))      errs.push('missing "name:"');
   if (!/^owner:/m.test(content) && !/^module:/m.test(content)) errs.push('missing "owner:" or "module:"');
+  if (!/^description:/m.test(content)) errs.push('missing "description:"');
   return errs;
 }
 

package/tools/installer/version-check.js

@@ -0,0 +1,117 @@
+// Best-effort, non-blocking npm registry check for "is there a newer wize-dev-kit
+// version than the one I'm running?". Designed so the CLI can call it from
+// `list` / `agent list` / `help` and print a single hint at the top, without
+// ever blocking the command if the network is slow, the user is offline, or
+// the registry is misbehaving.
+//
+// Strategy:
+//   - Cache the registry answer in $XDG_CACHE_HOME (or ~/.cache) for 1 hour.
+//   - Resolve via fetch with a 1.5s timeout. Failure is silent.
+//   - Compare with the kit version baked into the running CLI.
+//   - Expose a `printUpdateHintIfAny(currentVersion)` helper for the CLI.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CACHE_TTL_MS = 60 * 60 * 1000;       // 1h
+const NETWORK_TIMEOUT_MS = 1500;
+
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'wize-dev-kit', 'registry-version.json');
+}
+
+function readCache() {
+  const f = cacheFile();
+  try {
+    const stat = fs.statSync(f);
+    if (Date.now() - stat.mtimeMs > CACHE_TTL_MS) return null;
+    return JSON.parse(fs.readFileSync(f, 'utf-8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeCache(payload) {
+  const f = cacheFile();
+  try {
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(payload), 'utf-8');
+  } catch (_) { /* cache failure is harmless */ }
+}
+
+async function fetchLatestFromRegistry() {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    const res = await fetch('https://registry.npmjs.org/wize-dev-kit', {
+      signal: ctrl.signal,
+      headers: { Accept: 'application/vnd.npm.install-v1+json' }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const latest = body && body['dist-tags'] && body['dist-tags'].latest;
+    return typeof latest === 'string' ? latest : null;
+  } catch (_) {
+    return null;   // any error → silent fallback
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Returns the registry-latest version, hitting the cache first. Never throws,
+// never blocks meaningfully (network call is capped + abortable).
+async function getLatestVersion({ skipCache = false } = {}) {
+  if (!skipCache) {
+    const c = readCache();
+    if (c && c.version) return c.version;
+  }
+  const fresh = await fetchLatestFromRegistry();
+  if (fresh) writeCache({ version: fresh, fetched_at: Date.now() });
+  return fresh;
+}
+
+function semverGreater(a, b) {
+  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+// Prints a one-line hint when a newer version is available. Silent otherwise.
+// Designed to be awaited near the top of a CLI command; if anything is slow
+// or off, it just returns.
+async function printUpdateHintIfAny(currentVersion, { log = console.log, isTTY = process.stdout.isTTY } = {}) {
+  if (process.env.WIZE_DISABLE_UPDATE_CHECK === '1') return;
+  if (!isTTY) return;            // don't spam pipes
+  try {
+    const latest = await getLatestVersion();
+    if (!latest) return;
+    if (semverGreater(latest, currentVersion)) {
+      log('');
+      log(`  ↑ Update available: wize-dev-kit ${currentVersion} → ${latest}`);
+      log(`    Run \`npx wize-dev-kit@latest update\` in your project to refresh adapters.`);
+      log('');
+    }
+  } catch (_) {
+    /* total fallback — never block the command */
+  }
+}
+
+module.exports = {
+  CACHE_TTL_MS,
+  NETWORK_TIMEOUT_MS,
+  cacheFile,
+  readCache,
+  writeCache,
+  fetchLatestFromRegistry,
+  getLatestVersion,
+  semverGreater,
+  printUpdateHintIfAny
+};