create-aws-project 1.2.1

package/dist/__tests__/wizard.spec.js

@@ -0,0 +1,232 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+// Create a mock function for prompts
+const mockPrompts = jest.fn();
+// Mock prompts module
+jest.unstable_mockModule('prompts', () => ({
+    __esModule: true,
+    default: mockPrompts,
+}));
+// Mock picocolors to avoid console output issues
+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 { runWizard } = await import('../wizard.js');
+describe('runWizard', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Mock process.exit to prevent test from exiting
+        jest.spyOn(process, 'exit').mockImplementation((() => {
+            throw new Error('process.exit called');
+        }));
+    });
+    describe('successful completion', () => {
+        it('should return complete ProjectConfig when all prompts answered', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'my-test-app',
+                platforms: ['web', 'api'],
+                authProvider: 'none',
+                authFeatures: [],
+                features: ['github-actions'],
+                awsRegion: 'us-east-1',
+                brandColor: 'blue',
+            });
+            const result = await runWizard();
+            expect(result).not.toBeNull();
+            expect(result).toEqual({
+                projectName: 'my-test-app',
+                platforms: ['web', 'api'],
+                features: ['github-actions'],
+                awsRegion: 'us-east-1',
+                brandColor: 'blue',
+                auth: { provider: 'none', features: [] },
+            });
+        });
+        it('should return config with all platforms selected', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'full-stack-app',
+                platforms: ['web', 'mobile', 'api'],
+                authProvider: 'none',
+                authFeatures: [],
+                features: ['github-actions', 'vscode-config'],
+                awsRegion: 'eu-west-1',
+                brandColor: 'purple',
+            });
+            const result = await runWizard();
+            expect(result).not.toBeNull();
+            expect(result?.platforms).toEqual(['web', 'mobile', 'api']);
+            expect(result?.features).toEqual(['github-actions', 'vscode-config']);
+        });
+        it('should default features to empty array when none selected', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'minimal-app',
+                platforms: ['api'],
+                authProvider: 'none',
+                authFeatures: [],
+                features: undefined, // No features selected
+                awsRegion: 'ap-southeast-1',
+                brandColor: 'teal',
+            });
+            const result = await runWizard();
+            expect(result).not.toBeNull();
+            expect(result?.features).toEqual([]);
+        });
+    });
+    describe('incomplete responses', () => {
+        it('should return null when projectName is missing', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: undefined,
+                platforms: ['web'],
+                awsRegion: 'us-east-1',
+                brandColor: 'blue',
+            });
+            const result = await runWizard();
+            expect(result).toBeNull();
+        });
+        it('should return null when platforms is empty', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'my-app',
+                platforms: [],
+                awsRegion: 'us-east-1',
+                brandColor: 'blue',
+            });
+            const result = await runWizard();
+            expect(result).toBeNull();
+        });
+        it('should return null when awsRegion is missing', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'my-app',
+                platforms: ['web'],
+                awsRegion: undefined,
+                brandColor: 'blue',
+            });
+            const result = await runWizard();
+            expect(result).toBeNull();
+        });
+        it('should return null when brandColor is missing', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'my-app',
+                platforms: ['web'],
+                awsRegion: 'us-east-1',
+                brandColor: undefined,
+            });
+            const result = await runWizard();
+            expect(result).toBeNull();
+        });
+    });
+    describe('cancellation', () => {
+        it('should exit when user cancels via onCancel', async () => {
+            // Simulate prompts calling onCancel by storing the callback and calling it
+            let storedOnCancel;
+            mockPrompts.mockImplementationOnce(((_questions, options) => {
+                storedOnCancel = options?.onCancel;
+                // Trigger onCancel before returning
+                if (storedOnCancel) {
+                    storedOnCancel({}, {});
+                }
+                return Promise.resolve({});
+            }));
+            await expect(runWizard()).rejects.toThrow('process.exit called');
+            expect(process.exit).toHaveBeenCalledWith(0);
+        });
+    });
+    describe('config structure verification', () => {
+        it('should return config with all expected fields', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'test-app',
+                platforms: ['web'],
+                authProvider: 'none',
+                authFeatures: [],
+                features: [],
+                awsRegion: 'us-east-1',
+                brandColor: 'green',
+            });
+            const result = await runWizard();
+            expect(result).not.toBeNull();
+            expect(result).toHaveProperty('projectName');
+            expect(result).toHaveProperty('platforms');
+            expect(result).toHaveProperty('features');
+            expect(result).toHaveProperty('awsRegion');
+            expect(result).toHaveProperty('brandColor');
+            expect(result).toHaveProperty('auth');
+        });
+        it('should pass correct prompts to prompts library', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'my-app',
+                platforms: ['web'],
+                authProvider: 'none',
+                authFeatures: [],
+                features: [],
+                awsRegion: 'us-east-1',
+                brandColor: 'orange',
+            });
+            await runWizard();
+            expect(mockPrompts).toHaveBeenCalledTimes(1);
+            const [promptsArg] = mockPrompts.mock.calls[0];
+            // Verify 15 prompts are passed (projectName, platforms, authProvider, authFeatures, features, awsRegion,
+            // enableOrg, orgName, orgEnvironments, devEmail, stageEmail, prodEmail, qaEmail, sandboxEmail, brandColor)
+            expect(Array.isArray(promptsArg)).toBe(true);
+            expect(promptsArg.length).toBe(15);
+        });
+    });
+    describe('auth configuration', () => {
+        it('should return ProjectConfig with Cognito auth and features', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'auth-test-app',
+                platforms: ['web', 'api'],
+                authProvider: 'cognito',
+                authFeatures: ['social-login', 'mfa'],
+                features: [],
+                awsRegion: 'us-east-1',
+                brandColor: 'blue',
+            });
+            const result = await runWizard();
+            expect(result?.auth).toEqual({
+                provider: 'cognito',
+                features: ['social-login', 'mfa'],
+            });
+        });
+        it('should return ProjectConfig with Auth0 auth and no features', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'auth0-app',
+                platforms: ['web'],
+                authProvider: 'auth0',
+                authFeatures: [],
+                features: ['github-actions'],
+                awsRegion: 'eu-west-1',
+                brandColor: 'purple',
+            });
+            const result = await runWizard();
+            expect(result?.auth).toEqual({
+                provider: 'auth0',
+                features: [],
+            });
+        });
+        it('should default auth to none when not selected', async () => {
+            mockPrompts.mockResolvedValueOnce({
+                projectName: 'no-auth-app',
+                platforms: ['api'],
+                authProvider: 'none',
+                // authFeatures not returned when provider is 'none'
+                features: [],
+                awsRegion: 'us-west-2',
+                brandColor: 'teal',
+            });
+            const result = await runWizard();
+            expect(result?.auth).toEqual({
+                provider: 'none',
+                features: [],
+            });
+        });
+    });
+});

package/dist/aws/iam.d.ts

@@ -0,0 +1,75 @@
+import { IAMClient } from '@aws-sdk/client-iam';
+/**
+ * AWS IAM service module
+ *
+ * Provides functions to create IAM deployment users with least-privilege
+ * policies for CDK deployment to specific environment accounts.
+ */
+/**
+ * Creates a configured IAMClient
+ * @param region - AWS region (defaults to us-east-1)
+ * @returns Configured IAMClient instance
+ */
+export declare function createIAMClient(region?: string): IAMClient;
+/**
+ * Creates an IAM deployment user with path /deployment/
+ * @param client - IAMClient instance
+ * @param userName - User name (format: {project}-{environment}-deploy)
+ * @throws Error if user creation fails (unless user already exists)
+ */
+export declare function createDeploymentUser(client: IAMClient, userName: string): Promise<void>;
+/**
+ * Creates a customer managed policy with minimal CDK deployment permissions
+ * @param client - IAMClient instance
+ * @param policyName - Policy name (format: {project}-{environment}-cdk-deploy)
+ * @param accountId - AWS account ID for resource ARNs
+ * @returns Policy ARN
+ * @throws Error if policy creation fails (unless policy already exists)
+ */
+export declare function createCDKDeploymentPolicy(client: IAMClient, policyName: string, accountId: string): Promise<string>;
+/**
+ * Attaches an IAM policy to a user
+ * @param client - IAMClient instance
+ * @param userName - IAM user name
+ * @param policyArn - Policy ARN to attach
+ */
+export declare function attachPolicyToUser(client: IAMClient, userName: string, policyArn: string): Promise<void>;
+/**
+ * Access key credentials for a deployment user
+ */
+export interface AccessKeyCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+/**
+ * Creates access key credentials for an IAM user
+ * @param client - IAMClient instance
+ * @param userName - IAM user name
+ * @returns Access key ID and secret access key
+ * @note The secret access key is ONLY available at creation time
+ */
+export declare function createAccessKey(client: IAMClient, userName: string): Promise<AccessKeyCredentials>;
+/**
+ * Complete deployment user credentials
+ */
+export interface DeploymentUserCredentials {
+    userName: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+/**
+ * Creates a deployment user with all required resources and returns credentials
+ *
+ * Orchestrates the full workflow:
+ * 1. Create IAM user with path /deployment/
+ * 2. Create CDK deployment policy with least-privilege permissions
+ * 3. Attach policy to user
+ * 4. Create and return access key credentials
+ *
+ * @param client - IAMClient instance
+ * @param projectName - Project name for resource naming
+ * @param environment - Environment name (dev, stage, prod)
+ * @param accountId - AWS account ID for policy resource ARNs
+ * @returns User name and access credentials for GitHub secrets
+ */
+export declare function createDeploymentUserWithCredentials(client: IAMClient, projectName: string, environment: string, accountId: string): Promise<DeploymentUserCredentials>;

package/dist/aws/iam.js

@@ -0,0 +1,264 @@
+import { IAMClient, CreateUserCommand, GetUserCommand, CreatePolicyCommand, GetPolicyCommand, AttachUserPolicyCommand, CreateAccessKeyCommand, NoSuchEntityException, } from '@aws-sdk/client-iam';
+import pc from 'picocolors';
+/**
+ * AWS IAM service module
+ *
+ * Provides functions to create IAM deployment users with least-privilege
+ * policies for CDK deployment to specific environment accounts.
+ */
+/**
+ * Creates a configured IAMClient
+ * @param region - AWS region (defaults to us-east-1)
+ * @returns Configured IAMClient instance
+ */
+export function createIAMClient(region = 'us-east-1') {
+    return new IAMClient({ region });
+}
+/**
+ * Checks if an IAM user exists
+ * @param client - IAMClient instance
+ * @param userName - User name to check
+ * @returns true if user exists, false otherwise
+ */
+async function userExists(client, userName) {
+    try {
+        const command = new GetUserCommand({ UserName: userName });
+        await client.send(command);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof NoSuchEntityException) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Checks if an IAM policy exists
+ * @param client - IAMClient instance
+ * @param policyArn - Policy ARN to check
+ * @returns true if policy exists, false otherwise
+ */
+async function policyExists(client, policyArn) {
+    try {
+        const command = new GetPolicyCommand({ PolicyArn: policyArn });
+        await client.send(command);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof NoSuchEntityException) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Creates an IAM deployment user with path /deployment/
+ * @param client - IAMClient instance
+ * @param userName - User name (format: {project}-{environment}-deploy)
+ * @throws Error if user creation fails (unless user already exists)
+ */
+export async function createDeploymentUser(client, userName) {
+    // Check if user already exists
+    if (await userExists(client, userName)) {
+        console.log(pc.yellow(`  User ${userName} already exists, reusing`));
+        return;
+    }
+    const command = new CreateUserCommand({
+        UserName: userName,
+        Path: '/deployment/',
+        Tags: [
+            { Key: 'Purpose', Value: 'CDK Deployment' },
+            { Key: 'ManagedBy', Value: 'create-aws-starter-kit' },
+        ],
+    });
+    await client.send(command);
+    console.log(pc.green(`  Created IAM user: ${userName}`));
+}
+/**
+ * CDK deployment policy document with minimal permissions
+ * @param accountId - AWS account ID for resource ARNs
+ * @returns Policy document JSON string
+ */
+function getCDKDeploymentPolicyDocument(accountId) {
+    const policy = {
+        Version: '2012-10-17',
+        Statement: [
+            {
+                Sid: 'CloudFormationFullAccess',
+                Effect: 'Allow',
+                Action: 'cloudformation:*',
+                Resource: '*',
+            },
+            {
+                Sid: 'CDKBootstrapBucket',
+                Effect: 'Allow',
+                Action: 's3:*',
+                Resource: [
+                    `arn:aws:s3:::cdk-*-assets-${accountId}-*`,
+                    `arn:aws:s3:::cdk-*-assets-${accountId}-*/*`,
+                ],
+            },
+            {
+                Sid: 'CDKRoleAssumption',
+                Effect: 'Allow',
+                Action: [
+                    'iam:PassRole',
+                    'sts:AssumeRole',
+                ],
+                Resource: [
+                    `arn:aws:iam::${accountId}:role/cdk-*`,
+                ],
+            },
+            {
+                Sid: 'SSMContextLookup',
+                Effect: 'Allow',
+                Action: 'ssm:GetParameter',
+                Resource: `arn:aws:ssm:*:${accountId}:parameter/cdk-bootstrap/*`,
+            },
+            {
+                Sid: 'LambdaDeployment',
+                Effect: 'Allow',
+                Action: 'lambda:*',
+                Resource: '*',
+            },
+            {
+                Sid: 'APIGatewayDeployment',
+                Effect: 'Allow',
+                Action: 'apigateway:*',
+                Resource: '*',
+            },
+            {
+                Sid: 'DynamoDBDeployment',
+                Effect: 'Allow',
+                Action: 'dynamodb:*',
+                Resource: '*',
+            },
+            {
+                Sid: 'CloudFrontDeployment',
+                Effect: 'Allow',
+                Action: 'cloudfront:*',
+                Resource: '*',
+            },
+            {
+                Sid: 'CognitoDeployment',
+                Effect: 'Allow',
+                Action: 'cognito-idp:*',
+                Resource: '*',
+            },
+            {
+                Sid: 'ECRAccess',
+                Effect: 'Allow',
+                Action: [
+                    'ecr:GetAuthorizationToken',
+                    'ecr:BatchCheckLayerAvailability',
+                    'ecr:GetDownloadUrlForLayer',
+                    'ecr:BatchGetImage',
+                ],
+                Resource: '*',
+            },
+        ],
+    };
+    return JSON.stringify(policy);
+}
+/**
+ * Creates a customer managed policy with minimal CDK deployment permissions
+ * @param client - IAMClient instance
+ * @param policyName - Policy name (format: {project}-{environment}-cdk-deploy)
+ * @param accountId - AWS account ID for resource ARNs
+ * @returns Policy ARN
+ * @throws Error if policy creation fails (unless policy already exists)
+ */
+export async function createCDKDeploymentPolicy(client, policyName, accountId) {
+    // Construct the expected policy ARN
+    const expectedPolicyArn = `arn:aws:iam::${accountId}:policy/${policyName}`;
+    // Check if policy already exists
+    if (await policyExists(client, expectedPolicyArn)) {
+        console.log(pc.yellow(`  Policy ${policyName} already exists, reusing`));
+        return expectedPolicyArn;
+    }
+    const command = new CreatePolicyCommand({
+        PolicyName: policyName,
+        PolicyDocument: getCDKDeploymentPolicyDocument(accountId),
+        Description: `CDK deployment policy for ${policyName.replace('-cdk-deploy', '')}`,
+        Tags: [
+            { Key: 'Purpose', Value: 'CDK Deployment' },
+            { Key: 'ManagedBy', Value: 'create-aws-starter-kit' },
+        ],
+    });
+    const response = await client.send(command);
+    if (!response.Policy?.Arn) {
+        throw new Error('Policy created but no ARN returned');
+    }
+    console.log(pc.green(`  Created policy: ${policyName}`));
+    return response.Policy.Arn;
+}
+/**
+ * Attaches an IAM policy to a user
+ * @param client - IAMClient instance
+ * @param userName - IAM user name
+ * @param policyArn - Policy ARN to attach
+ */
+export async function attachPolicyToUser(client, userName, policyArn) {
+    const command = new AttachUserPolicyCommand({
+        UserName: userName,
+        PolicyArn: policyArn,
+    });
+    await client.send(command);
+    console.log(pc.green(`  Attached policy to user ${userName}`));
+}
+/**
+ * Creates access key credentials for an IAM user
+ * @param client - IAMClient instance
+ * @param userName - IAM user name
+ * @returns Access key ID and secret access key
+ * @note The secret access key is ONLY available at creation time
+ */
+export async function createAccessKey(client, userName) {
+    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 a deployment user with all required resources and returns credentials
+ *
+ * Orchestrates the full workflow:
+ * 1. Create IAM user with path /deployment/
+ * 2. Create CDK deployment policy with least-privilege permissions
+ * 3. Attach policy to user
+ * 4. Create and return access key credentials
+ *
+ * @param client - IAMClient instance
+ * @param projectName - Project name for resource naming
+ * @param environment - Environment name (dev, stage, prod)
+ * @param accountId - AWS account ID for policy resource ARNs
+ * @returns User name and access credentials for GitHub secrets
+ */
+export async function createDeploymentUserWithCredentials(client, projectName, environment, accountId) {
+    const userName = `${projectName}-${environment}-deploy`;
+    const policyName = `${projectName}-${environment}-cdk-deploy`;
+    console.log(pc.cyan(`\nCreating deployment user for ${environment}...`));
+    // Step 1: Create the deployment user
+    await createDeploymentUser(client, userName);
+    // Step 2: Create the CDK deployment policy
+    const policyArn = await createCDKDeploymentPolicy(client, policyName, accountId);
+    // Step 3: Attach policy to user
+    await attachPolicyToUser(client, userName, policyArn);
+    // Step 4: Create and return access credentials
+    const credentials = await createAccessKey(client, userName);
+    console.log(pc.green(`\nDeployment user ${userName} ready with credentials`));
+    return {
+        userName,
+        accessKeyId: credentials.accessKeyId,
+        secretAccessKey: credentials.secretAccessKey,
+    };
+}

package/dist/aws/organizations.d.ts

@@ -0,0 +1,79 @@
+import { OrganizationsClient } from '@aws-sdk/client-organizations';
+/**
+ * AWS Organizations service module
+ *
+ * Provides functions to create AWS Organizations and member accounts
+ * programmatically during project generation.
+ */
+/**
+ * Creates a configured OrganizationsClient
+ * @param region - AWS region (defaults to us-east-1 as Organizations API is global)
+ * @returns Configured OrganizationsClient instance
+ */
+export declare function createOrganizationsClient(region?: string): OrganizationsClient;
+/**
+ * Checks if the current AWS account is already part of an organization
+ * @param client - OrganizationsClient instance
+ * @returns Organization ID if exists, null if not in an organization
+ */
+export declare function checkExistingOrganization(client: OrganizationsClient): Promise<string | null>;
+/**
+ * Creates a new AWS Organization with all features enabled
+ * @param client - OrganizationsClient instance
+ * @returns Organization ID of the newly created organization
+ * @throws Error if organization creation fails (except for already existing)
+ */
+export declare function createOrganization(client: OrganizationsClient): Promise<string>;
+/**
+ * Result of an account creation request
+ */
+export interface CreateAccountResult {
+    requestId: string;
+}
+/**
+ * Creates a new AWS account within the organization
+ * @param client - OrganizationsClient instance
+ * @param email - Email address for the new account's root user
+ * @param accountName - Display name for the account
+ * @returns CreateAccountStatus ID for polling
+ */
+export declare function createAccount(client: OrganizationsClient, email: string, accountName: string): Promise<CreateAccountResult>;
+/**
+ * Result of a completed account creation
+ */
+export interface AccountCreationResult {
+    accountId: string;
+    accountName: string;
+}
+/**
+ * Polls the account creation status until completion or timeout
+ * @param client - OrganizationsClient instance
+ * @param createAccountRequestId - The request ID from createAccount
+ * @param timeoutMs - Maximum time to wait in milliseconds (default: 5 minutes)
+ * @returns Account ID when creation succeeds
+ * @throws Error if creation fails or times out
+ */
+export declare function waitForAccountCreation(client: OrganizationsClient, createAccountRequestId: string, timeoutMs?: number): Promise<AccountCreationResult>;
+/**
+ * Account configuration for environment creation
+ */
+export interface EnvironmentAccountConfig {
+    environment: string;
+    email: string;
+}
+/**
+ * Result of environment account creation
+ */
+export interface EnvironmentAccountResult {
+    environment: string;
+    email: string;
+    accountId: string;
+}
+/**
+ * Creates multiple environment accounts sequentially
+ * @param client - OrganizationsClient instance
+ * @param orgName - Organization name prefix for account names
+ * @param accounts - Array of environment and email configurations
+ * @returns Array of created account results
+ */
+export declare function createEnvironmentAccounts(client: OrganizationsClient, orgName: string, accounts: EnvironmentAccountConfig[]): Promise<EnvironmentAccountResult[]>;