@meng-xi/vite-plugin 0.1.3 → 0.1.4

package/dist/common/html/index.d.ts

@@ -1,25 +1,274 @@
+import { I as InjectCondition, b as SelectorMatch, a as InjectPosition, P as PositionInjectResult, S as SecurityConfig, H as HtmlInjectResult, D as DualInjectResult } from '../../shared/vite-plugin.FfJ-Wwfu.js';
+export { C as ConditionType } from '../../shared/vite-plugin.FfJ-Wwfu.js';
+
 /**
- * HTML 注入结果
+ * HTML 注入工具模块
+ *
+ * @module common/html/inject
+ * @description 提供高级 HTML 内容注入功能，包括选择器匹配、模板变量替换、
+ * 条件判断、规则排序和多位置注入等能力，为插件提供灵活的 HTML 操作支持。
  */
-interface HtmlInjectResult {
-    /** 注入后的 HTML 内容 */
-    html: string;
-    /** 是否成功注入 */
-    injected: boolean;
-}
+
 /**
- * 双区域 HTML 注入结果
+ * 在 HTML 中查找选择器匹配位置
+ *
+ * @param html - 要搜索的 HTML 字符串
+ * @param selector - 选择器字符串（普通字符串或正则表达式字符串）
+ * @param selectorMatch - 匹配模式，`'string'` 为精确字符串匹配，`'regex'` 为正则匹配
+ * @returns 匹配结果对象（包含 `index` 和 `length`），未匹配时返回 `null`
+ *
+ * @description 根据匹配模式在 HTML 中查找选择器的位置：
+ * - 字符串模式：使用 `indexOf` 进行精确匹配
+ * - 正则模式：使用 `RegExp` 进行正则匹配，正则语法错误时返回 `null`
+ *
+ * @example
+ * ```typescript
+ * // 字符串匹配
+ * findSelectorMatch('<div id="app">content</div>', '<div id="app">')
+ * // { index: 0, length: 14 }
+ *
+ * // 正则匹配
+ * findSelectorMatch('<div class="foo">bar</div>', 'class="\\w+"', 'regex')
+ * // { index: 5, length: 12 }
+ *
+ * // 未匹配
+ * findSelectorMatch('<div>hello</div>', '<span>')
+ * // null
+ * ```
  */
-interface DualInjectResult {
-    /** 注入后的 HTML 内容 */
-    html: string;
-    /** head 区域是否成功注入 */
-    headInjected: boolean;
-    /** body 区域是否成功注入 */
-    bodyInjected: boolean;
-    /** body 注入是否使用了回退策略（追加到末尾） */
-    usedFallback: boolean;
+declare function findSelectorMatch(html: string, selector: string, selectorMatch?: SelectorMatch): {
+    index: number;
+    length: number;
+} | null;
+/**
+ * 替换模板字符串中的变量占位符
+ *
+ * @param content - 包含 `{{变量名}}` 占位符的模板字符串
+ * @param ruleVars - 规则级变量映射（优先级高于全局变量）
+ * @param globalVars - 全局变量映射
+ * @returns 替换所有匹配占位符后的字符串
+ *
+ * @description 将模板字符串中形如 `{{key}}` 的占位符替换为对应的值。
+ * 规则变量（`ruleVars`）优先级高于全局变量（`globalVars`），
+ * 当两者存在相同键时，规则变量的值会覆盖全局变量的值。
+ * 变量名中的正则特殊字符会被自动转义，替换值中的 `$` 也会被安全处理。
+ *
+ * @example
+ * ```typescript
+ * // 基本替换
+ * applyTemplateVars('<div>{{name}}</div>', { name: 'test' })
+ * // '<div>test</div>'
+ *
+ * // 规则变量覆盖全局变量
+ * applyTemplateVars('{{a}}-{{b}}', { a: '1' }, { a: '0', b: '2' })
+ * // '1-2'
+ *
+ * // 无匹配占位符
+ * applyTemplateVars('no vars', { x: 'y' })
+ * // 'no vars'
+ * ```
+ */
+declare function applyTemplateVars(content: string, ruleVars?: Record<string, string>, globalVars?: Record<string, string>): string;
+/**
+ * 评估注入条件是否满足
+ *
+ * @param condition - 注入条件配置
+ * @param html - 当前 HTML 内容（用于 `file-contains` 类型判断）
+ * @returns 条件是否满足（布尔值）
+ *
+ * @description 根据条件类型评估注入条件：
+ * - `env`：检查环境变量是否存在且不为 `'false'` 或 `'0'`
+ * - `file-contains`：检查 HTML 内容是否包含指定字符串
+ * - `custom`：执行自定义函数，捕获异常时返回 `false`
+ * - 支持通过 `negate` 字段对结果取反
+ *
+ * @example
+ * ```typescript
+ * // 环境变量判断
+ * evaluateCondition({ type: 'env', value: 'ENABLE_ANALYTICS' }, '')
+ *
+ * // 内容包含判断
+ * evaluateCondition({ type: 'file-contains', value: '<div id="app">' }, html)
+ *
+ * // 自定义函数（带取反）
+ * evaluateCondition(
+ *   { type: 'custom', value: () => isDev(), negate: true },
+ *   html
+ * )
+ * ```
+ */
+declare function evaluateCondition(condition: InjectCondition, html: string): boolean;
+/**
+ * 按优先级排序规则列表
+ *
+ * @typeParam T - 规则类型，必须包含可选的 `priority` 字段
+ * @param rules - 待排序的规则数组
+ * @returns 按 `priority` 升序排列的新数组（不修改原数组）
+ *
+ * @description 将规则按 `priority` 字段升序排列，`priority` 越小优先级越高。
+ * 未指定 `priority` 的规则默认优先级为 100。
+ * 返回新数组，不修改原数组。
+ *
+ * @example
+ * ```typescript
+ * const rules = [
+ *   { priority: 30, name: 'C' },
+ *   { priority: 10, name: 'A' },
+ *   { name: 'D' },           // 默认 priority=100
+ *   { priority: 20, name: 'B' }
+ * ]
+ * sortRulesByPriority(rules)
+ * // [{ priority: 10, name: 'A' }, { priority: 20, name: 'B' },
+ * //  { priority: 30, name: 'C' }, { name: 'D' }]
+ * ```
+ */
+declare function sortRulesByPriority<T extends {
+    priority?: number;
+}>(rules: T[]): T[];
+/**
+ * 在 HTML 的指定位置注入内容
+ *
+ * @param html - 原始 HTML 字符串
+ * @param content - 要注入的内容
+ * @param position - 注入位置
+ * @param selector - 选择器字符串（仅 `before-selector`、`after-selector`、`replace-selector` 位置需要）
+ * @param selectorMatch - 选择器匹配模式（默认为字符串匹配）
+ * @returns 注入结果对象，包含注入后的 HTML、是否成功标志和失败原因
+ *
+ * @description 根据 `position` 参数将内容注入到 HTML 的指定位置：
+ * - `head-start`：在 `<head>` 标签开始后注入
+ * - `head-end`：在 `</head>` 标签前注入
+ * - `body-start`：在 `<body>` 标签开始后注入
+ * - `body-end`：在 `</body>` 标签前注入
+ * - `before-selector`：在选择器匹配位置前注入
+ * - `after-selector`：在选择器匹配位置后注入
+ * - `replace-selector`：替换选择器匹配的内容
+ *
+ * 当目标标签或选择器未找到时，返回 `injected: false` 并附带 `reason` 说明。
+ *
+ * @example
+ * ```typescript
+ * const html = '<html><head><title>Test</title></head><body><div id="app"></div></body></html>'
+ *
+ * // 在 head 开始后注入 meta 标签
+ * injectAtPosition(html, '<meta charset="utf-8">', 'head-start')
+ *
+ * // 在 body 结束前注入脚本
+ * injectAtPosition(html, '<script>app()</script>', 'body-end')
+ *
+ * // 在指定元素前注入
+ * injectAtPosition(html, '<nav>menu</nav>', 'before-selector', '<div id="app">')
+ *
+ * // 替换指定元素
+ * injectAtPosition(html, '<div id="root"></div>', 'replace-selector', '<div id="app">')
+ * ```
+ */
+declare function injectAtPosition(html: string, content: string, position: InjectPosition, selector?: string, selectorMatch?: SelectorMatch): PositionInjectResult;
+
+/**
+ * HTML 安全过滤模块
+ *
+ * @module common/html/security
+ * @description 提供 HTML 内容安全过滤和验证功能，防止 XSS 攻击和危险内容注入，
+ * 包括危险标签检测、危险属性过滤和安全配置验证等能力。
+ */
+
+/**
+ * 默认阻止的 HTML 标签列表
+ *
+ * @description 包含可能导致安全风险的 HTML 标签：
+ * - `script`：可执行 JavaScript 代码
+ * - `iframe`：可嵌入外部页面
+ * - `object`/`embed`/`applet`：可嵌入插件
+ * - `form`/`input`/`textarea`/`select`/`button`：可创建表单
+ */
+declare const DEFAULT_BLOCKED_TAGS: string[];
+/**
+ * 默认阻止的 HTML 事件属性列表
+ *
+ * @description 包含所有可能导致 JavaScript 执行的事件处理属性，
+ * 涵盖鼠标事件、键盘事件、表单事件、拖拽事件和动画事件等。
+ */
+declare const DEFAULT_BLOCKED_ATTRIBUTES: string[];
+/**
+ * 验证安全配置的合法性
+ *
+ * @param security - 安全配置对象
+ * @throws 当 `blockedTags` 不是字符串数组时抛出错误
+ * @throws 当 `allowedTags` 不是字符串数组时抛出错误
+ * @throws 当 `blockedAttributes` 不是字符串数组时抛出错误
+ *
+ * @description 检查安全配置中的数组字段是否为合法的字符串数组类型，
+ * 传入 `undefined` 时直接跳过验证。
+ *
+ * @example
+ * ```typescript
+ * // 合法配置
+ * validateSecurityConfig({ blockedTags: ['iframe'], allowedTags: ['div'] })
+ *
+ * // 非法配置（抛出错误）
+ * validateSecurityConfig({ blockedTags: 'iframe' })
+ * // Error: security.blockedTags 必须是字符串数组
+ * ```
+ */
+declare function validateSecurityConfig(security?: SecurityConfig): void;
+/**
+ * 内容消毒规则选项
+ *
+ * @description 定义对单条注入规则内容进行安全过滤时的选项，
+ * 控制是否允许脚本注入等特殊行为。
+ */
+interface SanitizeRuleOptions {
+    /** 规则标识符，用于错误消息和警告日志中标识来源规则 */
+    id?: string;
+    /**
+     * 是否允许注入 `<script>` 标签和被阻止的标签/属性
+     *
+     * @description 设置为 `true` 时，将跳过对危险标签和属性的安全检查，
+     * 但仍会输出警告日志提醒开发者注意安全风险。
+     * 仅在注入内容来源可信时使用此选项。
+     *
+     * @default false
+     */
+    allowScriptInjection?: boolean;
 }
+/**
+ * 对注入内容进行安全过滤
+ *
+ * @param content - 待过滤的 HTML 内容字符串
+ * @param rule - 当前注入规则的消毒选项
+ * @param security - 全局安全配置
+ * @param logger - 日志记录器（需提供 `warn` 方法），用于输出安全警告
+ * @returns 过滤后的安全 HTML 内容字符串
+ * @throws 当内容包含被阻止的标签且未启用 `allowScriptInjection` 时抛出错误
+ * @throws 当内容包含危险属性且未启用 `allowScriptInjection` 时抛出错误
+ *
+ * @description 对 HTML 内容进行安全过滤，防止 XSS 攻击：
+ * 1. **标签过滤**：检测并阻止默认阻止列表中的标签（如 script、iframe），
+ *    可通过 `security.allowedTags` 放行特定标签
+ * 2. **属性过滤**：检测并阻止事件处理属性（如 onclick、onerror）
+ * 3. **脚本检测**：特别检测 `<script>` 标签，需要显式启用 `allowScriptInjection`
+ *
+ * 当 `rule.allowScriptInjection` 为 `true` 时，跳过安全检查但输出警告日志。
+ *
+ * @example
+ * ```typescript
+ * // 安全内容直接通过
+ * sanitizeContent('<div>safe</div>', { id: 'rule1' })
+ *
+ * // 包含 script 标签（抛出错误）
+ * sanitizeContent('<script>alert(1)</script>', { id: 'rule2' })
+ *
+ * // 允许脚本注入（通过但输出警告）
+ * sanitizeContent('<script>alert(1)</script>', { id: 'rule3', allowScriptInjection: true }, undefined, console)
+ *
+ * // 自定义安全配置
+ * sanitizeContent('<iframe>test</iframe>', { id: 'rule4' }, { allowedTags: ['iframe'] })
+ * ```
+ */
+declare function sanitizeContent(content: string, rule: SanitizeRuleOptions, security?: SecurityConfig, logger?: {
+    warn: (msg: string) => void;
+}): string;
 
 /**
  * 在 HTML 中指定闭合标签前注入代码
@@ -105,5 +354,5 @@ declare function injectBeforeTagWithFallback(html: string, code: string, _fallba
  */
 declare function injectHeadAndBody(html: string, headCode: string | undefined, bodyCode: string): DualInjectResult;
 
-export { injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority };
-export type { DualInjectResult, HtmlInjectResult };
+export { DEFAULT_BLOCKED_ATTRIBUTES, DEFAULT_BLOCKED_TAGS, DualInjectResult, HtmlInjectResult, InjectCondition, InjectPosition, PositionInjectResult, SecurityConfig, SelectorMatch, applyTemplateVars, evaluateCondition, findSelectorMatch, injectAtPosition, injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority, sanitizeContent, sortRulesByPriority, validateSecurityConfig };
+export type { SanitizeRuleOptions };

package/dist/common/html/index.mjs

@@ -1,2 +1,2 @@
-function d(e,t,l){const n=new RegExp(t,"i");return n.test(e)?{html:e.replace(n,`${l}
-${t}`),injected:!0}:{html:e,injected:!1}}function o(e,t,l=["</head>","</body>","</html>"]){for(const n of l){const c=d(e,n,t);if(c.injected)return c}return{html:e+t,injected:!0}}function a(e,t,l){const n=d(e,"</body>",t);if(n.injected)return{...n,usedFallback:!1};const c=d(e,"</html>",t);return c.injected?{...c,usedFallback:!1}:{html:e+t,injected:!0,usedFallback:!0}}function u(e,t,l){let n=e,c=!1;if(t){const i=d(n,"</head>",t);i.injected&&(n=i.html,c=!0)}const r=a(n,l);return{html:r.html,headInjected:c,bodyInjected:r.injected,usedFallback:r.usedFallback}}export{d as injectBeforeTag,a as injectBeforeTagWithFallback,u as injectHeadAndBody,o as injectHtmlByPriority};
+export{D as DEFAULT_BLOCKED_ATTRIBUTES,a as DEFAULT_BLOCKED_TAGS,b as applyTemplateVars,e as evaluateCondition,f as findSelectorMatch,i as injectAtPosition,s as sanitizeContent,c as sortRulesByPriority,v as validateSecurityConfig}from"../../shared/vite-plugin.BCuhU1au.mjs";import"../script/index.mjs";function c(e,t,i){const n=new RegExp(t,"i");return n.test(e)?{html:e.replace(n,`${i}
+${t}`),injected:!0}:{html:e,injected:!1}}function s(e,t,i=["</head>","</body>","</html>"]){for(const n of i){const a=c(e,n,t);if(a.injected)return a}return{html:e+t,injected:!0}}function o(e,t,i){const n=c(e,"</body>",t);if(n.injected)return{...n,usedFallback:!1};const a=c(e,"</html>",t);return a.injected?{...a,usedFallback:!1}:{html:e+t,injected:!0,usedFallback:!0}}function d(e,t,i){let n=e,a=!1;if(t){const r=c(n,"</head>",t);r.injected&&(n=r.html,a=!0)}const l=o(n,i);return{html:l.html,headInjected:a,bodyInjected:l.injected,usedFallback:l.usedFallback}}export{c as injectBeforeTag,o as injectBeforeTagWithFallback,d as injectHeadAndBody,s as injectHtmlByPriority};

package/dist/common/index.cjs

@@ -1 +1 @@
-"use strict";const common_compress_index=require("./compress/index.cjs"),common_format_index=require("./format/index.cjs"),common_fs_index=require("./fs/index.cjs"),common_html_index=require("./html/index.cjs"),common_object_index=require("./object/index.cjs"),common_path_index=require("./path/index.cjs"),common_script_index=require("./script/index.cjs"),validator=require("../shared/vite-plugin.Bcg6RW2N.cjs"),common_validation_index=require("./validation/index.cjs");require("node:zlib"),require("node:stream/promises"),require("node:stream"),require("crypto"),require("node:path"),require("fs"),require("path"),exports.calculateGzipSize=common_compress_index.calculateGzipSize,exports.escapeHtmlAttr=common_format_index.escapeHtmlAttr,exports.formatDate=common_format_index.formatDate,exports.formatFileSize=common_format_index.formatFileSize,exports.generateRandomHash=common_format_index.generateRandomHash,exports.getDateFormatParams=common_format_index.getDateFormatParams,exports.getExtension=common_format_index.getExtension,exports.padNumber=common_format_index.padNumber,exports.parseTemplate=common_format_index.parseTemplate,exports.stripJsonComments=common_format_index.stripJsonComments,exports.toCamelCase=common_format_index.toCamelCase,exports.toPascalCase=common_format_index.toPascalCase,exports.checkSourceExists=common_fs_index.checkSourceExists,exports.copySourceToTarget=common_fs_index.copySourceToTarget,exports.ensureTargetDir=common_fs_index.ensureTargetDir,exports.fileExists=common_fs_index.fileExists,exports.readDirRecursive=common_fs_index.readDirRecursive,exports.readFileContent=common_fs_index.readFileContent,exports.readFileSync=common_fs_index.readFileSync,exports.runWithConcurrency=common_fs_index.runWithConcurrency,exports.scanDirectory=common_fs_index.scanDirectory,exports.shouldUpdateFile=common_fs_index.shouldUpdateFile,exports.writeFileContent=common_fs_index.writeFileContent,exports.writeJsonReport=common_fs_index.writeJsonReport,exports.injectBeforeTag=common_html_index.injectBeforeTag,exports.injectBeforeTagWithFallback=common_html_index.injectBeforeTagWithFallback,exports.injectHeadAndBody=common_html_index.injectHeadAndBody,exports.injectHtmlByPriority=common_html_index.injectHtmlByPriority,exports.deepMerge=common_object_index.deepMerge,exports.isNodeModule=common_path_index.isNodeModule,exports.containsScriptTag=common_script_index.containsScriptTag,exports.makeCallback=common_script_index.makeCallback,exports.validateIdentifierName=common_script_index.validateIdentifierName,exports.Validator=validator.Validator,exports.validateCallbackFields=common_validation_index.validateCallbackFields,exports.validateEnumValue=common_validation_index.validateEnumValue,exports.validateGlobalName=common_validation_index.validateGlobalName,exports.validateNestedDuration=common_validation_index.validateNestedDuration,exports.validateNoScriptInTemplate=common_validation_index.validateNoScriptInTemplate,exports.validateNonNegativeNumber=common_validation_index.validateNonNegativeNumber;
+"use strict";const common_compress_index=require("./compress/index.cjs"),common_format_index=require("./format/index.cjs"),common_fs_index=require("./fs/index.cjs"),common_html_index=require("./html/index.cjs"),common_object_index=require("./object/index.cjs"),common_path_index=require("./path/index.cjs"),common_script_index=require("./script/index.cjs"),common_ui_index=require("./ui/index.cjs"),validator=require("../shared/vite-plugin.Bcg6RW2N.cjs"),validators=require("../shared/vite-plugin.soT9a-KD.cjs"),env=require("../shared/vite-plugin.vwox4bU0.cjs"),security=require("../shared/vite-plugin.BrI73DHA.cjs");require("node:zlib"),require("node:stream/promises"),require("node:stream"),require("crypto"),require("node:path"),require("fs"),require("path"),exports.calculateGzipSize=common_compress_index.calculateGzipSize,exports.escapeHtmlAttr=common_format_index.escapeHtmlAttr,exports.formatDate=common_format_index.formatDate,exports.formatFileSize=common_format_index.formatFileSize,exports.generateRandomHash=common_format_index.generateRandomHash,exports.getDateFormatParams=common_format_index.getDateFormatParams,exports.getExtension=common_format_index.getExtension,exports.padNumber=common_format_index.padNumber,exports.parseTemplate=common_format_index.parseTemplate,exports.stripJsonComments=common_format_index.stripJsonComments,exports.toCamelCase=common_format_index.toCamelCase,exports.toPascalCase=common_format_index.toPascalCase,exports.checkSourceExists=common_fs_index.checkSourceExists,exports.copySourceToTarget=common_fs_index.copySourceToTarget,exports.ensureTargetDir=common_fs_index.ensureTargetDir,exports.fileExists=common_fs_index.fileExists,exports.readDirRecursive=common_fs_index.readDirRecursive,exports.readFileContent=common_fs_index.readFileContent,exports.readFileSync=common_fs_index.readFileSync,exports.runWithConcurrency=common_fs_index.runWithConcurrency,exports.scanDirectory=common_fs_index.scanDirectory,exports.shouldUpdateFile=common_fs_index.shouldUpdateFile,exports.writeFileContent=common_fs_index.writeFileContent,exports.writeJsonReport=common_fs_index.writeJsonReport,exports.injectBeforeTag=common_html_index.injectBeforeTag,exports.injectBeforeTagWithFallback=common_html_index.injectBeforeTagWithFallback,exports.injectHeadAndBody=common_html_index.injectHeadAndBody,exports.injectHtmlByPriority=common_html_index.injectHtmlByPriority,exports.deepMerge=common_object_index.deepMerge,exports.isNodeModule=common_path_index.isNodeModule,exports.containsScriptTag=common_script_index.containsScriptTag,exports.makeCallback=common_script_index.makeCallback,exports.validateIdentifierName=common_script_index.validateIdentifierName,exports.ANSI=common_ui_index.ANSI,exports.SPINNER_FRAMES=common_ui_index.SPINNER_FRAMES,exports.stripAnsi=common_ui_index.stripAnsi,exports.Validator=validator.Validator,exports.validateCallbackFields=validators.validateCallbackFields,exports.validateEnumValue=validators.validateEnumValue,exports.validateGlobalName=validators.validateGlobalName,exports.validateNestedDuration=validators.validateNestedDuration,exports.validateNoScriptInTemplate=validators.validateNoScriptInTemplate,exports.validateNonNegativeNumber=validators.validateNonNegativeNumber,exports.STRING_LIKE_TYPES=env.STRING_LIKE_TYPES,exports.validateEnvironment=env.validateEnvironment,exports.validateLength=env.validateLength,exports.validateRange=env.validateRange,exports.validateType=env.validateType,exports.validateValue=env.validateValue,exports.DEFAULT_BLOCKED_ATTRIBUTES=security.DEFAULT_BLOCKED_ATTRIBUTES,exports.DEFAULT_BLOCKED_TAGS=security.DEFAULT_BLOCKED_TAGS,exports.applyTemplateVars=security.applyTemplateVars,exports.evaluateCondition=security.evaluateCondition,exports.findSelectorMatch=security.findSelectorMatch,exports.injectAtPosition=security.injectAtPosition,exports.sanitizeContent=security.sanitizeContent,exports.sortRulesByPriority=security.sortRulesByPriority,exports.validateSecurityConfig=security.validateSecurityConfig;

package/dist/common/index.d.cts

@@ -1,9 +1,12 @@
 export { calculateGzipSize } from './compress/index.cjs';
 export { DateFormatOptions, escapeHtmlAttr, formatDate, formatFileSize, generateRandomHash, getDateFormatParams, getExtension, padNumber, parseTemplate, stripJsonComments, toCamelCase, toPascalCase } from './format/index.cjs';
 export { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile, checkSourceExists, copySourceToTarget, ensureTargetDir, fileExists, readDirRecursive, readFileContent, readFileSync, runWithConcurrency, scanDirectory, shouldUpdateFile, writeFileContent, writeJsonReport } from './fs/index.cjs';
-export { DualInjectResult, HtmlInjectResult, injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority } from './html/index.cjs';
+export { DEFAULT_BLOCKED_ATTRIBUTES, DEFAULT_BLOCKED_TAGS, SanitizeRuleOptions, applyTemplateVars, evaluateCondition, findSelectorMatch, injectAtPosition, injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority, sanitizeContent, sortRulesByPriority, validateSecurityConfig } from './html/index.cjs';
 export { deepMerge } from './object/index.cjs';
 export { isNodeModule } from './path/index.cjs';
 export { containsScriptTag, makeCallback, validateIdentifierName } from './script/index.cjs';
+export { ANSI, SPINNER_FRAMES, stripAnsi } from './ui/index.cjs';
 export { V as Validator } from '../shared/vite-plugin.DRRlWY8P.cjs';
 export { validateCallbackFields, validateEnumValue, validateGlobalName, validateNestedDuration, validateNoScriptInTemplate, validateNonNegativeNumber } from './validation/index.cjs';
+export { E as EnvFieldRule, a as EnvType, b as EnvValidationResult, S as STRING_LIKE_TYPES, v as validateEnvironment, c as validateLength, d as validateRange, e as validateType, f as validateValue } from '../shared/vite-plugin.CmtcnItg.cjs';
+export { C as ConditionType, D as DualInjectResult, H as HtmlInjectResult, I as InjectCondition, a as InjectPosition, P as PositionInjectResult, S as SecurityConfig, b as SelectorMatch } from '../shared/vite-plugin.FfJ-Wwfu.cjs';

package/dist/common/index.d.mts

@@ -1,9 +1,12 @@
 export { calculateGzipSize } from './compress/index.mjs';
 export { DateFormatOptions, escapeHtmlAttr, formatDate, formatFileSize, generateRandomHash, getDateFormatParams, getExtension, padNumber, parseTemplate, stripJsonComments, toCamelCase, toPascalCase } from './format/index.mjs';
 export { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile, checkSourceExists, copySourceToTarget, ensureTargetDir, fileExists, readDirRecursive, readFileContent, readFileSync, runWithConcurrency, scanDirectory, shouldUpdateFile, writeFileContent, writeJsonReport } from './fs/index.mjs';
-export { DualInjectResult, HtmlInjectResult, injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority } from './html/index.mjs';
+export { DEFAULT_BLOCKED_ATTRIBUTES, DEFAULT_BLOCKED_TAGS, SanitizeRuleOptions, applyTemplateVars, evaluateCondition, findSelectorMatch, injectAtPosition, injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority, sanitizeContent, sortRulesByPriority, validateSecurityConfig } from './html/index.mjs';
 export { deepMerge } from './object/index.mjs';
 export { isNodeModule } from './path/index.mjs';
 export { containsScriptTag, makeCallback, validateIdentifierName } from './script/index.mjs';
+export { ANSI, SPINNER_FRAMES, stripAnsi } from './ui/index.mjs';
 export { V as Validator } from '../shared/vite-plugin.DRRlWY8P.mjs';
 export { validateCallbackFields, validateEnumValue, validateGlobalName, validateNestedDuration, validateNoScriptInTemplate, validateNonNegativeNumber } from './validation/index.mjs';
+export { E as EnvFieldRule, a as EnvType, b as EnvValidationResult, S as STRING_LIKE_TYPES, v as validateEnvironment, c as validateLength, d as validateRange, e as validateType, f as validateValue } from '../shared/vite-plugin.CmtcnItg.mjs';
+export { C as ConditionType, D as DualInjectResult, H as HtmlInjectResult, I as InjectCondition, a as InjectPosition, P as PositionInjectResult, S as SecurityConfig, b as SelectorMatch } from '../shared/vite-plugin.FfJ-Wwfu.mjs';

package/dist/common/index.d.ts

@@ -1,9 +1,12 @@
 export { calculateGzipSize } from './compress/index.js';
 export { DateFormatOptions, escapeHtmlAttr, formatDate, formatFileSize, generateRandomHash, getDateFormatParams, getExtension, padNumber, parseTemplate, stripJsonComments, toCamelCase, toPascalCase } from './format/index.js';
 export { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile, checkSourceExists, copySourceToTarget, ensureTargetDir, fileExists, readDirRecursive, readFileContent, readFileSync, runWithConcurrency, scanDirectory, shouldUpdateFile, writeFileContent, writeJsonReport } from './fs/index.js';
-export { DualInjectResult, HtmlInjectResult, injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority } from './html/index.js';
+export { DEFAULT_BLOCKED_ATTRIBUTES, DEFAULT_BLOCKED_TAGS, SanitizeRuleOptions, applyTemplateVars, evaluateCondition, findSelectorMatch, injectAtPosition, injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority, sanitizeContent, sortRulesByPriority, validateSecurityConfig } from './html/index.js';
 export { deepMerge } from './object/index.js';
 export { isNodeModule } from './path/index.js';
 export { containsScriptTag, makeCallback, validateIdentifierName } from './script/index.js';
+export { ANSI, SPINNER_FRAMES, stripAnsi } from './ui/index.js';
 export { V as Validator } from '../shared/vite-plugin.DRRlWY8P.js';
 export { validateCallbackFields, validateEnumValue, validateGlobalName, validateNestedDuration, validateNoScriptInTemplate, validateNonNegativeNumber } from './validation/index.js';
+export { E as EnvFieldRule, a as EnvType, b as EnvValidationResult, S as STRING_LIKE_TYPES, v as validateEnvironment, c as validateLength, d as validateRange, e as validateType, f as validateValue } from '../shared/vite-plugin.CmtcnItg.js';
+export { C as ConditionType, D as DualInjectResult, H as HtmlInjectResult, I as InjectCondition, a as InjectPosition, P as PositionInjectResult, S as SecurityConfig, b as SelectorMatch } from '../shared/vite-plugin.FfJ-Wwfu.js';

package/dist/common/index.mjs

@@ -1 +1 @@
-export{calculateGzipSize}from"./compress/index.mjs";export{escapeHtmlAttr,formatDate,formatFileSize,generateRandomHash,getDateFormatParams,getExtension,padNumber,parseTemplate,stripJsonComments,toCamelCase,toPascalCase}from"./format/index.mjs";export{checkSourceExists,copySourceToTarget,ensureTargetDir,fileExists,readDirRecursive,readFileContent,readFileSync,runWithConcurrency,scanDirectory,shouldUpdateFile,writeFileContent,writeJsonReport}from"./fs/index.mjs";export{injectBeforeTag,injectBeforeTagWithFallback,injectHeadAndBody,injectHtmlByPriority}from"./html/index.mjs";export{deepMerge}from"./object/index.mjs";export{isNodeModule}from"./path/index.mjs";export{containsScriptTag,makeCallback,validateIdentifierName}from"./script/index.mjs";export{V as Validator}from"../shared/vite-plugin.DcExl6jd.mjs";export{validateCallbackFields,validateEnumValue,validateGlobalName,validateNestedDuration,validateNoScriptInTemplate,validateNonNegativeNumber}from"./validation/index.mjs";import"node:zlib";import"node:stream/promises";import"node:stream";import"crypto";import"node:path";import"fs";import"path";
+export{calculateGzipSize}from"./compress/index.mjs";export{escapeHtmlAttr,formatDate,formatFileSize,generateRandomHash,getDateFormatParams,getExtension,padNumber,parseTemplate,stripJsonComments,toCamelCase,toPascalCase}from"./format/index.mjs";export{checkSourceExists,copySourceToTarget,ensureTargetDir,fileExists,readDirRecursive,readFileContent,readFileSync,runWithConcurrency,scanDirectory,shouldUpdateFile,writeFileContent,writeJsonReport}from"./fs/index.mjs";export{injectBeforeTag,injectBeforeTagWithFallback,injectHeadAndBody,injectHtmlByPriority}from"./html/index.mjs";export{deepMerge}from"./object/index.mjs";export{isNodeModule}from"./path/index.mjs";export{containsScriptTag,makeCallback,validateIdentifierName}from"./script/index.mjs";export{ANSI,SPINNER_FRAMES,stripAnsi}from"./ui/index.mjs";export{V as Validator}from"../shared/vite-plugin.DcExl6jd.mjs";export{v as validateCallbackFields,a as validateEnumValue,b as validateGlobalName,c as validateNestedDuration,d as validateNoScriptInTemplate,e as validateNonNegativeNumber}from"../shared/vite-plugin.Dumot0up.mjs";export{S as STRING_LIKE_TYPES,v as validateEnvironment,a as validateLength,b as validateRange,c as validateType,d as validateValue}from"../shared/vite-plugin.DnFDPjNf.mjs";export{D as DEFAULT_BLOCKED_ATTRIBUTES,a as DEFAULT_BLOCKED_TAGS,b as applyTemplateVars,e as evaluateCondition,f as findSelectorMatch,i as injectAtPosition,s as sanitizeContent,c as sortRulesByPriority,v as validateSecurityConfig}from"../shared/vite-plugin.BCuhU1au.mjs";import"node:zlib";import"node:stream/promises";import"node:stream";import"crypto";import"node:path";import"fs";import"path";

package/dist/common/ui/index.cjs

@@ -0,0 +1 @@
+"use strict";const SPINNER_FRAMES=process.platform==="win32"?["|","/","-","\\"]:["\u280B","\u2819","\u2839","\u2838","\u283C","\u2834","\u2826","\u2827","\u2807","\u280F"],ANSI={reset:"\x1B[0G",clearLine:"\x1B[2K",hideCursor:"\x1B[?25l",showCursor:"\x1B[?25h",green:r=>`\x1B[32m${r}\x1B[39m`,cyan:r=>`\x1B[36m${r}\x1B[39m`,gray:r=>`\x1B[90m${r}\x1B[39m`,bold:r=>`\x1B[1m${r}\x1B[22m`,red:r=>`\x1B[31m${r}\x1B[39m`,yellow:r=>`\x1B[33m${r}\x1B[39m`,magenta:r=>`\x1B[35m${r}\x1B[39m`},x=/\x1b\[[0-9;]*m/g;function stripAnsi(r){return r.replace(x,"")}exports.ANSI=ANSI,exports.SPINNER_FRAMES=SPINNER_FRAMES,exports.stripAnsi=stripAnsi;

package/dist/common/ui/index.d.cts

@@ -0,0 +1,132 @@
+/**
+ * 终端 UI 工具模块
+ *
+ * @module common/ui/terminal
+ * @description 提供终端 ANSI 转义码处理、Spinner 动画帧和字符串清理等工具函数，
+ * 用于在终端中实现彩色输出、光标控制和进度动画等功能。
+ */
+/**
+ * Spinner 动画帧序列
+ *
+ * @description 根据操作系统平台自动选择合适的动画帧：
+ * - Windows：使用 ASCII 字符 `|`, `/`, `-`, `\`，确保在传统终端中正常显示
+ * - 其他平台：使用 Unicode Braille 字符 `⠋`-`⠏`，视觉效果更流畅
+ *
+ * @example
+ * ```typescript
+ * let frameIndex = 0
+ * setInterval(() => {
+ *   process.stdout.write(`\r${SPINNER_FRAMES[frameIndex]} Loading...`)
+ *   frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length
+ * }, 80)
+ * ```
+ */
+declare const SPINNER_FRAMES: string[];
+/**
+ * ANSI 转义码工具集
+ *
+ * @description 提供常用的终端 ANSI 转义码常量和彩色文本包装函数，
+ * 用于在终端中实现文本着色、光标控制和行清理等操作。
+ *
+ * @property reset - 将光标重置到行首（`\x1b[0G`）
+ * @property clearLine - 清除当前行内容（`\x1b[2K`）
+ * @property hideCursor - 隐藏终端光标（`\x1b[?25l`）
+ * @property showCursor - 显示终端光标（`\x1b[?25h`）
+ * @property green - 将文本包装为绿色
+ * @property cyan - 将文本包装为青色
+ * @property gray - 将文本包装为灰色
+ * @property bold - 将文本包装为粗体
+ * @property red - 将文本包装为红色
+ * @property yellow - 将文本包装为黄色
+ * @property magenta - 将文本包装为品红色
+ *
+ * @example
+ * ```typescript
+ * // 彩色输出
+ * console.log(ANSI.green('✓') + ' 构建成功')
+ * console.log(ANSI.red('✗') + ' 构建失败')
+ * console.log(ANSI.bold(ANSI.cyan('信息:')) + ' 正在处理...')
+ *
+ * // 光标控制
+ * process.stdout.write(ANSI.hideCursor)
+ * // ... 动画逻辑 ...
+ * process.stdout.write(ANSI.showCursor)
+ *
+ * // 行清理与重写
+ * process.stdout.write(ANSI.clearLine + ANSI.reset + ANSI.green('完成'))
+ * ```
+ */
+declare const ANSI: {
+    /** 将光标重置到行首 */
+    reset: string;
+    /** 清除当前行内容 */
+    clearLine: string;
+    /** 隐藏终端光标 */
+    hideCursor: string;
+    /** 显示终端光标 */
+    showCursor: string;
+    /**
+     * 将文本包装为绿色
+     * @param t - 要着色的文本
+     * @returns 包含绿色 ANSI 转义码的字符串
+     */
+    green: (t: string) => string;
+    /**
+     * 将文本包装为青色
+     * @param t - 要着色的文本
+     * @returns 包含青色 ANSI 转义码的字符串
+     */
+    cyan: (t: string) => string;
+    /**
+     * 将文本包装为灰色
+     * @param t - 要着色的文本
+     * @returns 包含灰色 ANSI 转义码的字符串
+     */
+    gray: (t: string) => string;
+    /**
+     * 将文本包装为粗体
+     * @param t - 要加粗的文本
+     * @returns 包含粗体 ANSI 转义码的字符串
+     */
+    bold: (t: string) => string;
+    /**
+     * 将文本包装为红色
+     * @param t - 要着色的文本
+     * @returns 包含红色 ANSI 转义码的字符串
+     */
+    red: (t: string) => string;
+    /**
+     * 将文本包装为黄色
+     * @param t - 要着色的文本
+     * @returns 包含黄色 ANSI 转义码的字符串
+     */
+    yellow: (t: string) => string;
+    /**
+     * 将文本包装为品红色
+     * @param t - 要着色的文本
+     * @returns 包含品红色 ANSI 转义码的字符串
+     */
+    magenta: (t: string) => string;
+};
+/**
+ * 移除字符串中的所有 ANSI 转义码
+ *
+ * @param str - 可能包含 ANSI 转义码的字符串
+ * @returns 不包含任何 ANSI 转义码的纯文本字符串
+ *
+ * @description 使用正则表达式匹配并移除所有形如 `\x1b[...m` 的 ANSI 转义序列，
+ * 常用于计算文本实际显示宽度或将彩色输出转为纯文本。
+ *
+ * @example
+ * ```typescript
+ * const colored = ANSI.green('hello') + ' ' + ANSI.red('world')
+ * stripAnsi(colored) // 'hello world'
+ *
+ * // 计算终端显示宽度
+ * const text = ANSI.bold(ANSI.cyan('状态:')) + ' 完成'
+ * stripAnsi(text).length // 7 (不含转义码的实际字符数)
+ * ```
+ */
+declare function stripAnsi(str: string): string;
+
+export { ANSI, SPINNER_FRAMES, stripAnsi };

package/dist/common/ui/index.d.mts

@@ -0,0 +1,132 @@
+/**
+ * 终端 UI 工具模块
+ *
+ * @module common/ui/terminal
+ * @description 提供终端 ANSI 转义码处理、Spinner 动画帧和字符串清理等工具函数，
+ * 用于在终端中实现彩色输出、光标控制和进度动画等功能。
+ */
+/**
+ * Spinner 动画帧序列
+ *
+ * @description 根据操作系统平台自动选择合适的动画帧：
+ * - Windows：使用 ASCII 字符 `|`, `/`, `-`, `\`，确保在传统终端中正常显示
+ * - 其他平台：使用 Unicode Braille 字符 `⠋`-`⠏`，视觉效果更流畅
+ *
+ * @example
+ * ```typescript
+ * let frameIndex = 0
+ * setInterval(() => {
+ *   process.stdout.write(`\r${SPINNER_FRAMES[frameIndex]} Loading...`)
+ *   frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length
+ * }, 80)
+ * ```
+ */
+declare const SPINNER_FRAMES: string[];
+/**
+ * ANSI 转义码工具集
+ *
+ * @description 提供常用的终端 ANSI 转义码常量和彩色文本包装函数，
+ * 用于在终端中实现文本着色、光标控制和行清理等操作。
+ *
+ * @property reset - 将光标重置到行首（`\x1b[0G`）
+ * @property clearLine - 清除当前行内容（`\x1b[2K`）
+ * @property hideCursor - 隐藏终端光标（`\x1b[?25l`）
+ * @property showCursor - 显示终端光标（`\x1b[?25h`）
+ * @property green - 将文本包装为绿色
+ * @property cyan - 将文本包装为青色
+ * @property gray - 将文本包装为灰色
+ * @property bold - 将文本包装为粗体
+ * @property red - 将文本包装为红色
+ * @property yellow - 将文本包装为黄色
+ * @property magenta - 将文本包装为品红色
+ *
+ * @example
+ * ```typescript
+ * // 彩色输出
+ * console.log(ANSI.green('✓') + ' 构建成功')
+ * console.log(ANSI.red('✗') + ' 构建失败')
+ * console.log(ANSI.bold(ANSI.cyan('信息:')) + ' 正在处理...')
+ *
+ * // 光标控制
+ * process.stdout.write(ANSI.hideCursor)
+ * // ... 动画逻辑 ...
+ * process.stdout.write(ANSI.showCursor)
+ *
+ * // 行清理与重写
+ * process.stdout.write(ANSI.clearLine + ANSI.reset + ANSI.green('完成'))
+ * ```
+ */
+declare const ANSI: {
+    /** 将光标重置到行首 */
+    reset: string;
+    /** 清除当前行内容 */
+    clearLine: string;
+    /** 隐藏终端光标 */
+    hideCursor: string;
+    /** 显示终端光标 */
+    showCursor: string;
+    /**
+     * 将文本包装为绿色
+     * @param t - 要着色的文本
+     * @returns 包含绿色 ANSI 转义码的字符串
+     */
+    green: (t: string) => string;
+    /**
+     * 将文本包装为青色
+     * @param t - 要着色的文本
+     * @returns 包含青色 ANSI 转义码的字符串
+     */
+    cyan: (t: string) => string;
+    /**
+     * 将文本包装为灰色
+     * @param t - 要着色的文本
+     * @returns 包含灰色 ANSI 转义码的字符串
+     */
+    gray: (t: string) => string;
+    /**
+     * 将文本包装为粗体
+     * @param t - 要加粗的文本
+     * @returns 包含粗体 ANSI 转义码的字符串
+     */
+    bold: (t: string) => string;
+    /**
+     * 将文本包装为红色
+     * @param t - 要着色的文本
+     * @returns 包含红色 ANSI 转义码的字符串
+     */
+    red: (t: string) => string;
+    /**
+     * 将文本包装为黄色
+     * @param t - 要着色的文本
+     * @returns 包含黄色 ANSI 转义码的字符串
+     */
+    yellow: (t: string) => string;
+    /**
+     * 将文本包装为品红色
+     * @param t - 要着色的文本
+     * @returns 包含品红色 ANSI 转义码的字符串
+     */
+    magenta: (t: string) => string;
+};
+/**
+ * 移除字符串中的所有 ANSI 转义码
+ *
+ * @param str - 可能包含 ANSI 转义码的字符串
+ * @returns 不包含任何 ANSI 转义码的纯文本字符串
+ *
+ * @description 使用正则表达式匹配并移除所有形如 `\x1b[...m` 的 ANSI 转义序列，
+ * 常用于计算文本实际显示宽度或将彩色输出转为纯文本。
+ *
+ * @example
+ * ```typescript
+ * const colored = ANSI.green('hello') + ' ' + ANSI.red('world')
+ * stripAnsi(colored) // 'hello world'
+ *
+ * // 计算终端显示宽度
+ * const text = ANSI.bold(ANSI.cyan('状态:')) + ' 完成'
+ * stripAnsi(text).length // 7 (不含转义码的实际字符数)
+ * ```
+ */
+declare function stripAnsi(str: string): string;
+
+export { ANSI, SPINNER_FRAMES, stripAnsi };