@xortex/xcode 3.0.0

package/utils/plugins/pluginBlocklist.ts

@@ -0,0 +1,127 @@
+/**
+ * Plugin delisting detection.
+ *
+ * Compares installed plugins against marketplace manifests to find plugins
+ * that have been removed, and auto-uninstalls them.
+ *
+ * The security.json fetch was removed (see #25447) — ~29.5M/week GitHub hits
+ * for UI reason/text only. If re-introduced, serve from downloads.claude.ai.
+ */
+
+import { uninstallPluginOp } from '../../services/plugins/pluginOperations.js'
+import { logForDebugging } from '../debug.js'
+import { errorMessage } from '../errors.js'
+import { loadInstalledPluginsV2 } from './installedPluginsManager.js'
+import {
+  getMarketplace,
+  loadKnownMarketplacesConfigSafe,
+} from './marketplaceManager.js'
+import {
+  addFlaggedPlugin,
+  getFlaggedPlugins,
+  loadFlaggedPlugins,
+} from './pluginFlagging.js'
+import type { InstalledPluginsFileV2, PluginMarketplace } from './schemas.js'
+
+/**
+ * Detect plugins installed from a marketplace that are no longer listed there.
+ *
+ * @param installedPlugins All installed plugins
+ * @param marketplace The marketplace to check against
+ * @param marketplaceName The marketplace name suffix (e.g. "claude-plugins-official")
+ * @returns List of delisted plugin IDs in "name@marketplace" format
+ */
+export function detectDelistedPlugins(
+  installedPlugins: InstalledPluginsFileV2,
+  marketplace: PluginMarketplace,
+  marketplaceName: string,
+): string[] {
+  const marketplacePluginNames = new Set(marketplace.plugins.map(p => p.name))
+  const suffix = `@${marketplaceName}`
+
+  const delisted: string[] = []
+  for (const pluginId of Object.keys(installedPlugins.plugins)) {
+    if (!pluginId.endsWith(suffix)) continue
+
+    const pluginName = pluginId.slice(0, -suffix.length)
+    if (!marketplacePluginNames.has(pluginName)) {
+      delisted.push(pluginId)
+    }
+  }
+
+  return delisted
+}
+
+/**
+ * Detect delisted plugins across all marketplaces, auto-uninstall them,
+ * and record them as flagged.
+ *
+ * This is the core delisting enforcement logic, shared between interactive
+ * mode (useManagePlugins) and headless mode (main.tsx print path).
+ *
+ * @returns List of newly flagged plugin IDs
+ */
+export async function detectAndUninstallDelistedPlugins(): Promise<string[]> {
+  await loadFlaggedPlugins()
+
+  const installedPlugins = loadInstalledPluginsV2()
+  const alreadyFlagged = getFlaggedPlugins()
+  // Read-only iteration — Safe variant so a corrupted config doesn't throw
+  // out of this function (it's called in the same try-block as loadAllPlugins
+  // in useManagePlugins, so a throw here would void loadAllPlugins' resilience).
+  const knownMarketplaces = await loadKnownMarketplacesConfigSafe()
+  const newlyFlagged: string[] = []
+
+  for (const marketplaceName of Object.keys(knownMarketplaces)) {
+    try {
+      const marketplace = await getMarketplace(marketplaceName)
+
+      if (!marketplace.forceRemoveDeletedPlugins) continue
+
+      const delisted = detectDelistedPlugins(
+        installedPlugins,
+        marketplace,
+        marketplaceName,
+      )
+
+      for (const pluginId of delisted) {
+        if (pluginId in alreadyFlagged) continue
+
+        // Skip managed-only plugins — enterprise admin should handle those
+        const installations = installedPlugins.plugins[pluginId] ?? []
+        const hasUserInstall = installations.some(
+          i =>
+            i.scope === 'user' || i.scope === 'project' || i.scope === 'local',
+        )
+        if (!hasUserInstall) continue
+
+        // Auto-uninstall the delisted plugin from all user-controllable scopes
+        for (const installation of installations) {
+          const { scope } = installation
+          if (scope !== 'user' && scope !== 'project' && scope !== 'local') {
+            continue
+          }
+          try {
+            await uninstallPluginOp(pluginId, scope)
+          } catch (error) {
+            logForDebugging(
+              `Failed to auto-uninstall delisted plugin ${pluginId} from ${scope}: ${errorMessage(error)}`,
+              { level: 'error' },
+            )
+          }
+        }
+
+        await addFlaggedPlugin(pluginId)
+        newlyFlagged.push(pluginId)
+      }
+    } catch (error) {
+      // Marketplace may not be available yet — log and continue
+      logForDebugging(
+        `Failed to check for delisted plugins in "${marketplaceName}": ${errorMessage(error)}`,
+        { level: 'warn' },
+      )
+    }
+  }
+
+  return newlyFlagged
+}

package/utils/plugins/pluginDirectories.ts

@@ -0,0 +1,178 @@
+/**
+ * Centralized plugin directory configuration.
+ *
+ * This module provides the single source of truth for the plugins directory path.
+ * It supports switching between 'plugins' and 'cowork_plugins' directories via:
+ * - CLI flag: --cowork
+ * - Environment variable: CLAUDE_CODE_USE_COWORK_PLUGINS
+ *
+ * The base directory can be overridden via CLAUDE_CODE_PLUGIN_CACHE_DIR.
+ */
+
+import { mkdirSync } from 'fs'
+import { readdir, rm, stat } from 'fs/promises'
+import { delimiter, join } from 'path'
+import { getUseCoworkPlugins } from '../../bootstrap/state.js'
+import { logForDebugging } from '../debug.js'
+import { getClaudeConfigHomeDir, isEnvTruthy } from '../envUtils.js'
+import { errorMessage, isFsInaccessible } from '../errors.js'
+import { formatFileSize } from '../format.js'
+import { expandTilde } from '../permissions/pathValidation.js'
+
+const PLUGINS_DIR = 'plugins'
+const COWORK_PLUGINS_DIR = 'cowork_plugins'
+
+/**
+ * Get the plugins directory name based on current mode.
+ * Uses session state (from --cowork flag) or env var.
+ *
+ * Priority:
+ * 1. Session state (set by CLI flag --cowork)
+ * 2. Environment variable CLAUDE_CODE_USE_COWORK_PLUGINS
+ * 3. Default: 'plugins'
+ */
+function getPluginsDirectoryName(): string {
+  // Session state takes precedence (set by CLI flag)
+  if (getUseCoworkPlugins()) {
+    return COWORK_PLUGINS_DIR
+  }
+  // Fall back to env var
+  if (isEnvTruthy(process.env.CLAUDE_CODE_USE_COWORK_PLUGINS)) {
+    return COWORK_PLUGINS_DIR
+  }
+  return PLUGINS_DIR
+}
+
+/**
+ * Get the full path to the plugins directory.
+ *
+ * Priority:
+ * 1. CLAUDE_CODE_PLUGIN_CACHE_DIR env var (explicit override)
+ * 2. Default: ~/.claude/plugins or ~/.claude/cowork_plugins
+ */
+export function getPluginsDirectory(): string {
+  // expandTilde: when CLAUDE_CODE_PLUGIN_CACHE_DIR is set via settings.json
+  // `env` (not shell), ~ is not expanded by the shell. Without this, a value
+  // like "~/.claude/plugins" becomes a literal `~` directory created in the
+  // cwd of every project (gh-30794 / CC-212).
+  const envOverride = process.env.CLAUDE_CODE_PLUGIN_CACHE_DIR
+  if (envOverride) {
+    return expandTilde(envOverride)
+  }
+  return join(getClaudeConfigHomeDir(), getPluginsDirectoryName())
+}
+
+/**
+ * Get the read-only plugin seed directories, if configured.
+ *
+ * Customers can pre-bake a populated plugins directory into their container
+ * image and point CLAUDE_CODE_PLUGIN_SEED_DIR at it. CC will use it as a
+ * read-only fallback layer under the primary plugins directory — marketplaces
+ * and plugin caches found in the seed are used in place without re-cloning.
+ *
+ * Multiple seed directories can be layered using the platform path delimiter
+ * (':' on Unix, ';' on Windows), in PATH-like precedence order — the first
+ * seed that contains a given marketplace or plugin cache wins.
+ *
+ * Seed structure mirrors the primary plugins directory:
+ *   $CLAUDE_CODE_PLUGIN_SEED_DIR/
+ *     known_marketplaces.json
+ *     marketplaces/<name>/...
+ *     cache/<marketplace>/<plugin>/<version>/...
+ *
+ * @returns Absolute paths to seed dirs in precedence order (empty if unset)
+ */
+export function getPluginSeedDirs(): string[] {
+  // Same tilde-expansion rationale as getPluginsDirectory (gh-30794).
+  const raw = process.env.CLAUDE_CODE_PLUGIN_SEED_DIR
+  if (!raw) return []
+  return raw.split(delimiter).filter(Boolean).map(expandTilde)
+}
+
+function sanitizePluginId(pluginId: string): string {
+  // Same character class as the install-cache sanitizer (pluginLoader.ts)
+  return pluginId.replace(/[^a-zA-Z0-9\-_]/g, '-')
+}
+
+/** Pure path — no mkdir. For display (e.g. uninstall dialog). */
+export function pluginDataDirPath(pluginId: string): string {
+  return join(getPluginsDirectory(), 'data', sanitizePluginId(pluginId))
+}
+
+/**
+ * Persistent per-plugin data directory, exposed to plugins as
+ * ${CLAUDE_PLUGIN_DATA}. Unlike the version-scoped install cache
+ * (${CLAUDE_PLUGIN_ROOT}, which is orphaned and GC'd on every update),
+ * this survives plugin updates — only removed on last-scope uninstall.
+ *
+ * Creates the directory on call (mkdir). The *lazy* behavior is at the
+ * substitutePluginVariables call site — the DATA pattern uses function-form
+ * .replace() so this isn't invoked unless ${CLAUDE_PLUGIN_DATA} is present
+ * (ROOT also uses function-form, but for $-pattern safety, not laziness).
+ * Env-var export sites (MCP/LSP server env, hook env) call this eagerly
+ * since subprocesses may expect the dir to exist before writing to it.
+ *
+ * Sync because it's called from substitutePluginVariables (sync, inside
+ * String.replace) — making this async would cascade through 6 call sites
+ * and their sync iteration loops. One mkdir in plugin-load path is cheap.
+ */
+export function getPluginDataDir(pluginId: string): string {
+  const dir = pluginDataDirPath(pluginId)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * Size of the data dir for the uninstall confirmation prompt. Returns null
+ * when the dir is absent or empty so callers can skip the prompt entirely.
+ * Recursive walk — not hot-path (only on uninstall).
+ */
+export async function getPluginDataDirSize(
+  pluginId: string,
+): Promise<{ bytes: number; human: string } | null> {
+  const dir = pluginDataDirPath(pluginId)
+  let bytes = 0
+  const walk = async (p: string) => {
+    for (const entry of await readdir(p, { withFileTypes: true })) {
+      const full = join(p, entry.name)
+      if (entry.isDirectory()) {
+        await walk(full)
+      } else {
+        // Per-entry catch: a broken symlink makes stat() throw ENOENT.
+        // Without this, one broken link bubbles to the outer catch →
+        // returns null → dialog skipped → data silently deleted.
+        try {
+          bytes += (await stat(full)).size
+        } catch {
+          // Broken symlink / raced delete — skip this entry, keep walking
+        }
+      }
+    }
+  }
+  try {
+    await walk(dir)
+  } catch (e) {
+    if (isFsInaccessible(e)) return null
+    throw e
+  }
+  if (bytes === 0) return null
+  return { bytes, human: formatFileSize(bytes) }
+}
+
+/**
+ * Best-effort cleanup on last-scope uninstall. Failure is logged but does
+ * not throw — the uninstall itself already succeeded; we don't want a
+ * cleanup side-effect surfacing as "uninstall failed". Same rationale as
+ * deletePluginOptions (pluginOptionsStorage.ts).
+ */
+export async function deletePluginDataDir(pluginId: string): Promise<void> {
+  const dir = pluginDataDirPath(pluginId)
+  try {
+    await rm(dir, { recursive: true, force: true })
+  } catch (e) {
+    logForDebugging(
+      `Failed to delete plugin data dir ${dir}: ${errorMessage(e)}`,
+      { level: 'warn' },
+    )
+  }
+}

package/utils/plugins/pluginFlagging.ts

@@ -0,0 +1,208 @@
+/**
+ * Flagged plugin tracking utilities
+ *
+ * Tracks plugins that were auto-removed because they were delisted from
+ * their marketplace. Data is stored in ~/.claude/plugins/flagged-plugins.json.
+ * Flagged plugins appear in a "Flagged" section in /plugins until the user
+ * dismisses them.
+ *
+ * Uses a module-level cache so that getFlaggedPlugins() can be called
+ * synchronously during React render. The cache is populated on the first
+ * async call (loadFlaggedPlugins or addFlaggedPlugin) and kept in sync
+ * with writes.
+ */
+
+import { randomBytes } from 'crypto'
+import { readFile, rename, unlink, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { logForDebugging } from '../debug.js'
+import { getFsImplementation } from '../fsOperations.js'
+import { logError } from '../log.js'
+import { jsonParse, jsonStringify } from '../slowOperations.js'
+import { getPluginsDirectory } from './pluginDirectories.js'
+
+const FLAGGED_PLUGINS_FILENAME = 'flagged-plugins.json'
+
+export type FlaggedPlugin = {
+  flaggedAt: string
+  seenAt?: string
+}
+
+const SEEN_EXPIRY_MS = 48 * 60 * 60 * 1000 // 48 hours
+
+// Module-level cache — populated by loadFlaggedPlugins(), updated by writes.
+let cache: Record<string, FlaggedPlugin> | null = null
+
+function getFlaggedPluginsPath(): string {
+  return join(getPluginsDirectory(), FLAGGED_PLUGINS_FILENAME)
+}
+
+function parsePluginsData(content: string): Record<string, FlaggedPlugin> {
+  const parsed = jsonParse(content) as unknown
+  if (
+    typeof parsed !== 'object' ||
+    parsed === null ||
+    !('plugins' in parsed) ||
+    typeof (parsed as { plugins: unknown }).plugins !== 'object' ||
+    (parsed as { plugins: unknown }).plugins === null
+  ) {
+    return {}
+  }
+  const plugins = (parsed as { plugins: Record<string, unknown> }).plugins
+  const result: Record<string, FlaggedPlugin> = {}
+  for (const [id, entry] of Object.entries(plugins)) {
+    if (
+      entry &&
+      typeof entry === 'object' &&
+      'flaggedAt' in entry &&
+      typeof (entry as { flaggedAt: unknown }).flaggedAt === 'string'
+    ) {
+      const parsed: FlaggedPlugin = {
+        flaggedAt: (entry as { flaggedAt: string }).flaggedAt,
+      }
+      if (
+        'seenAt' in entry &&
+        typeof (entry as { seenAt: unknown }).seenAt === 'string'
+      ) {
+        parsed.seenAt = (entry as { seenAt: string }).seenAt
+      }
+      result[id] = parsed
+    }
+  }
+  return result
+}
+
+async function readFromDisk(): Promise<Record<string, FlaggedPlugin>> {
+  try {
+    const content = await readFile(getFlaggedPluginsPath(), {
+      encoding: 'utf-8',
+    })
+    return parsePluginsData(content)
+  } catch {
+    return {}
+  }
+}
+
+async function writeToDisk(
+  plugins: Record<string, FlaggedPlugin>,
+): Promise<void> {
+  const filePath = getFlaggedPluginsPath()
+  const tempPath = `${filePath}.${randomBytes(8).toString('hex')}.tmp`
+
+  try {
+    await getFsImplementation().mkdir(getPluginsDirectory())
+
+    const content = jsonStringify({ plugins }, null, 2)
+    await writeFile(tempPath, content, {
+      encoding: 'utf-8',
+      mode: 0o600,
+    })
+    await rename(tempPath, filePath)
+    cache = plugins
+  } catch (error) {
+    logError(error)
+    try {
+      await unlink(tempPath)
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Load flagged plugins from disk into the module cache.
+ * Must be called (and awaited) before getFlaggedPlugins() returns
+ * meaningful data. Called by useManagePlugins during plugin refresh.
+ */
+export async function loadFlaggedPlugins(): Promise<void> {
+  const all = await readFromDisk()
+  const now = Date.now()
+  let changed = false
+
+  for (const [id, entry] of Object.entries(all)) {
+    if (
+      entry.seenAt &&
+      now - new Date(entry.seenAt).getTime() >= SEEN_EXPIRY_MS
+    ) {
+      delete all[id]
+      changed = true
+    }
+  }
+
+  cache = all
+  if (changed) {
+    await writeToDisk(all)
+  }
+}
+
+/**
+ * Get all flagged plugins from the in-memory cache.
+ * Returns an empty object if loadFlaggedPlugins() has not been called yet.
+ */
+export function getFlaggedPlugins(): Record<string, FlaggedPlugin> {
+  return cache ?? {}
+}
+
+/**
+ * Add a plugin to the flagged list.
+ *
+ * @param pluginId "name@marketplace" format
+ */
+export async function addFlaggedPlugin(pluginId: string): Promise<void> {
+  if (cache === null) {
+    cache = await readFromDisk()
+  }
+
+  const updated = {
+    ...cache,
+    [pluginId]: {
+      flaggedAt: new Date().toISOString(),
+    },
+  }
+
+  await writeToDisk(updated)
+  logForDebugging(`Flagged plugin: ${pluginId}`)
+}
+
+/**
+ * Mark flagged plugins as seen. Called when the Installed view renders
+ * flagged plugins. Sets seenAt on entries that don't already have it.
+ * After 48 hours from seenAt, entries are auto-cleared on next load.
+ */
+export async function markFlaggedPluginsSeen(
+  pluginIds: string[],
+): Promise<void> {
+  if (cache === null) {
+    cache = await readFromDisk()
+  }
+  const now = new Date().toISOString()
+  let changed = false
+
+  const updated = { ...cache }
+  for (const id of pluginIds) {
+    const entry = updated[id]
+    if (entry && !entry.seenAt) {
+      updated[id] = { ...entry, seenAt: now }
+      changed = true
+    }
+  }
+
+  if (changed) {
+    await writeToDisk(updated)
+  }
+}
+
+/**
+ * Remove a plugin from the flagged list. Called when the user dismisses
+ * a flagged plugin notification in /plugins.
+ */
+export async function removeFlaggedPlugin(pluginId: string): Promise<void> {
+  if (cache === null) {
+    cache = await readFromDisk()
+  }
+  if (!(pluginId in cache)) return
+
+  const { [pluginId]: _, ...rest } = cache
+  cache = rest
+  await writeToDisk(rest)
+}

package/utils/plugins/pluginIdentifier.ts

@@ -0,0 +1,123 @@
+import type {
+  EditableSettingSource,
+  SettingSource,
+} from '../settings/constants.js'
+import {
+  ALLOWED_OFFICIAL_MARKETPLACE_NAMES,
+  type PluginScope,
+} from './schemas.js'
+
+/**
+ * Extended scope type that includes 'flag' for session-only plugins.
+ * 'flag' scope is NOT persisted to installed_plugins.json.
+ */
+export type ExtendedPluginScope = PluginScope | 'flag'
+
+/**
+ * Scopes that are persisted to installed_plugins.json.
+ * Excludes 'flag' which is session-only.
+ */
+export type PersistablePluginScope = Exclude<ExtendedPluginScope, 'flag'>
+
+/**
+ * Map from SettingSource to plugin scope.
+ * Note: flagSettings maps to 'flag' which is session-only and not persisted.
+ */
+export const SETTING_SOURCE_TO_SCOPE = {
+  policySettings: 'managed',
+  userSettings: 'user',
+  projectSettings: 'project',
+  localSettings: 'local',
+  flagSettings: 'flag',
+} as const satisfies Record<SettingSource, ExtendedPluginScope>
+
+/**
+ * Parsed plugin identifier with name and optional marketplace
+ */
+export type ParsedPluginIdentifier = {
+  name: string
+  marketplace?: string
+}
+
+/**
+ * Parse a plugin identifier string into name and marketplace components
+ * @param plugin The plugin identifier (name or name@marketplace)
+ * @returns Parsed plugin name and optional marketplace
+ *
+ * Note: Only the first '@' is used as separator. If the input contains multiple '@' symbols
+ * (e.g., "plugin@market@place"), everything after the second '@' is ignored.
+ * This is intentional as marketplace names should not contain '@'.
+ */
+export function parsePluginIdentifier(plugin: string): ParsedPluginIdentifier {
+  if (plugin.includes('@')) {
+    const parts = plugin.split('@')
+    return { name: parts[0] || '', marketplace: parts[1] }
+  }
+  return { name: plugin }
+}
+
+/**
+ * Build a plugin ID from name and marketplace
+ * @param name The plugin name
+ * @param marketplace Optional marketplace name
+ * @returns Plugin ID in format "name" or "name@marketplace"
+ */
+export function buildPluginId(name: string, marketplace?: string): string {
+  return marketplace ? `${name}@${marketplace}` : name
+}
+
+/**
+ * Check if a marketplace name is an official (Anthropic-controlled) marketplace.
+ * Used for telemetry redaction — official plugin identifiers are safe to log to
+ * general-access additional_metadata; third-party identifiers go only to the
+ * PII-tagged _PROTO_* BQ columns.
+ */
+export function isOfficialMarketplaceName(
+  marketplace: string | undefined,
+): boolean {
+  return (
+    marketplace !== undefined &&
+    ALLOWED_OFFICIAL_MARKETPLACE_NAMES.has(marketplace.toLowerCase())
+  )
+}
+
+/**
+ * Map from installable plugin scope to editable setting source.
+ * This is the inverse of SETTING_SOURCE_TO_SCOPE for editable scopes only.
+ * Note: 'managed' scope cannot be installed to, so it's not included here.
+ */
+const SCOPE_TO_EDITABLE_SOURCE: Record<
+  Exclude<PluginScope, 'managed'>,
+  EditableSettingSource
+> = {
+  user: 'userSettings',
+  project: 'projectSettings',
+  local: 'localSettings',
+}
+
+/**
+ * Convert a plugin scope to its corresponding editable setting source
+ * @param scope The plugin installation scope
+ * @returns The corresponding setting source for reading/writing settings
+ * @throws Error if scope is 'managed' (cannot install plugins to managed scope)
+ */
+export function scopeToSettingSource(
+  scope: PluginScope,
+): EditableSettingSource {
+  if (scope === 'managed') {
+    throw new Error('Cannot install plugins to managed scope')
+  }
+  return SCOPE_TO_EDITABLE_SOURCE[scope]
+}
+
+/**
+ * Convert an editable setting source to its corresponding plugin scope.
+ * Derived from SETTING_SOURCE_TO_SCOPE to maintain a single source of truth.
+ * @param source The setting source
+ * @returns The corresponding plugin scope
+ */
+export function settingSourceToScope(
+  source: EditableSettingSource,
+): Exclude<PluginScope, 'managed'> {
+  return SETTING_SOURCE_TO_SCOPE[source] as Exclude<PluginScope, 'managed'>
+}