@x-otto/install 0.0.1-alpha.5 → 0.0.1-alpha.7

package/README.md

@@ -13,39 +13,45 @@ pnpm add @x-otto/install
 ## Usage
 
 ```typescript
-import { InstallManager } from '@x-otto/install'
-
-const manager = new InstallManager()
+import { install } from '@x-otto/install'
 
 // Install a skill from a local .tgz archive
-const result = await manager.install('./my-skill.tgz', {
+const result = await install('./my-skill.tgz', {
   workspaceDir: '/path/to/project',
   onProgress: (p) => console.log(`[${p.phase}] ${p.message}`),
 })
 
 // Install a plugin from npm
-const pluginResult = await manager.install('@scope/my-plugin', {
+const pluginResult = await install('@scope/my-plugin', {
   global: true,
 })
 
-// Install an MCP server from a git repo tag
-const mcpResult = await manager.install('https://github.com/user/mcp-server.git', {
-  ref: 'v1.2.0',
-  env: { API_KEY: 'xxx' },
-})
+// Install an MCP server from a git repo tag (MCP needs settings accessors)
+const mcpResult = await install(
+  'https://github.com/user/mcp-server.git',
+  { ref: 'v1.2.0', env: { API_KEY: 'xxx' } },
+  () => readMcpSettings(),
+  (servers) => persistMcpSettings(servers),
+)
 ```
 
-The `InstallManager` auto-detects the source type (file/url/git/npm) and content type (skill/plugin/mcp). Use `--as` to override auto-detection:
+`install()` auto-detects the source type (file/url/git/npm) and content type (skill/plugin/mcp). Use `as` to override auto-detection:
 
 ```typescript
 // Force treat content as plugin even if auto-detect might guess skill
-await manager.install('./dir', { as: 'plugin' })
+await install('./dir', { as: 'plugin' })
 ```
 
+> **Note (endgame review 2026-08-14):** `install` is a pure function — it replaced the
+> stateless `InstallManager` class (which held no instance state, so `new InstallManager()`
+> was an empty shell). MCP settings access is injected via the optional `getMcpSettings` /
+> `persistMcpSettings` callbacks; single-install semantics stay in `options`.
+
 ## Key Exports
 
 ### Installation
-- `InstallManager` — Top-level orchestrator with `install()` and `installSkill()` methods
+- `install()` — Top-level orchestrator (auto-detect source + content, dispatch to installer)
+- `installSkill()` — Convenience wrapper forcing `as: 'skill'`
 - `InstallOptions` — Workspace, scope, force, dry-run, sub-path, ref, progress callbacks
 - `InstallResult` — Success status, target path, definition/manifest, warnings, pending capabilities
 
@@ -70,8 +76,8 @@ await manager.install('./dir', { as: 'plugin' })
 
 ## Dependencies
 
-- **Internal**: `@x-otto/mcp`, `@x-otto/plugin`, `@x-otto/skill`, `@x-otto/shared`
-- **External**: `zod`, Node.js built-ins (fs, path, os, child_process)
+- **Internal**: `@x-otto/env`, `@x-otto/mcp`, `@x-otto/plugin`, `@x-otto/skill`, `@x-otto/shared`
+- **External**: `semver`, `zod`, Node.js built-ins (fs, path, os, child_process)
 
 ## Related
 

package/dist/index.d.ts

@@ -154,30 +154,30 @@ interface InstallOptions {
 //#endregion
 //#region src/installer.d.ts
 /**
- * InstallManager — 安装编排器。
+ * install — 安装编排入口（自动检测来源类型和内容类型）。
  *
  * 支持四种来源 × 三种内容类型。
  * 来源：file（本地归档）、url（HTTP 下载）、git（浅克隆）、npm（npm pack）
  * 内容：skill、plugin、mcp
  *
- * **阶段归属（RFC-286 D4）**：本类只负责 resolve / detect / write 三段，只 fire
- * `resolving` / `detecting` / `installing`。**不再 fire `refreshing`**——该阶段语义是
- * 「能力热重载」，真实动作 `App.reloadCapabilities()` 由 CLI 侧持有，install 包无 App
- * 句柄（引入会造成 install → coding 反向依赖）。此前本类在真实 reload 之前自行 fire
- * `refreshing`，是不拥有真实动作却展示真实阶段的「伪进度」，会让失败面板看起来仍在
- * 刷新。谁执行谁上报：`refreshing` 现由 `handlers/install.ts` 在调用真实 reload 前 fire。
- * `ProgressPhase` 类型保留 `'refreshing'` 取值供 CLI 使用。
+ * **形态（终局 review 2026-08-14 P1-1）**：此前是 `class InstallManager`，但该类零实例状态
+ * （无 logger/fetchImpl/配置持有），CLI 侧每次 `new InstallManager()` 都是空壳——类壳只是形式
+ * 化封装，无语义价值。降级为纯函数：单次安装语义走 `options`，MCP settings 访问经 `getMcpSettings`
+ * /`persistMcpSettings` 回调注入（本就是参数）。未引入 logger/fetchImpl/timeout 的 deps bag——
+ * 那三者当前无任何消费方（logger 在 url-resolver 硬编码、fetchImpl 仅 RegistryClient 用、timeout
+ * 已由 env var 覆盖），凭空造 bag 即为抽象而抽象。真需要时再随消费方一起引入。
+ *
+ * **阶段归属（RFC-286 D4）**：只负责 resolve / detect / write 三段，只 fire
+ * `resolving` / `detecting` / `installing`。**不 fire `refreshing`**——该阶段语义是「能力热重载」，
+ * 真实动作 `App.reloadCapabilities()` 由 CLI 侧持有，install 包无 App 句柄。谁执行谁上报：
+ * `refreshing` 由 `handlers/install.ts` 在调用真实 reload 前 fire。`ProgressPhase` 类型保留
+ * `'refreshing'` 取值供 CLI 使用。
  */
-declare class InstallManager {
-  /**
-   * 通用安装入口：自动检测来源类型和内容类型。
-   */
-  install(source: string, options: InstallOptions, getMcpSettings?: () => Record<string, unknown> | undefined, persistMcpSettings?: (servers: Record<string, unknown>) => Promise<void>): Promise<InstallResult>;
-  /**
-   * 安装 skill 包（兼容旧 API）。
-   */
-  installSkill(source: string, options: InstallOptions): Promise<InstallResult>;
-}
+declare function install(source: string, options: InstallOptions, getMcpSettings?: () => Record<string, unknown> | undefined, persistMcpSettings?: (servers: Record<string, unknown>) => Promise<void>): Promise<InstallResult>;
+/**
+ * 安装 skill 包（便捷入口：强制 `as: 'skill'`）。
+ */
+declare function installSkill(source: string, options: InstallOptions): Promise<InstallResult>;
 //#endregion
 //#region src/uninstaller.d.ts
 type UninstallTarget = 'skill' | 'plugin' | 'mcp';
@@ -192,6 +192,13 @@ interface UninstallResult {
   error?: string;
   /** dry-run 预览 */
   plan?: string[];
+  /**
+   * 非阻断告警（RFC-354 安全修复）：卸载成功但存在需用户知晓的残留风险。
+   * 典型：信任记录撤销失败——目录已删但信任白名单/能力授权可能残留，
+   * 重装同 id 插件到同一路径时旧授权会复活（fail-open）。撤销失败不阻断目录删除
+   * （删除是用户明确意图），但必须可见而非静默吞掉。
+   */
+  warnings?: string[];
 }
 interface InstalledItem {
   name: string;
@@ -233,7 +240,7 @@ declare function listInstalledItems(options: ListInstalledOptions, mcpServers?:
  * @param name 扩展名称
  * @param type 扩展类型（由 detectUninstallTarget 提供）
  * @param options 卸载选项
- * @param mcpServers 当前 mcp_servers 配置（仅 mcp 类型需要）
+ * @param getMcpServers 读取当前 mcp_servers 配置（仅 mcp 类型需要）
  * @param persistSettings 持久化 settings（仅 mcp 类型需要）
  */
 declare function uninstall(name: string, type: UninstallTarget, options: UninstallOptions, getMcpServers?: () => Record<string, unknown> | undefined, persistSettings?: (servers: Record<string, unknown>) => Promise<void>): Promise<UninstallResult>;
@@ -295,8 +302,12 @@ interface GitUpgradeCheckResult {
 /**
  * 检查 git 来源 skill/plugin 是否有更新。
  * 扫描 baseDir 下所有子目录的 .otto-install.json → git ls-remote → 比较 hash。
+ *
+ * 异步化（终局 review 2026-08-14 P1-3）：此前用 `spawnSync` 同步阻塞事件循环做
+ * 网络 `git ls-remote`——N 个 git 来源项串行最长阻塞 N×10s，TUI 环境冻结整个界面。
+ * 改为经包内共享 `spawnAsync`（与 git-resolver 同源），签名 `sync → async`。
  */
-declare function checkGitUpgrades(baseDir: string, type: 'skill' | 'plugin'): GitUpgradeCheckResult[];
+declare function checkGitUpgrades(baseDir: string, type: 'skill' | 'plugin'): Promise<GitUpgradeCheckResult[]>;
 //#endregion
 //#region src/archive-utils.d.ts
 /**
@@ -2392,6 +2403,12 @@ interface LoadedRegistry extends ParsedRegistry {
 }
 /** 官方源缺省条目（url 由调用方装配注入——发布形态未定期间指向仓内文件）。 */
 declare function builtinOfficialSource(url: string): RegistrySourceConfig;
+/**
+ * 2026-08-14 修订（用户指令）：删除内网官方源（`otto-official-internal`）自动加载——
+ * 原 RFC-341 G2 的 `OTTO_INTERNAL_REGISTRY_URL` + 内网可达探测机制整体退役，registry
+ * 单一走官方源（GitHub Pages）+ 用户自添源。内网插件发现不再依赖 registry 分发，
+ * 由插件自身的 install/装载链路负责（详见 RFC-341 修订记录）。
+ */
 declare class RegistryClient {
   private readonly options;
   constructor(options: {
@@ -2402,20 +2419,13 @@ declare class RegistryClient {
   });
   private get registriesPath();
   private get cacheDir();
-  /** 读源清单（官方源恒在首位；用户文件坏/缺时退化为仅官方源）。不含内网源——同步场景
-   *  （如 `/registry remove` 参数补全）不该为一次可能的网络探测阻塞输入响应，见 `listSourcesAsync`。 */
-  listSources(): RegistrySourceConfig[];
   /**
-   * 读源清单 + 内网可达时自动追加内网官方源（RFC-341 G2）——`otto-official`（公网）恒在
-   * 首位，`otto-official-internal`（内网）紧随其后（仅内网可达 + `OTTO_INTERNAL_REGISTRY_URL`
-   * 已配置时才出现），随后是用户自定义源。
+   * 读源清单（官方源恒在首位；用户文件坏/缺时退化为仅官方源）。
    *
-   * 与 `listSources()` 的取舍：本方法可能触发一次网络探测（`isIntranetReachable()` 内部
-   * 5 分钟缓存，非首次调用通常走缓存零延迟）——`loadAll()`/`/registry` 面板等本就是
-   * 异步流程的场景改用它；纯同步场景（如参数补全建议器）继续用 `listSources()`，
-   * 不因偶发探测延迟阻塞按键响应。
+   * 2026-08-14 修订：原 RFC-341 G2 的内网官方源自动追加（`listSourcesAsync`）已随
+   * 该特性整体退役删除——清单就是清单，不再含网络探测。
    */
-  listSourcesAsync(): Promise<RegistrySourceConfig[]>;
+  listSources(): RegistrySourceConfig[];
   addSource(name: string, url: string): void;
   removeSource(name: string): void;
   /**
@@ -2424,19 +2434,19 @@ declare class RegistryClient {
    * - 第三方源：改写用户配置中该条目的 disabled 字段；条目不存在则抛错。
    */
   setSourceEnabled(name: string, enabled: boolean): void;
-  /** 拉取全部启用源（缓存优先 → fetch → 陈旧缓存降级）。坏源跳过并记 warning。
-   *  RFC-341 G2：内网可达时自动含内网官方源（`listSourcesAsync`），公网用户/公网环境
-   *  不受影响（探测目标未配置时零网络请求、零延迟，见 `isIntranetReachable` doc）。 */
+  /** 拉取全部启用源（缓存优先 → fetch → 陈旧缓存降级）。坏源跳过并记 warning。 */
   loadAll(): Promise<{
     registries: LoadedRegistry[];
     warnings: string[];
   }>;
   private loadOne;
+  /** 缓存优先 → fetch → 陈旧缓存降级（URL 源与 npm 包源共用）。 */
+  private loadWithCache;
   private readUserSources;
   private writeUserSources;
   private readCache;
   private writeCache;
 }
 //#endregion
-export { type ContentType, type GitUpgradeCheckResult, InstallManager, type InstallOptions, type InstallProgress, type InstallResult, type InstallScope, type InstallSourceMetadata, type InstalledItem, type ListInstalledOptions, type LoadedRegistry, type ParsedRegistry, type PostInstallContext, type PostInstallResult, type ProgressPhase, type RegistriesFile, RegistryClient, type RegistryEntry, type RegistryEntryType, type RegistrySourceConfig, type ResolvedSource, type SourceType, type UninstallOptions, type UninstallResult, type UninstallTarget, type UpgradeCheckOptions, type UpgradeCheckResult, type VersionInfo, builtinOfficialSource, checkArchiveBomb, checkGitUpgrades, checkUpgrades, cleanTempDir, createArchive, createTempDir, detectUninstallTarget, extractArchive, listInstalledItems, parseRegistry, registryEntrySchema, registryEntryTypeSchema, registrySchema, sanitizeSourceUrl, scanInstalledVersions, uninstall, validateExtractedPaths };
+export { type ContentType, type GitUpgradeCheckResult, type InstallOptions, type InstallProgress, type InstallResult, type InstallScope, type InstallSourceMetadata, type InstalledItem, type ListInstalledOptions, type LoadedRegistry, type ParsedRegistry, type PostInstallContext, type PostInstallResult, type ProgressPhase, type RegistriesFile, RegistryClient, type RegistryEntry, type RegistryEntryType, type RegistrySourceConfig, type ResolvedSource, type SourceType, type UninstallOptions, type UninstallResult, type UninstallTarget, type UpgradeCheckOptions, type UpgradeCheckResult, type VersionInfo, builtinOfficialSource, checkArchiveBomb, checkGitUpgrades, checkUpgrades, cleanTempDir, createArchive, createTempDir, detectUninstallTarget, extractArchive, install, installSkill, listInstalledItems, parseRegistry, registryEntrySchema, registryEntryTypeSchema, registrySchema, sanitizeSourceUrl, scanInstalledVersions, uninstall, validateExtractedPaths };
 //# sourceMappingURL=index.d.ts.map