teamix-evo 0.3.1 → 0.4.1

package/README.md

@@ -18,14 +18,13 @@ packages/cli/
 ├── src/
 │   ├── index.ts                    # 入口:Commander 注册
 │   ├── commands/
-│   │   ├── design/                 # design init <variant> / list / list-variants
+│   │   ├── tokens/                 # tokens 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 提层)
+│   │   ├── tokens-init.ts          # 变体自包含装机(ADR 0020)
 │   │   ├── installer.ts            # UI 资源安装引擎
 │   │   ├── updater.ts              # 三策略更新引擎(frozen/regenerable/managed)
 │   │   ├── ui-{add,init,list,client,installer}.ts
@@ -131,8 +130,8 @@ 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 联动
+- `core-api.test.ts` — programmatic core API(runTokensInit / runSkillsAdd / runUiAdd)
+- `tokens-init-skills-link.test.ts` — tokens init ↔ skills auto-install 联动
 - `installer.test.ts` — UI 资源安装(frozen / regenerable)
 - `ui-installer.test.ts` — UI 装机引擎(依赖图 / alias 转换)
 - `skills-installer.test.ts` — skills 装机(source-mirror)
@@ -153,45 +152,47 @@ pnpm --filter teamix-evo build
 
 ```bash
 # 构建后在任意目录执行
-node /path/to/packages/cli/dist/index.js design init opentrek
+node /path/to/packages/cli/dist/index.js tokens init opentrek
 
 # 或通过 pnpm 链接
 cd packages/cli && pnpm link --global
-teamix-evo design init opentrek
+teamix-evo tokens init opentrek
 ```
 
 开启调试日志：
 
 ```bash
-TEAMIX_DEBUG=1 teamix-evo design init opentrek
+TEAMIX_DEBUG=1 teamix-evo tokens 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` 必填)            |
+| 命令                                                | 说明                                                           |
+| --------------------------------------------------- | -------------------------------------------------------------- |
+| `teamix-evo tokens init <variant>`                  | 初始化 tokens                                                  |
+| `teamix-evo tokens list-variants`                   | 列出可用 variant                                               |
+| `teamix-evo tokens list`                            | 查看已装机的 variant                                           |
+| `teamix-evo tokens update`                          | 更新已装资源(stub,v0.7 见 ADR 0019)                            |
+| `teamix-evo tokens uninstall`                       | 卸载已装 tokens                                                |
+| `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` 必填)                         |
+| `teamix-evo logs analyze [...]`                     | 分析 vibe-logger AI 调用链(`.log/ai/**/*.jsonl`)               |
+| `teamix-evo logs trace [...]`                       | 按会话还原 AI 调用链(prompt → PreToolUse → PostToolUse → Stop) |
 
 > 占位组件 → 真组件的升级流程**不是** CLI 子命令，由
-> [`teamix-evo-ui-upgrade`](../../packages/skills/skills/teamix-evo-ui-upgrade/SKILL.md)
-> skill 在 IDE 内驱动,底层仍调用 `teamix-evo ui add`。
+> [`teamix-evo-manage`](../../packages/skills/src/teamix-evo-manage/SKILL.md)
+> skill 在 IDE 内驱动「场景 6」,底层仍调用 `teamix-evo ui add`。
 
 ### 全局装 skill(`--scope global`)
 
@@ -216,7 +217,7 @@ cd ~/.teamix-evo-global && npx teamix-evo skills update
 
 ```
 本包 → @teamix-evo/registry（协议层）
-本包 → @teamix-evo/design（设计资源，运行时解析）
+本包 → @teamix-evo/tokens（设计 tokens，运行时解析）
 本包 → @teamix-evo/skills（技能资源，运行时解析）
 本包 → @teamix-evo/ui（UI 资源，manifest + 源码）
 ```

package/dist/core/index.d.ts

@@ -1,17 +1,17 @@
 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 {
+interface RunTokensInitOptions {
     /** Absolute project root directory. */
     projectRoot: string;
-    /** Design variant id (e.g. `"opentrek"`, `"uni-manager"`). */
+    /** Tokens 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"`). */
+    /** Override the tokens package name (defaults to `"@teamix-evo/tokens"`). */
     packageName?: string;
     /**
-     * Override resolution of the design package root. When provided, skips
+     * Override resolution of the tokens 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.
@@ -19,10 +19,11 @@ interface RunDesignInitOptions {
     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).
+ * Outcome of the post-init skill auto-install step. `attempted` is the variant
+ * skill id we tried to install; `addedSkillIds` is what was actually installed
+ * (empty if the skill was already present); `missing` lists ids that aren't in
+ * the manifest (warned, not fatal). Per ADR / "skills self-contained" decision,
+ * each variant skill is fully self-contained — no separate baseline skill.
  */
 interface SkillsAutoInstallResult {
     attempted: string[];
@@ -30,37 +31,54 @@ interface SkillsAutoInstallResult {
     skippedSkillIds: string[];
     missing: string[];
 }
-type RunDesignInitResult = {
+type RunTokensInitResult = {
     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. */
+    /** Result of the auto-install of the matching design skill. */
     skills?: SkillsAutoInstallResult;
 } | {
     status: 'already-initialized';
     existingVariant: string;
+} | {
+    status: 'variant-mismatch';
+    existingVariant: string;
+    requestedVariant: string;
 };
 /**
- * Programmatic equivalent of `teamix-evo design init <variant>`.
+ * Programmatic equivalent of `teamix-evo tokens 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)
+ * - Copies the variant's `theme.css` to `<projectRoot>/tokens/tokens.theme.css`
+ * - Ensures `<projectRoot>/tokens/tokens.overrides.css` exists (frozen)
+ * - Writes `tokens-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>;
+declare function runTokensInit(options: RunTokensInitOptions): Promise<RunTokensInitResult>;
+/**
+ * List all variants advertised by the top-level tokens catalog. Used by
+ * `teamix-evo tokens list-variants`.
+ */
+interface ListVariantsResult {
+    packageName: string;
+    packageVersion: string;
+    variants: Array<{
+        name: string;
+        displayName: string;
+        version: string;
+        description?: string;
+        linked?: {
+            'biz-ui'?: string;
+            templates?: string;
+        };
+    }>;
+}
+declare function listTokenVariants(packageName?: string, packageRoot?: string): Promise<ListVariantsResult>;
 
 interface RunSkillsAddOptions {
     /** Absolute project root directory. */
@@ -161,6 +179,12 @@ interface RunUiAddOptions {
     overwrite?: boolean;
     /** Override the ui package name (defaults to "@teamix-evo/ui"). */
     packageName?: string;
+    /**
+     * When true, allow installing entries that live in `manifest.deprecatedEntries`
+     * (ADR 0028). Default: false — deprecated ids are treated as unknown and the
+     * call errors with a hint pointing the user at the active replacement.
+     */
+    includeDeprecated?: boolean;
 }
 interface RunUiAddResult {
     packageName: string;
@@ -170,8 +194,6 @@ interface RunUiAddResult {
     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. */
@@ -192,12 +214,19 @@ interface RunUiListOptions {
     installedOnly?: boolean;
     /** Override the ui package name (defaults to "@teamix-evo/ui"). */
     packageName?: string;
+    /**
+     * When true, also include archived entries from `manifest.deprecatedEntries`
+     * (ADR 0028). They are flagged with `deprecated: true` in the result.
+     */
+    includeDeprecated?: boolean;
 }
 interface UiEntryListItem {
     id: string;
     type: UiEntry['type'];
     description: string;
     installed: boolean;
+    /** True when the entry comes from `manifest.deprecatedEntries` (ADR 0028). */
+    deprecated: boolean;
 }
 interface RunUiListResult {
     packageName: string;
@@ -319,6 +348,8 @@ interface SkillSyncOptions {
         id: string;
         name: string;
         updateStrategy: SkillEntry['updateStrategy'];
+        /** Managed-region ids for region-aware mirror sync. */
+        managedRegions?: readonly string[];
     }>;
     ides: readonly SkillIde[];
     scope: SkillScope;
@@ -335,6 +366,8 @@ interface SkillSyncResult {
 declare function syncSkillsToIdes(options: SkillSyncOptions): Promise<SkillSyncResult>;
 /**
  * Remove all installed skill files. Returns the absolute paths removed.
+ * After files are unlinked, walks up the directory tree pruning empty dirs
+ * until a non-empty ancestor is reached (#33).
  */
 declare function removeSkillFiles(records: InstalledResource[]): Promise<string[]>;
 
@@ -345,6 +378,13 @@ interface UiInstallOptions {
     manifest: UiPackageManifest;
     /** Absolute ui package root (used to resolve entry source paths) */
     packageRoot: string;
+    /**
+     * Optional per-entry package root override. When set, entries in the map
+     * resolve their `file.source` against the mapped root instead of `packageRoot`.
+     * Used by variant-aware packages (biz-ui / templates) that pull in
+     * @teamix-evo/ui transitive deps — each entry resolves from its source package.
+     */
+    entryPackageRoot?: Map<string, string>;
     /** Aliases configured in `packages.ui.aliases` */
     aliases: UiAliases;
     /** Entry ids the user explicitly requested to add */
@@ -363,8 +403,6 @@ interface UiInstallResult {
     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).
@@ -379,7 +417,7 @@ 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 packageName - e.g. "@teamix-evo/tokens"
  * @param variant - e.g. "opentrek"
  * @returns manifest and data for template rendering
  */
@@ -422,7 +460,8 @@ declare function getTeamixDir(projectRoot: string): string;
 declare function ensureTeamixDir(projectRoot: string): Promise<string>;
 /**
  * Read the project config from .teamix-evo/config.json.
- * Returns null if the file does not exist.
+ * Returns null if the file does not exist; THROWS on corrupted content
+ * so callers don't silently clobber prior config (#32 #18).
  */
 declare function readProjectConfig(projectRoot: string): Promise<ProjectConfig | null>;
 /**
@@ -431,7 +470,10 @@ declare function readProjectConfig(projectRoot: string): Promise<ProjectConfig |
 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.
+ * Returns null if the file does not exist; THROWS on corrupted content so
+ * callers don't silently lose prior installs by treating broken JSON as
+ * "fresh install" (#32 #18). Use `readInstalledManifestOrNull` for the
+ * old lenient behavior.
  */
 declare function readInstalledManifest(projectRoot: string): Promise<InstalledManifest | null>;
 /**
@@ -439,4 +481,4 @@ declare function readInstalledManifest(projectRoot: string): Promise<InstalledMa
  */
 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 };
+export { DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type ListVariantsResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunTokensInitOptions, type RunTokensInitResult, 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, listTokenVariants, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runSkillsAdd, runTokensInit, runUiAdd, runUiInit, runUiList, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };