@teamix-evo/registry 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teamix Evo Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @teamix-evo/registry
+
+> Teamix Evo 协议包 — 提供 Schema、类型、加载器、校验器和策略决策引擎。
+
+## 定位
+
+registry 是整个 Teamix Evo 架构的**协议层**，负责定义：
+
+- 资源清单（VariantManifest）的结构约束
+- 项目配置（ProjectConfig）的 Schema
+- 安装状态（InstalledManifest）的追踪格式
+- 三种更新策略（frozen / regenerable / managed）的决策逻辑
+- Managed Regions 标记的解析与替换
+
+CLI 包和 design 包都依赖本包的协议定义工作。
+
+## 目录结构
+
+```
+packages/registry/
+├── src/
+│   ├── schema/
+│   │   ├── index.ts          # Schema 统一导出
+│   │   ├── manifest.ts       # VariantManifest Zod Schema
+│   │   ├── config.ts         # ProjectConfig Zod Schema
+│   │   └── installed.ts      # InstalledManifest Zod Schema
+│   ├── types.ts              # 从 Schema 推导的 TypeScript 类型
+│   ├── loader.ts             # 从文件系统加载 manifest
+│   ├── validator.ts          # 校验封装 + 友好错误消息
+│   ├── strategy.ts           # updateStrategy 决策函数
+│   ├── managed-regions.ts    # HTML 标记区解析与替换
+│   ├── index.ts              # 公共导出入口
+│   └── __tests__/            # 单元测试
+├── tsup.config.ts            # 构建配置（ESM + CJS + DTS）
+├── tsconfig.json
+└── package.json
+```
+
+## 研发流程
+
+### 1. 环境准备
+
+```bash
+# 在仓库根目录
+pnpm install
+```
+
+### 2. 开发
+
+```bash
+# 监听模式构建（修改即时编译）
+pnpm --filter @teamix-evo/registry dev
+```
+
+### 3. 新增 / 修改 Schema
+
+1. 在 `src/schema/` 中使用 Zod 定义或修改 Schema
+2. 在 `src/types.ts` 中通过 `z.infer<typeof XxxSchema>` 导出对应类型
+3. 在 `src/index.ts` 中确保新增的 Schema 和类型被导出
+4. 如需新增校验函数，在 `src/validator.ts` 中添加
+
+### 4. 修改策略逻辑
+
+- `src/strategy.ts` — 修改 `shouldUpdate` 或 `getUpdateAction`
+- `src/managed-regions.ts` — 修改标记解析或替换逻辑
+
+### 5. 测试
+
+```bash
+# 运行全部测试
+pnpm --filter @teamix-evo/registry test
+
+# 监听模式
+pnpm --filter @teamix-evo/registry test:watch
+```
+
+测试文件位于 `src/__tests__/`，覆盖：
+
+- `manifest.test.ts` — VariantManifest Schema 校验
+- `config.test.ts` — ProjectConfig Schema 校验
+- `installed.test.ts` — InstalledManifest Schema 校验
+- `validator.test.ts` — 友好错误消息格式化
+- `strategy.test.ts` — 三种策略决策逻辑
+- `managed-regions.test.ts` — 标记解析、替换、错误检测
+
+### 6. 类型检查
+
+```bash
+pnpm --filter @teamix-evo/registry typecheck
+```
+
+### 7. 构建
+
+```bash
+pnpm --filter @teamix-evo/registry build
+```
+
+产物输出到 `dist/`，包含：
+
+- `index.js` — ESM 格式
+- `index.cjs` — CommonJS 格式
+- `index.d.ts` — TypeScript 声明
+
+### 8. 发布前检查
+
+- 确保所有测试通过
+- 确保类型检查通过
+- 本包与 `teamix-evo`（CLI）使用 **linked** 版本策略，需一起发布
+
+## 关键约定
+
+- 所有 Schema 使用 [Zod](https://zod.dev/) 定义，运行时校验 + 编译时类型推导一体
+- `Result<T>` 类型用于校验返回，避免 throw（除 loader 和 managed-regions 外）
+- managed regions 标记格式：`<!-- teamix-evo:managed:start id="xxx" -->...<!-- teamix-evo:managed:end id="xxx" -->`
+- 同一文件中 region id 不得重复
+
+## 依赖关系
+
+```
+本包无内部包依赖
+CLI 包 → 依赖本包
+design 包 → devDependencies 引用本包（验证脚本）
+```