@flun/windows 3.0.10 → 4.0.0

package/lib/eventlog.js

@@ -1,12 +1,14 @@
 import { execPromise, execSync, isPermissionError } from './shared.js';
 import { elevate } from './binaries.js';
 
-const eventLogs = ['APPLICATION', 'SYSTEM', 'SECURITY'], validTypes = ['ERROR', 'WARNING', 'INFORMATION', 'SUCCESSAUDIT', 'FAILUREAUDIT'];
+const eventLogs = ['APPLICATION', 'SYSTEM', 'SECURITY'],
+    validTypes = ['ERROR', 'WARNING', 'INFORMATION', 'SUCCESSAUDIT', 'FAILUREAUDIT'];
 
 /**
  * 事件日志记录器类,用于向Windows事件查看器写入日志
  * - 提供记录信息、警告、错误和审计成功、审计失败事件的方法
- * >查看定义:@see {@link EventLogger}、{@link info}、{@link warn}、{@link error}、{@link auditSuccess}、{@link auditFailure}
+ * >查看定义:@see {@link EventLogger}、{@link info}、{@link warn}、{@link error}、{@link auditSuccess}、
+ * {@link auditFailure}
  * @class EventLogger
  * @example
  *  // 配置示例
@@ -28,9 +30,9 @@ const eventLogs = ['APPLICATION', 'SYSTEM', 'SECURITY'], validTypes = ['ERROR',
 class EventLogger {
   /**
    * @constructor
-   * @param {string|Object} [config] - 配置字符串（作为 source）或配置对象
+   * @param {string|Object} [config] - 配置字符串(作为 source)或配置对象
    * @param {string} [config.source='Node.js'] - 事件源名称
-   * @param {string} [config.eventLog='APPLICATION'] - 事件日志名称（APPLICATION, SYSTEM, SECURITY）
+   * @param {string} [config.eventLog='APPLICATION'] - 事件日志名称(APPLICATION, SYSTEM, SECURITY)
    */
   constructor(config = {}) {
     if (typeof config === 'string') config = { source: config };
@@ -57,7 +59,7 @@ class EventLogger {
   }
 
   /**
-   * 获取当前事件日志名称（大写）
+   * 获取当前事件日志名称(大写)
    * @returns {string}
    */
   get eventLog() {
@@ -124,10 +126,14 @@ class EventLogger {
     // 判断是否需要使用PowerShell
     if (this.#shouldUsePowerShell(vType, vId)) {
       // 使用PowerShell的Write-EventLog命令
-      const entryTypeMap = { 'ERROR': 'Error', 'WARNING': 'Warning', 'SUCCESSAUDIT': 'SuccessAudit', 'FAILUREAUDIT': 'FailureAudit' },
+      const entryTypeMap = {
+        'ERROR': 'Error', 'WARNING': 'Warning',
+        'SUCCESSAUDIT': 'SuccessAudit', 'FAILUREAUDIT': 'FailureAudit'
+      },
         entryType = entryTypeMap[vType] || 'Information', escapedMsg = pMsg.replace(/"/g, '""'),
         powHad = 'powershell -Command "Write-EventLog -LogName';
-      command = `${powHad} '${vLog}' -Source '${vSrc}' -EventId ${vId} -EntryType ${entryType} -Message \\\"${escapedMsg}\\\""`;
+      command = `${powHad} '${vLog}' -Source '${vSrc}' -EventId ${vId}` +
+        ` -EntryType ${entryType} -Message \\\"${escapedMsg}\\\""`;
     } else {
       const eventCreateId = Math.min(Math.max(1, vId), 1000); // 限制在1-1000范围内
       command = `eventcreate /L ${vLog} /T ${vType} /SO "${vSrc}" /D "${pMsg}" /ID ${eventCreateId}`;

package/lib/shared.js

@@ -1,6 +1,7 @@
 /**
  * 共享模块,导出在多个文件中使用的常用函数和模块
- * >查看定义:@see {@link exec}、{@link execSync}、{@link fork}、{@link promisify}、{@link path}、{@link fs}、{@link EventEmitter}
+ * >查看定义:@see {@link exec}、{@link execSync}、{@link fork}、{@link promisify}、{@link path}、
+ * {@link fs}、{@link EventEmitter}
  */
 import { exec, execSync, fork } from 'child_process';
 import { promisify } from 'util';
@@ -24,14 +25,15 @@ const execPromise = promisify(exec);
  */
 const isPermissionError = error => {
     const errorMessage = error?.message || error?.toString() || String(error),
-        permissionErrors = ['拒绝访问', 'Access is denied', '权限不足', 'Insufficient privileges', 'AccessDenied', '需要提升权限',
+        permissionErrors = ['拒绝访问', 'Access is denied', '权限不足', 'Insufficient privileges',
+            'AccessDenied', '需要提升权限',
             'requires elevation', 'Administrator', 'admin', '权限被拒绝'],
         lowerMessage = errorMessage.toLowerCase();
     return permissionErrors.some(keyword => lowerMessage.includes(keyword.toLowerCase()));
 }
 
 /**
- * 获取当前模块所在目录的路径（类似 CommonJS 的 __dirname）
+ * 获取当前模块所在目录的路径(类似 CommonJS 的 __dirname)
  * >查看定义:@see {@link getDirname}
  * @param {string} metaUrl - 传入 `import.meta.url`
  * @returns {string} 当前模块的目录路径

package/lib/winsw.js

@@ -6,31 +6,31 @@ const __dirname = getDirname(import.meta.url);
 /**
  * @method generateXml 生成 winsw 配置文件的 XML;
  * >查看定义:@see {@link generateXml}
- * @param {Object} config - 配置对象,必须包含以下必需属性：
+ * @param {Object} config - 配置对象,必须包含以下必需属性:
  *   - *id* 服务的标识符,只能包含字母和数字,不能有空格
  *   - *name* 服务的描述性名称
- *   - *execPath* Node.js 可执行文件的绝对路径（如：C:\Program Files\nodejs\node.exe）
- *   - *script* Node.js 服务器脚本的绝对路径（包装脚本）
+ *   - *execPath* Node.js 可执行文件的绝对路径(如:C:\Program Files\nodejs\node.exe)
+ *   - *script* Node.js 服务器脚本的绝对路径(包装脚本)
  *   - *workingdirectory* 服务运行的工作目录
  * @param {string} [config.description] - 在服务管理器中显示的描述信息
- * @param {string|string[]} [config.nodeOptions] - Node.js 选项（数组或空格分隔的字符串）
+ * @param {string|string[]} [config.nodeOptions] - Node.js 选项(数组或空格分隔的字符串)
  * @param {string} [config.wrapperArgs] - 传递给包装脚本的额外参数
  * @param {string} [config.logmode] - 日志模式(老式):'rotate'(默认), 'reset', 'roll', 'append'
  * @param {Object} [config.logging] - 日志配置对象,可替代 logmode
  * @param {string} [config.logging.mode] - 日志模式(现代),支持 'append', 'reset', 'none', 'roll-by-time', 'roll-by-size'
- * @param {string} [config.logging.pattern] - roll-by-time 模式的时间格式模式（默认:'yyyyMMdd'）
- * @param {number} [config.logging.sizeThreshold] - roll-by-size 模式的大小阈值（默认:10240）
- * @param {number} [config.logging.keepFiles] - roll-by-size 模式保留的文件数（默认:8）
- * @param {string} [config.logpath] - 日志存储目录的绝对路径（默认:当前目录）
+ * @param {string} [config.logging.pattern] - roll-by-time 模式的时间格式模式(默认:'yyyyMMdd')
+ * @param {number} [config.logging.sizeThreshold] - roll-by-size 模式的大小阈值(默认:10240)
+ * @param {number} [config.logging.keepFiles] - roll-by-size 模式保留的文件数(默认:8)
+ * @param {string} [config.logpath] - 日志存储目录的绝对路径(默认:当前目录)
  * @param {string|string[]} [config.dependencies] - 进程依赖项的逗号分隔列表或数组
- * @param {{ name: string, value: string }[]|Object<string, string>} [config.env] - 环境变量配置（键/值对象或对象数组）
+ * @param {{ name: string, value: string }[]|Object<string, string>} [config.env] - 环境变量配置(键/值对象或对象数组)
  * @param {Object} [config.logOnAs] - 服务登录凭据配置
  * @param {string} [config.logOnAs.account] - 登录账户名
  * @param {string} [config.logOnAs.password] - 登录密码
  * @param {string} [config.logOnAs.domain] - 账户所在域
  * @param {boolean} [config.allowServiceLogon] - 是否允许服务登录
  * @param {boolean} [config.stopparentfirst] - 是否先停止父进程
- * @param {number} [config.stoptimeout] - 停止超时时间（秒）
+ * @param {number} [config.stoptimeout] - 停止超时时间(秒)
  * @returns {string} 生成的 XML 字符串
  * @throws {string} 当缺少必需配置时抛出错误
  */
@@ -41,7 +41,8 @@ const generateXml = config => {
   } = config;
 
   // 验证必需配置项是否存在
-  if (!id || !name || !script || !execPath || !workingdirectory) throw "id,name,script,execPath,workingdirectory为必需配置项";
+  if (!id || !name || !script || !execPath || !workingdirectory)
+      throw "id,name,script,execPath,workingdirectory为必需配置项";
 
   let xml = [{ id }, { name }, { description }, { executable: execPath }]; // 基础 XML 结构
 
@@ -58,7 +59,8 @@ const generateXml = config => {
 
   // 日志配置处理:优先使用 logging 对象,其次使用 logmode
   if (logging) {
-    const { mode = 'append', pattern = 'yyyyMMdd', sizeThreshold = 10240, keepFiles = 8 } = logging, logContent = [{ _attr: { mode } }];
+    const { mode = 'append', pattern = 'yyyyMMdd', sizeThreshold = 10240, keepFiles = 8 } = logging,
+        logContent = [{ _attr: { mode } }];
     if (mode === 'roll-by-time') logContent.push({ pattern });               // 按时间滚动日志
     else if (mode === 'roll-by-size') logContent.push({ sizeThreshold }), logContent.push({ keepFiles }); // 按大小滚动日志
     xml.push({ log: logContent });
@@ -88,7 +90,7 @@ const generateXml = config => {
  * @method createExe 创建 winsw 可执行文件及其配置文件
   * >查看定义:@see {@link createExe}
  * @param {string} name - 可执行文件名称(不含扩展名);
- * @param {string} dir - 输出目录（默认:当前工作目录）
+ * @param {string} dir - 输出目录(默认:当前工作目录)
  * @param {() => void} [callback] - 完成后的回调函数
  * @description 将 winsw.exe 的安装版本复制为根据服务id重命名的特定版本,
  * 并复制 .exe.config 文件以支持 .NET 4+ 运行时环境;

package/lib/wrapper.js

@@ -8,14 +8,14 @@
  * 4. 重启次数限制和频率控制
  * 5. 支持通过事件日志或控制台输出日志
  *
- * 命令行参数：
- *   -f, --file: 要运行的脚本绝对路径（必需）
+ * 命令行参数:
+ *   -f, --file: 要运行的脚本绝对路径(必需)
  *   -d, --cwd: 子进程工作目录
- *   -l, --log: 日志描述名称（必需）
- *   -e, --eventlog: 事件日志容器（APPLICATION或SYSTEM）
- *   -m, --maxretries: 最大重启次数（-1表示无限制）
+ *   -l, --log: 日志描述名称(必需)
+ *   -e, --eventlog: 事件日志容器(APPLICATION或SYSTEM)
+ *   -m, --maxretries: 最大重启次数(-1表示无限制)
  *   -r, --maxrestarts: 时间窗口内最大重启次数
- *   -w, --wait: 重启等待时间（秒）
+ *   -w, --wait: 重启等待时间(秒)
  *   -g, --grow: 等待时间增长系数
  *   -a, --abortonerror: 错误时是否终止
  *   -s, --stopparentfirst: 是否允许优雅退出
@@ -27,7 +27,7 @@ import yargs from 'yargs/yargs';
 import { hideBin } from 'yargs/helpers';
 import { EventLogger } from './eventlog.js';
 
-// 时间窗口（秒）,默认时间窗口内最大重启次数,默认重启等待时间（秒）,默认等待时间增长系数
+// 时间窗口(秒),默认时间窗口内最大重启次数,默认重启等待时间(秒),默认等待时间增长系数
 const timeWindow = 60, defaultMaxRestarts = 3, defaultWaitTime = 1, defaultGrowth = 0.25,
   booleanChoices = ['y', 'n', 'yes', 'no', 'true', 'false'],
   /**
@@ -104,7 +104,7 @@ const timeWindow = 60, defaultMaxRestarts = 3, defaultWaitTime = 1, defaultGrowt
       alias: 'm',
       type: 'number',
       default: -1,
-      description: '进程自动重启的最大次数（-1表示无限制）'
+      description: '进程自动重启的最大次数(-1表示无限制)'
     })
     .option('maxrestarts', {
       alias: 'r',
@@ -126,7 +126,7 @@ const timeWindow = 60, defaultMaxRestarts = 3, defaultWaitTime = 1, defaultGrowt
       alias: 'g',
       type: 'number',
       default: defaultGrowth,
-      description: '等待时间增长的增长百分比（0-1之间）',
+      description: '等待时间增长的增长百分比(0-1之间)',
       check: growth => {
         if (growth < 0 || growth > 1) throw new Error('增长率必须在0到1之间');
         return true;
@@ -150,7 +150,7 @@ const timeWindow = 60, defaultMaxRestarts = 3, defaultWaitTime = 1, defaultGrowt
     })
     .option('scriptoptions', {
       type: 'string',
-      description: '要传递给脚本的选项（空格分隔）',
+      description: '要传递给脚本的选项(空格分隔)',
       default: '',
       coerce: parseQuotedOption
     }).help().parse();
@@ -223,7 +223,7 @@ const prepareScriptArgs = () => {
 
         // 检查总重启次数限制
         if (argv.maxretries >= 0 && restartAttempts > argv.maxretries)
-          logger.error(`重启次数过多。${scriptPath} 将不会被重启,已超过最大重启次数 ${argv.maxretries}`), process.exit(1);
+          logger.error(`重启次数过多;${scriptPath} 将不会被重启,已超过最大重启次数 ${argv.maxretries}`), process.exit(1);
 
         launchProcess('warn', `在意外退出后 ${waitTime} 毫秒重启: 尝试次数=${restartAttempts}`);
       }, waitTime);
@@ -233,7 +233,7 @@ const prepareScriptArgs = () => {
 
   /**
    * 启动子进程
-   * @param {string} logLevel - 日志级别（info, warn, error等）
+   * @param {string} logLevel - 日志级别(info, warn, error等)
    * @param {string} message - 日志消息
    * @returns {void}
    */
@@ -273,7 +273,7 @@ const prepareScriptArgs = () => {
       logger.warn(exitMessage);
       // 检查是否需要因错误而终止
       if (code !== 0 && (argv.abortonerror === 'yes' || argv.abortonerror === 'y'))
-        logger.error(`${scriptPath} 以错误代码 ${code} 退出，终止包装器进程`), process.exit(code || 1);
+        logger.error(`${scriptPath} 以错误代码 ${code} 退出,终止包装器进程`), process.exit(code || 1);
       else if (isForceKill) process.exit(0);
 
       childProcess = null, monitorChildProcess();                              // 重新监控并可能重启
@@ -306,10 +306,10 @@ const prepareScriptArgs = () => {
 // 注册进程终止事件处理程序
 process.on('exit', terminateChildProcess);
 process.on('SIGINT', () => {
-  logger.info('收到 SIGINT 信号，正在终止...'), terminateChildProcess();
+  logger.info('收到 SIGINT 信号,正在终止...'), terminateChildProcess();
 });
 process.on('SIGTERM', () => {
-  logger.info('收到 SIGTERM 信号，正在终止...'), terminateChildProcess();
+  logger.info('收到 SIGTERM 信号,正在终止...'), terminateChildProcess();
 });
 
 // 处理未捕获异常

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flun/windows",
-  "version": "3.0.10",
+  "version": "4.0.0",
   "description": "支持 Windows 服务、事件日志、UAC 以及多种与操作系统交互的辅助方法",
   "keywords": [
     "windows",
@@ -23,12 +23,15 @@
     ".": "./index.js"
   },
   "main": "index.js",
+  "bin": {
+    "windows": "bin/cli.js"
+  },
   "files": [
     "lib",
     "bin",
     "index.d.ts",
     "index.js",
-    "sevWin.js",
+    "win-service.config.js",
     "copy-files.js",
     "CHANGELOG.md",
     "README.md",
@@ -36,6 +39,7 @@
   ],
   "preferGlobal": true,
   "dependencies": {
+    "chalk": "^6.0.1",
     "xml": "1.0.1",
     "yargs": "^18.2.0"
   },
@@ -47,7 +51,7 @@
     "type": "git",
     "url": "git+https://github.com/OpenFlun/windows.git"
   },
-  "homepage": "https://www.npmjs.com/package/@flun/windows#readme",
+  "homepage": "https://github.com/OpenFlun/windows#readme",
   "bugs": {
     "url": "https://github.com/OpenFlun/windows/issues"
   },

package/win-service.config.js

@@ -0,0 +1,68 @@
+/**
+ * Windows 服务配置模板
+ * 带 * 的为必填项,其余可删除或按需保留;
+ * 本配置既支持命令行方式(如 windows install),
+ * 也支持在函数方式中导入:import config from './win-service.config.js';
+ * 具体用法见 README 的「命令行」与「函数方式」章节;
+ *
+ * 关于 quiet:默认 false,各方法执行后会在终端打印结果(如"服务安装完成;");
+ * 若本包嵌入到自己的生产项目,终端输出会混入宿主日志,此时设为 true,
+ * 库只发事件不打印,由宿主自行监听 install/start/stop/uninstall/error 等事件;
+ * 命令行方式恒为 quiet,不受此字段影响;
+ */
+export default {
+  // * 服务名称,用于服务管理与注册表标识;不能含 <>:"\/|?*
+  name: 'MyApp',
+  // * 启动服务的入口脚本绝对路径
+  script: 'C:\\path\\to\\main.js',
+
+  // 服务描述,显示在服务管理器中
+  description: 'Node.js 服务',
+  // 传递给 node 进程的选项,可为数组或空格分隔的字符串
+  nodeOptions: ['--harmony'],
+  // 传递给脚本的选项
+  scriptOptions: '',
+  // node 可执行文件路径,默认取当前进程的 execPath
+  execPath: process.execPath,
+  // 服务工作目录,默认取当前工作目录
+  workingDirectory: process.cwd(),
+
+  // 无响应/故障前的最大重试次数,默认 null(不启用)
+  maxRetries: null,
+  // 60 秒内最大重启次数,0 表示不启用,默认 3
+  maxRestarts: 3,
+  // 停止服务的超时秒数,默认 30
+  stoptimeout: 30,
+  // 脚本停止后等待重启的秒数,默认 1
+  wait: 1,
+  // 重启等待时间的增长百分比,默认 0.25
+  grow: 0.25,
+  // 脚本运行错误时是否退出进程,默认 false
+  abortOnError: false,
+  // 是否先停止父进程,默认 false
+  stopparentfirst: false,
+
+  // 日志文件路径,默认与可执行文件同目录
+  logpath: null,
+  // 日志模式:rotate(默认)、truncate、append
+  logmode: 'rotate',
+
+  // 环境变量,形式为 { name, value } 或同构数组
+  env: { name: 'NODE_ENV', value: 'production' },
+
+  // 日志配置对象,可替代 logmode;含 mode、pattern、sizeThreshold、keepFiles
+  logging: undefined,
+
+  // 服务登录凭据;默认使用 LocalSystem
+  logOnAs: {
+    account: undefined,
+    password: null,
+    domain: process.env.COMPUTERNAME,
+    mungeCredentialsAfterInstall: true,
+  },
+  // 是否允许服务登录,默认 undefined
+  allowServiceLogon: undefined,
+
+  // 为 true 时不打印执行结果,只发事件;嵌入生产项目时建议开启
+  quiet: false,
+};

package/sevWin.js

@@ -1,18 +0,0 @@
-import { Service } from '@flun/windows'; // 可选参数(EventLogger,elevate, sudo, isAdminUser, kill, list)
-
-const serviceName = 'TestApp', scriptPath = 'D:\\test\\dev.js', // 请根据实际路径修改
-	svc = new Service({
-		name: serviceName,
-		description: 'Node.js 开发服务器',
-		script: scriptPath,
-		nodeOptions: ['--harmony', '--max-old-space-size=4096'],
-		env: { name: "NODE_ENV", value: "production" },
-	});
-
-const installService = () => {
-	console.log('🚀 开始安装服务...');
-	svc.on('install', () => svc.start());
-	svc.on('start', () => console.log('✅ 安装成功,服务已启动!!'));
-	svc.install();
-}
-installService();