@teamix-evo/skills 0.5.0 → 0.7.0

package/src/teamix-evo-upgrade/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: teamix-evo-upgrade
+description: |
+  Help the user adopt token renames in `.teamix-evo/.upgrade-hints/tokens-<ts>.json` AND component source upgrades in `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` after `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade`. Read each hint or staging manifest, scan the project for usages or compare current vs incoming source, propose codemod / file-replace diffs, apply only after explicit user approval, then archive processed inputs.
+  TRIGGER when: user references `.teamix-evo/.upgrade-hints/`、`.teamix-evo/.upgrade-staging/`、`tokens-*.json` hint files、`ui-*` or `biz-ui-*` staging directories、phrases like "处理 token 改名"、"应用 codemod"、"扫一下 legacy token"、"升级 token 引用"、"更新 token 名"、"组件升级"、"ui-staging"、"biz-ui staging"、"apply ui staging"、"apply biz-ui staging"、"应用组件升级"、"apply token rename codemod"、"adopt token rename hints"、"scan for legacy tokens"、"token rename upgrade"、"component source upgrade"、"review ui staging diff"; AI sees output of `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch --apply` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` mentioning `💡 token rename hint:` or `staging at .teamix-evo/.upgrade-staging/...` and the user wants to follow up; user opens any `.teamix-evo/.upgrade-hints/tokens-*.json` or any file under `.teamix-evo/.upgrade-staging/{ui,biz-ui}-*/`.
+  SKIP: any other lifecycle work — `init` / `update` orchestration / variant switch itself / install / uninstall / generating staging (defer to teamix-evo-manage); pure visual or design changes (defer to teamix-evo-design-<variant>); any code authoring unrelated to the rename / staging window (defer to teamix-evo-code-<variant>); refuse to auto-apply — never write source code without explicit per-file user confirmation.
+  Coordinates with: teamix-evo-manage (manage drives the upgrade flow that emits hints + staging; this skill consumes the resulting files).
+---
+
+# teamix-evo-upgrade
+
+This skill consumes two complementary upgrade artefacts the CLI produces during upgrades and the consumer must adopt by hand under the [ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) **frozen-on-add boundary** (after first-time install via `npm create teamix-evo` / `teamix-evo init` / `ui add`, the CLI never overwrites existing files under `src/components/{ui,business}/**`; upgrades go through staging instead of in-place rewrites):
+
+1. **Token rename hints** — `.teamix-evo/.upgrade-hints/tokens-<ts>.json` (variable-level rewrites under `src/**` + `tokens/tokens.overrides.css`).
+2. **Component source staging** — `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` (per-component file replacements under `src/components/{ui,business}/**`, see [ADR 0040](../../../../docs/adr/0040-component-source-layer-upgrade-flow.md)).
+
+Both flows share the same shape (discover → read → propose → hard-gate confirm → archive); they only differ in the artefact they consume. Token-rename details are in part A, component-source details are in part B.
+
+# Part A — Token rename adoption
+
+## What is a hint file
+
+When `teamix-evo tokens update` bumps a variant version that ships a `renames` log, or `teamix-evo switch --apply` lands on a new variant whose history contains renames, the CLI writes a single JSON file:
+
+```
+.teamix-evo/
+└── .upgrade-hints/
+    └── tokens-2026-06-12T03-15-00-000Z.json
+```
+
+Schema v1 payload (every field is required except `description` per rename):
+
+```json
+{
+  "schemaVersion": 1,
+  "ts": "2026-06-12T03:15:00.000Z",
+  "package": "tokens",
+  "trigger": "update",
+  "fromVariant": "opentrek",
+  "toVariant": "opentrek",
+  "fromVersion": "0.5.0",
+  "toVersion": "0.6.5",
+  "renames": [
+    {
+      "sinceVersion": "0.6.0",
+      "from": "--color-old",
+      "to": "--color-new"
+    },
+    {
+      "sinceVersion": "0.6.5",
+      "from": "--space-x",
+      "to": "--space-h",
+      "description": "horizontal axis rename"
+    }
+  ]
+}
+```
+
+> `trigger` is `"update"` for version-bump hints and `"switch"` for variant-switch hints. Both consume the same way — only the framing line differs.
+
+## Workflow (5 steps, never skip step 4)
+
+### 1 · Discover
+
+List every hint file under `.teamix-evo/.upgrade-hints/`. Sort newest-first by filename (the `tokens-<fs-ts>.json` ts is filesystem-safe and lexically chronological).
+
+```bash
+ls -1 .teamix-evo/.upgrade-hints/tokens-*.json 2>/dev/null
+```
+
+If the directory is missing or empty, tell the user:
+
+> 当前没有待处理的 token rename hint。这通常意味着最近一次 `tokens update` / `switch` 没有跨过 rename 节点；你可以继续做你原本的事。
+
+### 2 · Aggregate
+
+Read each hint and aggregate the `renames` arrays into a single `from → to` map. When two hints rename the same token (rare — usually means a token was renamed twice across versions), the **newest hint wins** and the older mapping is discarded (treat the chain as resolved).
+
+Surface a one-line summary per hint to the user:
+
+> `tokens-…06-12T03-15-00-000Z.json` · update · opentrek 0.5.0 → 0.6.5 · 2 renames
+
+### 3 · Scan
+
+For each `from` token, run a project-wide search across the consumer-owned surface (never read `node_modules/` or `dist/`). The exact glob set depends on which token shape the rename targets:
+
+| `from` shape                                  | Where to search                                                            | Tooling          |
+| --------------------------------------------- | -------------------------------------------------------------------------- | ---------------- |
+| CSS variable (`--color-old`)                  | `src/**/*.{ts,tsx,js,jsx,css,scss,md,mdx}` + `tokens/tokens.overrides.css` | grep / Grep tool |
+| Tailwind class fragment (e.g. `bg-color-old`) | `src/**/*.{ts,tsx,jsx}` + `index.html`                                     | grep             |
+| Token JSON path (`color.old`)                 | `tokens/**/*.json` if any                                                  | grep             |
+
+Explicitly exclude:
+
+- `node_modules/**`、`dist/**`、`build/**`、`.next/**`
+- Anything under `.teamix-evo/snapshots/**` (those are restore points, not live code)
+- The hint file itself
+
+For each occurrence collect: file path, 1-based line number, the matched line.
+
+### 4 · Propose & ask (HARD GATE)
+
+For every `from → to` rename, show a diff hunk and **ask the user per file** before touching it. Use this template:
+
+```
+─── tokens/tokens.overrides.css (1 occurrence) ───
+- 12 |   color: var(--color-old);
++ 12 |   color: var(--color-new);
+
+─── src/components/Banner.tsx (3 occurrences) ───
+- 18 |   className="text-[var(--color-old)]"
++ 18 |   className="text-[var(--color-new)]"
+…
+
+应用这些修改？(y / n / per-file)
+```
+
+`per-file` lets the user pick file-by-file. Default to **no** if the user is silent. **Never auto-apply.** This is the entire reason the rename pipeline exists — ADR 0019 frozen boundary.
+
+If the user declines a particular file, record it in your reply (`保留：src/legacy/old-page.tsx — 用户选择不替换`) so they can come back to it later.
+
+### 5 · Archive processed hints
+
+After (and only after) the user has either accepted or explicitly skipped every rename in a hint file, **move the hint into the archive subdirectory** so subsequent runs don't re-prompt:
+
+```bash
+mkdir -p .teamix-evo/.upgrade-hints/.processed
+mv .teamix-evo/.upgrade-hints/tokens-<ts>.json .teamix-evo/.upgrade-hints/.processed/
+```
+
+Tell the user the file moved and that they can `git diff` to review the rewrites + the hint move in one shot.
+
+> If the user wants to **defer** an entire hint (not just per-file skip), leave it in place and tell them they can re-run this skill later.
+
+## Edge cases
+
+| Situation                                                       | Response                                                                                                                  |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Hint file fails JSON parse / wrong schemaVersion                | Print the file path + the parse error; **do not** delete it. Suggest the user inspect or run `teamix-evo restore --list`. |
+| `from` token literally not found in `src/**`                    | Tell the user the rename is "已经无影响" and ask whether to archive the hint anyway.                                      |
+| Multiple hint files pending                                     | Process newest-first one hint at a time — never batch across hints (keeps the diff small and the user in control).        |
+| User says "全部接受" / "apply all"                              | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**.                                     |
+| Project has no `src/` (library / monorepo root)                 | Ask the user which directory to scan; default to `packages/*/src` if a `pnpm-workspace.yaml` is present.                  |
+| User asks to handle an old hint that's already in `.processed/` | Read it from `.processed/`, re-run scan, and let the user decide whether to apply again or remove it permanently.         |
+
+## What this skill is NOT
+
+- **Not** a CLI command — there is no `teamix-evo upgrade`. The CLI emits hints + staging; this skill consumes them.
+- **Not** a token authority — only consumes the rename log declared by the upstream tokens pack (registry `TokensVariantEntry.renames`).
+- **Not** a refactor robot — diff-then-confirm is mandatory, the user owns every byte under `src/**`.
+- **Not** the place to discuss new token names or design decisions — those flow through the design skill.
+
+# Part B — Component source upgrade
+
+When `teamix-evo update` (auto-staging step), `teamix-evo ui upgrade [id]`, or `teamix-evo biz-ui upgrade [id]` runs, the CLI compares the consumer's installed component source against the latest upstream package contents and writes a **staging directory**:
+
+```
+.teamix-evo/.upgrade-staging/
+└── ui-2026-06-12T12-00-00-000Z/
+    ├── meta.json                       # UpgradeStagingManifest
+    ├── button/
+    │   ├── current.tsx                  # what is on disk now
+    │   └── incoming.tsx                 # alias-rewritten upstream source
+    └── …
+```
+
+> **v1 note** — CLI does **not** pre-render `diff.unified.patch`. The schema's `diffRelPath` field is reserved for a future v2 emitter; today this skill diffs `current.tsx` against `incoming.tsx` on the fly (B4).
+
+The CLI **never writes** into `src/components/{ui,business}/**` — frozen boundary, [ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) + [ADR 0040](../../../../docs/adr/0040-component-source-layer-upgrade-flow.md). This skill is the only path to land staged changes.
+
+## Staging manifest payload (schema v1)
+
+```json
+{
+  "schemaVersion": 1,
+  "ts": "2026-06-12T12:00:00.000Z",
+  "package": "ui",
+  "trigger": "ui-upgrade",
+  "fromVersion": "0.7.0",
+  "toVersion": "0.8.0",
+  "lineage": "teamix-evo",
+  "summary": {
+    "total": 4,
+    "byRisk": { "unchanged": 1, "upgradable-medium": 2, "risky": 1 }
+  },
+  "entries": [
+    {
+      "id": "button",
+      "category": "ui",
+      "current": {
+        "target": "src/components/ui/button.tsx",
+        "hash": "sha256:…",
+        "sourceLineage": "teamix-evo"
+      },
+      "incoming": {
+        "sourceVersion": "0.8.0",
+        "hash": "sha256:…",
+        "relPath": "button/incoming.tsx"
+      },
+      "diff": {
+        "riskLevel": "upgradable-medium",
+        "hints": ["new export: ButtonGroup"],
+        "filesChangedCount": 1
+      }
+    }
+  ]
+}
+```
+
+`riskLevel` values (from [ADR 0040 §D3](../../../../docs/adr/0040-component-source-layer-upgrade-flow.md)):
+
+| level               | meaning                                                              | suggested handling                  |
+| ------------------- | -------------------------------------------------------------------- | ----------------------------------- |
+| `unchanged`         | hash identical — nothing to do                                       | skip silently                       |
+| `upgradable-low`    | single file, no new/removed exports or cva variants                  | batch confirm                       |
+| `upgradable-medium` | new exports / new cva variants / multi-file                          | per-file confirm                    |
+| `risky`             | removed exports / removed cva variants / props rename                | discuss each, surface hints         |
+| `breaking`          | upstream removed the entry entirely                                  | flag explicitly, never auto-replace |
+| `foreign`           | file exists in `src/` but no upstream / no installed manifest record | leave untouched, ask for intent     |
+
+## Workflow (5 steps, never skip step 4)
+
+### B1 · Discover
+
+```bash
+ls -1d .teamix-evo/.upgrade-staging/{ui,biz-ui}-*/ 2>/dev/null | sort -r
+```
+
+If the directory is missing or empty:
+
+> 当前没有待应用的组件升级 staging。请先跑 `teamix-evo update` / `teamix-evo ui upgrade [id]` / `teamix-evo biz-ui upgrade [id]` 生成。
+
+### B2 · Read manifest & frame the opening line
+
+Parse `meta.json`. Pick the opening message based on `lineage`:
+
+| lineage         | opening line template                                                                                                                                                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `teamix-evo`    | `检测到 X 个组件，其中 Y 个有变化（unchanged=A, upgradable-low=B, medium=C, risky=D, breaking=E）。准备逐个 review。`                                                                                                             |
+| `mixed`         | `检测到 Z 个 teamix-evo 组件 + W 个未登记组件（foreign=F）。先处理可升级项，最后与你商量 foreign 组件去留。`                                                                                                                      |
+| `shadcn-native` | `你当前是 shadcn 原生安装（未使用 teamix-evo 的资产）。升级前建议先迁移到 teamix-evo 谱系（run 「teamix-evo ui init」重新安装），或者手动对齐调谐表。是否继续详细对比？` (CLI 这种情况不会生成 staging，但用户可能手工走到这一步) |
+| `custom-only`   | (CLI skip 了，不会出现在 staging 中 — 若出现是异常，请提示用户检查)                                                                                                                                                               |
+
+### B3 · Group by risk
+
+Iterate `entries` and bucket by `riskLevel`:
+
+- **`unchanged`** — just announce “以下组件未变，跳过” (list ids on one line).
+- **`upgradable-low`** — group all together, **one** confirmation prompt (“这些升级较安全，是否一起应用？”).
+- **`upgradable-medium`** — walk one-by-one with a short hint summary, ask y/n/per-file (see B4).
+- **`risky`** — force per-component review; spell out every `hints[]` entry verbatim before showing the diff.
+- **`breaking`** — do **not** offer auto-replace. Tell the user upstream removed the entry, ask if they want to delete the local file or keep it as a custom component (likely a re-naming — cross-check `removedExports`).
+- **`foreign`** — list separately (“以下组件不在 manifest 中，可能是你手工添加的”), ask whether to register, delete, or leave alone.
+
+### B4 · Propose & ask (HARD GATE)
+
+For each non-unchanged entry the user has agreed to consider, render the diff with **the same template as Part A step 4** but use file replacement instead of inline rewrite. Read `current.tsx` + `incoming.tsx` and compute the diff on the fly (v1 does not pre-render `diff.unified.patch` — if the entry's `diff.diffRelPath` is set in a future schema version, prefer that file as the source of truth).
+
+```
+─── src/components/ui/button.tsx · risk=upgradable-medium · hints: new export: ButtonGroup ───
+@@ -1,3 +1,5 @@
+ export const Button = (props: any) => null;
++
++export const ButtonGroup = (props: any) => null;
+
+应用？(y / n / per-file)
+```
+
+Application = **copy `incoming.tsx` over the file at `current.target`**, atomically. Do not partial-merge — the staging is whole-file.
+
+**Never auto-apply.** If the user is silent, default to no. If the user says “全部接受” / “apply all”, still show every diff (one screen each) before writing.
+
+If a file's `riskLevel` is `breaking` and the user opts to delete the file, do that explicitly with a confirmed `rm` command — not silently.
+
+### B5 · Archive staging
+
+After every entry has either been applied or explicitly skipped:
+
+```bash
+mkdir -p .teamix-evo/.upgrade-staging/.processed
+mv .teamix-evo/.upgrade-staging/<dir> .teamix-evo/.upgrade-staging/.processed/
+```
+
+Tell the user the directory was archived and that `git diff` will show every accepted file replacement plus the staging move in one shot.
+
+If the user wants to **defer** the entire staging (not per-entry skip), leave it in place — they can re-run this skill later.
+
+## Edge cases (component source)
+
+| Situation                                                              | Response                                                                                                                                                           |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `meta.json` parse error / wrong schemaVersion                          | Print the path + parse error; **do not** delete it. Suggest `teamix-evo ui upgrade` re-run or `teamix-evo restore --list`.                                         |
+| `current.tsx` differs from `entry.current.target` on disk              | The user edited locally since CLI generated staging. Show both diffs (your edits vs incoming), let them merge by hand; do not silently overwrite.                  |
+| User passes `--apply` to a CLI upgrade command                         | The CLI itself rejects with frozen-boundary guidance. Re-route them here.                                                                                          |
+| Multiple staging directories pending                                   | Process newest-first one staging at a time — never batch across staging dirs (different `fromVersion/toVersion`, different baseline).                              |
+| User says “全部接受” / “apply all”                                     | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**.                                                                              |
+| `lineage=mixed` with `foreign` entries                                 | After upgradable-\* are processed, walk foreign entries one-by-one and ask: register (out of scope here — redirect to `teamix-evo ui add <id>`), delete, or leave. |
+| User asks to handle an old staging dir that's already in `.processed/` | Read the manifest from `.processed/`, re-render diffs, decide whether to re-apply or remove permanently.                                                           |

package/src/teamix-evo-design-opentrek/patterns/sidebar.md

@@ -1,122 +0,0 @@
-# Sidebar Pattern — OpenTrek 侧边栏统一规范
-
-> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 3 确认布局包含侧边栏，或由翻新/验证路径引导到这里。
-
-> AI 生成或翻新页面时必须引用本规则。所有色值与尺寸通过 token 引用，禁止硬编码。Token 真值见 `tokens/tokens.theme.css`。
-
----
-
-## 1. 宽度与定位
-
-| 状态   | Token                       | 业务含义                        |
-| ------ | --------------------------- | ------------------------------- |
-| 展开态 | `--layout-sidebar-width`    | 侧边栏展开宽度                  |
-| 收起态 | `--sidebar-collapsed-width` | 仅图标，居中对齐于中轴线        |
-| 顶部条 | `--topbar-height`           | 与 Sidebar 顶部对齐，区分品牌区 |
-
-**布局规则**：
-
-- Sidebar 走 `position: fixed; top: 0; left: 0; bottom: 0; z-index: 100`
-- 主内容区通过 `margin-left: var(--layout-sidebar-width)` 补偿
-- **禁止**：把 Sidebar + 主内容区放进一个 flex 容器（不可预期的滚动行为）
-
----
-
-## 2. 结构变体（2 选 1，按信息架构层级）
-
-### 2.1 三级结构（默认）
-
-适用：信息架构需要 3 层归类（顶层业务域 / 中层主导航 / 底层细分）。
-
-```
-aside.sidebar
-├─ div.sidebar-header        ← 品牌区
-├─ div.sidebar-content       ← 滚动容器
-│  ├─ div.sidebar-group-label  ← 分组标题（可重复）
-│  ├─ ul.sidebar-menu
-│  │  └─ li > a.sidebar-menu-item
-│  └─ ul.sidebar-sub-menu      ← 主菜单展开后显示
-│     └─ li > a.sidebar-menu-item
-├─ div.sidebar-divider
-└─ div.sidebar-footer
-```
-
-### 2.2 二级结构（v4.1 新增）
-
-适用：主菜单项语义对等，无需分组标题归类。
-
-- **禁止** `div.sidebar-group-label`
-- 所有主菜单项放进同一个 `ul.sidebar-menu`
-- 子菜单项与主菜单项**文字 x 坐标对齐**（同列），层级关系由展开箭头 + 字号 + 背景色表现，**不**通过左缩进
-- 子菜单项不带 `.item-icon`，只有文字
-
-### 2.3 选型决策
-
-| 信息架构层级深度 | 选用       |
-| ---------------- | ---------- |
-| 3 层归类         | threeLevel |
-| 2 层归类         | twoLevel   |
-
-> 与菜单项**个数无关**，只看信息架构。
-
----
-
-## 3. 颜色映射（v4.1 品牌化）
-
-| 槽位                                | 用途                                        |
-| ----------------------------------- | ------------------------------------------- |
-| `--color-sidebar`                   | 侧边栏背景                                  |
-| `--color-sidebar-foreground`        | 默认文字                                    |
-| `--color-sidebar-active`            | 选中项背景（v4.1 走灰色，区别 hover）       |
-| `--color-sidebar-active-foreground` | 选中项文字（OpenTrek 蓝）                   |
-| `--color-sidebar-hover`             | hover 态背景                                |
-| `--color-sidebar-title`             | sidebar-group-label 文字                    |
-| `--color-sidebar-item-muted`        | 二级文字 / 次要项                           |
-| `--color-sidebar-primary`           | 品牌强调（`#0055EE`）— 高亮 logo / 选中态等 |
-| `--color-sidebar-border`            | 分隔线                                      |
-| `--color-sidebar-ring`              | 焦点圈                                      |
-
-**禁止**：
-
-- 直接用 `bg-blue-600` / `text-gray-500` 这类原始 Tailwind 色
-- 在 sidebar 内消费 `--color-primary` / `--color-foreground`（应走 sidebar 命名空间）
-
----
-
-## 4. 收起态行为
-
-- 宽度 `--sidebar-collapsed-width`，`overflow: visible`（支持 flyout 浮层溢出）
-- 滚动能力下移到 `.sidebar-content`（`overflow-y: auto; overflow-x: hidden`）
-- 仅显示图标，隐藏所有文字（label / group title / count / expand-icon）
-- 选中态用 `--color-sidebar-active` 灰色背景，**不**显示左侧高亮条
-- 过渡走 `width var(--duration-normal) var(--easing-ease)`
-- 菜单项 40×40px，`border-radius: var(--radius-md)`，`li { display: flex; justify-content: center }` 保证居中于中轴线
-
----
-
-## 5. Footer / Header 槽位
-
-| 槽位             | 内容                                                  |
-| ---------------- | ----------------------------------------------------- |
-| sidebar-header   | 展开态：品牌 logo；收起态：方形 logo +hover 展开 icon |
-| sidebar-avatar   | 用户头像                                              |
-| sidebar-username | 用户名（收起态隐藏）                                  |
-| sidebar-more     | 更多操作触发器                                        |
-
----
-
-## 6. 禁止清单（硬约束）
-
-- [ERROR] 扁平化结构（直接 `<a>` 挂在 `nav`/`div` 下，无 `ul > li` 包裹）
-- [ERROR] Sidebar 整体使用 flex 布局（必须 `fixed` 定位）
-- [ERROR] 省略 `sidebar-content` 滚动容器
-- [ERROR] twoLevel 变体出现 `sidebar-group-label`
-- [ERROR] 无子菜单的菜单项出现 expand-icon 或 `data-toggle`（expand-icon 仅出现在有 `sidebar-sub-menu` 的主菜单项）
-- [WARN] 在 sidebar 里直接消费 `--color-primary`（应走 `--color-sidebar-primary`）
-- [WARN] 二级结构子菜单文字起点低于主菜单文字 x（隐藏层级关系）
-
----
-
-## 7. 引用关系
-
-本规则是 OpenTrek sidebar 的 **single source of truth**。其他 skill 文件（page-frame / common-components / 子技能）须 `$ref` 本文件，禁止重复定义或冲突覆写。