feat: implement client installation progress tracking with detailed event emissions and UI integration

Author: Cyneric

src/main/__tests__/preload-bridge.test.ts

@@ -74,6 +74,7 @@ const EXPECTED_KEYS = [
   'windowMaximize',
   'windowClose',
   'onConfigChanged',
+  'onClientInstallProgress',
   'onActivateProfileFromTray',
   'onUpdateAvailable',
   'onUpdateDownloaded',
@@ -122,6 +123,8 @@ describe('preload bridge composition', () => {
     await api.backupsList('cursor')
     await api.filesReveal('C:\\tmp\\file.txt')
     await api.registryPrepareInstall('smithery', '@anthropic/github-mcp')
+    const offInstallProgress = api.onClientInstallProgress(() => {})
+    offInstallProgress()
 
     expect(invoke).toHaveBeenCalledWith('clients:detect-all')
     expect(invoke).toHaveBeenCalledWith('clients:install', 'cursor')
@@ -155,5 +158,10 @@ describe('preload bridge composition', () => {
       'smithery',
       '@anthropic/github-mcp',
     )
+    const installProgressListener = (
+      on.mock.calls as [string, (...args: unknown[]) => void][]
+    ).find((call) => call[0] === 'clients:install-progress')?.[1]
+    expect(installProgressListener).toBeTypeOf('function')
+    expect(removeListener).toHaveBeenCalledWith('clients:install-progress', installProgressListener)
   })
 })

src/main/clients/__tests__/client-install.service.test.ts

@@ -7,6 +7,7 @@
 
 import { EventEmitter } from 'events'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ClientInstallProgressPayload } from '@shared/channels'
 
 type Platform = typeof process.platform
 
@@ -100,6 +101,34 @@ describe('ClientInstallService', () => {
     expect(spawnMock).toHaveBeenNthCalledWith(2, 'choco', expect.any(Array), expect.any(Object))
   })
 
+  it('emits monotonic progress events across fallback attempts', async () => {
+    spawnPlanQueue.push(
+      { command: 'winget', exitCode: 1, stderr: 'failed' },
+      { command: 'choco', exitCode: 0, stdout: 'ok' },
+    )
+    const service = new ClientInstallService()
+    const progressEvents: ClientInstallProgressPayload[] = []
+
+    await service.install('cursor', (payload) => {
+      progressEvents.push(payload)
+    })
+
+    expect(progressEvents.map((event) => event.phase)).toEqual([
+      'start',
+      'manager_check',
+      'manager_running',
+      'manager_failed',
+      'manager_check',
+      'manager_running',
+      'manager_succeeded',
+      'completed',
+    ])
+    expect(progressEvents.map((event) => event.progress)).toEqual(
+      [...progressEvents.map((event) => event.progress)].sort((a, b) => a - b),
+    )
+    expect(progressEvents.at(-1)?.progress).toBe(100)
+  })
+
   it('returns no_available_manager when none of the managers are present', async () => {
     managerAvailability.winget = false
     managerAvailability.choco = false
@@ -115,6 +144,26 @@ describe('ClientInstallService', () => {
     expect(spawnMock).not.toHaveBeenCalled()
   })
 
+  it('emits manager_skipped progress events when managers are unavailable', async () => {
+    managerAvailability.winget = false
+    managerAvailability.choco = false
+    managerAvailability.npm = false
+    const service = new ClientInstallService()
+    const progressEvents: ClientInstallProgressPayload[] = []
+
+    const result = await service.install('codex-cli', (payload) => {
+      progressEvents.push(payload)
+    })
+
+    expect(result.failureReason).toBe('no_available_manager')
+    expect(progressEvents.filter((event) => event.phase === 'manager_skipped')).toHaveLength(3)
+    expect(progressEvents.at(-1)).toMatchObject({
+      phase: 'completed',
+      failureReason: 'no_available_manager',
+      progress: 100,
+    })
+  })
+
   it('returns requires_elevation without trying to elevate automatically', async () => {
     spawnPlanQueue.push({
       command: 'winget',
@@ -136,13 +185,18 @@ describe('ClientInstallService', () => {
 
   it('returns manual_install_required for manual-only clients', async () => {
     const service = new ClientInstallService()
+    const progressEvents: ClientInstallProgressPayload[] = []
 
-    const result = await service.install('jetbrains')
+    const result = await service.install('jetbrains', (payload) => {
+      progressEvents.push(payload)
+    })
 
     expect(result.success).toBe(false)
     expect(result.failureReason).toBe('manual_install_required')
     expect(result.docsUrl).toContain('jetbrains.com')
     expect(result.attempts).toHaveLength(0)
+    expect(progressEvents.map((event) => event.phase)).toEqual(['start', 'completed'])
+    expect(progressEvents.at(-1)?.failureReason).toBe('manual_install_required')
     expect(spawnMock).not.toHaveBeenCalled()
   })
 

src/main/clients/client-install.service.ts

@@ -8,6 +8,7 @@
 
 import spawn from 'cross-spawn'
 import log from 'electron-log'
+import type { ClientInstallProgressPayload } from '@shared/channels'
 import type {
   ClientId,
   ClientInstallAttempt,
@@ -38,6 +39,8 @@ interface InstallExecutionResult {
   readonly error?: string
 }
 
+type InstallProgressReporter = (payload: ClientInstallProgressPayload) => void
+
 const INSTALL_DEFINITIONS: Readonly<Record<ClientId, ClientInstallDefinition>> = {
   cursor: {
     docsUrl: 'https://www.cursor.com/downloads',
@@ -335,6 +338,46 @@ const requiresElevation = (text: string): boolean =>
 const managerAvailable = (manager: AutomaticInstallManager): boolean =>
   hasWindowsCommandOnPath(MANAGER_COMMANDS[manager])
 
+const clampProgress = (progress: number): number => Math.min(100, Math.max(0, Math.round(progress)))
+
+const progressForAttempt = (
+  attemptIndex: number,
+  attemptCount: number,
+  segment: 'check' | 'running' | 'result',
+): number => {
+  if (attemptCount <= 0) return 95
+  const start = 5
+  const total = 90
+  const span = total / attemptCount
+  const offset = segment === 'check' ? 0 : segment === 'running' ? 0.5 : 1
+  return start + (attemptIndex - 1 + offset) * span
+}
+
+const createProgressEmitter = (
+  clientId: ClientId,
+  reportProgress?: InstallProgressReporter,
+): ((payload: Omit<ClientInstallProgressPayload, 'clientId'>) => void) => {
+  let lastProgress = 0
+
+  return (payload) => {
+    if (!reportProgress) return
+
+    const nextProgress = clampProgress(payload.progress)
+    const monotonicProgress = Math.max(lastProgress, nextProgress)
+    lastProgress = monotonicProgress
+
+    try {
+      reportProgress({
+        ...payload,
+        clientId,
+        progress: monotonicProgress,
+      })
+    } catch (err) {
+      log.warn(`[clients:install] progress reporter failed for ${clientId}: ${String(err)}`)
+    }
+  }
+}
+
 const execute = async (command: string, args: readonly string[]): Promise<InstallExecutionResult> =>
   new Promise((resolve) => {
     const child = spawn(command, [...args], {
@@ -388,41 +431,88 @@ const failureResult = (
 })
 
 export class ClientInstallService {
-  async install(clientId: ClientId): Promise<ClientInstallResult> {
+  async install(
+    clientId: ClientId,
+    reportProgress?: InstallProgressReporter,
+  ): Promise<ClientInstallResult> {
+    const expectedAttemptCount = INSTALL_DEFINITIONS[clientId]?.attempts.length ?? 0
+    const emitProgress = createProgressEmitter(clientId, reportProgress)
+    emitProgress({
+      phase: 'start',
+      progress: 1,
+      attemptIndex: 0,
+      attemptCount: expectedAttemptCount,
+    })
+
     if (process.platform !== 'win32') {
-      return failureResult(
+      const result = failureResult(
         clientId,
         [],
         'unsupported_platform',
         'In-app installs are currently supported on Windows only.',
       )
+      emitProgress({
+        phase: 'completed',
+        progress: 100,
+        attemptIndex: 0,
+        attemptCount: expectedAttemptCount,
+        ...(result.failureReason ? { failureReason: result.failureReason } : {}),
+      })
+      return result
     }
 
     const definition = INSTALL_DEFINITIONS[clientId]
     if (!definition) {
-      return failureResult(
+      const result = failureResult(
         clientId,
         [],
         'unsupported_client',
         `No install definition is available for client: ${clientId}`,
       )
+      emitProgress({
+        phase: 'completed',
+        progress: 100,
+        attemptIndex: 0,
+        attemptCount: 0,
+        ...(result.failureReason ? { failureReason: result.failureReason } : {}),
+      })
+      return result
     }
 
     if (definition.manualOnly || definition.attempts.length === 0) {
-      return failureResult(
+      const result = failureResult(
         clientId,
         [],
         'manual_install_required',
         'Automatic install is not available for this client. Please install it manually.',
         definition.docsUrl,
       )
+      emitProgress({
+        phase: 'completed',
+        progress: 100,
+        attemptIndex: 0,
+        attemptCount: definition.attempts.length,
+        ...(result.failureReason ? { failureReason: result.failureReason } : {}),
+      })
+      return result
     }
 
     const attempts: ClientInstallAttempt[] = []
     let hadRunnableManager = false
     let sawElevationFailure = false
+    const attemptCount = definition.attempts.length
+    let attemptIndex = 0
 
     for (const installAttempt of definition.attempts) {
+      attemptIndex += 1
+      emitProgress({
+        phase: 'manager_check',
+        progress: progressForAttempt(attemptIndex, attemptCount, 'check'),
+        attemptIndex,
+        attemptCount,
+        manager: installAttempt.manager,
+      })
+
       if (!managerAvailable(installAttempt.manager)) {
         attempts.push({
           manager: installAttempt.manager,
@@ -432,10 +522,24 @@ export class ClientInstallService {
           skipped: true,
           error: `${installAttempt.manager} is not available on PATH`,
         })
+        emitProgress({
+          phase: 'manager_skipped',
+          progress: progressForAttempt(attemptIndex, attemptCount, 'result'),
+          attemptIndex,
+          attemptCount,
+          manager: installAttempt.manager,
+        })
         continue
       }
 
       hadRunnableManager = true
+      emitProgress({
+        phase: 'manager_running',
+        progress: progressForAttempt(attemptIndex, attemptCount, 'running'),
+        attemptIndex,
+        attemptCount,
+        manager: installAttempt.manager,
+      })
       const runResult = await execute(installAttempt.command, installAttempt.args)
       const combinedOutput = `${runResult.stdout}\n${runResult.stderr}\n${runResult.error ?? ''}`
 
@@ -456,45 +560,85 @@ export class ClientInstallService {
 
       attempts.push(result)
 
+      emitProgress({
+        phase: result.success ? 'manager_succeeded' : 'manager_failed',
+        progress: progressForAttempt(attemptIndex, attemptCount, 'result'),
+        attemptIndex,
+        attemptCount,
+        manager: installAttempt.manager,
+      })
+
       if (result.success) {
         log.info(`[clients:install] ${clientId} installed via ${installAttempt.manager}`)
-        return {
+        const successResult: ClientInstallResult = {
           clientId,
           success: true,
           attempts,
           installedWith: installAttempt.manager,
           docsUrl: definition.docsUrl,
           message: `Installed via ${installAttempt.manager}.`,
         }
+        emitProgress({
+          phase: 'completed',
+          progress: 100,
+          attemptIndex,
+          attemptCount,
+          manager: installAttempt.manager,
+        })
+        return successResult
       }
     }
 
     if (!hadRunnableManager) {
-      return failureResult(
+      const result = failureResult(
         clientId,
         attempts,
         'no_available_manager',
         'No supported package manager is available (winget/choco/npm).',
         definition.docsUrl,
       )
+      emitProgress({
+        phase: 'completed',
+        progress: 100,
+        attemptIndex,
+        attemptCount,
+        ...(result.failureReason ? { failureReason: result.failureReason } : {}),
+      })
+      return result
     }
 
     if (sawElevationFailure) {
-      return failureResult(
+      const result = failureResult(
         clientId,
         attempts,
         'requires_elevation',
         'Install failed because elevated privileges are required. aidrelay does not auto-elevate.',
         definition.docsUrl,
       )
+      emitProgress({
+        phase: 'completed',
+        progress: 100,
+        attemptIndex,
+        attemptCount,
+        ...(result.failureReason ? { failureReason: result.failureReason } : {}),
+      })
+      return result
     }
 
-    return failureResult(
+    const result = failureResult(
       clientId,
       attempts,
       'command_failed',
       'Install failed for all attempted package managers.',
       definition.docsUrl,
     )
+    emitProgress({
+      phase: 'completed',
+      progress: 100,
+      attemptIndex,
+      attemptCount,
+      ...(result.failureReason ? { failureReason: result.failureReason } : {}),
+    })
+    return result
   }
 }