@gylautorun/dev-proxy-cookie 1.0.1 → 1.0.2

package/src/proxy/vue-proxy-config.ts

@@ -1,3 +1,11 @@
+/**
+ * Vue CLI 代理配置模块
+ * 
+ * 提供 Vue CLI 开发服务器的代理配置功能，支持从文件读取 Cookie 并注入代理请求。
+ * 核心函数包括 createFileCookieGetter 和 createVueProxyConfig。
+ * 
+ * @module vue-proxy-config
+ */
 import type { IncomingMessage } from 'http';
 import * as path from 'path';
 import { CookieReader, watchCookieFile, shouldEnableWatch } from '../utils';
@@ -34,27 +42,57 @@ export interface CreateFileCookieGetterOptions {
   isDev?: boolean;
 }
 
+/**
+ * Vue 代理配置选项
+ */
 export interface VueProxyConfigOptions {
+  /** Cookie 获取函数 */
   getCookie?: () => string;
+  /** 是否输出调试日志 */
   debug?: boolean;
+  /** 自定义请求头 */
   headers?: Record<string, string>;
+  /** 是否启用 WebSocket 代理 */
   ws?: boolean;
+  /** 是否修改请求头中的 Origin */
   changeOrigin?: boolean;
+  /** 是否验证 SSL 证书 */
   secure?: boolean;
+  /** 错误回调函数 */
   onError?: (err: Error) => void;
 }
 
+/**
+ * Vue CLI 代理配置接口
+ * 
+ * 符合 Vue CLI 代理配置格式的对象结构
+ */
 export interface ProxyConfig {
+  /** 是否启用 WebSocket 代理 */
   ws: boolean;
+  /** 代理目标地址 */
   target: string;
+  /** 是否修改请求头中的 Origin */
   changeOrigin: boolean;
+  /** 是否验证 SSL 证书 */
   secure: boolean;
+  /** 代理请求前的回调函数 */
   onProxyReq: (proxyReq: any, req: IncomingMessage) => void;
+  /** 代理响应后的回调函数（可选） */
   onProxyRes?: (proxyRes: any, req: IncomingMessage) => void;
+  /** 错误处理回调函数 */
   onError: (err: Error) => void;
+  /** 自定义请求头 */
   headers?: Record<string, string>;
 }
 
+/**
+ * 创建 Vue CLI 代理配置
+ * 
+ * @param target - 代理目标地址
+ * @param options - 配置选项
+ * @returns Vue CLI 代理配置对象
+ */
 export function createVueProxyConfig(
   target: string,
   options: VueProxyConfigOptions = {}
@@ -93,17 +131,26 @@ export function createVueProxyConfig(
   return config;
 }
 
+/**
+ * 创建文件 Cookie 获取器
+ * 
+ * 从指定文件读取 Cookie 值，支持文件监听功能。
+ * 
+ * @param cookieFile - Cookie 文件路径
+ * @param options - 配置选项
+ * @returns Cookie 获取函数
+ */
 export function createFileCookieGetter(
   cookieFile: string,
   options: CreateFileCookieGetterOptions = {}
 ): () => string {
   const { 
     watch = 'auto', 
-    debug = false,
+    debug = true,
     productionEnvs = [],
     isDev 
   } = options;
-  const reader = new CookieReader({ cookieFile: path.resolve(cookieFile) });
+  const reader = new CookieReader({ cookieFile: path.resolve(cookieFile) }, debug);
 
   // 判断是否应该启用监听
   // isDev 参数优先级最高，直接决定是否启用监听
@@ -139,13 +186,28 @@ export function createFileCookieGetter(
   return () => reader.readCookie();
 }
 
+/**
+ * 自动代理配置选项
+ */
 export interface AutoProxyConfigOptions extends VueProxyConfigOptions {
+  /** 代理目标地址 */
   target: string;
+  /** 忽略的路径列表（不代理这些路径） */
   ignorePaths?: string[];
+  /** 包含的路径列表（只代理这些路径） */
   includePaths?: string[];
+  /** 额外的代理配置 */
   additionalProxies?: Record<string, string>;
 }
 
+/**
+ * 创建自动代理配置
+ * 
+ * 根据配置自动生成 Vue CLI 代理配置对象，支持忽略路径和包含路径两种模式。
+ * 
+ * @param options - 配置选项
+ * @returns Vue CLI 代理配置对象映射
+ */
 export function createAutoProxyConfig(options: AutoProxyConfigOptions): Record<string, ProxyConfig> {
   const { target, ignorePaths = [], includePaths = [], additionalProxies = {}, getCookie, debug, headers } = options;
 

package/src/utils/cookie-reader.ts

@@ -1,39 +1,102 @@
+/**
+ * Cookie 文件读取器模块
+ * 
+ * 提供从文件读取 Cookie 的功能，支持注释过滤和自动文件创建。
+ * 
+ * @module cookie-reader
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 
+/**
+ * Cookie 读取器配置选项
+ */
 export interface CookieReaderOptions {
   cookieFile: string;
   encoding?: BufferEncoding;
 }
 
+/**
+ * Cookie 文件读取器类
+ * 
+ * 提供从文件读取 Cookie 的功能，支持注释过滤和自动文件创建。
+ */
 export class CookieReader {
+  /** 配置选项 */
   protected options: CookieReaderOptions;
+  /** 是否启用调试模式 */
+  protected debug: boolean;
 
-  constructor(options: CookieReaderOptions) {
+  /**
+   * 构造函数
+   * @param options - 配置选项
+   * @param debug - 是否启用调试模式
+   */
+  constructor(options: CookieReaderOptions, debug: boolean = false) {
     this.options = {
       encoding: 'utf-8',
       ...options,
     };
+    this.debug = debug;
   }
 
+  /**
+   * 读取 Cookie 文件内容
+   * 
+   * 支持过滤注释行（以 # 开头）和空行，将有效行用分号连接。
+   * 
+   * @returns Cookie 字符串
+   */
   readCookie(): string {
     try {
       const filePath = path.resolve(this.options.cookieFile);
+      
+      if (this.debug) {
+        console.log('[CookieReader] Resolved cookie file path:', filePath);
+        console.log('[CookieReader] File exists:', fs.existsSync(filePath));
+      }
+      
       if (fs.existsSync(filePath)) {
         const content = fs.readFileSync(filePath, this.options.encoding || 'utf-8');
+        
+        if (this.debug) {
+          console.log('[CookieReader] File content length:', content.length);
+        }
+        
         // 过滤注释行（以 # 开头）和空行，然后合并成一行
         const lines = content.split('\n');
         const cookieLines = lines
           .map(line => line.trim())
           .filter(line => line && !line.startsWith('#'));
-        return cookieLines.join('; ');
+        
+        const result = cookieLines.join('; ');
+        
+        if (this.debug) {
+          console.log('[CookieReader] Parsed cookie:', result ? '(has cookie)' : '(empty)');
+        }
+        
+        return result;
+      }
+      
+      if (this.debug) {
+        console.log('[CookieReader] Cookie file not found:', filePath);
       }
+      
       return '';
-    } catch {
+    } catch (err) {
+      if (this.debug) {
+        console.error('[CookieReader] Error reading cookie file:', (err as Error).message);
+      }
       return '';
     }
   }
 
+  /**
+   * 确保 Cookie 文件存在
+   * 
+   * 如果文件不存在，会自动创建空文件。
+   * 如果父目录不存在，会自动创建目录。
+   */
   ensureCookieFile(): void {
     const filePath = path.resolve(this.options.cookieFile);
     const dir = path.dirname(filePath);
@@ -48,6 +111,14 @@ export class CookieReader {
   }
 }
 
+/**
+ * 创建 Cookie 获取器函数
+ * 
+ * 返回一个函数，每次调用时从文件读取最新的 Cookie 值。
+ * 
+ * @param cookieFile - Cookie 文件路径
+ * @returns Cookie 获取函数
+ */
 export function createCookieGetter(cookieFile: string): () => string {
   const reader = new CookieReader({ cookieFile });
   return () => reader.readCookie();

package/src/utils/cookie-watcher.ts

@@ -1,8 +1,19 @@
+/**
+ * Cookie 文件监听器模块
+ * 
+ * 使用 chokidar 监听 Cookie 文件变化，当文件内容改变时触发回调。
+ * 支持自动创建文件和稳定性阈值配置。
+ * 
+ * @module cookie-watcher
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import chokidar, { FSWatcher } from 'chokidar';
 import { CookieReader } from './cookie-reader';
 
+/**
+ * Cookie 监听器配置选项
+ */
 export interface CookieWatcherOptions {
   cookieFile: string;
   onCookieChange: (cookie: string) => void;
@@ -10,12 +21,26 @@ export interface CookieWatcherOptions {
   autoCreateFile?: boolean;
 }
 
+/**
+ * Cookie 文件监听器类
+ * 
+ * 使用 chokidar 监听 Cookie 文件变化，当文件内容改变时触发回调。
+ * 支持自动创建文件和稳定性阈值配置。
+ */
 export class CookieWatcher {
+  /** 文件监听器实例 */
   private watcher: FSWatcher | null = null;
+  /** 配置选项 */
   private options: CookieWatcherOptions;
+  /** Cookie 读取器 */
   private cookieReader: CookieReader;
+  /** 上次读取的 Cookie 内容 */
   private lastContent: string = '';
 
+  /**
+   * 构造函数
+   * @param options - 配置选项
+   */
   constructor(options: CookieWatcherOptions) {
     this.options = {
       autoCreateFile: true,
@@ -24,6 +49,11 @@ export class CookieWatcher {
     this.cookieReader = new CookieReader({ cookieFile: options.cookieFile });
   }
 
+  /**
+   * 文件变化处理函数
+   * 
+   * 读取新的 Cookie 内容，如果与上次不同则触发回调。
+   */
   private handleChange = (): void => {
     const newContent = this.cookieReader.readCookie();
     if (newContent !== this.lastContent) {
@@ -33,6 +63,9 @@ export class CookieWatcher {
     }
   };
 
+  /**
+   * 启动文件监听
+   */
   start(): void {
     if (this.options.autoCreateFile) {
       this.cookieReader.ensureCookieFile();
@@ -52,7 +85,8 @@ export class CookieWatcher {
         },
       });
 
-      // "add" covers atomic replace (unlink + rename) used by some editors; "change" covers in-place writes
+      // "add" covers atomic replace (unlink + rename) used by some editors; 
+      // "change" covers in-place writes
       this.watcher.on('change', this.handleChange);
       this.watcher.on('add', this.handleChange);
       this.watcher.on('error', (error) => {
@@ -63,6 +97,9 @@ export class CookieWatcher {
     }
   }
 
+  /**
+   * 停止文件监听
+   */
   stop(): void {
     if (this.watcher) {
       this.watcher.close();
@@ -71,11 +108,23 @@ export class CookieWatcher {
     }
   }
 
+  /**
+   * 获取当前 Cookie 值
+   * @returns 当前 Cookie 字符串
+   */
   getCurrentCookie(): string {
     return this.lastContent;
   }
 }
 
+/**
+ * 创建并启动 Cookie 文件监听器
+ * 
+ * @param cookieFile - Cookie 文件路径
+ * @param onCookieChange - Cookie 变化回调函数
+ * @param onError - 错误回调函数（可选）
+ * @returns CookieWatcher 实例
+ */
 export function watchCookieFile(
   cookieFile: string,
   onCookieChange: (cookie: string) => void,

package/src/utils/env-detector.ts

@@ -1,10 +1,17 @@
 /**
- * 环境检测工具函数
- * 用于智能判断当前是否为生产构建环境
+ * 环境检测工具模块
+ * 
+ * 提供智能环境检测功能，用于判断当前是否为生产构建环境，
+ * 从而决定是否启用文件监听等开发环境特性。
+ * 
+ * @module env-detector
  */
 
 /**
  * 判断环境变量值是否表示生产环境
+ * 
+ * @param value - 环境变量值
+ * @returns 是否为生产环境值
  */
 export function isProductionValue(value: string): boolean {
   const productionValues = [

package/src/utils/index.ts

@@ -1,3 +1,10 @@
+/**
+ * 工具模块导出文件
+ * 
+ * 包含 Cookie 读取、文件监听和环境检测等核心工具函数。
+ * 
+ * @module utils
+ */
 export * from './cookie-reader';
 export * from './cookie-watcher';
 export * from './env-detector';

package/src/proxy/vite-adapter.ts

@@ -1,98 +0,0 @@
-import type { Plugin } from 'vite';
-import { viteAutoProxyCookie, type ViteAutoProxyCookiePluginOptions } from './vite-plugin';
-import { viteDevProxyCookie, type ViteDevProxyCookieOptions } from './vite-cookie-plugin';
-
-let viteVersion: string = '';
-let majorVersion: number | null = null;
-
-function detectViteVersion(): number {
-  if (majorVersion !== null) {
-    return majorVersion;
-  }
-
-  try {
-    const pkg = require('vite/package.json');
-    viteVersion = pkg.version;
-    majorVersion = parseInt(viteVersion.split('.')[0], 10);
-  } catch {
-    majorVersion = 5;
-  }
-
-  return majorVersion;
-}
-
-export interface UnifiedProxyCookieOptions {
-  cookieFile: string;
-  target?: string;
-  debug?: boolean;
-  autoRestart?: boolean;
-  restartMarkerFile?: string;
-  proxyMap?: Record<string, string>;
-  ignorePaths?: string[];
-  includePaths?: string[];
-  onCookieChange?: (cookie: string) => void;
-  mode?: 'auto' | 'proxy' | 'cookie';
-  /**
-   * 是否监听文件变化
-   * - true: 始终监听
-   * - false: 从不监听
-   * - 'auto': 根据环境自动判断（默认）
-   * @default 'auto'
-   */
-  watch?: boolean | 'auto';
-  /**
-   * 是否为开发环境（优先级最高）
-   * 设置此参数后，将直接决定是否启用文件监听：
-   * - true: 启用监听（开发模式）
-   * - false: 禁用监听（生产模式）
-   * 
-   * 使用示例: isDev: process.env.NODE_ENV === 'development'
-   */
-  isDev?: boolean;
-}
-
-export function createDevProxyCookie(options: UnifiedProxyCookieOptions): Plugin {
-  const {
-    mode = 'auto',
-    watch = 'auto',
-    isDev,
-    ...restOptions
-  } = options;
-
-  const version = detectViteVersion();
-  
-  if (options.debug) {
-    console.log(`[dev-proxy-cookie] Detected Vite ${version}.x`);
-  }
-
-  if (mode === 'cookie' || (mode === 'auto' && !options.target)) {
-    return viteDevProxyCookie({
-      cookieFile: options.cookieFile,
-      debug: options.debug,
-      onCookieChange: options.onCookieChange,
-      watch,
-      isDev,
-    });
-  }
-
-  const pluginOptions: ViteAutoProxyCookiePluginOptions = {
-    cookieFile: options.cookieFile,
-    target: options.target!,
-    debug: options.debug,
-    autoRestart: options.autoRestart ?? true,
-    restartMarkerFile: options.restartMarkerFile,
-    proxyMap: options.proxyMap,
-    ignorePaths: options.ignorePaths,
-  };
-
-  return viteAutoProxyCookie(pluginOptions);
-}
-
-export function getViteVersion(): string | null {
-  detectViteVersion();
-  return viteVersion;
-}
-
-export function getViteMajorVersion(): number {
-  return detectViteVersion();
-}

package/src/proxy/vite-cookie-plugin.ts

@@ -1,94 +0,0 @@
-import type { Plugin, ViteDevServer } from 'vite';
-import { CookieReader, watchCookieFile, shouldEnableWatch } from '../utils';
-
-export interface ViteDevProxyCookieOptions {
-  cookieFile: string;
-  debug?: boolean;
-  onCookieChange?: (cookie: string) => void;
-  /**
-   * 是否监听文件变化
-   * - true: 始终监听
-   * - false: 从不监听
-   * - 'auto': 根据环境自动判断（默认）
-   * @default 'auto'
-   */
-  watch?: boolean | 'auto';
-  /**
-   * 是否为开发环境（优先级最高）
-   * 设置此参数后，将直接决定是否启用文件监听：
-   * - true: 启用监听（开发模式）
-   * - false: 禁用监听（生产模式）
-   * 
-   * 使用示例: isDev: process.env.NODE_ENV === 'development'
-   */
-  isDev?: boolean;
-}
-
-export function viteDevProxyCookie(options: ViteDevProxyCookieOptions): Plugin {
-  const { cookieFile, debug = false, onCookieChange, watch = 'auto', isDev } = options;
-  let watcher: any = null;
-  let currentCookie: string = '';
-
-  const cookieReader = new CookieReader({ cookieFile });
-
-  return {
-    name: 'vite-dev-proxy-cookie',
-    apply: 'serve',
-
-    configureServer(server: ViteDevServer) {
-      currentCookie = cookieReader.readCookie();
-      if (debug) {
-        console.log('[vite-dev-proxy-cookie] Initial cookie loaded');
-      }
-
-      const middlewares = server.middlewares || 
-        (server as any)._middlewares || 
-        (server as any).app;
-
-      if (middlewares && typeof middlewares.use === 'function') {
-        middlewares.use((req: any, _res: any, next: any) => {
-          if (currentCookie && req.url?.startsWith('/')) {
-            req.headers = req.headers || {};
-            req.headers['cookie'] = currentCookie;
-          }
-          next();
-        });
-      } else {
-        console.warn('[vite-dev-proxy-cookie] Could not access middleware stack, cookie injection disabled');
-      }
-
-      // 判断是否应该启用监听
-      // isDev 参数优先级最高
-      let shouldWatch: boolean;
-      
-      if (isDev !== undefined) {
-        shouldWatch = isDev;
-        if (debug) {
-          console.log(`[vite-dev-proxy-cookie] isDev=${isDev}, ${shouldWatch ? 'enabling' : 'disabling'} watch`);
-        }
-      } else {
-        shouldWatch = shouldEnableWatch(watch, [], debug, '[vite-dev-proxy-cookie]');
-      }
-      
-      if (shouldWatch) {
-        watcher = watchCookieFile(
-          cookieFile,
-          (newCookie) => {
-            currentCookie = newCookie;
-            onCookieChange?.(newCookie);
-            console.log('[vite-dev-proxy-cookie] Cookie changed, please restart server for full effect');
-          },
-          (error) => {
-            console.error('[vite-dev-proxy-cookie] Watch error:', error.message);
-          }
-        );
-      } else if (debug) {
-        console.log('[vite-dev-proxy-cookie] File watch disabled');
-      }
-    },
-
-    closeBundle() {
-      watcher?.stop();
-    },
-  };
-}

package/src/proxy/vite-plugin.ts

@@ -1,66 +0,0 @@
-import type { Plugin, ViteDevServer } from 'vite';
-import { AutoProxyCookie, createAutoProxyCookie, type AutoProxyCookieOptions } from './core';
-
-export interface ViteAutoProxyCookiePluginOptions extends AutoProxyCookieOptions {
-  name?: string;
-  /**
-   * 是否为开发环境（优先级最高）
-   * 设置此参数后，将直接决定是否启用文件监听：
-   * - true: 启用监听（开发模式）
-   * - false: 禁用监听（生产模式）
-   * 
-   * 使用示例: isDev: process.env.NODE_ENV === 'development'
-   */
-  isDev?: boolean;
-}
-
-function getHttpServer(server: ViteDevServer): any {
-  if ('httpServer' in server && server.httpServer) {
-    return server.httpServer;
-  }
-  if ('_server' in server && server._server) {
-    return server._server;
-  }
-  return null;
-}
-
-export function viteAutoProxyCookie(options: ViteAutoProxyCookiePluginOptions): Plugin {
-  const {
-    name = 'vite-auto-proxy-cookie',
-    isDev,
-    ...autoProxyOptions
-  } = options;
-
-  let autoProxy: AutoProxyCookie | null = null;
-
-  return {
-    name,
-    apply: 'serve',
-
-    async configureServer(server: ViteDevServer) {
-      autoProxy = createAutoProxyCookie({
-        ...autoProxyOptions,
-        debug: options.debug ?? false,
-        autoRestart: options.autoRestart ?? true,
-        isDev,
-      });
-
-      try {
-        await autoProxy.setup(server);
-      } catch (error) {
-        console.error('[vite-auto-proxy-cookie] Failed to setup proxy:', error);
-        
-        if (options.debug) {
-          console.log('[vite-auto-proxy-cookie] Falling back to middleware mode');
-        }
-      }
-    },
-
-    closeBundle() {
-      autoProxy?.stop();
-    },
-  };
-}
-
-export { AutoProxyCookie, createAutoProxyCookie };
-export type { AutoProxyCookieOptions };