refactor: unify result types with discriminated Result<T, E> union

Introduce a shared Result<T, E> type (inspired by Rust's Result) that
replaces ad-hoc { success: boolean; error?: string } patterns across
the codebase.

Key changes:
- Add src/lib/types.ts with Result<T, E> discriminated union type
- Add toError() helper in src/cli/errors.ts for catch blocks
- Migrate all command, operation, and primitive result types to Result<T>
- Error field is now Error (not string) on the failure branch
- Data fields only exist on the success branch (proper narrowing)
- Update all consumers to narrow before accessing branch-specific fields
- Update test assertions to match new Error objects and add narrowing

Author: Hweinstock

src/cli/__tests__/errors.test.ts

@@ -1,10 +1,11 @@
+import { AgentAlreadyExistsError } from '../../lib';
 import {
-  AgentAlreadyExistsError,
   getErrorMessage,
   isChangesetInProgressError,
   isExpiredTokenError,
   isNoCredentialsError,
   isStackInProgressError,
+  toError,
 } from '../errors.js';
 import { describe, expect, it } from 'vitest';
 
@@ -204,4 +205,35 @@ describe('errors', () => {
       expect(isChangesetInProgressError({})).toBe(false);
     });
   });
+
+  describe('toError', () => {
+    it('returns Error instance as-is', () => {
+      const err = new Error('original');
+      expect(toError(err)).toBe(err);
+    });
+
+    it('wraps string in Error', () => {
+      const result = toError('string error');
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toBe('string error');
+    });
+
+    it('handles null', () => {
+      const result = toError(null);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toBe('null');
+    });
+
+    it('handles undefined', () => {
+      const result = toError(undefined);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toBe('undefined');
+    });
+
+    it('handles non-Error objects', () => {
+      const result = toError({ code: 42 });
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toBe('[object Object]');
+    });
+  });
 });

src/cli/aws/__tests__/transaction-search.test.ts

@@ -1,4 +1,5 @@
 import { enableTransactionSearch } from '../transaction-search.js';
+import assert from 'node:assert';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 const { mockAppSignalsSend, mockLogsSend, mockXRaySend } = vi.hoisted(() => ({
@@ -162,17 +163,17 @@ describe('enableTransactionSearch', () => {
 
       const result = await enableTransactionSearch('us-east-1', '123456789012');
 
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('Insufficient permissions to enable Application Signals');
+      assert(!result.success);
+      expect(result.error.message).toContain('Insufficient permissions to enable Application Signals');
     });
 
     it('returns error when Application Signals fails with generic error', async () => {
       mockAppSignalsSend.mockRejectedValue(new Error('Service unavailable'));
 
       const result = await enableTransactionSearch('us-east-1', '123456789012');
 
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('Failed to enable Application Signals');
+      assert(!result.success);
+      expect(result.error.message).toContain('Failed to enable Application Signals');
     });
 
     it('returns error when CloudWatch Logs policy fails with AccessDenied', async () => {
@@ -183,8 +184,8 @@ describe('enableTransactionSearch', () => {
 
       const result = await enableTransactionSearch('us-east-1', '123456789012');
 
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('Insufficient permissions to configure CloudWatch Logs policy');
+      assert(!result.success);
+      expect(result.error.message).toContain('Insufficient permissions to configure CloudWatch Logs policy');
     });
 
     it('returns error when trace destination fails', async () => {
@@ -194,8 +195,8 @@ describe('enableTransactionSearch', () => {
 
       const result = await enableTransactionSearch('us-east-1', '123456789012');
 
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('Failed to configure trace destination');
+      assert(!result.success);
+      expect(result.error.message).toContain('Failed to configure trace destination');
     });
 
     it('returns error when indexing rule update fails', async () => {
@@ -214,8 +215,8 @@ describe('enableTransactionSearch', () => {
 
       const result = await enableTransactionSearch('us-east-1', '123456789012');
 
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('Failed to configure indexing rules');
+      assert(!result.success);
+      expect(result.error.message).toContain('Failed to configure indexing rules');
     });
 
     it('does not proceed to later steps when an earlier step fails', async () => {

src/cli/aws/index.ts

@@ -17,7 +17,7 @@ export {
   type GetAgentRuntimeStatusOptions,
 } from './agentcore-control';
 export { streamLogs, searchLogs, type LogEvent, type StreamLogsOptions, type SearchLogsOptions } from './cloudwatch';
-export { enableTransactionSearch, type TransactionSearchEnableResult } from './transaction-search';
+export { enableTransactionSearch } from './transaction-search';
 export {
   startPolicyGeneration,
   getPolicyGeneration,

src/cli/aws/transaction-search.ts

@@ -1,3 +1,5 @@
+import { AccessDeniedError } from '../../lib';
+import type { Result } from '../../lib/result';
 import { getErrorMessage, isAccessDeniedError } from '../errors';
 import { getCredentialProvider } from './account';
 import { arnPrefix } from './partition';
@@ -14,11 +16,6 @@ import {
   XRayClient,
 } from '@aws-sdk/client-xray';
 
-export interface TransactionSearchEnableResult {
-  success: boolean;
-  error?: string;
-}
-
 const RESOURCE_POLICY_NAME = 'TransactionSearchXRayAccess';
 
 /**
@@ -34,7 +31,7 @@ export async function enableTransactionSearch(
   region: string,
   accountId: string,
   indexPercentage = 100
-): Promise<TransactionSearchEnableResult> {
+): Promise<Result> {
   const credentials = getCredentialProvider();
 
   // Step 1: Enable Application Signals (creates service-linked role, idempotent)
@@ -44,9 +41,14 @@ export async function enableTransactionSearch(
   } catch (err: unknown) {
     const message = getErrorMessage(err);
     if (isAccessDeniedError(err)) {
-      return { success: false, error: `Insufficient permissions to enable Application Signals: ${message}` };
+      return {
+        success: false,
+        error: new AccessDeniedError(`Insufficient permissions to enable Application Signals: ${message}`, {
+          cause: err,
+        }),
+      };
     }
-    return { success: false, error: `Failed to enable Application Signals: ${message}` };
+    return { success: false, error: new Error(`Failed to enable Application Signals: ${message}`, { cause: err }) };
   }
 
   // Step 2: Create CloudWatch Logs resource policy for X-Ray (if needed)
@@ -80,9 +82,17 @@ export async function enableTransactionSearch(
   } catch (err: unknown) {
     const message = getErrorMessage(err);
     if (isAccessDeniedError(err)) {
-      return { success: false, error: `Insufficient permissions to configure CloudWatch Logs policy: ${message}` };
+      return {
+        success: false,
+        error: new AccessDeniedError(`Insufficient permissions to configure CloudWatch Logs policy: ${message}`, {
+          cause: err,
+        }),
+      };
     }
-    return { success: false, error: `Failed to configure CloudWatch Logs policy: ${message}` };
+    return {
+      success: false,
+      error: new Error(`Failed to configure CloudWatch Logs policy: ${message}`, { cause: err }),
+    };
   }
 
   const xrayClient = new XRayClient({ region, credentials });
@@ -96,9 +106,14 @@ export async function enableTransactionSearch(
   } catch (err: unknown) {
     const message = getErrorMessage(err);
     if (isAccessDeniedError(err)) {
-      return { success: false, error: `Insufficient permissions to configure trace destination: ${message}` };
+      return {
+        success: false,
+        error: new AccessDeniedError(`Insufficient permissions to configure trace destination: ${message}`, {
+          cause: err,
+        }),
+      };
     }
-    return { success: false, error: `Failed to configure trace destination: ${message}` };
+    return { success: false, error: new Error(`Failed to configure trace destination: ${message}`, { cause: err }) };
   }
 
   // Step 4: Set indexing to 100% on the built-in Default rule (always exists, idempotent)
@@ -112,9 +127,14 @@ export async function enableTransactionSearch(
   } catch (err: unknown) {
     const message = getErrorMessage(err);
     if (isAccessDeniedError(err)) {
-      return { success: false, error: `Insufficient permissions to configure indexing rules: ${message}` };
+      return {
+        success: false,
+        error: new AccessDeniedError(`Insufficient permissions to configure indexing rules: ${message}`, {
+          cause: err,
+        }),
+      };
     }
-    return { success: false, error: `Failed to configure indexing rules: ${message}` };
+    return { success: false, error: new Error(`Failed to configure indexing rules: ${message}`, { cause: err }) };
   }
 
   return { success: true };

src/cli/commands/add/types.ts

@@ -41,13 +41,6 @@ export interface AddAgentOptions extends VpcOptions {
   json?: boolean;
 }
 
-export interface AddAgentResult {
-  success: boolean;
-  agentName?: string;
-  agentPath?: string;
-  error?: string;
-}
-
 // Gateway types
 export interface AddGatewayOptions {
   name?: string;
@@ -68,12 +61,6 @@ export interface AddGatewayOptions {
   json?: boolean;
 }
 
-export interface AddGatewayResult {
-  success: boolean;
-  gatewayName?: string;
-  error?: string;
-}
-
 // Gateway Target types
 export interface AddGatewayTargetOptions {
   name?: string;
@@ -100,13 +87,6 @@ export interface AddGatewayTargetOptions {
   json?: boolean;
 }
 
-export interface AddGatewayTargetResult {
-  success: boolean;
-  toolName?: string;
-  sourcePath?: string;
-  error?: string;
-}
-
 // Memory types (v2: no owner/user concept)
 export interface AddMemoryOptions {
   name?: string;
@@ -119,12 +99,6 @@ export interface AddMemoryOptions {
   json?: boolean;
 }
 
-export interface AddMemoryResult {
-  success: boolean;
-  memoryName?: string;
-  error?: string;
-}
-
 // Credential types (v2: credential, no owner/user concept)
 export interface AddCredentialOptions {
   name?: string;
@@ -139,9 +113,3 @@ export interface AddCredentialOptions {
 
 /** @deprecated Use AddCredentialOptions */
 export type AddIdentityOptions = AddCredentialOptions;
-
-export interface AddCredentialResult {
-  success: boolean;
-  credentialName?: string;
-  error?: string;
-}

src/cli/commands/create/action.ts

@@ -1,4 +1,12 @@
-import { APP_DIR, CONFIG_DIR, ConfigIO, setEnvVar, setSessionProjectRoot } from '../../../lib';
+import {
+  APP_DIR,
+  CONFIG_DIR,
+  ConfigIO,
+  DependencyCheckError,
+  GitInitError,
+  setEnvVar,
+  setSessionProjectRoot,
+} from '../../../lib';
 import type {
   BuildType,
   DeployedState,
@@ -8,7 +16,7 @@ import type {
   SDKFramework,
   TargetLanguage,
 } from '../../../schema';
-import { getErrorMessage } from '../../errors';
+import { toError } from '../../errors';
 import { checkCreateDependencies } from '../../external-requirements';
 import { initGitRepo, setupPythonProject, writeEnvFile, writeGitignore } from '../../operations';
 import { createConfigBundleForAgent } from '../../operations/agent/config-bundle-defaults';
@@ -57,7 +65,11 @@ export async function createProject(options: CreateProjectOptions): Promise<Crea
 
     // Fail on errors
     if (!depCheck.passed) {
-      return { success: false, error: depCheck.errors.join('\n'), warnings: depWarnings };
+      return {
+        success: false,
+        error: new DependencyCheckError(depCheck.errors),
+        warnings: depWarnings.length > 0 ? depWarnings : undefined,
+      };
     }
   }
 
@@ -93,7 +105,11 @@ export async function createProject(options: CreateProjectOptions): Promise<Crea
       const gitResult = await initGitRepo(projectRoot);
       if (gitResult.status === 'error') {
         onProgress?.('Initialize git repository', 'error');
-        return { success: false, error: gitResult.message, warnings: depWarnings };
+        return {
+          success: false,
+          error: new GitInitError(gitResult.message ?? 'Git initialization failed'),
+          warnings: depWarnings.length > 0 ? depWarnings : undefined,
+        };
       }
       onProgress?.('Initialize git repository', 'done');
     }
@@ -104,7 +120,7 @@ export async function createProject(options: CreateProjectOptions): Promise<Crea
       warnings: depWarnings.length > 0 ? depWarnings : undefined,
     };
   } catch (err) {
-    return { success: false, error: getErrorMessage(err), warnings: depWarnings };
+    return { success: false, error: toError(err), warnings: depWarnings.length > 0 ? depWarnings : undefined };
   }
 }
 
@@ -174,7 +190,11 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
 
   // Fail on errors
   if (!depCheck.passed) {
-    return { success: false, error: depCheck.errors.join('\n'), warnings: depWarnings };
+    return {
+      success: false,
+      error: new DependencyCheckError(depCheck.errors),
+      warnings: depWarnings.length > 0 ? depWarnings : undefined,
+    };
   }
 
   // First create the base project (skip dependency check since we already did it)
@@ -187,9 +207,7 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
     onProgress,
   });
   if (!projectResult.success) {
-    // Merge warnings from both checks
-    const allWarnings = [...depWarnings, ...(projectResult.warnings ?? [])];
-    return { ...projectResult, warnings: allWarnings.length > 0 ? allWarnings : undefined };
+    return { ...projectResult, warnings: depWarnings.length > 0 ? depWarnings : projectResult.warnings };
   }
 
   // Import path: delegate to executeImportAgent after project scaffolding
@@ -207,7 +225,7 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
       });
       if (!importResult.success) {
         onProgress?.('Import agent from Bedrock', 'error');
-        return { success: false, error: importResult.error, warnings: depWarnings };
+        return importResult;
       }
       onProgress?.('Import agent from Bedrock', 'done');
       return {
@@ -217,7 +235,7 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
         warnings: depWarnings.length > 0 ? depWarnings : undefined,
       };
     } catch (err) {
-      return { success: false, error: getErrorMessage(err), warnings: depWarnings };
+      return { success: false, error: toError(err), warnings: depWarnings.length > 0 ? depWarnings : undefined };
     }
   }
 
@@ -310,7 +328,7 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
       warnings: depWarnings.length > 0 ? depWarnings : undefined,
     };
   } catch (err) {
-    return { success: false, error: getErrorMessage(err), warnings: depWarnings };
+    return { success: false, error: toError(err), warnings: depWarnings.length > 0 ? depWarnings : undefined };
   }
 }