teamix-evo 0.5.0 → 0.6.0

package/README.md

@@ -174,9 +174,10 @@ 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 skills add [name...]`                   | 装 skills(写源 + 镜像 IDE);不传 = 全装                         |
+| `teamix-evo skills init`                            | 自举 skills(按 variant + scope 全装 — ADR 0034)                |
+| `teamix-evo skills add <name...>`                   | 增量装指定 skill(`<name...>` 必填)                             |
 | `teamix-evo skills list`                            | 列出所有 skill 的安装状态                                      |
-| `teamix-evo skills update`                          | 升级 skills(保留 managed 改动)                                 |
+| `teamix-evo skills update [name...] [--dry-run]`    | 升级 skills(双闸 + version 短路 — ADR 0035)                    |
 | `teamix-evo skills sync [name...]`                  | 源 → IDE 镜像(漂移恢复用)                                      |
 | `teamix-evo skills doctor`                          | 检测源/镜像漂移(ADR 0013)                                      |
 | `teamix-evo skills uninstall`                       | 卸载 skills(源 + 镜像 + lock)                                  |
@@ -187,6 +188,7 @@ TEAMIX_DEBUG=1 teamix-evo tokens init opentrek
 | `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 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) |
 
@@ -196,7 +198,7 @@ TEAMIX_DEBUG=1 teamix-evo tokens init opentrek
 
 ### 全局装 skill(`--scope global`)
 
-`skills add` 支持 `--scope global` 装到 IDE 全局(`~/.qoder/skills/` + `~/.claude/skills/`)。当 cwd 不是 Teamix Evo 项目时,工具会自动把元数据写到 `~/.teamix-evo-global/`,不污染当前目录。
+`skills init` 与 `skills add` 都支持 `--scope global` 装到 IDE 全局(`~/.qoder/skills/` + `~/.claude/skills/`)。当 cwd 不是 Teamix Evo 项目时,工具会自动把元数据写到 `~/.teamix-evo-global/`,不污染当前目录。
 
 ```bash
 # Onboarding 推荐:全局装 manage skill

package/dist/core/index.d.ts

@@ -80,31 +80,58 @@ interface ListVariantsResult {
 }
 declare function listTokenVariants(packageName?: string, packageRoot?: string): Promise<ListVariantsResult>;
 
+interface RunSkillsInitOptions {
+    /** Absolute project root directory. */
+    projectRoot: string;
+    /** Target IDEs to inject skills into. Required (bulk has no fallback source). */
+    ides: readonly SkillIde[];
+    /** Install scope. Required (bulk has no fallback source). */
+    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;
+}
+type RunSkillsInitResult = {
+    status: 'installed';
+    packageName: string;
+    version: string;
+    ides: SkillIde[];
+    scope: SkillScope;
+    skillCount: number;
+    fileCount: number;
+    resources: InstalledResource[];
+    addedSkillIds: string[];
+    skippedSkillIds: string[];
+} | {
+    /** Returned when a skills package is already installed and bulk has nothing new to add. */
+    status: 'already-initialized';
+};
+/**
+ * Programmatic equivalent of `teamix-evo skills init`.
+ *
+ * Installs every manifest skill that matches the current tokens variant +
+ * install scope (per ADR 0033 scope filter). Re-running on a project whose
+ * `packages.skills` is already configured AND has no missing candidates
+ * returns `'already-initialized'`.
+ */
+declare function runSkillsInit(options: RunSkillsInitOptions): Promise<RunSkillsInitResult>;
 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.
+     * Skill ids to add. **Required, must contain at least one id.** Use
+     * {@link runSkillsInit} for bulk bootstrap (no ids).
      */
+    names: readonly string[];
+    /** Target IDEs. Optional — falls back to the previously installed config. */
     ides?: readonly SkillIde[];
-    /**
-     * Install scope. Optional in incremental mode (falls back to existing
-     * config). Required for the bulk path.
-     */
+    /** Install scope. Optional — falls back to existing config. */
     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';
@@ -122,21 +149,85 @@ type RunSkillsAddResult = {
     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`.
+ * Programmatic equivalent of `teamix-evo skills add <names...>` (ADR 0034).
  *
- * - 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.
+ * Installs 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.
+ *
+ * Throws if `names` is empty — bulk bootstrap belongs to {@link runSkillsInit}.
  */
 declare function runSkillsAdd(options: RunSkillsAddOptions): Promise<RunSkillsAddResult>;
 
+interface RunSkillsUpdateOptions {
+    /** Absolute project (or global meta) root. */
+    projectRoot: string;
+    /**
+     * Optional: limit the update to these skill ids. Falls back to "every
+     * skill in lock that matches the current install scope".
+     */
+    names?: readonly string[];
+    /** When true, plan only — no source rewrite, no mirror, no lock write. */
+    dryRun?: boolean;
+    /** Override the skills package name (defaults to `@teamix-evo/skills`). */
+    packageName?: string;
+}
+interface UpdatePlanItem {
+    id: string;
+    current: string;
+    next: string;
+    /** Same as updateStrategy semantics, computed from the manifest. */
+    strategy: 'frozen' | 'regenerable' | 'managed';
+    /**
+     * Predicted action for this skill source file in non-dryRun mode.
+     * - `up-to-date`  — version unchanged; safe to skip
+     * - `version-bump` — version changed; will overwrite/merge per strategy
+     */
+    action: 'up-to-date' | 'version-bump';
+}
+type RunSkillsUpdateResult = {
+    status: 'no-skills';
+} | {
+    status: 'no-changes';
+    packageName: string;
+    version: string;
+    checkedSkillIds: string[];
+} | {
+    status: 'dry-run';
+    packageName: string;
+    currentVersion: string;
+    availableVersion: string;
+    plan: UpdatePlanItem[];
+} | {
+    status: 'updated';
+    packageName: string;
+    version: string;
+    ides: SkillIde[];
+    scope: SkillScope;
+    updatedSkillIds: string[];
+    skippedSkillIds: string[];
+    summary: {
+        overwritten: number;
+        managed: number;
+        skipped: number;
+        created: number;
+    };
+    resources: InstalledResource[];
+};
+/**
+ * Programmatic equivalent of `teamix-evo skills update [names...] [--dry-run]`.
+ *
+ * Per ADR 0035:
+ *   1. Range = `keys(lock.skills) ∩ scope-match ∩ (names if given)`
+ *   2. version-diff short-circuit when every target id has the same lock
+ *      version as the manifest
+ *   3. New skills (not in lock) are NEVER auto-installed by update
+ *   4. lock writeback only touches `targetIds` — existing entries are preserved
+ */
+declare function runSkillsUpdate(options: RunSkillsUpdateOptions): Promise<RunSkillsUpdateResult>;
+
 declare const DEFAULT_UI_ALIASES: UiAliases;
 declare const DEFAULT_UI_ICON_LIBRARY = "lucide";
 interface RunUiInitOptions {
@@ -244,6 +335,31 @@ interface RunUiListResult {
  */
 declare function runUiList(options: RunUiListOptions): Promise<RunUiListResult>;
 
+interface RunLintInitOptions {
+    /** Absolute project root directory. */
+    projectRoot: string;
+    /**
+     * Skip npm dependency installation. Used by the create scaffold where
+     * dependencies are already declared in the template package.json and
+     * installed in a later batch step.
+     */
+    skipInstall?: boolean;
+}
+type RunLintInitResult = {
+    status: 'installed';
+    eslint: boolean;
+    stylelint: boolean;
+} | {
+    status: 'already-initialized';
+};
+/**
+ * Programmatic equivalent of `teamix-evo lint init`.
+ *
+ * Writes lint configuration files and optionally installs dependencies.
+ * Idempotent: if both config files already exist, returns `already-initialized`.
+ */
+declare function runLintInit(options: RunLintInitOptions): Promise<RunLintInitResult>;
+
 interface InstallOptions {
     /** Project root directory */
     projectRoot: string;
@@ -316,6 +432,16 @@ interface SkillUpdateOptions extends SkillInstallOptions {
      * unused by the new flow. Callers should stop passing it.
      */
     installed?: InstalledResource[];
+    /**
+     * Optional: limit the update to these skill ids. When provided, skills not
+     * in the set are skipped (no source rewrite, no mirror). Per ADR 0035,
+     * the high-level `runSkillsUpdate` always passes this with the intersection
+     * of `keys(lock.skills)` and the current install scope, ensuring update
+     * never accidentally installs new skills or skills from a mismatched scope.
+     *
+     * Type matches `SkillInstallOptions.onlyIds` (mutable `string[] | undefined`).
+     */
+    onlyIds?: string[];
 }
 interface SkillUpdateResult {
     resources: InstalledResource[];
@@ -481,4 +607,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 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 };
+export { DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type ListVariantsResult, type RunLintInitOptions, type RunLintInitResult, 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 SkillInstallOptions, type SkillInstallResult, type SkillSyncOptions, type SkillSyncResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, type UpdatePlanItem, ensureTeamixDir, getTeamixDir, installResources, installSkills, installUiEntries, listTokenVariants, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runLintInit, runSkillsAdd, runSkillsInit, runSkillsUpdate, runTokensInit, runUiAdd, runUiInit, runUiList, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };