wave-agent-sdk 1.1.5 → 1.3.0

package/dist/services/MarketplaceService.d.ts

@@ -1,4 +1,4 @@
-import { KnownMarketplace, KnownMarketplacesRegistry, InstalledPlugin, InstalledPluginsRegistry, MarketplaceManifest, MarketplaceSource } from "../types/marketplace.js";
+import { KnownMarketplace, KnownMarketplacesRegistry, InstalledPlugin, InstalledPluginsRegistry, MarketplaceManifest, MarketplaceSource, PluginInstallLocation } from "../types/marketplace.js";
 import { ConfigurationService } from "./configurationService.js";
 import type { Scope } from "../types/configuration.js";
 /**
@@ -11,7 +11,18 @@ import type { Scope } from "../types/configuration.js";
  * known_marketplaces.json is kept as a cache for installLocation/lastUpdated metadata.
  */
 export declare class MarketplaceService {
-    private static isLockedInProcess;
+    /**
+     * 已持有市场操作锁的调用链标记（重入判据）。
+     *
+     * 用 AsyncLocalStorage 而不是进程内布尔值：锁内发起的嵌套调用（如
+     * refreshMarketplaces → updateMarketplace → installPlugin）必须跳过再次加锁，
+     * 否则会自锁；但**另一条并发调用链**必须老老实实排队。布尔值无法区分这两者
+     * ——第二个并发调用会以为「已在锁内」而跳过锁直接执行，于是两个操作并行改同一
+     * 个市场检出（并发两次 `git pull` 同一检出必然失败，spec 插件市场 场景 14）。
+     */
+    private static readonly lockChain;
+    /** In-flight [refreshMarketplaces] call (single-flight, spec 插件市场 场景 13). */
+    private refreshInFlight;
     private pluginsDir;
     private knownMarketplacesPath;
     private installedPluginsPath;
@@ -49,7 +60,7 @@ export declare class MarketplaceService {
     private isStaleLock;
     /**
      * Acquires a file-based lock (with PID tracking for stale lock detection) and executes the provided function.
-     * Supports re-entrancy within the same process.
+     * Supports re-entrancy within the same call chain (see [lockChain]).
      */
     private withLock;
     /**
@@ -78,6 +89,21 @@ export declare class MarketplaceService {
      * Saves the installed plugins registry
      */
     saveInstalledPlugins(registry: InstalledPluginsRegistry): Promise<void>;
+    /**
+     * Whether an install record belongs to the given install location.
+     *
+     * Records written before scopes were tracked carry no `scope`; they stand for
+     * "installed once on this machine" and match any scope, so uninstalling them
+     * keeps working (they are that plugin's only record). They still match by
+     * project path, so records of two different projects stay distinguishable.
+     */
+    private matchesInstallLocation;
+    /**
+     * The install location a record is keyed by. Scope-less legacy records are
+     * treated as user-scope when they have to be re-created (e.g. by an update).
+     */
+    private locationOf;
+    private describeInstallLocations;
     /**
      * Loads a marketplace manifest from a local path
      */
@@ -94,6 +120,18 @@ export declare class MarketplaceService {
      * Finds which scope declared a marketplace (user, project, local, or builtin)
      */
     getMarketplaceDeclaringSource(name: string): Scope | "builtin" | null;
+    /**
+     * 已注册的市场（作用域配置 + 缓存注册表合并去重），用于添加前的判重
+     */
+    private listRegisteredMarketplaces;
+    /**
+     * 添加市场前判重（spec ecosystem/plugin「设置页插件市场」场景 16）：来源重复或
+     * 清单声明的名称与已有市场同名时不允许添加。只传 source 时仅判来源（用于克隆
+     * 之前，避免为一个已存在的来源白克隆一次）。
+     */
+    private assertMarketplaceAddable;
+    /** 两个市场来源是否指向同一处（同类型比 url/repo/path，忽略 ref） */
+    private static isSameMarketplaceSource;
     /**
      * Adds a new marketplace (local directory, GitHub repo, or Git URL)
      */
@@ -114,28 +152,74 @@ export declare class MarketplaceService {
     private uninstallPluginsByMarketplace;
     /**
      * Updates a specific marketplace or all marketplaces
+     *
+     * `refreshCheckout` (default true) pulls the checkout from its upstream; pass
+     * false to upgrade plugins against the current checkout only — the interactive
+     * "批量更新插件" path does that, because opening the plugin-marketplace surface
+     * already refreshed the checkout (spec 插件市场 A-013).
+     *
+     * Returns the number of installed plugins whose version actually changed
+     * during this run (0 = everything was already up to date) — the GUI hosts
+     * use it to tell "已更新 N 个插件" apart from "已是最新" (spec 插件市场 场景 13).
      */
     updateMarketplace(name?: string, options?: {
         updatePlugins?: boolean;
-    }): Promise<void>;
-    /**
-     * Automatically updates all marketplaces that have auto-update enabled
-     */
-    autoUpdateAll(): Promise<void>;
-    /**
-     * Toggles auto-update for a marketplace
-     */
-    toggleAutoUpdate(name: string, enabled: boolean): Promise<void>;
+        refreshCheckout?: boolean;
+    }): Promise<number>;
+    /**
+     * 交互界面的「批量更新插件」：按当前清单把该市场内所有已安装且有新版本的插件
+     * 升级到最新，**不拉取检出**——清单的新鲜度由打开插件市场界面时的那次刷新保证
+     * （spec 插件市场 A-013/场景 14）。检出尚未据此刷新的场景（无界面可依赖的非交互
+     * 命令）走 [updateMarketplace] 的默认行为。
+     */
+    updateMarketplacePlugins(name?: string): Promise<number>;
+    /**
+     * Refreshes the local checkout of every registered marketplace.
+     *
+     * Callers are the plugin-marketplace surfaces (GUI settings view / CLI plugin
+     * manager), refreshed when the user opens them — the agent-startup path no
+     * longer refreshes anything (spec 插件市场 A-013 场景 5).
+     *
+     * This is a fixed behavior with no opt-in/opt-out: `autoUpdate` no longer
+     * exists, so all marketplaces are refreshed alike (A-014). Refreshing only
+     * updates the checkout — installed plugins are never reinstalled here, so a
+     * newer plugin version surfaces as an explicit "更新" (per plugin) /
+     * "批量更新插件" (batch) action instead of being applied behind the user's
+     * back.
+     *
+     * Single-flight: a call landing while a refresh is running reuses it instead
+     * of pulling every checkout twice (spec 场景 13).
+     */
+    refreshMarketplaces(): Promise<void>;
     /**
      * Installs a plugin from a marketplace
+     *
+     * @param location 该次安装记账的位置（spec plugin A-015）。缺省只在内部调用
+     *   （宿主加载时补装）出现，此时写入一条不带作用域的历史形态记录。
      */
-    installPlugin(pluginAtMarketplace: string, projectPath?: string): Promise<InstalledPlugin>;
+    installPlugin(pluginAtMarketplace: string, location?: PluginInstallLocation): Promise<InstalledPlugin>;
     /**
      * Uninstalls a plugin
-     */
-    uninstallPlugin(pluginAtMarketplace: string, projectPath?: string): Promise<void>;
-    /**
-     * Updates a plugin (uninstall followed by install)
+     *
+     * With a [location], only that scope's install record is removed — other
+     * scopes (including other projects' project/local records) keep theirs, and
+     * the shared cache directory is deleted only once no record references it
+     * (spec plugin A-015). Without one, every record of the plugin is removed
+     * (used by [updatePlugin] and the marketplace-level cleanup).
+     */
+    uninstallPlugin(pluginAtMarketplace: string, location?: PluginInstallLocation): Promise<void>;
+    /**
+     * Moves a plugin's install record to another location（「更换安装作用域」）:
+     * the record currently at [from] (or the plugin's only record when [from] is
+     * omitted or unknown) is rewritten to [to], so that uninstalling the plugin
+     * at its new scope still finds it (spec plugin A-015). A duplicate record
+     * already at [to] wins and the moved one is dropped.
+     */
+    relocatePlugin(pluginAtMarketplace: string, from: PluginInstallLocation | undefined, to: PluginInstallLocation): Promise<void>;
+    /**
+     * Updates a plugin (uninstall followed by install). Every install record of
+     * the plugin is re-created at its original location, so the install scopes
+     * stay unchanged (spec plugin「设置页插件市场」场景 12 / A-015).
      */
     updatePlugin(pluginAtMarketplace: string): Promise<InstalledPlugin>;
 }