jsql-neo 6.5.24 → 6.5.25

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Vexify
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -3,7 +3,7 @@
 > **One engine to rule them all** — a Rust-powered embedded database that speaks your language:
 > MySQL, PostgreSQL, MongoDB, Redis, SQL, TypeScript, **and the browser**.
 
-> **v6.5.24** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.25** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
 
 ![Engines](https://img.shields.io/badge/engines-Native%20%7C%20WASM%20%7C%20Pure%20JS-7ee787)
 ![MySQL](https://img.shields.io/badge/protocol-MySQL%20compatible-1f6feb)
@@ -20,8 +20,8 @@
 
 ![JSQL-NEO terminal demo](doc/demo.gif)
 
-A real `jsql tui` session: joins, NULL semantics, exact 64-bit integers, and
-savepoint rollback.
+A real `jsql tui` session (v6.5.25): 64-bit integer precision, joins, NULL semantics,
+and savepoint rollback — all in one in-memory engine, rendered on a dark background.
 
 [MP4 version](doc/demo.mp4) · [asciinema recording](doc/demo.cast)
 
@@ -227,5 +227,6 @@ Apache-2.0 License — contributions welcome!
 - **Issues:** [Open an issue](https://github.com/vexify-org/JSQL-neo/issues)
 - **PRs:** Fork → branch → PR — thank you!
 - **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
+- **Dev container:** [jsql-neo/devbox](https://github.com/jsql-neo/devbox) — reproducible dev environment (Docker/devcontainer)
 - **Code of Conduct:** [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
 - **Security:** [SECURITY.md](SECURITY.md) — please report vulnerabilities privately

package/bin/jsql

@@ -13,7 +13,7 @@ const { nag, setStarred, readConfig } = require('../lib/star-nag');
 
 // star 提示：任何异常都不该挡住命令本身
 // version / --version 只回版本号、star 本身就是干这件事的 —— 这些不提示，其余全部提示
-const NO_NAG_ARGS = new Set(['version', '--version', '-v', 'star']);
+const NO_NAG_ARGS = new Set(['version', '--version', '-v', 'star', 'update', 'uninstall', 'remove']);
 if (!process.env.JSQL_NO_STAR_NAG && !NO_NAG_ARGS.has(process.argv[2])) {
   try { nag(); } catch (e) { /* 提示失败与命令无关 */ }
 }
@@ -34,6 +34,122 @@ const manager = new ModuleManager();
 const RAW_ARGV = process.argv.slice(2);
 
 const _pkg = require('../package.json');
+
+// ── update / uninstall 命令的实现 ─────────────────────────────
+
+function updateOptions(sub) {
+  sub.option('check', { type: 'boolean', description: 'Only check for a newer version' });
+  sub.option('force', { type: 'boolean', description: 'Reinstall even if already up to date' });
+  sub.option('dry-run', { type: 'boolean', description: 'Print the install command without running it' });
+  sub.option('json', { type: 'boolean', description: 'Output as JSON' });
+}
+
+async function updateHandler(argv) {
+  const updater = require('../lib/updater');
+  try {
+    const result = await updater.runUpdate({
+      checkOnly: argv.check === true,
+      force: argv.force === true,
+      dryRun: argv['dry-run'] === true,
+    });
+    if (argv.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(updater.formatResult(result));
+    if (!result.ok) process.exitCode = 1;
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+function uninstallOptions(sub) {
+  sub.option('yes', { alias: ['y'], type: 'boolean', description: 'Skip the confirmation prompt' });
+  sub.option('keep-data', { type: 'boolean', description: 'Keep user data (plugins/config/cache)' });
+  sub.option('global', { type: 'boolean', description: 'Only uninstall the global npm package' });
+  sub.option('all', { type: 'boolean', description: 'Remove user data and the global npm package' });
+  sub.option('dry-run', { type: 'boolean', description: 'Show what would be removed' });
+  sub.option('json', { type: 'boolean', description: 'Output as JSON' });
+}
+
+async function uninstallHandler(argv) {
+  const un = require('../lib/uninstaller');
+  const fail = (e) => { console.error(`Error: ${e.message}`); process.exitCode = 1; };
+  try {
+    const yes = argv.yes === true || argv.y === true;
+    const dryRun = argv['dry-run'] === true;
+    const doGlobal = argv.global === true || argv.all === true;
+    const keepData = argv['keep-data'] === true || (argv.global === true && argv.all !== true);
+    const doData = !keepData;
+
+    if (!doData && !doGlobal) {
+      console.log('Nothing to do (data kept, global package not requested).');
+      return;
+    }
+
+    const targets = doData ? un.inspectTargets() : [];
+    const existing = targets.filter((t) => t.exists);
+    const globalInstalled = doGlobal ? un.isGloballyInstalled() : false;
+
+    if (!dryRun) {
+      if (doData && existing.length === 0 && !doGlobal) {
+        console.log('No jsql user data found. Nothing to remove.');
+        return;
+      }
+      if (!yes) {
+        if (!process.stdin.isTTY) {
+          console.error('Refusing to delete user data without confirmation. Re-run with --yes (or --dry-run to preview).');
+          process.exitCode = 1;
+          return;
+        }
+        if (doData && existing.length) {
+          console.log('The following user data will be removed:');
+          for (const t of existing) console.log(`  - ${t.path}  (${t.label})`);
+        }
+        if (doGlobal) console.log('Will also run: npm uninstall -g ' + un.PKG_NAME);
+        const ok = await un.confirm('Proceed? [y/N] ');
+        if (!ok) {
+          console.log('Aborted. No changes were made.');
+          return;
+        }
+      }
+    }
+
+    const dataResult = doData ? un.removeData({ dryRun }) : { removed: [], skipped: [], failed: [] };
+    let globalResult = null;
+    if (doGlobal) {
+      if (dryRun) globalResult = { ok: true, dryRun: true, command: `npm uninstall -g ${un.PKG_NAME}`, error: null };
+      else if (!globalInstalled) globalResult = { ok: true, skipped: true, command: `npm uninstall -g ${un.PKG_NAME}`, error: null };
+      else globalResult = un.uninstallGlobal(false);
+    }
+
+    if (argv.json) {
+      console.log(JSON.stringify({ data: dataResult, global: globalResult, dryRun }, null, 2));
+    } else {
+      const verb = dryRun ? 'Would remove' : 'Removed';
+      if (dataResult.removed.length) {
+        console.log(`${verb} ${dataResult.removed.length} path(s):`);
+        for (const p of dataResult.removed) console.log(`  - ${p}`);
+      } else if (doData) {
+        console.log('No jsql user data to remove.');
+      }
+      for (const f of dataResult.failed) console.error(`Failed to remove ${f.path}: ${f.error}`);
+      if (doGlobal) {
+        if (globalResult.dryRun) console.log(`Would run: ${globalResult.command}`);
+        else if (globalResult.skipped) console.log('Global jsql-neo package is not installed; skipped npm uninstall.');
+        else if (globalResult.ok) console.log('Uninstalled global package (npm uninstall -g jsql-neo).');
+        else console.error(`Global uninstall failed: ${globalResult.error}`);
+      }
+      if (!doGlobal) {
+        console.log('To remove the package itself, run: npm uninstall -g jsql-neo');
+      }
+    }
+    if (dataResult.failed.length || (globalResult && !globalResult.ok && !globalResult.skipped)) {
+      process.exitCode = 1;
+    }
+  } catch (e) {
+    fail(e);
+  }
+}
+
 const cli = (yaggs || require('./yaggs-fallback').buildYaggsFallback(_pkg))({
   pkg: _pkg,
 })
@@ -412,6 +528,9 @@ const cli = (yaggs || require('./yaggs-fallback').buildYaggsFallback(_pkg))({
       fail(e);
     }
   })
+  .command('update', 'Update jsql-neo to the latest version', updateOptions, updateHandler)
+  .command('uninstall', 'Remove jsql user data and/or the global package', uninstallOptions, uninstallHandler)
+  .command('remove', 'Alias of uninstall', uninstallOptions, uninstallHandler)
   .command('version', 'Show version', null, () => {
     console.log(require('../package.json').version);
   })

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.5.24 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.25 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');

package/lib/uninstaller.js

@@ -0,0 +1,216 @@
+'use strict';
+/**
+ * jsql uninstall —— 清理 jsql-neo 的用户级数据（可选卸载全局包）。
+ *
+ * 红线：
+ *   - 只允许删除用户 home 目录下、且属于 jsql 的固定路径；
+ *   - 拒绝删除 home 本身、文件系统根、当前工作目录、包目录（仓库）及其祖先/子目录；
+ *   - 绝不静默删除：非 TTY 且没有 --yes 时直接拒绝；TTY 下要求交互确认。
+ *
+ * 覆盖的数据位置（与代码里的实际路径保持一致）：
+ *   ~/.jsql/                 插件注册表安装目录（lib/database.js / src/cli/plugin.js）
+ *   ~/.config/jsql/          模块配置 mod.config（lib/mod.js）
+ *   ~/.jsqlmr                star 提示状态（lib/star-nag.js）
+ *   ~/.cache/jsql/           可能的缓存（存在才删）
+ * 支持 JSQL_PLUGIN_DIR / JSQL_MOD_CONFIG / JSQL_MR_PATH / JSQL_CACHE_DIR 覆盖。
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+const { execFileSync, spawnSync } = require('child_process');
+
+const PKG_NAME = 'jsql-neo';
+
+function packageDir() {
+  return path.resolve(__dirname, '..');
+}
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function isInside(child, parent) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * 列出所有清理目标。
+ * @param {{keepData?: boolean}} [opts]
+ * @returns {Array<{path: string, kind: 'dir'|'file', label: string}>}
+ */
+function collectTargets(opts = {}) {
+  if (opts.keepData) return [];
+  const home = os.homedir();
+  const targets = [];
+  const add = (p, kind, label) => {
+    if (!p) return;
+    const resolved = path.resolve(p);
+    if (targets.some((t) => t.path === resolved)) return;
+    targets.push({ path: resolved, kind, label });
+  };
+
+  add(process.env.JSQL_PLUGIN_DIR || path.join(home, '.jsql'), 'dir', '插件/用户数据 (~/.jsql)');
+
+  if (process.env.JSQL_MOD_CONFIG) {
+    add(process.env.JSQL_MOD_CONFIG, 'file', '模块配置 (JSQL_MOD_CONFIG)');
+  } else {
+    add(path.join(home, '.config', 'jsql'), 'dir', '模块配置 (~/.config/jsql)');
+  }
+
+  add(process.env.JSQL_MR_PATH || path.join(home, '.jsqlmr'), 'file', 'star 状态 (~/.jsqlmr)');
+  add(process.env.JSQL_CACHE_DIR || path.join(home, '.cache', 'jsql'), 'dir', '缓存 (~/.cache/jsql)');
+
+  return targets;
+}
+
+/**
+ * 安全校验：任何目标都必须落在 home 下、且不能碰到仓库/工作目录。
+ * @throws {Error} 校验不通过
+ */
+function assertSafeTarget(target) {
+  const resolved = path.resolve(target.path || target);
+  const home = path.resolve(os.homedir());
+  const pkg = packageDir();
+  const cwd = path.resolve(process.cwd());
+  const root = path.parse(resolved).root;
+
+  if (resolved === root) {
+    throw new Error(`refusing to remove filesystem root: ${resolved}`);
+  }
+  if (resolved === home) {
+    throw new Error(`refusing to remove home directory: ${resolved}`);
+  }
+  if (!isInside(resolved, home)) {
+    throw new Error(`refusing to remove path outside home (${home}): ${resolved}`);
+  }
+  if (isInside(pkg, resolved) || isInside(resolved, pkg)) {
+    throw new Error(`refusing to remove path overlapping the jsql-neo package: ${resolved}`);
+  }
+  // 目标不能是当前工作目录的祖先（否则会连工作目录一起删掉）
+  if (isInside(cwd, resolved)) {
+    throw new Error(`refusing to remove an ancestor of the current working directory: ${resolved}`);
+  }
+  // 目标必须是 jsql 命名的目录/文件，杜绝误删
+  const base = path.basename(resolved).toLowerCase();
+  const looksLikeJsql = base === '.jsqlmr' || base.startsWith('jsql') || base === '.jsql';
+  const parentIsConfig = path.basename(path.dirname(resolved)) === '.config'
+    || path.basename(path.dirname(resolved)) === '.cache';
+  if (!looksLikeJsql && !parentIsConfig) {
+    throw new Error(`refusing to remove unexpected path: ${resolved}`);
+  }
+  return resolved;
+}
+
+/**
+ * 检查目标是否存在，并给出可删除列表（不实际删除）。
+ * @param {{keepData?: boolean}} [opts]
+ */
+function inspectTargets(opts = {}) {
+  return collectTargets(opts).map((t) => {
+    let exists = false;
+    let isSymlink = false;
+    try {
+      const st = fs.lstatSync(t.path);
+      exists = true;
+      isSymlink = st.isSymbolicLink();
+    } catch (_) { /* 不存在 */ }
+    return { ...t, exists, isSymlink };
+  });
+}
+
+/**
+ * 删除数据目标。
+ * @param {{keepData?: boolean, dryRun?: boolean}} [opts]
+ * @returns {{removed: string[], skipped: string[], failed: Array<{path: string, error: string}>}}
+ */
+function removeData(opts = {}) {
+  const result = { removed: [], skipped: [], failed: [] };
+  const targets = inspectTargets(opts);
+  for (const t of targets) {
+    if (!t.exists) {
+      result.skipped.push(t.path);
+      continue;
+    }
+    let safe;
+    try {
+      safe = assertSafeTarget(t);
+    } catch (e) {
+      result.failed.push({ path: t.path, error: e.message });
+      continue;
+    }
+    if (opts.dryRun) {
+      result.removed.push(safe);
+      continue;
+    }
+    try {
+      // 符号链接只删链接本身，绝不跟随
+      if (t.isSymlink) fs.unlinkSync(safe);
+      else fs.rmSync(safe, { recursive: true, force: true });
+      result.removed.push(safe);
+    } catch (e) {
+      result.failed.push({ path: safe, error: e.message });
+    }
+  }
+  return result;
+}
+
+/** 卸载全局 npm 包；失败时返回错误信息而不是抛异常 */
+function uninstallGlobal(dryRun) {
+  const args = ['uninstall', '-g', PKG_NAME];
+  const command = `${npmCommand()} ${args.join(' ')}`;
+  if (dryRun) return { ok: true, dryRun: true, command, error: null };
+
+  const r = spawnSync(npmCommand(), args, {
+    stdio: 'inherit',
+    timeout: 5 * 60 * 1000,
+  });
+  if (r.error) return { ok: false, command, error: r.error.message };
+  if (r.status !== 0) return { ok: false, command, error: `npm uninstall exited with code ${r.status}` };
+  return { ok: true, command, error: null };
+}
+
+/** 全局安装是否还存在（用 npm root -g 判断） */
+function isGloballyInstalled() {
+  try {
+    const root = execFileSync(npmCommand(), ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: 15000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!root) return false;
+    return fs.existsSync(path.join(root, PKG_NAME, 'package.json'));
+  } catch (_) {
+    return false;
+  }
+}
+
+/** 交互确认；非 TTY 返回 false（调用方应要求 --yes） */
+function confirm(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      resolve(false);
+      return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
+    });
+  });
+}
+
+module.exports = {
+  PKG_NAME,
+  collectTargets,
+  assertSafeTarget,
+  inspectTargets,
+  removeData,
+  uninstallGlobal,
+  isGloballyInstalled,
+  confirm,
+  packageDir,
+  isInside,
+};

package/lib/updater.js

@@ -0,0 +1,365 @@
+'use strict';
+/**
+ * jsql update —— 检查并安装 jsql-neo 的新版本。
+ *
+ * 设计取舍：
+ *   - 版本来源优先 npm registry（https://registry.npmjs.org/jsql-neo/latest），
+ *     失败时退回 `npm view jsql-neo version`；两者都失败就优雅报错，不 crash。
+ *   - 只有「全局安装」才自动执行 `npm install -g jsql-neo@latest`；
+ *     本地依赖安装绝不自动改用户的 package.json，只打印清晰指令。
+ *   - `--check` 只看不装；`--dry-run` 打印将要执行的命令；`--force` 即使已是最新也重装。
+ *
+ * 不引入任何第三方依赖（与项目其它部分保持一致）。
+ */
+
+const path = require('path');
+const https = require('https');
+const { execFileSync, spawnSync } = require('child_process');
+
+const PKG_NAME = 'jsql-neo';
+const REGISTRY_LATEST = `https://registry.npmjs.org/${PKG_NAME}/latest`;
+const FETCH_TIMEOUT_MS = 8000;
+const MAX_BODY_BYTES = 512 * 1024;
+
+function packageDir() {
+  return path.resolve(__dirname, '..');
+}
+
+function currentVersion() {
+  return require('../package.json').version;
+}
+
+// ─── 版本比较 ────────────────────────────────────────────────
+
+/** 解析 semver（宽松）：v1.2.3 / 1.2 / 1.2.3-beta.1 → { nums, pre } */
+function parseVersion(v) {
+  let s = String(v == null ? '' : v).trim();
+  if (s[0] === 'v' || s[0] === 'V') s = s.slice(1);
+  const plus = s.indexOf('+');
+  if (plus !== -1) s = s.slice(0, plus);
+  const dash = s.indexOf('-');
+  const core = dash === -1 ? s : s.slice(0, dash);
+  const pre = dash === -1 ? '' : s.slice(dash + 1);
+  const nums = core.split('.').map((n) => {
+    const x = parseInt(n, 10);
+    return Number.isFinite(x) ? x : 0;
+  });
+  while (nums.length < 3) nums.push(0);
+  return { nums, pre };
+}
+
+/** semver-ish 比较：a < b → -1，相等 → 0，a > b → 1（prerelease 视为更低） */
+function compareVersions(a, b) {
+  const A = parseVersion(a);
+  const B = parseVersion(b);
+  for (let i = 0; i < 3; i++) {
+    if (A.nums[i] !== B.nums[i]) return A.nums[i] > B.nums[i] ? 1 : -1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;
+  if (!B.pre) return -1;
+  return A.pre > B.pre ? 1 : -1;
+}
+
+function isNewer(latest, current) {
+  return compareVersions(latest, current) > 0;
+}
+
+// ─── 网络 ───────────────────────────────────────────────────
+
+function httpGetText(url, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) {
+      reject(new Error(`too many redirects for ${url}`));
+      return;
+    }
+    let req;
+    try {
+      req = https.get(url, {
+        headers: {
+          'User-Agent': `jsql-neo/${currentVersion()} (+https://github.com/vexify-org/JSQL-neo)`,
+          Accept: 'application/vnd.npm.install-v1+json, application/json;q=0.9, */*;q=0.1',
+        },
+      }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          const next = new URL(res.headers.location, url).toString();
+          if (!/^https?:/i.test(next)) {
+            reject(new Error(`invalid redirect target for ${url}`));
+            return;
+          }
+          httpGetText(next, redirects + 1).then(resolve, reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+          return;
+        }
+        const chunks = [];
+        let received = 0;
+        res.on('data', (chunk) => {
+          received += chunk.length;
+          if (received > MAX_BODY_BYTES) {
+            res.destroy();
+            reject(new Error(`response too large for ${url}`));
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        res.on('error', reject);
+      });
+    } catch (e) {
+      reject(e);
+      return;
+    }
+    req.on('error', reject);
+    req.setTimeout(FETCH_TIMEOUT_MS, () => {
+      try { req.destroy(); } catch (_) { /* ignore */ }
+      reject(new Error(`request timed out after ${FETCH_TIMEOUT_MS}ms: ${url}`));
+    });
+  });
+}
+
+/**
+ * 查询 npm 上的最新版本号。
+ * @param {{ fetchImpl?: Function, npmView?: boolean }} [opts] 测试可注入
+ * @returns {Promise<{version: string, source: string}>}
+ */
+async function fetchLatestVersion(opts = {}) {
+  const fetchImpl = opts.fetchImpl || httpGetText;
+  const errors = [];
+
+  // 1) registry HTTP（快，且不需要 npm 进程）
+  try {
+    const body = await fetchImpl(REGISTRY_LATEST);
+    const data = JSON.parse(body);
+    if (data && typeof data.version === 'string' && data.version.trim()) {
+      return { version: data.version.trim(), source: 'registry' };
+    }
+    throw new Error('registry response has no version field');
+  } catch (e) {
+    errors.push(`registry: ${e.message}`);
+  }
+
+  // 2) npm CLI 兜底（有些环境走私有 registry 配置，curl 直连反而不通）
+  if (opts.npmView !== false) {
+    try {
+      const out = execFileSync(npmCommand(), ['view', PKG_NAME, 'version'], {
+        encoding: 'utf8',
+        timeout: 15000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }).trim();
+      // `npm view` 在旧版本里可能输出多行/带引号
+      const m = out.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/);
+      if (m) return { version: m[0], source: 'npm-view' };
+      throw new Error(`unexpected npm view output: ${out.slice(0, 120)}`);
+    } catch (e) {
+      errors.push(`npm view: ${e.message}`);
+    }
+  }
+
+  const err = new Error(`could not determine the latest version (${errors.join('; ')})`);
+  err.causes = errors;
+  throw err;
+}
+
+// ─── 安装形态判断 ───────────────────────────────────────────
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function isInside(child, parent) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/** 收集可能的全局 node_modules 根目录 */
+function globalRoots() {
+  const roots = [];
+  try {
+    const out = execFileSync(npmCommand(), ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: 15000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (out) roots.push(out);
+  } catch (_) { /* npm 不可用就靠下面的启发式 */ }
+
+  if (process.env.npm_config_prefix) {
+    roots.push(path.join(process.env.npm_config_prefix, 'lib', 'node_modules'));
+    if (process.platform === 'win32') {
+      roots.push(path.join(process.env.npm_config_prefix, 'node_modules'));
+    }
+  }
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    roots.push(path.join(process.env.APPDATA, 'npm', 'node_modules'));
+  }
+  return Array.from(new Set(roots.filter(Boolean)));
+}
+
+/**
+ * 判断当前这份 jsql-neo 是否来自全局安装。
+ * @param {string} [dir] 包目录，默认是 lib/.. 
+ */
+function isGlobalInstall(dir) {
+  const pkgDir = path.resolve(dir || packageDir());
+  return globalRoots().some((root) => isInside(pkgDir, root));
+}
+
+/** 当前包是否位于某个项目的 node_modules 下（本地依赖安装） */
+function isLocalDependency(dir) {
+  const pkgDir = path.resolve(dir || packageDir());
+  return path.basename(path.dirname(pkgDir)) === 'node_modules';
+}
+
+// ─── 更新流程 ───────────────────────────────────────────────
+
+function installCommand(version) {
+  return `${npmCommand()} install -g ${PKG_NAME}@${version}`;
+}
+
+/**
+ * 执行更新检查 / 安装。
+ * @param {{checkOnly?: boolean, force?: boolean, dryRun?: boolean}} [opts]
+ */
+async function runUpdate(opts = {}) {
+  const current = currentVersion();
+  let latestInfo;
+  try {
+    latestInfo = await fetchLatestVersion({ fetchImpl: opts.fetchImpl, npmView: opts.npmView });
+  } catch (e) {
+    return {
+      ok: false,
+      current,
+      latest: null,
+      error: e.message,
+      hints: [
+        '检查网络/registry 配置，或手动执行: ' + installCommand('latest'),
+      ],
+    };
+  }
+
+  const latest = latestInfo.version;
+  const updateAvailable = isNewer(latest, current);
+  const global = typeof opts.global === 'boolean' ? opts.global : isGlobalInstall();
+  const localDep = typeof opts.localDependency === 'boolean' ? opts.localDependency : isLocalDependency();
+  const result = {
+    ok: true,
+    current,
+    latest,
+    latestSource: latestInfo.source,
+    updateAvailable,
+    installType: global ? 'global' : (localDep ? 'local-dependency' : 'unknown'),
+    action: 'none',
+    command: null,
+    installed: false,
+    warnings: [],
+  };
+
+  if (!updateAvailable && !opts.force) {
+    result.action = opts.checkOnly ? 'checked' : 'up-to-date';
+    return result;
+  }
+
+  if (opts.checkOnly) {
+    result.action = 'checked';
+    result.command = global ? installCommand(latest) : installCommand(latest);
+    return result;
+  }
+
+  if (opts.dryRun) {
+    result.action = 'would-install';
+    result.command = installCommand(latest);
+    return result;
+  }
+
+  // 非全局安装：不自动改动用户项目依赖，只给清晰指令
+  if (!global) {
+    result.action = 'instructions';
+    result.command = installCommand(latest);
+    result.localHint = `npm install ${PKG_NAME}@${latest}`;
+    result.warnings.push(
+      'jsql-neo 不是全局安装（当前位于项目 node_modules 或开发目录），未自动安装。'
+    );
+    return result;
+  }
+
+  const args = ['install', '-g', `${PKG_NAME}@${latest}`];
+  const r = spawnSync(npmCommand(), args, {
+    stdio: 'inherit',
+    timeout: 10 * 60 * 1000,
+  });
+  result.command = `${npmCommand()} ${args.join(' ')}`;
+  if (r.error) {
+    result.ok = false;
+    result.error = r.error.message;
+    result.action = 'install-failed';
+    result.warnings.push('可尝试手动执行并检查权限: ' + result.command);
+    return result;
+  }
+  if (r.status !== 0) {
+    result.ok = false;
+    result.error = `npm install exited with code ${r.status}`;
+    result.action = 'install-failed';
+    result.warnings.push(
+      '如果是权限问题，尝试: sudo ' + result.command,
+    );
+    return result;
+  }
+
+  result.installed = true;
+  result.action = 'installed';
+  result.after = latest;
+  return result;
+}
+
+/** 把 runUpdate 的结果渲染成人读文本 */
+function formatResult(r) {
+  const lines = [];
+  if (!r.ok) {
+    lines.push(`更新失败: ${r.error}`);
+    for (const h of r.hints || []) lines.push(`  ${h}`);
+    return lines.join('\n');
+  }
+  lines.push(`当前版本: ${r.current}`);
+  lines.push(`最新版本: ${r.latest}${r.latestSource === 'npm-view' ? ' (via npm view)' : ''}`);
+
+  if (r.action === 'up-to-date') {
+    lines.push('已是最新版本。');
+  } else if (r.action === 'checked') {
+    lines.push(r.updateAvailable ? '有新版本可用。' : '已是最新版本。');
+    if (r.updateAvailable) lines.push(`运行 \`jsql update\` 安装，或手动执行: ${r.command}`);
+  } else if (r.action === 'would-install') {
+    lines.push(`将执行: ${r.command}`);
+    lines.push('（--dry-run，未做任何修改）');
+  } else if (r.action === 'installed') {
+    lines.push(`已更新到 ${r.latest}。重新打开终端后 \`jsql version\` 生效。`);
+  } else if (r.action === 'instructions') {
+    lines.push('检测到非全局安装，未自动更新（避免改动你的项目依赖）。');
+    lines.push(`全局安装: ${r.command}`);
+    if (r.localHint) lines.push(`项目内升级: ${r.localHint}`);
+  } else if (r.action === 'install-failed') {
+    lines.push(`安装失败: ${r.error}`);
+  }
+  for (const w of r.warnings || []) lines.push(`注意: ${w}`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  PKG_NAME,
+  REGISTRY_LATEST,
+  parseVersion,
+  compareVersions,
+  isNewer,
+  currentVersion,
+  fetchLatestVersion,
+  isGlobalInstall,
+  isLocalDependency,
+  globalRoots,
+  runUpdate,
+  formatResult,
+  installCommand,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.5.24",
+  "version": "6.5.25",
   "description": "JSQL-NEO \u2014 Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",

package/postinstall.js

@@ -30,13 +30,28 @@ const GHPROXY = process.env.JSQL_GHPROXY !== undefined
   ? process.env.JSQL_GHPROXY
   : '';
 const GHPROXY_TOKEN = process.env.JSQL_GHPROXY_TOKEN || '';
-// 原生二进制自动下载默认关闭（opt-in）：防止每次 npm install 都从网络拉取并
-// require() 一个预编译二进制（issue #25 供应链风险）。显式设置
-// JSQL_AUTO_DOWNLOAD_NATIVE=1（或 JSQL_NATIVE_DOWNLOAD=1）才下载；
-// 否则只用本地已有模块，或回退源码编译。
-const AUTO_DOWNLOAD_NATIVE = process.env.JSQL_AUTO_DOWNLOAD_NATIVE === '1'
-  || process.env.JSQL_NATIVE_DOWNLOAD === '1';
-const TAG = `v${pkg.version}`;
+
+// ── 原生二进制获取策略 ────────────────────────────────────────────────
+// v6.5.25 起默认【强制从远端拉取最新版】：安装时总是从 GitHub Release 重新
+// 下载与当前包版本匹配的原生模块，校验 SHA256 后覆盖本地同名文件（旧缓存、
+// 手工编译产物都不会被直接信任）。下载失败时保留本地可用模块，最后才回退
+// 源码编译 —— 即「远端优先 / 强制覆盖 / 失败降级」。
+//
+// 环境变量：
+//   JSQL_NO_NATIVE_DOWNLOAD=1        完全关闭下载（旧 opt-in 行为，local → 源码编译）
+//   JSQL_NATIVE_DOWNLOAD=0           同上（=0 语义）
+//   JSQL_AUTO_DOWNLOAD_NATIVE=0      同上（=0 语义）
+//   JSQL_NATIVE_FORCE_REFRESH=0      仍下载，但本地模块可用时跳过（旧「缓存优先」）
+//   JSQL_NATIVE_TAG=vX.Y.Z|latest    指定远端 tag；默认 v<package.version>
+//   JSQL_AUTO_DOWNLOAD_NATIVE=1 / JSQL_NATIVE_DOWNLOAD=1  仍然兼容（显式开）
+//
+// 供应链安全（issue #25）：不内置任何加速站/token，代理仍需显式 JSQL_GHPROXY，
+// 且下载必须通过 SHA256SUMS 校验（除非用户显式 JSQL_ALLOW_UNVERIFIED_NATIVE=1）。
+const DOWNLOAD_DISABLED = process.env.JSQL_NO_NATIVE_DOWNLOAD === '1'
+  || process.env.JSQL_NATIVE_DOWNLOAD === '0'
+  || process.env.JSQL_AUTO_DOWNLOAD_NATIVE === '0';
+const FORCE_REFRESH = process.env.JSQL_NATIVE_FORCE_REFRESH !== '0';
+const TAG = process.env.JSQL_NATIVE_TAG || `v${pkg.version}`;
 
 // 原生模块体积上限（防代理/镜像返回超大文件打爆磁盘/内存）
 const MAX_DOWNLOAD_BYTES = 64 * 1024 * 1024;
@@ -76,6 +91,52 @@ function sameOrigin(a, b) {
   try { return new URL(a).origin === new URL(b).origin; } catch (_) { return false; }
 }
 
+/**
+ * 解析 JSQL_NATIVE_TAG=latest：跟随 GitHub `/releases/latest` 的 302 跳转，
+ * 从 Location 里取出真实 tag（vX.Y.Z）。失败返回 null —— 调用方回退到当前版本 tag。
+ */
+function resolveLatestTag() {
+  return new Promise((resolve) => {
+    const url = `https://github.com/${REPO}/releases/latest`;
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    let req;
+    try {
+      req = https.get(url, { headers: { 'User-Agent': 'jsql-neo-postinstall' } }, (res) => {
+        const loc = res.headers.location || '';
+        res.resume();
+        const m = String(loc).match(/\/releases\/tag\/([^/?#]+)/);
+        done(m ? decodeURIComponent(m[1]) : null);
+      });
+    } catch (_) {
+      done(null);
+      return;
+    }
+    req.on('error', () => done(null));
+    req.setTimeout(8000, () => { try { req.destroy(); } catch (_) {} done(null); });
+  });
+}
+
+/**
+ * 取得本次要拉取的 release tag。
+ * 默认 = v<package.version>（二进制必须与包版本匹配，避免 ABI/API 错配）；
+ * 只有用户显式 JSQL_NATIVE_TAG=latest 时才去解析最新 release。
+ */
+async function releaseTag() {
+  if (TAG.toLowerCase() !== 'latest') return TAG;
+  const resolved = await resolveLatestTag();
+  if (resolved) {
+    console.log(`[jsql-neo] JSQL_NATIVE_TAG=latest resolved to ${resolved}`);
+    return resolved;
+  }
+  console.warn(`[jsql-neo] cannot resolve latest release tag; using v${pkg.version}`);
+  return `v${pkg.version}`;
+}
+
+function withUserAgent(headers) {
+  return Object.assign({ 'User-Agent': 'jsql-neo-postinstall' }, headers || {});
+}
+
 function safeRedirect(next) {
   return /^https?:/i.test(String(next || ''));
 }
@@ -87,7 +148,7 @@ function download(url, dest, headers, redirects = 0) {
       return;
     }
     const mod = url.startsWith('https:') ? https : http;
-    const req = mod.get(url, { headers: headers || {} }, (res) => {
+    const req = mod.get(url, { headers: withUserAgent(headers) }, (res) => {
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
         res.resume();
         const next = new URL(res.headers.location, url).toString();
@@ -137,6 +198,10 @@ function download(url, dest, headers, redirects = 0) {
       });
     });
     req.on('error', reject);
+    req.setTimeout(60000, () => {
+      try { req.destroy(); } catch (_) { /* ignore */ }
+      reject(new Error(`download timed out after 60s: ${url}`));
+    });
   });
 }
 
@@ -147,7 +212,7 @@ function fetchText(url, headers, redirects = 0) {
       return;
     }
     const mod = url.startsWith('https:') ? https : http;
-    const req = mod.get(url, { headers: headers || {} }, (res) => {
+    const req = mod.get(url, { headers: withUserAgent(headers) }, (res) => {
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
         res.resume();
         const next = new URL(res.headers.location, url).toString();
@@ -178,6 +243,10 @@ function fetchText(url, headers, redirects = 0) {
       res.on('error', reject);
     });
     req.on('error', reject);
+    req.setTimeout(20000, () => {
+      try { req.destroy(); } catch (_) { /* ignore */ }
+      reject(new Error(`request timed out after 20s: ${url}`));
+    });
   });
 }
 
@@ -213,7 +282,7 @@ function expectedHashFromManifest(text, asset) {
  *   2) 从 GitHub Release 的 SHA256SUMS 资产下载并解析
  * 拿不到就返回 null —— 调用方会拒绝加载未校验的二进制（fail closed）。
  */
-async function fetchExpectedHash(asset) {
+async function fetchExpectedHash(asset, tag) {
   const explicit = process.env.JSQL_NATIVE_SHA256;
   if (explicit) {
     if (!/^[a-fA-F0-9]{64}$/.test(explicit.trim())) {
@@ -221,7 +290,7 @@ async function fetchExpectedHash(asset) {
     }
     return explicit.trim().toLowerCase();
   }
-  const raw = `https://github.com/${REPO}/releases/download/${TAG}/${CHECKSUM_ASSET}`;
+  const raw = `https://github.com/${REPO}/releases/download/${tag}/${CHECKSUM_ASSET}`;
   for (const cand of proxyCandidates(raw)) {
     try {
       const text = await fetchText(cand.url, cand.viaProxy ? proxyHeaders() : undefined);
@@ -271,7 +340,43 @@ function tryLoadNative() {
   }
 }
 
-async function downloadAndVerify() {
+/**
+ * 把已经校验过的临时文件安装到 NATIVE_PATH：
+ * 先备份现有模块（若存在），再原子替换。返回备份路径供失败回滚。
+ */
+function installDownloadedModule(tmp) {
+  fs.mkdirSync(path.dirname(NATIVE_PATH), { recursive: true });
+  const backup = `${NATIVE_PATH}.previous`;
+  let hadBackup = false;
+  if (fs.existsSync(NATIVE_PATH)) {
+    try {
+      fs.copyFileSync(NATIVE_PATH, backup);
+      hadBackup = true;
+    } catch (_) { /* 备份失败不阻塞覆盖，但会失去回滚能力 */ }
+  }
+  try {
+    fs.renameSync(tmp, NATIVE_PATH);
+  } catch (e) {
+    // Windows 上 rename 覆盖已存在文件会 EEXIST/EPERM
+    if (e.code === 'EEXIST' || e.code === 'EPERM' || e.code === 'EACCES') {
+      try { fs.unlinkSync(NATIVE_PATH); } catch (_) { /* ignore */ }
+      fs.renameSync(tmp, NATIVE_PATH);
+    } else {
+      throw e;
+    }
+  }
+  fs.chmodSync(NATIVE_PATH, 0o755);
+  return { backup: hadBackup ? backup : null };
+}
+
+/**
+ * 强制从远端拉取原生模块（默认路径）。
+ * 关键点：不因本地已有同名文件而跳过 —— 每次都重新下载、校验、覆盖安装。
+ *
+ * @param {{ tag?: string }} [opts]
+ * @returns {Promise<boolean>} 是否成功安装并加载
+ */
+async function downloadAndVerify(opts = {}) {
   if (!supportsNativeNapi()) {
     console.warn(
       `[jsql-neo] Node ${process.versions.node} provides N-API ${nativeNapiVersion() || 'unknown'}, ` +
@@ -279,13 +384,14 @@ async function downloadAndVerify() {
     );
     return false;
   }
+  const tag = opts.tag || await releaseTag();
   const libc = detectLibc();
   const asset = process.env.JSQL_NATIVE_ASSET || `jsql-neo-native.${nativeTargetSuffix(process.platform, process.arch, libc)}.node`;
-  const raw = `https://github.com/${REPO}/releases/download/${TAG}/${asset}`;
+  const raw = `https://github.com/${REPO}/releases/download/${tag}/${asset}`;
 
   let expected = null;
   try {
-    expected = await fetchExpectedHash(asset);
+    expected = await fetchExpectedHash(asset, tag);
   } catch (e) {
     console.warn('[jsql-neo] failed to resolve native checksum:', e.message);
   }
@@ -294,13 +400,13 @@ async function downloadAndVerify() {
   if (!expected && !allowUnverified) {
     if (libc === 'musl') {
       console.warn(
-        `[jsql-neo] musl libc detected but this release has no native asset for ${asset}; ` +
+        `[jsql-neo] musl libc detected but release ${tag} has no native asset for ${asset}; ` +
         'falling back to the WASM/JS engine. Set JSQL_NATIVE_ASSET to a compatible musl build if available.'
       );
     } else {
       // fail closed：拿不到 SHA256SUMS 就不下载，绝不 require 未经校验的二进制
       console.warn(
-        '[jsql-neo] no SHA256SUMS available for this release; refusing to download an unverified native module.\n' +
+        `[jsql-neo] no SHA256SUMS available for release ${tag}; refusing to download an unverified native module.\n` +
         '[jsql-neo] set JSQL_NATIVE_SHA256=<64-hex> to pin a checksum, or JSQL_ALLOW_UNVERIFIED_NATIVE=1 to override (unsafe).'
       );
     }
@@ -312,7 +418,7 @@ async function downloadAndVerify() {
 
   // 依次尝试：环境变量指定的代理 → 内置加速站 → 直连
   for (const cand of proxyCandidates(raw)) {
-    console.log(`[jsql-neo] downloading native module: ${cand.url}`);
+    console.log(`[jsql-neo] fetching native module (${tag}): ${cand.url}`);
     const tmp = `${NATIVE_PATH}.${process.pid}.download`;
     try {
       // 加速站鉴权走 Authorization 头，直连时不带
@@ -325,13 +431,23 @@ async function downloadAndVerify() {
         }
         console.log('[jsql-neo] checksum verified:', actual);
       }
-      fs.mkdirSync(path.dirname(NATIVE_PATH), { recursive: true });
-      fs.renameSync(tmp, NATIVE_PATH);
-      fs.chmodSync(NATIVE_PATH, 0o755);
+
+      // 强制覆盖：即便本地已有同名文件也替换（旧模块先备份，加载失败可回滚）
+      const installed = installDownloadedModule(tmp);
       if (tryLoadNative()) {
-        console.log('[jsql-neo] native module downloaded: native/jsql-neo-native.node');
+        if (installed.backup) {
+          try { fs.unlinkSync(installed.backup); } catch (_) { /* ignore */ }
+        }
+        console.log(`[jsql-neo] native module updated: native/jsql-neo-native.node (${tag})`);
         return true;
       }
+      // 新模块无法加载 → 回滚到之前的可用模块
+      if (installed.backup) {
+        try {
+          fs.renameSync(installed.backup, NATIVE_PATH);
+          console.warn('[jsql-neo] rolled back to the previous native module.');
+        } catch (_) { /* ignore */ }
+      }
       console.warn('[jsql-neo] downloaded module cannot be loaded; trying next source.');
     } catch (e) {
       console.warn('[jsql-neo] download failed:', e.message);
@@ -342,22 +458,13 @@ async function downloadAndVerify() {
   return false;
 }
 
-// 原生模块下载默认关闭（#25 安全加固）：只有在 CI 或显式设置 JSQL_NATIVE_DOWNLOAD=1
-// 时才从 GitHub Release 下载预编译二进制；普通 npm install 直接走源码编译或 WASM/JS 回退。
-function nativeDownloadEnabled() {
-  if (AUTO_DOWNLOAD_NATIVE) return true;
-  if (process.env.JSQL_NATIVE_DOWNLOAD === '1') return true;
-  // CI 构建需要发布平台二进制，视为显式 opt-in
-  if (process.env.CI === 'true' || process.env.CI === '1') return true;
-  return false;
-}
-
+/**
+ * 确保原生模块可用。
+ *
+ * 默认行为（v6.5.25+）：总是从远端 release 强制拉取并覆盖本地模块；
+ * 失败时按「本地已有模块 → 源码编译 → WASM/JS」逐级降级，绝不让安装失败。
+ */
 async function ensureNativeNode() {
-  // 已存在且能加载 → 直接用；否则默认不再自动下载（opt-in），只回退源码编译。
-  if (tryLoadNative()) {
-    console.log('[jsql-neo] native module ready: native/jsql-neo-native.node');
-    return;
-  }
   if (!supportsNativeNapi()) {
     console.warn(
       `[jsql-neo] Node ${process.versions.node} provides N-API ${nativeNapiVersion() || 'unknown'}, ` +
@@ -365,14 +472,35 @@ async function ensureNativeNode() {
     );
     return;
   }
-  if (nativeDownloadEnabled()) {
-    if (await downloadAndVerify()) return;
-  } else {
-    console.warn(
-      '[jsql-neo] native module not present; auto-download is OFF (opt-in, default).\n' +
-      '[jsql-neo] set JSQL_AUTO_DOWNLOAD_NATIVE=1 to fetch the prebuilt binary, or run: npm run build:native'
-    );
+
+  if (DOWNLOAD_DISABLED) {
+    console.warn('[jsql-neo] native download disabled by env (JSQL_NO_NATIVE_DOWNLOAD=1 / JSQL_NATIVE_DOWNLOAD=0); using local module or source build.');
+    if (tryLoadNative()) {
+      console.log('[jsql-neo] native module ready: native/jsql-neo-native.node');
+      return;
+    }
+    buildNativeFromSource();
+    return;
+  }
+
+  const localReady = tryLoadNative();
+  if (localReady && !FORCE_REFRESH) {
+    console.log('[jsql-neo] native module ready (JSQL_NATIVE_FORCE_REFRESH=0, remote refresh skipped): native/jsql-neo-native.node');
+    return;
+  }
+
+  console.log(localReady
+    ? '[jsql-neo] local native module found; forcing refresh from remote release (set JSQL_NATIVE_FORCE_REFRESH=0 to keep the local copy)'
+    : '[jsql-neo] fetching native module from remote release...');
+
+  if (await downloadAndVerify()) return;
+
+  // 拉取失败：本地可用就继续用本地 —— 网络问题不该把已经能跑的安装搞坏
+  if (tryLoadNative()) {
+    console.warn('[jsql-neo] remote refresh failed; keeping the existing local native module.');
+    return;
   }
+  console.warn('[jsql-neo] could not fetch a verified native module; falling back to source build / WASM.');
   buildNativeFromSource();
 }
 
@@ -416,4 +544,11 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { buildNativeFromSource, downloadAndVerify, ensureNativeNode };
+module.exports = {
+  buildNativeFromSource,
+  downloadAndVerify,
+  ensureNativeNode,
+  releaseTag,
+  resolveLatestTag,
+  installDownloadedModule,
+};

package/test/cli-maintenance.test.js

@@ -0,0 +1,112 @@
+'use strict';
+/* v6.5.25: `jsql update` / `jsql uninstall` helpers — offline unit tests. */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const updater = require('../lib/updater');
+const uninstaller = require('../lib/uninstaller');
+
+let pass = 0, fail = 0;
+function ok(name, cond) {
+  if (cond) { pass++; console.log(`[OK] ${name}`); }
+  else { fail++; console.log(`[FAIL] ${name}`); }
+}
+
+function fakeFetch(version) {
+  return async () => JSON.stringify({ name: 'jsql-neo', version });
+}
+
+(async () => {
+  // ── version comparison ─────────────────────────────────
+  ok('compareVersions 6.5.24 < 6.5.25', updater.compareVersions('6.5.24', '6.5.25') === -1);
+  ok('compareVersions v6.5.4 > 6.5.3', updater.compareVersions('v6.5.4', '6.5.3') === 1);
+  ok('compareVersions equal', updater.compareVersions('6.5.24', 'v6.5.24') === 0);
+  ok('prerelease is lower', updater.compareVersions('6.5.25-beta.1', '6.5.25') === -1);
+  ok('isNewer true', updater.isNewer('6.5.25', '6.5.24'));
+  ok('isNewer false', !updater.isNewer('6.5.24', '6.5.24'));
+
+  // ── fetchLatestVersion (injected fetch) ────────────────
+  const info = await updater.fetchLatestVersion({ fetchImpl: fakeFetch('9.9.9'), npmView: false });
+  ok('fetchLatestVersion parses registry json', info.version === '9.9.9' && info.source === 'registry');
+
+  let threw = false;
+  try {
+    await updater.fetchLatestVersion({ fetchImpl: async () => { throw new Error('offline'); }, npmView: false });
+  } catch (e) { threw = true; }
+  ok('fetchLatestVersion fails gracefully', threw);
+
+  // ── runUpdate branches ─────────────────────────────────
+  const upToDate = await updater.runUpdate({
+    fetchImpl: fakeFetch(updater.currentVersion()), npmView: false, global: false,
+  });
+  ok('update: up-to-date', upToDate.ok && upToDate.action === 'up-to-date' && !upToDate.updateAvailable);
+
+  const check = await updater.runUpdate({
+    fetchImpl: fakeFetch('99.0.0'), npmView: false, global: false, checkOnly: true,
+  });
+  ok('update: check only', check.ok && check.action === 'checked' && check.updateAvailable);
+
+  const local = await updater.runUpdate({
+    fetchImpl: fakeFetch('99.0.0'), npmView: false, global: false,
+  });
+  ok('update: non-global gives instructions', local.action === 'instructions' && !!local.command);
+  ok('update: never auto-installs locally', local.installed === false);
+
+  const dry = await updater.runUpdate({
+    fetchImpl: fakeFetch('99.0.0'), npmView: false, global: true, dryRun: true,
+  });
+  ok('update: global dry-run', dry.action === 'would-install' && /install -g/.test(dry.command));
+
+  ok('formatResult renders versions', /当前版本/.test(updater.formatResult(upToDate)));
+
+  // ── uninstall: path collection + safety ────────────────
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'jsql-uninstall-'));
+  const oldHome = process.env.HOME;
+  const oldMod = process.env.JSQL_MOD_CONFIG;
+  const oldMr = process.env.JSQL_MR_PATH;
+  const oldCache = process.env.JSQL_CACHE_DIR;
+  try {
+    process.env.HOME = tmpHome;
+    delete process.env.JSQL_MOD_CONFIG;
+    delete process.env.JSQL_MR_PATH;
+    delete process.env.JSQL_CACHE_DIR;
+
+    fs.mkdirSync(path.join(tmpHome, '.jsql', 'plugins'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.jsql', 'plugins', 'p.json'), '{}');
+    fs.mkdirSync(path.join(tmpHome, '.config', 'jsql'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.config', 'jsql', 'mod.config'), '{}');
+    fs.writeFileSync(path.join(tmpHome, '.jsqlmr'), '{}');
+
+    const targets = uninstaller.collectTargets();
+    ok('uninstall: collects user data paths', targets.length >= 3);
+    ok('uninstall: keep-data collects nothing', uninstaller.collectTargets({ keepData: true }).length === 0);
+
+    const inspected = uninstaller.inspectTargets();
+    ok('uninstall: detects existing paths', inspected.filter(t => t.exists).length === 3);
+
+    const dryRun = uninstaller.removeData({ dryRun: true });
+    ok('uninstall: dry-run deletes nothing', fs.existsSync(path.join(tmpHome, '.jsql')) && dryRun.removed.length === 3);
+
+    const removed = uninstaller.removeData();
+    ok('uninstall: removes data', removed.removed.length === 3 && removed.failed.length === 0);
+    ok('uninstall: .jsql gone', !fs.existsSync(path.join(tmpHome, '.jsql')));
+    ok('uninstall: .jsqlmr gone', !fs.existsSync(path.join(tmpHome, '.jsqlmr')));
+    ok('uninstall: home still exists', fs.existsSync(tmpHome));
+
+    // malicious override must be refused
+    process.env.JSQL_MR_PATH = path.join(uninstaller.packageDir(), 'README.md');
+    const bad = uninstaller.removeData();
+    ok('uninstall: refuses path inside package', bad.failed.length === 1 && fs.existsSync(path.join(uninstaller.packageDir(), 'README.md')));
+  } finally {
+    process.env.HOME = oldHome;
+    if (oldMod === undefined) delete process.env.JSQL_MOD_CONFIG; else process.env.JSQL_MOD_CONFIG = oldMod;
+    if (oldMr === undefined) delete process.env.JSQL_MR_PATH; else process.env.JSQL_MR_PATH = oldMr;
+    if (oldCache === undefined) delete process.env.JSQL_CACHE_DIR; else process.env.JSQL_CACHE_DIR = oldCache;
+    try { fs.rmSync(tmpHome, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+  }
+
+  console.log(`\n=== pass ${pass}  fail ${fail} ===`);
+  process.exit(fail ? 1 : 0);
+})();