@xortex/xcode 3.0.0

package/utils/plugins/pluginStartupCheck.ts

@@ -0,0 +1,341 @@
+import { join } from 'path'
+import { getCwd } from '../cwd.js'
+import { logForDebugging } from '../debug.js'
+import { logError } from '../log.js'
+import type { SettingSource } from '../settings/constants.js'
+import {
+  getInitialSettings,
+  getSettingsForSource,
+  updateSettingsForSource,
+} from '../settings/settings.js'
+import { getAddDirEnabledPlugins } from './addDirPluginSettings.js'
+import {
+  getInMemoryInstalledPlugins,
+  migrateFromEnabledPlugins,
+} from './installedPluginsManager.js'
+import { getPluginById } from './marketplaceManager.js'
+import {
+  type ExtendedPluginScope,
+  type PersistablePluginScope,
+  SETTING_SOURCE_TO_SCOPE,
+  scopeToSettingSource,
+} from './pluginIdentifier.js'
+import {
+  cacheAndRegisterPlugin,
+  registerPluginInstallation,
+} from './pluginInstallationHelpers.js'
+import { isLocalPluginSource, type PluginScope } from './schemas.js'
+
+/**
+ * Checks for enabled plugins across all settings sources, including --add-dir.
+ *
+ * Uses getInitialSettings() which merges all sources with policy as
+ * highest priority, then layers --add-dir plugins underneath. This is the
+ * authoritative "is this plugin enabled?" check — don't delegate to
+ * getPluginEditableScopes() which serves a different purpose (scope tracking).
+ *
+ * @returns Array of plugin IDs (plugin@marketplace format) that are enabled
+ */
+export async function checkEnabledPlugins(): Promise<string[]> {
+  const settings = getInitialSettings()
+  const enabledPlugins: string[] = []
+
+  // Start with --add-dir plugins (lowest priority)
+  const addDirPlugins = getAddDirEnabledPlugins()
+  for (const [pluginId, value] of Object.entries(addDirPlugins)) {
+    if (pluginId.includes('@') && value) {
+      enabledPlugins.push(pluginId)
+    }
+  }
+
+  // Merged settings (policy > local > project > user) override --add-dir
+  if (settings.enabledPlugins) {
+    for (const [pluginId, value] of Object.entries(settings.enabledPlugins)) {
+      if (!pluginId.includes('@')) {
+        continue
+      }
+      const idx = enabledPlugins.indexOf(pluginId)
+      if (value) {
+        if (idx === -1) {
+          enabledPlugins.push(pluginId)
+        }
+      } else {
+        // Explicitly disabled — remove even if --add-dir enabled it
+        if (idx !== -1) {
+          enabledPlugins.splice(idx, 1)
+        }
+      }
+    }
+  }
+
+  return enabledPlugins
+}
+
+/**
+ * Gets the user-editable scope that "owns" each enabled plugin.
+ *
+ * Used for scope tracking: determining where to write back when a user
+ * enables/disables a plugin. Managed (policy) settings are processed first
+ * (lowest priority) because the user cannot edit them — the scope should
+ * resolve to the highest user-controllable source.
+ *
+ * NOTE: This is NOT the authoritative "is this plugin enabled?" check.
+ * Use checkEnabledPlugins() for that — it uses merged settings where
+ * policy has highest priority and can block user-enabled plugins.
+ *
+ * Precedence (lowest to highest):
+ * 0. addDir (--add-dir directories) - session-only, lowest priority
+ * 1. managed (policySettings) - not user-editable
+ * 2. user (userSettings)
+ * 3. project (projectSettings)
+ * 4. local (localSettings)
+ * 5. flag (flagSettings) - session-only, not persisted
+ *
+ * @returns Map of plugin ID to the user-editable scope that owns it
+ */
+export function getPluginEditableScopes(): Map<string, ExtendedPluginScope> {
+  const result = new Map<string, ExtendedPluginScope>()
+
+  // Process --add-dir directories FIRST (lowest priority, overridden by all standard sources)
+  const addDirPlugins = getAddDirEnabledPlugins()
+  for (const [pluginId, value] of Object.entries(addDirPlugins)) {
+    if (!pluginId.includes('@')) {
+      continue
+    }
+    if (value === true) {
+      result.set(pluginId, 'flag') // 'flag' scope = session-only, no write-back
+    } else if (value === false) {
+      result.delete(pluginId)
+    }
+  }
+
+  // Process standard sources in precedence order (later overrides earlier)
+  const scopeSources: Array<{
+    scope: ExtendedPluginScope
+    source: SettingSource
+  }> = [
+    { scope: 'managed', source: 'policySettings' },
+    { scope: 'user', source: 'userSettings' },
+    { scope: 'project', source: 'projectSettings' },
+    { scope: 'local', source: 'localSettings' },
+    { scope: 'flag', source: 'flagSettings' },
+  ]
+
+  for (const { scope, source } of scopeSources) {
+    const settings = getSettingsForSource(source)
+    if (!settings?.enabledPlugins) {
+      continue
+    }
+
+    for (const [pluginId, value] of Object.entries(settings.enabledPlugins)) {
+      // Skip invalid format
+      if (!pluginId.includes('@')) {
+        continue
+      }
+
+      // Log when a standard source overrides an --add-dir plugin
+      if (pluginId in addDirPlugins && addDirPlugins[pluginId] !== value) {
+        logForDebugging(
+          `Plugin ${pluginId} from --add-dir (${addDirPlugins[pluginId]}) overridden by ${source} (${value})`,
+        )
+      }
+
+      if (value === true) {
+        // Plugin enabled at this scope
+        result.set(pluginId, scope)
+      } else if (value === false) {
+        // Explicitly disabled - remove from result
+        result.delete(pluginId)
+      }
+      // Note: Other values (like version strings for future P2) are ignored for now
+    }
+  }
+
+  logForDebugging(
+    `Found ${result.size} enabled plugins with scopes: ${Array.from(
+      result.entries(),
+    )
+      .map(([id, scope]) => `${id}(${scope})`)
+      .join(', ')}`,
+  )
+
+  return result
+}
+
+/**
+ * Check if a scope is persistable (not session-only).
+ * @param scope The scope to check
+ * @returns true if the scope should be persisted to installed_plugins.json
+ */
+export function isPersistableScope(
+  scope: ExtendedPluginScope,
+): scope is PersistablePluginScope {
+  return scope !== 'flag'
+}
+
+/**
+ * Convert SettingSource to plugin scope.
+ * @param source The settings source
+ * @returns The corresponding plugin scope
+ */
+export function settingSourceToScope(
+  source: SettingSource,
+): ExtendedPluginScope {
+  return SETTING_SOURCE_TO_SCOPE[source]
+}
+
+/**
+ * Gets the list of currently installed plugins
+ * Reads from installed_plugins.json which tracks global installation state.
+ * Automatically runs migration on first call if needed.
+ *
+ * Always uses V2 format and initializes the in-memory session state
+ * (which triggers V1→V2 migration if needed).
+ *
+ * @returns Array of installed plugin IDs
+ */
+export async function getInstalledPlugins(): Promise<string[]> {
+  // Trigger sync in background (don't await - don't block startup)
+  // This syncs enabledPlugins from settings.json to installed_plugins.json
+  void migrateFromEnabledPlugins().catch(error => {
+    logError(error)
+  })
+
+  // Always use V2 format - initializes in-memory session state and triggers V1→V2 migration
+  const v2Data = getInMemoryInstalledPlugins()
+  const installed = Object.keys(v2Data.plugins)
+  logForDebugging(`Found ${installed.length} installed plugins`)
+  return installed
+}
+
+/**
+ * Finds plugins that are enabled but not installed
+ * @param enabledPlugins Array of enabled plugin IDs
+ * @returns Array of missing plugin IDs
+ */
+export async function findMissingPlugins(
+  enabledPlugins: string[],
+): Promise<string[]> {
+  try {
+    const installedPlugins = await getInstalledPlugins()
+
+    // Filter to not-installed synchronously, then look up all in parallel.
+    // Results are collected in original enabledPlugins order.
+    const notInstalled = enabledPlugins.filter(
+      id => !installedPlugins.includes(id),
+    )
+    const lookups = await Promise.all(
+      notInstalled.map(async pluginId => {
+        try {
+          const plugin = await getPluginById(pluginId)
+          return { pluginId, found: plugin !== null && plugin !== undefined }
+        } catch (error) {
+          logForDebugging(
+            `Failed to check plugin ${pluginId} in marketplace: ${error}`,
+          )
+          // Plugin doesn't exist in any marketplace, will be handled as an error
+          return { pluginId, found: false }
+        }
+      }),
+    )
+    const missing = lookups
+      .filter(({ found }) => found)
+      .map(({ pluginId }) => pluginId)
+
+    return missing
+  } catch (error) {
+    logError(error)
+    return []
+  }
+}
+
+/**
+ * Result of plugin installation attempt
+ */
+export type PluginInstallResult = {
+  installed: string[]
+  failed: Array<{ name: string; error: string }>
+}
+
+/**
+ * Installation scope type for install functions (excludes 'managed' which is read-only)
+ */
+type InstallableScope = Exclude<PluginScope, 'managed'>
+
+/**
+ * Installs the selected plugins
+ * @param pluginsToInstall Array of plugin IDs to install
+ * @param onProgress Optional callback for installation progress
+ * @param scope Installation scope: user, project, or local (defaults to 'user')
+ * @returns Installation results with succeeded and failed plugins
+ */
+export async function installSelectedPlugins(
+  pluginsToInstall: string[],
+  onProgress?: (name: string, index: number, total: number) => void,
+  scope: InstallableScope = 'user',
+): Promise<PluginInstallResult> {
+  // Get projectPath for non-user scopes
+  const projectPath = scope !== 'user' ? getCwd() : undefined
+
+  // Get the correct settings source for this scope
+  const settingSource = scopeToSettingSource(scope)
+  const settings = getSettingsForSource(settingSource)
+  const updatedEnabledPlugins = { ...settings?.enabledPlugins }
+  const installed: string[] = []
+  const failed: Array<{ name: string; error: string }> = []
+
+  for (let i = 0; i < pluginsToInstall.length; i++) {
+    const pluginId = pluginsToInstall[i]
+    if (!pluginId) continue
+
+    if (onProgress) {
+      onProgress(pluginId, i + 1, pluginsToInstall.length)
+    }
+
+    try {
+      const pluginInfo = await getPluginById(pluginId)
+      if (!pluginInfo) {
+        failed.push({
+          name: pluginId,
+          error: 'Plugin not found in any marketplace',
+        })
+        continue
+      }
+
+      // Cache the plugin if it's from an external source
+      const { entry, marketplaceInstallLocation } = pluginInfo
+      if (!isLocalPluginSource(entry.source)) {
+        // External plugin - cache and register it with scope
+        await cacheAndRegisterPlugin(pluginId, entry, scope, projectPath)
+      } else {
+        // Local plugin - just register it with the install path and scope
+        registerPluginInstallation(
+          {
+            pluginId,
+            installPath: join(marketplaceInstallLocation, entry.source),
+            version: entry.version,
+          },
+          scope,
+          projectPath,
+        )
+      }
+
+      // Mark as enabled in settings
+      updatedEnabledPlugins[pluginId] = true
+      installed.push(pluginId)
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error)
+      failed.push({ name: pluginId, error: errorMessage })
+      logError(error)
+    }
+  }
+
+  // Update settings with newly enabled plugins using the correct settings source
+  updateSettingsForSource(settingSource, {
+    ...settings,
+    enabledPlugins: updatedEnabledPlugins,
+  })
+
+  return { installed, failed }
+}

package/utils/plugins/pluginVersioning.ts

@@ -0,0 +1,157 @@
+/**
+ * Plugin Version Calculation Module
+ *
+ * Handles version calculation for plugins from various sources.
+ * Versions are used for versioned cache paths and update detection.
+ *
+ * Version sources (in order of preference):
+ * 1. Explicit version from plugin.json
+ * 2. Git commit SHA (for git/github sources)
+ * 3. Fallback timestamp for local sources
+ */
+
+import { createHash } from 'crypto'
+import { logForDebugging } from '../debug.js'
+import { getHeadForDir } from '../git/gitFilesystem.js'
+import type { PluginManifest, PluginSource } from './schemas.js'
+
+/**
+ * Calculate the version for a plugin based on its source.
+ *
+ * Version sources (in order of priority):
+ * 1. plugin.json version field (highest priority)
+ * 2. Provided version (typically from marketplace entry)
+ * 3. Git commit SHA from install path
+ * 4. 'unknown' as last resort
+ *
+ * @param pluginId - Plugin identifier (e.g., "plugin@marketplace")
+ * @param source - Plugin source configuration (used for git-subdir path hashing)
+ * @param manifest - Optional plugin manifest with version field
+ * @param installPath - Optional path to installed plugin (for git SHA extraction)
+ * @param providedVersion - Optional version from marketplace entry or caller
+ * @param gitCommitSha - Optional pre-resolved git SHA (for sources like
+ *   git-subdir where the clone is discarded and the install path has no .git)
+ * @returns Version string (semver, short SHA, or 'unknown')
+ */
+export async function calculatePluginVersion(
+  pluginId: string,
+  source: PluginSource,
+  manifest?: PluginManifest,
+  installPath?: string,
+  providedVersion?: string,
+  gitCommitSha?: string,
+): Promise<string> {
+  // 1. Use explicit version from plugin.json if available
+  if (manifest?.version) {
+    logForDebugging(
+      `Using manifest version for ${pluginId}: ${manifest.version}`,
+    )
+    return manifest.version
+  }
+
+  // 2. Use provided version (typically from marketplace entry)
+  if (providedVersion) {
+    logForDebugging(
+      `Using provided version for ${pluginId}: ${providedVersion}`,
+    )
+    return providedVersion
+  }
+
+  // 3. Use pre-resolved git SHA if caller captured it before discarding the clone
+  if (gitCommitSha) {
+    const shortSha = gitCommitSha.substring(0, 12)
+    if (typeof source === 'object' && source.source === 'git-subdir') {
+      // Encode the subdir path in the version so cache keys differ when
+      // marketplace.json's `path` changes but the monorepo SHA doesn't.
+      // Without this, two plugins at different subdirs of the same commit
+      // collide at cache/<m>/<p>/<sha>/ and serve each other's trees.
+      //
+      // Normalization MUST match the squashfs cron byte-for-byte:
+      //   1. backslash → forward slash
+      //   2. strip one leading `./`
+      //   3. strip all trailing `/`
+      //   4. UTF-8 sha256, first 8 hex chars
+      // See api/…/plugins_official_squashfs/job.py _validate_subdir().
+      const normPath = source.path
+        .replace(/\\/g, '/')
+        .replace(/^\.\//, '')
+        .replace(/\/+$/, '')
+      const pathHash = createHash('sha256')
+        .update(normPath)
+        .digest('hex')
+        .substring(0, 8)
+      const v = `${shortSha}-${pathHash}`
+      logForDebugging(
+        `Using git-subdir SHA+path version for ${pluginId}: ${v} (path=${normPath})`,
+      )
+      return v
+    }
+    logForDebugging(`Using pre-resolved git SHA for ${pluginId}: ${shortSha}`)
+    return shortSha
+  }
+
+  // 4. Try to get git SHA from install path
+  if (installPath) {
+    const sha = await getGitCommitSha(installPath)
+    if (sha) {
+      const shortSha = sha.substring(0, 12)
+      logForDebugging(`Using git SHA for ${pluginId}: ${shortSha}`)
+      return shortSha
+    }
+  }
+
+  // 5. Return 'unknown' as last resort
+  logForDebugging(`No version found for ${pluginId}, using 'unknown'`)
+  return 'unknown'
+}
+
+/**
+ * Get the git commit SHA for a directory.
+ *
+ * @param dirPath - Path to directory (should be a git repository)
+ * @returns Full commit SHA or null if not a git repo
+ */
+export function getGitCommitSha(dirPath: string): Promise<string | null> {
+  return getHeadForDir(dirPath)
+}
+
+/**
+ * Extract version from a versioned cache path.
+ *
+ * Given a path like `~/.claude/plugins/cache/marketplace/plugin/1.0.0`,
+ * extracts and returns `1.0.0`.
+ *
+ * @param installPath - Full path to plugin installation
+ * @returns Version string from path, or null if not a versioned path
+ */
+export function getVersionFromPath(installPath: string): string | null {
+  // Versioned paths have format: .../plugins/cache/marketplace/plugin/version/
+  const parts = installPath.split('/').filter(Boolean)
+
+  // Find 'cache' index to determine depth
+  const cacheIndex = parts.findIndex(
+    (part, i) => part === 'cache' && parts[i - 1] === 'plugins',
+  )
+
+  if (cacheIndex === -1) {
+    return null
+  }
+
+  // Versioned path has 3 components after 'cache': marketplace/plugin/version
+  const componentsAfterCache = parts.slice(cacheIndex + 1)
+  if (componentsAfterCache.length >= 3) {
+    return componentsAfterCache[2] || null
+  }
+
+  return null
+}
+
+/**
+ * Check if a path is a versioned plugin path.
+ *
+ * @param path - Path to check
+ * @returns True if path follows versioned structure
+ */
+export function isVersionedPath(path: string): boolean {
+  return getVersionFromPath(path) !== null
+}