teamix-evo 0.1.0 → 0.2.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,196 @@
+# teamix-evo (CLI)
+
+> Teamix Evo 命令行入口 — 管理设计体系资源的安装、更新和查询。
+
+## 定位
+
+CLI 是 Teamix Evo 的**执行层**，用户通过 `npx teamix-evo` 或全局安装后使用。核心职责：
+
+- 从 npm 包加载 variant manifest 和模板数据
+- 使用 Handlebars 渲染模板为目标文件
+- 根据 updateStrategy（frozen / regenerable / managed）决定文件更新方式
+- 维护 `.teamix-evo/` 下的配置和状态文件
+
+## 目录结构
+
+```
+packages/cli/
+├── src/
+│   ├── index.ts                    # 入口：Commander 注册
+│   ├── commands/
+│   │   ├── design/
+│   │   │   ├── index.ts            # design 命令组
+│   │   │   ├── init.ts             # design init [variant]
+│   │   │   ├── update.ts           # design update
+│   │   │   └── list.ts             # design list
+│   │   ├── skills/
+│   │   │   ├── index.ts            # skills 命令组
+│   │   │   ├── add.ts              # skills add [name...]
+│   │   │   ├── list.ts             # skills list
+│   │   │   ├── update.ts           # skills update
+│   │   │   └── uninstall.ts        # skills uninstall
+│   │   └── ui/
+│   │       ├── index.ts            # ui 命令组
+│   │       ├── init.ts             # ui init
+│   │       ├── add.ts              # ui add <id...>
+│   │       └── list.ts             # ui list
+│   ├── core/
+│   │   ├── installer.ts            # 资源安装引擎
+│   │   ├── updater.ts              # 资源更新引擎（三策略处理）
+│   │   ├── registry-client.ts      # 从 npm 包解析 variant
+│   │   └── state.ts                # .teamix-evo/ 状态读写
+│   ├── ide/
+│   │   ├── IdeAdapter.ts           # IDE 适配接口
+│   │   ├── QoderAdapter.ts         # Qoder 适配实现
+│   │   └── index.ts                # IDE 检测入口
+│   ├── utils/
+│   │   ├── fs.ts                   # 原子写入、备份、文件操作
+│   │   ├── hash.ts                 # SHA-256 哈希
+│   │   ├── logger.ts               # 分级彩色日志
+│   │   ├── path.ts                 # 路径解析、目录遍历
+│   │   └── template.ts             # Handlebars 渲染（带缓存）
+│   └── __tests__/                  # 单元测试
+├── tsup.config.ts                  # 构建配置（单文件 ESM + shebang）
+├── tsconfig.json
+└── package.json
+```
+
+## 研发流程
+
+### 1. 环境准备
+
+```bash
+# 在仓库根目录
+pnpm install
+
+# 需要先构建依赖包
+pnpm --filter @teamix-evo/registry build
+```
+
+### 2. 开发
+
+```bash
+# 监听模式构建
+pnpm --filter teamix-evo dev
+```
+
+构建产物为单文件 `dist/index.js`（ESM，带 `#!/usr/bin/env node` banner）。
+
+### 3. 新增命令
+
+1. 在 `src/commands/<group>/` 下新建命令文件
+2. 使用 Commander 的 `Command` 类定义命令
+3. 在对应 group 的 `index.ts` 中注册（`addCommand`）
+4. 如果是新的命令组，在 `src/index.ts` 中注册
+
+示例模式：
+
+```typescript
+import { Command } from 'commander';
+import { detectIde } from '../../ide/index.js';
+import { logger } from '../../utils/logger.js';
+
+export const myCommand = new Command('my-cmd')
+  .description('命令描述')
+  .action(async () => {
+    try {
+      const ide = detectIde();
+      const projectRoot = ide.getProjectRoot();
+      // ... 业务逻辑
+      logger.success('完成');
+    } catch (err) {
+      logger.error(`Failed: ${(err as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+```
+
+### 4. 修改核心引擎
+
+- `core/installer.ts` — 资源首次安装逻辑
+- `core/updater.ts` — 资源更新逻辑（处理三种策略 + managed regions）
+- `core/registry-client.ts` — 从 node_modules 解析 variant 包路径
+- `core/state.ts` — `.teamix-evo/config.json` 和 `manifest.json` 的读写
+
+### 5. IDE 适配
+
+当前 MVP 仅支持 Qoder。扩展新 IDE：
+
+1. 在 `src/ide/` 下新建 `XxxAdapter.ts`，实现 `IdeAdapter` 接口
+2. 在 `src/ide/index.ts` 的 `detectIde()` 中添加检测逻辑
+
+### 6. 测试
+
+```bash
+# 运行全部测试
+pnpm --filter teamix-evo test
+
+# 监听模式
+pnpm --filter teamix-evo test:watch
+```
+
+测试文件位于 `src/__tests__/`，覆盖：
+
+- `installer.test.ts` — 资源安装（plain / template / recursive）
+- `updater.test.ts` — 三种策略更新逻辑
+- `state.test.ts` — 配置文件读写
+- `template.test.ts` — Handlebars 渲染
+
+### 7. 类型检查 & 构建
+
+```bash
+pnpm --filter teamix-evo typecheck
+pnpm --filter teamix-evo build
+```
+
+### 8. 本地调试
+
+```bash
+# 构建后在任意目录执行
+node /path/to/packages/cli/dist/index.js design init opentrek
+
+# 或通过 pnpm 链接
+cd packages/cli && pnpm link --global
+teamix-evo design init opentrek
+```
+
+开启调试日志：
+
+```bash
+TEAMIX_DEBUG=1 teamix-evo design init opentrek
+```
+
+## 命令参考
+
+| 命令                               | 说明                            |
+| ---------------------------------- | ------------------------------- |
+| `teamix-evo design init [variant]` | 初始化设计体系（默认 opentrek） |
+| `teamix-evo design update`         | 更新已安装的设计资源            |
+| `teamix-evo design list`           | 查看已安装信息                  |
+| `teamix-evo skills add [name...]`  | 装入 skills（全量/增量）        |
+| `teamix-evo skills list`           | 列出所有 skill 的安装状态       |
+| `teamix-evo skills update`         | 升级已安装 skills               |
+| `teamix-evo skills uninstall`      | 卸载 skills                     |
+| `teamix-evo ui init`               | 初始化 ui 组件环境              |
+| `teamix-evo ui add <id...>`        | 安装指定 ui 组件源码            |
+| `teamix-evo ui list`               | 列出可用/已安装 ui 组件         |
+
+选项：
+
+- `--tailwind <v3|v4>` — 指定 Tailwind CSS 版本（默认 v3）
+
+## 关键约定
+
+- 使用 `process.exitCode = 1` 而非 `process.exit(1)`，确保异步操作完成
+- 文件写入使用 `writeFileSafe`（tmp + rename 原子写入）
+- 更新前自动备份到 `.teamix-evo/.backups/`
+- 版本号从 `package.json` 动态读取，不硬编码
+
+## 依赖关系
+
+```
+本包 → @teamix-evo/registry（协议层）
+本包 → @teamix-evo/design（设计资源，运行时解析）
+本包 → @teamix-evo/skills（技能资源，运行时解析）
+本包 → @teamix-evo/ui（UI 资源，manifest + 源码）
+```

package/dist/core/index.d.ts

@@ -0,0 +1,364 @@
+import { TailwindVersion, InstalledResource, SkillIde, SkillScope, UiAliases, UiEntry, VariantManifest, SkillsPackageManifest, UiPackageManifest, InstalledManifest, ProjectConfig } from '@teamix-evo/registry';
+export { InstalledManifest, InstalledResource, ProjectConfig, SkillIde, SkillScope, TailwindVersion, UiAliases } from '@teamix-evo/registry';
+
+interface RunDesignInitOptions {
+    /** Absolute project root directory. */
+    projectRoot: string;
+    /** Design variant id, e.g. "opentrek". */
+    variant: string;
+    /** Tailwind major version of the consuming project. */
+    tailwind: TailwindVersion;
+    /** IDE identifier written into config.json (e.g. "qoder", "claude"). */
+    ide: string;
+    /** Override the design package name (defaults to "@teamix-evo/design"). */
+    packageName?: string;
+}
+type RunDesignInitResult = {
+    status: 'installed';
+    packageName: string;
+    variant: string;
+    version: string;
+    tailwind: TailwindVersion;
+    count: number;
+    resources: InstalledResource[];
+} | {
+    status: 'already-initialized';
+    existingVariant: string;
+};
+/**
+ * Programmatic equivalent of `teamix-evo design init <variant>`.
+ *
+ * Side effects:
+ * - Creates `<projectRoot>/.teamix-evo/`
+ * - Writes `config.json` and `manifest.json`
+ * - Installs design resources from the variant manifest into the project
+ *
+ * No interactive prompts, no `process.exit`. Throws on hard failure.
+ */
+declare function runDesignInit(options: RunDesignInitOptions): Promise<RunDesignInitResult>;
+
+interface RunSkillsAddOptions {
+    /** Absolute project root directory. */
+    projectRoot: string;
+    /**
+     * Target IDEs to inject skills into. Optional in incremental mode (i.e. when
+     * `names` is provided) — falls back to the previously installed config.
+     * Required for the bulk path.
+     */
+    ides?: readonly SkillIde[];
+    /**
+     * Install scope. Optional in incremental mode (falls back to existing
+     * config). Required for the bulk path.
+     */
+    scope?: SkillScope;
+    /** IDE identifier written into config.ide when bootstrapping a fresh config (defaults to "qoder"). */
+    ide?: string;
+    /** Override the skills package name (defaults to "@teamix-evo/skills"). */
+    packageName?: string;
+    /**
+     * Optional skill ids to add. When omitted, all skills declared in the
+     * manifest are installed (bulk mode). When provided, only the listed skills
+     * are added (incremental mode); skills that are already installed are
+     * silently skipped and reported via `skippedSkillIds`.
+     */
+    names?: readonly string[];
+}
+type RunSkillsAddResult = {
+    status: 'installed';
+    packageName: string;
+    version: string;
+    ides: SkillIde[];
+    scope: SkillScope;
+    /** Number of skills that were freshly added in this call. */
+    skillCount: number;
+    /** Number of files written by `installSkills` for the freshly added skills. */
+    fileCount: number;
+    /** InstalledResource records for the freshly added skills only. */
+    resources: InstalledResource[];
+    /** Skill ids that were freshly added in this call. */
+    addedSkillIds: string[];
+    /** Skill ids that were requested but already installed; skipped. */
+    skippedSkillIds: string[];
+} | {
+    /** Returned only from bulk mode when a skills package is already installed. */
+    status: 'already-added';
+};
+/**
+ * Programmatic equivalent of `teamix-evo skills add`.
+ *
+ * - Bulk mode (`names` omitted): install every skill in the manifest. Re-run
+ *   on a project that already has `packages.skills` returns `'already-added'`.
+ * - Incremental mode (`names` provided): install only the listed skills. Skills
+ *   already present are skipped (use `skills update` to refresh). `ides`/`scope`
+ *   may be omitted — they fall back to the previously installed config.
+ */
+declare function runSkillsAdd(options: RunSkillsAddOptions): Promise<RunSkillsAddResult>;
+
+declare const DEFAULT_UI_ALIASES: UiAliases;
+declare const DEFAULT_UI_ICON_LIBRARY = "lucide";
+interface RunUiInitOptions {
+    /** Absolute project root directory. */
+    projectRoot: string;
+    /** Component aliases. Falls back to {@link DEFAULT_UI_ALIASES}. */
+    aliases?: Partial<UiAliases>;
+    /** Declared icon library (does not trigger code rewrite). Defaults to "lucide". */
+    iconLibrary?: string;
+    /** Whether the project uses TSX (true) or JSX (false). Defaults to true. */
+    tsx?: boolean;
+    /** Whether the project emits React Server Components markers. Defaults to false. */
+    rsc?: boolean;
+    /** IDE identifier written into config.ide when bootstrapping a fresh config (defaults to "qoder"). */
+    ide?: string;
+}
+type RunUiInitResult = {
+    status: 'installed';
+    aliases: UiAliases;
+    iconLibrary: string;
+    tsx: boolean;
+    rsc: boolean;
+} | {
+    status: 'already-initialized';
+};
+/**
+ * Programmatic equivalent of `teamix-evo ui init`.
+ *
+ * Writes `packages.ui` into `.teamix-evo/config.json` only — no resource files
+ * are touched. Use {@link runUiAdd} afterwards to install component sources.
+ */
+declare function runUiInit(options: RunUiInitOptions): Promise<RunUiInitResult>;
+
+interface RunUiAddOptions {
+    /** Absolute project root directory. */
+    projectRoot: string;
+    /** Entry ids to install (registry dependencies are resolved transitively). */
+    ids: string[];
+    /** When true, overwrite frozen entries that already exist on disk. */
+    overwrite?: boolean;
+    /** Override the ui package name (defaults to "@teamix-evo/ui"). */
+    packageName?: string;
+}
+interface RunUiAddResult {
+    packageName: string;
+    /** Registered ids in install order (deps + requested). */
+    orderedIds: string[];
+    /** Number of files written. */
+    written: number;
+    /** Number of files skipped due to frozen + exists. */
+    skipped: number;
+    /** Meta files dropped under .teamix-evo/design/components/. */
+    metaFiles: string[];
+    /** Aggregate npm dependencies of the installed entries. */
+    npmDependencies: Record<string, string>;
+    /** Per-file install records merged into the installed manifest. */
+    resources: InstalledResource[];
+}
+/**
+ * Programmatic equivalent of `teamix-evo ui add <ids...>`.
+ *
+ * Requires `packages.ui` to already exist in `.teamix-evo/config.json`
+ * (i.e. {@link runUiInit} was called earlier).
+ */
+declare function runUiAdd(options: RunUiAddOptions): Promise<RunUiAddResult>;
+
+interface RunUiListOptions {
+    /** Absolute project root directory. */
+    projectRoot: string;
+    /** When true, only return entries that are already installed. */
+    installedOnly?: boolean;
+    /** Override the ui package name (defaults to "@teamix-evo/ui"). */
+    packageName?: string;
+}
+interface UiEntryListItem {
+    id: string;
+    type: UiEntry['type'];
+    description: string;
+    installed: boolean;
+}
+interface RunUiListResult {
+    packageName: string;
+    /** Total number of entries declared by the package manifest. */
+    total: number;
+    /** Number of installed entries (based on the project's installed manifest). */
+    installedCount: number;
+    /** Filtered + decorated entries. */
+    entries: UiEntryListItem[];
+}
+/**
+ * Programmatic equivalent of `teamix-evo ui list`.
+ *
+ * Returns structured data; the CLI command formats it for terminal output.
+ */
+declare function runUiList(options: RunUiListOptions): Promise<RunUiListResult>;
+
+interface InstallOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** The variant manifest */
+    manifest: VariantManifest;
+    /** Template data for Handlebars rendering */
+    data: Record<string, unknown>;
+    /** Absolute path to the variant directory (where source files live) */
+    variantDir: string;
+    /** Absolute path to the package root (for resolving _template/ sources) */
+    packageRoot: string;
+}
+interface InstallResult {
+    /** Successfully installed resource records */
+    resources: InstalledResource[];
+    /** Number of resources installed */
+    count: number;
+}
+/**
+ * Install resources from a variant manifest into the project.
+ */
+declare function installResources(options: InstallOptions): Promise<InstallResult>;
+
+interface SkillInstallOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Skills package manifest */
+    manifest: SkillsPackageManifest;
+    /** Template data */
+    data: Record<string, unknown>;
+    /** Absolute skills package root */
+    packageRoot: string;
+    /** IDE kinds to install for (intersection with skill.ides is computed) */
+    ides: readonly SkillIde[];
+    /** Install scope */
+    scope: SkillScope;
+    /** Optional: limit to specific skill ids */
+    onlyIds?: string[];
+}
+interface SkillInstallResult {
+    resources: InstalledResource[];
+    count: number;
+}
+/**
+ * Install (or reinstall) all skills declared in the manifest, fanning out to the
+ * intersection of requested IDEs and each skill's declared `ides`.
+ */
+declare function installSkills(options: SkillInstallOptions): Promise<SkillInstallResult>;
+interface SkillUpdateOptions extends SkillInstallOptions {
+    /** Existing installed records for the skills package */
+    installed: InstalledResource[];
+}
+interface SkillUpdateResult {
+    resources: InstalledResource[];
+    summary: {
+        overwritten: number;
+        managed: number;
+        skipped: number;
+        created: number;
+    };
+}
+/**
+ * Update skills according to their updateStrategy.
+ */
+declare function updateSkills(options: SkillUpdateOptions): Promise<SkillUpdateResult>;
+/**
+ * Remove all installed skill files. Returns the absolute paths removed.
+ */
+declare function removeSkillFiles(records: InstalledResource[]): Promise<string[]>;
+
+interface UiInstallOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** UI package manifest */
+    manifest: UiPackageManifest;
+    /** Absolute ui package root (used to resolve entry source paths) */
+    packageRoot: string;
+    /** Aliases configured in `packages.ui.aliases` */
+    aliases: UiAliases;
+    /** Entry ids the user explicitly requested to add */
+    requested: string[];
+    /** When true, skip writing entries whose target file already exists (frozen-on-add). */
+    skipExisting?: boolean;
+}
+interface UiInstallResult {
+    /** Ordered list of entry ids that were processed (deps + requested) */
+    orderedIds: string[];
+    /** Per-file install records (for InstalledManifest) */
+    resources: InstalledResource[];
+    /** Aggregate npm dependencies across the installed entries */
+    npmDependencies: Record<string, string>;
+    /** Number of files written */
+    written: number;
+    /** Number of files skipped because they already exist (frozen) */
+    skipped: number;
+    /** Meta files dropped under .teamix-evo/design/components/ */
+    metaFiles: string[];
+}
+/**
+ * Install the requested ui entries (transitively resolving registryDependencies).
+ * For frozen entries that already exist on disk, the write is skipped — shadcn-style.
+ */
+declare function installUiEntries(options: UiInstallOptions): Promise<UiInstallResult>;
+/**
+ * Remove all installed ui resource files and prune empty parent directories.
+ */
+declare function removeUiFiles(records: InstalledResource[]): Promise<string[]>;
+
+/**
+ * Load the variant manifest and _data.json for template rendering.
+ *
+ * @param packageName - e.g. "@teamix-evo/design"
+ * @param variant - e.g. "opentrek"
+ * @returns manifest and data for template rendering
+ */
+declare function loadVariantData(packageName: string, variant: string): Promise<{
+    manifest: VariantManifest;
+    data: Record<string, unknown>;
+    variantDir: string;
+    packageRoot: string;
+}>;
+
+/**
+ * Load the skills package manifest and optional shared `_data.json`.
+ *
+ * @param packageName - e.g. "@teamix-evo/skills"
+ */
+declare function loadSkillsData(packageName: string): Promise<{
+    manifest: SkillsPackageManifest;
+    data: Record<string, unknown>;
+    packageRoot: string;
+}>;
+
+/**
+ * Load the ui package manifest and optional shared `_data.json`.
+ *
+ * @param packageName - e.g. "@teamix-evo/ui"
+ */
+declare function loadUiData(packageName: string): Promise<{
+    manifest: UiPackageManifest;
+    data: Record<string, unknown>;
+    packageRoot: string;
+}>;
+
+/**
+ * Get the .teamix-evo directory path for a project.
+ */
+declare function getTeamixDir(projectRoot: string): string;
+/**
+ * Ensure the .teamix-evo directory exists.
+ */
+declare function ensureTeamixDir(projectRoot: string): Promise<string>;
+/**
+ * Read the project config from .teamix-evo/config.json.
+ * Returns null if the file does not exist.
+ */
+declare function readProjectConfig(projectRoot: string): Promise<ProjectConfig | null>;
+/**
+ * Write the project config to .teamix-evo/config.json.
+ */
+declare function writeProjectConfig(projectRoot: string, config: ProjectConfig): Promise<void>;
+/**
+ * Read the installed manifest from .teamix-evo/manifest.json.
+ * Returns null if the file does not exist.
+ */
+declare function readInstalledManifest(projectRoot: string): Promise<InstalledManifest | null>;
+/**
+ * Write the installed manifest to .teamix-evo/manifest.json.
+ */
+declare function writeInstalledManifest(projectRoot: string, manifest: InstalledManifest): Promise<void>;
+
+export { DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type RunDesignInitOptions, type RunDesignInitResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunUiAddOptions, type RunUiAddResult, type RunUiInitOptions, type RunUiInitResult, type RunUiListOptions, type RunUiListResult, type SkillInstallOptions, type SkillInstallResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, ensureTeamixDir, getTeamixDir, installResources, installSkills, installUiEntries, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runDesignInit, runSkillsAdd, runUiAdd, runUiInit, runUiList, updateSkills, writeInstalledManifest, writeProjectConfig };