@xortex/xcode 3.0.0

package/utils/plugins/reconciler.ts

@@ -0,0 +1,265 @@
+/**
+ * Marketplace reconciler — makes known_marketplaces.json consistent with
+ * declared intent in settings.
+ *
+ * Two layers:
+ * - diffMarketplaces(): comparison (reads .git for worktree canonicalization, memoized)
+ * - reconcileMarketplaces(): bundled diff + install (I/O, idempotent, additive)
+ */
+
+import isEqual from 'lodash-es/isEqual.js'
+import { isAbsolute, resolve } from 'path'
+import { getOriginalCwd } from '../../bootstrap/state.js'
+import { logForDebugging } from '../debug.js'
+import { errorMessage } from '../errors.js'
+import { pathExists } from '../file.js'
+import { findCanonicalGitRoot } from '../git.js'
+import { logError } from '../log.js'
+import {
+  addMarketplaceSource,
+  type DeclaredMarketplace,
+  getDeclaredMarketplaces,
+  loadKnownMarketplacesConfig,
+} from './marketplaceManager.js'
+import {
+  isLocalMarketplaceSource,
+  type KnownMarketplacesFile,
+  type MarketplaceSource,
+} from './schemas.js'
+
+export type MarketplaceDiff = {
+  /** Declared in settings, absent from known_marketplaces.json */
+  missing: string[]
+  /** Present in both, but settings source ≠ JSON source (settings wins) */
+  sourceChanged: Array<{
+    name: string
+    declaredSource: MarketplaceSource
+    materializedSource: MarketplaceSource
+  }>
+  /** Present in both, sources match */
+  upToDate: string[]
+}
+
+/**
+ * Compare declared intent (settings) against materialized state (JSON).
+ *
+ * Resolves relative directory/file paths in `declared` before comparing,
+ * so project settings with `./path` match JSON's absolute path. Path
+ * resolution reads `.git` to canonicalize worktree paths (memoized).
+ */
+export function diffMarketplaces(
+  declared: Record<string, DeclaredMarketplace>,
+  materialized: KnownMarketplacesFile,
+  opts?: { projectRoot?: string },
+): MarketplaceDiff {
+  const missing: string[] = []
+  const sourceChanged: MarketplaceDiff['sourceChanged'] = []
+  const upToDate: string[] = []
+
+  for (const [name, intent] of Object.entries(declared)) {
+    const state = materialized[name]
+    const normalizedIntent = normalizeSource(intent.source, opts?.projectRoot)
+
+    if (!state) {
+      missing.push(name)
+    } else if (intent.sourceIsFallback) {
+      // Fallback: presence suffices. Don't compare sources — the declared source
+      // is only a default for the `missing` branch. If seed/prior-install/mirror
+      // materialized this marketplace under ANY source, leave it alone. Comparing
+      // would report sourceChanged → re-clone → stomp the materialized content.
+      upToDate.push(name)
+    } else if (!isEqual(normalizedIntent, state.source)) {
+      sourceChanged.push({
+        name,
+        declaredSource: normalizedIntent,
+        materializedSource: state.source,
+      })
+    } else {
+      upToDate.push(name)
+    }
+  }
+
+  return { missing, sourceChanged, upToDate }
+}
+
+export type ReconcileOptions = {
+  /** Skip a declared marketplace. Used by zip-cache mode for unsupported source types. */
+  skip?: (name: string, source: MarketplaceSource) => boolean
+  onProgress?: (event: ReconcileProgressEvent) => void
+}
+
+export type ReconcileProgressEvent =
+  | {
+      type: 'installing'
+      name: string
+      action: 'install' | 'update'
+      index: number
+      total: number
+    }
+  | { type: 'installed'; name: string; alreadyMaterialized: boolean }
+  | { type: 'failed'; name: string; error: string }
+
+export type ReconcileResult = {
+  installed: string[]
+  updated: string[]
+  failed: Array<{ name: string; error: string }>
+  upToDate: string[]
+  skipped: string[]
+}
+
+/**
+ * Make known_marketplaces.json consistent with declared intent.
+ * Idempotent. Additive only (never deletes). Does not touch AppState.
+ */
+export async function reconcileMarketplaces(
+  opts?: ReconcileOptions,
+): Promise<ReconcileResult> {
+  const declared = getDeclaredMarketplaces()
+  if (Object.keys(declared).length === 0) {
+    return { installed: [], updated: [], failed: [], upToDate: [], skipped: [] }
+  }
+
+  let materialized: KnownMarketplacesFile
+  try {
+    materialized = await loadKnownMarketplacesConfig()
+  } catch (e) {
+    logError(e)
+    materialized = {}
+  }
+
+  const diff = diffMarketplaces(declared, materialized, {
+    projectRoot: getOriginalCwd(),
+  })
+
+  type WorkItem = {
+    name: string
+    source: MarketplaceSource
+    action: 'install' | 'update'
+  }
+  const work: WorkItem[] = [
+    ...diff.missing.map(
+      (name): WorkItem => ({
+        name,
+        source: normalizeSource(declared[name]!.source),
+        action: 'install',
+      }),
+    ),
+    ...diff.sourceChanged.map(
+      ({ name, declaredSource }): WorkItem => ({
+        name,
+        source: declaredSource,
+        action: 'update',
+      }),
+    ),
+  ]
+
+  const skipped: string[] = []
+  const toProcess: WorkItem[] = []
+  for (const item of work) {
+    if (opts?.skip?.(item.name, item.source)) {
+      skipped.push(item.name)
+      continue
+    }
+    // For sourceChanged local-path entries, skip if the declared path doesn't
+    // exist. Guards multi-checkout scenarios where normalizeSource can't
+    // canonicalize and produces a dead path — the materialized entry may still
+    // be valid; addMarketplaceSource would fail anyway, so skipping avoids a
+    // noisy "failed" event and preserves the working entry. Missing entries
+    // are NOT skipped (nothing to preserve; the user should see the error).
+    if (
+      item.action === 'update' &&
+      isLocalMarketplaceSource(item.source) &&
+      !(await pathExists(item.source.path))
+    ) {
+      logForDebugging(
+        `[reconcile] '${item.name}' declared path does not exist; keeping materialized entry`,
+      )
+      skipped.push(item.name)
+      continue
+    }
+    toProcess.push(item)
+  }
+
+  if (toProcess.length === 0) {
+    return {
+      installed: [],
+      updated: [],
+      failed: [],
+      upToDate: diff.upToDate,
+      skipped,
+    }
+  }
+
+  logForDebugging(
+    `[reconcile] ${toProcess.length} marketplace(s): ${toProcess.map(w => `${w.name}(${w.action})`).join(', ')}`,
+  )
+
+  const installed: string[] = []
+  const updated: string[] = []
+  const failed: ReconcileResult['failed'] = []
+
+  for (let i = 0; i < toProcess.length; i++) {
+    const { name, source, action } = toProcess[i]!
+    opts?.onProgress?.({
+      type: 'installing',
+      name,
+      action,
+      index: i + 1,
+      total: toProcess.length,
+    })
+
+    try {
+      // addMarketplaceSource is source-idempotent — same source returns
+      // alreadyMaterialized:true without cloning. For 'update' (source
+      // changed), the new source won't match existing → proceeds with clone
+      // and overwrites the old JSON entry.
+      const result = await addMarketplaceSource(source)
+
+      if (action === 'install') installed.push(name)
+      else updated.push(name)
+      opts?.onProgress?.({
+        type: 'installed',
+        name,
+        alreadyMaterialized: result.alreadyMaterialized,
+      })
+    } catch (e) {
+      const error = errorMessage(e)
+      failed.push({ name, error })
+      opts?.onProgress?.({ type: 'failed', name, error })
+      logError(e)
+    }
+  }
+
+  return { installed, updated, failed, upToDate: diff.upToDate, skipped }
+}
+
+/**
+ * Resolve relative directory/file paths for stable comparison.
+ * Settings declared at project scope may use project-relative paths;
+ * JSON stores absolute paths.
+ *
+ * For git worktrees, resolve against the main checkout (canonical root)
+ * instead of the worktree cwd. Project settings are checked into git,
+ * so `./foo` means "relative to this repo" — but known_marketplaces.json is
+ * user-global with one entry per marketplace name. Resolving against the
+ * worktree cwd means each worktree session overwrites the shared entry with
+ * its own absolute path, and deleting the worktree leaves a dead
+ * installLocation. The canonical root is stable across all worktrees.
+ */
+function normalizeSource(
+  source: MarketplaceSource,
+  projectRoot?: string,
+): MarketplaceSource {
+  if (
+    (source.source === 'directory' || source.source === 'file') &&
+    !isAbsolute(source.path)
+  ) {
+    const base = projectRoot ?? getOriginalCwd()
+    const canonicalRoot = findCanonicalGitRoot(base)
+    return {
+      ...source,
+      path: resolve(canonicalRoot ?? base, source.path),
+    }
+  }
+  return source
+}

package/utils/plugins/refresh.ts

@@ -0,0 +1,215 @@
+/**
+ * Layer-3 refresh primitive: swap active plugin components in the running session.
+ *
+ * Three-layer model (see reconciler.ts for Layer-2):
+ * - Layer 1: intent (settings)
+ * - Layer 2: materialization (~/.claude/plugins/) — reconcileMarketplaces()
+ * - Layer 3: active components (AppState) — this file
+ *
+ * Called from:
+ * - /reload-plugins command (interactive, user-initiated)
+ * - print.ts refreshPluginState() (headless, auto before first query with SYNC_PLUGIN_INSTALL)
+ * - performBackgroundPluginInstallations() (background, auto after new marketplace install)
+ *
+ * NOT called from:
+ * - useManagePlugins needsRefresh effect — interactive mode shows a notification;
+ *   user explicitly runs /reload-plugins (PR 5c)
+ * - /plugin menu — sets needsRefresh, user runs /reload-plugins (PR 5b)
+ */
+
+import { getOriginalCwd } from '../../bootstrap/state.js'
+import type { Command } from '../../commands.js'
+import { reinitializeLspServerManager } from '../../services/lsp/manager.js'
+import type { AppState } from '../../state/AppState.js'
+import type { AgentDefinitionsResult } from '../../tools/AgentTool/loadAgentsDir.js'
+import { getAgentDefinitionsWithOverrides } from '../../tools/AgentTool/loadAgentsDir.js'
+import type { PluginError } from '../../types/plugin.js'
+import { logForDebugging } from '../debug.js'
+import { errorMessage } from '../errors.js'
+import { logError } from '../log.js'
+import { clearAllCaches } from './cacheUtils.js'
+import { getPluginCommands } from './loadPluginCommands.js'
+import { loadPluginHooks } from './loadPluginHooks.js'
+import { loadPluginLspServers } from './lspPluginIntegration.js'
+import { loadPluginMcpServers } from './mcpPluginIntegration.js'
+import { clearPluginCacheExclusions } from './orphanedPluginFilter.js'
+import { loadAllPlugins } from './pluginLoader.js'
+
+type SetAppState = (updater: (prev: AppState) => AppState) => void
+
+export type RefreshActivePluginsResult = {
+  enabled_count: number
+  disabled_count: number
+  command_count: number
+  agent_count: number
+  hook_count: number
+  mcp_count: number
+  /** LSP servers provided by enabled plugins. reinitializeLspServerManager()
+   * is called unconditionally so the manager picks these up (no-op if
+   * manager was never initialized). */
+  lsp_count: number
+  error_count: number
+  /** The refreshed agent definitions, for callers (e.g. print.ts) that also
+   * maintain a local mutable reference outside AppState. */
+  agentDefinitions: AgentDefinitionsResult
+  /** The refreshed plugin commands, same rationale as agentDefinitions. */
+  pluginCommands: Command[]
+}
+
+/**
+ * Refresh all active plugin components: commands, agents, hooks, MCP-reconnect
+ * trigger, AppState plugin arrays. Clears ALL plugin caches (unlike the old
+ * needsRefresh path which only cleared loadAllPlugins and returned stale data
+ * from downstream memoized loaders).
+ *
+ * Consumes plugins.needsRefresh (sets to false).
+ * Increments mcp.pluginReconnectKey so useManageMCPConnections effects re-run
+ * and pick up new plugin MCP servers.
+ *
+ * LSP: if plugins now contribute LSP servers, reinitializeLspServerManager()
+ * re-reads config. Servers are lazy-started so this is just config parsing.
+ */
+export async function refreshActivePlugins(
+  setAppState: SetAppState,
+): Promise<RefreshActivePluginsResult> {
+  logForDebugging('refreshActivePlugins: clearing all plugin caches')
+  clearAllCaches()
+  // Orphan exclusions are session-frozen by default, but /reload-plugins is
+  // an explicit "disk changed, re-read it" signal — recompute them too.
+  clearPluginCacheExclusions()
+
+  // Sequence the full load before cache-only consumers. Before #23693 all
+  // three shared loadAllPlugins()'s memoize promise so Promise.all was a
+  // no-op race. After #23693 getPluginCommands/getAgentDefinitions call
+  // loadAllPluginsCacheOnly (separate memoize) — racing them means they
+  // read installed_plugins.json before loadAllPlugins() has cloned+cached
+  // the plugin, returning plugin-cache-miss. loadAllPlugins warms the
+  // cache-only memoize on completion, so the awaits below are ~free.
+  const pluginResult = await loadAllPlugins()
+  const [pluginCommands, agentDefinitions] = await Promise.all([
+    getPluginCommands(),
+    getAgentDefinitionsWithOverrides(getOriginalCwd()),
+  ])
+
+  const { enabled, disabled, errors } = pluginResult
+
+  // Populate mcpServers/lspServers on each enabled plugin. These are lazy
+  // cache slots NOT filled by loadAllPlugins() — they're written later by
+  // extractMcpServersFromPlugins/getPluginLspServers, which races with this.
+  // Loading here gives accurate metrics AND warms the cache slots so the MCP
+  // connection manager (triggered by pluginReconnectKey bump) sees the servers
+  // without re-parsing manifests. Errors are pushed to the shared errors array.
+  const [mcpCounts, lspCounts] = await Promise.all([
+    Promise.all(
+      enabled.map(async p => {
+        if (p.mcpServers) return Object.keys(p.mcpServers).length
+        const servers = await loadPluginMcpServers(p, errors)
+        if (servers) p.mcpServers = servers
+        return servers ? Object.keys(servers).length : 0
+      }),
+    ),
+    Promise.all(
+      enabled.map(async p => {
+        if (p.lspServers) return Object.keys(p.lspServers).length
+        const servers = await loadPluginLspServers(p, errors)
+        if (servers) p.lspServers = servers
+        return servers ? Object.keys(servers).length : 0
+      }),
+    ),
+  ])
+  const mcp_count = mcpCounts.reduce((sum, n) => sum + n, 0)
+  const lsp_count = lspCounts.reduce((sum, n) => sum + n, 0)
+
+  setAppState(prev => ({
+    ...prev,
+    plugins: {
+      ...prev.plugins,
+      enabled,
+      disabled,
+      commands: pluginCommands,
+      errors: mergePluginErrors(prev.plugins.errors, errors),
+      needsRefresh: false,
+    },
+    agentDefinitions,
+    mcp: {
+      ...prev.mcp,
+      pluginReconnectKey: prev.mcp.pluginReconnectKey + 1,
+    },
+  }))
+
+  // Re-initialize LSP manager so newly-loaded plugin LSP servers are picked
+  // up. No-op if LSP was never initialized (headless subcommand path).
+  // Unconditional so removing the last LSP plugin also clears stale config.
+  // Fixes issue #15521: LSP manager previously read a stale memoized
+  // loadAllPlugins() result from before marketplaces were reconciled.
+  reinitializeLspServerManager()
+
+  // clearAllCaches() prunes removed-plugin hooks; this does the FULL swap
+  // (adds hooks from newly-enabled plugins too). Catching here so
+  // hook_load_failed can feed error_count; a failure doesn't lose the
+  // plugin/command/agent data above (hooks go to STATE.registeredHooks, not
+  // AppState).
+  let hook_load_failed = false
+  try {
+    await loadPluginHooks()
+  } catch (e) {
+    hook_load_failed = true
+    logError(e)
+    logForDebugging(
+      `refreshActivePlugins: loadPluginHooks failed: ${errorMessage(e)}`,
+    )
+  }
+
+  const hook_count = enabled.reduce((sum, p) => {
+    if (!p.hooksConfig) return sum
+    return (
+      sum +
+      Object.values(p.hooksConfig).reduce(
+        (s, matchers) =>
+          s + (matchers?.reduce((h, m) => h + m.hooks.length, 0) ?? 0),
+        0,
+      )
+    )
+  }, 0)
+
+  logForDebugging(
+    `refreshActivePlugins: ${enabled.length} enabled, ${pluginCommands.length} commands, ${agentDefinitions.allAgents.length} agents, ${hook_count} hooks, ${mcp_count} MCP, ${lsp_count} LSP`,
+  )
+
+  return {
+    enabled_count: enabled.length,
+    disabled_count: disabled.length,
+    command_count: pluginCommands.length,
+    agent_count: agentDefinitions.allAgents.length,
+    hook_count,
+    mcp_count,
+    lsp_count,
+    error_count: errors.length + (hook_load_failed ? 1 : 0),
+    agentDefinitions,
+    pluginCommands,
+  }
+}
+
+/**
+ * Merge fresh plugin-load errors with existing errors, preserving LSP and
+ * plugin-component errors that were recorded by other systems and
+ * deduplicating. Same logic as refreshPlugins()/updatePluginState(), extracted
+ * so refresh.ts doesn't leave those errors stranded.
+ */
+function mergePluginErrors(
+  existing: PluginError[],
+  fresh: PluginError[],
+): PluginError[] {
+  const preserved = existing.filter(
+    e => e.source === 'lsp-manager' || e.source.startsWith('plugin:'),
+  )
+  const freshKeys = new Set(fresh.map(errorKey))
+  const deduped = preserved.filter(e => !freshKeys.has(errorKey(e)))
+  return [...deduped, ...fresh]
+}
+
+function errorKey(e: PluginError): string {
+  return e.type === 'generic-error'
+    ? `generic-error:${e.source}:${e.error}`
+    : `${e.type}:${e.source}`
+}