teamix-evo 0.10.1 → 0.12.0

package/README.md

@@ -197,8 +197,11 @@ TEAMIX_DEBUG=1 teamix-evo tokens init opentrek
 | `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 包内提供的页面模板变体                                                                                   |
-| `teamix-evo templates add <id...> --variant <name>`   | 安装变体感知页面模板(`--variant` 必填)                                                                                  |
+| `teamix-evo blocks add <id...>`                       | 安装营销页区块（保留目录结构）                                                                                          |
+| `teamix-evo blocks list [--installed] [--json]`       | 列出可用/已安装区块                                                                                                     |
+| `teamix-evo blocks upgrade [<id...>]`                 | 升级已安装的区块源码                                                                                                    |
+| `teamix-evo templates list-variants`                  | _(deprecated → blocks)_ 列出 templates 包内提供的页面模板变体                                                           |
+| `teamix-evo templates add <id...> --variant <name>`   | _(deprecated → blocks)_ 安装变体感知页面模板                                                                            |
 | `teamix-evo lint init [-y]`                           | 一键安装 ESLint + Stylelint token-discipline 规则集                                                                     |
 | `teamix-evo logs analyze [...]`                       | 分析 vibe-logger AI 调用链(`.log/ai/**/*.jsonl`)                                                                        |
 | `teamix-evo logs trace [...]`                         | 按会话还原 AI 调用链(prompt → PreToolUse → PostToolUse → Stop)                                                          |

package/dist/core/index.d.ts

@@ -104,10 +104,12 @@ type RunSkillsInitResult = {
     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.
+     * Skill ids that were auto-upgraded because their locked version was
+     * older than the manifest version.
+     */
+    autoUpdatedSkillIds: string[];
+    /**
+     * @deprecated Outdated skills are now auto-upgraded; kept for compat.
      */
     outdatedSkills: OutdatedSkillInfo[];
 } | {
@@ -168,14 +170,17 @@ type RunSkillsAddResult = {
     addedSkillIds: string[];
     /**
      * Skill ids that were requested but already installed at the latest version;
-     * nothing to do. Outdated installs are reported separately via
-     * {@link outdatedSkills}.
+     * nothing to do.
      */
     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>`.
+     * Skill ids that were auto-upgraded because their locked version was older
+     * than the manifest version.
+     */
+    autoUpdatedSkillIds: string[];
+    /**
+     * @deprecated Outdated skills are now auto-upgraded; this array is always
+     * empty. Kept for backward-compatible callers; will be removed in next major.
      */
     outdatedSkills: OutdatedSkillInfo[];
 };
@@ -670,63 +675,6 @@ interface ConflictReport {
  */
 declare function detectConflicts(cwd: string): Promise<ConflictReport>;
 
-/**
- * Final answers produced by the init wizard. Every consumer of `teamix-evo
- * init` (orchestrator + later sub-commands) reads from this object exclusively
- * — flags / prompts must not be re-evaluated downstream (silent sub-commands).
- */
-interface InitWizardAnswers {
-    variant: string;
-    ides: SkillIde[];
-    scope: SkillScope;
-    withLint: boolean;
-    withUi: boolean;
-    /** 'baseline' = preset 推荐组件子集；'all' = 全量装 */
-    uiSelection: 'baseline' | 'all';
-    withBizUi: boolean;
-    /**
-     * 每类冲突文件的最终策略。键是 6 类 ConflictKey，值是 user-chosen
-     * `ConflictStrategy`。当对应 ConflictItem.exists === false 时，值默认为
-     * `'overwrite'`（即首次写入）。
-     */
-    conflictDecisions: Record<ConflictKey, ConflictStrategy>;
-}
-
-interface UiConflictEntry {
-    /** UI entry id from manifest (e.g. "button") */
-    id: string;
-    /** Absolute path on disk that conflicts */
-    targetPath: string;
-    /** Project-relative posix path for display */
-    relativePath: string;
-    /**
-     * Heuristic guess: true when the existing file looks like an unmodified
-     * shadcn/ui original (no `data-slot` attribute from teamix-evo).
-     * v1 uses filename + content heuristics; future versions may hash-compare.
-     */
-    isShadcnOriginal: boolean;
-}
-interface UiConflictReport {
-    /** Entries whose target file already exists on disk */
-    conflictEntries: UiConflictEntry[];
-    /** Number of manifest entries with no on-disk conflict */
-    unconflictedTargets: number;
-    /** Total manifest entries checked */
-    totalEntries: number;
-    /** True when at least one conflict exists — caller should block */
-    shouldBlock: boolean;
-    /** Distinct target alias directories that have conflicts */
-    conflictDirs: string[];
-}
-
-/** Result of `createSnapshot` when a snapshot was actually taken. */
-interface SnapshotResult {
-    /** Filesystem-safe UTC timestamp identifier (e.g. `2026-06-11T20-59-03-000Z`). */
-    ts: string;
-    /** Absolute path to the snapshot directory. */
-    path: string;
-}
-
 type FileChangeKind = 'created' | 'modified' | 'backed-up' | 'deleted';
 interface FileChange {
     kind: FileChangeKind;
@@ -739,267 +687,62 @@ interface FileChange {
 }
 
 /**
- * Programmatic orchestrator for `teamix-evo init` (existing-project adoption).
- *
- * Consumes {@link InitWizardAnswers} produced by `runInitWizard` and drives
- * the existing core sub-commands (`runTokensInit`, `runSkillsAdd`,
- * `runGenerateAgentsMd`, `runUiInit`, `runUiAdd`, `runLintInit`) in a fixed
- * order. Sub-commands are invoked silently — no interactive prompts here.
+ * Programmatic orchestrator for `teamix-evo init` (ADR 0043).
  *
- * Conflict handling:
- * - `conflictDecisions[key] === 'skip'` skips the corresponding step entirely.
- * - `'overwrite'` is the trivial path (the underlying core APIs already write).
- * - `'merge-managed'` (agents-md) is implemented today via
- *   `runGenerateAgentsMd` which writes managed regions natively.
- * - `'skip-existing'` (shadcn-source) maps to `runUiAdd({ overwrite: false })`,
- *   the existing default.
- * - All other strategies (`diff-prompt`, `backup-overwrite`, `migrate`,
- *   `coexist`, `append`, `per-file-prompt`) require the managed-region engine
- *   from batch 4 — they are recorded to `pendingConflictWork` so the CLI
- *   surface can guide the user to the followup `teamix-evo conflict resolve`
- *   step (post-batch-4).
+ * Drives the 8-step pipeline that installs the full teamix-evo suite into an
+ * existing project. Each step is idempotent — re-running `init` picks up from
+ * where it left off.
  *
- * No interactive prompts, no `process.exit`. Throws on hard failure (P8).
+ * Conflict handling is intentionally thin (ADR 0043 §3): detect → terminate →
+ * structured output → AI decides. The orchestrator only checks `force` — when
+ * true, it skips conflict detection entirely.
  */
 
-/**
- * Strategy for handling UI component conflicts when existing shadcn/ui
- * components are found in the target project.
- *
- * - `isolate-progressive` (Path A): move existing → shadcn-ui/, install
- *    fresh teamix-evo components into ui/, rewrite imports, let user
- *    migrate at their own pace.
- * - `isolate-aggressive` (Path C): same as A + immediately generate
- *    upgrade staging so user can batch-replace.
- * - `frozen-skip`: legacy behaviour — skip existing files, no migration.
- */
-type UiConflictStrategy = 'isolate-progressive' | 'isolate-aggressive' | 'frozen-skip';
-type ProjectInitStepName = 'tokens' | 'skills' | 'agents-md' | 'ui-init' | 'ui-add' | 'lint' | 'gitignore';
+type ProjectInitStepName = 'tokens' | 'skills' | 'agents-md' | 'ui-init' | 'ui-add' | 'biz-ui-add' | 'lint' | 'gitignore';
 type ProjectInitStepStatus = 'ok' | 'skip' | 'fail' | 'planned';
 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/`).
-     */
+    /** Files this step touched. */
     changes?: FileChange[];
 }
-interface PendingConflictWork {
-    key: ConflictKey;
-    strategy: ConflictStrategy;
-    reason: string;
-}
 interface ResumeHint {
-    /** The first step that failed (caller resumes from here). */
     failedAt: ProjectInitStepName;
-    /** Steps already finished (status === 'ok'); will short-circuit on resume. */
     completed: ProjectInitStepName[];
-    /** All steps that ended in fail status. */
     failed: ProjectInitStepName[];
-    /** Human-readable error from the first failed step. */
     error: string;
-    /**
-     * Suggested CLI command to resume. Today this is just `teamix-evo init`
-     * itself — every sub-step is idempotent (returns `already-initialized`
-     * when the matching state file already exists), so a re-run continues
-     * from the failure point automatically. Future batches may grow a
-     * dedicated `--resume` flag with a richer recovery model (batch 3).
-     */
     resumeCommand: string;
 }
 interface RunProjectInitOptions {
     /** Absolute project root (existing repo to adopt teamix-evo into). */
     projectRoot: string;
-    /** Wizard outcome (single source of truth for every silent sub-command). */
-    answers: InitWizardAnswers;
-    /**
-     * Override the resolved UI entry list. When provided, replaces the
-     * `answers.uiSelection`-driven list (`'baseline'` / `'all'`). Useful for
-     * tests and for callers that want to install a custom subset.
-     */
-    uiEntries?: string[];
+    /** Tokens variant (e.g. "opentrek" / "uni-manager"). */
+    variant: string;
+    /** Target IDEs (at least one). */
+    ides: SkillIde[];
+    /** Skill install scope. Defaults to 'project'. */
+    scope?: SkillScope;
     /**
-     * If true, skip `npm install` for lint deps. Defaults to `false` so lint
-     * works out of the box; pass `true` from the create scaffold which installs
-     * everything in one batch.
+     * When true, skip conflict detection and overwrite everything.
+     * Distinction: init --force = skip conflict check; create --force = overwrite directory.
      */
+    force?: boolean;
+    /** Skip `npm install` for lint deps. */
     skipInstall?: boolean;
-    /**
-     * Legacy token CSS files (paths relative to `projectRoot`) detected by
-     * `detectConflicts` for the `tokens` key. When `conflictDecisions.tokens`
-     * is `'migrate'` and this list is non-empty, the orchestrator appends
-     * each file's content into `tokens/tokens.overrides.css` and backs the
-     * legacy files up to `.teamix-evo/.backups/` (W1.4 of the manage-entry
-     * plan; see [`legacy-tokens-migrate`](./legacy-tokens-migrate.ts)).
-     *
-     * Ignored for any other `tokens` decision. The caller (init command) is
-     * 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[];
-    /**
-     * UI conflict resolution strategy. When omitted AND conflicts are
-     * detected, the orchestrator returns `uiDecisionRequired` so the
-     * caller can prompt the user. When `-y` (non-interactive), defaults
-     * to `'isolate-progressive'`.
-     */
-    uiConflictStrategy?: UiConflictStrategy;
-    /**
-     * When true, treat the invocation as non-interactive (`-y` flag).
-     * Affects default conflict strategy selection.
-     */
-    nonInteractive?: boolean;
-    /** Step-level progress hook (caller controls presentation). */
+    /** Step-level progress hook. */
     onStep?: (step: ProjectInitStep) => void;
-    /**
-     * If true, plan-only mode: compute the full step list without running any
-     * sub-command. Returns each step with `status: 'planned'`.
-     */
+    /** Plan-only mode: compute steps without running sub-commands. */
     dryRun?: boolean;
 }
-/**
- * Returned when UI conflicts are detected and no `uiConflictStrategy` was
- * provided. The caller should present the options to the user and re-invoke
- * `runProjectInit` with the chosen strategy.
- */
-interface UiDecisionRequired {
-    /** The full conflict report for display */
-    report: UiConflictReport;
-    /** Available strategies with human-readable descriptions */
-    options: Array<{
-        strategy: UiConflictStrategy;
-        label: string;
-        description: string;
-    }>;
-}
 interface RunProjectInitResult {
     status: 'installed' | 'partial' | 'dry-run';
     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
-     * programmatic consumers a deterministic field to branch on.
-     */
     resumeHint?: ResumeHint;
-    /**
-     * Pre-init snapshot of `.teamix-evo/`, captured automatically before any
-     * file is written ([ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) §2).
-     *
-     * - `null` on first-ever init (`.teamix-evo/` did not yet exist) and on
-     *   `dryRun`.
-     * - Failure to capture a snapshot is **non-fatal** — surfaced via
-     *   {@link snapshotError} so the CLI can warn the user. The init pipeline
-     *   itself still runs.
-     */
-    snapshot?: SnapshotResult | null;
-    /** Reason a snapshot capture failed (best-effort — never blocks init). */
-    snapshotError?: string;
-    /**
-     * Present when UI conflicts are detected and no `uiConflictStrategy`
-     * was provided (interactive mode). Caller should prompt the user with
-     * `options`, then re-invoke with the chosen strategy.
-     */
-    uiDecisionRequired?: UiDecisionRequired;
 }
-/**
- * Existing-project init pipeline.
- *
- * Order:
- *   1. tokens init (auto-installs `teamix-evo-design-${variant}` skill)
- *   2. skills add (`teamix-evo-code-${variant}`; entry skill is global, ADR 0033)
- *   3. AGENTS.md (skill trigger fallback, ADR 0038)
- *   4. ui init + ui add (gated by `withUi`)
- *   5. lint init (gated by `withLint`)
- */
 declare function runProjectInit(options: RunProjectInitOptions): Promise<RunProjectInitResult>;
 
-type ProjectUpdateStepName = 'tokens' | 'skills' | 'ui' | 'biz-ui';
-type ProjectUpdateStepStatus = 'ok' | 'skip' | 'fail' | 'planned';
-interface ProjectUpdateStep {
-    name: ProjectUpdateStepName;
-    status: ProjectUpdateStepStatus;
-    detail?: string;
-}
-interface ProjectUpdateResumeHint {
-    /** The first step that failed (caller resumes from here). */
-    failedAt: ProjectUpdateStepName;
-    /** Steps already finished (status === 'ok'); will short-circuit on resume. */
-    completed: ProjectUpdateStepName[];
-    /** All steps that ended in fail status. */
-    failed: ProjectUpdateStepName[];
-    /** Human-readable error from the first failed step. */
-    error: string;
-    /**
-     * Suggested CLI command to resume. Today this is just `teamix-evo update`
-     * itself — every sub-step is idempotent (version-diff short-circuits when
-     * up-to-date), so a re-run continues from the failure point automatically.
-     */
-    resumeCommand: string;
-}
-interface RunProjectUpdateOptions {
-    /** Absolute project root (must already be teamix-evo-installed). */
-    projectRoot: string;
-    /**
-     * If true, plan-only mode: compute version deltas without writing any
-     * file. Returns each step with `status: 'planned'`.
-     */
-    dryRun?: boolean;
-    /** Step-level progress hook (caller controls presentation). */
-    onStep?: (step: ProjectUpdateStep) => void;
-    /** Override the tokens package name (defaults to `@teamix-evo/tokens`). */
-    tokensPackageName?: string;
-    /** Override the skills package name (defaults to `@teamix-evo/skills`). */
-    skillsPackageName?: string;
-}
-type RunProjectUpdateResult = {
-    status: 'not-initialized';
-} | {
-    status: 'up-to-date' | 'updated' | 'partial' | 'dry-run';
-    steps: ProjectUpdateStep[];
-    resumeHint?: ProjectUpdateResumeHint;
-    /**
-     * Pre-update snapshot of `.teamix-evo/` ([ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) §2).
-     * `null` on `dryRun`. Best-effort — capture failures surface via
-     * {@link snapshotError} but never abort the pipeline.
-     */
-    snapshot?: SnapshotResult | null;
-    /** Reason a snapshot capture failed (best-effort — never blocks update). */
-    snapshotError?: string;
-};
-/**
- * Post-init refresh pipeline.
- *
- * Order:
- *   1. tokens update (regenerable rewrite + frozen preserved — ADR 0003 三态)
- *   2. skills update (lock ∩ scope ∩ version-diff short-circuit — ADR 0035)
- *
- * Re-runs are safe: each sub-step short-circuits when already at latest.
- */
-declare function runProjectUpdate(options: RunProjectUpdateOptions): Promise<RunProjectUpdateResult>;
-
 interface InstallOptions {
     /** Project root directory */
     projectRoot: string;
@@ -1157,6 +900,8 @@ interface UiInstallOptions {
     requested: string[];
     /** When true, skip writing entries whose target file already exists (frozen-on-add). */
     skipExisting?: boolean;
+    /** When false, preserve directory structure in import paths (skip flattenRestPath). Defaults to true. */
+    flatten?: boolean;
 }
 interface UiInstallResult {
     /** Ordered list of entry ids that were processed (deps + requested) */
@@ -1247,4 +992,4 @@ declare function readInstalledManifest(projectRoot: string): Promise<InstalledMa
  */
 declare function writeInstalledManifest(projectRoot: string, manifest: InstalledManifest): Promise<void>;
 
-export { type ConflictItem, type ConflictKey, type ConflictReport, type ConflictStrategy, DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type ListVariantUiEntriesResult, type ListVariantUiResult, type ListVariantsResult, type PendingConflictWork, type ProjectInitStep, type ProjectInitStepName, type ProjectInitStepStatus, type ProjectState, type ProjectStateReport, type ProjectUpdateResumeHint, type ProjectUpdateStep, type ProjectUpdateStepName, type ProjectUpdateStepStatus, type ResumeHint, type RunGenerateAgentsMdOptions, type RunGenerateAgentsMdResult, type RunLintInitOptions, type RunLintInitResult, type RunProjectInitOptions, type RunProjectInitResult, type RunProjectUpdateOptions, type RunProjectUpdateResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunSkillsInitOptions, type RunSkillsInitResult, type RunSkillsUpdateOptions, type RunSkillsUpdateResult, type RunTokensInitOptions, type RunTokensInitResult, type RunUiAddOptions, type RunUiAddResult, type RunUiInitOptions, type RunUiInitResult, type RunUiListOptions, type RunUiListResult, type RunVariantUiAddOptions, type RunVariantUiAddResult, type SkillInstallOptions, type SkillInstallResult, type SkillSyncOptions, type SkillSyncResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, type UpdatePlanItem, detectConflicts, detectProjectState, ensureTeamixDir, extractDescriptionParts, getTeamixDir, installResources, installSkills, installUiEntries, listBizUiEntries, listBizUiVariants, listTemplatesEntries, listTemplatesVariants, listTokenVariants, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runBizUiAdd, runGenerateAgentsMd, runLintInit, runProjectInit, runProjectUpdate, runSkillsAdd, runSkillsInit, runSkillsUpdate, runTemplatesAdd, runTokensInit, runUiAdd, runUiInit, runUiList, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };
+export { type ConflictItem, type ConflictKey, type ConflictReport, type ConflictStrategy, DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type ListVariantUiEntriesResult, type ListVariantUiResult, type ListVariantsResult, type ProjectInitStep, type ProjectInitStepName, type ProjectInitStepStatus, type ProjectState, type ProjectStateReport, type ResumeHint, type RunGenerateAgentsMdOptions, type RunGenerateAgentsMdResult, type RunLintInitOptions, type RunLintInitResult, type RunProjectInitOptions, type RunProjectInitResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunSkillsInitOptions, type RunSkillsInitResult, type RunSkillsUpdateOptions, type RunSkillsUpdateResult, type RunTokensInitOptions, type RunTokensInitResult, type RunUiAddOptions, type RunUiAddResult, type RunUiInitOptions, type RunUiInitResult, type RunUiListOptions, type RunUiListResult, type RunVariantUiAddOptions, type RunVariantUiAddResult, type SkillInstallOptions, type SkillInstallResult, type SkillSyncOptions, type SkillSyncResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, type UpdatePlanItem, detectConflicts, detectProjectState, ensureTeamixDir, extractDescriptionParts, getTeamixDir, installResources, installSkills, installUiEntries, listBizUiEntries, listBizUiVariants, listTemplatesEntries, listTemplatesVariants, listTokenVariants, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runBizUiAdd, runGenerateAgentsMd, runLintInit, runProjectInit, runSkillsAdd, runSkillsInit, runSkillsUpdate, runTemplatesAdd, runTokensInit, runUiAdd, runUiInit, runUiList, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };