create-aws-project 1.5.0 → 1.6.0

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;
+    }
+}

package/dist/cli.js

@@ -7,6 +7,7 @@ import { generateProject } from './generator/index.js';
 import { showDeprecationNotice } from './commands/setup-github.js';
 import { runSetupAwsEnvs } from './commands/setup-aws-envs.js';
 import { runInitializeGitHub } from './commands/initialize-github.js';
+import { promptGitSetup, setupGitRepository } from './git/setup.js';
 /**
  * Write project configuration file for downstream commands
  */
@@ -40,14 +41,14 @@ function getVersion() {
  */
 function printHelp() {
     console.log(`
-create-aws-starter-kit [command] [options]
+create-aws-project [command] [options]
 
 Scaffold a new AWS Starter Kit project with React, Lambda, and CDK infrastructure.
 
 Commands:
   (default)           Create a new project (interactive wizard)
   setup-aws-envs      Set up AWS Organizations and environment accounts
-  initialize-github   Configure GitHub Environment for deployment
+  initialize-github   Configure GitHub Environment for deployment (supports batch mode)
   setup-github        ${pc.dim('[DEPRECATED]')} Use initialize-github instead
 
 Options:
@@ -55,15 +56,19 @@ Options:
   --version, -v       Show version number
 
 Usage:
-  create-aws-starter-kit                         Run interactive wizard
-  create-aws-starter-kit setup-aws-envs          Create AWS accounts
-  create-aws-starter-kit initialize-github dev   Configure dev environment
+  create-aws-project                              Run interactive wizard
+  create-aws-project setup-aws-envs               Create AWS accounts
+  create-aws-project initialize-github dev        Configure dev environment
+  create-aws-project initialize-github --all      Configure all environments
+  create-aws-project initialize-github dev stage  Configure specific environments
 
 Examples:
-  create-aws-starter-kit my-app
-  create-aws-starter-kit setup-aws-envs
-  create-aws-starter-kit initialize-github dev
-  create-aws-starter-kit --help
+  create-aws-project my-app
+  create-aws-project setup-aws-envs
+  create-aws-project initialize-github dev
+  create-aws-project initialize-github --all
+  create-aws-project initialize-github dev stage prod
+  create-aws-project --help
 `.trim());
 }
 /**
@@ -73,7 +78,7 @@ function printWelcome() {
     console.log(`
 ╔═══════════════════════════════════════════════════════╗
 ║                                                       ║
-║            create-aws-starter-kit                     ║
+║            create-aws-project                     ║
 ║       AWS Starter Kit Project Generator               ║
 ║                                                       ║
 ╚═══════════════════════════════════════════════════════╝
@@ -82,41 +87,30 @@ function printWelcome() {
 /**
  * Print post-generation instructions
  */
-function printNextSteps(projectName, platforms) {
+function printNextSteps(projectName) {
     console.log('');
     console.log(pc.bold('Next steps:'));
     console.log('');
     console.log(`  ${pc.cyan('cd')} ${projectName}`);
-    console.log(`  ${pc.cyan('npm install')}`);
     console.log('');
-    if (platforms.includes('web')) {
-        console.log(`  ${pc.gray('# Start web app')}`);
-        console.log(`  ${pc.cyan('npm run web')}`);
-        console.log('');
-    }
-    if (platforms.includes('mobile')) {
-        console.log(`  ${pc.gray('# Start mobile app')}`);
-        console.log(`  ${pc.cyan('npm run mobile')}`);
-        console.log('');
-    }
-    if (platforms.includes('api')) {
-        console.log(`  ${pc.gray('# Deploy API')}`);
-        console.log(`  ${pc.cyan('npm run cdk:deploy')}`);
-        console.log('');
-    }
-    console.log(`  ${pc.gray('# Configure AWS environments')}`);
+    console.log(`  ${pc.gray('# Set up AWS accounts and credentials')}`);
     console.log(`  ${pc.cyan('npx create-aws-project setup-aws-envs')}`);
     console.log('');
+    console.log(`  ${pc.gray('# Push credentials to GitHub secrets')}`);
+    console.log(`  ${pc.cyan('npx create-aws-project initialize-github')}`);
+    console.log('');
     console.log(pc.gray('Happy coding!'));
 }
 /**
  * Run the create project wizard flow
  * This is the default command when no subcommand is specified
  */
-async function runCreate(_args) {
+async function runCreate(args) {
     printWelcome();
     console.log(''); // blank line after banner
-    const config = await runWizard();
+    // Extract project name from CLI args (first non-flag argument)
+    const nameArg = args.find(arg => !arg.startsWith('-'));
+    const config = await runWizard(nameArg ? { defaultName: nameArg } : undefined);
     if (!config) {
         console.log('\nProject creation cancelled.');
         process.exit(1);
@@ -137,10 +131,15 @@ async function runCreate(_args) {
     await generateProject(config, outputDir);
     // Write config file for downstream commands
     writeConfigFile(outputDir, config);
+    // Optional: GitHub repository setup
+    const gitResult = await promptGitSetup();
+    if (gitResult) {
+        await setupGitRepository(outputDir, gitResult.repoUrl, gitResult.pat);
+    }
     // Success message and next steps
     console.log('');
     console.log(pc.green('✔') + ` Created ${pc.bold(config.projectName)} successfully!`);
-    printNextSteps(config.projectName, config.platforms);
+    printNextSteps(config.projectName);
     process.exit(0);
 }
 /**