teamix-evo 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,222 @@
+# 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/                 # design init <variant> / list / list-variants
+│   │   │   │                       # / update(stub) / uninstall
+│   │   ├── skills/                 # source-mirror 模型见 ADR 0013
+│   │   │   │                       # add / list / update / sync / doctor / uninstall
+│   │   └── ui/                     # init / add / list
+│   ├── core/                       # 业务编排层(programmatic API,subpath 导出)
+│   │   ├── design-init.ts          # walk-and-merge 装机
+│   │   ├── design-pack-classify.ts # 路径分类(W1.4 tokens 提层)
+│   │   ├── installer.ts            # UI 资源安装引擎
+│   │   ├── updater.ts              # 三策略更新引擎(frozen/regenerable/managed)
+│   │   ├── ui-{add,init,list,client,installer}.ts
+│   │   ├── skills-{add,client,installer,sync,doctor}.ts
+│   │   ├── registry-client.ts      # 从 npm 包解析 variant
+│   │   └── state.ts                # .teamix-evo/ 状态读写
+│   ├── ide/
+│   │   ├── IdeAdapter.ts           # IDE 适配接口
+│   │   ├── QoderAdapter.ts         # Qoder 适配
+│   │   ├── ClaudeAdapter.ts        # Claude Code 适配
+│   │   └── index.ts                # detectIde / ALL_IDE_KINDS
+│   ├── utils/
+│   │   ├── fs.ts                   # 原子写入、备份
+│   │   ├── hash.ts                 # SHA-256
+│   │   ├── logger.ts               # 分级彩色日志
+│   │   ├── path.ts                 # 路径解析、目录遍历
+│   │   ├── template.ts             # Handlebars 渲染(带缓存)
+│   │   ├── transform-imports.ts    # 假路径 @/ → 用户 alias
+│   │   └── global-root.ts          # ~/.teamix-evo-global 解析(scope=global 用)
+│   └── __tests__/                  # 10 份单测,见下方测试章节
+├── tsup.config.ts                  # 构建配置(双入口:bin + core subpath)
+├── tsconfig.json
+└── package.json
+```
+
+## 研发流程
+
+### 1. 环境准备
+
+```bash
+# 在仓库根目录
+pnpm install
+
+# 需要先构建依赖包
+pnpm --filter @teamix-evo/registry build
+```
+
+### 2. 开发
+
+```bash
+# 监听模式构建
+pnpm --filter teamix-evo dev
+```
+
+构建产物双入口（见 `tsup.config.ts`）：
+
+- `dist/index.js` — CLI bin（ESM，带 `#!/usr/bin/env node` banner，对应 `package.json#bin`）
+- `dist/core/index.{js,d.ts}` — programmatic API（ESM + 类型，对应 `teamix-evo/core` subpath 导出，不带 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 适配
+
+当前支持 Qoder 与 Claude Code(`QoderAdapter` / `ClaudeAdapter`),`detectIde()` 自动判断。扩展新 IDE:
+
+1. 在 `src/ide/` 下新建 `XxxAdapter.ts`,实现 `IdeAdapter` 接口
+2. 在 `src/ide/index.ts` 的 `detectIde()` 中添加检测逻辑
+3. 在 `ALL_IDE_KINDS` 与 `SkillIde` 类型中加上新 IDE 名
+
+### 6. 测试
+
+```bash
+# 运行全部测试
+pnpm --filter teamix-evo test
+
+# 监听模式
+pnpm --filter teamix-evo test:watch
+```
+
+测试文件位于 `src/__tests__/`,覆盖:
+
+- `core-api.test.ts` — programmatic core API(runDesignInit / runSkillsAdd / runUiAdd)
+- `design-init-skills-link.test.ts` — design init ↔ skills auto-install 联动
+- `installer.test.ts` — UI 资源安装(frozen / regenerable)
+- `ui-installer.test.ts` — UI 装机引擎(依赖图 / alias 转换)
+- `skills-installer.test.ts` — skills 装机(source-mirror)
+- `skills-sync-doctor.test.ts` — source ↔ mirror 漂移检测
+- `updater.test.ts` — 三策略更新逻辑(ADR 0003)
+- `state.test.ts` — `.teamix-evo/` 状态读写
+- `template.test.ts` — Handlebars 渲染
+- `transform-imports.test.ts` — 假路径(@/)→ 用户 alias 转换
+
+### 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>`                  | 初始化设计体系(variant 必填)                      |
+| `teamix-evo design list-variants`                   | 列出可用 variant                                  |
+| `teamix-evo design list`                            | 查看已装机的 variant                              |
+| `teamix-evo design update`                          | 更新已装资源(stub,v0.7 见 ADR 0019)               |
+| `teamix-evo design uninstall`                       | 卸载已装 design                                   |
+| `teamix-evo skills add [name...]`                   | 装 skills(写源 + 镜像 IDE);不传 = 全装            |
+| `teamix-evo skills list`                            | 列出所有 skill 的安装状态                         |
+| `teamix-evo skills update`                          | 升级 skills(保留 managed 改动)                    |
+| `teamix-evo skills sync [name...]`                  | 源 → IDE 镜像(漂移恢复用)                         |
+| `teamix-evo skills doctor`                          | 检测源/镜像漂移(ADR 0013)                         |
+| `teamix-evo skills uninstall`                       | 卸载 skills(源 + 镜像 + lock)                     |
+| `teamix-evo ui init`                                | 初始化 ui 配置(aliases / iconLibrary / tsx / rsc) |
+| `teamix-evo ui add <id...>`                         | 安装指定 ui 组件源码                              |
+| `teamix-evo ui list [--installed]`                  | 列出可用/已安装 ui 组件                           |
+| `teamix-evo biz-ui list-variants`                   | 列出 biz-ui 包内提供的业务变体                    |
+| `teamix-evo biz-ui add <id...> --variant <name>`    | 安装变体感知业务组件(`--variant` 必填)            |
+| `teamix-evo templates list-variants`                | 列出 templates 包内提供的页面模板变体             |
+| `teamix-evo templates add <id...> --variant <name>` | 安装变体感知页面模板(`--variant` 必填)            |
+
+> 占位组件 → 真组件的升级流程**不是** CLI 子命令，由
+> [`teamix-evo-ui-upgrade`](../../packages/skills/skills/teamix-evo-ui-upgrade/SKILL.md)
+> skill 在 IDE 内驱动,底层仍调用 `teamix-evo ui add`。
+
+### 全局装 skill(`--scope global`)
+
+`skills add` 支持 `--scope global` 装到 IDE 全局(`~/.qoder/skills/` + `~/.claude/skills/`)。当 cwd 不是 Teamix Evo 项目时,工具会自动把元数据写到 `~/.teamix-evo-global/`,不污染当前目录。
+
+```bash
+# Onboarding 推荐:全局装 manage skill
+npx teamix-evo@latest skills add teamix-evo-manage --scope global --ide claude,qoder -y
+
+# 后续维护(update / uninstall 等)需 cd 到全局元数据根
+cd ~/.teamix-evo-global && npx teamix-evo skills update
+```
+
+## 关键约定
+
+- 使用 `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,442 @@
+import { InstalledResource, SkillIde, SkillScope, UiAliases, UiEntry, VariantManifest, SkillsPackageManifest, SkillEntry, 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"`, `"uni-manager"`). */
+    variant: string;
+    /** IDE identifier written into config.json (e.g. `"qoder"`, `"claude"`). */
+    ide: string;
+    /** Override the design package name (defaults to `"@teamix-evo/design"`). */
+    packageName?: string;
+    /**
+     * Override resolution of the design package root. When provided, skips
+     * `require.resolve("<packageName>/package.json")`. Useful for tests that
+     * want to point at a fixture tree, and for embedding inside `create`
+     * where the package may not yet be installed in the consumer.
+     */
+    packageRoot?: string;
+}
+/**
+ * Outcome of the post-init skill auto-install step. `attempted` lists the skill
+ * ids we tried to install (baseline + variant overlay); `addedSkillIds` is what
+ * was actually installed (the rest were already present); `missing` lists skill
+ * ids that aren't in the manifest (warned, not fatal).
+ */
+interface SkillsAutoInstallResult {
+    attempted: string[];
+    addedSkillIds: string[];
+    skippedSkillIds: string[];
+    missing: string[];
+}
+type RunDesignInitResult = {
+    status: 'installed';
+    packageName: string;
+    variant: string;
+    version: string;
+    count: number;
+    resources: InstalledResource[];
+    /** Per ADR 0010 §4 diagnostics. */
+    merge: {
+        overrides: string[];
+        variantAdds: string[];
+        defaultPassThrough: string[];
+    };
+    /** Result of the auto-install of baseline + variant design-rules skills. */
+    skills?: SkillsAutoInstallResult;
+} | {
+    status: 'already-initialized';
+    existingVariant: string;
+};
+/**
+ * Programmatic equivalent of `teamix-evo design init <variant>`.
+ *
+ * Side effects:
+ * - Creates `<projectRoot>/.teamix-evo/`
+ * - Walks `default/` + `variants/<variant>/`, classifies each file by path
+ *   convention, writes to consumer (skipping `frozen` files that already exist)
+ * - Writes `pack.lock.json`, `config.json`, `manifest.json` (installed)
+ *
+ * No interactive prompts, no `process.exit`. Throws on hard failure (P8).
+ */
+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>;
+
+/**
+ * Source-mirror skills installer (per ADR 0013).
+ *
+ * Two-stage flow:
+ *   1. **writeSkillSources** — render upstream `<packageRoot>/<skill.source>` and
+ *      write to `<projectRoot>/.teamix-evo/skills/<id>/` (the consumer-side
+ *      source of truth, regenerable, in git).
+ *   2. **syncSkillsToIdes** — pure byte-for-byte copy from source dir to each
+ *      requested IDE mirror path (`.qoder/skills/<id>/`, `.claude/skills/<id>/`).
+ *      Mirrors are 100% derived; not subject to managed-region preservation.
+ *
+ * `installSkills` orchestrates both. `updateSkills` re-renders the source with
+ * managed-region preservation against the existing source (NOT the mirrors),
+ * then re-syncs.
+ */
+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 using the
+ * source-mirror flow. Returns InstalledResource records for both source files
+ * and IDE mirror files.
+ */
+declare function installSkills(options: SkillInstallOptions): Promise<SkillInstallResult>;
+interface SkillUpdateOptions extends SkillInstallOptions {
+    /**
+     * Optional: existing installed records (legacy parameter kept for callers that
+     * still pass it). The refactored updater consults the file-system source under
+     * `.teamix-evo/skills/<id>/` for managed-region preservation, so this is
+     * unused by the new flow. Callers should stop passing it.
+     */
+    installed?: InstalledResource[];
+}
+interface SkillUpdateResult {
+    resources: InstalledResource[];
+    summary: {
+        overwritten: number;
+        managed: number;
+        skipped: number;
+        created: number;
+    };
+}
+/**
+ * Update skills with managed-region preservation applied at the SOURCE layer
+ * (not the mirrors). After source is rewritten, mirrors are re-synced cleanly.
+ */
+declare function updateSkills(options: SkillUpdateOptions): Promise<SkillUpdateResult>;
+/**
+ * Sync existing skill sources to the requested IDE mirror paths.
+ *
+ * Used by:
+ *   - `skills add` (immediate mirror after source write — handled by installSkills)
+ *   - `skills sync` (re-mirror after the user adds an IDE or moves machines)
+ *   - `skills update` (re-mirror after source is rewritten)
+ *
+ * `onlyIds` lets the caller limit which skills are synced.
+ */
+interface SkillSyncOptions {
+    projectRoot: string;
+    /** Skills present in the source dir to mirror (caller derives from lock). */
+    skills: ReadonlyArray<{
+        id: string;
+        name: string;
+        updateStrategy: SkillEntry['updateStrategy'];
+    }>;
+    ides: readonly SkillIde[];
+    scope: SkillScope;
+    onlyIds?: string[];
+}
+interface SkillSyncResult {
+    resources: InstalledResource[];
+    count: number;
+}
+/**
+ * Mirror existing source dirs (`.teamix-evo/skills/<id>/`) to the given IDE
+ * paths. Pure byte-for-byte copy — no rendering, no merge.
+ */
+declare function syncSkillsToIdes(options: SkillSyncOptions): Promise<SkillSyncResult>;
+/**
+ * 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 SkillSyncOptions, type SkillSyncResult, 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, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };