xgem-cli 2.0.0-alpha.14 → 2.0.0-alpha.16

package/lib-win/ci.js

@@ -1,40 +1,70 @@
-// xgem Windows engine ci — port of lib/ci.sh: run lint -> test -> build for
-// every configured framework before you push.
+// xgem Windows engine ci — port of lib/ci.sh: run the checks for every
+// configured framework before you push.
 
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { logInfo, logSuccess, logWarn, logError, die } = require('./logger');
+const toolchain = require('./toolchain');
 
 const STEPS = ['lint', 'test', 'build'];
 
+function runStep(label, cmd, args, results) {
+    logInfo(`Running ${label}...`);
+    const result = spawnSync(cmd, args, {
+        stdio: ['ignore', 'inherit', 'inherit'],
+        env: { ...process.env, CI: 'true' },
+        shell: cmd !== process.execPath,
+    });
+    const ok = (result.status ?? 1) === 0;
+    results.push({ line: `${ok ? 'PASS ' : 'FAIL '} ${label}`, ok });
+}
+
+async function flutterSteps(results) {
+    if (!(await toolchain.ensure('flutter'))) {
+        results.push({ line: 'SKIP  flutter (flutter not found)', ok: true });
+        return;
+    }
+    runStep('flutter analyze', 'flutter', ['analyze'], results);
+    if (fs.existsSync('test')) {
+        runStep('flutter test', 'flutter', ['test'], results);
+    } else {
+        results.push({ line: 'SKIP  flutter test (no test/ directory)', ok: true });
+    }
+}
+
 async function cmdCi(configDir) {
     if (!fs.existsSync(configDir)) die(`No ${configDir} found — run 'xgem init' or 'xgem add' first.`);
 
     const results = [];
-    let overallOk = true;
 
     for (const fw of fs.readdirSync(configDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)) {
+        if (fw === 'flutter') {
+            await flutterSteps(results);
+            continue;
+        }
+        const needed = toolchain.fwTool(fw);
+        if (needed && !(await toolchain.ensure(needed))) {
+            results.push({ line: `SKIP  ${fw} (${needed} not found)`, ok: true });
+            continue;
+        }
         for (const step of STEPS) {
             const target = path.join(configDir, fw, `${step}.mjs`);
             if (!fs.existsSync(target)) continue;
-            logInfo(`Running ${fw} ${step}...`);
-            const result = spawnSync(process.execPath, [target], { stdio: 'inherit' });
-            const ok = (result.status ?? 1) === 0;
-            results.push(`${ok ? 'PASS ' : 'FAIL '} ${fw} ${step}`);
-            if (!ok) overallOk = false;
+            runStep(`${fw} ${step}`, process.execPath, [target], results);
         }
     }
 
     if (results.length === 0) {
-        logWarn(`No lint/test/build scripts found under ${configDir} to run.`);
+        logWarn(`No checks found under ${configDir} to run.`);
         return;
     }
 
     console.log('');
     console.log('=== xgem ci summary ===');
-    results.forEach((r) => console.log(r));
+    results.forEach((r) => console.log(r.line));
 
+    const overallOk = results.every((r) => r.ok);
     if (overallOk) logSuccess('All checks passed.');
     else logError('Some checks failed.');
     process.exitCode = overallOk ? 0 : 1;

package/lib-win/doctor.js

@@ -1,43 +1,71 @@
-// xgem Windows engine doctor — mirrors lib/doctor.sh's general report.
+// xgem Windows engine doctor — mirrors lib/doctor.sh's toolchain report.
 // No iOS/SwiftPM engine exists here (see flutter.js) since Xcode has no
 // Windows equivalent; `doctor ios` explains that instead of pretending.
 
-const { getVersion, detectArch } = require('./utils');
-const { paint } = require('./logger');
+const os = require('node:os');
+const { detectArch } = require('./utils');
+const { paint, logInfo } = require('./logger');
+const toolchain = require('./toolchain');
 
-function printGeneral() {
+const TOOLS = ['git', 'flutter', 'dart', 'node', 'python', 'go', 'cargo', 'docker', 'gh', 'fvm'];
+
+const pretty = (p) => (p.startsWith(os.homedir()) ? `~${p.slice(os.homedir().length)}` : p);
+
+async function printGeneral() {
     console.log(paint('cyan', '=== xgem doctor (Windows) ==='));
-    console.log(`OS:              win32`);
-    console.log(`Arch:            ${detectArch()}`);
-    console.log(`git:             ${getVersion('git') || 'not found'}`);
-    console.log(`flutter:         ${getVersion('flutter') || 'not found'}`);
-    console.log(`dart:            ${getVersion('dart') || 'not found'}`);
-    console.log(`node:            ${getVersion('node') || 'not found'}`);
-    console.log(`python:          ${getVersion('python') || getVersion('python3') || 'not found'}`);
-    console.log(`go:              ${getVersion('go', ['version']) || 'not found'}`);
-    console.log(`cargo:           ${getVersion('cargo') || 'not found'}`);
-    console.log(`docker:          ${getVersion('docker') || 'not found'}`);
+    console.log(`OS:   win32   Arch: ${detectArch()}\n`);
+
+    const noNetwork = process.env.XGEM_NO_NETWORK === '1';
+    if (!noNetwork) {
+        logInfo('Checking installed tools and the latest available versions...');
+        await Promise.all(TOOLS.filter((t) => toolchain.resolve(t)).map((t) => toolchain.latest(t)));
+    }
+
+    console.log(paint('cyan', 'Toolchains'));
+    for (const t of TOOLS) {
+        const found = toolchain.resolve(t);
+        if (!found) {
+            console.log(`  ${t.padEnd(9)} ${'not found'.padEnd(11)} download: ${toolchain.url(t)}`);
+            const recipe = toolchain.installCmd(t);
+            if (recipe) console.log(`            install:  ${recipe}   (or run: xgem update ${t})`);
+            continue;
+        }
+        const version = toolchain.versionOf(t, found);
+        const shown = found.manager === 'other' ? '' : ` (${found.manager})`;
+        console.log(`  ${t.padEnd(9)} ${(version || 'unknown').padEnd(11)} ${pretty(found.path)}${shown}`);
+        if (!found.onPath && t !== 'dart') {
+            console.log(`            ! not on PATH: found via ${found.manager}, so plain scripts and CI won't see it (xgem resolves it for its own commands)`);
+        }
+        const newer = await toolchain.latest(t, true);
+        if (version && newer && toolchain.verLt(version, newer)) {
+            console.log(`            ^ update available: ${version} -> ${newer}   (run: xgem update ${t})`);
+        }
+        const pinned = t === 'dart' ? '' : toolchain.pin(t);
+        if (pinned && version && /^\d/.test(pinned) && !version.startsWith(pinned)) {
+            console.log(`            ! this project pins ${t} ${pinned} but the active one is ${version}`);
+        }
+    }
 }
 
 function printIos() {
     console.log(paint('cyan', '=== xgem doctor ios (Windows) ==='));
     console.log(paint('yellow', 'iOS/macOS builds are not available on Windows — Xcode has no Windows equivalent.'));
     console.log('Use WSL2 with a Mac, or a real Mac, for Flutter iOS builds.');
-    const flutterVersion = getVersion('flutter');
-    if (flutterVersion) {
-        console.log(`\nflutter is installed here (${flutterVersion}) and can still build Android/Windows targets:`);
+    const found = toolchain.resolve('flutter');
+    if (found) {
+        console.log(`\nflutter is installed here (${toolchain.versionOf('flutter', found)}) and can still build Android/Windows targets:`);
         console.log('  xgem run flutter build   (choose APK or Windows)');
     }
 }
 
-function cmdDoctor(target) {
+async function cmdDoctor(target) {
     if (target === 'ios') {
         printIos();
     } else if (!target) {
-        printGeneral();
+        await printGeneral();
     } else {
         const { die } = require('./logger');
-        die(`Unknown doctor target '${target}'. Usage: xgem doctor [ios]`);
+        die(`Unknown doctor target '${target}'. Usage: xgem doctor [ios] [--no-network]`);
     }
 }
 

package/lib-win/flutter.js

@@ -8,14 +8,15 @@
 const fs = require('node:fs');
 const { spawnSync } = require('node:child_process');
 const { logInfo, logSuccess, logError, die } = require('./logger');
-const { prompt, requireCmd } = require('./utils');
+const { prompt } = require('./utils');
+const toolchain = require('./toolchain');
 
 function flutter(args) {
     return spawnSync('flutter', args, { stdio: 'inherit' });
 }
 
 async function cmdHardClean() {
-    requireCmd('flutter', 'Install Flutter: https://docs.flutter.dev/get-started/install/windows');
+    if (!(await toolchain.ensure('flutter'))) die('Flutter is required for this command.');
     logInfo('Cleaning Flutter project...');
     fs.rmSync('pubspec.lock', { force: true });
     flutter(['clean']);
@@ -26,7 +27,7 @@ async function cmdHardClean() {
 }
 
 async function cmdBuildRunner() {
-    requireCmd('flutter', 'Install Flutter: https://docs.flutter.dev/get-started/install/windows');
+    if (!(await toolchain.ensure('flutter'))) die('Flutter is required for this command.');
     logInfo('Running Flutter Build Runner...');
     const verboseChoice = ((await prompt('Run in verbose mode? (Y/n)')) || 'Y').toLowerCase();
     const args = ['pub', 'run', 'build_runner', 'build', '--delete-conflicting-outputs'];
@@ -43,7 +44,7 @@ function pubspecVersion() {
 }
 
 async function cmdBuild() {
-    requireCmd('flutter', 'Install Flutter: https://docs.flutter.dev/get-started/install/windows');
+    if (!(await toolchain.ensure('flutter'))) die('Flutter is required for this command.');
     console.log('--- Flutter Build Orchestrator (Windows) ---');
 
     let currentName = '';

package/lib-win/git.js

@@ -57,6 +57,24 @@ function baseBranch(remote) {
     return '';
 }
 
+async function resolveConflictsHelp() {
+    const files = gitCapture(['diff', '--name-only', '--diff-filter=U']).split(/\r?\n/).filter(Boolean);
+    if (files.length) {
+        logWarn('Files with conflicts:');
+        files.forEach((f) => console.log(`  - ${f}`));
+    }
+    logWarn('Resolve them, then run: git add <files> && git rebase --continue   (or give up with: git rebase --abort)');
+
+    const openEditor = (await prompt('Do you want to open VS Code to resolve this now? (y/n)')).toLowerCase();
+    if (openEditor !== 'y') return;
+
+    if (hasCmd('code')) {
+        spawnSync('code', ['.'], { stdio: 'inherit', shell: true });
+    } else {
+        logWarn("VS Code's 'code' command isn't on your PATH. Reinstall VS Code with 'Add to PATH' enabled, or open the files above manually.");
+    }
+}
+
 async function cmdCmt(commitMsg) {
     if (!commitMsg) die('Missing commit message!');
 
@@ -131,7 +149,7 @@ async function cmdCmt(commitMsg) {
         const inConflict = fs.existsSync(path.join(gitDir, 'rebase-merge')) || fs.existsSync(path.join(gitDir, 'rebase-apply'));
         if (inConflict) {
             logError('MERGE CONFLICT DETECTED!');
-            logWarn('Execution paused. Resolve conflicts to proceed.');
+            await resolveConflictsHelp();
         } else {
             logError(`Could not sync with '${remoteName}' — this looks like a connection problem, not a merge conflict (see the git error above).`);
             logWarn(`Your commit is safe locally. Re-run 'xgem git cmt' once connectivity is restored, or push manually: git push ${remoteName} ${currentBranch}`);
@@ -369,9 +387,7 @@ async function cmdSync() {
     const inConflict = fs.existsSync(path.join(gitDir, 'rebase-merge')) || fs.existsSync(path.join(gitDir, 'rebase-apply'));
     if (inConflict) {
         logError('MERGE CONFLICT DETECTED!');
-        logWarn("Execution paused. Resolve conflicts, then 'git rebase --continue'.");
-        const openEditor = (await prompt('Do you want to open VS Code to resolve this now? (y/n)')).toLowerCase();
-        if (openEditor === 'y') spawnSync('code', ['.'], { stdio: 'inherit' });
+        await resolveConflictsHelp();
     } else {
         logError('Rebase failed — this looks like a connection problem, not a merge conflict (see the git error above).');
     }

package/lib-win/toolchain.js

@@ -0,0 +1,284 @@
+// xgem Windows engine toolchain layer — port of lib/toolchain.sh: finds
+// tools where version managers keep them, offers to install missing ones,
+// and reports/applies updates. Best-effort: not runtime-tested on Windows.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const https = require('node:https');
+const { spawnSync } = require('node:child_process');
+const { logInfo, logSuccess, logWarn, logError } = require('./logger');
+
+const CACHE_DIR = process.env.XGEM_CACHE_DIR || path.join(os.homedir(), '.xgem', 'cache');
+const HOME = os.homedir();
+const EXTS = ['.exe', '.cmd', '.bat', ''];
+
+const CANON = { npm: 'node', npx: 'node', corepack: 'node', pip: 'python', pip3: 'python', python3: 'python', rustc: 'cargo', rustup: 'cargo' };
+const KNOWN = ['flutter', 'dart', 'node', 'python', 'go', 'cargo', 'docker', 'git', 'gh', 'fvm'];
+const DISPLAY = { flutter: 'Flutter SDK', dart: 'Dart SDK', node: 'Node.js', python: 'Python 3', go: 'Go', cargo: 'Rust (cargo)', docker: 'Docker', git: 'Git', gh: 'GitHub CLI', fvm: 'FVM (Flutter Version Management)' };
+const URLS = {
+    flutter: 'https://docs.flutter.dev/get-started/install/windows',
+    dart: 'https://docs.flutter.dev/get-started/install/windows',
+    node: 'https://nodejs.org/en/download',
+    python: 'https://www.python.org/downloads/windows/',
+    go: 'https://go.dev/dl/',
+    cargo: 'https://www.rust-lang.org/tools/install',
+    docker: 'https://www.docker.com/products/docker-desktop/',
+    git: 'https://git-scm.com/downloads/win',
+    gh: 'https://cli.github.com',
+    fvm: 'https://fvm.app/documentation/getting-started/installation',
+};
+const WINGET_IDS = { node: 'OpenJS.NodeJS.LTS', python: 'Python.Python.3.13', go: 'GoLang.Go', docker: 'Docker.DockerDesktop', git: 'Git.Git', gh: 'GitHub.cli', cargo: 'Rustlang.Rustup' };
+const FW_TOOL = { flutter: 'flutter', node: 'node', react: 'node', vue: 'node', angular: 'node', next: 'node', python: 'python', go: 'go', rust: 'cargo' };
+
+const canon = (t) => CANON[t] || t;
+const isKnown = (t) => KNOWN.includes(canon(t));
+const display = (t) => DISPLAY[t] || t;
+const url = (t) => URLS[t] || '';
+const fwTool = (fw) => FW_TOOL[fw] || '';
+
+function findUp(rel) {
+    let dir = process.cwd();
+    for (;;) {
+        if (dir === HOME && process.cwd() !== HOME) return null;
+        const candidate = path.join(dir, rel);
+        if (fs.existsSync(candidate)) return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+function readJson(file) {
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function pin(tool) {
+    let v = '';
+    if (tool === 'flutter' || tool === 'dart') {
+        const rc = findUp('.fvmrc');
+        const cfg = findUp(path.join('.fvm', 'fvm_config.json'));
+        if (rc) v = (readJson(rc) || {}).flutter || '';
+        else if (cfg) v = (readJson(cfg) || {}).flutterSdkVersion || '';
+    } else if (tool === 'node') {
+        const f = findUp('.nvmrc');
+        if (f) v = fs.readFileSync(f, 'utf8').trim().replace(/^v/, '');
+    }
+    return v;
+}
+
+function listDirs(dir) {
+    try { return fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name); } catch { return []; }
+}
+
+function newest(names) {
+    return [...names].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).pop();
+}
+
+function fvmRoots() {
+    return [process.env.FVM_CACHE_PATH, process.env.FVM_HOME, path.join(process.env.LOCALAPPDATA || '', 'fvm'), path.join(HOME, 'fvm'), path.join(HOME, '.fvm')].filter(Boolean);
+}
+
+function candidates(tool) {
+    const out = [];
+    const add = (dir, manager) => out.push({ dir, manager });
+    const pf = process.env.ProgramFiles || 'C:\\Program Files';
+    const local = process.env.LOCALAPPDATA || path.join(HOME, 'AppData', 'Local');
+
+    if (tool === 'flutter' || tool === 'dart') {
+        const proj = findUp(path.join('.fvm', 'flutter_sdk'));
+        if (proj) add(path.join(proj, 'bin'), 'fvm');
+        const p = pin('flutter');
+        for (const root of fvmRoots()) if (p) add(path.join(root, 'versions', p, 'bin'), 'fvm');
+        add(path.join(HOME, '.fvm', 'flutter_sdk', 'bin'), 'fvm');
+        for (const root of fvmRoots()) add(path.join(root, 'default', 'bin'), 'fvm');
+        for (const root of fvmRoots()) {
+            const v = newest(listDirs(path.join(root, 'versions')));
+            if (v) add(path.join(root, 'versions', v, 'bin'), 'fvm');
+        }
+        add('C:\\src\\flutter\\bin', 'other');
+        add(path.join(HOME, 'development', 'flutter', 'bin'), 'other');
+    } else if (tool === 'node') {
+        const nvmHome = process.env.NVM_HOME;
+        if (nvmHome) {
+            const p = pin('node');
+            const names = listDirs(nvmHome).filter((n) => /^v?\d/.test(n));
+            const match = p && /^\d/.test(p) ? names.filter((n) => n.replace(/^v/, '').startsWith(p)) : [];
+            const pick = newest(match.length ? match : names);
+            if (pick) add(path.join(nvmHome, pick), 'nvm');
+        }
+        if (process.env.NVM_SYMLINK) add(process.env.NVM_SYMLINK, 'nvm');
+        add(path.join(local, 'Volta', 'bin'), 'volta');
+        add(path.join(pf, 'nodejs'), 'other');
+    } else if (tool === 'python') {
+        const base = path.join(local, 'Programs', 'Python');
+        const v = newest(listDirs(base));
+        if (v) add(path.join(base, v), 'other');
+    } else if (tool === 'go') {
+        add(path.join(pf, 'Go', 'bin'), 'other');
+    } else if (tool === 'cargo') {
+        add(path.join(HOME, '.cargo', 'bin'), 'rustup');
+    } else if (tool === 'docker') {
+        add(path.join(pf, 'Docker', 'Docker', 'resources', 'bin'), 'other');
+    } else if (tool === 'git') {
+        add(path.join(pf, 'Git', 'cmd'), 'other');
+    } else if (tool === 'gh') {
+        add(path.join(pf, 'GitHub CLI'), 'other');
+    }
+    return out;
+}
+
+function managerOf(p) {
+    const s = p.replace(/\\/g, '/').toLowerCase();
+    if (s.includes('/fvm/') || s.includes('/.fvm/')) return 'fvm';
+    if (s.includes('/nvm')) return 'nvm';
+    if (s.includes('/.cargo/')) return 'rustup';
+    if (s.includes('/volta/')) return 'volta';
+    if (s.includes('/winget/') || s.includes('/scoop/')) return 'package manager';
+    return 'other';
+}
+
+function whereFirst(cmd) {
+    const r = spawnSync('where', [cmd], { encoding: 'utf8', shell: false });
+    if (r.status !== 0) return '';
+    return (r.stdout || '').split(/\r?\n/).find(Boolean) || '';
+}
+
+// resolve(cmd) -> { path, dir, manager, onPath } or null
+function resolve(cmd) {
+    const c = canon(cmd);
+    const onPath = whereFirst(cmd);
+    if (onPath) return { path: onPath, dir: path.dirname(onPath), manager: managerOf(onPath), onPath: true };
+    for (const { dir, manager } of candidates(c)) {
+        for (const ext of EXTS) {
+            const full = path.join(dir, cmd + ext);
+            if (fs.existsSync(full) && fs.statSync(full).isFile()) return { path: full, dir, manager, onPath: false };
+        }
+    }
+    return null;
+}
+
+function activate(found) {
+    if (!found || found.onPath) return;
+    process.env.PATH = `${found.dir}${path.delimiter}${process.env.PATH || ''}`;
+}
+
+function versionOf(t, found) {
+    if (t === 'flutter') {
+        const sdk = path.join(path.dirname(found.path), '..');
+        const j = readJson(path.join(sdk, 'bin', 'cache', 'flutter.version.json'));
+        if (j && j.frameworkVersion) return j.frameworkVersion;
+    }
+    const args = t === 'go' ? ['version'] : ['--version'];
+    const r = spawnSync(found.path, args, { encoding: 'utf8', shell: /\.(cmd|bat)$/i.test(found.path) });
+    const m = ((r.stdout || '') + (r.stderr || '')).split(/\r?\n/).slice(0, 3).join(' ').match(/\d+(\.\d+)+/);
+    return m ? m[0] : '';
+}
+
+function verLt(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] || 0;
+        const y = pb[i] || 0;
+        if (x !== y) return x < y;
+    }
+    return false;
+}
+
+function fetchText(u) {
+    return new Promise((resolveP) => {
+        const req = https.get(u, { timeout: 8000 }, (res) => {
+            if (res.statusCode !== 200) { res.resume(); resolveP(''); return; }
+            let data = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => { data += c; });
+            res.on('end', () => resolveP(data));
+        });
+        req.on('timeout', () => { req.destroy(); resolveP(''); });
+        req.on('error', () => resolveP(''));
+    });
+}
+
+async function fetchLatest(t) {
+    if (t === 'flutter') {
+        const j = JSON.parse((await fetchText('https://storage.googleapis.com/flutter_infra_release/releases/releases_windows.json')) || 'null');
+        if (!j) return '';
+        const rel = j.releases.find((r) => r.hash === j.current_release.stable && r.channel === 'stable');
+        return rel ? rel.version : '';
+    }
+    if (t === 'node') {
+        const list = JSON.parse((await fetchText('https://nodejs.org/dist/index.json')) || 'null');
+        const lts = list && list.find((r) => r.lts);
+        return lts ? lts.version.replace(/^v/, '') : '';
+    }
+    if (t === 'go') {
+        return ((await fetchText('https://go.dev/VERSION?m=text')).split(/\r?\n/)[0] || '').replace(/^go/, '');
+    }
+    return '';
+}
+
+// latest(t) -> newest known version, cached 12h; noNetwork uses only the cache.
+async function latest(t, noNetwork = process.env.XGEM_NO_NETWORK === '1') {
+    const f = path.join(CACHE_DIR, `latest-${t}`);
+    const fresh = fs.existsSync(f) && Date.now() - fs.statSync(f).mtimeMs < 12 * 3600 * 1000;
+    if (noNetwork || fresh) return fs.existsSync(f) ? fs.readFileSync(f, 'utf8').trim() : '';
+    let v = '';
+    try { v = await fetchLatest(t); } catch { v = ''; }
+    if (v) {
+        fs.mkdirSync(CACHE_DIR, { recursive: true });
+        fs.writeFileSync(f, v);
+        return v;
+    }
+    return fs.existsSync(f) ? fs.readFileSync(f, 'utf8').trim() : '';
+}
+
+function installCmd(t) {
+    if (t === 'flutter' || t === 'dart') {
+        return resolve('fvm') ? 'fvm install stable && fvm global stable' : '';
+    }
+    if (t === 'fvm') return 'dart pub global activate fvm';
+    if (WINGET_IDS[t]) return `winget install --id ${WINGET_IDS[t]} -e`;
+    return '';
+}
+
+function updateCmd(t, latestVersion, manager) {
+    if (t === 'flutter' && manager === 'fvm') return `fvm install ${latestVersion}`;
+    if (t === 'cargo' && manager === 'rustup') return 'rustup update';
+    if (WINGET_IDS[t] && t !== 'cargo') return `winget upgrade --id ${WINGET_IDS[t]} -e`;
+    return '';
+}
+
+// ensure(t) -> true once the tool is usable, after explaining what's needed
+// and (with confirmation) installing it.
+async function ensure(tool) {
+    const { confirm } = require('./utils');
+    const t = canon(tool);
+    let found = resolve(tool);
+    if (found) { activate(found); return true; }
+
+    logWarn(`${display(t)} is required for this but wasn't found (checked PATH, version managers like fvm/nvm, and common install locations).`);
+    console.log(`  Download: ${url(t)}`);
+    const recipe = installCmd(t);
+    if (!recipe) {
+        logInfo('Install it from the link above, then re-run this command.');
+        return false;
+    }
+    if (recipe.startsWith('winget') && !whereFirst('winget')) {
+        logInfo('That install route needs winget (App Installer from the Microsoft Store) — install it first, or use the download link above.');
+        return false;
+    }
+    console.log(`  Install command: ${recipe}`);
+    if (!(await confirm(`Install ${display(t)} now?`))) {
+        logInfo("Skipped. Install it from the link above when you're ready.");
+        return false;
+    }
+    const r = spawnSync(recipe, { stdio: 'inherit', shell: true });
+    if (r.status !== 0) { logError('The install command failed (see its output above).'); return false; }
+    found = resolve(tool);
+    if (found) { activate(found); logSuccess(`${display(t)} is ready.`); return true; }
+    logWarn(`Install finished but '${tool}' still isn't reachable — you may need to open a new terminal.`);
+    return false;
+}
+
+module.exports = { canon, isKnown, display, url, fwTool, pin, resolve, activate, versionOf, verLt, latest, installCmd, updateCmd, ensure, findUp, KNOWN };

package/lib-win/update.js

@@ -0,0 +1,68 @@
+// xgem update [tool] — port of lib/update.sh.
+
+const { spawnSync } = require('node:child_process');
+const { logInfo, logSuccess, logWarn, logError, die } = require('./logger');
+const { confirm } = require('./utils');
+const toolchain = require('./toolchain');
+
+const DEFAULT_TOOLS = ['flutter', 'node', 'cargo', 'go', 'fvm', 'gh', 'git', 'docker', 'python'];
+
+async function updateOne(tool, explicit) {
+    const found = toolchain.resolve(tool);
+    if (!found) {
+        if (explicit) await toolchain.ensure(tool);
+        return;
+    }
+
+    const version = toolchain.versionOf(tool, found);
+    const newest = await toolchain.latest(tool, true);
+    if (!newest) {
+        if (explicit) logWarn(`Couldn't determine the latest ${toolchain.display(tool)} version (offline, or no version source).`);
+        return;
+    }
+    if (!version || !toolchain.verLt(version, newest)) {
+        if (explicit) logSuccess(`${toolchain.display(tool)} ${version} is up to date.`);
+        return;
+    }
+
+    console.log('');
+    logInfo(`${toolchain.display(tool)}: ${version} -> ${newest}`);
+    const cmd = toolchain.updateCmd(tool, newest, found.manager);
+    if (!cmd) {
+        console.log(`  No automated update route for this install (${found.manager}). Download: ${toolchain.url(tool)}`);
+        return;
+    }
+    console.log(`  Update command: ${cmd}`);
+    if (!(await confirm(`Update ${toolchain.display(tool)} to ${newest}?`))) return;
+    if (spawnSync(cmd, { stdio: 'inherit', shell: true }).status !== 0) {
+        logError('Update failed (see output above).');
+        return;
+    }
+    logSuccess(`${toolchain.display(tool)} update finished.`);
+
+    if (tool === 'flutter' && found.manager === 'fvm') {
+        if (await confirm(`Make Flutter ${newest} your global default (fvm global)?`)) {
+            spawnSync(`fvm global ${newest}`, { stdio: 'inherit', shell: true });
+        }
+        if ((toolchain.findUp('.fvmrc') || toolchain.findUp('.fvm')) && (await confirm(`Also pin ${newest} for the project in this directory (fvm use)?`))) {
+            spawnSync(`fvm use ${newest}`, { stdio: 'inherit', shell: true });
+        }
+    }
+}
+
+async function cmdUpdate(target) {
+    if (target) {
+        if (!toolchain.isKnown(target)) die(`Unknown tool '${target}'. Known: ${toolchain.KNOWN.join(' ')}`);
+        await updateOne(toolchain.canon(target), true);
+        return;
+    }
+    if (process.env.XGEM_NO_NETWORK !== '1') {
+        logInfo('Checking installed tools for updates...');
+        await Promise.all(DEFAULT_TOOLS.filter((t) => toolchain.resolve(t)).map((t) => toolchain.latest(t)));
+    }
+    for (const t of DEFAULT_TOOLS) await updateOne(t, false);
+    console.log('');
+    logSuccess("Update check finished. Run 'xgem doctor' for the full toolchain report.");
+}
+
+module.exports = { cmdUpdate };

package/lib-win/utils.js

@@ -12,13 +12,21 @@ function detectArch() {
 // works regardless of whether the tool itself supports --version.
 function hasCmd(name) {
     const result = spawnSync('where', [name], { stdio: 'ignore', shell: false });
-    return result.status === 0;
+    if (result.status === 0) return true;
+    const toolchain = require('./toolchain');
+    if (!toolchain.isKnown(name)) return false;
+    const found = toolchain.resolve(name);
+    if (!found) return false;
+    toolchain.activate(found);
+    return true;
 }
 
 function requireCmd(name, hint) {
     if (!hasCmd(name)) {
         const { die } = require('./logger');
-        die(hint ? `'${name}' is required but not found. ${hint}` : `'${name}' is required but not found in PATH.`);
+        const toolchain = require('./toolchain');
+        const link = toolchain.isKnown(name) ? ` Download: ${toolchain.url(toolchain.canon(name))}` : '';
+        die(hint ? `'${name}' is required but not found. ${hint}` : `'${name}' is required but not found in PATH.${link}`);
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xgem-cli",
-  "version": "2.0.0-alpha.14",
+  "version": "2.0.0-alpha.16",
   "description": "Framework-aware automation CLI: scaffolds and runs clean/build/dev scripts per project type, an environment doctor, a SwiftPM-aware iOS build engine, and a git workflow helper. Runs natively on macOS, Linux, and Windows.",
   "bin": {
     "xgem": "bin/xgem.js"