screepsmod-exec-cli-in-console 1.0.2 → 1.0.5

package/README.md

@@ -42,18 +42,42 @@ Example `mods.json`:
 
 ## Configuration (IMPORTANT)
 
-Edit `execute-cli.js` and update `SETTINGS`:
-
-- `allowAllUsers`: if `true`, every real player becomes a **normal** user (NOT super admin). Keep `false` unless this is a local/dev server.
-- `normalUserIds` / `normalUsernames`: allow-list for **normal** users when `allowAllUsers=false`.
-- `superAdminUserIds` / `superAdminUsernames`: allow-list for **super** users.
-- `superAdminUsersCodeSelfOnly`: if `true`, even super admins cannot read/modify other users' code in `users.code`.
-- `allowedCodePrefixes`: if non-empty, only code starting with one of these prefixes is allowed.
-- Limits:
-  - `maxCodeLength`
-  - `maxOutputLines`
-  - `evalTimeoutMs`
-  - `promiseTimeoutMs`
+Create a `execute-cli.config.json` file in your server root directory (same level as `mods.json`). Only include the fields you want to override; missing fields use defaults.
+
+Example `execute-cli.config.json`:
+
+```json
+{
+  "allowAllUsers": false,
+  "normalUsernames": ["player1", "player2"],
+  "superAdminUsernames": ["admin"],
+  "superAdminUserIds": ["1"]
+}
+```
+
+Config file search order:
+1. Directory of `MODFILE` env var (Screeps server sets this to `mods.json` path)
+2. Current working directory (`process.cwd()`)
+3. One level up from the mod directory
+4. Two/three levels up (for `node_modules/` installations)
+
+### Available options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `allowAllUsers` | boolean | `false` | If `true`, every real player becomes a **normal** user (NOT super admin). Keep `false` unless this is a local/dev server. |
+| `normalUserIds` | string[] | `[]` | User IDs for **normal** users (e.g. `["1", "4"]`). Used when `allowAllUsers=false`. |
+| `normalUsernames` | string[] | `[]` | Usernames for **normal** users. Case-sensitive. |
+| `superAdminUserIds` | string[] | `[]` | User IDs for **super admin** users. |
+| `superAdminUsernames` | string[] | `[]` | Usernames for **super admin** users. Case-sensitive. |
+| `superAdminUsersCodeSelfOnly` | boolean | `true` | If `true`, even super admins cannot read/modify other users' code in `users.code`. |
+| `allowedCodePrefixes` | string[] | `[]` | If non-empty, only code starting with one of these prefixes is allowed. |
+| `maxCodeLength` | number | `2000` | Maximum length of CLI code string allowed per call. |
+| `maxOutputLines` | number | `60` | Maximum number of output lines sent back to the player's console. |
+| `evalTimeoutMs` | number | `2000` | Node vm timeout (ms) for synchronous code execution. |
+| `promiseTimeoutMs` | number | `5000` | Timeout (ms) for waiting on returned promise/thenable results. |
+
+> **Note**: Username matching is **case-sensitive**. Make sure to use the exact username as registered.
 
 ## Usage (in-game console)
 
@@ -93,6 +117,20 @@ Sets `progress = progressTotal - 1` for construction sites in the given rooms.
 Game.cli.finishConstructionSites(['W1N9'])
 ```
 
+### Common commands
+
+#### Modify all ramparts HP
+
+```js
+Game.cli.exec("(function(){var hp=300000000;return storage.db.rooms.find({}).then(function(rs){var rooms=(rs||[]).map(function(r){return r._id});return storage.db['rooms.objects'].find({type:'rampart',room:{$in:rooms}}).then(function(ws){var p=storage.db['rooms.objects'].count({_id:{$in:[]}});(ws||[]).forEach(function(w){p=p.then(function(){return storage.db['rooms.objects'].update({_id:w._id},{$set:{hits:hp,hitsMax:hp}});});});return p.then(function(){return 'OK ramparts='+(ws?ws.length:0);});});});})()")
+```
+
+#### Modify walls/ramparts HP in a specific room (e.g. W4N1)
+
+```js
+Game.cli.exec("storage.db['rooms.objects'].find({ type: { $in: ['constructedWall', 'rampart'] }, room: { $in: ['W4N1'] } }).then(resp => resp.map(cs => storage.db['rooms.objects'].findOne({ _id: cs._id }).then(csDetail => storage.db['rooms.objects'].update({ _id: cs._id }, { $set: { hits: 10000000 } }))))")
+```
+
 ## Security notes
 
 Executing arbitrary server CLI JS is powerful:
@@ -113,7 +151,7 @@ Role behavior:
   - Make sure the mod is enabled in `mods.json` and the server restarted.
   - Ensure your server has `isolated-vm` available (Screeps uses it for player sandbox).
 - **`[cli] denied: not allowed user`**:
-  - Add your user id / username to `SETTINGS.normalUserIds/normalUsernames` or `superAdmin*`.
+  - Add your user id / username to `normalUserIds/normalUsernames` or `superAdminUserIds/superAdminUsernames` in `execute-cli.config.json`.
 - **No output / output truncated**:
   - Adjust `maxOutputLines`, `evalTimeoutMs`, `promiseTimeoutMs`.
 

package/README.zh.md

@@ -42,18 +42,42 @@
 
 ## 配置（非常重要）
 
-请直接编辑 `execute-cli.js` 顶部的 `SETTINGS`：
-
-- `allowAllUsers`：若为 `true`，所有真实玩家都会被视为**普通用户**（不是超管）。除非本地/单机测试服，否则不要开。
-- `normalUserIds` / `normalUsernames`：当 `allowAllUsers=false` 时，普通用户白名单。
-- `superAdminUserIds` / `superAdminUsernames`：超管白名单。
-- `superAdminUsersCodeSelfOnly`：若为 `true`，即便是超管也不允许读/改其他用户在 `users.code` 里的代码（隐私保护）。
-- `allowedCodePrefixes`：如果不为空，只允许执行以这些前缀开头的代码字符串。
-- 限制项：
-  - `maxCodeLength`
-  - `maxOutputLines`
-  - `evalTimeoutMs`
-  - `promiseTimeoutMs`
+在私服根目录（与 `mods.json` 同级）创建 `execute-cli.config.json` 配置文件。只需填写你想覆盖的字段，未填写的字段使用默认值。
+
+`execute-cli.config.json` 示例：
+
+```json
+{
+  "allowAllUsers": false,
+  "normalUsernames": ["player1", "player2"],
+  "superAdminUsernames": ["admin"],
+  "superAdminUserIds": ["1"]
+}
+```
+
+配置文件搜索顺序：
+1. `MODFILE` 环境变量指定的目录（Screeps 私服会将其设为 `mods.json` 路径）
+2. 当前工作目录（`process.cwd()`）
+3. mod 目录的上一级
+4. 上两/三级目录（适用于 `node_modules/` 安装方式）
+
+### 可用配置项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `allowAllUsers` | boolean | `false` | 若为 `true`，所有真实玩家都会被视为**普通用户**（不是超管）。除非本地/单机测试服，否则不要开。 |
+| `normalUserIds` | string[] | `[]` | 普通用户的 User ID 列表（如 `["1", "4"]`）。仅当 `allowAllUsers=false` 时生效。 |
+| `normalUsernames` | string[] | `[]` | 普通用户的用户名列表。区分大小写。 |
+| `superAdminUserIds` | string[] | `[]` | 超管的 User ID 列表。 |
+| `superAdminUsernames` | string[] | `[]` | 超管的用户名列表。区分大小写。 |
+| `superAdminUsersCodeSelfOnly` | boolean | `true` | 若为 `true`，即便是超管也不允许读/改其他用户在 `users.code` 里的代码（隐私保护）。 |
+| `allowedCodePrefixes` | string[] | `[]` | 如果不为空，只允许执行以这些前缀开头的代码字符串。 |
+| `maxCodeLength` | number | `2000` | 每次调用允许的 CLI 代码最大长度。 |
+| `maxOutputLines` | number | `60` | 返回给玩家控制台的最大输出行数。 |
+| `evalTimeoutMs` | number | `2000` | 同步代码执行的 Node vm 超时时间（毫秒）。 |
+| `promiseTimeoutMs` | number | `5000` | 等待返回的 Promise/thenable 结果的超时时间（毫秒）。 |
+
+> **注意**：用户名匹配**区分大小写**，请确保使用与注册时完全一致的用户名。
 
 ## 用法（游戏内控制台）
 
@@ -93,6 +117,20 @@ Game.cli.setControllerLevel('67c8...df8', 8)
 Game.cli.finishConstructionSites(['W1N9'])
 ```
 
+### 常用命令
+
+#### 修改所有墙的血量
+
+```js
+Game.cli.exec("(function(){var hp=300000000;return storage.db.rooms.find({}).then(function(rs){var rooms=(rs||[]).map(function(r){return r._id});return storage.db['rooms.objects'].find({type:'rampart',room:{$in:rooms}}).then(function(ws){var p=storage.db['rooms.objects'].count({_id:{$in:[]}});(ws||[]).forEach(function(w){p=p.then(function(){return storage.db['rooms.objects'].update({_id:w._id},{$set:{hits:hp,hitsMax:hp}});});});return p.then(function(){return 'OK ramparts='+(ws?ws.length:0);});});});})()")
+```
+
+#### 修改指定房间内的墙血量（如 W4N1）
+
+```js
+Game.cli.exec("storage.db['rooms.objects'].find({ type: { $in: ['constructedWall', 'rampart'] }, room: { $in: ['W4N1'] } }).then(resp => resp.map(cs => storage.db['rooms.objects'].findOne({ _id: cs._id }).then(csDetail => storage.db['rooms.objects'].update({ _id: cs._id }, { $set: { hits: 10000000 } }))))")
+```
+
 ## 安全说明
 
 执行服务端 CLI JS 权限很大：
@@ -113,7 +151,7 @@ Game.cli.finishConstructionSites(['W1N9'])
   - 确认已在 `mods.json` 启用并重启私服。
   - 确认环境可用 `isolated-vm`（Screeps 玩家沙箱依赖它）。
 - **提示 `[cli] denied: not allowed user`**：
-  - 把你的 userId / 用户名加入 `SETTINGS.normalUserIds/normalUsernames` 或 `superAdmin*`。
+  - 在 `execute-cli.config.json` 中把你的 userId / 用户名加入 `normalUserIds/normalUsernames` 或 `superAdminUserIds/superAdminUsernames`。
 - **输出缺失/被截断**：
   - 调整 `maxOutputLines`、`evalTimeoutMs`、`promiseTimeoutMs`。
 

package/index.js

@@ -19,10 +19,29 @@ const EventEmitter = require('events').EventEmitter;
 const vm = require('vm');
 const util = require('util');
 
-// ---- Settings (edit me) ----------------------------------------------------
+// ---- Settings (defaults, can be overridden via execute-cli.config.json in server root) ----
+//
+// To customize settings WITHOUT editing this file, create `execute-cli.config.json` in the
+// server root directory (same level as mods.json). Example:
+//
+//   {
+//     "allowAllUsers": false,
+//     "normalUsernames": ["player1", "player2"],
+//     "superAdminUsernames": ["admin"]
+//   }
+//
+// Only include the fields you want to override; missing fields use defaults below.
+
+const fs = require('fs');
 
-const SETTINGS = {
+/**
+ * DEFAULT_SETTINGS - These are the default values for all configuration options.
+ * They can be overridden by `execute-cli.config.json` in the server root.
+ */
+const DEFAULT_SETTINGS = {
     /**
+     * allowAllUsers (boolean, default: false)
+     *
      * If true, EVERY real player is treated as a "normal" allowed user (see `resolveRole()`),
      * i.e. they can call `Game.cli.exec()` without being in `normalUserIds/normalUsernames`.
      *
@@ -36,23 +55,33 @@ const SETTINGS = {
     allowAllUsers: false,
 
     /**
+     * normalUserIds / normalUsernames (array of strings, default: [])
+     *
      * Normal permission allow-list (used only when allowAllUsers=false).
      * Normal users can ONLY access:
      * - storage.db.rooms (restricted to rooms they own)
      * - storage.db.objects / storage.db['rooms.objects'] (restricted to {user: self})
      * - storage.db.creeps (view over rooms.objects with {type:'creep', user:self})
+     *
+     * In many private servers user ids are simple strings like "1", "4", ...
+     * NPC users are usually "2" (Invader) and "3" (Source Keeper) and are blocked anyway.
      */
     normalUserIds: [],
     normalUsernames: [],
 
     /**
+     * superAdminUserIds / superAdminUsernames (array of strings, default: [])
+     *
      * Super admin allow-list.
-     * Super admins can execute any CLI JS and access all CLI sandbox objects.
+     * Super admins can execute any CLI JS and access all CLI sandbox objects
+     * (storage, system, map, bots, strongholds, etc).
      */
     superAdminUserIds: [],
     superAdminUsernames: [],
 
     /**
+     * superAdminUsersCodeSelfOnly (boolean, default: true)
+     *
      * Privacy guard:
      * Even for super admins, do NOT allow reading/modifying other users' code in `users.code`.
      * (Super admins can still access other tables unless you restrict them elsewhere.)
@@ -60,25 +89,108 @@ const SETTINGS = {
     superAdminUsersCodeSelfOnly: true,
 
     /**
+     * allowedCodePrefixes (array of strings, default: [])
+     *
      * Optional prefix allow-list for the CLI JS string.
      * If non-empty, only commands starting with one of these prefixes will be allowed.
      *
      * Examples:
      * - ['system.', 'map.']          -> allow only system.* and map.* helpers
      * - ['help(', 'print(']          -> allow only help()/print()
-     * - []                          -> allow any JS (still subject to user allow-list)
+     * - []                           -> allow any JS (still subject to user allow-list)
      */
     allowedCodePrefixes: [],
 
     /**
-     * Basic abuse limits.
+     * maxCodeLength (number, default: 2000)
+     *
+     * Maximum length of CLI code string allowed per call.
      */
     maxCodeLength: 2000,
+
+    /**
+     * maxOutputLines (number, default: 60)
+     *
+     * Maximum number of output lines sent back to the player's console per call.
+     */
     maxOutputLines: 60,
-    evalTimeoutMs: 2000, // Node vm timeout for sync execution
-    promiseTimeoutMs: 5000, // waiting for returned promise/thenable
+
+    /**
+     * evalTimeoutMs (number, default: 2000)
+     *
+     * Node vm timeout (in milliseconds) for synchronous code execution.
+     * Prevents infinite loops from blocking the server.
+     */
+    evalTimeoutMs: 2000,
+
+    /**
+     * promiseTimeoutMs (number, default: 5000)
+     *
+     * Timeout (in milliseconds) for waiting on returned promise/thenable results.
+     */
+    promiseTimeoutMs: 5000,
 };
 
+/**
+ * Load external config from `execute-cli.config.json` in the server root directory
+ * (same level as mods.json). If the file exists and is valid JSON, its values will
+ * be merged into SETTINGS. This way you can update the mod code without losing your config.
+ *
+ * Config file search order:
+ * 1. Directory of MODFILE env var (Screeps server sets this to mods.json path)
+ * 2. Current working directory (process.cwd())
+ * 3. One level up from this file's directory (for example-mods/ installation)
+ */
+function loadExternalConfig() {
+    const CONFIG_FILENAME = 'execute-cli.config.json';
+    const candidateDirs = [];
+
+    // 1. Use MODFILE env var if available (Screeps server sets this)
+    if (process.env.MODFILE) {
+        candidateDirs.push(path.dirname(path.resolve(process.cwd(), process.env.MODFILE)));
+    }
+
+    // 2. Current working directory
+    candidateDirs.push(process.cwd());
+
+    // 3. One level up from __dirname (for example-mods/ or similar)
+    candidateDirs.push(path.resolve(__dirname, '..'));
+
+    // 4. Two levels up (for node_modules/xxx/ installation)
+    candidateDirs.push(path.resolve(__dirname, '..', '..'));
+
+    // 5. Three levels up (for node_modules/@scope/xxx/ installation)
+    candidateDirs.push(path.resolve(__dirname, '..', '..', '..'));
+
+    // Deduplicate
+    const seen = new Set();
+    const uniqueDirs = candidateDirs.filter(d => {
+        const resolved = path.resolve(d);
+        if (seen.has(resolved)) return false;
+        seen.add(resolved);
+        return true;
+    });
+
+    for (const dir of uniqueDirs) {
+        const configPath = path.join(dir, CONFIG_FILENAME);
+        try {
+            if (fs.existsSync(configPath)) {
+                const raw = fs.readFileSync(configPath, 'utf8');
+                const ext = JSON.parse(raw);
+                console.log('[execute-cli mod] Loaded config from', configPath);
+                return ext;
+            }
+        } catch (e) {
+            console.error('[execute-cli mod] Failed to load config from', configPath, ':', e && (e.message || e));
+        }
+    }
+
+    console.log('[execute-cli mod] No config file found, using defaults. Searched:', uniqueDirs.map(d => path.join(d, CONFIG_FILENAME)).join(', '));
+    return {};
+}
+
+const SETTINGS = Object.assign({}, DEFAULT_SETTINGS, loadExternalConfig());
+
 // ---------------------------------------------------------------------------
 
 // In Steam-distributed Screeps server, dependencies may live under `package/node_modules/`
@@ -142,7 +254,7 @@ function normalizeIdSet(list) {
 }
 
 function normalizeNameSet(list) {
-    return new Set(normalizeList(list).map(i => i.toLowerCase()));
+    return new Set(normalizeList(list));
 }
 
 function getEffectiveSuperAdminSets() {
@@ -455,19 +567,19 @@ async function resolveRole(userId) {
     userId = String(userId);
     const superSets = getEffectiveSuperAdminSets();
     const normalSets = getEffectiveNormalSets();
+    const defaultRole = SETTINGS.allowAllUsers ? 'normal': null
 
     if (superSets.ids.has(userId)) return 'super';
-    if (SETTINGS.allowAllUsers) return 'normal';
     if (normalSets.ids.has(userId)) return 'normal';
 
     const needNameLookup = superSets.names.size > 0 || normalSets.names.size > 0;
-    if (!needNameLookup) return null;
+    if (!needNameLookup) return defaultRole;
 
     const user = await common.storage.db.users.findOne({_id: userId});
-    const usernameLower = user && user.username ? String(user.username).toLowerCase() : '';
+    const usernameLower = user && user.username ? String(user.username) : '';
     if (usernameLower && superSets.names.has(usernameLower)) return 'super';
     if (usernameLower && normalSets.names.has(usernameLower)) return 'normal';
-    return null;
+    return defaultRole;
 }
 
 function withTimeout(promise, ms, label) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screepsmod-exec-cli-in-console",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Allow players to execute (some) server CLI-only commands from the in-game console.",
   "main": "index.js",
   "scripts": {},