@yancyyu/openhermit 1.6.28 → 1.6.30

package/src/main/services/extensions/catalog/PluginCatalogService.ts

@@ -0,0 +1,392 @@
+/**
+ * Fetches and caches the Claude Code plugin marketplace catalog.
+ *
+ * - Fetches marketplace.json from raw.githubusercontent.com
+ * - ETag + If-None-Match for bandwidth efficiency
+ * - In-memory cache with TTL (15 min)
+ * - Stale cache fallback on network error
+ * - Deduplicates concurrent requests
+ */
+
+import { promises as fsp } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import path from 'node:path';
+
+import { getClaudeBasePath } from '@main/utils/pathDecoder';
+import { buildPluginId } from '@shared/utils/extensionNormalizers';
+import { createLogger } from '@shared/utils/logger';
+
+import type { PluginCatalogItem } from '@shared/types/extensions';
+
+const logger = createLogger('Extensions:PluginCatalog');
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const MARKETPLACE_URL =
+  'https://raw.githubusercontent.com/anthropics/claude-plugins-official/main/.claude-plugin/marketplace.json';
+
+const CACHE_TTL_MS = 15 * 60 * 1_000; // 15 minutes
+const HTTP_TIMEOUT_MS = 15_000; // 15 seconds
+const MAX_REDIRECTS = 5;
+const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB safety limit
+const MAX_README_CACHE_SIZE = 50; // Max README entries to cache
+
+// ── HTTP helpers (adapted from CliInstallerService) ────────────────────────
+
+interface FetchOptions {
+  headers?: Record<string, string>;
+}
+
+interface FetchResponse {
+  statusCode: number;
+  headers: Record<string, string | string[] | undefined>;
+  body: string;
+}
+
+function httpsGetFollowRedirects(
+  url: string,
+  options: FetchOptions = {},
+  redirectsLeft = MAX_REDIRECTS,
+  timeoutMs = HTTP_TIMEOUT_MS
+): Promise<FetchResponse> {
+  return new Promise((resolve, reject) => {
+    const parsedUrl = new URL(url);
+    const transport = parsedUrl.protocol === 'http:' ? http : https;
+    let settled = false;
+
+    const settleResolve = (value: FetchResponse): void => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const settleReject = (err: Error): void => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    };
+
+    const reqOptions = {
+      headers: options.headers ?? {},
+    };
+
+    const req = transport.get(url, reqOptions, (res) => {
+      const status = res.statusCode ?? 0;
+
+      if (status >= 300 && status < 400 && res.headers.location) {
+        if (redirectsLeft <= 0) {
+          res.destroy();
+          settleReject(new Error('Too many redirects'));
+          return;
+        }
+        const redirectUrl = new URL(res.headers.location, url).toString();
+        res.destroy();
+        httpsGetFollowRedirects(redirectUrl, options, redirectsLeft - 1, timeoutMs).then(
+          settleResolve,
+          settleReject
+        );
+        return;
+      }
+
+      const chunks: Buffer[] = [];
+      let totalSize = 0;
+      res.on('data', (chunk: Buffer) => {
+        totalSize += chunk.length;
+        if (totalSize > MAX_BODY_SIZE) {
+          res.destroy(new Error(`Response body exceeds ${MAX_BODY_SIZE} bytes`));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      res.on('end', () =>
+        settleResolve({
+          statusCode: status,
+          headers: res.headers as Record<string, string | string[] | undefined>,
+          body: Buffer.concat(chunks).toString('utf-8'),
+        })
+      );
+      res.on('error', settleReject);
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`Connection timed out after ${timeoutMs}ms fetching ${url}`));
+    });
+    req.on('error', (err) => settleReject(err instanceof Error ? err : new Error(String(err))));
+  });
+}
+
+// ── Marketplace JSON shape ─────────────────────────────────────────────────
+
+interface MarketplaceJson {
+  name: string;
+  plugins: RawMarketplacePlugin[];
+}
+
+interface RawMarketplacePlugin {
+  name: string;
+  description?: string;
+  version?: string;
+  category?: string;
+  author?: { name: string; email?: string };
+  source: string | { source: string; url: string; sha?: string };
+  homepage?: string;
+  tags?: string[];
+  strict?: boolean;
+  lspServers?: Record<string, unknown>;
+  mcpServers?: Record<string, unknown>;
+  agents?: Record<string, unknown>;
+  commands?: Record<string, unknown>;
+  hooks?: Record<string, unknown>;
+}
+
+// ── Cache ──────────────────────────────────────────────────────────────────
+
+interface CatalogCache {
+  items: PluginCatalogItem[];
+  etag: string | null;
+  fetchedAt: number;
+}
+
+// ── Service ────────────────────────────────────────────────────────────────
+
+export class PluginCatalogService {
+  private cache: CatalogCache | null = null;
+  private fetchInFlight: Promise<PluginCatalogItem[]> | null = null;
+  private readmeCache = new Map<string, { content: string | null; fetchedAt: number }>();
+
+  /**
+   * Get all plugins shown in the store: the official Anthropic marketplace plus
+   * any plugins from marketplaces the user has registered locally (e.g. custom
+   * git marketplaces like `oh-my-claudecode@omc`). Each source is resilient —
+   * a failure in one does not hide the other.
+   */
+  async getPlugins(forceRefresh = false): Promise<PluginCatalogItem[]> {
+    const [official, local] = await Promise.all([
+      this.getOfficialPlugins(forceRefresh).catch((err) => {
+        logger.warn('Official marketplace unavailable:', err);
+        return [] as PluginCatalogItem[];
+      }),
+      this.getLocalPlugins().catch((err) => {
+        logger.warn('Local marketplaces unavailable:', err);
+        return [] as PluginCatalogItem[];
+      }),
+    ]);
+
+    // Official wins on pluginId collisions; append local plugins not already present.
+    const seen = new Set(official.map((p) => p.pluginId));
+    return [...official, ...local.filter((p) => !seen.has(p.pluginId))];
+  }
+
+  /**
+   * Get plugins from the official Anthropic marketplace.
+   * Uses in-memory cache with ETag validation.
+   */
+  private async getOfficialPlugins(forceRefresh = false): Promise<PluginCatalogItem[]> {
+    // Return cached if fresh and not forcing
+    if (!forceRefresh && this.cache && Date.now() - this.cache.fetchedAt < CACHE_TTL_MS) {
+      return this.cache.items;
+    }
+
+    // Deduplicate concurrent requests
+    if (this.fetchInFlight) {
+      return this.fetchInFlight;
+    }
+
+    this.fetchInFlight = this.fetchCatalog().finally(() => {
+      this.fetchInFlight = null;
+    });
+
+    return this.fetchInFlight;
+  }
+
+  /**
+   * Read plugins from marketplaces the user has registered locally.
+   *
+   * Source of truth: `~/.claude/plugins/known_marketplaces.json`, which maps a
+   * marketplace name to its on-disk `installLocation`. Each location holds a
+   * `.claude-plugin/marketplace.json` describing its plugins.
+   */
+  private async getLocalPlugins(): Promise<PluginCatalogItem[]> {
+    const pluginsDir = path.join(getClaudeBasePath(), 'plugins');
+    const knownPath = path.join(pluginsDir, 'known_marketplaces.json');
+
+    let known: Record<string, { installLocation?: string }>;
+    try {
+      known = JSON.parse(await fsp.readFile(knownPath, 'utf-8')) as Record<
+        string,
+        { installLocation?: string }
+      >;
+    } catch {
+      return []; // No known marketplaces (or unreadable) — nothing local to add.
+    }
+
+    const items: PluginCatalogItem[] = [];
+    for (const [, entry] of Object.entries(known)) {
+      const installLocation = entry?.installLocation;
+      if (!installLocation) continue;
+      const marketplaceJsonPath = path.join(installLocation, '.claude-plugin', 'marketplace.json');
+      try {
+        const json = JSON.parse(
+          await fsp.readFile(marketplaceJsonPath, 'utf-8')
+        ) as MarketplaceJson;
+        if (Array.isArray(json.plugins)) {
+          items.push(...this.parseMarketplace(json, 'local'));
+        }
+      } catch (err) {
+        logger.warn(`Failed to read local marketplace at ${marketplaceJsonPath}:`, err);
+      }
+    }
+    return items;
+  }
+
+  /**
+   * Get README content for a plugin by its pluginId.
+   * For external plugins (source is URL), fetches README from the GitHub repo.
+   * Returns null for local/bundled plugins or on error.
+   */
+  async getPluginReadme(pluginId: string): Promise<string | null> {
+    const cached = this.readmeCache.get(pluginId);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+      return cached.content;
+    }
+
+    // Need catalog to find the plugin's repo URL
+    const plugins = await this.getPlugins();
+    const plugin = plugins.find((p) => p.pluginId === pluginId);
+    if (!plugin?.homepage) {
+      this.setReadmeCache(pluginId, null);
+      return null;
+    }
+
+    const readmeUrl = this.buildReadmeUrl(plugin.homepage);
+    if (!readmeUrl) {
+      this.setReadmeCache(pluginId, null);
+      return null;
+    }
+
+    try {
+      const response = await httpsGetFollowRedirects(readmeUrl);
+      if (response.statusCode === 200) {
+        this.setReadmeCache(pluginId, response.body);
+        return response.body;
+      }
+      this.setReadmeCache(pluginId, null);
+      return null;
+    } catch (err) {
+      logger.warn(`Failed to fetch README for ${pluginId}:`, err);
+      this.setReadmeCache(pluginId, null);
+      return null;
+    }
+  }
+
+  /**
+   * Look up a single plugin by pluginId from the cached catalog.
+   * Used for main-side re-resolution during install.
+   */
+  async resolvePlugin(pluginId: string): Promise<PluginCatalogItem | null> {
+    const plugins = await this.getPlugins();
+    return plugins.find((p) => p.pluginId === pluginId) ?? null;
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────
+
+  /** Set readme cache with LRU eviction */
+  private setReadmeCache(pluginId: string, content: string | null): void {
+    // Evict oldest entries if at capacity
+    if (this.readmeCache.size >= MAX_README_CACHE_SIZE && !this.readmeCache.has(pluginId)) {
+      let oldestKey: string | null = null;
+      let oldestTime = Infinity;
+      for (const [key, entry] of this.readmeCache) {
+        if (entry.fetchedAt < oldestTime) {
+          oldestTime = entry.fetchedAt;
+          oldestKey = key;
+        }
+      }
+      if (oldestKey) this.readmeCache.delete(oldestKey);
+    }
+    this.readmeCache.set(pluginId, { content, fetchedAt: Date.now() });
+  }
+
+  private async fetchCatalog(): Promise<PluginCatalogItem[]> {
+    const headers: Record<string, string> = {};
+    if (this.cache?.etag) {
+      headers['If-None-Match'] = this.cache.etag;
+    }
+
+    try {
+      const response = await httpsGetFollowRedirects(MARKETPLACE_URL, { headers });
+
+      // 304 Not Modified — cache is still valid
+      if (response.statusCode === 304 && this.cache) {
+        this.cache.fetchedAt = Date.now();
+        logger.info('Marketplace catalog not modified (304)');
+        return this.cache.items;
+      }
+
+      if (response.statusCode !== 200) {
+        throw new Error(`HTTP ${response.statusCode} fetching marketplace`);
+      }
+
+      const json = JSON.parse(response.body) as MarketplaceJson;
+      const items = this.parseMarketplace(json);
+      const etag = (response.headers.etag as string) ?? null;
+
+      this.cache = { items, etag, fetchedAt: Date.now() };
+      logger.info(`Fetched ${items.length} plugins from marketplace "${json.name}"`);
+      return items;
+    } catch (err) {
+      // Stale cache fallback
+      if (this.cache) {
+        logger.warn('Marketplace fetch failed, using stale cache:', err);
+        return this.cache.items;
+      }
+      logger.error('Marketplace fetch failed with no cache:', err);
+      throw err;
+    }
+  }
+
+  private parseMarketplace(
+    json: MarketplaceJson,
+    source: 'official' | 'local' = 'official'
+  ): PluginCatalogItem[] {
+    const marketplaceName = json.name;
+
+    return json.plugins.map((raw): PluginCatalogItem => {
+      const qualifiedName = buildPluginId(raw.name, marketplaceName);
+      const isExternal = typeof raw.source === 'object';
+      const homepage =
+        raw.homepage ?? (isExternal ? (raw.source as { url: string }).url : undefined);
+
+      return {
+        pluginId: qualifiedName,
+        marketplaceId: qualifiedName,
+        qualifiedName,
+        name: raw.name,
+        source,
+        description: raw.description ?? '',
+        category: raw.category ?? 'other',
+        author: raw.author,
+        version: raw.version,
+        homepage: homepage?.replace(/\.git$/, ''),
+        tags: raw.tags,
+        hasLspServers: raw.lspServers != null && Object.keys(raw.lspServers).length > 0,
+        hasMcpServers: raw.mcpServers != null && Object.keys(raw.mcpServers).length > 0,
+        hasAgents: raw.agents != null && Object.keys(raw.agents).length > 0,
+        hasCommands: raw.commands != null && Object.keys(raw.commands).length > 0,
+        hasHooks: raw.hooks != null && Object.keys(raw.hooks).length > 0,
+        isExternal,
+      };
+    });
+  }
+
+  /**
+   * Build raw GitHub README URL from a GitHub repo URL.
+   * e.g. https://github.com/org/repo → https://raw.githubusercontent.com/org/repo/main/README.md
+   */
+  private buildReadmeUrl(repoUrl: string): string | null {
+    const match = /github\.com\/([^/]+)\/([^/]+)/.exec(repoUrl);
+    if (!match) return null;
+    const [, owner, repo] = match;
+    return `https://raw.githubusercontent.com/${owner}/${repo}/main/README.md`;
+  }
+}