teamix-evo 0.8.0 → 0.9.0

package/README.md

@@ -178,6 +178,7 @@ TEAMIX_DEBUG=1 teamix-evo tokens init opentrek
 | `teamix-evo tokens list`                            | 查看已装机的 variant                                                            |
 | `teamix-evo tokens update`                          | 更新已装资源(stub,v0.7 见 ADR 0019)                                             |
 | `teamix-evo tokens uninstall`                       | 卸载已装 tokens                                                                 |
+| `teamix-evo tokens audit`                           | 审计 tokens 引用（4 类：redundant / kept / migrate / custom，v3↔v4 语义比较）   |
 | `teamix-evo skills init`                            | 自举 skills(按 variant + scope 全装 — ADR 0034)                                 |
 | `teamix-evo skills add <name...>`                   | 增量装指定 skill(`<name...>` 必填)                                              |
 | `teamix-evo skills list`                            | 列出所有 skill 的安装状态                                                       |
@@ -188,6 +189,7 @@ TEAMIX_DEBUG=1 teamix-evo tokens init opentrek
 | `teamix-evo ui init`                                | 初始化 ui 配置(aliases / iconLibrary / tsx / rsc)                               |
 | `teamix-evo ui add <id...>`                         | 安装指定 ui 组件源码                                                            |
 | `teamix-evo ui list [--installed]`                  | 列出可用/已安装 ui 组件                                                         |
+| `teamix-evo ui promote-to-biz <id...>`              | 把 ui 组件提升为业务组件（8 模式：Coexist/Preset/Wrapper/Compose/Variant/Fork/TokenOnly/ManualReview） |
 | `teamix-evo biz-ui list-variants`                   | 列出 biz-ui 包内提供的业务变体                                                  |
 | `teamix-evo biz-ui add <id...> --variant <name>`    | 安装变体感知业务组件(`--variant` 必填)                                          |
 | `teamix-evo templates list-variants`                | 列出 templates 包内提供的页面模板变体                                           |

package/dist/core/index.d.ts

@@ -103,6 +103,13 @@ type RunSkillsInitResult = {
     resources: InstalledResource[];
     addedSkillIds: string[];
     skippedSkillIds: string[];
+    /**
+     * Always `[]` for `runSkillsInit` — bulk bootstrap deliberately does not
+     * surface upgrade hints (only `runSkillsAdd` does, ADR 0034). Kept on
+     * the type so the result shape stays consistent with `RunSkillsAddResult`
+     * and `finalizeSkillsInstall`'s return.
+     */
+    outdatedSkills: OutdatedSkillInfo[];
 } | {
     /** Returned when a skills package is already installed and bulk has nothing new to add. */
     status: 'already-initialized';
@@ -133,6 +140,18 @@ interface RunSkillsAddOptions {
     /** Override the skills package name (defaults to "@teamix-evo/skills"). */
     packageName?: string;
 }
+/**
+ * Detail for an already-installed skill whose locked version is older than
+ * the manifest's latest version. Use `skills update <id>` to upgrade.
+ */
+interface OutdatedSkillInfo {
+    /** Skill id */
+    id: string;
+    /** Version recorded in `.teamix-evo/skills.lock.json` */
+    installed: string;
+    /** Version available in the upstream manifest (i.e. `npx` resolved `@latest`) */
+    latest: string;
+}
 type RunSkillsAddResult = {
     status: 'installed';
     packageName: string;
@@ -147,8 +166,18 @@ type RunSkillsAddResult = {
     resources: InstalledResource[];
     /** Skill ids that were freshly added in this call. */
     addedSkillIds: string[];
-    /** Skill ids that were requested but already installed; skipped. */
+    /**
+     * Skill ids that were requested but already installed at the latest version;
+     * nothing to do. Outdated installs are reported separately via
+     * {@link outdatedSkills}.
+     */
     skippedSkillIds: string[];
+    /**
+     * Skill ids that were requested, are already installed, but whose locked
+     * version is older than the manifest version. Caller should surface a hint
+     * recommending `skills update <id>`.
+     */
+    outdatedSkills: OutdatedSkillInfo[];
 };
 /**
  * Programmatic equivalent of `teamix-evo skills add <names...>` (ADR 0034).
@@ -390,6 +419,15 @@ interface ListVariantUiEntriesResult {
 declare function listBizUiEntries(variant: string, packageRoot?: string): Promise<ListVariantUiEntriesResult>;
 declare function listTemplatesEntries(variant: string, packageRoot?: string): Promise<ListVariantUiEntriesResult>;
 
+/**
+ * Phase 3.E lint conflict strategies (mirrors `init-conflicts.ts`).
+ *
+ * `merge` and `backup-overwrite` both back up the existing user file before
+ * writing the teamix-evo template; `merge` additionally surfaces an AI-assist
+ * hint so the manage / code skill can guide the user through merging custom
+ * rules. `skip` keeps the user's file as-is and emits no template.
+ */
+type LintConflictStrategy = 'merge' | 'backup-overwrite' | 'skip' | 'overwrite';
 interface RunLintInitOptions {
     /** Absolute project root directory. */
     projectRoot: string;
@@ -399,11 +437,43 @@ interface RunLintInitOptions {
      * installed in a later batch step.
      */
     skipInstall?: boolean;
+    /**
+     * Phase 3.E: strategy for handling existing ESLint config files.
+     * Defaults to `'overwrite'` (legacy behaviour); the `init` orchestrator
+     * passes the wizard-resolved value when consumer files are detected.
+     */
+    eslintStrategy?: LintConflictStrategy;
+    /**
+     * Phase 3.E: strategy for handling existing Stylelint config files.
+     */
+    stylelintStrategy?: LintConflictStrategy;
+    /**
+     * Phase 3.E: paths of existing ESLint configs (relative to projectRoot)
+     * to back up. Empty when no consumer config was detected.
+     */
+    eslintExistingPaths?: string[];
+    /**
+     * Phase 3.E: paths of existing Stylelint configs (relative to projectRoot).
+     */
+    stylelintExistingPaths?: string[];
 }
 type RunLintInitResult = {
     status: 'installed';
     eslint: boolean;
     stylelint: boolean;
+    /** True when the user had a custom config and asked for AI-assisted merge. */
+    eslintMergeRequested?: boolean;
+    stylelintMergeRequested?: boolean;
+    /** True when the strategy asked us to keep the user file untouched. */
+    eslintSkipped?: boolean;
+    stylelintSkipped?: boolean;
+    /**
+     * True when `package.json` was actually patched (lint / lint:css
+     * scripts inserted). Powers the project-init change ledger so the
+     * CLI does not report a phantom write when both scripts already
+     * existed.
+     */
+    packageJsonPatched?: boolean;
 } | {
     status: 'already-initialized';
 };
@@ -445,14 +515,45 @@ interface RunGenerateAgentsMdOptions {
      * (e.g. `teamix-evo-manage`).
      */
     skillIds: string[];
+    /**
+     * Reconciliation mode (Phase 2.B):
+     *   - `'overwrite'` (default): always rewrite the full file. Pre-existing
+     *     content is backed up and discarded.
+     *   - `'merge-managed'`: rewrite only the `teamix-evo-skills` managed
+     *     region. When the consumer file lacks the region, prepend a fresh
+     *     managed block ahead of the user's content (auto-adopt). The user's
+     *     non-managed sections are preserved.
+     *
+     * In both modes, an existing file is backed up under
+     * `.teamix-evo/.backups/AGENTS.md.<isoTs>.bak` before any mutation.
+     */
+    mode?: 'overwrite' | 'merge-managed';
 }
 interface RunGenerateAgentsMdResult {
     /** Absolute path of the written `AGENTS.md`. */
     path: string;
-    /** Number of skill sections rendered (excludes missing SKILL.md degradations are still counted). */
+    /** Number of skill sections rendered (missing SKILL.md degradations are still counted). */
     skillCount: number;
     /** Skill ids whose SKILL.md could not be read (rendered as degraded section). */
     missingSkillIds: string[];
+    /**
+     * True when an existing AGENTS.md was backed up under
+     * `.teamix-evo/.backups/AGENTS.md.<isoTs>.bak` before being overwritten
+     * (Phase 1.A2 — full backup strategy).
+     */
+    backedUp: boolean;
+    /**
+     * Outcome of the merge step (Phase 2.B):
+     *   - `'created'`: no AGENTS.md existed; wrote a fresh full template.
+     *   - `'overwritten'`: existed but mode='overwrite' — full rewrite.
+     *   - `'managed-replaced'`: mode='merge-managed' and the consumer file
+     *     already had the `teamix-evo-skills` managed region; only that region
+     *     was rewritten. User content outside is preserved.
+     *   - `'managed-prepended'`: mode='merge-managed' but the consumer file
+     *     did not yet have the managed region; a fresh block was inserted at
+     *     the top, with the existing user content kept below.
+     */
+    merge: 'created' | 'overwritten' | 'managed-replaced' | 'managed-prepended';
 }
 interface SkillDescriptionParts {
     /** First non-empty line(s) of `description` (the capability statement). */
@@ -462,8 +563,16 @@ interface SkillDescriptionParts {
     coordinates: string | null;
 }
 /**
- * Generate and write the `AGENTS.md` file. Idempotent — repeated invocations
- * fully overwrite the file (regenerable per ADR 0038 §4).
+ * Generate and write the `AGENTS.md` file.
+ *
+ * Phase 2.B — reconciliation modes:
+ *   - `'overwrite'` (default): regenerable behaviour, full rewrite.
+ *   - `'merge-managed'`: rewrite only the `teamix-evo-skills` managed region
+ *     so user-authored sections (project-specific guidance, design tokens,
+ *     prompts) are never clobbered.
+ *
+ * Existing files are always backed up under `.teamix-evo/.backups/` before
+ * mutation (ADR 0019 §2, Phase 1.A2).
  */
 declare function runGenerateAgentsMd(options: RunGenerateAgentsMdOptions): Promise<RunGenerateAgentsMdResult>;
 /**
@@ -512,15 +621,15 @@ interface ProjectStateReport {
 declare function detectProjectState(cwd: string): Promise<ProjectStateReport>;
 
 /**
- * The 6 categories of consumer-side files that `teamix-evo init` may
+ * The 8 categories of consumer-side files that `teamix-evo init` may
  * conflict with when running against a non-teamix-evo project.
  *
  * See ADR 0019 D1 task #5 — these are the only files we mutate at
  * `init` time, so they're the only ones we ask the user about.
  */
-type ConflictKey = 'agents-md' | 'components-json' | 'tailwind-config' | 'tokens' | 'index-css' | 'shadcn-source';
+type ConflictKey = 'agents-md' | 'components-json' | 'tailwind-config' | 'tokens' | 'index-css' | 'shadcn-source' | 'eslint-config' | 'stylelint-config';
 /** Strategy options per conflict category. */
-type ConflictStrategy = 'overwrite' | 'merge-managed' | 'skip' | 'diff-prompt' | 'backup-overwrite' | 'migrate' | 'coexist' | 'append' | 'skip-existing' | 'per-file-prompt';
+type ConflictStrategy = 'overwrite' | 'merge-managed' | 'skip' | 'diff-prompt' | 'backup-overwrite' | 'migrate' | 'coexist' | 'append' | 'skip-existing' | 'per-file-prompt' | 'merge';
 interface ConflictItem {
     /** Stable id for the category. */
     key: ConflictKey;
@@ -542,13 +651,13 @@ interface ConflictItem {
 }
 interface ConflictReport {
     cwd: string;
-    /** Always 6 items, ordered by ConflictKey enumeration above. */
+    /** Always 8 items, ordered by ConflictKey enumeration above. */
     items: ConflictItem[];
     /** True if any item has `exists === true`. */
     hasAnyConflict: boolean;
 }
 /**
- * Inspect `cwd` for the 6 categories of files that `teamix-evo init` may
+ * Inspect `cwd` for the 8 categories of files that `teamix-evo init` may
  * touch. Pure read-only — never mutates the filesystem. Returns one
  * `ConflictItem` per category in stable order so callers can render a
  * deterministic wizard.
@@ -585,6 +694,17 @@ interface SnapshotResult {
     path: string;
 }
 
+type FileChangeKind = 'created' | 'modified' | 'backed-up' | 'deleted';
+interface FileChange {
+    kind: FileChangeKind;
+    /** Project-root-relative path, posix style (forward slashes). */
+    path: string;
+    /** Originating pipeline step (free-form to avoid coupling on `ProjectInitStepName`). */
+    step: string;
+    /** Optional human-readable note (e.g. `frozen` / `regenerable` / `managed`). */
+    detail?: string;
+}
+
 /**
  * Programmatic orchestrator for `teamix-evo init` (existing-project adoption).
  *
@@ -615,6 +735,13 @@ interface ProjectInitStep {
     name: ProjectInitStepName;
     status: ProjectInitStepStatus;
     detail?: string;
+    /**
+     * Files this step touched (Phase 1.A1). Empty when the step skipped or
+     * failed before any I/O. The `kind` is `created` by default; the orchestrator
+     * upgrades entries to `modified` post-hoc by checking the backup ledger
+     * (`.teamix-evo/.backups/`).
+     */
+    changes?: FileChange[];
 }
 interface PendingConflictWork {
     key: ConflictKey;
@@ -668,6 +795,18 @@ interface RunProjectInitOptions {
      * responsible for filtering out paths already inside `tokens/`.
      */
     legacyTokensPaths?: string[];
+    /**
+     * Phase 3.E: existing ESLint config paths (relative to `projectRoot`)
+     * detected by `detectConflicts` for the `eslint-config` key. Used to
+     * back up the consumer's file before writing the teamix-evo template,
+     * and to gate the `merge` / `backup-overwrite` / `skip` strategies in
+     * `runLintInit`.
+     */
+    legacyEslintPaths?: string[];
+    /**
+     * Phase 3.E: existing Stylelint config paths (relative to `projectRoot`).
+     */
+    legacyStylelintPaths?: string[];
     /** Step-level progress hook (caller controls presentation). */
     onStep?: (step: ProjectInitStep) => void;
     /**
@@ -681,6 +820,12 @@ interface RunProjectInitResult {
     steps: ProjectInitStep[];
     /** Conflicts whose strategy needs the post-batch-4 managed-region engine. */
     pendingConflictWork: PendingConflictWork[];
+    /**
+     * Aggregated, classified file-change ledger covering every step
+     * (Phase 1.A1). Backup entries are surfaced as `kind: 'backed-up'` so the
+     * CLI can render a four-bucket summary (新建 / 修改 / 备份 / 删除).
+     */
+    changes: FileChange[];
     /**
      * Present when at least one step ended in `fail`. Lets the CLI surface a
      * structured recovery message instead of just a stack-trace, and gives
@@ -805,7 +950,7 @@ declare function installResources(options: InstallOptions): Promise<InstallResul
  *
  * Two-stage flow:
  *   1. **writeSkillSources** — render upstream `<packageRoot>/<skill.source>` and
- *      write to `<projectRoot>/.teamix-evo/skills/<id>/` (the consumer-side
+ *      write to `<projectRoot>/.teamix-evo/skills-source/<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>/`).