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

result-work

@@ -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/__tests__/transaction-search.test.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/index.ts

@@ -1,4 +1,5 @@
-import { getErrorMessage, isAccessDeniedError } from '../errors';
+import type { Result } from '../../lib/types';
+import { AccessDeniedError, getErrorMessage, isAccessDeniedError } from '../errors';
 import { getCredentialProvider } from './account';
 import { arnPrefix } from './partition';
 import { ApplicationSignalsClient, StartDiscoveryCommand } from '@aws-sdk/client-application-signals';
@@ -14,11 +15,6 @@ import {
   XRayClient,
 } from '@aws-sdk/client-xray';
 
-export interface TransactionSearchEnableResult {
-  success: boolean;
-  error?: string;
-}
-
 const RESOURCE_POLICY_NAME = 'TransactionSearchXRayAccess';
 
 /**
@@ -34,7 +30,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 +40,12 @@ 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}`),
+      };
     }
-    return { success: false, error: `Failed to enable Application Signals: ${message}` };
+    return { success: false, error: new Error(`Failed to enable Application Signals: ${message}`) };
   }
 
   // Step 2: Create CloudWatch Logs resource policy for X-Ray (if needed)
@@ -80,9 +79,12 @@ 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}`),
+      };
     }
-    return { success: false, error: `Failed to configure CloudWatch Logs policy: ${message}` };
+    return { success: false, error: new Error(`Failed to configure CloudWatch Logs policy: ${message}`) };
   }
 
   const xrayClient = new XRayClient({ region, credentials });
@@ -96,9 +98,12 @@ 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}`),
+      };
     }
-    return { success: false, error: `Failed to configure trace destination: ${message}` };
+    return { success: false, error: new Error(`Failed to configure trace destination: ${message}`) };
   }
 
   // Step 4: Set indexing to 100% on the built-in Default rule (always exists, idempotent)
@@ -112,9 +117,12 @@ 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}`),
+      };
     }
-    return { success: false, error: `Failed to configure indexing rules: ${message}` };
+    return { success: false, error: new Error(`Failed to configure indexing rules: ${message}`) };
   }
 
   return { success: true };

src/cli/aws/transaction-search.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/add/types.ts

@@ -8,7 +8,7 @@ import type {
   SDKFramework,
   TargetLanguage,
 } from '../../../schema';
-import { getErrorMessage } from '../../errors';
+import { DependencyCheckError, GitInitError, 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 +57,7 @@ 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) };
     }
   }
 
@@ -93,7 +93,7 @@ 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') };
       }
       onProgress?.('Initialize git repository', 'done');
     }
@@ -104,7 +104,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) };
   }
 }
 
@@ -174,7 +174,7 @@ 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) };
   }
 
   // First create the base project (skip dependency check since we already did it)
@@ -187,9 +187,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;
   }
 
   // Import path: delegate to executeImportAgent after project scaffolding
@@ -207,7 +205,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 +215,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) };
     }
   }
 
@@ -310,7 +308,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) };
   }
 }
 

src/cli/commands/create/action.ts

@@ -1,4 +1,4 @@
-import { getWorkingDirectory } from '../../../lib';
+import { getWorkingDirectory, resultToJson } from '../../../lib';
 import type {
   BuildType,
   ModelProvider,
@@ -93,8 +93,8 @@ async function handleCreateCLI(options: CreateOptions): Promise<void> {
   if (options.dryRun) {
     const result = getDryRunInfo({ name: name!, projectName, cwd, language: options.language });
     if (options.json) {
-      console.log(JSON.stringify(result));
-    } else {
+      console.log(resultToJson(result));
+    } else if (result.success) {
       console.log('Dry run - would create:');
       for (const path of result.wouldCreate ?? []) {
         console.log(`  ${path}`);
@@ -158,7 +158,7 @@ async function handleCreateCLI(options: CreateOptions): Promise<void> {
       });
 
   if (options.json) {
-    console.log(JSON.stringify(result));
+    console.log(resultToJson(result));
   } else if (result.success) {
     printCreateSummary(projectName!, result.agentName, options.language, options.framework);
     if (options.skipInstall) {

src/cli/commands/create/command.tsx

@@ -1,3 +1,4 @@
+import type { Result } from '../../../lib/types';
 import type { VpcOptions } from '../shared/vpc-utils';
 
 export interface CreateOptions extends VpcOptions {
@@ -28,12 +29,10 @@ export interface CreateOptions extends VpcOptions {
   json?: boolean;
 }
 
-export interface CreateResult {
-  success: boolean;
+export type CreateResult = Result<{
   projectPath?: string;
   agentName?: string;
-  error?: string;
   dryRun?: boolean;
   wouldCreate?: string[];
   warnings?: string[];
-}
+}>;