subagent-cli 0.3.0 → 0.3.1

package/src/utils/plugins/gitAvailability.ts

@@ -1,69 +0,0 @@
-/**
- * Utility for checking git availability.
- *
- * Git is required for installing GitHub-based marketplaces. This module
- * provides a memoized check to determine if git is available on the system.
- */
-
-import memoize from 'lodash-es/memoize.js'
-import { which } from '../which.js'
-
-/**
- * Check if a command is available in PATH.
- *
- * Uses which to find the actual executable without executing it.
- * This is a security best practice to avoid executing arbitrary code
- * in untrusted directories.
- *
- * @param command - The command to check for
- * @returns True if the command exists and is executable
- */
-async function isCommandAvailable(command: string): Promise<boolean> {
-  try {
-    return !!(await which(command))
-  } catch {
-    return false
-  }
-}
-
-/**
- * Check if git is available on the system.
- *
- * This is memoized so repeated calls within a session return the cached result.
- * Git availability is unlikely to change during a single CLI session.
- *
- * Only checks PATH — does not exec git. On macOS this means the /usr/bin/git
- * xcrun shim passes even without Xcode CLT installed; callers that hit
- * `xcrun: error:` at exec time should call markGitUnavailable() so the rest
- * of the session behaves as though git is absent.
- *
- * @returns True if git is installed and executable
- */
-export const checkGitAvailable = memoize(async (): Promise<boolean> => {
-  return isCommandAvailable('git')
-})
-
-/**
- * Force the memoized git-availability check to return false for the rest of
- * the session.
- *
- * Call this when a git invocation fails in a way that indicates the binary
- * exists on PATH but cannot actually run — the macOS xcrun shim being the
- * main case (`xcrun: error: invalid active developer path`). Subsequent
- * checkGitAvailable() calls then short-circuit to false, so downstream code
- * that guards on git availability skips cleanly instead of failing repeatedly
- * with the same exec error.
- *
- * lodash memoize uses a no-arg cache key of undefined.
- */
-export function markGitUnavailable(): void {
-  checkGitAvailable.cache?.set?.(undefined, Promise.resolve(false))
-}
-
-/**
- * Clear the git availability cache.
- * Used for testing purposes.
- */
-export function clearGitAvailabilityCache(): void {
-  checkGitAvailable.cache?.clear?.()
-}

package/src/utils/plugins/headlessPluginInstall.ts

@@ -1,174 +0,0 @@
-/**
- * Plugin installation for headless/CCR mode.
- *
- * This module provides plugin installation without AppState updates,
- * suitable for non-interactive environments like CCR.
- *
- * When CLAUDE_CODE_PLUGIN_USE_ZIP_CACHE is enabled, plugins are stored as
- * ZIPs on a mounted volume. The storage layer (pluginLoader.ts) handles
- * ZIP creation on install and extraction on load transparently.
- */
-
-import { logEvent } from '../../services/analytics/index.js'
-import { registerCleanup } from '../cleanupRegistry.js'
-import { logForDebugging } from '../debug.js'
-import { withDiagnosticsTiming } from '../diagLogs.js'
-import { getFsImplementation } from '../fsOperations.js'
-import { logError } from '../log.js'
-import {
-  clearMarketplacesCache,
-  getDeclaredMarketplaces,
-  registerSeedMarketplaces,
-} from './marketplaceManager.js'
-import { detectAndUninstallDelistedPlugins } from './pluginBlocklist.js'
-import { clearPluginCache } from './pluginLoader.js'
-import { reconcileMarketplaces } from './reconciler.js'
-import {
-  cleanupSessionPluginCache,
-  getZipCacheMarketplacesDir,
-  getZipCachePluginsDir,
-  isMarketplaceSourceSupportedByZipCache,
-  isPluginZipCacheEnabled,
-} from './zipCache.js'
-import { syncMarketplacesToZipCache } from './zipCacheAdapters.js'
-
-/**
- * Install plugins for headless/CCR mode.
- *
- * This is the headless equivalent of performBackgroundPluginInstallations(),
- * but without AppState updates (no UI to update in headless mode).
- *
- * @returns true if any plugins were installed (caller should refresh MCP)
- */
-export async function installPluginsForHeadless(): Promise<boolean> {
-  const zipCacheMode = isPluginZipCacheEnabled()
-  logForDebugging(
-    `installPluginsForHeadless: starting${zipCacheMode ? ' (zip cache mode)' : ''}`,
-  )
-
-  // Register seed marketplaces (CLAUDE_CODE_PLUGIN_SEED_DIR) before diffing.
-  // Idempotent; no-op if seed not configured. Without this, findMissingMarketplaces
-  // would see seed entries as missing → clone → defeats seed's purpose.
-  //
-  // If registration changed state, clear caches so the early plugin-load pass
-  // (which runs during CLI startup before this function) doesn't keep stale
-  // "marketplace not found" results. Without this clear, a first-boot headless
-  // run with a seed-cached plugin would show 0 plugin commands/agents/skills
-  // in the init message even though the seed has everything.
-  const seedChanged = await registerSeedMarketplaces()
-  if (seedChanged) {
-    clearMarketplacesCache()
-    clearPluginCache('headlessPluginInstall: seed marketplaces registered')
-  }
-
-  // Ensure zip cache directory structure exists
-  if (zipCacheMode) {
-    await getFsImplementation().mkdir(getZipCacheMarketplacesDir())
-    await getFsImplementation().mkdir(getZipCachePluginsDir())
-  }
-
-  // Declared now includes an implicit claude-plugins-official entry when any
-  // enabled plugin references it (see getDeclaredMarketplaces). This routes
-  // the official marketplace through the same reconciler path as any other —
-  // which composes correctly with CLAUDE_CODE_PLUGIN_SEED_DIR: seed registers
-  // it in known_marketplaces.json, reconciler diff sees it as upToDate, no clone.
-  const declaredCount = Object.keys(getDeclaredMarketplaces()).length
-
-  const metrics = {
-    marketplaces_installed: 0,
-    delisted_count: 0,
-  }
-
-  // Initialize from seedChanged so the caller (print.ts) calls
-  // refreshPluginState() → clearCommandsCache/clearAgentDefinitionsCache
-  // when seed registration added marketplaces. Without this, the caller
-  // only refreshes when an actual plugin install happened.
-  let pluginsChanged = seedChanged
-
-  try {
-    if (declaredCount === 0) {
-      logForDebugging('installPluginsForHeadless: no marketplaces declared')
-    } else {
-      // Reconcile declared marketplaces (settings intent + implicit official)
-      // with materialized state. Zip cache: skip unsupported source types.
-      const reconcileResult = await withDiagnosticsTiming(
-        'headless_marketplace_reconcile',
-        () =>
-          reconcileMarketplaces({
-            skip: zipCacheMode
-              ? (_name, source) =>
-                  !isMarketplaceSourceSupportedByZipCache(source)
-              : undefined,
-            onProgress: event => {
-              if (event.type === 'installed') {
-                logForDebugging(
-                  `installPluginsForHeadless: installed marketplace ${event.name}`,
-                )
-              } else if (event.type === 'failed') {
-                logForDebugging(
-                  `installPluginsForHeadless: failed to install marketplace ${event.name}: ${event.error}`,
-                )
-              }
-            },
-          }),
-        r => ({
-          installed_count: r.installed.length,
-          updated_count: r.updated.length,
-          failed_count: r.failed.length,
-          skipped_count: r.skipped.length,
-        }),
-      )
-
-      if (reconcileResult.skipped.length > 0) {
-        logForDebugging(
-          `installPluginsForHeadless: skipped ${reconcileResult.skipped.length} marketplace(s) unsupported by zip cache: ${reconcileResult.skipped.join(', ')}`,
-        )
-      }
-
-      const marketplacesChanged =
-        reconcileResult.installed.length + reconcileResult.updated.length
-
-      // Clear caches so newly-installed marketplace plugins are discoverable.
-      // Plugin caching is the loader's job — after caches clear, the caller's
-      // refreshPluginState() → loadAllPlugins() will cache any missing plugins
-      // from the newly-materialized marketplaces.
-      if (marketplacesChanged > 0) {
-        clearMarketplacesCache()
-        clearPluginCache('headlessPluginInstall: marketplaces reconciled')
-        pluginsChanged = true
-      }
-
-      metrics.marketplaces_installed = marketplacesChanged
-    }
-
-    // Zip cache: save marketplace JSONs for offline access on ephemeral containers.
-    // Runs unconditionally so that steady-state containers (all plugins installed)
-    // still sync marketplace data that may have been cloned in a previous run.
-    if (zipCacheMode) {
-      await syncMarketplacesToZipCache()
-    }
-
-    // Delisting enforcement
-    const newlyDelisted = await detectAndUninstallDelistedPlugins()
-    metrics.delisted_count = newlyDelisted.length
-    if (newlyDelisted.length > 0) {
-      pluginsChanged = true
-    }
-
-    if (pluginsChanged) {
-      clearPluginCache('headlessPluginInstall: plugins changed')
-    }
-
-    // Zip cache: register session cleanup for extracted plugin temp dirs
-    if (zipCacheMode) {
-      registerCleanup(cleanupSessionPluginCache)
-    }
-
-    return pluginsChanged
-  } catch (error) {
-    logError(error)
-    return false
-  } finally {
-    logEvent('tengu_headless_plugin_install', metrics)
-  }
-}

package/src/utils/plugins/hintRecommendation.ts

@@ -1,164 +0,0 @@
-/**
- * Plugin-hint recommendations.
- *
- * Companion to lspRecommendation.ts: where LSP recommendations are triggered
- * by file edits, plugin hints are triggered by CLIs/SDKs emitting a
- * `<claude-code-hint />` tag to stderr (detected by the Bash/PowerShell tools).
- *
- * State persists in GlobalConfig.claudeCodeHints — a show-once record per
- * plugin and a disabled flag (user picked "don't show again"). Official-
- * marketplace filtering is hardcoded for v1.
- */
-
-import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
-import {
-  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
-  type AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED,
-  logEvent,
-} from '../../services/analytics/index.js'
-import {
-  type ClaudeCodeHint,
-  hasShownHintThisSession,
-  setPendingHint,
-} from '../claudeCodeHints.js'
-import { getGlobalConfig, saveGlobalConfig } from '../config.js'
-import { logForDebugging } from '../debug.js'
-import { isPluginInstalled } from './installedPluginsManager.js'
-import { getPluginById } from './marketplaceManager.js'
-import {
-  isOfficialMarketplaceName,
-  parsePluginIdentifier,
-} from './pluginIdentifier.js'
-import { isPluginBlockedByPolicy } from './pluginPolicy.js'
-
-/**
- * Hard cap on `claudeCodeHints.plugin[]` — bounds config growth. Each shown
- * plugin appends one slug; past this point we stop prompting (and stop
- * appending) rather than let the config grow without limit.
- */
-const MAX_SHOWN_PLUGINS = 100
-
-export type PluginHintRecommendation = {
-  pluginId: string
-  pluginName: string
-  marketplaceName: string
-  pluginDescription?: string
-  sourceCommand: string
-}
-
-/**
- * Pre-store gate called by shell tools when a `type="plugin"` hint is detected.
- * Drops the hint if:
- *
- *  - a dialog has already been shown this session
- *  - user has disabled hints
- *  - the shown-plugins list has hit the config-growth cap
- *  - plugin slug doesn't parse as `name@marketplace`
- *  - marketplace isn't official (hardcoded for v1)
- *  - plugin is already installed
- *  - plugin was already shown in a prior session
- *
- * Synchronous on purpose — shell tools shouldn't await a marketplace lookup
- * just to strip a stderr line. The async marketplace-cache check happens
- * later in resolvePluginHint (hook side).
- */
-export function maybeRecordPluginHint(hint: ClaudeCodeHint): void {
-  if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_lapis_finch', false)) return
-  if (hasShownHintThisSession()) return
-
-  const state = getGlobalConfig().claudeCodeHints
-  if (state?.disabled) return
-
-  const shown = state?.plugin ?? []
-  if (shown.length >= MAX_SHOWN_PLUGINS) return
-
-  const pluginId = hint.value
-  const { name, marketplace } = parsePluginIdentifier(pluginId)
-  if (!name || !marketplace) return
-  if (!isOfficialMarketplaceName(marketplace)) return
-  if (shown.includes(pluginId)) return
-  if (isPluginInstalled(pluginId)) return
-  if (isPluginBlockedByPolicy(pluginId)) return
-
-  // Bound repeat lookups on the same slug — a CLI that emits on every
-  // invocation shouldn't trigger N resolve cycles for the same plugin.
-  if (triedThisSession.has(pluginId)) return
-  triedThisSession.add(pluginId)
-
-  setPendingHint(hint)
-}
-
-const triedThisSession = new Set<string>()
-
-/** Test-only reset. */
-export function _resetHintRecommendationForTesting(): void {
-  triedThisSession.clear()
-}
-
-/**
- * Resolve the pending hint to a renderable recommendation. Runs the async
- * marketplace lookup that the sync pre-store gate skipped. Returns null if
- * the plugin isn't in the marketplace cache — the hint is discarded.
- */
-export async function resolvePluginHint(
-  hint: ClaudeCodeHint,
-): Promise<PluginHintRecommendation | null> {
-  const pluginId = hint.value
-  const { name, marketplace } = parsePluginIdentifier(pluginId)
-
-  const pluginData = await getPluginById(pluginId)
-
-  logEvent('tengu_plugin_hint_detected', {
-    _PROTO_plugin_name: (name ??
-      '') as AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED,
-    _PROTO_marketplace_name: (marketplace ??
-      '') as AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED,
-    result: (pluginData
-      ? 'passed'
-      : 'not_in_cache') as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
-  })
-
-  if (!pluginData) {
-    logForDebugging(
-      `[hintRecommendation] ${pluginId} not found in marketplace cache`,
-    )
-    return null
-  }
-
-  return {
-    pluginId,
-    pluginName: pluginData.entry.name,
-    marketplaceName: marketplace ?? '',
-    pluginDescription: pluginData.entry.description,
-    sourceCommand: hint.sourceCommand,
-  }
-}
-
-/**
- * Record that a prompt for this plugin was surfaced. Called regardless of
- * the user's yes/no response — show-once semantics.
- */
-export function markHintPluginShown(pluginId: string): void {
-  saveGlobalConfig(current => {
-    const existing = current.claudeCodeHints?.plugin ?? []
-    if (existing.includes(pluginId)) return current
-    return {
-      ...current,
-      claudeCodeHints: {
-        ...current.claudeCodeHints,
-        plugin: [...existing, pluginId],
-      },
-    }
-  })
-}
-
-/** Called when the user picks "don't show plugin installation hints again". */
-export function disableHintRecommendations(): void {
-  saveGlobalConfig(current => {
-    if (current.claudeCodeHints?.disabled) return current
-    return {
-      ...current,
-      claudeCodeHints: { ...current.claudeCodeHints, disabled: true },
-    }
-  })
-}

package/src/utils/plugins/installCounts.ts

@@ -1,292 +0,0 @@
-/**
- * Plugin install counts data layer
- *
- * This module fetches and caches plugin install counts from the official
- * Claude plugins statistics repository. The cache is refreshed if older
- * than 24 hours.
- *
- * Cache location: ~/.claude/plugins/install-counts-cache.json
- */
-
-import axios from 'axios'
-import { randomBytes } from 'crypto'
-import { readFile, rename, unlink, writeFile } from 'fs/promises'
-import { join } from 'path'
-import { logForDebugging } from '../debug.js'
-import { errorMessage, getErrnoCode } from '../errors.js'
-import { getFsImplementation } from '../fsOperations.js'
-import { logError } from '../log.js'
-import { jsonParse, jsonStringify } from '../slowOperations.js'
-import { classifyFetchError, logPluginFetch } from './fetchTelemetry.js'
-import { getPluginsDirectory } from './pluginDirectories.js'
-
-const INSTALL_COUNTS_CACHE_VERSION = 1
-const INSTALL_COUNTS_CACHE_FILENAME = 'install-counts-cache.json'
-const INSTALL_COUNTS_URL =
-  'https://raw.githubusercontent.com/anthropics/claude-plugins-official/refs/heads/stats/stats/plugin-installs.json'
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours in milliseconds
-
-/**
- * Structure of the install counts cache file
- */
-type InstallCountsCache = {
-  version: number
-  fetchedAt: string // ISO timestamp
-  counts: Array<{
-    plugin: string // "pluginName@marketplace"
-    unique_installs: number
-  }>
-}
-
-/**
- * Expected structure of the GitHub stats response
- */
-type GitHubStatsResponse = {
-  plugins: Array<{
-    plugin: string
-    unique_installs: number
-  }>
-}
-
-/**
- * Get the path to the install counts cache file
- */
-function getInstallCountsCachePath(): string {
-  return join(getPluginsDirectory(), INSTALL_COUNTS_CACHE_FILENAME)
-}
-
-/**
- * Load the install counts cache from disk.
- * Returns null if the file doesn't exist, is invalid, or is stale (>24h old).
- */
-async function loadInstallCountsCache(): Promise<InstallCountsCache | null> {
-  const cachePath = getInstallCountsCachePath()
-
-  try {
-    const content = await readFile(cachePath, { encoding: 'utf-8' })
-    const parsed = jsonParse(content) as unknown
-
-    // Validate basic structure
-    if (
-      typeof parsed !== 'object' ||
-      parsed === null ||
-      !('version' in parsed) ||
-      !('fetchedAt' in parsed) ||
-      !('counts' in parsed)
-    ) {
-      logForDebugging('Install counts cache has invalid structure')
-      return null
-    }
-
-    const cache = parsed as {
-      version: unknown
-      fetchedAt: unknown
-      counts: unknown
-    }
-
-    // Validate version
-    if (cache.version !== INSTALL_COUNTS_CACHE_VERSION) {
-      logForDebugging(
-        `Install counts cache version mismatch (got ${cache.version}, expected ${INSTALL_COUNTS_CACHE_VERSION})`,
-      )
-      return null
-    }
-
-    // Validate fetchedAt and counts
-    if (typeof cache.fetchedAt !== 'string' || !Array.isArray(cache.counts)) {
-      logForDebugging('Install counts cache has invalid structure')
-      return null
-    }
-
-    // Validate fetchedAt is a valid date
-    const fetchedAt = new Date(cache.fetchedAt).getTime()
-    if (Number.isNaN(fetchedAt)) {
-      logForDebugging('Install counts cache has invalid fetchedAt timestamp')
-      return null
-    }
-
-    // Validate count entries have required fields
-    const validCounts = cache.counts.every(
-      (entry): entry is { plugin: string; unique_installs: number } =>
-        typeof entry === 'object' &&
-        entry !== null &&
-        typeof entry.plugin === 'string' &&
-        typeof entry.unique_installs === 'number',
-    )
-    if (!validCounts) {
-      logForDebugging('Install counts cache has malformed entries')
-      return null
-    }
-
-    // Check if cache is stale (>24 hours old)
-    const now = Date.now()
-    if (now - fetchedAt > CACHE_TTL_MS) {
-      logForDebugging('Install counts cache is stale (>24h old)')
-      return null
-    }
-
-    // Return validated cache
-    return {
-      version: cache.version as number,
-      fetchedAt: cache.fetchedAt,
-      counts: cache.counts,
-    }
-  } catch (error) {
-    const code = getErrnoCode(error)
-    if (code !== 'ENOENT') {
-      logForDebugging(
-        `Failed to load install counts cache: ${errorMessage(error)}`,
-      )
-    }
-    return null
-  }
-}
-
-/**
- * Save the install counts cache to disk atomically.
- * Uses a temp file + rename pattern to prevent corruption.
- */
-async function saveInstallCountsCache(
-  cache: InstallCountsCache,
-): Promise<void> {
-  const cachePath = getInstallCountsCachePath()
-  const tempPath = `${cachePath}.${randomBytes(8).toString('hex')}.tmp`
-
-  try {
-    // Ensure the plugins directory exists
-    const pluginsDir = getPluginsDirectory()
-    await getFsImplementation().mkdir(pluginsDir)
-
-    // Write to temp file
-    const content = jsonStringify(cache, null, 2)
-    await writeFile(tempPath, content, {
-      encoding: 'utf-8',
-      mode: 0o600,
-    })
-
-    // Atomic rename
-    await rename(tempPath, cachePath)
-    logForDebugging('Install counts cache saved successfully')
-  } catch (error) {
-    logError(error)
-    // Clean up temp file if it exists
-    try {
-      await unlink(tempPath)
-    } catch {
-      // Ignore cleanup errors
-    }
-  }
-}
-
-/**
- * Fetch install counts from GitHub stats repository
- */
-async function fetchInstallCountsFromGitHub(): Promise<
-  Array<{ plugin: string; unique_installs: number }>
-> {
-  logForDebugging(`Fetching install counts from ${INSTALL_COUNTS_URL}`)
-
-  const started = performance.now()
-  try {
-    const response = await axios.get<GitHubStatsResponse>(INSTALL_COUNTS_URL, {
-      timeout: 10000,
-    })
-
-    if (!response.data?.plugins || !Array.isArray(response.data.plugins)) {
-      throw new Error('Invalid response format from install counts API')
-    }
-
-    logPluginFetch(
-      'install_counts',
-      INSTALL_COUNTS_URL,
-      'success',
-      performance.now() - started,
-    )
-    return response.data.plugins
-  } catch (error) {
-    logPluginFetch(
-      'install_counts',
-      INSTALL_COUNTS_URL,
-      'failure',
-      performance.now() - started,
-      classifyFetchError(error),
-    )
-    throw error
-  }
-}
-
-/**
- * Get plugin install counts as a Map.
- * Uses cached data if available and less than 24 hours old.
- * Returns null on errors so UI can hide counts rather than show misleading zeros.
- *
- * @returns Map of plugin ID (name@marketplace) to install count, or null if unavailable
- */
-export async function getInstallCounts(): Promise<Map<string, number> | null> {
-  // Try to load from cache first
-  const cache = await loadInstallCountsCache()
-  if (cache) {
-    logForDebugging('Using cached install counts')
-    logPluginFetch('install_counts', INSTALL_COUNTS_URL, 'cache_hit', 0)
-    const map = new Map<string, number>()
-    for (const entry of cache.counts) {
-      map.set(entry.plugin, entry.unique_installs)
-    }
-    return map
-  }
-
-  // Cache miss or stale - fetch from GitHub
-  try {
-    const counts = await fetchInstallCountsFromGitHub()
-
-    // Save to cache
-    const newCache: InstallCountsCache = {
-      version: INSTALL_COUNTS_CACHE_VERSION,
-      fetchedAt: new Date().toISOString(),
-      counts,
-    }
-    await saveInstallCountsCache(newCache)
-
-    // Convert to Map
-    const map = new Map<string, number>()
-    for (const entry of counts) {
-      map.set(entry.plugin, entry.unique_installs)
-    }
-    return map
-  } catch (error) {
-    // Log error and return null so UI can hide counts
-    logError(error)
-    logForDebugging(`Failed to fetch install counts: ${errorMessage(error)}`)
-    return null
-  }
-}
-
-/**
- * Format an install count for display.
- *
- * @param count - The raw install count
- * @returns Formatted string:
- *   - <1000: raw number (e.g., "42")
- *   - >=1000: K suffix with 1 decimal (e.g., "1.2K", "36.2K")
- *   - >=1000000: M suffix with 1 decimal (e.g., "1.2M")
- */
-export function formatInstallCount(count: number): string {
-  if (count < 1000) {
-    return String(count)
-  }
-
-  if (count < 1000000) {
-    const k = count / 1000
-    // Use toFixed(1) but remove trailing .0
-    const formatted = k.toFixed(1)
-    return formatted.endsWith('.0')
-      ? `${formatted.slice(0, -2)}K`
-      : `${formatted}K`
-  }
-
-  const m = count / 1000000
-  const formatted = m.toFixed(1)
-  return formatted.endsWith('.0')
-    ? `${formatted.slice(0, -2)}M`
-    : `${formatted}M`
-}