fix: preserve lastError as cause in poll errors, add domain error wrapping

Addresses PR review feedback:
- PollExhaustedError and PollTimeoutError now include the last error
  as `cause` for debuggability (e.g., shows 'Rate exceeded' when
  throttling exhausts retries)
- phase2-import.ts wraps poll errors with operation-specific messages
  ('Timed out waiting for change set creation') preserving original
  error as cause
- Fixed misleading message when maxConsecutiveErrors triggers (now
  reports actual attempt count)
- Added 3 tests verifying cause propagation

Author: Hweinstock

src/cli/commands/import/phase2-import.ts

@@ -1,4 +1,4 @@
-import { isThrottlingError, poll } from '../../../lib/utils/polling';
+import { PollExhaustedError, PollTimeoutError, isThrottlingError, poll } from '../../../lib/utils/polling';
 import { getCredentialProvider } from '../../aws/account';
 import type { CfnTemplate } from './template-utils';
 import { buildImportTemplate } from './template-utils';
@@ -142,47 +142,61 @@ async function waitForChangeSetReady(
   stackName: string,
   changeSetName: string
 ): Promise<void> {
-  await poll({
-    fn: async () => {
-      const response = await cfn.send(
-        new DescribeChangeSetCommand({
-          StackName: stackName,
-          ChangeSetName: changeSetName,
-        })
-      );
-      const status = response.Status;
-      if (status === 'CREATE_COMPLETE') return { done: true, value: undefined };
-      if (status === 'FAILED') {
-        throw new Error(`Change set creation failed: ${response.StatusReason ?? 'Unknown reason'}`);
-      }
-      return { done: false };
-    },
-    maxAttempts: 60,
-    delayMs: 5000,
-    onError: (err: unknown) => (isThrottlingError(err) ? 'retry' : 'abort'),
-  });
+  try {
+    await poll({
+      fn: async () => {
+        const response = await cfn.send(
+          new DescribeChangeSetCommand({
+            StackName: stackName,
+            ChangeSetName: changeSetName,
+          })
+        );
+        const status = response.Status;
+        if (status === 'CREATE_COMPLETE') return { done: true, value: undefined };
+        if (status === 'FAILED') {
+          throw new Error(`Change set creation failed: ${response.StatusReason ?? 'Unknown reason'}`);
+        }
+        return { done: false };
+      },
+      maxAttempts: 60,
+      delayMs: 5000,
+      onError: (err: unknown) => (isThrottlingError(err) ? 'retry' : 'abort'),
+    });
+  } catch (err) {
+    if (err instanceof PollExhaustedError || err instanceof PollTimeoutError) {
+      throw new Error('Timed out waiting for change set creation', { cause: err });
+    }
+    throw err;
+  }
 }
 
 /**
  * Wait for stack to reach IMPORT_COMPLETE status.
  */
 async function waitForStackImportComplete(cfn: CloudFormationClient, stackName: string): Promise<void> {
-  await poll({
-    fn: async () => {
-      const response = await cfn.send(new DescribeStacksCommand({ StackName: stackName }));
-      const stack = response.Stacks?.[0];
-      if (!stack) throw new Error(`Stack ${stackName} not found during import wait`);
-      const status = stack.StackStatus ?? '';
-      if (status === 'IMPORT_COMPLETE') return { done: true, value: undefined };
-      if (status.includes('FAILED') || status.includes('ROLLBACK')) {
-        throw new Error(`Import failed with status: ${status}. Reason: ${stack.StackStatusReason ?? 'Unknown'}`);
-      }
-      return { done: false };
-    },
-    maxAttempts: 120,
-    delayMs: 5000,
-    onError: (err: unknown) => (isThrottlingError(err) ? 'retry' : 'abort'),
-  });
+  try {
+    await poll({
+      fn: async () => {
+        const response = await cfn.send(new DescribeStacksCommand({ StackName: stackName }));
+        const stack = response.Stacks?.[0];
+        if (!stack) throw new Error(`Stack ${stackName} not found during import wait`);
+        const status = stack.StackStatus ?? '';
+        if (status === 'IMPORT_COMPLETE') return { done: true, value: undefined };
+        if (status.includes('FAILED') || status.includes('ROLLBACK')) {
+          throw new Error(`Import failed with status: ${status}. Reason: ${stack.StackStatusReason ?? 'Unknown'}`);
+        }
+        return { done: false };
+      },
+      maxAttempts: 120,
+      delayMs: 5000,
+      onError: (err: unknown) => (isThrottlingError(err) ? 'retry' : 'abort'),
+    });
+  } catch (err) {
+    if (err instanceof PollExhaustedError || err instanceof PollTimeoutError) {
+      throw new Error('Timed out waiting for import to complete', { cause: err });
+    }
+    throw err;
+  }
 }
 
 /**

src/lib/utils/__tests__/polling.test.ts

@@ -119,6 +119,42 @@ describe('poll', () => {
     ).rejects.toThrow(PollExhaustedError);
   });
 
+  it('PollExhaustedError includes cause with the last error', async () => {
+    const err = await poll({
+      fn: async () => {
+        throw new Error('Rate exceeded');
+      },
+      maxAttempts: 3,
+      delayMs: 1,
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PollExhaustedError);
+    expect((err as PollExhaustedError).cause).toBeInstanceOf(Error);
+    expect(((err as PollExhaustedError).cause as Error).message).toBe('Rate exceeded');
+  });
+
+  it('PollTimeoutError includes cause with the last error', async () => {
+    const err = await poll({
+      fn: async () => {
+        throw new Error('service unavailable');
+      },
+      timeoutMs: 50,
+      delayMs: 10,
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PollTimeoutError);
+    expect((err as PollTimeoutError).cause).toBeInstanceOf(Error);
+    expect(((err as PollTimeoutError).cause as Error).message).toBe('service unavailable');
+  });
+
+  it('cause is undefined when no errors occurred during polling', async () => {
+    const err = await poll({
+      fn: async () => ({ done: false }),
+      maxAttempts: 2,
+      delayMs: 1,
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PollExhaustedError);
+    expect((err as PollExhaustedError).cause).toBeUndefined();
+  });
+
   it('resets consecutive error count on success', async () => {
     let count = 0;
     const result = await poll({

src/lib/utils/polling.ts

@@ -24,15 +24,15 @@ export interface PollOptions<T> {
 }
 
 export class PollTimeoutError extends Error {
-  constructor(timeoutMs: number) {
-    super(`Polling timed out after ${timeoutMs}ms`);
+  constructor(timeoutMs: number, options?: { cause?: unknown }) {
+    super(`Polling timed out after ${timeoutMs}ms`, options);
     this.name = 'PollTimeoutError';
   }
 }
 
 export class PollExhaustedError extends Error {
-  constructor(maxAttempts: number) {
-    super(`Polling exhausted after ${maxAttempts} attempts`);
+  constructor(maxAttempts: number, options?: { cause?: unknown }) {
+    super(`Polling exhausted after ${maxAttempts} attempts`, options);
     this.name = 'PollExhaustedError';
   }
 }
@@ -57,13 +57,14 @@ export async function poll<T>(options: PollOptions<T>): Promise<T> {
   let attempts = 0;
   let consecutiveErrors = 0;
   let currentDelay = delayMs;
+  let lastError: unknown = undefined;
 
   while (true) {
     if (maxAttempts !== undefined && attempts >= maxAttempts) {
-      throw new PollExhaustedError(maxAttempts);
+      throw new PollExhaustedError(maxAttempts, { cause: lastError });
     }
     if (timeoutMs !== undefined && Date.now() - start >= timeoutMs) {
-      throw new PollTimeoutError(timeoutMs);
+      throw new PollTimeoutError(timeoutMs, { cause: lastError });
     }
 
     attempts++;
@@ -75,15 +76,16 @@ export async function poll<T>(options: PollOptions<T>): Promise<T> {
     } catch (err: unknown) {
       const action = onError ? onError(err) : 'retry';
       if (action === 'abort') throw err;
+      lastError = err;
       consecutiveErrors++;
       if (maxConsecutiveErrors && consecutiveErrors >= maxConsecutiveErrors) {
-        throw new PollExhaustedError(maxConsecutiveErrors);
+        throw new PollExhaustedError(attempts, { cause: lastError });
       }
     }
 
     // Don't sleep if we're about to exceed timeout
     if (timeoutMs !== undefined && Date.now() - start + currentDelay >= timeoutMs) {
-      throw new PollTimeoutError(timeoutMs);
+      throw new PollTimeoutError(timeoutMs, { cause: lastError });
     }
 
     await new Promise(resolve => setTimeout(resolve, currentDelay));