subagent-cli 0.3.0 → 0.3.1

package/src/utils/plugins/mcpbHandler.ts

@@ -1,968 +0,0 @@
-import type {
-  McpbManifest,
-  McpbUserConfigurationOption,
-} from '@anthropic-ai/mcpb'
-import axios from 'axios'
-import { createHash } from 'crypto'
-import { chmod, writeFile } from 'fs/promises'
-import { dirname, join } from 'path'
-import type { McpServerConfig } from '../../services/mcp/types.js'
-import { logForDebugging } from '../debug.js'
-import { parseAndValidateManifestFromBytes } from '../dxt/helpers.js'
-import { parseZipModes, unzipFile } from '../dxt/zip.js'
-import { errorMessage, getErrnoCode, isENOENT, toError } from '../errors.js'
-import { getFsImplementation } from '../fsOperations.js'
-import { logError } from '../log.js'
-import { getSecureStorage } from '../secureStorage/index.js'
-import {
-  getSettings_DEPRECATED,
-  updateSettingsForSource,
-} from '../settings/settings.js'
-import { jsonParse, jsonStringify } from '../slowOperations.js'
-import { getSystemDirectories } from '../systemDirectories.js'
-import { classifyFetchError, logPluginFetch } from './fetchTelemetry.js'
-/**
- * User configuration values for MCPB
- */
-export type UserConfigValues = Record<
-  string,
-  string | number | boolean | string[]
->
-
-/**
- * User configuration schema from DXT manifest
- */
-export type UserConfigSchema = Record<string, McpbUserConfigurationOption>
-
-/**
- * Result of loading an MCPB file (success case)
- */
-export type McpbLoadResult = {
-  manifest: McpbManifest
-  mcpConfig: McpServerConfig
-  extractedPath: string
-  contentHash: string
-}
-
-/**
- * Result when MCPB needs user configuration
- */
-export type McpbNeedsConfigResult = {
-  status: 'needs-config'
-  manifest: McpbManifest
-  extractedPath: string
-  contentHash: string
-  configSchema: UserConfigSchema
-  existingConfig: UserConfigValues
-  validationErrors: string[]
-}
-
-/**
- * Metadata stored for each cached MCPB
- */
-export type McpbCacheMetadata = {
-  source: string
-  contentHash: string
-  extractedPath: string
-  cachedAt: string
-  lastChecked: string
-}
-
-/**
- * Progress callback for download and extraction operations
- */
-export type ProgressCallback = (status: string) => void
-
-/**
- * Check if a source string is an MCPB file reference
- */
-export function isMcpbSource(source: string): boolean {
-  return source.endsWith('.mcpb') || source.endsWith('.dxt')
-}
-
-/**
- * Check if a source is a URL
- */
-function isUrl(source: string): boolean {
-  return source.startsWith('http://') || source.startsWith('https://')
-}
-
-/**
- * Generate content hash for an MCPB file
- */
-function generateContentHash(data: Uint8Array): string {
-  return createHash('sha256').update(data).digest('hex').substring(0, 16)
-}
-
-/**
- * Get cache directory for MCPB files
- */
-function getMcpbCacheDir(pluginPath: string): string {
-  return join(pluginPath, '.mcpb-cache')
-}
-
-/**
- * Get metadata file path for cached MCPB
- */
-function getMetadataPath(cacheDir: string, source: string): string {
-  const sourceHash = createHash('md5')
-    .update(source)
-    .digest('hex')
-    .substring(0, 8)
-  return join(cacheDir, `${sourceHash}.metadata.json`)
-}
-
-/**
- * Compose the secureStorage key for a per-server secret bucket.
- * `pluginSecrets` is a flat map — per-server secrets share it with top-level
- * plugin options (pluginOptionsStorage.ts) using a `${pluginId}/${server}`
- * composite key. `/` can't appear in plugin IDs (`name@marketplace`) or
- * server names (MCP identifier constraints), so it's unambiguous. Keeps the
- * SecureStorageData schema unchanged and the single-keychain-entry size
- * budget (~2KB stdin-safe, see INC-3028) shared across all plugin secrets.
- */
-function serverSecretsKey(pluginId: string, serverName: string): string {
-  return `${pluginId}/${serverName}`
-}
-
-/**
- * Load user configuration for an MCP server, merging non-sensitive values
- * (from settings.json) with sensitive values (from secureStorage keychain).
- * secureStorage wins on collision — schema determines destination so
- * collision shouldn't happen, but if a user hand-edits settings.json we
- * trust the more secure source.
- *
- * Returns null only if NEITHER source has anything — callers skip
- * ${user_config.X} substitution in that case.
- *
- * @param pluginId - Plugin identifier in "plugin@marketplace" format
- * @param serverName - MCP server name from DXT manifest
- */
-export function loadMcpServerUserConfig(
-  pluginId: string,
-  serverName: string,
-): UserConfigValues | null {
-  try {
-    const settings = getSettings_DEPRECATED()
-    const nonSensitive =
-      settings.pluginConfigs?.[pluginId]?.mcpServers?.[serverName]
-
-    const sensitive =
-      getSecureStorage().read()?.pluginSecrets?.[
-        serverSecretsKey(pluginId, serverName)
-      ]
-
-    if (!nonSensitive && !sensitive) {
-      return null
-    }
-
-    logForDebugging(
-      `Loaded user config for ${pluginId}/${serverName} (settings + secureStorage)`,
-    )
-    return { ...nonSensitive, ...sensitive }
-  } catch (error) {
-    const errorObj = toError(error)
-    logError(errorObj)
-    logForDebugging(
-      `Failed to load user config for ${pluginId}/${serverName}: ${error}`,
-      { level: 'error' },
-    )
-    return null
-  }
-}
-
-/**
- * Save user configuration for an MCP server, splitting by `schema[key].sensitive`.
- * Mirrors savePluginOptions (pluginOptionsStorage.ts:90) for top-level options:
- *   - `sensitive: true` → secureStorage (keychain on macOS, .credentials.json 0600 elsewhere)
- *   - everything else   → settings.json pluginConfigs[pluginId].mcpServers[serverName]
- *
- * Without this split, per-channel `sensitive: true` was a false sense of
- * security — the dialog masked the input but the save went to plaintext
- * settings.json anyway. H1 #3617646 (Telegram/Discord bot tokens in
- * world-readable .env) surfaced this as the gap to close.
- *
- * Writes are skipped if nothing in that category is present.
- *
- * @param pluginId - Plugin identifier in "plugin@marketplace" format
- * @param serverName - MCP server name from DXT manifest
- * @param config - User configuration values
- * @param schema - The userConfig schema for this server (manifest.user_config
- *   or channels[].userConfig) — drives the sensitive/non-sensitive split
- */
-export function saveMcpServerUserConfig(
-  pluginId: string,
-  serverName: string,
-  config: UserConfigValues,
-  schema: UserConfigSchema,
-): void {
-  try {
-    const nonSensitive: UserConfigValues = {}
-    const sensitive: Record<string, string> = {}
-
-    for (const [key, value] of Object.entries(config)) {
-      if (schema[key]?.sensitive === true) {
-        sensitive[key] = String(value)
-      } else {
-        nonSensitive[key] = value
-      }
-    }
-
-    // Scrub ONLY keys we're writing in this call. Covers both directions
-    // across schema-version flips:
-    //  - sensitive→secureStorage ⇒ remove stale plaintext from settings.json
-    //  - nonSensitive→settings.json ⇒ remove stale entry from secureStorage
-    //    (otherwise loadMcpServerUserConfig's {...nonSensitive, ...sensitive}
-    //    would let the stale secureStorage value win on next read)
-    // Partial `config` (user only re-enters one field) leaves other fields
-    // untouched in BOTH stores — defense-in-depth against future callers.
-    const sensitiveKeysInThisSave = new Set(Object.keys(sensitive))
-    const nonSensitiveKeysInThisSave = new Set(Object.keys(nonSensitive))
-
-    // Sensitive → secureStorage FIRST. If this fails (keychain locked,
-    // .credentials.json perms), throw before touching settings.json — the
-    // old plaintext stays as a fallback instead of losing BOTH copies.
-    //
-    // Also scrub non-sensitive keys from secureStorage — schema flipped
-    // sensitive→false and they're being written to settings.json now. Without
-    // this, loadMcpServerUserConfig's merge would let the stale secureStorage
-    // value win on next read.
-    const storage = getSecureStorage()
-    const k = serverSecretsKey(pluginId, serverName)
-    const existingInSecureStorage =
-      storage.read()?.pluginSecrets?.[k] ?? undefined
-    const secureScrubbed = existingInSecureStorage
-      ? Object.fromEntries(
-          Object.entries(existingInSecureStorage).filter(
-            ([key]) => !nonSensitiveKeysInThisSave.has(key),
-          ),
-        )
-      : undefined
-    const needSecureScrub =
-      secureScrubbed &&
-      existingInSecureStorage &&
-      Object.keys(secureScrubbed).length !==
-        Object.keys(existingInSecureStorage).length
-    if (Object.keys(sensitive).length > 0 || needSecureScrub) {
-      const existing = storage.read() ?? {}
-      if (!existing.pluginSecrets) {
-        existing.pluginSecrets = {}
-      }
-      // secureStorage keyvault is a flat object — direct replace, no merge
-      // semantics to worry about (unlike settings.json's mergeWith).
-      existing.pluginSecrets[k] = {
-        ...secureScrubbed,
-        ...sensitive,
-      }
-      const result = storage.update(existing)
-      if (!result.success) {
-        throw new Error(
-          `Failed to save sensitive config to secure storage for ${k}`,
-        )
-      }
-      if (result.warning) {
-        logForDebugging(`Server secrets save warning: ${result.warning}`, {
-          level: 'warn',
-        })
-      }
-      if (needSecureScrub) {
-        logForDebugging(
-          `saveMcpServerUserConfig: scrubbed ${
-            Object.keys(existingInSecureStorage!).length -
-            Object.keys(secureScrubbed!).length
-          } stale non-sensitive key(s) from secureStorage for ${k}`,
-        )
-      }
-    }
-
-    // Non-sensitive → settings.json. Write whenever there are new non-sensitive
-    // values OR existing plaintext sensitive values to scrub — so reconfiguring
-    // a sensitive-only schema still cleans up the old settings.json. Runs
-    // AFTER the secureStorage write succeeded, so the scrub can't leave you
-    // with zero copies of the secret.
-    //
-    // updateSettingsForSource does mergeWith(diskSettings, ourSettings, ...)
-    // which PRESERVES destination keys absent from source — so simply omitting
-    // sensitive keys doesn't scrub them, the disk copy merges back in. Instead:
-    // set each sensitive key to explicit `undefined` — mergeWith (with the
-    // customizer at settings.ts:349) treats explicit undefined as a delete.
-    const settings = getSettings_DEPRECATED()
-    const existingInSettings =
-      settings.pluginConfigs?.[pluginId]?.mcpServers?.[serverName] ?? {}
-    const keysToScrubFromSettings = Object.keys(existingInSettings).filter(k =>
-      sensitiveKeysInThisSave.has(k),
-    )
-    if (
-      Object.keys(nonSensitive).length > 0 ||
-      keysToScrubFromSettings.length > 0
-    ) {
-      if (!settings.pluginConfigs) {
-        settings.pluginConfigs = {}
-      }
-      if (!settings.pluginConfigs[pluginId]) {
-        settings.pluginConfigs[pluginId] = {}
-      }
-      if (!settings.pluginConfigs[pluginId].mcpServers) {
-        settings.pluginConfigs[pluginId].mcpServers = {}
-      }
-      // Build the scrub-via-undefined map. The UserConfigValues type doesn't
-      // include undefined, but updateSettingsForSource's mergeWith customizer
-      // needs explicit undefined to delete — cast is deliberate internal
-      // plumbing (same rationale as deletePluginOptions in
-      // pluginOptionsStorage.ts:184, see CLAUDE.md's 10% case).
-      const scrubbed = Object.fromEntries(
-        keysToScrubFromSettings.map(k => [k, undefined]),
-      ) as Record<string, undefined>
-      settings.pluginConfigs[pluginId].mcpServers![serverName] = {
-        ...nonSensitive,
-        ...scrubbed,
-      } as UserConfigValues
-      const result = updateSettingsForSource('userSettings', settings)
-      if (result.error) {
-        throw result.error
-      }
-      if (keysToScrubFromSettings.length > 0) {
-        logForDebugging(
-          `saveMcpServerUserConfig: scrubbed ${keysToScrubFromSettings.length} plaintext sensitive key(s) from settings.json for ${pluginId}/${serverName}`,
-        )
-      }
-    }
-
-    logForDebugging(
-      `Saved user config for ${pluginId}/${serverName} (${Object.keys(nonSensitive).length} non-sensitive, ${Object.keys(sensitive).length} sensitive)`,
-    )
-  } catch (error) {
-    const errorObj = toError(error)
-    logError(errorObj)
-    throw new Error(
-      `Failed to save user configuration for ${pluginId}/${serverName}: ${errorObj.message}`,
-    )
-  }
-}
-
-/**
- * Validate user configuration values against DXT user_config schema
- */
-export function validateUserConfig(
-  values: UserConfigValues,
-  schema: UserConfigSchema,
-): { valid: boolean; errors: string[] } {
-  const errors: string[] = []
-
-  // Check each field in the schema
-  for (const [key, fieldSchema] of Object.entries(schema)) {
-    const value = values[key]
-
-    // Check required fields
-    if (fieldSchema.required && (value === undefined || value === '')) {
-      errors.push(`${fieldSchema.title || key} is required but not provided`)
-      continue
-    }
-
-    // Skip validation for optional fields that aren't provided
-    if (value === undefined || value === '') {
-      continue
-    }
-
-    // Type validation
-    if (fieldSchema.type === 'string') {
-      if (Array.isArray(value)) {
-        // String arrays are allowed if multiple: true
-        if (!fieldSchema.multiple) {
-          errors.push(
-            `${fieldSchema.title || key} must be a string, not an array`,
-          )
-        } else if (!value.every(v => typeof v === 'string')) {
-          errors.push(`${fieldSchema.title || key} must be an array of strings`)
-        }
-      } else if (typeof value !== 'string') {
-        errors.push(`${fieldSchema.title || key} must be a string`)
-      }
-    } else if (fieldSchema.type === 'number' && typeof value !== 'number') {
-      errors.push(`${fieldSchema.title || key} must be a number`)
-    } else if (fieldSchema.type === 'boolean' && typeof value !== 'boolean') {
-      errors.push(`${fieldSchema.title || key} must be a boolean`)
-    } else if (
-      (fieldSchema.type === 'file' || fieldSchema.type === 'directory') &&
-      typeof value !== 'string'
-    ) {
-      errors.push(`${fieldSchema.title || key} must be a path string`)
-    }
-
-    // Number range validation
-    if (fieldSchema.type === 'number' && typeof value === 'number') {
-      if (fieldSchema.min !== undefined && value < fieldSchema.min) {
-        errors.push(
-          `${fieldSchema.title || key} must be at least ${fieldSchema.min}`,
-        )
-      }
-      if (fieldSchema.max !== undefined && value > fieldSchema.max) {
-        errors.push(
-          `${fieldSchema.title || key} must be at most ${fieldSchema.max}`,
-        )
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors }
-}
-
-/**
- * Generate MCP server configuration from DXT manifest
- */
-async function generateMcpConfig(
-  manifest: McpbManifest,
-  extractedPath: string,
-  userConfig: UserConfigValues = {},
-): Promise<McpServerConfig> {
-  // Lazy import: @anthropic-ai/mcpb barrel pulls in zod v3 schemas (~700KB of
-  // bound closures). See dxt/helpers.ts for details.
-  const { getMcpConfigForManifest } = await import('@anthropic-ai/mcpb')
-  const mcpConfig = await getMcpConfigForManifest({
-    manifest,
-    extensionPath: extractedPath,
-    systemDirs: getSystemDirectories(),
-    userConfig,
-    pathSeparator: '/',
-  })
-
-  if (!mcpConfig) {
-    const error = new Error(
-      `Failed to generate MCP server configuration from manifest "${manifest.name}"`,
-    )
-    logError(error)
-    throw error
-  }
-
-  return mcpConfig as McpServerConfig
-}
-
-/**
- * Load cache metadata for an MCPB source
- */
-async function loadCacheMetadata(
-  cacheDir: string,
-  source: string,
-): Promise<McpbCacheMetadata | null> {
-  const fs = getFsImplementation()
-  const metadataPath = getMetadataPath(cacheDir, source)
-
-  try {
-    const content = await fs.readFile(metadataPath, { encoding: 'utf-8' })
-    return jsonParse(content) as McpbCacheMetadata
-  } catch (error) {
-    const code = getErrnoCode(error)
-    if (code === 'ENOENT') return null
-    const errorObj = toError(error)
-    logError(errorObj)
-    logForDebugging(`Failed to load MCPB cache metadata: ${error}`, {
-      level: 'error',
-    })
-    return null
-  }
-}
-
-/**
- * Save cache metadata for an MCPB source
- */
-async function saveCacheMetadata(
-  cacheDir: string,
-  source: string,
-  metadata: McpbCacheMetadata,
-): Promise<void> {
-  const metadataPath = getMetadataPath(cacheDir, source)
-
-  await getFsImplementation().mkdir(cacheDir)
-  await writeFile(metadataPath, jsonStringify(metadata, null, 2), 'utf-8')
-}
-
-/**
- * Download MCPB file from URL
- */
-async function downloadMcpb(
-  url: string,
-  destPath: string,
-  onProgress?: ProgressCallback,
-): Promise<Uint8Array> {
-  logForDebugging(`Downloading MCPB from ${url}`)
-  if (onProgress) {
-    onProgress(`Downloading ${url}...`)
-  }
-
-  const started = performance.now()
-  let fetchTelemetryFired = false
-  try {
-    const response = await axios.get(url, {
-      timeout: 120000, // 2 minute timeout
-      responseType: 'arraybuffer',
-      maxRedirects: 5, // Follow redirects (like curl -L)
-      onDownloadProgress: progressEvent => {
-        if (progressEvent.total && onProgress) {
-          const percent = Math.round(
-            (progressEvent.loaded / progressEvent.total) * 100,
-          )
-          onProgress(`Downloading... ${percent}%`)
-        }
-      },
-    })
-
-    const data = new Uint8Array(response.data)
-    // Fire telemetry before writeFile — the event measures the network
-    // fetch, not disk I/O. A writeFile EACCES would otherwise match
-    // classifyFetchError's /permission denied/ → misreport as auth.
-    logPluginFetch('mcpb', url, 'success', performance.now() - started)
-    fetchTelemetryFired = true
-
-    // Save to disk (binary data)
-    await writeFile(destPath, Buffer.from(data))
-
-    logForDebugging(`Downloaded ${data.length} bytes to ${destPath}`)
-    if (onProgress) {
-      onProgress('Download complete')
-    }
-
-    return data
-  } catch (error) {
-    if (!fetchTelemetryFired) {
-      logPluginFetch(
-        'mcpb',
-        url,
-        'failure',
-        performance.now() - started,
-        classifyFetchError(error),
-      )
-    }
-    const errorMsg = errorMessage(error)
-    const fullError = new Error(
-      `Failed to download MCPB file from ${url}: ${errorMsg}`,
-    )
-    logError(fullError)
-    throw fullError
-  }
-}
-
-/**
- * Extract MCPB file and write contents to extraction directory.
- *
- * @param modes - name→mode map from `parseZipModes`. MCPB bundles can ship
- *   native MCP server binaries, so preserving the exec bit matters here.
- */
-async function extractMcpbContents(
-  unzipped: Record<string, Uint8Array>,
-  extractPath: string,
-  modes: Record<string, number>,
-  onProgress?: ProgressCallback,
-): Promise<void> {
-  if (onProgress) {
-    onProgress('Extracting files...')
-  }
-
-  // Create extraction directory
-  await getFsImplementation().mkdir(extractPath)
-
-  // Write all files. Filter directory entries from the count so progress
-  // messages use the same denominator as filesWritten (which skips them).
-  let filesWritten = 0
-  const entries = Object.entries(unzipped).filter(([k]) => !k.endsWith('/'))
-  const totalFiles = entries.length
-
-  for (const [filePath, fileData] of entries) {
-    // Directory entries (common in zip -r, Python zipfile, Java ZipOutputStream)
-    // are filtered above — writeFile would create `bin/` as an empty regular
-    // file, then mkdir for `bin/server` would fail with ENOTDIR. The
-    // mkdir(dirname(fullPath)) below creates parent dirs implicitly.
-
-    const fullPath = join(extractPath, filePath)
-    const dir = dirname(fullPath)
-
-    // Ensure directory exists (recursive handles already-existing)
-    if (dir !== extractPath) {
-      await getFsImplementation().mkdir(dir)
-    }
-
-    // Determine if text or binary
-    const isTextFile =
-      filePath.endsWith('.json') ||
-      filePath.endsWith('.js') ||
-      filePath.endsWith('.ts') ||
-      filePath.endsWith('.txt') ||
-      filePath.endsWith('.md') ||
-      filePath.endsWith('.yml') ||
-      filePath.endsWith('.yaml')
-
-    if (isTextFile) {
-      const content = new TextDecoder().decode(fileData)
-      await writeFile(fullPath, content, 'utf-8')
-    } else {
-      await writeFile(fullPath, Buffer.from(fileData))
-    }
-
-    const mode = modes[filePath]
-    if (mode && mode & 0o111) {
-      // Swallow EPERM/ENOTSUP (NFS root_squash, some FUSE mounts) — losing +x
-      // is the pre-PR behavior and better than aborting mid-extraction.
-      await chmod(fullPath, mode & 0o777).catch(() => {})
-    }
-
-    filesWritten++
-    if (onProgress && filesWritten % 10 === 0) {
-      onProgress(`Extracted ${filesWritten}/${totalFiles} files`)
-    }
-  }
-
-  logForDebugging(`Extracted ${filesWritten} files to ${extractPath}`)
-  if (onProgress) {
-    onProgress(`Extraction complete (${filesWritten} files)`)
-  }
-}
-
-/**
- * Check if an MCPB source has changed and needs re-extraction
- */
-export async function checkMcpbChanged(
-  source: string,
-  pluginPath: string,
-): Promise<boolean> {
-  const fs = getFsImplementation()
-  const cacheDir = getMcpbCacheDir(pluginPath)
-  const metadata = await loadCacheMetadata(cacheDir, source)
-
-  if (!metadata) {
-    // No cache metadata, needs loading
-    return true
-  }
-
-  // Check if extraction directory still exists
-  try {
-    await fs.stat(metadata.extractedPath)
-  } catch (error) {
-    const code = getErrnoCode(error)
-    if (code === 'ENOENT') {
-      logForDebugging(`MCPB extraction path missing: ${metadata.extractedPath}`)
-    } else {
-      logForDebugging(
-        `MCPB extraction path inaccessible: ${metadata.extractedPath}: ${error}`,
-        { level: 'error' },
-      )
-    }
-    return true
-  }
-
-  // For local files, check mtime
-  if (!isUrl(source)) {
-    const localPath = join(pluginPath, source)
-    let stats
-    try {
-      stats = await fs.stat(localPath)
-    } catch (error) {
-      const code = getErrnoCode(error)
-      if (code === 'ENOENT') {
-        logForDebugging(`MCPB source file missing: ${localPath}`)
-      } else {
-        logForDebugging(
-          `MCPB source file inaccessible: ${localPath}: ${error}`,
-          { level: 'error' },
-        )
-      }
-      return true
-    }
-
-    const cachedTime = new Date(metadata.cachedAt).getTime()
-    // Floor to match the ms precision of cachedAt (ISO string). Sub-ms
-    // precision on mtimeMs would make a freshly-cached file appear "newer"
-    // than its own cache timestamp when both happen in the same millisecond.
-    const fileTime = Math.floor(stats.mtimeMs)
-
-    if (fileTime > cachedTime) {
-      logForDebugging(
-        `MCPB file modified: ${new Date(fileTime)} > ${new Date(cachedTime)}`,
-      )
-      return true
-    }
-  }
-
-  // For URLs, we'll re-check on explicit update (handled elsewhere)
-  return false
-}
-
-/**
- * Load and extract an MCPB file, with caching and user configuration support
- *
- * @param source - MCPB file path or URL
- * @param pluginPath - Plugin directory path
- * @param pluginId - Plugin identifier in "plugin@marketplace" format (for config storage)
- * @param onProgress - Progress callback
- * @param providedUserConfig - User configuration values (for initial setup or reconfiguration)
- * @returns Success with MCP config, or needs-config status with schema
- */
-export async function loadMcpbFile(
-  source: string,
-  pluginPath: string,
-  pluginId: string,
-  onProgress?: ProgressCallback,
-  providedUserConfig?: UserConfigValues,
-  forceConfigDialog?: boolean,
-): Promise<McpbLoadResult | McpbNeedsConfigResult> {
-  const fs = getFsImplementation()
-  const cacheDir = getMcpbCacheDir(pluginPath)
-  await fs.mkdir(cacheDir)
-
-  logForDebugging(`Loading MCPB from source: ${source}`)
-
-  // Check cache first
-  const metadata = await loadCacheMetadata(cacheDir, source)
-  if (metadata && !(await checkMcpbChanged(source, pluginPath))) {
-    logForDebugging(
-      `Using cached MCPB from ${metadata.extractedPath} (hash: ${metadata.contentHash})`,
-    )
-
-    // Load manifest from cache
-    const manifestPath = join(metadata.extractedPath, 'manifest.json')
-    let manifestContent: string
-    try {
-      manifestContent = await fs.readFile(manifestPath, { encoding: 'utf-8' })
-    } catch (error) {
-      if (isENOENT(error)) {
-        const err = new Error(`Cached manifest not found: ${manifestPath}`)
-        logError(err)
-        throw err
-      }
-      throw error
-    }
-
-    const manifestData = new TextEncoder().encode(manifestContent)
-    const manifest = await parseAndValidateManifestFromBytes(manifestData)
-
-    // Check for user_config requirement
-    if (manifest.user_config && Object.keys(manifest.user_config).length > 0) {
-      // Server name from DXT manifest
-      const serverName = manifest.name
-
-      // Try to load existing config from settings.json or use provided config
-      const savedConfig = loadMcpServerUserConfig(pluginId, serverName)
-      const userConfig = providedUserConfig || savedConfig || {}
-
-      // Validate we have all required fields
-      const validation = validateUserConfig(userConfig, manifest.user_config)
-
-      // Return needs-config if: forced (reconfiguration) OR validation failed
-      if (forceConfigDialog || !validation.valid) {
-        return {
-          status: 'needs-config',
-          manifest,
-          extractedPath: metadata.extractedPath,
-          contentHash: metadata.contentHash,
-          configSchema: manifest.user_config,
-          existingConfig: savedConfig || {},
-          validationErrors: validation.valid ? [] : validation.errors,
-        }
-      }
-
-      // Save config if it was provided (first time or reconfiguration)
-      if (providedUserConfig) {
-        saveMcpServerUserConfig(
-          pluginId,
-          serverName,
-          providedUserConfig,
-          manifest.user_config ?? {},
-        )
-      }
-
-      // Generate MCP config WITH user config
-      const mcpConfig = await generateMcpConfig(
-        manifest,
-        metadata.extractedPath,
-        userConfig,
-      )
-
-      return {
-        manifest,
-        mcpConfig,
-        extractedPath: metadata.extractedPath,
-        contentHash: metadata.contentHash,
-      }
-    }
-
-    // No user_config required - generate config without it
-    const mcpConfig = await generateMcpConfig(manifest, metadata.extractedPath)
-
-    return {
-      manifest,
-      mcpConfig,
-      extractedPath: metadata.extractedPath,
-      contentHash: metadata.contentHash,
-    }
-  }
-
-  // Not cached or changed - need to download/load and extract
-  let mcpbData: Uint8Array
-  let mcpbFilePath: string
-
-  if (isUrl(source)) {
-    // Download from URL
-    const sourceHash = createHash('md5')
-      .update(source)
-      .digest('hex')
-      .substring(0, 8)
-    mcpbFilePath = join(cacheDir, `${sourceHash}.mcpb`)
-    mcpbData = await downloadMcpb(source, mcpbFilePath, onProgress)
-  } else {
-    // Load from local path
-    const localPath = join(pluginPath, source)
-
-    if (onProgress) {
-      onProgress(`Loading ${source}...`)
-    }
-
-    try {
-      mcpbData = await fs.readFileBytes(localPath)
-      mcpbFilePath = localPath
-    } catch (error) {
-      if (isENOENT(error)) {
-        const err = new Error(`MCPB file not found: ${localPath}`)
-        logError(err)
-        throw err
-      }
-      throw error
-    }
-  }
-
-  // Generate content hash
-  const contentHash = generateContentHash(mcpbData)
-  logForDebugging(`MCPB content hash: ${contentHash}`)
-
-  // Extract ZIP
-  if (onProgress) {
-    onProgress('Extracting MCPB archive...')
-  }
-
-  const unzipped = await unzipFile(Buffer.from(mcpbData))
-  // fflate doesn't surface external_attr — parse the central directory so
-  // native MCP server binaries keep their exec bit after extraction.
-  const modes = parseZipModes(mcpbData)
-
-  // Check for manifest.json
-  const manifestData = unzipped['manifest.json']
-  if (!manifestData) {
-    const error = new Error('No manifest.json found in MCPB file')
-    logError(error)
-    throw error
-  }
-
-  // Parse and validate manifest
-  const manifest = await parseAndValidateManifestFromBytes(manifestData)
-  logForDebugging(
-    `MCPB manifest: ${manifest.name} v${manifest.version} by ${manifest.author.name}`,
-  )
-
-  // Check if manifest has server config
-  if (!manifest.server) {
-    const error = new Error(
-      `MCPB manifest for "${manifest.name}" does not define a server configuration`,
-    )
-    logError(error)
-    throw error
-  }
-
-  // Extract to cache directory
-  const extractPath = join(cacheDir, contentHash)
-  await extractMcpbContents(unzipped, extractPath, modes, onProgress)
-
-  // Check for user_config requirement
-  if (manifest.user_config && Object.keys(manifest.user_config).length > 0) {
-    // Server name from DXT manifest
-    const serverName = manifest.name
-
-    // Try to load existing config from settings.json or use provided config
-    const savedConfig = loadMcpServerUserConfig(pluginId, serverName)
-    const userConfig = providedUserConfig || savedConfig || {}
-
-    // Validate we have all required fields
-    const validation = validateUserConfig(userConfig, manifest.user_config)
-
-    if (!validation.valid) {
-      // Save cache metadata even though config is incomplete
-      const newMetadata: McpbCacheMetadata = {
-        source,
-        contentHash,
-        extractedPath: extractPath,
-        cachedAt: new Date().toISOString(),
-        lastChecked: new Date().toISOString(),
-      }
-      await saveCacheMetadata(cacheDir, source, newMetadata)
-
-      // Return "needs configuration" status
-      return {
-        status: 'needs-config',
-        manifest,
-        extractedPath: extractPath,
-        contentHash,
-        configSchema: manifest.user_config,
-        existingConfig: savedConfig || {},
-        validationErrors: validation.errors,
-      }
-    }
-
-    // Save config if it was provided (first time or reconfiguration)
-    if (providedUserConfig) {
-      saveMcpServerUserConfig(
-        pluginId,
-        serverName,
-        providedUserConfig,
-        manifest.user_config ?? {},
-      )
-    }
-
-    // Generate MCP config WITH user config
-    if (onProgress) {
-      onProgress('Generating MCP server configuration...')
-    }
-
-    const mcpConfig = await generateMcpConfig(manifest, extractPath, userConfig)
-
-    // Save cache metadata
-    const newMetadata: McpbCacheMetadata = {
-      source,
-      contentHash,
-      extractedPath: extractPath,
-      cachedAt: new Date().toISOString(),
-      lastChecked: new Date().toISOString(),
-    }
-    await saveCacheMetadata(cacheDir, source, newMetadata)
-
-    return {
-      manifest,
-      mcpConfig,
-      extractedPath: extractPath,
-      contentHash,
-    }
-  }
-
-  // No user_config required - generate config without it
-  if (onProgress) {
-    onProgress('Generating MCP server configuration...')
-  }
-
-  const mcpConfig = await generateMcpConfig(manifest, extractPath)
-
-  // Save cache metadata
-  const newMetadata: McpbCacheMetadata = {
-    source,
-    contentHash,
-    extractedPath: extractPath,
-    cachedAt: new Date().toISOString(),
-    lastChecked: new Date().toISOString(),
-  }
-  await saveCacheMetadata(cacheDir, source, newMetadata)
-
-  logForDebugging(
-    `Successfully loaded MCPB: ${manifest.name} (extracted to ${extractPath})`,
-  )
-
-  return {
-    manifest,
-    mcpConfig: mcpConfig as McpServerConfig,
-    extractedPath: extractPath,
-    contentHash,
-  }
-}