feat(cli): gate CLI installation behind feature flag (#1544)

* feat(cli): gate PATH configuration behind feature flag

Skip writing to shell RC files when cli_validation_enforce flag is
disabled, while still detecting and logging the user's shell to Sentry
for analytics purposes.

* feat(cli): gate PATH configuration behind feature flag

Wrap configureShellPath in a dedicated Sentry span to track shell
detection analytics. Skip writing to shell RC files (Unix) and Windows
registry when cli_validation_enforce flag is disabled.

* feat(cli): gate CLI installation behind feature flag

Skip symlink creation, marker file, and PATH configuration when
cli_validation_enforce flag is disabled. Add Sentry span for
configureShellPath to track shell detection analytics.

Author: samuv

main/src/cli/__tests__/path-configurator.test.ts

@@ -73,10 +73,40 @@ vi.mock('../../logger', () => ({
   },
 }))
 
+const { mockSpan } = vi.hoisted(() => ({
+  mockSpan: {
+    setAttribute: vi.fn(),
+    setAttributes: vi.fn(),
+    end: vi.fn(),
+  },
+}))
+
+vi.mock('@sentry/electron/main', () => ({
+  startSpanManual: vi.fn((_options, callback) => callback(mockSpan)),
+}))
+
+const { mockGetFeatureFlag } = vi.hoisted(() => ({
+  mockGetFeatureFlag: vi.fn().mockReturnValue(true),
+}))
+
+vi.mock('../../feature-flags', () => ({
+  getFeatureFlag: mockGetFeatureFlag,
+}))
+
+vi.mock('../../../../utils/feature-flags', () => ({
+  featureFlagKeys: {
+    CLI_VALIDATION_ENFORCE: 'cli_validation_enforce',
+  },
+}))
+
 describe('path-configurator', () => {
   beforeEach(() => {
     vol.reset()
     vi.clearAllMocks()
+    // Reset span mock
+    mockSpan.setAttribute.mockClear()
+    mockSpan.setAttributes.mockClear()
+    mockSpan.end.mockClear()
     // Default to non-Windows
     vi.stubGlobal('process', {
       ...process,
@@ -85,6 +115,8 @@ describe('path-configurator', () => {
     })
     // Default mock for execAsync (shell detection)
     mockExecAsync.mockResolvedValue({ stdout: '', stderr: '' })
+    // Default feature flag to enabled
+    mockGetFeatureFlag.mockReturnValue(true)
   })
 
   afterEach(() => {
@@ -186,6 +218,36 @@ export PATH="$HOME/.toolhive/bin:$PATH"
       expect(result.success).toBe(true)
       expect(vol.existsSync('/home/testuser/.config/fish')).toBe(true)
     })
+
+    it('skips PATH modification when feature flag is disabled but still records shell in span', async () => {
+      mockGetFeatureFlag.mockReturnValue(false)
+
+      vol.fromJSON({
+        '/home/testuser/.zshrc': '# My zsh config\nalias ll="ls -la"\n',
+      })
+
+      const result = await configureShellPath()
+
+      expect(result.success).toBe(false)
+      expect(result.modifiedFiles).toHaveLength(0)
+      // Should still record detected shell in span
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+        'cli.detected_shell',
+        'zsh'
+      )
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+        'cli.feature_flag_enabled',
+        false
+      )
+      expect(mockSpan.setAttributes).toHaveBeenCalledWith({
+        'cli.path_configured': false,
+        'cli.skipped_reason': 'feature_flag_disabled',
+      })
+      expect(mockSpan.end).toHaveBeenCalled()
+      // File should not be modified
+      const content = vol.readFileSync('/home/testuser/.zshrc', 'utf8')
+      expect(content).not.toContain('# Added by ToolHive Studio')
+    })
   })
 
   describe('removeShellPath', () => {
@@ -388,5 +450,28 @@ export PATH="$HOME/.toolhive/bin:$PATH"
 
       expect(result.isConfigured).toBe(false)
     })
+
+    it('skips PATH modification when feature flag is disabled on Windows', async () => {
+      mockGetFeatureFlag.mockReturnValue(false)
+      mockExecAsync.mockResolvedValue({ stdout: '', stderr: '' })
+
+      const result = await configureShellPath()
+
+      expect(result.success).toBe(false)
+      expect(result.modifiedFiles).toHaveLength(0)
+      // Should record in span
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+        'cli.feature_flag_enabled',
+        false
+      )
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith('cli.is_windows', true)
+      expect(mockSpan.setAttributes).toHaveBeenCalledWith({
+        'cli.path_configured': false,
+        'cli.skipped_reason': 'feature_flag_disabled',
+      })
+      expect(mockSpan.end).toHaveBeenCalled()
+      // PowerShell should NOT be called
+      expect(mockExecAsync).not.toHaveBeenCalled()
+    })
   })
 })

main/src/cli/__tests__/validation.test.ts

@@ -56,6 +56,20 @@ vi.mock('@sentry/electron/main', () => ({
   startSpan: vi.fn((_options, callback) => callback()),
 }))
 
+const { mockGetFeatureFlag } = vi.hoisted(() => ({
+  mockGetFeatureFlag: vi.fn().mockReturnValue(true),
+}))
+
+vi.mock('../../feature-flags', () => ({
+  getFeatureFlag: mockGetFeatureFlag,
+}))
+
+vi.mock('../../../../utils/feature-flags', () => ({
+  featureFlagKeys: {
+    CLI_VALIDATION_ENFORCE: 'cli_validation_enforce',
+  },
+}))
+
 import { detectExternalCli, getCliInfo } from '../cli-detection'
 import { readMarkerFile, createMarkerForDesktopInstall } from '../marker-file'
 import {
@@ -93,6 +107,8 @@ describe('validation', () => {
       modifiedFiles: [],
       pathEntry: '/home/testuser/.toolhive/bin',
     })
+    // Default feature flag to enabled
+    mockGetFeatureFlag.mockReturnValue(true)
   })
 
   afterEach(() => {
@@ -335,6 +351,33 @@ describe('validation', () => {
 
       expect(result.status).toBe('fresh-install')
     })
+
+    it('skips symlink and marker creation when feature flag is disabled', async () => {
+      mockGetFeatureFlag.mockReturnValue(false)
+
+      const result = await handleValidationResult(
+        { status: 'fresh-install' },
+        'darwin'
+      )
+
+      expect(mockCreateSymlink).not.toHaveBeenCalled()
+      expect(mockCreateMarkerForDesktopInstall).not.toHaveBeenCalled()
+      expect(mockConfigureShellPath).not.toHaveBeenCalled()
+      expect(result.status).toBe('valid')
+    })
+
+    it('skips symlink creation for symlink-missing when feature flag is disabled', async () => {
+      mockGetFeatureFlag.mockReturnValue(false)
+
+      const result = await handleValidationResult(
+        { status: 'symlink-missing' },
+        'darwin'
+      )
+
+      expect(mockCreateSymlink).not.toHaveBeenCalled()
+      expect(mockCreateMarkerForDesktopInstall).not.toHaveBeenCalled()
+      expect(result.status).toBe('valid')
+    })
   })
 
   describe('repairCliSymlink', () => {

main/src/cli/path-configurator.ts

@@ -14,6 +14,7 @@ import path from 'node:path'
 import { homedir } from 'node:os'
 import { exec } from 'node:child_process'
 import { promisify } from 'node:util'
+import * as Sentry from '@sentry/electron/main'
 import {
   getShellRcFiles,
   SHELL_PATH_ENTRY,
@@ -22,6 +23,8 @@ import {
 } from './constants'
 import type { PathConfigStatus } from './types'
 import log from '../logger'
+import { getFeatureFlag } from '../feature-flags'
+import { featureFlagKeys } from '../../../utils/feature-flags'
 
 const execAsync = promisify(exec)
 
@@ -173,42 +176,95 @@ export async function configureShellPath(): Promise<{
   success: boolean
   modifiedFiles: string[]
 }> {
-  if (process.platform === 'win32') {
-    return configureWindowsPath()
-  }
+  return Sentry.startSpanManual(
+    {
+      name: 'CLI configure shell PATH',
+      op: 'cli.configure_path',
+      attributes: {
+        'analytics.source': 'tracking',
+        'analytics.type': 'event',
+        'cli.platform': process.platform,
+      },
+    },
+    async (span) => {
+      // Check if PATH configuration is enabled via feature flag
+      const isPathConfigEnabled = getFeatureFlag(
+        featureFlagKeys.CLI_VALIDATION_ENFORCE
+      )
 
-  const shellRcFiles = getShellRcFiles()
-  const modifiedFiles: string[] = []
+      span.setAttribute('cli.feature_flag_enabled', isPathConfigEnabled)
 
-  const defaultShell = await detectDefaultShell()
-  log.info(`Detected default shell: ${defaultShell}`)
+      if (process.platform === 'win32') {
+        span.setAttribute('cli.is_windows', true)
 
-  const defaultShellFiles = shellRcFiles[defaultShell] ?? []
-  const isFish = defaultShell === 'fish'
+        if (!isPathConfigEnabled) {
+          log.info('PATH configuration disabled by feature flag, skipping')
+          span.setAttributes({
+            'cli.path_configured': false,
+            'cli.skipped_reason': 'feature_flag_disabled',
+          })
+          span.end()
+          return { success: false, modifiedFiles: [] }
+        }
 
-  for (const rcFile of defaultShellFiles) {
-    if (addPathToFile(rcFile, isFish)) {
-      modifiedFiles.push(rcFile)
-    }
-  }
+        const result = await configureWindowsPath()
+        span.setAttribute('cli.path_configured', result.success)
+        span.end()
+        return result
+      }
 
-  const otherShells = Object.entries(shellRcFiles).filter(
-    ([shell]) => shell !== defaultShell
-  )
+      const shellRcFiles = getShellRcFiles()
+      const modifiedFiles: string[] = []
+
+      const defaultShell = await detectDefaultShell()
+      log.info(`Detected default shell: ${defaultShell}`)
+
+      // Record detected shell in span for analytics
+      span.setAttribute('cli.detected_shell', defaultShell)
 
-  for (const [shell, files] of otherShells) {
-    const shellIsFish = shell === 'fish'
+      if (!isPathConfigEnabled) {
+        log.info('PATH configuration disabled by feature flag, skipping')
+        span.setAttributes({
+          'cli.path_configured': false,
+          'cli.skipped_reason': 'feature_flag_disabled',
+        })
+        span.end()
+        return { success: false, modifiedFiles: [] }
+      }
+
+      const defaultShellFiles = shellRcFiles[defaultShell] ?? []
+      const isFish = defaultShell === 'fish'
 
-    for (const rcFile of files) {
-      if (existsSync(rcFile) && addPathToFile(rcFile, shellIsFish)) {
-        if (!modifiedFiles.includes(rcFile)) {
+      for (const rcFile of defaultShellFiles) {
+        if (addPathToFile(rcFile, isFish)) {
           modifiedFiles.push(rcFile)
         }
       }
-    }
-  }
 
-  return { success: true, modifiedFiles }
+      const otherShells = Object.entries(shellRcFiles).filter(
+        ([shell]) => shell !== defaultShell
+      )
+
+      for (const [shell, files] of otherShells) {
+        const shellIsFish = shell === 'fish'
+
+        for (const rcFile of files) {
+          if (existsSync(rcFile) && addPathToFile(rcFile, shellIsFish)) {
+            if (!modifiedFiles.includes(rcFile)) {
+              modifiedFiles.push(rcFile)
+            }
+          }
+        }
+      }
+
+      span.setAttributes({
+        'cli.path_configured': true,
+        'cli.modified_files_count': modifiedFiles.length,
+      })
+      span.end()
+      return { success: true, modifiedFiles }
+    }
+  )
 }
 
 async function removeWindowsPath(): Promise<{

main/src/cli/validation.ts

@@ -18,6 +18,8 @@ import { getDesktopCliPath } from './constants'
 import type { ValidationResult } from '@common/types/cli'
 import type { CliAlignmentStatus, Platform } from './types'
 import log from '../logger'
+import { getFeatureFlag } from '../feature-flags'
+import { featureFlagKeys } from '../../../utils/feature-flags'
 
 export async function validateCliAlignment(
   platform: Platform = process.platform as Platform
@@ -206,6 +208,25 @@ export async function handleValidationResult(
         // These cases can be auto-fixed without user interaction
         case 'symlink-missing':
         case 'fresh-install': {
+          // Check if CLI installation is enabled via feature flag
+          const isCliInstallEnabled = getFeatureFlag(
+            featureFlagKeys.CLI_VALIDATION_ENFORCE
+          )
+
+          span.setAttribute('cli.feature_flag_enabled', isCliInstallEnabled)
+
+          if (!isCliInstallEnabled) {
+            log.info(
+              'CLI installation disabled by feature flag, skipping symlink and marker creation'
+            )
+            span.setAttributes({
+              'cli.output_status': 'skipped',
+              'cli.skipped_reason': 'feature_flag_disabled',
+            })
+            span.end()
+            return { status: 'valid' }
+          }
+
           log.info('Performing fresh CLI installation...')
 
           const symlinkResult = createSymlink(platform)