@quicktvui/web-cli 1.0.7 → 2.1.0

package/lib/BundleWatcher.js

@@ -0,0 +1,192 @@
+/**
+ * BundleWatcher - 监听 dist/dev 目录变化，检测 bundle 文件就绪
+ *
+ * 职责：
+ *   1. 监听 dist/dev 目录的文件变化
+ *   2. 检测 index.bundle 入口文件是否就绪
+ *   3. 文件变化时通知回调
+ *   4. 支持防抖，避免频繁触发
+ */
+
+const chokidar = require('chokidar')
+const path = require('path')
+const fs = require('fs')
+const signale = require('signale')
+
+class BundleWatcher {
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot
+    this.distDir = path.join(projectRoot, 'dist', 'dev')
+    this.watcher = null
+    this.bundleEntry = null
+    this.onChange = options.onChange || null
+    this.onReady = options.onReady || null
+    this.debounceMs = options.debounceMs || 800
+    this._debounceTimer = null
+  }
+
+  /**
+   * 检测 bundle 入口文件
+   */
+  detectBundleEntry() {
+    if (!fs.existsSync(this.distDir)) {
+      return null
+    }
+
+    // 优先查找 index.bundle
+    const indexPath = path.join(this.distDir, 'index.bundle')
+    if (fs.existsSync(indexPath)) {
+      return 'index.bundle'
+    }
+
+    // 兼容 index.android.js
+    const androidPath = path.join(this.distDir, 'index.android.js')
+    if (fs.existsSync(androidPath)) {
+      return 'index.android.js'
+    }
+
+    return null
+  }
+
+  /**
+   * 获取 bundle 的完整 URL 路径（相对于服务器根目录）
+   */
+  getBundleUrlPath() {
+    const entry = this.detectBundleEntry()
+    if (!entry) return null
+    return `/dist/dev/${entry}`
+  }
+
+  /**
+   * 获取所有 bundle 文件列表
+   */
+  listBundleFiles() {
+    if (!fs.existsSync(this.distDir)) {
+      return []
+    }
+
+    const files = []
+    const entries = fs.readdirSync(this.distDir)
+
+    for (const entry of entries) {
+      const fullPath = path.join(this.distDir, entry)
+      const stat = fs.statSync(fullPath)
+
+      if (stat.isFile()) {
+        files.push({
+          name: entry,
+          path: fullPath,
+          size: stat.size,
+          mtime: stat.mtime,
+          urlPath: `/dist/dev/${entry}`,
+          isEntry: entry === 'index.bundle' || entry === 'index.android.js',
+        })
+      }
+    }
+
+    return files
+  }
+
+  /**
+   * 启动监听
+   */
+  start() {
+    // 确保 dist 目录存在
+    if (!fs.existsSync(this.distDir)) {
+      fs.mkdirSync(this.distDir, { recursive: true })
+      signale.info(`创建 dist/dev 目录: ${this.distDir}`)
+    }
+
+    // 先检测已有 bundle
+    const existingEntry = this.detectBundleEntry()
+    if (existingEntry) {
+      this.bundleEntry = existingEntry
+      signale.success(`检测到已有构建产物: dist/dev/${existingEntry}`)
+    }
+
+    // 启动 chokidar 监听
+    this.watcher = chokidar.watch(this.distDir, {
+      ignored: [/node_modules/, /\.DS_Store/, /Thumbs\.db/],
+      ignoreInitial: true,
+      persistent: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 300,
+        pollInterval: 100,
+      },
+    })
+
+    this.watcher.on('add', (filePath) => this._handleFileChange(filePath, 'add'))
+    this.watcher.on('change', (filePath) => this._handleFileChange(filePath, 'change'))
+    this.watcher.on('unlink', (filePath) => this._handleFileChange(filePath, 'unlink'))
+
+    this.watcher.on('ready', () => {
+      signale.info('BundleWatcher 已就绪，正在监听 dist/dev/ 目录变化...')
+      if (this.onReady) this.onReady()
+    })
+
+    this.watcher.on('error', (error) => {
+      signale.error('BundleWatcher 错误:', error.message)
+    })
+  }
+
+  /**
+   * 处理文件变化
+   */
+  _handleFileChange(filePath, eventType) {
+    const relativePath = path.relative(this.distDir, filePath)
+    const isBundle = this._isBundleFile(filePath)
+
+    if (isBundle) {
+      // 检测入口文件
+      const entry = this.detectBundleEntry()
+      if (entry && entry !== this.bundleEntry) {
+        this.bundleEntry = entry
+        signale.success(`检测到 bundle 入口: dist/dev/${entry}`)
+      }
+
+      // 防抖通知
+      clearTimeout(this._debounceTimer)
+      this._debounceTimer = setTimeout(() => {
+        signale.info(`文件变化: ${relativePath} (${eventType})`)
+        if (this.onChange) {
+          this.onChange({
+            type: eventType,
+            file: relativePath,
+            fullPath: filePath,
+            isBundle: true,
+            isEntry: relativePath === 'index.bundle' || relativePath === 'index.android.js',
+            bundleEntry: this.detectBundleEntry(),
+            bundleUrlPath: this.getBundleUrlPath(),
+          })
+        }
+      }, this.debounceMs)
+    }
+  }
+
+  /**
+   * 判断是否为 bundle 文件
+   */
+  _isBundleFile(filePath) {
+    const basename = path.basename(filePath)
+    return (
+      basename.endsWith('.bundle') ||
+      basename.endsWith('.js') ||
+      basename.endsWith('.map') ||
+      /assets[\\/]/.test(filePath)
+    )
+  }
+
+  /**
+   * 停止监听
+   */
+  stop() {
+    clearTimeout(this._debounceTimer)
+    if (this.watcher) {
+      this.watcher.close()
+      this.watcher = null
+      signale.info('BundleWatcher 已停止')
+    }
+  }
+}
+
+module.exports = BundleWatcher

package/lib/DevBuildManager.js

@@ -0,0 +1,295 @@
+/**
+ * DevBuildManager - 管理项目的 dev 构建进程
+ *
+ * 职责：
+ *   1. 检测项目的 dev 脚本
+ *   2. 调用 npm run dev 启动构建
+ *   3. 监听子进程 stdout/stderr，检测构建就绪信号
+ *   4. 管理子进程生命周期（启动/停止/重启）
+ */
+
+const { spawn } = require('child_process')
+const path = require('path')
+const fs = require('fs')
+const signale = require('signale')
+
+// 构建就绪的检测关键词（不区分大小写匹配）
+// 匹配 webpack 4/5 / qt-dev / hippy-debug-server 的各种输出格式
+const READY_SIGNALS = [
+  'webpack compiled',
+  'compiled successfully',
+  'compiled with warnings',
+  'webpack build is watching',
+  // webpack 4 输出: "webpack is watching the files…"
+  'watching the files',
+  // webpack 输出 "[built]" 标记（如：[./src/routes.js] 3.19 KiB {index} [built]）
+  '] [built]',
+  // hidden modules 输出（webpack 编译完成的最终行）
+  'hidden modules',
+  // qt-dev / hippy-debug-server 的输出
+  'bundle is valid',
+  'bundle created',
+]
+
+// 编译成功但进程因非编译原因退出的信号（如 adb 连接失败）
+// 这些信号表明编译已完成，不应重启进程
+const COMPILATION_DONE_SIGNALS = ['[built]', 'hidden modules', 'bundle is valid', 'bundle created']
+
+class DevBuildManager {
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot
+    this.pkg = options.pkg || {}
+    this.childProcess = null
+    this.isReady = false
+    this.onReady = options.onReady || null
+    this.onOutput = options.onOutput || null
+    this.onError = options.onError || null
+    this.devScriptName = options.devScript || 'dev'
+    this._restartCount = 0
+    this._maxRestarts = 3
+  }
+
+  /**
+   * 检测项目可用的 dev 脚本
+   */
+  detectDevScript() {
+    const scripts = this.pkg.scripts || {}
+
+    // 按优先级检测
+    const candidates = [this.devScriptName, 'dev', 'dev:android', 'build:dev']
+    for (const name of candidates) {
+      if (scripts[name]) {
+        return { name, script: scripts[name] }
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * 检测 dist/dev 目录是否已有构建产物
+   */
+  detectExistingBundle() {
+    const distDevDir = path.join(this.projectRoot, 'dist', 'dev')
+
+    if (!fs.existsSync(distDevDir)) {
+      return null
+    }
+
+    // 查找 index.bundle
+    const indexPath = path.join(distDevDir, 'index.bundle')
+    if (fs.existsSync(indexPath)) {
+      const stat = fs.statSync(indexPath)
+      return {
+        entry: 'index.bundle',
+        path: indexPath,
+        size: stat.size,
+        mtime: stat.mtime,
+      }
+    }
+
+    // 查找 index.android.js (兼容旧模式)
+    const androidPath = path.join(distDevDir, 'index.android.js')
+    if (fs.existsSync(androidPath)) {
+      const stat = fs.statSync(androidPath)
+      return {
+        entry: 'index.android.js',
+        path: androidPath,
+        size: stat.size,
+        mtime: stat.mtime,
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * 启动 dev 构建
+   */
+  start() {
+    const devScript = this.detectDevScript()
+    if (!devScript) {
+      signale.error('项目未配置 dev 脚本，请在 package.json 中添加 "dev" 脚本')
+      signale.error('示例: "dev": "qt-dev android -c ./scripts/quicktvui-webpack.dev.ts"')
+      return Promise.reject(new Error('No dev script found'))
+    }
+
+    signale.info(`检测到 dev 脚本: npm run ${devScript.name} → ${devScript.script}`)
+
+    return new Promise((resolve, reject) => {
+      this._startProcess(devScript.name, resolve, reject)
+    })
+  }
+
+  /**
+   * 启动子进程
+   */
+  _startProcess(scriptName, resolve, reject) {
+    const isWindows = process.platform === 'win32'
+    const cmd = isWindows ? 'npm.cmd' : 'npm'
+    const args = ['run', scriptName]
+
+    signale.pending(`正在启动 dev 构建: npm run ${scriptName} ...`)
+
+    this.childProcess = spawn(cmd, args, {
+      cwd: this.projectRoot,
+      stdio: 'pipe',
+      shell: isWindows,
+      env: {
+        ...process.env,
+        NODE_ENV: 'development',
+        FORCE_COLOR: '1',
+        // 阻止 webpack-dev-server 自动打开浏览器
+        // web-cli 自己管理浏览器打开逻辑
+        BROWSER: 'none',
+      },
+    })
+
+    let stdoutBuffer = ''
+    let stderrBuffer = ''
+    let resolved = false
+
+    // 去除 ANSI 颜色码的正则（用于构建就绪信号检测）
+    const ANSI_REGEX = /\x1b\[[0-9;]*[a-zA-Z]/g
+
+    this.childProcess.stdout.on('data', (data) => {
+      const text = data.toString()
+      stdoutBuffer += text
+
+      // 输出到控制台
+      if (this.onOutput) {
+        this.onOutput(text, 'stdout')
+      } else {
+        process.stdout.write(text)
+      }
+
+      // 检测构建就绪信号（不区分大小写）
+      // 先去除 ANSI 颜色码再匹配，避免颜色码将关键词截断
+      if (!resolved && !this.isReady) {
+        const cleanBuffer = stdoutBuffer.replace(ANSI_REGEX, '')
+        const lowerBuffer = cleanBuffer.toLowerCase()
+        for (const signal of READY_SIGNALS) {
+          if (lowerBuffer.includes(signal.toLowerCase())) {
+            this.isReady = true
+            resolved = true
+            signale.success('dev 构建已完成，bundle 已就绪')
+            if (this.onReady) this.onReady()
+            resolve()
+            break
+          }
+        }
+      }
+    })
+
+    this.childProcess.stderr.on('data', (data) => {
+      const text = data.toString()
+      stderrBuffer += text
+
+      if (this.onOutput) {
+        this.onOutput(text, 'stderr')
+      } else {
+        process.stderr.write(text)
+      }
+    })
+
+    this.childProcess.on('error', (err) => {
+      signale.error('dev 构建进程启动失败:', err.message)
+      if (this.onError) this.onError(err)
+      if (!resolved) {
+        resolved = true
+        reject(err)
+      }
+    })
+
+    this.childProcess.on('exit', (code, signal) => {
+      this.childProcess = null
+
+      if (code !== 0 && code !== null) {
+        // 检查编译是否实际已完成（即使 READY_SIGNALS 没匹配到）
+        // 场景：webpack 编译输出 "[built]" 但进程随后因 adb 等原因退出
+        const compilationDone = this.isReady || this._checkCompilationDone(stdoutBuffer)
+        const bundleExists = !!this.detectExistingBundle()
+
+        if (compilationDone && bundleExists) {
+          signale.warn(`dev 进程已退出 (code: ${code})，但编译产物已生成，web 预览不受影响`)
+          this.isReady = true
+          if (!resolved) {
+            resolved = true
+            if (this.onReady) this.onReady()
+            resolve()
+          }
+          return
+        }
+
+        signale.warn(`dev 构建进程退出 (code: ${code}, signal: ${signal})`)
+
+        // 自动重启
+        if (!resolved && this._restartCount < this._maxRestarts) {
+          this._restartCount++
+          signale.pending(`正在重启 dev 构建 (第 ${this._restartCount} 次)...`)
+          setTimeout(() => {
+            this._startProcess(scriptName, resolve, reject)
+          }, 2000)
+        } else if (!resolved) {
+          reject(new Error(`dev 构建进程异常退出 (code: ${code})`))
+        }
+      } else {
+        signale.info('dev 构建进程已退出')
+      }
+    })
+
+    // 超时检测 - 60 秒内未就绪则认为可能有问题
+    setTimeout(() => {
+      if (!resolved && !this.isReady) {
+        // 检查 dist/dev 目录是否已有产物
+        const bundle = this.detectExistingBundle()
+        if (bundle) {
+          signale.warn('未检测到构建完成信号，但发现已有构建产物，尝试使用')
+          this.isReady = true
+          resolved = true
+          resolve()
+        } else {
+          signale.warn('等待构建完成中... (可能需要较长时间)')
+        }
+      }
+    }, 60000)
+  }
+
+  /**
+   * 检查 stdout 缓冲区是否包含编译完成的信号
+   * 用于处理编译成功但进程因非编译原因（如 adb 失败）退出的情况
+   */
+  _checkCompilationDone(stdoutBuffer) {
+    const ANSI_REGEX = /\x1b\[[0-9;]*[a-zA-Z]/g
+    const cleanBuffer = stdoutBuffer.replace(ANSI_REGEX, '')
+    const lowerBuffer = cleanBuffer.toLowerCase()
+    return COMPILATION_DONE_SIGNALS.some((signal) => lowerBuffer.includes(signal.toLowerCase()))
+  }
+
+  /**
+   * 停止 dev 构建进程
+   */
+  stop() {
+    if (this.childProcess) {
+      signale.info('正在停止 dev 构建进程...')
+      this.childProcess.kill('SIGTERM')
+
+      // 强制退出
+      setTimeout(() => {
+        if (this.childProcess) {
+          this.childProcess.kill('SIGKILL')
+          this.childProcess = null
+        }
+      }, 5000)
+    }
+  }
+
+  /**
+   * 检查进程是否正在运行
+   */
+  isRunning() {
+    return this.childProcess !== null && this.childProcess.exitCode === null
+  }
+}
+
+module.exports = DevBuildManager