jsql-neo 6.5.23 → 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.23** — 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.23 — 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/native_client.js

@@ -1,7 +1,8 @@
 const path = require('path');
 const os = require('os');
 const { executeSQL } = require('./sql');
-const { JSQL_Error, ErrorCodes } = require('./errors');
+const { JSQL_Error, ErrorCodes, createError } = require('./errors');
+const bigintJson = require('./bigint_json');
 const {
   createHookRegistry, applyPlugin, buildPluginContext, registerHook,
   runHooks, getPluginApis
@@ -155,6 +156,69 @@ function assertRowObject(row, index, isBatch) {
   throw new TypeError(`insert(): expected a row object${where}, got ${got}`);
 }
 
+const INT64_MIN = -9223372036854775808n;
+const INT64_MAX = 9223372036854775807n;
+const SAFE_INT_MIN = BigInt(Number.MIN_SAFE_INTEGER);
+const SAFE_INT_MAX = BigInt(Number.MAX_SAFE_INTEGER);
+const DECIMAL_INT_RE = /^[+-]?\d+$/;
+
+function isIntegerType(t) {
+  return t === 'integer' || t === 'int' || t === 'bigint';
+}
+
+/** 与 lib/table.js 的 normalizeInteger 一致（Issue #38）。 */
+function normalizeInteger(v, type) {
+  let b;
+  if (typeof v === 'bigint') b = v;
+  else {
+    try { b = BigInt(String(v).trim()); } catch (_) { throw createError('ER_TRUNCATED_WRONG_VALUE', type, v); }
+  }
+  if (b < INT64_MIN || b > INT64_MAX) throw createError('ER_TRUNCATED_WRONG_VALUE', type, b.toString());
+  return (b >= SAFE_INT_MIN && b <= SAFE_INT_MAX) ? Number(b) : b;
+}
+
+/** Rust 绑定层把 >2^53 的整数以十进制字符串返回，这里还原为 BigInt。 */
+function restoreInteger(v) {
+  if (typeof v === 'bigint') return v;
+  if (typeof v === 'string' && DECIMAL_INT_RE.test(v)) {
+    const b = BigInt(v);
+    return (b >= SAFE_INT_MIN && b <= SAFE_INT_MAX) ? Number(b) : b;
+  }
+  if (typeof v === 'number' && Number.isInteger(v) && !Number.isSafeInteger(v)) return BigInt(v);
+  return v;
+}
+
+function normalizeIntegerInput(v, type) {
+  if (typeof v === 'bigint') return normalizeInteger(v, type);
+  if (typeof v === 'number') {
+    if (!Number.isInteger(v) || !Number.isSafeInteger(v)) throw createError('ER_TRUNCATED_WRONG_VALUE', type, v);
+    return v;
+  }
+  if (typeof v === 'string' && DECIMAL_INT_RE.test(v.trim())) return normalizeInteger(v.trim(), type);
+  throw createError('ER_TRUNCATED_WRONG_VALUE', type, v);
+}
+
+/** 按 schema 做插入/更新前的值归一（JSON 列序列化、整数列精确化）。 */
+function normalizeRowForRust(table, schema, row) {
+  const out = {};
+  for (const [k, v] of Object.entries(row)) {
+    const def = schema[k];
+    let t = null;
+    if (typeof def === 'string') t = def.toLowerCase();
+    else if (def && typeof def === 'object' && def.type) t = String(def.type).toLowerCase();
+    if (v !== null && v !== undefined && ['json', 'array', 'object'].includes(t) && typeof v !== 'string') {
+      out[k] = safeStringify(v, table, k);
+    } else if (v !== null && v !== undefined && isIntegerType(t)) {
+      out[k] = normalizeIntegerInput(v, t);
+    } else if (v instanceof Date) {
+      out[k] = v.toISOString();
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
 const NATIVE_TYPE_MAP = {
   text: 'string',
   varchar: 'string',
@@ -169,7 +233,7 @@ const NATIVE_TYPE_MAP = {
   array: 'string',
   object: 'string',
   bool: 'boolean',
-  bigint: 'string',
+  bigint: 'bigint',
   int: 'integer',
 };
 
@@ -260,9 +324,9 @@ function restoreRow(row, schema) {
     if (typeof colDef === 'string') t = colDef.toLowerCase();
     else if (colDef && typeof colDef === 'object' && colDef.type) t = String(colDef.type).toLowerCase();
     if (['json', 'array', 'object'].includes(t) && typeof value === 'string') {
-      try { out[field] = JSON.parse(value); } catch (e) { out[field] = value; }
-    } else if ((t === 'integer' || t === 'int' || t === 'bigint') && typeof value === 'string' && /^-?\d+$/.test(value)) {
-      out[field] = Number(value);
+      try { out[field] = bigintJson.parse(value); } catch (e) { out[field] = value; }
+    } else if (isIntegerType(t)) {
+      out[field] = restoreInteger(value);
     } else if ((t === 'float' || t === 'double' || t === 'number') && typeof value === 'string' && !Number.isNaN(Number(value))) {
       out[field] = Number(value);
     } else {
@@ -274,6 +338,7 @@ function restoreRow(row, schema) {
 
 function _encodedFieldSize(v) {
   if (v === null || v === undefined) return 1;
+  if (typeof v === 'bigint') return 1 + 8;
   if (typeof v === 'number') {
     if (Number.isInteger(v)) return (v >= -2147483648 && v <= 2147483647) ? 1 + 4 : 1 + 8;
     return 1 + 8;
@@ -287,6 +352,9 @@ function encodeField(buf, off, v) {
   if (v === null || v === undefined) {
     buf.writeUInt8(0, off); return off + 1;
   }
+  if (typeof v === 'bigint') {
+    buf.writeUInt8(INT64_TAG, off); buf.writeBigInt64LE(v, off + 1); return off + 9;
+  }
   if (typeof v === 'number') {
     if (Number.isInteger(v)) {
       if (v >= -2147483648 && v <= 2147483647) {
@@ -554,7 +622,9 @@ class JSQL {
     let t = null;
     if (typeof def === 'string') t = def.trim().split(/\s+/)[0].toLowerCase();
     else if (def && typeof def === 'object' && def.type) t = String(def.type).toLowerCase();
-    if (['integer', 'int', 'bigint'].includes(t)) return Number(id);
+    if (isIntegerType(t)) {
+      try { return normalizeIntegerInput(id, t); } catch (_) { return id; }
+    }
     return id;
   }
 
@@ -578,7 +648,7 @@ class JSQL {
     if (pk) {
       if (this._isAutoIntPk(table)) {
         const n = toNonNeg('id', id, NaN);
-        if (Number.isFinite(n)) {
+        if (typeof id !== 'bigint' && Number.isSafeInteger(n)) {
           // 负 id 会被原生层 `i64 -> u64` 静默回绕成 usize::MAX，导致
           // findById 误报 not found（行明明存在却取不到）。在此显式拒绝。
           if (n < 0) throw new Error('id must be a non-negative number');
@@ -589,7 +659,7 @@ class JSQL {
       }
       const filter = {};
       filter[pk] = this._coercePkId(table, id);
-      const r = safeParse(this._n('jsqlFind', table, JSON.stringify(filter), 1, 0));
+      const r = safeParse(this._n('jsqlFind', table, bigintJson.stringify(filter), 1, 0));
       if (r && r.error) return r;
       return Array.isArray(r) && r.length > 0 ? r[0] : null;
     }
@@ -601,7 +671,7 @@ class JSQL {
     if (pk) {
       if (this._isAutoIntPk(table)) {
         const n = toNonNeg('id', id, NaN);
-        if (Number.isFinite(n)) {
+        if (typeof id !== 'bigint' && Number.isSafeInteger(n)) {
           // 负 id 在原生层回绕为 usize::MAX 后静默 not found，update/remove
           // 会无提示地什么都不做 —— 这里显式拒绝（见 issue #35）。
           if (n < 0) throw new Error('id must be a non-negative number');
@@ -612,7 +682,7 @@ class JSQL {
       }
       const filter = {};
       filter[pk] = this._coercePkId(table, id);
-      const r = safeParse(this._n('jsqlFind', table, JSON.stringify(filter), 1, 0));
+      const r = safeParse(this._n('jsqlFind', table, bigintJson.stringify(filter), 1, 0));
       if (Array.isArray(r) && r.length > 0) return r[0].id;
       return null;
     }
@@ -639,23 +709,7 @@ class JSQL {
     const schema = this._schemas[table];
     // 对 JSON/array/object 列保留 safeStringify 以给出可读错误（环形对象等）
     if (schema) {
-      rows = rows.map(row => {
-        const out = {};
-        for (const [k, v] of Object.entries(row)) {
-          const def = schema[k];
-          let t = null;
-          if (typeof def === 'string') t = def.toLowerCase();
-          else if (def && typeof def === 'object' && def.type) t = String(def.type).toLowerCase();
-          if (v !== null && v !== undefined && ['json', 'array', 'object'].includes(t) && typeof v !== 'string') {
-            out[k] = safeStringify(v, table, k);
-          } else if (v instanceof Date) {
-            out[k] = v.toISOString();
-          } else {
-            out[k] = v;
-          }
-        }
-        return out;
-      });
+      rows = rows.map(row => normalizeRowForRust(table, schema, row));
     }
     // 批量插入优先走二进制格式：整批只在 JS 侧 encode 一次，Rust 直接按
     // tag 解析成 FieldValue，省掉「JS JSON.stringify → Rust serde 解析 →
@@ -666,7 +720,7 @@ class JSQL {
     if (typeof native.jsqlInsertBuf === 'function' && _canEncodeBatch(rows)) {
       r = safeParse(this._n('jsqlInsertBuf', table, encodeBatch(rows)));
     } else if (typeof native.jsqlInsertRaw === 'function') {
-      r = safeParse(this._n('jsqlInsertRaw', table, JSON.stringify(rows)));
+      r = safeParse(this._n('jsqlInsertRaw', table, bigintJson.stringify(rows)));
     } else {
       r = safeParse(this._n('jsqlInsertBuf', table, encodeBatch(rows)));
     }
@@ -704,7 +758,7 @@ class JSQL {
     for (var table in update) {
       var entries = update[table];
       if (entries.length === 0) continue;
-      var r = safeParse(this._n('jsqlUpdateByIds', table, JSON.stringify(entries)));
+      var r = safeParse(this._n('jsqlUpdateByIds', table, bigintJson.stringify(entries)));
       this._emit('update', { table, entries, result: r });
     }
     this._opBuffer = { remove: {}, update: {} };
@@ -844,7 +898,7 @@ class JSQL {
     this._flushOpsNow();
     if (!(await this._runHooks('beforeFind', [table, { ids }]))) return null;
     let r;
-    if (this._isAutoIntPk(table) && ids.every(id => Number.isFinite(Number(id)))) {
+    if (this._isAutoIntPk(table) && ids.every(id => typeof id !== 'bigint' && Number.isSafeInteger(Number(id)))) {
       // 自增主键：内部 id 即主键值，一次批量调用即可，避免 N 次往返。
       // #35：负 id 在原生层 `i64 -> u64` 回绕成 usize::MAX，静默 not found；
       // NaN/Infinity 同样不允许。绑定层先校验，绝不把非法值传给原生模块。
@@ -869,7 +923,7 @@ class JSQL {
   async find(table, filter, opts = {}) {
     this._flushOpsNow();
     if (!(await this._runHooks('beforeFind', [table, { filter, opts }]))) return [];
-    const filterStr = filter ? JSON.stringify(filter) : '';
+    const filterStr = filter ? bigintJson.stringify(filter) : '';
     const { limit = 100, offset = 0 } = opts;
     // #35：原生层把 limit/offset 按 `as usize` 无符号转换，负数会静默回绕
     // （release 下空结果 / debug 下 usize::MAX+1 溢出 panic）。绑定层先校验，
@@ -894,10 +948,11 @@ class JSQL {
   }
 
   async updateByIds(table, entries) {
+    const schema = this._schemas[table];
     const pairs = [];
     for (const [id, data] of entries) {
       const seq = this._seqIdByPk(table, id);
-      if (seq !== null) pairs.push([seq, data]);
+      if (seq !== null) pairs.push([seq, schema ? normalizeRowForRust(table, schema, data) : data]);
     }
     if (!(await this._runHooks('beforeUpdate', [table, pairs]))) return;
     if (!this._opBuffer.update[table]) this._opBuffer.update[table] = [];
@@ -922,8 +977,10 @@ class JSQL {
     // 改主键 / UNIQUE 列前先查冲突（同步版，与 lib/database.js 的修复对齐）。
     // 此前直接写入，导致 UPDATE t SET id = 1 WHERE id = 2 静默产生两行同主键。
     this._assertNoKeyConflictSync(table, id, data);
+    const schema = this._schemas[table];
+    const payload = schema ? normalizeRowForRust(table, schema, data) : data;
     if (!this._opBuffer.update[table]) this._opBuffer.update[table] = [];
-    this._opBuffer.update[table].push([seq, data]);
+    this._opBuffer.update[table].push([seq, payload]);
     this._scheduleOpFlush();
   }
 
@@ -953,7 +1010,7 @@ class JSQL {
       if (valOf(self, f) === nv) continue;                            // 值没变
       // 只需知道「是否还存在另一行占用了这个键值」：limit 2 让原生层命中即停，
       // 输出量恒定，不随表规模增长。
-      const probe = safeParse(this._n('jsqlFind', table, JSON.stringify({ [f]: nv }), 2, 0));
+      const probe = safeParse(this._n('jsqlFind', table, bigintJson.stringify({ [f]: nv }), 2, 0));
       if (!Array.isArray(probe)) continue;
       if (probe.some(r => String(idOf(r)) !== String(id))) {
         const e = new Error(`Duplicate entry '${nv}' for key '${f}'`);

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,
+};