jsql-neo 6.5.1-beta.2 → 6.5.3

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.1-beta.2** — pre-release build · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.3** — 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)
@@ -38,16 +38,17 @@ npm install jsql-neo
 
 **JSQL-NEO** is a Rust-powered embedded database with **zero runtime dependencies**. It runs in Node.js, CLI, Web UI, and the browser (WASM).
 
-- **MySQL wire protocol, ready to use** — `jsql serve` starts it; `mysql2` / most MySQL clients connect directly
+- **Four wire protocols on one port** — `jsql serve` accepts MySQL, PostgreSQL, MongoDB and Redis clients; `mysql2`, `pg`, `mongodb` and `ioredis` connect directly
 - **Zero dependencies** — no native libs to compile, no system deps to install
 - **Three engines, same API** — `native` (Rust N-API), `wasm` (same Rust core), `js` (pure JS)
 - **~2× faster than better-sqlite3** on indexed point lookups
 
-> **About the other wire protocols** — PostgreSQL, MongoDB and Redis protocol stacks
-> ship as libraries (`lib/pg_server`, `lib/mongo_server`, `lib/redis_server`) and each
-> listens on its own port; there is **no single-port multi-protocol mode**, and the CLI
-> exposes no entry point for them. MongoDB additionally does not yet complete a
-> handshake with the modern official `mongodb` driver. Treat them as experimental.
+> **Wire protocols** — MySQL, PostgreSQL, MongoDB and Redis share a single listener
+> (`jsql serve`, default port 3306). The server sniffs the first packet of each
+> connection and hands it to the matching protocol handler. MySQL / PostgreSQL /
+> MongoDB read the same `Database` engine (same tables), Redis keeps its own key
+> namespace. Verified with `mysql2`, `pg`, `mongodb` (driver 7.x) and `ioredis`;
+> pass `--mysql-only` to serve the MySQL protocol alone.
 
 ---
 
@@ -100,13 +101,23 @@ db.stop();
 jsql serve --port 3306 --data-dir ./data
 ```
 
+All four protocols share the same port:
+
 ```bash
-# MySQL clients (mysql CLI, mysql2, DBeaver, DataGrip …) connect here
-mysql -h 127.0.0.1 -P 3306
+# MySQL clients (mysql CLI, mysql2, DBeaver, DataGrip …)
+mysql -h 127.0.0.1 -P 3306 -u root
+
+# PostgreSQL clients (psql, pg, pgAdmin …)
+psql "host=127.0.0.1 port=3306 user=postgres dbname=app"
+
+# MongoDB clients (mongosh, mongodb driver, Compass …)
+mongosh "mongodb://127.0.0.1:3306/app?directConnection=true"
+
+# Redis clients (redis-cli, ioredis …)
+redis-cli -h 127.0.0.1 -p 3306 PING
 ```
 
-Only MySQL is served by the CLI today. The PostgreSQL / Redis / MongoDB stacks are
-available as libraries — see the note near the top of this file.
+Pass `--mysql-only` to serve the MySQL wire protocol alone.
 
 ### Browser / WASM
 

package/bin/jsql

@@ -8,7 +8,9 @@ const migrate = require('../lib/migrate');
 const { nag, setStarred, readConfig } = require('../lib/star-nag');
 
 // star 提示：任何异常都不该挡住命令本身
-if (!process.env.JSQL_NO_STAR_NAG && process.argv[2] !== 'star') {
+// version / --version 只回版本号、star 本身就是干这件事的 —— 这些不提示，其余全部提示
+const NO_NAG_ARGS = new Set(['version', '--version', '-v', 'star']);
+if (!process.env.JSQL_NO_STAR_NAG && !NO_NAG_ARGS.has(process.argv[2])) {
   try { nag(); } catch (e) { /* 提示失败与命令无关 */ }
 }
 
@@ -154,14 +156,14 @@ const cli = yaggs({ pkg: require('../package.json') })
       }
     } catch (e) { fail(e); }
   })
-  .command('serve', 'Run the MySQL-compatible server in the foreground', (sub) => {
+  .command('serve', 'Run the multi-protocol server (MySQL / PostgreSQL / MongoDB / Redis on one port)', (sub) => {
     sub.option('port', { alias: ['p'], type: 'number', description: 'Listen port (default 3306)' });
     sub.option('host', { type: 'string', description: 'Listen host (default 127.0.0.1)' });
     sub.option('data-dir', { type: 'string', description: 'Directory to store databases' });
     sub.option('no-auth', { type: 'boolean', description: 'Allow connections without authentication' });
     sub.option('log', { type: 'boolean', description: 'Log queries to stdout' });
+    sub.option('mysql-only', { type: 'boolean', description: 'Serve the MySQL wire protocol only' });
   }, async (argv) => {
-    const { createMysqlServer } = require('../lib/mysql_server');
     const options = {
       port: argv.port != null ? argv.port : 3306,
       host: argv.host || '127.0.0.1',
@@ -169,9 +171,27 @@ const cli = yaggs({ pkg: require('../package.json') })
       noAuth: argv['no-auth'] === true,
     };
     if (argv.log) options.onQuery = (q) => console.log('[sql]', q);
-    const srv = createMysqlServer(options);
-    srv.listen();
-    console.log(`jsql-neo MySQL server on ${options.host}:${options.port}${options.dataDir ? ' (data: ' + options.dataDir + ')' : ' (in-memory)'}`);
+    options.onError = (err) => {
+      console.error(`serve failed: ${err.message}`);
+      process.exit(1);
+    };
+    const mysqlOnly = argv['mysql-only'] === true;
+    if (mysqlOnly) {
+      const { createMysqlServer } = require('../lib/mysql_server');
+      const srv = createMysqlServer(options);
+      srv.listen();
+      console.log(`jsql-neo MySQL server on ${options.host}:${options.port}${options.dataDir ? ' (data: ' + options.dataDir + ')' : ' (in-memory)'}`);
+    } else {
+      const { createMultiServer } = require('../lib/multiserver');
+      const srv = createMultiServer(options);
+      srv.listen(() => {
+        console.log(`jsql-neo multi-protocol server on ${options.host}:${options.port}${options.dataDir ? ' (data: ' + options.dataDir + ')' : ' (in-memory)'}`);
+        console.log('  MySQL / PostgreSQL / MongoDB / Redis — one port, shared data');
+      });
+      const shutdown = () => srv.close(() => process.exit(0));
+      process.once('SIGINT', shutdown);
+      process.once('SIGTERM', shutdown);
+    }
     setInterval(() => {}, 1 << 30);
   })
   .command('star', 'Confirm whether you starred this repo (opens browser once)', (sub) => {
@@ -189,7 +209,32 @@ const cli = yaggs({ pkg: require('../package.json') })
     const nonceUrl = sn.startOauthCheck();     // 打开浏览器 + 后台轮询写回 ~/.jsqlmr
     if (!process.stdout.isTTY) console.log('  ' + nonceUrl);
     console.log('After you authorize, this config is updated: ' + sn.configPath());
-    console.log('Run `jsql star` again afterwards to see the result.');
+    console.log('Waiting for authorization (up to 3 minutes)…');
+    // startOauthCheck 的定时器是 unref 的，命令必须自己前台等，否则接不到结果
+    const res = sn.waitForResult(nonceUrl, 180000);
+    const status = res && res.status;
+    if (status === 'starred') {
+      sn.setStarred(true);
+      console.log(`Confirmed: ${res.login} has starred ${res.repo}. Thanks!`);
+      return;
+    }
+    if (status === 'not-starred') {
+      console.log(`Authorization finished, but ${res.login} has not starred ${res.repo} yet.`);
+      console.log(`Star it at ${sn.URL} then run \`jsql star\` again.`);
+      return;
+    }
+    if (status === 'denied' || status === 'error') {
+      // 这不是「没 star」，是授权本身没走通（code 过期、链接被重复打开、被拒绝）。
+      // 老实现这里会把 login/repo 打印成 undefined，并让用户去 star —— 误导。
+      console.log(`Authorization ${status === 'denied' ? 'was declined' : 'failed'}: ${res.error || 'unknown reason'}`);
+      console.log('The link is single-use. Run `jsql star` again to get a fresh one.');
+      return;
+    }
+    if (status === 'expired') {
+      console.log('The link expired. Run `jsql star` again to retry.');
+      return;
+    }
+    console.log('Timed out. Run `jsql star` again to retry.');
   })
   .command('bench', 'Insert + query benchmark against a data directory', (sub) => {
     sub.option('n', { type: 'number', description: 'Number of rows (default 10000)' });

package/index.js

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

package/lib/mongo_server.js

@@ -155,20 +155,28 @@ class MongoServer {
     this._server = null;
     this._sockets = new Set();
     this._dbCollections = new Map(); // db name → Set of collection names
+    this._engineByDb = new Map();    // db name → Database (standalone 模式)
   }
 
-  async _getEngine() {
+  async _getEngine(db = null) {
+    if (this._engineByDb && db) {
+      if (!this._engineByDb.has(db)) this._engineByDb.set(db, this._createEngine(db));
+      return this._engineByDb.get(db);
+    }
     if (this._engine) return this._engine;
+    this._engine = this._createEngine(null);
+    return this._engine;
+  }
+
+  _createEngine(db) {
     if (this.dataDir && this.dataDir !== ':memory:') {
-      this._engine = new Database(path.join(this.dataDir, 'default'), { autoSave: true });
-    } else {
-      this._engine = new Database(':memory:', { autoSave: false });
+      return new Database(path.join(this.dataDir, db || 'default'), { autoSave: true });
     }
-    return this._engine;
+    return new Database(':memory:', { autoSave: false });
   }
 
   async _ensureCollection(name, db = null) {
-    const engine = await this._getEngine();
+    const engine = await this._getEngine(db);
     if (!engine.getTableSchema(name)) {
       engine.createTable(name, {});
     }
@@ -190,25 +198,35 @@ class MongoServer {
     socket.on('close', () => this._sockets.delete(socket));
     let buf = Buffer.isBuffer(existing) ? Buffer.from(existing) : Buffer.alloc(0);
     socket.on('error', () => {});
+    let processing = false;
+    let again = false;
     const processLoop = async () => {
-      for (;;) {
-        if (buf.length < 4) break;
-        const len = buf.readInt32LE(0);
-        if (len < 16 || buf.length < len) break;
-        const msg = buf.slice(0, len);
-        buf = buf.slice(len);
-        try {
-          await this._handleMessage(socket, msg);
-        } catch (e) {
-          try { socket.write(this._wrapMsg(bsonDocument({ ok: 0, errmsg: e.message || String(e) }), this._reqId(msg))); } catch (_) {}
+      if (processing) { again = true; return; }
+      processing = true;
+      try {
+        for (;;) {
+          if (buf.length < 4) break;
+          const len = buf.readInt32LE(0);
+          if (len < 16 || len > 48 * 1024 * 1024) break;
+          if (buf.length < len) break;
+          const msg = buf.slice(0, len);
+          buf = buf.slice(len);
+          try {
+            await this._handleMessage(socket, msg);
+          } catch (e) {
+            try { socket.write(this._wrapMsg(bsonDocument({ ok: 0, errmsg: e.message || String(e) }), this._reqId(msg))); } catch (_) {}
+          }
         }
+      } finally {
+        processing = false;
+        if (again) { again = false; processLoop(); }
       }
     };
-    socket.on('data', async (chunk) => {
+    socket.on('data', (chunk) => {
       buf = Buffer.concat([buf, chunk]);
-      await process();
+      processLoop();
     });
-    if (buf.length > 0) process();
+    if (buf.length > 0) processLoop();
   }
 
   _reqId(msg) {
@@ -272,13 +290,45 @@ class MongoServer {
       socket.write(this._wrapMsg(bsonDocument({ ok: 0, errmsg: `opCode ${op2} not supported` }), this._reqId(msg)));
       return;
     }
+    const flags = msg.readInt32LE(16);
+    const msgEnd = (flags & 1) ? msg.length - 4 : msg.length; // checksumPresent
     let pos = 16 + 4; // header + flagBits
-    const kind = msg[pos]; pos++; // section kind: 0 = single BSON doc
-    if (kind !== 0) {
-      socket.write(this._wrapMsg(bsonDocument({ ok: 0, errmsg: `section kind ${kind} not supported` }), this._reqId(msg)));
+    const body = {};
+    let sawBody = false;
+    while (pos < msgEnd) {
+      const kind = msg[pos++];
+      if (kind === 0) {
+        const r = bsonReadDocument(msg, pos);
+        Object.assign(body, r.value);
+        pos = r.pos;
+        sawBody = true;
+      } else if (kind === 1) {
+        // Document sequence: int32 size, cstring identifier, BSON docs
+        const size = msg.readInt32LE(pos);
+        const end = pos + size;
+        if (size < 5 || end > msgEnd) throw new Error('malformed document sequence');
+        let p = pos + 4;
+        const nameEnd = msg.indexOf(0, p);
+        if (nameEnd < 0 || nameEnd >= end) throw new Error('malformed document sequence identifier');
+        const ident = msg.toString('utf8', p, nameEnd);
+        p = nameEnd + 1;
+        const seq = [];
+        while (p < end) {
+          const r = bsonReadDocument(msg, p);
+          seq.push(r.value);
+          p = r.pos;
+        }
+        body[ident] = seq;
+        pos = end;
+      } else {
+        socket.write(this._wrapMsg(bsonDocument({ ok: 0, errmsg: `section kind ${kind} not supported` }), this._reqId(msg)));
+        return;
+      }
+    }
+    if (!sawBody) {
+      socket.write(this._wrapMsg(bsonDocument({ ok: 0, errmsg: 'missing OP_MSG body section' }), this._reqId(msg)));
       return;
     }
-    const body = bsonReadDocument(msg, pos).value;
     const command = this._commandName(body);
     const reply = await this._dispatch(command, body);
     socket.write(this._wrapMsg(bsonDocument(reply), this._reqId(msg)));
@@ -332,13 +382,13 @@ class MongoServer {
       case 'endSessions': return { ok: 1 };
       case 'listDatabases': {
         // P3-17: listDatabases 只返回当前库——返回所有数据库
-        const engine = await this._getEngine();
+        const engine = await this._getEngine(this._dbOf(doc));
         const dbs = Object.keys(engine._meta && engine._meta.databases ? engine._meta.databases : { [this._dbOf(doc)]: 1 });
         const databases = Object.keys(dbs).map(name => ({ name, sizeOnDisk: 1, empty: false }));
         return { ok: 1, databases, totalSize: databases.length };
       }
       case 'listCollections': {
-        const engine = await this._getEngine();
+        const engine = await this._getEngine(this._dbOf(doc));
         const tables = Object.keys(engine._meta && engine._meta.tables ? engine._meta.tables : (engine._tables || {}));
         const firstBatch = tables.map((t) => ({ name: t, type: 'collection', options: {}, info: { readOnly: false, uuid: '' } }));
         return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.$cmd.listCollections`, firstBatch } };
@@ -349,7 +399,7 @@ class MongoServer {
       }
       case 'drop': {
         try {
-          const engine = await this._getEngine();
+          const engine = await this._getEngine(this._dbOf(doc));
           engine.dropTable(String(doc.drop));
           return { ok: 1, ns: `${this._dbOf(doc)}.${doc.drop}` };
         } catch (e) {
@@ -365,10 +415,11 @@ class MongoServer {
           const doc2 = { ...d };
           // 检查 _id 唯一性
           if (doc2._id !== undefined) {
-            const existing = engine.find(coll, { _id: doc2._id });
+            const existing = await engine.find(coll, { _id: doc2._id });
             if (existing.length > 0) continue; // 跳过重复 _id
           }
-          ids.push(engine.insert(coll, doc2));
+          await engine.insert(coll, doc2);
+          ids.push(doc2._id);
         }
         return { ok: 1, n: ids.length };
       }
@@ -376,23 +427,23 @@ class MongoServer {
         const coll = String(doc.findAndModify);
         const engine = await this._ensureCollection(coll, this._dbOf(doc));
         const q = doc.query || {};
-        const rows = this._matching(engine, coll, q);
+        const rows = await this._matching(engine, coll, q);
         const found = rows[0] || null;
         const set = doc.update && doc.update.$set ? doc.update.$set : (doc.update || {});
         let value = null;
         if (found) {
           if (doc.remove) {
-            this._removeRows(engine, coll, [found]);
+            await this._removeRows(engine, coll, [found]);
             value = found;
           } else {
             const patched = { ...found, ...set };
-            this._patchRows(engine, coll, [found], set);
+            await this._patchRows(engine, coll, [found], set);
             value = doc.new ? patched : found;
           }
         } else if (doc.upsert) {
           const merged = { ...q, ...set };
-          const id = engine.insert(coll, merged);
-          value = doc.new ? { ...merged, _id: id } : null;
+          await engine.insert(coll, merged);
+          value = doc.new ? { ...merged } : null;
         }
         return { ok: 1, value, lastErrorObject: { n: found ? 1 : (doc.upsert ? 1 : 0), updatedExisting: !!found && !doc.remove } };
       }
@@ -400,7 +451,7 @@ class MongoServer {
         const coll = String(doc.distinct);
         const engine = await this._ensureCollection(coll, this._dbOf(doc));
         const key = String(doc.key || '');
-        const rows = this._matching(engine, coll, doc.query);
+        const rows = await this._matching(engine, coll, doc.query);
         const seen = new Set();
         const values = [];
         for (const r of rows) {
@@ -411,7 +462,7 @@ class MongoServer {
       }
       case 'dropDatabase': {
         const dbName = String(doc.$db || 'test');
-        const engine = await this._getEngine();
+        const engine = await this._getEngine(dbName);
         const colls = this._dbCollections.get(dbName);
         if (colls) {
           for (const c of colls) {
@@ -424,7 +475,7 @@ class MongoServer {
       case 'find': {
         const coll = String(doc.find);
         const engine = await this._ensureCollection(coll, this._dbOf(doc));
-        let rows = this._matching(engine, coll, doc.filter);
+        let rows = await this._matching(engine, coll, doc.filter);
         const skip = typeof doc.skip === 'number' ? doc.skip : 0;
         if (skip > 0) rows = rows.slice(skip);
         const limit = typeof doc.limit === 'number' ? doc.limit : 0;
@@ -442,24 +493,24 @@ class MongoServer {
           const q = u.q || {};
           const set = u.u && u.u.$set ? u.u.$set : (u.u || {});
           const multi = u.multi === true;
-          let targets = this._matching(engine, coll, q);
+          let targets = await this._matching(engine, coll, q);
           if (!targets.length && u.upsert) {
             const merged = { ...q, ...set };
-            engine.insert(coll, merged);
+            await engine.insert(coll, merged);
             n++;
             continue;
           }
           if (multi) {
             // 更新所有匹配的行
             for (const target of targets) {
-              this._patchRows(engine, coll, [target], u.u || { $set: set });
+              await this._patchRows(engine, coll, [target], u.u || { $set: set });
               n++;
             }
           } else {
             // 只更新第一条
             let target = targets[0] || null;
             if (target) {
-              this._patchRows(engine, coll, [target], u.u || { $set: set });
+              await this._patchRows(engine, coll, [target], u.u || { $set: set });
               n++;
             }
           }
@@ -471,10 +522,10 @@ class MongoServer {
         const engine = await this._ensureCollection(coll, this._dbOf(doc));
         let n = 0;
         for (const d of (doc.deletes || [])) {
-          const rows = this._matching(engine, coll, d.q || {});
+          const rows = await this._matching(engine, coll, d.q || {});
           // MongoDB delete: limit=1 means delete only one, limit=0 means delete all
           const toDelete = d.limit === 1 ? rows.slice(0, 1) : rows;
-          if (toDelete.length > 0) this._removeRows(engine, coll, toDelete);
+          if (toDelete.length > 0) await this._removeRows(engine, coll, toDelete);
           n += toDelete.length;
         }
         return { ok: 1, n };
@@ -482,14 +533,14 @@ class MongoServer {
       case 'count': {
         const coll = String(doc.count);
         const engine = await this._ensureCollection(coll, this._dbOf(doc));
-        const rows = this._matching(engine, coll, doc.query);
+        const rows = await this._matching(engine, coll, doc.query);
         return { ok: 1, n: Number(doc.limit) > 0 ? Math.min(rows.length, doc.limit) : rows.length };
       }
       case 'aggregate': {
         const coll = String(doc.aggregate);
         const engine = await this._ensureCollection(coll, this._dbOf(doc));
         const pipeline = doc.pipeline || [];
-        let rows = engine.find(coll, {});
+        let rows = await engine.find(coll, {});
         for (const stage of pipeline) {
           if (stage.$match) rows = rows.filter((r) => this._match(r, stage.$match));
           else if (stage.$count) rows = [{ [stage.$count]: rows.length }];
@@ -613,11 +664,19 @@ class MongoServer {
     return row._id != null ? row._id : row.id;
   }
 
-  _matching(engine, coll, filter) {
-    return engine.find(coll, {}).filter((r) => this._match(r, filter || {}));
+  async _matching(engine, coll, filter) {
+    const rows = await engine.find(coll, {});
+    return rows.filter((r) => this._match(r, filter || {}));
+  }
+
+  _rowKey(engine, coll, row) {
+    const table = engine._tables && engine._tables[coll];
+    const pk = table && (table._primaryKey || table._autoIncrementField);
+    // 有主键用主键值；Mongo 自建集合没有主键，传行对象走深度匹配
+    return pk ? row[pk] : { ...row };
   }
 
-  _patchRows(engine, coll, rows, updateDoc) {
+  async _patchRows(engine, coll, rows, updateDoc) {
     const entries = [];
     // 检查是否有更新操作符
     const operators = ['$inc', '$unset', '$push', '$set'];
@@ -626,14 +685,14 @@ class MongoServer {
     if (!hasOperators) {
       // 没有操作符，直接 set
       for (const r of rows) {
-        const id = this._idOf(r);
-        if (id !== undefined) entries.push([id, { ...updateDoc }]);
+        const key = this._rowKey(engine, coll, r);
+        if (key !== undefined) entries.push([key, { ...updateDoc }]);
       }
     } else {
       // 有操作符，需要特殊处理
       for (const r of rows) {
-        const id = this._idOf(r);
-        if (id === undefined) continue;
+        const key = this._rowKey(engine, coll, r);
+        if (key === undefined) continue;
         const update = {};
         if (updateDoc.$set) Object.assign(update, updateDoc.$set);
         if (updateDoc.$inc) {
@@ -654,21 +713,21 @@ class MongoServer {
             update[field] = null;
           }
         }
-        if (Object.keys(update).length > 0) entries.push([id, update]);
+        if (Object.keys(update).length > 0) entries.push([key, update]);
       }
     }
-    if (entries.length > 0) engine.updateByIds(coll, entries);
+    if (entries.length > 0) await engine.updateByIds(coll, entries);
   }
 
-  _removeRows(engine, coll, rows) {
+  async _removeRows(engine, coll, rows) {
     // 收集所有需要删除的行的 id，走 engine.removeByIds
     // 这样会写 WAL、触发 hooks、检查约束
     const ids = [];
     for (const r of rows) {
-      const id = this._idOf(r);
-      if (id !== undefined) ids.push(id);
+      const key = this._rowKey(engine, coll, r);
+      if (key !== undefined) ids.push(key);
     }
-    if (ids.length > 0) engine.removeByIds(coll, ids);
+    if (ids.length > 0) await engine.removeByIds(coll, ids);
   }
 
   _match(row, filter) {
@@ -729,7 +788,11 @@ class MongoServer {
       if (this._server) { this._server.close(cb || (() => {})); this._server = null; }
       else if (cb) cb();
     };
-    if (this._engine && typeof this._engine.stop === 'function') this._engine.stop().then(done).catch(done);
+    const engines = new Set(this._engineByDb ? this._engineByDb.values() : []);
+    if (this._engine) engines.add(this._engine);
+    const stops = [];
+    for (const e of engines) if (e && typeof e.stop === 'function') stops.push(e.stop());
+    if (stops.length > 0) Promise.allSettled(stops).then(done).catch(done);
     else done();
     return this;
   }

package/lib/multiserver.js

@@ -42,6 +42,10 @@ class MultiServer {
     this.port = options.port ?? 5432;
     this.host = options.host || '127.0.0.1';
     this.dataDir = options.dataDir || null;
+    // 静默连接的兜底协议：MySQL 客户端等待服务器先发握手包，
+    // 而空闲的 Redis 连接也不主动发包，只能按配置的二选一处理。
+    this.idleProtocol = options.idleProtocol || 'mysql';
+    this.sniffTimeout = options.sniffTimeout != null ? options.sniffTimeout : 200;
     // 共享 SQL 引擎：三种 SQL 协议读写同一份数据
     this._engines = new Map();
     const getEngine = async (dbName) => {
@@ -72,13 +76,17 @@ class MultiServer {
   listen(cb) {
     this._server = net.createServer((socket) => {
       this._sockets.add(socket);
+      socket.on('error', () => {});
       socket.on('close', () => this._sockets.delete(socket));
       let first = Buffer.alloc(0);
       let routed = false;
-      // MySQL 客户端会先等服务器握手包，不主动发字节；超时后按 MySQL 处理
+      // MySQL 客户端会先等服务器握手包，不主动发字节；超时后按 idleProtocol 处理
       const t = setTimeout(() => {
-        if (!routed) { routed = true; socket.removeListener('data', sniff); this._route(socket, first); }
-      }, 200);
+        if (routed) return;
+        routed = true;
+        socket.removeListener('data', sniff);
+        try { this._route(socket, first); } catch (e) { socket.destroy(); }
+      }, this.sniffTimeout);
       t.unref();
       const sniff = (chunk) => {
         first = Buffer.concat([first, chunk]);
@@ -104,7 +112,7 @@ class MultiServer {
   }
 
   _route(socket, first) {
-    const proto = sniffProtocol(first) || 'mysql'; // 无字节（MySQL 客户端等握手）→ 按 MySQL 处理
+    const proto = sniffProtocol(first) || this.idleProtocol;
     if (proto === 'mysql') {
       const conn = new MysqlConnection(socket, this.mysql);
       conn._onData(first);

package/lib/star-nag.js

@@ -24,7 +24,9 @@ const REPO = 'vexify-org/JSQL-neo';
 const URL = `https://github.com/${REPO}`;
 const NAG_INTERVAL_DAYS = 30;
 
-const AUTH_BASE = process.env.JSQL_AUTH_BASE || 'https://auth.vexify.top/callback';
+const AUTH_BASE = process.env.JSQL_AUTH_BASE || 'https://auth.vexify.top';
+const AUTH_START = AUTH_BASE + '/start.php';
+const AUTH_RESULT = AUTH_BASE + '/result.php';
 
 /**
  * 发起 OAuth 浏览器流并在后台轮询结果。
@@ -33,10 +35,28 @@ const AUTH_BASE = process.env.JSQL_AUTH_BASE || 'https://auth.vexify.top/callbac
  * 拿到结果写进 ~/.jsqlmr（starred: true/false）。
  * 进程提前退出就放弃这一次，下次启动会再提示（30 天节流管频率）。
  */
+// result.php 的合法终态：done / denied / error。
+// 只有终态才写配置——"started" 这一类中间态写进去只会污染 ~/.jsqlmr。
+const TERMINAL_STATES = new Set(['done', 'denied', 'error']);
+
+// 把 result.php 的响应收敛成规范状态。老服务端会把 started 也报成 done，
+// 缺少 starred 字段 —— 一律当未完成处理，让调用方继续等。
+function parseAuthResult(j) {
+  if (!j || typeof j !== 'object') return null;
+  const st = j.state;
+  if (!TERMINAL_STATES.has(st)) return null;
+  const r = j.result || {};
+  if (st === 'done') {
+    if (typeof r.starred !== 'boolean') return null;
+    return { status: r.starred ? 'starred' : 'not-starred', login: r.login, repo: r.repo };
+  }
+  return { status: st, error: r.error || (st === 'denied' ? 'authorization denied' : 'authorization failed') };
+}
+
 function startOauthCheck() {
   const crypto = require('crypto');
   const nonce = crypto.randomBytes(24).toString('base64url');
-  const url = AUTH_BASE + '?action=start&nonce=' + nonce;
+  const url = AUTH_START + '?nonce=' + nonce;
 
   // 开浏览器：三平台各一个命令；失败就只打印链接让人手动点
   const cmd = process.platform === 'win32' ? 'start'
@@ -54,19 +74,20 @@ function startOauthCheck() {
   const t = setInterval(() => {
     if (++tries > 45) { clearInterval(t); return; }
     const { execFile } = require('child_process');
-    execFile('curl', ['-sS', '-m', '5', AUTH_BASE + '?action=result&nonce=' + nonce],
+    execFile('curl', ['-sS', '-m', '5', AUTH_RESULT + '?nonce=' + nonce],
       { timeout: 6000, encoding: 'utf8' }, (err, stdout) => {
         if (err) return;
         let j = null;
         try { j = JSON.parse(stdout); } catch (e) { return; }
-        if (!j || j.state !== 'done' || !j.result) return;
+        const res = parseAuthResult(j);
+        if (!res) return;   // pending / started / 格式不符 —— 继续等
         clearInterval(t);
         const cfg = readConfig();
         cfg.oauthCheckedAt = Date.now();
-        cfg.login = j.result.login || undefined;
-        cfg.starred = !!j.result.starred;
+        cfg.login = res.login || undefined;
+        cfg.starred = res.status === 'starred';
         if (cfg.starred) cfg.starredAt = Date.now();
-        writeConfig(cfg);   // nonce.json 由服务端 TTL 自清理
+        writeConfig(cfg);
       });
   }, 2000);
   t.unref();
@@ -159,35 +180,37 @@ function checkStarred() {
  * @param {boolean} [opts.force] 忽略节流，强制提示一次
  * @returns {boolean} 是否真的打印了
  */
+/**
+ * 在 stdout 上印一行 star 提示。
+ *
+ * 规则（用户明确要求）：
+ *   1. **不强制** —— 只印文字，绝不自动弹浏览器。要确认请用户自己跑 `jsql star`。
+ *   2. **除 `version` 外的每个命令都印**，没有 30 天节流这类「只提醒一次」的设计。
+ *   3. `~/.jsqlmr` 记录是否 star 过 —— `starred: true` 是唯一的闭嘴开关
+ *      （另外 `JSQL_NO_STAR_NAG=1` 可临时静音）。
+ *
+ * @returns {boolean} 是否真的印了
+ */
 function nag(opts = {}) {
   const out = opts.out || process.stdout;
   const cfg = readConfig();
 
+  // 已确认 star 过 → 永久闭嘴。jsqlmr 就是干这个的。
   if (!opts.force && cfg.starred) return false;
 
-  const last = Number(cfg.lastNagAt) || 0;
-  if (!opts.force && last && Date.now() - last < NAG_INTERVAL_DAYS * 86400000) {
-    // 顺便有机会补记 star 状态（不打印）
-    const s = checkStarred();
-    if (s) { cfg.starred = true; writeConfig(cfg); }
-    return false;
-  }
-
-  // 有 token 就先查，省得对已经 star 的人重复啰嗦
+  // 有凭据就先查一下，省得对已经 star 的人反复啰嗦（查不到就当没查，照印）
   const starred = checkStarred();
   if (starred) {
     cfg.starred = true;
     cfg.starredAt = Date.now();
     writeConfig(cfg);
-    return false;                 // 已 star，闭嘴
+    return false;
   }
 
   out.write(`\n  If JSQL-NEO saved you time, a star helps others find it: ${URL}\n`);
-  out.write(`  (set JSQL_NO_STAR_NAG=1 to hide, or run \`jsql star\` to confirm and stop seeing this)\n\n`);
-
-  cfg.lastNagAt = Date.now();
-  writeConfig(cfg);
+  out.write(`  Run \`jsql star\` to confirm and stop seeing this (or set JSQL_NO_STAR_NAG=1 to hide)\n\n`);
 
+  // 只记录「有没有 star」，不再写 lastNagAt —— 没有节流，写它没有意义。
   return true;
 }
 
@@ -200,4 +223,60 @@ function setStarred(v) {
   return cfg.starred;
 }
 
-module.exports = { nag, checkStarred, startOauthCheck, readConfig, setStarred, configPath, REPO, URL };
+/**
+ * 同步阻塞轮询授权结果，直到拿到 done / expired 或超时。
+ *
+ * `jsql star` 用：startOauthCheck 的定时器是 unref 的（不能拖住别的命令），
+ * 所以 star 命令必须自己前台等，否则授权完成后 CLI 早已退出，结果没人接。
+ *
+ * @param {string} startUrl startOauthCheck 返回的 URL（含 nonce）
+ * @param {number} [timeoutMs] 最长等待时间，默认 180 秒
+ * @returns {object|null} result 对象（含 login/starred/repo），超时或失败返回 null
+ */
+/**
+ * 前台等待授权结果（`jsql star` 用）。
+ *
+ * 返回规范化后的结果对象：
+ *   { status: 'starred', login, repo }        已 star
+ *   { status: 'not-starred', login, repo }    授权完成但没 star
+ *   { status: 'denied', error }               用户在 GitHub 拒绝授权
+ *   { status: 'error', error }                回调失败（code 过期/复用等）
+ *   { status: 'expired' }                     链接超龄被清理
+ *   null                                     超时（timeoutMs 内没有终态）
+ *
+ * 老服务端会把 "started" 这类中间态也报成 done 且不带 starred 字段 ——
+ * parseAuthResult 一律判为未完成，继续轮询直到超时，而不是打印一段
+ * login/repo 全为 undefined 的假失败信息。
+ */
+function waitForResult(startUrl, timeoutMs = 180000) {
+  const { execFileSync } = require('child_process');
+  // 注意：本模块顶部有 const URL = 'https://github.com/...' 会遮蔽全局 URL 类，
+  // 必须显式从 url 模块取，否则 new URL(...) 抛 TypeError
+  const { URL: NodeURL } = require('url');
+  let nonce = '';
+  try {
+    nonce = new NodeURL(startUrl).searchParams.get('nonce') || '';
+  } catch (e) {
+    return null;
+  }
+  if (!nonce) return null;
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const out = execFileSync('curl', ['-sS', '-m', '5', AUTH_RESULT + '?nonce=' + nonce],
+        { stdio: ['ignore', 'pipe', 'ignore'], timeout: 8000, encoding: 'utf8' });
+      let j = null;
+      try { j = JSON.parse(out); } catch (e) { j = null; }
+      const res = parseAuthResult(j);
+      if (res) return res;
+      if (j && j.state === 'expired') return { status: 'expired' };
+    } catch (e) {
+      // 网络抖动 / 超时 —— 继续等
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2000);
+  }
+  return null;
+}
+
+module.exports = { nag, checkStarred, startOauthCheck, waitForResult, parseAuthResult, readConfig, setStarred, configPath, REPO, URL };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.5.1-beta.2",
+  "version": "6.5.3",
   "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",
@@ -46,18 +46,20 @@
   ],
   "scripts": {
     "postinstall": "node postinstall.js",
-    "test": "node test/smoke.js && node test/native.test.js && node test/json-functions.test.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/query-opt.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/dml-constraints.test.js",
+    "test": "node test/smoke.js && node test/native.test.js && node test/json-functions.test.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/query-opt.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/dml-constraints.test.js && node test/star-nag.test.js",
     "test:parser": "node test/sql-parser.test.js",
     "test:btree": "node test/btree.test.js",
     "test:native": "node test/native.test.js",
     "test:regress": "node test/regress-5.1.0.js",
-    "test:all": "node test/smoke.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/native.test.js && node test/native-multi-instance.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/wasm.test.js && node test/coverage.js && node test/regress-5.1.0.js && node test/join.test.js && node test/btree.test.js && node test/dml-constraints.test.js && node test/savepoint.test.js && node test/alter-table.test.js && node test/null-semantics.test.js && node test/identifier-keywords.test.js && node test/sql-semantics.test.js && node test/extra-coverage.test.js && node test/filter-compile.test.js && node test/recursive-cte.test.js && node test/index-ddl.test.js",
+    "test:all": "node test/smoke.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/native.test.js && node test/native-multi-instance.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/wasm.test.js && node test/coverage.js && node test/regress-5.1.0.js && node test/join.test.js && node test/btree.test.js && node test/dml-constraints.test.js && node test/savepoint.test.js && node test/alter-table.test.js && node test/null-semantics.test.js && node test/identifier-keywords.test.js && node test/sql-semantics.test.js && node test/extra-coverage.test.js && node test/filter-compile.test.js && node test/recursive-cte.test.js && node test/index-ddl.test.js && node test/mongo-group.test.js && node test/multiprotocol.test.js",
     "test:coverage": "c8 --all --include='lib/**' --exclude='lib/web_ui.js' --reporter=text --reporter=lcov node test/coverage.js",
     "test:orms": "node examples/orms/run-all.js",
     "test:dml": "node test/dml-constraints.test.js",
     "test:cte": "node test/recursive-cte.test.js",
     "test:index": "node test/index-ddl.test.js",
     "test:mongo": "node test/mongo-group.test.js",
+    "test:multi": "node test/multiprotocol.test.js",
+    "test:star": "node test/star-nag.test.js",
     "test:savepoint": "node test/savepoint.test.js",
     "test:alter": "node test/alter-table.test.js",
     "test:ident": "node test/identifier-keywords.test.js",

package/test/mongo-group.test.js

@@ -1,16 +1,5 @@
-/* ⚠️ 已知损坏，未纳入任何 CI 套件（test:all / npm test 都不含本文件）
- *
- * 现状：本文件会崩在 `rows is not iterable`（lib/mongo_server.js:541）。
- * 另外 MongoDB 协议栈与**官方现代 driver 的握手尚未打通** ——
- * 用官方 mongodb driver 连不上。
- *
- * 因此「四协议」目前实际是「一个半」：MySQL 可用；PG / Redis 以库形式
- * 提供、需自行装配；MongoDB 仅供实验。
- * 文档已按此更正（doc/why.md、doc/cli.md）。
- *
- * 修好前请勿把本文件加进 CI —— 它一崩就会像之前那样掐断 `&&` 链。
- * 修 MongoDB 需要单独排期，不属于性能/打包类改动。
- */
+/* Test: MongoDB $group aggregation operators
+ * Directly tests the _dispatch method of createMongoServer */
 
 // Test: MongoDB $group aggregation operators
 // Directly tests the _dispatch method of createMongoServer
@@ -26,9 +15,9 @@ const ok = (name, cond, extra) => {
 const srv = createMongoServer({ port: 0, noAuth: true, dataDir: ':memory:' });
 srv.listen(() => {
   (async () => {
-    // Get the engine and pre-populate
-    const engine = await srv._getEngine();
-    engine.createTable('sales', { schema: { _id: { type: 'integer' }, item: { type: 'string' }, qty: { type: 'integer' }, price: { type: 'integer' } } });
+    // Get the engine and pre-populate（库名必须与 dispatch 的 $db 一致）
+    const engine = await srv._getEngine('test');
+    await engine.createTable('sales', { _id: { type: 'integer' }, item: { type: 'string' }, qty: { type: 'integer' }, price: { type: 'integer' } });
     const table = engine._ensureTable('sales');
     table._rows = [
       { _id: 1, item: 'A', qty: 10, price: 5 },

package/test/multiprotocol.test.js

@@ -0,0 +1,155 @@
+/**
+ * 单端口多协议回归测试
+ *
+ * 校验 README 里「One Port」这条承诺：
+ *   1. 同一个 TCP 端口按首包嗅探到 MySQL / PostgreSQL / MongoDB / Redis
+ *   2. 静默连接（MySQL 客户端等服务器先握手）按 idleProtocol 兜底
+ *   3. `jsql serve` 默认启动多协议服务器，`--mysql-only` 保留单协议行为
+ *
+ * 全部使用原始 socket，不依赖 mysql2 / pg / mongodb / ioredis。
+ */
+const net = require('net');
+const path = require('path');
+const { spawn } = require('child_process');
+const { createMultiServer, sniffProtocol } = require('../lib/multiserver');
+const { bsonDocument } = require('../lib/mongo_server');
+
+let pass = 0, fail = 0;
+function ok(name, cond, extra) {
+  if (cond) { pass++; console.log('[OK]   ' + name); }
+  else { fail++; console.log('[FAIL] ' + name + (extra !== undefined ? ' → ' + JSON.stringify(extra) : '')); }
+}
+
+function connect(port) {
+  return new Promise((resolve, reject) => {
+    const s = net.connect(port, '127.0.0.1', () => resolve(s));
+    s.on('error', reject);
+  });
+}
+
+function readSome(socket, ms = 1500) {
+  return new Promise((resolve) => {
+    let buf = Buffer.alloc(0);
+    const done = () => { clearTimeout(t); socket.removeListener('data', onData); resolve(buf); };
+    const onData = (c) => { buf = Buffer.concat([buf, c]); };
+    const t = setTimeout(done, ms);
+    socket.on('data', onData);
+  });
+}
+
+function mongoHello() {
+  const payload = bsonDocument({ hello: 1, helloOk: true, $db: 'admin' });
+  const head = Buffer.alloc(16);
+  head.writeInt32LE(16 + 4 + 1 + payload.length, 0);
+  head.writeInt32LE(1, 4);
+  head.writeInt32LE(0, 8);
+  head.writeInt32LE(2013, 12);
+  return Buffer.concat([head, Buffer.alloc(4), Buffer.from([0]), payload]);
+}
+
+async function main() {
+  console.log('--- 首包嗅探 ---');
+  ok('PG StartupMessage 判为 pg', sniffProtocol(Buffer.from([0, 0, 0, 60, 0, 3, 0, 0])) === 'pg');
+  ok('MySQL 握手版本判为 mysql', sniffProtocol(Buffer.from([0x0a, 0x38, 0x2e, 0x30])) === 'mysql');
+  ok('RESP 数组判为 redis', sniffProtocol(Buffer.from('*1\r\n$4\r\nPING\r\n')) === 'redis');
+  {
+    const m = mongoHello();
+    ok('Mongo OP_MSG 判为 mongo', sniffProtocol(m) === 'mongo');
+  }
+
+  console.log('\n--- 同一端口四协议 ---');
+  const srv = createMultiServer({ port: 0, host: '127.0.0.1', noAuth: true });
+  await new Promise((r) => srv.listen(r));
+  const port = srv.address.port;
+  ok('监听成功', port > 0, port);
+
+  {
+    const s = await connect(port);
+    const buf = await readSome(s);
+    s.destroy();
+    ok('MySQL 静默连接收到握手包', buf.length > 5 && buf[4] === 0x0a, buf.slice(0, 8).toString('hex'));
+    ok('握手包含服务器版本', buf.includes(Buffer.from('jsql-neo')));
+  }
+
+  {
+    const s = await connect(port);
+    const ssl = Buffer.alloc(8);
+    ssl.writeInt32BE(8, 0);
+    ssl.writeInt32BE(80877103, 4); // SSLRequest
+    s.write(ssl);
+    const buf = await readSome(s, 800);
+    s.destroy();
+    ok('PostgreSQL SSLRequest 被拒绝并回 N', buf.toString('utf8') === 'N', buf.toString('utf8'));
+  }
+
+  {
+    const s = await connect(port);
+    s.write(Buffer.from('PING\r\n'));
+    const buf = await readSome(s, 800);
+    s.destroy();
+    ok('Redis PING 返回 +PONG', buf.toString('utf8').startsWith('+PONG'), buf.toString('utf8'));
+  }
+
+  {
+    const s = await connect(port);
+    s.write(mongoHello());
+    const buf = await readSome(s, 1500);
+    s.destroy();
+    ok('Mongo hello 返回 OP_MSG', buf.length >= 16 && buf.readInt32LE(12) === 2013);
+    ok('Mongo hello ok:1', buf.includes(Buffer.from('isWritablePrimary')));
+  }
+
+  console.log('\n--- 共享同一份 SQL 引擎 ---');
+  {
+    // 直接用 MT 服务器内部的引擎实例验证：Mongo 与 SQL 走同一个 Database
+    const eng = await srv.mysql._getEngine('shared');
+    const sameAsPg = (await srv.pg._getEngine('shared')) === eng;
+    const sameAsMongo = (await srv.mongo._getEngine('shared')) === eng;
+    ok('MySQL/PG/Mongo 取到同一个引擎', sameAsPg && sameAsMongo);
+  }
+
+  await new Promise((r) => srv.close(r));
+
+  console.log('\n--- idleProtocol 兜底 ---');
+  {
+    const redisIdle = createMultiServer({ port: 0, host: '127.0.0.1', idleProtocol: 'redis' });
+    await new Promise((r) => redisIdle.listen(r));
+    const s = await connect(redisIdle.address.port);
+    // 不主动发包：按 idleProtocol 走 Redis，随后发 PING 必须能回
+    await new Promise((r) => setTimeout(r, 350));
+    s.write(Buffer.from('PING\r\n'));
+    const buf = await readSome(s, 800);
+    s.destroy();
+    ok('idleProtocol=redis 时空闲连接仍可用', buf.toString('utf8').startsWith('+PONG'), buf.toString('utf8'));
+    await new Promise((r) => redisIdle.close(r));
+  }
+
+  console.log('\n--- CLI serve 入口 ---');
+  {
+    const bin = path.join(__dirname, '..', 'bin', 'jsql');
+    const child = spawn(process.execPath, [bin, 'serve', '-p', '0'], {
+      env: { ...process.env, JSQL_NO_STAR_NAG: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    child.stdout.on('data', (c) => { out += c; });
+    child.stderr.on('data', (c) => { out += c; });
+    const started = await new Promise((resolve) => {
+      const t = setTimeout(() => resolve(false), 5000);
+      const check = () => {
+        if (/multi-protocol server on/.test(out) || /serve failed/.test(out)) {
+          clearTimeout(t); resolve(/multi-protocol server on/.test(out));
+        } else setTimeout(check, 50);
+      };
+      check();
+    });
+    ok('jsql serve 默认启动多协议服务器', started, out.trim());
+    child.kill('SIGTERM');
+    await new Promise((r) => { child.on('exit', r); setTimeout(r, 1000); });
+  }
+
+  console.log(`\nRESULT: ${pass} passed, ${fail} failed`);
+  if (fail > 0) process.exit(1);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/test/star-nag.test.js

@@ -0,0 +1,160 @@
+/**
+ * jsql star 授权流回归测试
+ *
+ * 背景：线上 result.php 曾把「state 文件存在」一律当成授权完成，
+ * 而 start.php 一开始就会写入 {"state":"started"}。于是 CLI 第二轮轮询
+ * 就拿到 started 当 done，打印出：
+ *     Authorization finished, but undefined has not starred undefined yet.
+ *     Star it at https://github.com/undefined then run `jsql star` again.
+ * 真相是授权根本没走完。
+ *
+ * 覆盖：
+ *   1. parseAuthResult 对各形态响应的归一化（中间态不得当成完成）
+ *   2. CLI 对 starred / not-starred / denied / error 的输出
+ *   3. 慢用户场景：先 pending 再完成，CLI 必须继续等而不是误判
+ *   4. waitForResult 的超时与 expired 收敛
+ *
+ * 注意：AUTH_RESULT 是 lib/star-nag 在 require 时从 JSQL_AUTH_BASE 读的，
+ * 所以必须先把 env 设好再 require（waitForResult 又用同步 curl，
+ * 本进程内的 server 会被饿死，所以 CLI 相关用例一律起子进程）。
+ */
+const http = require('http');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const PORT = Number(process.env.JSQL_STAR_TEST_PORT) || 34711;
+process.env.JSQL_AUTH_BASE = `http://127.0.0.1:${PORT}`;
+
+const sn = require('../lib/star-nag');
+
+let pass = 0, fail = 0;
+function ok(name, cond, extra) {
+  if (cond) { pass++; console.log('[OK]   ' + name); }
+  else { fail++; console.log('[FAIL] ' + name + (extra !== undefined ? ' → ' + JSON.stringify(extra) : '')); }
+}
+
+/** 当前 result.php 要返回的内容；pollsLeft <= 0 时切到 after */
+let scenario = { state: 'pending' };
+let pollsLeft = 0;
+let after = null;
+
+const server = http.createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  if (new URL(req.url, 'http://127.0.0.1').pathname === '/result.php') {
+    if (pollsLeft > 0 && --pollsLeft === 0 && after) scenario = after;
+    res.end(JSON.stringify(scenario));
+    return;
+  }
+  res.end('{}');
+});
+
+function runCli(mrPath) {
+  return new Promise((resolve) => {
+    const bin = path.join(__dirname, '..', 'bin', 'jsql');
+    const child = spawn(process.execPath, [bin, 'star'], {
+      env: { ...process.env, JSQL_AUTH_BASE: `http://127.0.0.1:${PORT}`, JSQL_MR_PATH: mrPath, JSQL_NO_STAR_NAG: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    child.stdout.on('data', (c) => { out += c; });
+    child.stderr.on('data', (c) => { out += c; });
+    const t = setTimeout(() => { try { child.kill(); } catch (e) {} resolve(out + '\n[TIMEOUT]'); }, 40000);
+    child.on('exit', () => { clearTimeout(t); resolve(out); });
+  });
+}
+
+async function main() {
+  /* ---------- 1. parseAuthResult ---------- */
+  console.log('--- parseAuthResult：中间态不得当成完成 ---');
+  {
+    const P = sn.parseAuthResult;
+    ok('done + starred=true → starred', P({ state: 'done', result: { starred: true, login: 'u', repo: 'o/r' } }).status === 'starred');
+    ok('done + starred=false → not-starred', P({ state: 'done', result: { starred: false, login: 'u', repo: 'o/r' } }).status === 'not-starred');
+    ok('started 被误报成 done → 未完成', P({ state: 'done', result: { state: 'started', at: 1 } }) === null);
+    ok('pending → 未完成', P({ state: 'pending' }) === null);
+    ok('缺 result 的 done → 未完成', P({ state: 'done' }) === null);
+    ok('denied → 带原因', P({ state: 'denied', result: { error: 'access_denied' } }).status === 'denied');
+    ok('error → 带原因', P({ state: 'error', result: { error: 'The code passed is incorrect or expired.' } }).error === 'The code passed is incorrect or expired.');
+    ok('空响应 → 未完成', P(null) === null && P({}) === null);
+    ok('未知状态 → 未完成', P({ state: 'weird' }) === null);
+    ok('expired 不在终态集（由 waitForResult 单独处理）', P({ state: 'expired' }) === null);
+  }
+
+  await new Promise((r) => server.listen(PORT, '127.0.0.1', r));
+  const mrDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsqlmr-'));
+
+  /* ---------- 2. CLI 各终态输出 ---------- */
+  console.log('\n--- 假 result.php 驱动真实 CLI ---');
+  const cases = [
+    ['done + starred', { state: 'done', result: { starred: true, login: 'octocat', repo: 'vexify-org/JSQL-neo' } },
+      'Confirmed: octocat has starred vexify-org/JSQL-neo. Thanks!'],
+    ['done + 未 star', { state: 'done', result: { starred: false, login: 'octocat', repo: 'vexify-org/JSQL-neo' } },
+      'Authorization finished, but octocat has not starred vexify-org/JSQL-neo yet.'],
+    ['denied', { state: 'denied', result: { error: 'access_denied' } },
+      'Authorization was declined: access_denied'],
+    ['error（code 过期/复用）', { state: 'error', result: { error: 'The code passed is incorrect or expired.' } },
+      'Authorization failed: The code passed is incorrect or expired.'],
+  ];
+  for (const [name, resp, expect] of cases) {
+    scenario = resp; pollsLeft = 0; after = null;
+    const out = await runCli(path.join(mrDir, name.replace(/[^a-z0-9]+/gi, '-')));
+    ok(`CLI 输出正确：${name}`, out.includes(expect), out.trim().slice(0, 200));
+    ok(`CLI 不再出现 undefined：${name}`, !/undefined/.test(out), out.trim().slice(0, 200));
+  }
+
+  /* ---------- 3. 慢用户 ---------- */
+  console.log('\n--- 慢用户：先 pending 再完成，CLI 必须继续等而不是误判 ---');
+  {
+    scenario = { state: 'pending' };
+    pollsLeft = 2;
+    after = { state: 'done', result: { starred: true, login: 'octocat', repo: 'vexify-org/JSQL-neo' } };
+    const out = await runCli(path.join(mrDir, 'slow'));
+    ok('等完 pending 后正确确认', out.includes('Confirmed: octocat has starred vexify-org/JSQL-neo. Thanks!'), out.trim().slice(0, 200));
+    ok('全程没有误判成完成', !/Authorization finished/.test(out), out.trim().slice(0, 200));
+    ok('全程没有 undefined', !/undefined/.test(out), out.trim().slice(0, 200));
+  }
+
+  /* ---------- 4. waitForResult ---------- */
+  console.log('\n--- waitForResult：中间态与超时 ---');
+  {
+    // waitForResult 用同步 curl，会阻塞本进程事件循环 —— server 必须留在父进程，
+    // 轮询放到子进程里跑，否则 parent 的 server 被饿死，curl 全部 -m 超时。
+    const url = `http://127.0.0.1:${PORT}/start.php?nonce=abcdefghijklmnopqrst`;
+    const poll = (resp, timeoutMs) => new Promise((resolve) => {
+      scenario = resp; pollsLeft = 0; after = null;
+      const code = [
+        `const sn = require(${JSON.stringify(path.join(__dirname, '..', 'lib', 'star-nag'))});`,
+        `const t = Date.now();`,
+        `const r = sn.waitForResult(process.env.TEST_URL, ${timeoutMs});`,
+        `process.stdout.write(JSON.stringify({ r, ms: Date.now() - t }));`,
+      ].join('\n');
+      const c = spawn(process.execPath, ['-e', code],
+        { env: { ...process.env, TEST_URL: url }, stdio: ['ignore', 'pipe', 'ignore'] });
+      let out = '';
+      c.stdout.on('data', (d) => { out += d; });
+      c.on('exit', () => { try { resolve(JSON.parse(out)); } catch (e) { resolve({ r: null, ms: -1 }); } });
+    });
+
+    for (const [name, resp] of [
+      ['pending', { state: 'pending' }],
+      ['老服务端误报 started 为 done', { state: 'done', result: { state: 'started', at: 1 } }],
+    ]) {
+      const { r, ms } = await poll(resp, 3000);
+      ok(`waitForResult(${name}) 超时返回 null`, r === null, r);
+      ok(`确实等满了 3 秒`, ms >= 2800, ms);
+    }
+    {
+      const { r, ms } = await poll({ state: 'expired' }, 5000);
+      ok('waitForResult(expired) 立即收敛', !!r && r.status === 'expired', r);
+      ok('expired 没有拖到超时', ms >= 0 && ms < 2500, ms);
+    }
+  }
+
+  server.close();
+  console.log(`\nRESULT: ${pass} passed, ${fail} failed`);
+  if (fail > 0) process.exit(1);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });