@path-ioc/pack 0.1.3 → 0.1.5

package/README.md

@@ -15,12 +15,16 @@
   </p>
 </div>
 
+> 💡 **Architectural Positioning & Usage Boundary**  
+> `@path-ioc/pack` is a dedicated Vite build plugin designed to bundle an isolated Mesh module directory into a **distributable standalone npm package / component library**.  
+> **Warning**: This plugin automatically intercepts Vite configuration and forces Library Mode (`build.lib`). **Do NOT unconditionally embed it in standard web application builds (e.g. standard Vite SPA/SSR configs).** It is recommended to use a dedicated packaging config (e.g. `vite.config.pack.ts`) or trigger it via separate packaging scripts.
+
 ---
 
-## Features
+## Core Capabilities
 
 - **Physical Entrypoint Generation**:
-  During Vite builds, automatically scans `src/modules` for physical directories containing `index.ts/tsx` and synthesizes clean on-disk entrypoints (default `.modular-plugin-entry.ts`).
+  During Vite builds, automatically scans `src/modules` for physical directories containing `index.ts/tsx` and synthesizes clean on-disk entrypoints (default `node_modules/.path-ioc/.modular-plugin-entry.ts`);
 - **Full Mesh Registry & Type Exports**:
   Generates unified module import aliases and exports the canonical runtime module registry array `modules`:
   ```typescript
@@ -30,9 +34,11 @@
   ];
   ```
 - **Static Type Mapping Extraction (`sharedMappings`)**:
-  Fills `sharedMappings` and `sharedContainerMappings` to provide accurate type descriptions for cross-package SDKs or microfrontend mesh topologies.
-- **Physical Isolation & Bundler Obfuscation Compatibility**:
-  Generated physical entrypoint files integrate seamlessly into standard npm packaging pipelines, fully compatible with downstream AST transformers and code protection tools.
+  Populates `sharedMappings` and `sharedContainerMappings` arrays to provide accurate type descriptions for cross-package SDKs or microfrontend mesh topologies;
+- **Built-in Obfuscation Protection**:
+  During the `closeBundle` lifecycle, automatically performs deep code obfuscation using `javascript-obfuscator` by default. Can be disabled via environment variable `MODULAR_OBFUSCATE=false`;
+- **Automated Packaging**:
+  Automatically synthesizes package-ready metadata (`package.json`, `index.d.ts`) and triggers `npm pack` in `outDir` to produce distribution `.tgz` tarballs.
 
 ---
 
@@ -48,7 +54,7 @@ npm install -D @path-ioc/pack
 
 ## Quick Start
 
-### Vite Configuration (`vite.config.ts`)
+### Dedicated Packaging Config (`vite.config.pack.ts`)
 
 ```typescript
 import { defineConfig } from "vite";
@@ -61,7 +67,8 @@ export default defineConfig({
   plugins: [
     modularPackPlugin({
       modulesPath: "src/modules",
-      // Optional: Custom on-disk entrypoint path (default: node_modules/.path-ioc/.modular-plugin-entry.ts)
+      outDir: "dist-plugin",
+      // Optional: Custom on-disk entrypoint path
       entryFile: "node_modules/.path-ioc/.modular-plugin-entry.ts",
       sharedMappings,
       sharedContainerMappings,
@@ -70,6 +77,11 @@ export default defineConfig({
 });
 ```
 
+To build and package your mesh bundle:
+```bash
+vite build --config vite.config.pack.ts
+```
+
 ---
 
 ## Configuration Options (`PackPluginOptions`)
@@ -78,11 +90,18 @@ export default defineConfig({
 | :--- | :--- | :--- | :--- |
 | **`modulesPath`** | `string` | `'src/modules'` | Root directory scanned for modular IoC entrypoints. |
 | **`entryFile`** | `string` | `'node_modules/.path-ioc/.modular-plugin-entry.ts'` | Target physical path for the generated entrypoint file. |
+| **`outDir`** | `string` | `'dist-plugin'` | Output directory for the packaged library bundle and npm tarball. |
 | **`sharedMappings`** | `string[]` | `[]` *(optional)* | Reference to an array that receives generated type mapping strings. |
 | **`sharedContainerMappings`** | `string[]` | `[]` *(optional)* | Reference to an array that receives generated container type mapping strings. |
 
 ---
 
+## Environment Variables
+
+- **`MODULAR_OBFUSCATE`**: Set to `false` (e.g. `MODULAR_OBFUSCATE=false vite build`) to disable the default `javascript-obfuscator` pass for debugging or open-source distribution.
+
+---
+
 ## Exported API
 
 ```typescript

package/README.zh-CN.md

@@ -15,12 +15,16 @@
   </p>
 </div>
 
+> 💡 **架构定位与使用边界警告**  
+> `@path-ioc/pack` 是专用于将 Mesh 模块目录打包为**独立发布的 npm 插件包/组件库**的专用 Vite 构建插件。  
+> **警告**：该插件会在构建期自动接管改写 Vite 的 Library 模式（`build.lib`）。**严禁无条件直接写入通用 Web 前端应用（如 SPA/SSR）的主构建配置中。** 推荐通过独立的打包配置（例如 `vite.config.pack.ts`）或专属构建脚本按需触发。
+
 ---
 
 ## 核心特性 (Features)
 
 - **物理入口自动生成 (Physical Entrypoint Generation)**：
-  在 Vite 构建流程中，自动深度扫描 `src/modules` 下所有包含 `index.ts/tsx` 的物理子目录，并在磁盘上自动生成/更新干净的入口文件（默认 `.modular-plugin-entry.ts`）。
+  在 Vite 构建流程中，自动深度扫描 `src/modules` 下所有包含 `index.ts/tsx` 的物理子目录，并在磁盘上自动生成/更新入口文件（默认 `node_modules/.path-ioc/.modular-plugin-entry.ts`）；
 - **Mesh 注册表与类型全导出**：
   自动生成统一的模块导入别名与导出，并导出标准运行期注册表数组 `modules`：
   ```typescript
@@ -30,9 +34,11 @@
   ];
   ```
 - **静态类型映射提取 (`sharedMappings`)**：
-  自动填充 `sharedMappings` 与 `sharedContainerMappings` 集合，为构建跨包 SDK 或微前端网格映射提供准确的类型描述。
-- **物理隔离与代码混淆兼容**：
-  物理生成的入口文件可直接用于 npm 打包流程，完美兼容各类 AST 物理打散与防篡改混淆工具。
+  自动填充 `sharedMappings` 与 `sharedContainerMappings` 集合，为构建跨包 SDK 或微前端网格映射提供准确的类型描述；
+- **内置源码深度混淆保护**：
+  构建结束时（`closeBundle` 生命周期）默认集成 `javascript-obfuscator` 对产物代码进行深度混淆保护，可通过环境变量 `MODULAR_OBFUSCATE=false` 关闭；
+- **交付包全自动打包**：
+  自动生成交付标准的 `package.json` 与 `index.d.ts` 类型声明，并自动在 `outDir` 目录调用 `npm pack` 产出可分发的 `.tgz` 压缩包。
 
 ---
 
@@ -48,7 +54,7 @@ npm install -D @path-ioc/pack
 
 ## 快速上手 (Quick Start)
 
-### Vite 配置 (`vite.config.ts`)
+### 专属 Vite 打包配置 (`vite.config.pack.ts`)
 
 ```typescript
 import { defineConfig } from "vite";
@@ -61,7 +67,8 @@ export default defineConfig({
   plugins: [
     modularPackPlugin({
       modulesPath: "src/modules",
-      // 可选：自定义生成的入口文件路径（默认存放在 node_modules/.path-ioc/.modular-plugin-entry.ts）
+      outDir: "dist-plugin",
+      // 可选：自定义生成的入口文件路径
       entryFile: "node_modules/.path-ioc/.modular-plugin-entry.ts",
       sharedMappings,
       sharedContainerMappings,
@@ -70,6 +77,11 @@ export default defineConfig({
 });
 ```
 
+执行打包命令：
+```bash
+vite build --config vite.config.pack.ts
+```
+
 ---
 
 ## 配置选项 (PackPluginOptions)
@@ -78,11 +90,18 @@ export default defineConfig({
 | :--- | :--- | :--- | :--- |
 | **`modulesPath`** | `string` | `'src/modules'` | 模块扫描的物理根目录路径。 |
 | **`entryFile`** | `string` | `'node_modules/.path-ioc/.modular-plugin-entry.ts'` | 物理生成的入口文件路径。 |
+| **`outDir`** | `string` | `'dist-plugin'` | 构建产物输出与 npm 打包目录。 |
 | **`sharedMappings`** | `string[]` | `[]` *(可选)* | 接收生成的类型映射字符串数组引用。 |
 | **`sharedContainerMappings`** | `string[]` | `[]` *(可选)* | 接收生成的容器类型映射字符串数组引用。 |
 
 ---
 
+## 环境变量 (Environment Variables)
+
+- **`MODULAR_OBFUSCATE`**：设置为 `false`（例如 `MODULAR_OBFUSCATE=false vite build --config vite.config.pack.ts`）可关闭默认的 `javascript-obfuscator` 混淆步骤，便于本地调试或开源包发布。
+
+---
+
 ## 导出的 API
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@path-ioc/pack",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Mesh registry distribution bundler & obfuscator for Path-IoC",
   "keywords": [
     "ioc",
@@ -50,7 +50,7 @@
     }
   },
   "devDependencies": {
-    "@path-ioc/unplugin": "0.1.3",
+    "@path-ioc/unplugin": "0.1.5",
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.5",