@mt0926/node-network-devtools 0.1.1 → 0.1.3

package/dist/esm/gui/browser-detector.js

@@ -0,0 +1,256 @@
+/**
+ * 浏览器检测器模块
+ *
+ * 跨平台检测系统已安装的浏览器（Chrome、Edge、Chromium）
+ */
+/**
+ * 浏览器类型枚举
+ */
+export var BrowserType;
+(function (BrowserType) {
+    BrowserType["Chrome"] = "chrome";
+    BrowserType["Edge"] = "edge";
+    BrowserType["Chromium"] = "chromium";
+})(BrowserType || (BrowserType = {}));
+import { existsSync } from 'fs';
+import { platform } from 'os';
+/**
+ * Windows 平台浏览器路径配置
+ */
+const WINDOWS_BROWSER_PATHS = {
+    [BrowserType.Chrome]: [
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        ...(process.env.LOCALAPPDATA
+            ? [`${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`]
+            : []),
+    ],
+    [BrowserType.Edge]: [
+        'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+        'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+    ],
+    [BrowserType.Chromium]: [
+        ...(process.env.LOCALAPPDATA
+            ? [`${process.env.LOCALAPPDATA}\\Chromium\\Application\\chrome.exe`]
+            : []),
+    ],
+};
+/**
+ * macOS 平台浏览器路径配置
+ */
+const MACOS_BROWSER_PATHS = {
+    [BrowserType.Chrome]: [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        ...(process.env.HOME
+            ? [`${process.env.HOME}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`]
+            : []),
+    ],
+    [BrowserType.Edge]: [
+        '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    ],
+    [BrowserType.Chromium]: [
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ],
+};
+/**
+ * Linux 平台浏览器路径配置
+ */
+const LINUX_BROWSER_PATHS = {
+    [BrowserType.Chrome]: [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/local/bin/google-chrome',
+        '/snap/bin/chromium',
+    ],
+    [BrowserType.Chromium]: [
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+    ],
+    [BrowserType.Edge]: [
+        '/usr/bin/microsoft-edge',
+    ],
+};
+/**
+ * 浏览器显示名称映射
+ */
+const BROWSER_NAMES = {
+    [BrowserType.Chrome]: 'Google Chrome',
+    [BrowserType.Edge]: 'Microsoft Edge',
+    [BrowserType.Chromium]: 'Chromium',
+};
+/**
+ * 浏览器优先级顺序（数字越小优先级越高）
+ */
+const BROWSER_PRIORITY = {
+    [BrowserType.Chrome]: 1,
+    [BrowserType.Edge]: 2,
+    [BrowserType.Chromium]: 3,
+};
+/**
+ * 根据当前平台获取浏览器路径配置
+ */
+function getBrowserPathsForPlatform() {
+    const currentPlatform = platform();
+    switch (currentPlatform) {
+        case 'win32':
+            return WINDOWS_BROWSER_PATHS;
+        case 'darwin':
+            return MACOS_BROWSER_PATHS;
+        case 'linux':
+            return LINUX_BROWSER_PATHS;
+        default:
+            // 未知平台，返回空配置
+            return {
+                [BrowserType.Chrome]: [],
+                [BrowserType.Edge]: [],
+                [BrowserType.Chromium]: [],
+            };
+    }
+}
+/**
+ * 检测指定类型的浏览器
+ *
+ * @param type 浏览器类型
+ * @returns 浏览器信息，如果未找到则返回 null
+ */
+function detectBrowserByType(type) {
+    const paths = getBrowserPathsForPlatform()[type];
+    for (const path of paths) {
+        if (existsSync(path)) {
+            return {
+                type,
+                path,
+                name: BROWSER_NAMES[type],
+            };
+        }
+    }
+    return null;
+}
+/**
+ * 浏览器检测器实现类
+ */
+class BrowserDetector {
+    /**
+     * 检测系统已安装的浏览器（按优先级返回第一个）
+     */
+    detect() {
+        // 优先检查自定义浏览器路径
+        const customPath = process.env.NND_BROWSER_PATH;
+        if (customPath && existsSync(customPath)) {
+            // 尝试从路径推断浏览器类型
+            const lowerPath = customPath.toLowerCase();
+            let type;
+            if (lowerPath.includes('chrome') && !lowerPath.includes('chromium')) {
+                type = BrowserType.Chrome;
+            }
+            else if (lowerPath.includes('edge') || lowerPath.includes('msedge')) {
+                type = BrowserType.Edge;
+            }
+            else {
+                type = BrowserType.Chromium;
+            }
+            return {
+                type,
+                path: customPath,
+                name: BROWSER_NAMES[type],
+            };
+        }
+        // 按优先级检测浏览器
+        const browserTypes = [
+            BrowserType.Chrome,
+            BrowserType.Edge,
+            BrowserType.Chromium,
+        ];
+        for (const type of browserTypes) {
+            const browser = detectBrowserByType(type);
+            if (browser) {
+                return browser;
+            }
+        }
+        return null;
+    }
+    /**
+     * 检测所有已安装的浏览器
+     */
+    detectAll() {
+        const browsers = [];
+        // 检查自定义浏览器路径
+        const customPath = process.env.NND_BROWSER_PATH;
+        if (customPath && existsSync(customPath)) {
+            const lowerPath = customPath.toLowerCase();
+            let type;
+            if (lowerPath.includes('chrome') && !lowerPath.includes('chromium')) {
+                type = BrowserType.Chrome;
+            }
+            else if (lowerPath.includes('edge') || lowerPath.includes('msedge')) {
+                type = BrowserType.Edge;
+            }
+            else {
+                type = BrowserType.Chromium;
+            }
+            browsers.push({
+                type,
+                path: customPath,
+                name: `${BROWSER_NAMES[type]} (自定义)`,
+            });
+        }
+        // 检测所有浏览器类型
+        const browserTypes = [
+            BrowserType.Chrome,
+            BrowserType.Edge,
+            BrowserType.Chromium,
+        ];
+        for (const type of browserTypes) {
+            const browser = detectBrowserByType(type);
+            if (browser) {
+                // 避免重复添加自定义路径的浏览器
+                if (!browsers.some(b => b.path === browser.path)) {
+                    browsers.push(browser);
+                }
+            }
+        }
+        // 按优先级排序
+        browsers.sort((a, b) => BROWSER_PRIORITY[a.type] - BROWSER_PRIORITY[b.type]);
+        return browsers;
+    }
+}
+/**
+ * 浏览器检测器单例
+ */
+let detectorInstance = null;
+/**
+ * 获取浏览器检测器单例
+ */
+export function getBrowserDetector() {
+    if (!detectorInstance) {
+        detectorInstance = new BrowserDetector();
+    }
+    return detectorInstance;
+}
+/**
+ * 创建新的浏览器检测器实例
+ */
+export function createBrowserDetector() {
+    return new BrowserDetector();
+}
+/**
+ * 检测浏览器（便捷函数）
+ *
+ * 使用单例检测器检测系统已安装的浏览器
+ *
+ * @returns 浏览器信息，如果未检测到则返回 null
+ */
+export function detectBrowser() {
+    return getBrowserDetector().detect();
+}
+/**
+ * 检测所有浏览器（便捷函数）
+ *
+ * 使用单例检测器检测所有已安装的浏览器
+ *
+ * @returns 浏览器信息数组，按优先级排序
+ */
+export function detectAllBrowsers() {
+    return getBrowserDetector().detectAll();
+}
+//# sourceMappingURL=browser-detector.js.map

package/dist/esm/gui/browser-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-detector.js","sourceRoot":"","sources":["../../../src/gui/browser-detector.ts"],"names":[],"mappings":"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"}

package/dist/esm/gui/browser-launcher.js

@@ -1,98 +1,248 @@
 /**
  * 浏览器启动器模块
  *
- * 支持使用系统默认浏览器或 Puppeteer 打开 GUI
+ * 使用原生浏览器检测和启动机制打开 GUI
  */
+import { spawn } from 'child_process';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { nanoid } from 'nanoid';
 import { getConfig } from '../config.js';
+import { detectBrowser } from './browser-detector.js';
+/**
+ * 浏览器未检测到错误
+ *
+ * 当系统中未检测到任何支持的浏览器时抛出此错误
+ */
+export class BrowserNotFoundError extends Error {
+    constructor() {
+        super('未检测到已安装的浏览器');
+        this.name = 'BrowserNotFoundError';
+        // 保持原型链正确（TypeScript 继承 Error 的最佳实践）
+        Object.setPrototypeOf(this, BrowserNotFoundError.prototype);
+    }
+}
+/**
+ * 浏览器启动失败错误
+ *
+ * 当浏览器启动过程中发生错误时抛出此错误
+ */
+export class BrowserLaunchError extends Error {
+    cause;
+    /**
+     * @param message 错误消息
+     * @param cause 原始错误（可选）
+     */
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'BrowserLaunchError';
+        // 保持原型链正确（TypeScript 继承 Error 的最佳实践）
+        Object.setPrototypeOf(this, BrowserLaunchError.prototype);
+    }
+}
 /**
  * 浏览器启动器实现
  */
 class BrowserLauncherImpl {
-    puppeteerBrowser = null;
-    puppeteerPage = null;
     isOpened = false;
     /**
      * 打开浏览器
+     *
+     * 执行以下步骤：
+     * 1. 调用 BrowserDetector.detect() 检测浏览器
+     * 2. 处理未找到浏览器的情况
+     * 3. 构建启动参数
+     * 4. 调用启动逻辑
+     * 5. 处理启动失败的情况
+     *
+     * @param url GUI 访问 URL
+     *
+     * @remarks
+     * 此方法不会抛出异常，所有错误都会被捕获并显示友好的错误消息。
+     * 这确保浏览器启动失败不会中断主进程。
+     *
+     * **验证需求：2.5, 4.1, 4.2, 4.3, 4.4, 4.5, 6.1, 6.4**
      */
     async open(url) {
-        const config = getConfig();
-        if (config.usePuppeteer) {
-            await this.openWithPuppeteer(url);
-        }
-        else {
-            await this.openWithDefaultBrowser(url);
-        }
-        this.isOpened = true;
-    }
-    /**
-     * 使用系统默认浏览器打开
-     */
-    async openWithDefaultBrowser(url) {
         try {
-            // 动态导入 open 包
-            const openModule = await import('open');
-            const open = openModule.default;
-            await open(url);
-            console.log(`[node-network-devtools] 已在默认浏览器中打开: ${url}`);
+            // 步骤 1: 调用 BrowserDetector.detect() 检测浏览器
+            const browserInfo = detectBrowser();
+            // 步骤 2: 处理未找到浏览器的情况
+            if (!browserInfo) {
+                // 浏览器未找到，显示友好提示（需求 6.1）
+                this.handleBrowserNotFound(url);
+                return;
+            }
+            // 获取配置
+            const config = getConfig();
+            const windowConfig = {
+                width: config.browserWindowSize?.width || 1280,
+                height: config.browserWindowSize?.height || 800,
+                title: config.browserWindowTitle || 'Node Network DevTools',
+            };
+            // 创建用户数据目录（需求 4.2）
+            const userDataDir = createUserDataDir();
+            // 步骤 3: 构建启动参数（需求 4.1）
+            const args = this.buildLaunchArgs({
+                url,
+                windowConfig,
+                userDataDir,
+            });
+            // 步骤 4: 调用启动逻辑（需求 4.3, 4.4, 4.5）
+            this.launchBrowser(browserInfo.path, args);
+            this.isOpened = true;
+            console.log(`[node-network-devtools] 已使用 ${browserInfo.name} 打开 GUI: ${url}`);
         }
         catch (err) {
-            console.error('[node-network-devtools] 无法打开默认浏览器:', err);
-            throw err;
+            // 步骤 5: 处理启动失败的情况（需求 6.4）
+            this.handleLaunchError(err, url);
         }
     }
     /**
-     * 使用 Puppeteer 打开
+     * 启动浏览器进程
+     *
+     * 使用 child_process.spawn() 启动浏览器，并配置为分离进程。
+     * 这样浏览器进程不会阻塞父进程，父进程退出后浏览器仍可继续运行。
+     *
+     * @param browserPath 浏览器可执行文件路径
+     * @param args 启动参数数组
+     * @throws {BrowserLaunchError} 当浏览器启动失败时抛出
+     *
+     * @remarks
+     * 进程配置：
+     * - detached: true - 进程分离，允许父进程退出（需求 4.3）
+     * - stdio: 'ignore' - 忽略标准输入输出，避免管道阻塞（需求 4.4）
+     * - child.unref() - 允许父进程退出而不等待子进程（需求 4.5）
+     *
+     * **验证需求：4.3, 4.4, 4.5**
      */
-    async openWithPuppeteer(url) {
+    launchBrowser(browserPath, args) {
         try {
-            // 动态导入 puppeteer（可选依赖）
-            const puppeteer = await import('puppeteer');
-            // 启动浏览器
-            this.puppeteerBrowser = await puppeteer.default.launch({
-                headless: false,
-                defaultViewport: null,
-                args: [
-                    '--no-sandbox',
-                    '--disable-setuid-sandbox',
-                    `--window-size=1200,800`,
-                ],
+            // 启动分离进程
+            const child = spawn(browserPath, args, {
+                detached: true, // 进程分离，允许父进程退出（需求 4.3）
+                stdio: 'ignore', // 忽略标准输入输出，避免管道阻塞（需求 4.4）
+            });
+            // 允许父进程退出而不等待子进程（需求 4.5）
+            child.unref();
+            // 监听错误事件（虽然 stdio: 'ignore'，但 spawn 本身可能失败）
+            child.on('error', (err) => {
+                throw new BrowserLaunchError(`浏览器进程启动失败: ${err.message}`, err);
             });
-            // 创建新页面
-            const browser = this.puppeteerBrowser;
-            this.puppeteerPage = await browser.newPage();
-            // 导航到 URL
-            const page = this.puppeteerPage;
-            await page.goto(url);
-            console.log(`[node-network-devtools] 已使用 Puppeteer 打开: ${url}`);
         }
         catch (err) {
-            if (err.code === 'MODULE_NOT_FOUND') {
-                console.error('[node-network-devtools] Puppeteer 未安装，请运行: pnpm add puppeteer');
-                // 回退到默认浏览器
-                console.log('[node-network-devtools] 回退到默认浏览器...');
-                await this.openWithDefaultBrowser(url);
-            }
-            else {
-                console.error('[node-network-devtools] Puppeteer 启动失败:', err);
+            // 将原始错误包装为 BrowserLaunchError
+            if (err instanceof BrowserLaunchError) {
                 throw err;
             }
+            throw new BrowserLaunchError(`无法启动浏览器: ${err.message}`, err);
+        }
+    }
+    /**
+     * 处理浏览器未找到的情况
+     *
+     * 显示友好的错误消息，包含：
+     * - 支持的浏览器列表
+     * - GUI 访问 URL（需求 6.2）
+     * - 自定义浏览器路径设置说明
+     * - 浏览器安装指引链接（需求 6.3）
+     *
+     * @param guiUrl GUI 访问 URL
+     *
+     * **验证需求：6.1, 6.2, 6.3**
+     */
+    handleBrowserNotFound(guiUrl) {
+        console.error(`
+[node-network-devtools] 未检测到已安装的浏览器
+
+支持的浏览器：
+  - Google Chrome
+  - Microsoft Edge
+  - Chromium
+
+请安装其中一个浏览器，或手动访问 GUI：
+  ${guiUrl}
+
+自定义浏览器路径：
+  export NND_BROWSER_PATH=/path/to/browser
+
+浏览器安装指引：
+  Chrome: https://www.google.com/chrome/
+  Edge: https://www.microsoft.com/edge
+  更多信息: https://github.com/dong0926/node-network-devtools#readme
+    `);
+    }
+    /**
+     * 处理浏览器启动失败的情况
+     *
+     * 显示友好的错误消息，包含：
+     * - 错误信息（需求 6.4）
+     * - 可能的原因分析
+     * - 解决方案建议（需求 6.5）
+     * - 手动访问 URL 提示
+     *
+     * @param err 错误对象
+     * @param guiUrl GUI 访问 URL
+     *
+     * **验证需求：6.4, 6.5**
+     */
+    handleLaunchError(err, guiUrl) {
+        console.error(`
+[node-network-devtools] 浏览器启动失败
+
+错误信息：${err.message}
+
+可能的原因：
+  1. 浏览器路径无效
+  2. 权限不足
+  3. 系统资源不足
+
+解决方案：
+  - 手动访问 GUI: ${guiUrl}
+  - 设置 NND_AUTO_OPEN=false 禁用自动打开
+  - 检查浏览器是否正确安装
+  - 尝试设置自定义浏览器路径: export NND_BROWSER_PATH=/path/to/browser
+    `);
+    }
+    /**
+     * 构建浏览器启动参数
+     *
+     * @param options 启动选项
+     * @returns Chrome 命令行参数数组
+     */
+    buildLaunchArgs(options) {
+        const { url, windowConfig, userDataDir } = options;
+        const args = [
+            // App 模式（极简窗口，无地址栏和工具栏）
+            `--app=${url}`,
+            // 窗口大小
+            `--window-size=${windowConfig.width},${windowConfig.height}`,
+        ];
+        // 用户数据目录（如果提供）
+        if (userDataDir) {
+            args.push(`--user-data-dir=${userDataDir}`);
         }
+        // 优化参数
+        args.push('--no-first-run', // 跳过首次运行向导
+        '--no-default-browser-check', // 跳过默认浏览器检查
+        '--disable-extensions', // 禁用扩展
+        '--disable-sync', // 禁用同步
+        '--disable-background-networking', // 禁用后台网络请求
+        '--disable-features=TranslateUI', // 禁用翻译 UI
+        '--disable-component-extensions-with-background-pages', '--disable-default-apps', // 禁用默认应用
+        '--mute-audio', // 静音
+        // 性能优化
+        '--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding', '--disable-background-timer-throttling', 
+        // 安全相关（某些环境需要）
+        '--no-sandbox', '--disable-setuid-sandbox');
+        return args;
     }
     /**
      * 关闭浏览器
      */
     async close() {
-        if (this.puppeteerBrowser) {
-            try {
-                const browser = this.puppeteerBrowser;
-                await browser.close();
-            }
-            catch {
-                // 忽略关闭错误
-            }
-            this.puppeteerBrowser = null;
-            this.puppeteerPage = null;
-        }
+        // TODO: 实现浏览器关闭逻辑（注：由于进程分离，实际无法关闭）
         this.isOpened = false;
     }
     /**
@@ -137,23 +287,9 @@ export function buildGUIUrl(host, guiPort, wsPort) {
 /**
  * 打开浏览器（便捷函数）
  */
-export async function openBrowser(url, options) {
+export async function openBrowser(url) {
     const launcher = getBrowserLauncher();
-    // 如果指定了 usePuppeteer，临时修改配置
-    if (options?.usePuppeteer !== undefined) {
-        const { setConfig, getConfig } = await import('../config.js');
-        const originalConfig = getConfig();
-        setConfig({ usePuppeteer: options.usePuppeteer });
-        try {
-            await launcher.open(url);
-        }
-        finally {
-            setConfig({ usePuppeteer: originalConfig.usePuppeteer });
-        }
-    }
-    else {
-        await launcher.open(url);
-    }
+    await launcher.open(url);
 }
 /**
  * 关闭浏览器（便捷函数）
@@ -162,4 +298,55 @@ export async function closeBrowser() {
     const launcher = getBrowserLauncher();
     await launcher.close();
 }
+/**
+ * 构建浏览器启动参数（导出用于测试）
+ *
+ * @param options 启动选项
+ * @returns Chrome 命令行参数数组
+ */
+export function buildLaunchArgs(options) {
+    const { url, windowConfig, userDataDir } = options;
+    const args = [
+        // App 模式（极简窗口，无地址栏和工具栏）
+        `--app=${url}`,
+        // 窗口大小
+        `--window-size=${windowConfig.width},${windowConfig.height}`,
+    ];
+    // 用户数据目录（如果提供）
+    if (userDataDir) {
+        args.push(`--user-data-dir=${userDataDir}`);
+    }
+    // 优化参数
+    args.push('--no-first-run', // 跳过首次运行向导
+    '--no-default-browser-check', // 跳过默认浏览器检查
+    '--disable-extensions', // 禁用扩展
+    '--disable-sync', // 禁用同步
+    '--disable-background-networking', // 禁用后台网络请求
+    '--disable-features=TranslateUI', // 禁用翻译 UI
+    '--disable-component-extensions-with-background-pages', '--disable-default-apps', // 禁用默认应用
+    '--mute-audio', // 静音
+    // 性能优化
+    '--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding', '--disable-background-timer-throttling', 
+    // 安全相关（某些环境需要）
+    '--no-sandbox', '--disable-setuid-sandbox');
+    return args;
+}
+/**
+ * 创建用户数据目录路径
+ *
+ * 生成一个唯一的临时目录路径用于浏览器用户数据。
+ * 使用 nanoid 生成 8 位随机 ID 确保每次启动都使用独立的会话。
+ *
+ * @returns 用户数据目录的完整路径，格式：`{tmpdir}/nnd-browser-{sessionId}`
+ *
+ * @example
+ * ```typescript
+ * const userDataDir = createUserDataDir();
+ * // 返回类似：/tmp/nnd-browser-a1b2c3d4
+ * ```
+ */
+export function createUserDataDir() {
+    const sessionId = nanoid(8);
+    return join(tmpdir(), `nnd-browser-${sessionId}`);
+}
 //# sourceMappingURL=browser-launcher.js.map