create-aws-project 1.5.1 → 1.7.0

package/dist/__tests__/config/non-interactive.spec.js

@@ -0,0 +1,152 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+// Mock picocolors to avoid console output issues in tests
+jest.unstable_mockModule('picocolors', () => ({
+    __esModule: true,
+    default: {
+        red: (s) => s,
+        green: (s) => s,
+        blue: (s) => s,
+        yellow: (s) => s,
+        cyan: (s) => s,
+        magenta: (s) => s,
+        bold: (s) => s,
+        dim: (s) => s,
+    },
+}));
+// Dynamic import after mocking
+const { loadNonInteractiveConfig } = await import('../../config/non-interactive.js');
+// Helper to write a temp config file and return its path
+function writeTempConfig(content) {
+    const tmpFile = join(tmpdir(), `non-interactive-test-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+    writeFileSync(tmpFile, typeof content === 'string' ? content : JSON.stringify(content));
+    return tmpFile;
+}
+describe('loadNonInteractiveConfig', () => {
+    beforeEach(() => {
+        // Mock process.exit to throw so tests can catch exit calls
+        jest.spyOn(process, 'exit').mockImplementation((() => {
+            throw new Error('process.exit called');
+        }));
+        // Suppress console.error output during tests
+        jest.spyOn(console, 'error').mockImplementation(() => { });
+    });
+    describe('schema defaults (NI-04)', () => {
+        it('applies all defaults when only name is provided', () => {
+            const tmpFile = writeTempConfig({ name: 'my-app' });
+            const config = loadNonInteractiveConfig(tmpFile);
+            expect(config.projectName).toBe('my-app');
+            expect(config.platforms).toEqual(['web', 'api']);
+            expect(config.auth.provider).toBe('none');
+            expect(config.auth.features).toEqual([]);
+            expect(config.features).toEqual(['github-actions', 'vscode-config']);
+            expect(config.awsRegion).toBe('us-east-1');
+            expect(config.brandColor).toBe('blue');
+        });
+        it('uses specified values when all fields provided', () => {
+            const tmpFile = writeTempConfig({
+                name: 'full-app',
+                platforms: ['web', 'mobile', 'api'],
+                auth: 'cognito',
+                authFeatures: ['social-login', 'mfa'],
+                features: ['github-actions'],
+                region: 'eu-west-1',
+                brandColor: 'purple',
+            });
+            const config = loadNonInteractiveConfig(tmpFile);
+            expect(config.projectName).toBe('full-app');
+            expect(config.platforms).toEqual(['web', 'mobile', 'api']);
+            expect(config.auth.provider).toBe('cognito');
+            expect(config.auth.features).toEqual(['social-login', 'mfa']);
+            expect(config.features).toEqual(['github-actions']);
+            expect(config.awsRegion).toBe('eu-west-1');
+            expect(config.brandColor).toBe('purple');
+        });
+    });
+    describe('schema validation (NI-05)', () => {
+        it('exits with error when name is missing', () => {
+            const tmpFile = writeTempConfig({});
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+            expect(console.error).toHaveBeenCalledWith(expect.stringContaining('name'));
+        });
+        it('exits with error when name is empty string', () => {
+            const tmpFile = writeTempConfig({ name: '' });
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+        it('exits with error for invalid platform value', () => {
+            const tmpFile = writeTempConfig({ name: 'x', platforms: ['invalid'] });
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+        it('exits with error for invalid auth provider', () => {
+            const tmpFile = writeTempConfig({ name: 'x', auth: 'firebase' });
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+        it('exits with error for invalid region', () => {
+            const tmpFile = writeTempConfig({ name: 'x', region: 'mars-1' });
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+        it('exits with error for invalid brand color', () => {
+            const tmpFile = writeTempConfig({ name: 'x', brandColor: 'red' });
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+        it('reports multiple validation failures at once', () => {
+            const tmpFile = writeTempConfig({
+                // name missing AND multiple invalid fields
+                platforms: ['bad'],
+                auth: 'bad',
+                region: 'bad',
+            });
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+            // At least 3 distinct error calls for the 3+ failing fields
+            expect(console.error.mock.calls.length).toBeGreaterThanOrEqual(3);
+        });
+    });
+    describe('auth normalization', () => {
+        it('silently drops authFeatures when auth is none', () => {
+            const tmpFile = writeTempConfig({
+                name: 'x',
+                auth: 'none',
+                authFeatures: ['social-login'],
+            });
+            const config = loadNonInteractiveConfig(tmpFile);
+            expect(config.auth.features).toEqual([]);
+        });
+        it('preserves authFeatures when auth is cognito', () => {
+            const tmpFile = writeTempConfig({
+                name: 'x',
+                auth: 'cognito',
+                authFeatures: ['mfa'],
+            });
+            const config = loadNonInteractiveConfig(tmpFile);
+            expect(config.auth.features).toEqual(['mfa']);
+        });
+    });
+    describe('file errors', () => {
+        it('exits with error for non-existent file', () => {
+            expect(() => loadNonInteractiveConfig('/nonexistent/path.json')).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+        it('exits with error for invalid JSON', () => {
+            const tmpFile = writeTempConfig('not json {{{');
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+    });
+    describe('project name validation', () => {
+        it('exits with error for invalid npm package name', () => {
+            // npm package names cannot have uppercase letters
+            const tmpFile = writeTempConfig({ name: 'UPPERCASE' });
+            expect(() => loadNonInteractiveConfig(tmpFile)).toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(1);
+        });
+    });
+});

package/dist/aws/cdk-bootstrap.d.ts

@@ -0,0 +1,77 @@
+import type { Ora } from 'ora';
+/**
+ * Credentials for AWS API operations
+ */
+export interface AWSCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/**
+ * Options for bootstrapping a single CDK environment
+ */
+export interface BootstrapCDKEnvironmentOptions {
+    accountId: string;
+    region: string;
+    credentials: AWSCredentials;
+}
+/**
+ * Result of a CDK bootstrap operation
+ */
+export interface BootstrapResult {
+    success: boolean;
+    output: string;
+}
+/**
+ * Options for bootstrapping all environments
+ */
+export interface BootstrapAllEnvironmentsOptions {
+    accounts: Record<string, string>;
+    region: string;
+    adminCredentials: AWSCredentials | null;
+    spinner: Ora;
+}
+/**
+ * Bootstraps AWS CDK in a single environment account
+ *
+ * Runs `cdk bootstrap` via npx to prepare the account for CDK deployments.
+ * Bootstrap creates the necessary CloudFormation stack with S3 bucket and ECR
+ * repository for CDK deployment assets.
+ *
+ * @param options - Bootstrap options including account ID, region, and credentials
+ * @returns Promise resolving to bootstrap result with success status and output
+ *
+ * @example
+ * ```typescript
+ * const result = await bootstrapCDKEnvironment({
+ *   accountId: '123456789012',
+ *   region: 'us-west-2',
+ *   credentials: { accessKeyId: 'AKIA...', secretAccessKey: 'secret...', sessionToken: 'token...' }
+ * });
+ * if (!result.success) {
+ *   console.error('Bootstrap failed:', result.output);
+ * }
+ * ```
+ */
+export declare function bootstrapCDKEnvironment(options: BootstrapCDKEnvironmentOptions): Promise<BootstrapResult>;
+/**
+ * Bootstraps AWS CDK in all environment accounts (dev, stage, prod)
+ *
+ * Iterates through all environments, assumes the OrganizationAccountAccessRole
+ * in each account, and runs CDK bootstrap. This prepares all environments for
+ * CDK deployments with proper trust relationships and execution policies.
+ *
+ * @param options - Bootstrap options including account map, region, admin credentials, and spinner
+ * @throws Error if bootstrap fails in any environment
+ *
+ * @example
+ * ```typescript
+ * await bootstrapAllEnvironments({
+ *   accounts: { dev: '111111111111', stage: '222222222222', prod: '333333333333' },
+ *   region: 'us-west-2',
+ *   adminCredentials: { accessKeyId: 'AKIA...', secretAccessKey: 'secret...' },
+ *   spinner: ora()
+ * });
+ * ```
+ */
+export declare function bootstrapAllEnvironments(options: BootstrapAllEnvironmentsOptions): Promise<void>;

package/dist/aws/cdk-bootstrap.js

@@ -0,0 +1,139 @@
+import { STSClient, AssumeRoleCommand } from '@aws-sdk/client-sts';
+import { execa } from 'execa';
+import pc from 'picocolors';
+/**
+ * AWS CDK Bootstrap module
+ *
+ * Provides functions to bootstrap AWS CDK in environment accounts,
+ * preparing them for CDK deployments with proper trust policies.
+ */
+const ENVIRONMENTS = ['dev', 'stage', 'prod'];
+/**
+ * Bootstraps AWS CDK in a single environment account
+ *
+ * Runs `cdk bootstrap` via npx to prepare the account for CDK deployments.
+ * Bootstrap creates the necessary CloudFormation stack with S3 bucket and ECR
+ * repository for CDK deployment assets.
+ *
+ * @param options - Bootstrap options including account ID, region, and credentials
+ * @returns Promise resolving to bootstrap result with success status and output
+ *
+ * @example
+ * ```typescript
+ * const result = await bootstrapCDKEnvironment({
+ *   accountId: '123456789012',
+ *   region: 'us-west-2',
+ *   credentials: { accessKeyId: 'AKIA...', secretAccessKey: 'secret...', sessionToken: 'token...' }
+ * });
+ * if (!result.success) {
+ *   console.error('Bootstrap failed:', result.output);
+ * }
+ * ```
+ */
+export async function bootstrapCDKEnvironment(options) {
+    const { accountId, region, credentials } = options;
+    try {
+        const args = [
+            'cdk',
+            'bootstrap',
+            `aws://${accountId}/${region}`,
+            '--trust',
+            accountId,
+            '--cloudformation-execution-policies',
+            'arn:aws:iam::aws:policy/AdministratorAccess',
+            '--require-approval',
+            'never',
+        ];
+        const env = {
+            ...process.env,
+            AWS_ACCESS_KEY_ID: credentials.accessKeyId,
+            AWS_SECRET_ACCESS_KEY: credentials.secretAccessKey,
+            AWS_REGION: region,
+        };
+        // Add session token if present (for temporary credentials)
+        if (credentials.sessionToken) {
+            env.AWS_SESSION_TOKEN = credentials.sessionToken;
+        }
+        const result = await execa('npx', args, {
+            all: true,
+            env,
+        });
+        return {
+            success: true,
+            output: result.all || '',
+        };
+    }
+    catch (error) {
+        const execaError = error;
+        return {
+            success: false,
+            output: execaError.all || execaError.message,
+        };
+    }
+}
+/**
+ * Bootstraps AWS CDK in all environment accounts (dev, stage, prod)
+ *
+ * Iterates through all environments, assumes the OrganizationAccountAccessRole
+ * in each account, and runs CDK bootstrap. This prepares all environments for
+ * CDK deployments with proper trust relationships and execution policies.
+ *
+ * @param options - Bootstrap options including account map, region, admin credentials, and spinner
+ * @throws Error if bootstrap fails in any environment
+ *
+ * @example
+ * ```typescript
+ * await bootstrapAllEnvironments({
+ *   accounts: { dev: '111111111111', stage: '222222222222', prod: '333333333333' },
+ *   region: 'us-west-2',
+ *   adminCredentials: { accessKeyId: 'AKIA...', secretAccessKey: 'secret...' },
+ *   spinner: ora()
+ * });
+ * ```
+ */
+export async function bootstrapAllEnvironments(options) {
+    const { accounts, region, adminCredentials, spinner } = options;
+    for (const env of ENVIRONMENTS) {
+        const accountId = accounts[env];
+        if (!accountId) {
+            continue;
+        }
+        spinner.text = `Bootstrapping CDK in ${env} account (${accountId})...`;
+        // Get cross-account credentials via STS AssumeRole
+        const stsClient = new STSClient({
+            region,
+            ...(adminCredentials && { credentials: adminCredentials }),
+        });
+        const assumeRoleCommand = new AssumeRoleCommand({
+            RoleArn: `arn:aws:iam::${accountId}:role/OrganizationAccountAccessRole`,
+            RoleSessionName: `create-aws-project-bootstrap-${Date.now()}`,
+            DurationSeconds: 900,
+        });
+        const assumeRoleResponse = await stsClient.send(assumeRoleCommand);
+        if (!assumeRoleResponse.Credentials?.AccessKeyId ||
+            !assumeRoleResponse.Credentials?.SecretAccessKey ||
+            !assumeRoleResponse.Credentials?.SessionToken) {
+            spinner.fail(`Failed to assume role in ${env} account`);
+            throw new Error(`Failed to get temporary credentials for ${env} account`);
+        }
+        const credentials = {
+            accessKeyId: assumeRoleResponse.Credentials.AccessKeyId,
+            secretAccessKey: assumeRoleResponse.Credentials.SecretAccessKey,
+            sessionToken: assumeRoleResponse.Credentials.SessionToken,
+        };
+        // Bootstrap the environment
+        const result = await bootstrapCDKEnvironment({
+            accountId,
+            region,
+            credentials,
+        });
+        if (!result.success) {
+            spinner.fail(`CDK bootstrap failed in ${env} account`);
+            console.error(pc.red('Bootstrap error:'));
+            console.error(result.output);
+            throw new Error(`CDK bootstrap failed in ${env} account`);
+        }
+        spinner.succeed(`CDK bootstrapped in ${env} account (${accountId})`);
+    }
+    console.log(pc.green('All environments bootstrapped for CDK deployments!'));
+}

package/dist/aws/iam.js

@@ -210,6 +210,23 @@ function getCDKDeploymentPolicyDocument(accountId) {
                 ],
                 Resource: '*',
             },
+            {
+                Sid: 'S3ListBuckets',
+                Effect: 'Allow',
+                Action: 's3:ListAllMyBuckets',
+                Resource: '*',
+            },
+            {
+                Sid: 'AccessWebBucket',
+                Effect: 'Allow',
+                Action: [
+                    's3:*'
+                ],
+                Resource: [
+                    `arn:aws:s3:::*-development-web-${accountId}`,
+                    `arn:aws:s3:::*-development-web-${accountId}/*`,
+                ],
+            },
         ],
     };
     return JSON.stringify(policy);

package/dist/aws/organizations.d.ts

@@ -1,4 +1,4 @@
-import { OrganizationsClient } from '@aws-sdk/client-organizations';
+import { OrganizationsClient, Account } from '@aws-sdk/client-organizations';
 /**
  * AWS Organizations service module
  *
@@ -17,6 +17,12 @@ export declare function createOrganizationsClient(region?: string): Organization
  * @returns Organization ID if exists, null if not in an organization
  */
 export declare function checkExistingOrganization(client: OrganizationsClient): Promise<string | null>;
+/**
+ * Lists all accounts in the AWS Organization with automatic pagination handling
+ * @param client - OrganizationsClient instance
+ * @returns Array of Account objects from the organization
+ */
+export declare function listOrganizationAccounts(client: OrganizationsClient): Promise<Account[]>;
 /**
  * Creates a new AWS Organization with all features enabled
  * @param client - OrganizationsClient instance

package/dist/aws/organizations.js

@@ -1,4 +1,4 @@
-import { OrganizationsClient, CreateOrganizationCommand, CreateAccountCommand, DescribeCreateAccountStatusCommand, DescribeOrganizationCommand, AlreadyInOrganizationException, } from '@aws-sdk/client-organizations';
+import { OrganizationsClient, CreateOrganizationCommand, CreateAccountCommand, DescribeCreateAccountStatusCommand, DescribeOrganizationCommand, AlreadyInOrganizationException, ListAccountsCommand, } from '@aws-sdk/client-organizations';
 import pc from 'picocolors';
 /**
  * AWS Organizations service module
@@ -33,6 +33,24 @@ export async function checkExistingOrganization(client) {
         throw error;
     }
 }
+/**
+ * Lists all accounts in the AWS Organization with automatic pagination handling
+ * @param client - OrganizationsClient instance
+ * @returns Array of Account objects from the organization
+ */
+export async function listOrganizationAccounts(client) {
+    const accounts = [];
+    let nextToken;
+    do {
+        const command = new ListAccountsCommand({ NextToken: nextToken });
+        const response = await client.send(command);
+        if (response.Accounts) {
+            accounts.push(...response.Accounts);
+        }
+        nextToken = response.NextToken;
+    } while (nextToken);
+    return accounts;
+}
 /**
  * Creates a new AWS Organization with all features enabled
  * @param client - OrganizationsClient instance

package/dist/aws/root-credentials.d.ts

@@ -0,0 +1,68 @@
+import { IAMClient } from '@aws-sdk/client-iam';
+/**
+ * AWS Root Credential Detection and Admin User Management
+ *
+ * Provides functions to detect root credentials and create/adopt admin IAM users
+ * in the management account for cross-account operations.
+ */
+/**
+ * Caller identity information from STS GetCallerIdentity
+ */
+export interface CallerIdentity {
+    arn: string;
+    accountId: string;
+    userId: string;
+    isRoot: boolean;
+}
+/**
+ * Admin user creation result
+ */
+export interface AdminUserResult {
+    userName: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    adopted: boolean;
+}
+/**
+ * Checks if an ARN represents a root user
+ * @param arn - AWS ARN to check
+ * @returns true if ARN ends with :root
+ */
+export declare function isRootUser(arn: string): boolean;
+/**
+ * Detects if the current AWS credentials are for a root user
+ * @param region - AWS region for STS client
+ * @returns Caller identity with root status flag
+ */
+export declare function detectRootCredentials(region: string): Promise<CallerIdentity>;
+/**
+ * Retries a function with exponential backoff
+ * @param fn - Async function to retry
+ * @param options - Retry configuration
+ * @returns Result of the function
+ * @throws Last error if all retries fail
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    description?: string;
+}): Promise<T>;
+/**
+ * Creates access key for admin user
+ * @param client - IAMClient instance
+ * @param userName - Admin user name
+ * @returns Access key credentials
+ * @throws Error if user already has 2 access keys
+ */
+export declare function createAccessKeyForAdmin(client: IAMClient, userName: string): Promise<{
+    accessKeyId: string;
+    secretAccessKey: string;
+}>;
+/**
+ * Creates or adopts an admin user in the management account
+ * @param client - IAMClient instance
+ * @param projectName - Project name for user naming
+ * @returns Admin user credentials
+ * @throws Error if user exists but not managed by this tool or has existing keys
+ */
+export declare function createOrAdoptAdminUser(client: IAMClient, projectName: string): Promise<AdminUserResult>;

package/dist/aws/root-credentials.js

@@ -0,0 +1,157 @@
+import { CreateUserCommand, GetUserCommand, AttachUserPolicyCommand, CreateAccessKeyCommand, ListUserTagsCommand, NoSuchEntityException, } from '@aws-sdk/client-iam';
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import pc from 'picocolors';
+import { getAccessKeyCount } from './iam.js';
+/**
+ * Checks if an ARN represents a root user
+ * @param arn - AWS ARN to check
+ * @returns true if ARN ends with :root
+ */
+export function isRootUser(arn) {
+    return arn.endsWith(':root');
+}
+/**
+ * Detects if the current AWS credentials are for a root user
+ * @param region - AWS region for STS client
+ * @returns Caller identity with root status flag
+ */
+export async function detectRootCredentials(region) {
+    const client = new STSClient({ region });
+    const command = new GetCallerIdentityCommand({});
+    const response = await client.send(command);
+    if (!response.Arn || !response.Account || !response.UserId) {
+        throw new Error('GetCallerIdentity returned incomplete response');
+    }
+    return {
+        arn: response.Arn,
+        accountId: response.Account,
+        userId: response.UserId,
+        isRoot: isRootUser(response.Arn),
+    };
+}
+/**
+ * Helper function to sleep for retry backoff
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retries a function with exponential backoff
+ * @param fn - Async function to retry
+ * @param options - Retry configuration
+ * @returns Result of the function
+ * @throws Last error if all retries fail
+ */
+export async function retryWithBackoff(fn, options) {
+    const maxRetries = options?.maxRetries ?? 5;
+    const baseDelayMs = options?.baseDelayMs ?? 1000;
+    const description = options?.description ?? 'operation';
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxRetries) {
+                const delay = baseDelayMs * Math.pow(2, attempt);
+                console.log(pc.dim(`  Retrying ${description} (attempt ${attempt + 1}/${maxRetries})...`));
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Creates access key for admin user
+ * @param client - IAMClient instance
+ * @param userName - Admin user name
+ * @returns Access key credentials
+ * @throws Error if user already has 2 access keys
+ */
+export async function createAccessKeyForAdmin(client, userName) {
+    // Check access key limit before attempting creation
+    const keyCount = await getAccessKeyCount(client, userName);
+    if (keyCount >= 2) {
+        throw new Error(`IAM user ${userName} already has 2 access keys (AWS maximum). Delete an existing key in AWS Console > IAM > Users > ${userName} > Security credentials before retrying.`);
+    }
+    const command = new CreateAccessKeyCommand({
+        UserName: userName,
+    });
+    const response = await client.send(command);
+    if (!response.AccessKey?.AccessKeyId || !response.AccessKey?.SecretAccessKey) {
+        throw new Error('Access key created but credentials not returned');
+    }
+    console.log(pc.green(`  Created access key for ${userName}`));
+    return {
+        accessKeyId: response.AccessKey.AccessKeyId,
+        secretAccessKey: response.AccessKey.SecretAccessKey,
+    };
+}
+/**
+ * Creates or adopts an admin user in the management account
+ * @param client - IAMClient instance
+ * @param projectName - Project name for user naming
+ * @returns Admin user credentials
+ * @throws Error if user exists but not managed by this tool or has existing keys
+ */
+export async function createOrAdoptAdminUser(client, projectName) {
+    const userName = `${projectName}-admin`;
+    // Check if user already exists
+    try {
+        await client.send(new GetUserCommand({ UserName: userName }));
+        // User exists - check if managed by us
+        const tagsCommand = new ListUserTagsCommand({ UserName: userName });
+        const tagsResponse = await client.send(tagsCommand);
+        const isManagedByUs = tagsResponse.Tags?.some((tag) => tag.Key === 'ManagedBy' && tag.Value === 'create-aws-starter-kit') ?? false;
+        if (!isManagedByUs) {
+            throw new Error(`IAM user "${userName}" exists but was not created by this tool. Delete it or use a different project name.`);
+        }
+        // Managed by us - check key count
+        const keyCount = await getAccessKeyCount(client, userName);
+        if (keyCount >= 1) {
+            throw new Error(`IAM user "${userName}" already exists with ${keyCount} access key(s). This tool cannot retrieve existing secret keys. Please delete all access keys for this user in AWS Console > IAM > Users > ${userName} > Security credentials, or provide IAM credentials directly instead of using root credentials.`);
+        }
+        // No keys - create new key and adopt
+        console.log(pc.yellow(`  Adopting existing admin user: ${userName}`));
+        const credentials = await retryWithBackoff(() => createAccessKeyForAdmin(client, userName), { description: 'access key creation' });
+        return {
+            userName,
+            accessKeyId: credentials.accessKeyId,
+            secretAccessKey: credentials.secretAccessKey,
+            adopted: true,
+        };
+    }
+    catch (error) {
+        // User doesn't exist - create new
+        if (error instanceof NoSuchEntityException) {
+            console.log(pc.cyan(`  Creating admin user: ${userName}`));
+            // Create user
+            await client.send(new CreateUserCommand({
+                UserName: userName,
+                Path: '/admin/',
+                Tags: [
+                    { Key: 'Purpose', Value: 'CLI Admin' },
+                    { Key: 'ManagedBy', Value: 'create-aws-starter-kit' },
+                ],
+            }));
+            console.log(pc.green(`  Created IAM user: ${userName}`));
+            // Attach AdministratorAccess policy
+            await client.send(new AttachUserPolicyCommand({
+                UserName: userName,
+                PolicyArn: 'arn:aws:iam::aws:policy/AdministratorAccess',
+            }));
+            console.log(pc.green(`  Attached AdministratorAccess policy`));
+            // Create access key with retry for IAM eventual consistency
+            const credentials = await retryWithBackoff(() => createAccessKeyForAdmin(client, userName), { description: 'access key creation after user creation' });
+            return {
+                userName,
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                adopted: false,
+            };
+        }
+        // Other error - propagate
+        throw error;
+    }
+}