fix(tui): render /plugins marketplace before version lookups resolve

Author: elkaix

.changeset/plugins-marketplace-async-versions.md

@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": patch
+---
+
+Show the /plugins marketplace catalog as soon as it loads, with latest-version lookups running in the background.

apps/pythinker-code/src/constant/app.ts

@@ -75,3 +75,7 @@ export const OAUTH_LOGIN_REQUIRED_CODE = ErrorCodes.AUTH_LOGIN_REQUIRED;
 export {
   PYTHINKER_CODE_PLUGIN_MARKETPLACE_URL_ENV,
 } from '@pymodel/agent-core-v2/app/plugin/marketplace';
+// Bound on each background "latest release" lookup when the TUI fills in
+// marketplace versions. Without it a stalled connection to github.com hangs
+// the version phase for undici's default header timeout (300s).
+export const MARKETPLACE_VERSION_LOOKUP_TIMEOUT_MS = 5000;

apps/pythinker-code/src/tui/commands/plugins.ts

@@ -35,7 +35,13 @@ import {
   isOfficialPluginSource,
 } from '../utils/plugin-source-label';
 import { PYTHINKER_CODE_PLUGIN_MARKETPLACE_URL_ENV } from '#/constant/app';
-import { loadPluginMarketplace, type PluginMarketplaceEntry } from '#/utils/plugin-marketplace';
+import {
+  loadPluginMarketplace,
+  withBuiltInEntries,
+  withMarketplaceLatestVersions,
+  type PluginMarketplace,
+  type PluginMarketplaceEntry,
+} from '#/utils/plugin-marketplace';
 import type { SlashCommandHost } from './dispatch';
 
 interface ShowPluginsPickerOptions {
@@ -343,18 +349,49 @@ async function loadMarketplaceCatalog(
   source: string | undefined,
   capabilities: readonly CapabilityStatus[],
 ): Promise<void> {
+  const builtInEntries =
+    host.engineV2 && isDefaultMarketplaceCatalog(source)
+      ? capabilities.map(capabilityMarketplaceEntry)
+      : undefined;
+  let marketplace: PluginMarketplace;
+  let catalog: PluginMarketplace;
   try {
-    const marketplace = await loadPluginMarketplace({
+    // Phase 1: render the catalog as soon as it arrives. Version lookups
+    // (GitHub releases/latest round trips) must not gate the first paint.
+    // Keep the raw parsed catalog for phase 2: injecting built-ins first
+    // would mask the matching catalog entries' GitHub sources behind
+    // `capability:<id>` rows, making their versions unresolvable.
+    catalog = await loadPluginMarketplace({
       workDir: host.state.appState.workDir,
       source,
-      builtInEntries:
-        host.engineV2 && isDefaultMarketplaceCatalog(source)
-          ? capabilities.map(capabilityMarketplaceEntry)
-          : undefined,
+      skipLatestVersions: true,
     });
+    marketplace =
+      builtInEntries !== undefined ? withBuiltInEntries(catalog, builtInEntries) : catalog;
     panel.setMarketplace(marketplace.plugins, marketplace.source);
+    host.state.ui.requestRender();
   } catch (error) {
+    // Any phase-1 failure (unreachable OR malformed catalog) surfaces as an
+    // error: the panel keeps built-in capability rows installable in the
+    // Official tab while the error is shown, and a broken catalog must not
+    // be masked as a successfully loaded, built-ins-only marketplace.
     panel.setMarketplaceError(formatErrorMessage(error));
+    host.state.ui.requestRender();
+    return;
+  }
+  try {
+    // Phase 2: resolve latest versions in the background (against the raw
+    // catalog), re-apply the built-in injection so resolved versions flow
+    // onto capability rows, then refresh so update badges appear. Failures
+    // degrade to badge-less rows and never clobber the rendered list.
+    const enrichedCatalog = await withMarketplaceLatestVersions(catalog);
+    const enriched =
+      builtInEntries !== undefined
+        ? withBuiltInEntries(enrichedCatalog, builtInEntries)
+        : enrichedCatalog;
+    panel.setMarketplace(enriched.plugins, enriched.source);
+  } catch (error) {
+    log.warn('marketplace version lookup failed', { error });
   }
   host.state.ui.requestRender();
 }

apps/pythinker-code/src/utils/plugin-marketplace.ts

@@ -16,11 +16,15 @@ import {
   type PluginMarketplaceEntry,
 } from '@pymodel/agent-core-v2/app/plugin/marketplace';
 
-import { PYTHINKER_CODE_PLUGIN_MARKETPLACE_URL_ENV } from '#/constant/app';
+import {
+  PYTHINKER_CODE_PLUGIN_MARKETPLACE_URL_ENV,
+  MARKETPLACE_VERSION_LOOKUP_TIMEOUT_MS,
+} from '#/constant/app';
 
 export {
   computeUpdateStatus,
   PLUGIN_MARKETPLACE_TIERS,
+  withBuiltInEntries,
   type PluginMarketplace,
   type PluginMarketplaceEntry,
   type PluginMarketplaceTier,
@@ -37,6 +41,31 @@ export interface LoadPluginMarketplaceOptions {
    * Undefined means no injection.
    */
   readonly builtInEntries?: readonly PluginMarketplaceEntry[];
+  /**
+   * Skip the per-entry "latest GitHub release" lookups so the catalog can be
+   * rendered as soon as it is parsed; the caller resolves versions in the
+   * background via {@link withMarketplaceLatestVersions} and re-renders.
+   */
+  readonly skipLatestVersions?: boolean;
+}
+
+/**
+ * Second phase of the marketplace load: fill in `version` for entries that
+ * need a GitHub `releases/latest` lookup. Every lookup gets a hard timeout
+ * (MARKETPLACE_VERSION_LOOKUP_TIMEOUT_MS) and per-entry failures degrade to
+ * a missing version (badge-less row), so this never throws for network
+ * reasons and never blocks the first paint.
+ */
+export async function withMarketplaceLatestVersions(
+  marketplace: PluginMarketplace,
+  fetchImpl: typeof fetch = fetch,
+): Promise<PluginMarketplace> {
+  const timedFetch: typeof fetch = (input, init) =>
+    fetchImpl(input, {
+      ...init,
+      signal: AbortSignal.timeout(MARKETPLACE_VERSION_LOOKUP_TIMEOUT_MS),
+    });
+  return withLatestVersions(marketplace, timedFetch);
 }
 
 export async function loadPluginMarketplace(
@@ -63,9 +92,8 @@ export async function loadPluginMarketplace(
     }
     throw error;
   }
-  const marketplace = await withLatestVersions(
-    parsePluginMarketplace(read.raw, read.location),
-    fetchImpl,
-  );
+  const marketplace = options.skipLatestVersions === true
+    ? parsePluginMarketplace(read.raw, read.location)
+    : await withLatestVersions(parsePluginMarketplace(read.raw, read.location), fetchImpl);
   return withBuiltInEntries(marketplace, builtInEntries);
 }

apps/pythinker-code/test/utils/plugin-marketplace.test.ts

@@ -6,7 +6,13 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it, vi } from 'vitest';
 
 import { PYTHINKER_CODE_PLUGIN_MARKETPLACE_URL_ENV } from '#/constant/app';
-import { computeUpdateStatus, loadPluginMarketplace } from '#/utils/plugin-marketplace';
+import {
+  computeUpdateStatus,
+  loadPluginMarketplace,
+  withBuiltInEntries,
+  withMarketplaceLatestVersions,
+  type PluginMarketplaceEntry,
+} from '#/utils/plugin-marketplace';
 
 const REPO_ROOT = join(import.meta.dirname, '../../../..');
 
@@ -575,4 +581,127 @@ describe('loadPluginMarketplace', () => {
     );
   });
 
+  describe('two-phase version lookup', () => {
+    async function writeCatalog(dir: string) {
+      const file = join(dir, 'marketplace.json');
+      await writeFile(
+        file,
+        JSON.stringify({
+          plugins: [
+            { id: 'demo', displayName: 'Demo', source: 'https://github.com/owner/repo' },
+          ],
+        }),
+        'utf8',
+      );
+      return file;
+    }
+
+    it('skipLatestVersions returns the catalog without querying GitHub', async () => {
+      const fetchImpl = vi.fn(async () => {
+        throw new Error('should not be called');
+      }) as unknown as typeof fetch;
+      const dir = await mkdtemp(join(tmpdir(), 'pythinker-plugin-marketplace-'));
+      const file = await writeCatalog(dir);
+
+      const marketplace = await loadPluginMarketplace({
+        workDir: dir,
+        source: file,
+        fetchImpl,
+        skipLatestVersions: true,
+      });
+
+      expect(marketplace.plugins[0]?.version).toBeUndefined();
+      expect(fetchImpl).not.toHaveBeenCalled();
+    });
+
+    it('withMarketplaceLatestVersions fills versions from the latest release redirect', async () => {
+      const fetchImpl = vi.fn(async (input: unknown) => ({
+        ok: false,
+        status: 302,
+        headers: new Headers({
+          location: 'https://github.com/owner/repo/releases/tag/v1.2.3',
+        }),
+        text: async () => '',
+      })) as unknown as typeof fetch;
+      const dir = await mkdtemp(join(tmpdir(), 'pythinker-plugin-marketplace-'));
+      const file = await writeCatalog(dir);
+      const marketplace = await loadPluginMarketplace({
+        workDir: dir,
+        source: file,
+        skipLatestVersions: true,
+      });
+
+      const enriched = await withMarketplaceLatestVersions(marketplace, fetchImpl);
+
+      expect(fetchImpl).toHaveBeenCalledWith(
+        'https://github.com/owner/repo/releases/latest',
+        expect.objectContaining({ redirect: 'manual', signal: expect.any(AbortSignal) }),
+      );
+      expect(enriched.plugins[0]?.version).toBe('1.2.3');
+    });
+
+    it('withMarketplaceLatestVersions degrades to a missing version when the lookup aborts', async () => {
+      const fetchImpl = vi.fn(async (_input: unknown, init?: { signal?: AbortSignal }) => {
+        // Simulate the lookup hitting the timeout: undici rejects with the
+        // signal's reason once the AbortSignal fires.
+        throw init?.signal?.aborted === true
+          ? init.signal.reason
+          : new DOMException('This operation was aborted', 'AbortError');
+      }) as unknown as typeof fetch;
+      const dir = await mkdtemp(join(tmpdir(), 'pythinker-plugin-marketplace-'));
+      const file = await writeCatalog(dir);
+      const marketplace = await loadPluginMarketplace({
+        workDir: dir,
+        source: file,
+        skipLatestVersions: true,
+      });
+
+      const enriched = await withMarketplaceLatestVersions(marketplace, fetchImpl);
+
+      expect(enriched.plugins[0]?.version).toBeUndefined();
+      expect(enriched.plugins[0]?.id).toBe('demo');
+    });
+
+    it('carries a resolved catalog version onto a built-in row injected after enrichment', async () => {
+      // Regression for the resolve-before-inject ordering: enriching the
+      // built-in-masked marketplace cannot see the catalog entry's GitHub
+      // source, so built-in rows would never get update badges.
+      const fetchImpl = vi.fn(async () => ({
+        ok: false,
+        status: 302,
+        headers: new Headers({
+          location: 'https://github.com/owner/repo/releases/tag/v2.0.0',
+        }),
+        text: async () => '',
+      })) as unknown as typeof fetch;
+      const dir = await mkdtemp(join(tmpdir(), 'pythinker-plugin-marketplace-'));
+      const file = join(dir, 'marketplace.json');
+      await writeFile(
+        file,
+        JSON.stringify({
+          plugins: [{ id: 'demo', displayName: 'Demo', source: 'https://github.com/owner/repo' }],
+        }),
+        'utf8',
+      );
+      const catalog = await loadPluginMarketplace({
+        workDir: dir,
+        source: file,
+        skipLatestVersions: true,
+      });
+      const builtIns: readonly PluginMarketplaceEntry[] = [
+        { id: 'demo', displayName: 'Demo Capability', source: 'capability:demo', builtIn: true },
+      ];
+
+      const enriched = withBuiltInEntries(
+        await withMarketplaceLatestVersions(catalog, fetchImpl),
+        builtIns,
+      );
+
+      expect(enriched.plugins).toHaveLength(1);
+      expect(enriched.plugins[0]).toEqual(
+        expect.objectContaining({ id: 'demo', builtIn: true, version: '2.0.0' }),
+      );
+    });
+  });
+
 });