create-aws-project 1.2.1 → 1.3.0

package/README.md

@@ -7,7 +7,7 @@ Create a new AWS project from scratch including CloudFront, API Gateway, Lambdas
 ## Quick Start
 
 ```bash
-npx create-aws-starter-kit my-project
+npx create-aws-project my-project
 ```
 
 **Requirements:** Node.js 22.16.0+ (npm included)
@@ -33,35 +33,24 @@ The generated project is a full-stack Nx monorepo with:
 ## CLI Options
 
 ```
-create-aws-starter-kit [options] [project-name]
+create-aws-starter-kit [command] [options]
+
+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
 
 Options:
-  --help, -h      Show help message
-  --version, -v   Show version number
+  --help, -h          Show help message
+  --version, -v       Show version number
 
 Examples:
   npx create-aws-starter-kit my-app
+  npx create-aws-starter-kit setup-aws-envs
+  npx create-aws-starter-kit initialize-github dev
   npx create-aws-starter-kit --help
-  npx create-aws-starter-kit --version
-```
-
-### Setup GitHub Command
-
-After generating a project with AWS Organizations enabled, configure GitHub Actions deployment:
-
-```bash
-npx create-aws-starter-kit setup-github
 ```
 
-This command:
-- Creates IAM deployment users per environment (dev, stage, prod)
-- Configures GitHub Environments with AWS credentials
-- Sets up least-privilege CDK deployment permissions
-
-**Requirements:**
-- GitHub Personal Access Token with `repo` and `admin:org` scopes
-- AWS credentials with IAM permissions
-
 ## Wizard Prompts
 
 The interactive wizard will ask you about:
@@ -72,11 +61,7 @@ The interactive wizard will ask you about:
    - None (add later)
    - AWS Cognito
    - Auth0
-   - Optional: Social login, MFA
-4. **AWS Organizations** - Multi-account setup (optional):
-   - Creates separate AWS accounts for each environment
-   - Environments: dev, stage, prod (plus optional qa, sandbox)
-   - Requires root email per account
+4. **Auth features** - Social login, MFA (conditional on auth provider)
 5. **Features** - Optional extras:
    - GitHub Actions workflows for CI/CD
    - VS Code workspace configuration
@@ -113,6 +98,123 @@ npm run cdk:deploy
 
 See the generated project's README for detailed documentation.
 
+## Post-Install Setup
+
+After creating your project, you'll set up AWS environments and GitHub deployment. This is a one-time setup.
+
+### Prerequisites
+
+Before you begin:
+- AWS CLI configured with credentials from your AWS management account
+- GitHub repository created for your project
+- GitHub Personal Access Token with "repo" scope ([create one here](https://github.com/settings/tokens/new))
+
+### Step 1: Set Up AWS Environments
+
+From your project directory, run:
+
+```bash
+npx create-aws-project setup-aws-envs
+```
+
+This command:
+- Creates an AWS Organization (if you don't have one)
+- Creates three environment accounts: dev, stage, prod
+- Prompts for a unique root email for each account (tip: use aliases like you+dev@email.com)
+
+**What's happening:** AWS Organizations lets you isolate each environment in its own AWS account. This is a security best practice - your production data is completely separate from development.
+
+Expected output:
+```
+✔ Created AWS Organization: o-xxxxxxxxxx
+✔ Created dev account: 123456789012
+✔ Created stage account: 234567890123
+✔ Created prod account: 345678901234
+
+AWS environment setup complete!
+```
+
+Account IDs are saved to `.aws-starter-config.json` for the next step.
+
+### Step 2: Configure GitHub Environments
+
+For each environment, run:
+
+```bash
+npx create-aws-project initialize-github dev
+```
+
+This command:
+- Creates an IAM deployment user in the target AWS account
+- Configures GitHub Environment secrets with AWS credentials
+- Sets up least-privilege permissions for CDK deployments
+
+**What's happening:** Each GitHub Environment (Development, Staging, Production) gets its own AWS credentials. When GitHub Actions runs, it uses the right credentials for the target environment.
+
+Repeat for each environment:
+```bash
+npx create-aws-project initialize-github stage
+npx create-aws-project initialize-github prod
+```
+
+You'll be prompted for your GitHub PAT each time (it's not stored).
+
+### You're Done!
+
+Push to main to trigger your first deployment:
+```bash
+git push origin main
+```
+
+GitHub Actions will deploy to your dev environment automatically.
+
+## Troubleshooting
+
+### setup-aws-envs errors
+
+**"Insufficient AWS permissions"**
+
+Your AWS credentials need Organizations permissions. Ensure you're using credentials from the management account (not a member account).
+
+Required permissions:
+- organizations:DescribeOrganization
+- organizations:CreateOrganization
+- organizations:CreateAccount
+- organizations:DescribeCreateAccountStatus
+
+**"AWS Organizations limit reached"**
+
+AWS limits how many accounts you can create. Contact AWS Support to request a limit increase.
+
+**"AWS Organization is still initializing"**
+
+New organizations take up to an hour to fully initialize. Wait and try again.
+
+### initialize-github errors
+
+**"Cannot assume role in target account"**
+
+The command needs to access the target AWS account via `OrganizationAccountAccessRole`. This role is created automatically when you create accounts via `setup-aws-envs`. Ensure:
+1. You ran `setup-aws-envs` first
+2. Your credentials are from the management account
+3. The account ID in `.aws-starter-config.json` is correct
+
+**"IAM user already exists"**
+
+The deployment user already exists in the target account. To retry:
+1. Go to AWS Console > IAM > Users
+2. Delete the existing `<project>-<env>-deploy` user
+3. Run the command again
+
+**"GitHub authentication failed"**
+
+Your Personal Access Token may be invalid or missing permissions. Ensure:
+1. Token has "repo" scope enabled
+2. Token belongs to the repository owner (or has collaborator access)
+3. Token is not expired
+
+Create a new token at: https://github.com/settings/tokens/new
+
 ## License
 
 ISC

package/dist/__tests__/generator/replace-tokens.spec.js

@@ -12,6 +12,9 @@ describe('replaceTokens', () => {
         AUTH_AUTH0: 'false',
         AUTH_SOCIAL_LOGIN: 'false',
         AUTH_MFA: 'false',
+        WEB: 'false',
+        MOBILE: 'false',
+        API: 'false',
     };
     describe('single token replacement', () => {
         it('should replace PROJECT_NAME token', () => {
@@ -107,6 +110,9 @@ describe('processConditionalBlocks', () => {
         AUTH_AUTH0: 'false',
         AUTH_SOCIAL_LOGIN: 'false',
         AUTH_MFA: 'false',
+        WEB: 'false',
+        MOBILE: 'false',
+        API: 'false',
     };
     describe('comment-wrapped conditionals', () => {
         it('should keep content when token is true (removes markers)', () => {
@@ -228,6 +234,9 @@ describe('replaceTokens integration with conditionals', () => {
         AUTH_AUTH0: 'false',
         AUTH_SOCIAL_LOGIN: 'false',
         AUTH_MFA: 'false',
+        WEB: 'false',
+        MOBILE: 'false',
+        API: 'false',
     };
     it('should process conditionals before token replacement', () => {
         const tokens = { ...baseTokens, AUTH_COGNITO: 'true' };

package/dist/__tests__/wizard.spec.js

@@ -173,10 +173,9 @@ describe('runWizard', () => {
             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)
+            // Verify 7 prompts are passed (projectName, platforms, authProvider, authFeatures, features, awsRegion, brandColor)
             expect(Array.isArray(promptsArg)).toBe(true);
-            expect(promptsArg.length).toBe(15);
+            expect(promptsArg.length).toBe(7);
         });
     });
     describe('auth configuration', () => {

package/dist/aws/iam.d.ts

@@ -11,11 +11,18 @@ import { IAMClient } from '@aws-sdk/client-iam';
  * @returns Configured IAMClient instance
  */
 export declare function createIAMClient(region?: string): IAMClient;
+/**
+ * Creates an IAMClient configured to access a target account via cross-account role assumption
+ * @param region - AWS region
+ * @param targetAccountId - Target AWS account ID to access
+ * @returns IAMClient configured with cross-account credentials
+ */
+export declare function createCrossAccountIAMClient(region: string, targetAccountId: 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)
+ * @throws Error if user already exists or creation fails
  */
 export declare function createDeploymentUser(client: IAMClient, userName: string): Promise<void>;
 /**

package/dist/aws/iam.js

@@ -1,4 +1,5 @@
 import { IAMClient, CreateUserCommand, GetUserCommand, CreatePolicyCommand, GetPolicyCommand, AttachUserPolicyCommand, CreateAccessKeyCommand, NoSuchEntityException, } from '@aws-sdk/client-iam';
+import { fromTemporaryCredentials } from '@aws-sdk/credential-providers';
 import pc from 'picocolors';
 /**
  * AWS IAM service module
@@ -14,6 +15,25 @@ import pc from 'picocolors';
 export function createIAMClient(region = 'us-east-1') {
     return new IAMClient({ region });
 }
+/**
+ * Creates an IAMClient configured to access a target account via cross-account role assumption
+ * @param region - AWS region
+ * @param targetAccountId - Target AWS account ID to access
+ * @returns IAMClient configured with cross-account credentials
+ */
+export function createCrossAccountIAMClient(region, targetAccountId) {
+    const roleArn = `arn:aws:iam::${targetAccountId}:role/OrganizationAccountAccessRole`;
+    return new IAMClient({
+        region,
+        credentials: fromTemporaryCredentials({
+            params: {
+                RoleArn: roleArn,
+                RoleSessionName: `create-aws-project-${Date.now()}`,
+                DurationSeconds: 900,
+            },
+        }),
+    });
+}
 /**
  * Checks if an IAM user exists
  * @param client - IAMClient instance
@@ -56,13 +76,12 @@ async function policyExists(client, policyArn) {
  * 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)
+ * @throws Error if user already exists or creation fails
  */
 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;
+        throw new Error(`IAM user "${userName}" already exists. Delete manually before retrying.`);
     }
     const command = new CreateUserCommand({
         UserName: userName,

package/dist/cli.js

@@ -1,11 +1,30 @@
-import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import pc from 'picocolors';
 import { runWizard } from './wizard.js';
 import { generateProject } from './generator/index.js';
-import { createOrganizationsClient, checkExistingOrganization, createOrganization, createEnvironmentAccounts, } from './aws/organizations.js';
-import { runSetupGitHub } from './commands/setup-github.js';
+import { showDeprecationNotice } from './commands/setup-github.js';
+import { runSetupAwsEnvs } from './commands/setup-aws-envs.js';
+import { runInitializeGitHub } from './commands/initialize-github.js';
+/**
+ * Write project configuration file for downstream commands
+ */
+function writeConfigFile(outputDir, config) {
+    const configContent = {
+        configVersion: '1.0',
+        projectName: config.projectName,
+        platforms: config.platforms,
+        authProvider: config.auth.provider,
+        features: config.features,
+        awsRegion: config.awsRegion,
+        theme: config.brandColor,
+        createdAt: new Date().toISOString(),
+        accounts: {},
+    };
+    const configPath = join(outputDir, '.aws-starter-config.json');
+    writeFileSync(configPath, JSON.stringify(configContent, null, 2), 'utf-8');
+}
 /**
  * Get the version from package.json
  */
@@ -26,20 +45,24 @@ create-aws-starter-kit [command] [options]
 Scaffold a new AWS Starter Kit project with React, Lambda, and CDK infrastructure.
 
 Commands:
-  (default)       Create a new project (interactive wizard)
-  setup-github    Configure GitHub Actions deployment credentials
+  (default)           Create a new project (interactive wizard)
+  setup-aws-envs      Set up AWS Organizations and environment accounts
+  initialize-github   Configure GitHub Environment for deployment
+  setup-github        ${pc.dim('[DEPRECATED]')} Use initialize-github instead
 
 Options:
-  --help, -h      Show this help message
-  --version, -v   Show version number
+  --help, -h          Show this help message
+  --version, -v       Show version number
 
 Usage:
-  create-aws-starter-kit [project-name]    Create a new project
-  create-aws-starter-kit setup-github      Configure GitHub deployment
+  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
 
 Examples:
   create-aws-starter-kit my-app
-  create-aws-starter-kit setup-github
+  create-aws-starter-kit setup-aws-envs
+  create-aws-starter-kit initialize-github dev
   create-aws-starter-kit --help
 `.trim());
 }
@@ -81,31 +104,16 @@ function printNextSteps(projectName, platforms) {
         console.log(`  ${pc.cyan('npm run cdk:deploy')}`);
         console.log('');
     }
+    console.log(`  ${pc.gray('# Configure AWS environments')}`);
+    console.log(`  ${pc.cyan('npx create-aws-project setup-aws-envs')}`);
+    console.log('');
     console.log(pc.gray('Happy coding!'));
 }
 /**
- * Parse command line arguments and run the CLI
+ * Run the create project wizard flow
+ * This is the default command when no subcommand is specified
  */
-export async function run() {
-    const args = process.argv.slice(2);
-    // Check for --help or -h
-    if (args.includes('--help') || args.includes('-h')) {
-        printHelp();
-        process.exit(0);
-    }
-    // Check for --version or -v
-    if (args.includes('--version') || args.includes('-v')) {
-        console.log(getVersion());
-        process.exit(0);
-    }
-    // Check for subcommands (first non-flag argument)
-    const command = args.find((arg) => !arg.startsWith('-'));
-    // Handle setup-github command
-    if (command === 'setup-github') {
-        await runSetupGitHub();
-        process.exit(0);
-    }
-    // Default: run interactive wizard
+async function runCreate(_args) {
     printWelcome();
     console.log(''); // blank line after banner
     const config = await runWizard();
@@ -113,77 +121,6 @@ export async function run() {
         console.log('\nProject creation cancelled.');
         process.exit(1);
     }
-    // Set up AWS Organizations if enabled
-    if (config.org?.enabled) {
-        console.log('');
-        console.log(pc.cyan('Setting up AWS Organizations...'));
-        try {
-            const orgClient = createOrganizationsClient(config.awsRegion);
-            // Check if already in an organization
-            const existingOrgId = await checkExistingOrganization(orgClient);
-            if (existingOrgId) {
-                console.log(pc.yellow(`Already in organization: ${existingOrgId}`));
-                console.log(pc.dim('Proceeding with existing organization...'));
-            }
-            else {
-                // Create new organization
-                console.log(pc.dim('Creating new AWS Organization...'));
-                const orgId = await createOrganization(orgClient);
-                console.log(pc.green('✔') + ` Organization created: ${orgId}`);
-            }
-            // Create environment accounts
-            const accountResults = await createEnvironmentAccounts(orgClient, config.org.organizationName, config.org.accounts);
-            // Update config.org.accounts with returned accountIds
-            for (const result of accountResults) {
-                const account = config.org.accounts.find((a) => a.environment === result.environment);
-                if (account) {
-                    account.accountId = result.accountId;
-                }
-            }
-            console.log('');
-            console.log(pc.green('✔') + ' AWS Organizations setup complete');
-            console.log(pc.dim('Account IDs:'));
-            for (const account of config.org.accounts) {
-                console.log(pc.dim(`  ${account.environment}: ${account.accountId}`));
-            }
-        }
-        catch (error) {
-            console.log('');
-            // Handle specific AWS errors
-            if (error instanceof Error) {
-                if (error.name === 'CredentialsProviderError' ||
-                    error.message.includes('Could not load credentials')) {
-                    console.log(pc.red('Error:') + ' AWS credentials not configured.');
-                    console.log('');
-                    console.log('Please configure AWS credentials using one of these methods:');
-                    console.log('  1. Run: ' + pc.cyan('aws configure'));
-                    console.log('  2. Set environment variables: ' + pc.cyan('AWS_ACCESS_KEY_ID') + ' and ' + pc.cyan('AWS_SECRET_ACCESS_KEY'));
-                    console.log('  3. Use an AWS profile: ' + pc.cyan('export AWS_PROFILE=your-profile'));
-                    process.exit(1);
-                }
-                if (error.name === 'AccessDeniedException' ||
-                    error.message.includes('not authorized')) {
-                    console.log(pc.red('Error:') + ' Insufficient AWS permissions.');
-                    console.log('');
-                    console.log('Required IAM permissions for AWS Organizations:');
-                    console.log('  - ' + pc.cyan('organizations:CreateOrganization'));
-                    console.log('  - ' + pc.cyan('organizations:DescribeOrganization'));
-                    console.log('  - ' + pc.cyan('organizations:CreateAccount'));
-                    console.log('  - ' + pc.cyan('organizations:DescribeCreateAccountStatus'));
-                    process.exit(1);
-                }
-                // Log which account failed if it's an account creation error
-                if (error.message.includes('Failed to create')) {
-                    console.log(pc.red('Error:') + ` ${error.message}`);
-                    process.exit(1);
-                }
-            }
-            // Generic error
-            const message = error instanceof Error ? error.message : 'Unknown error';
-            console.log(pc.red('Error:') + ` AWS Organizations setup failed: ${message}`);
-            process.exit(1);
-        }
-    }
     // Determine output directory
     const outputDir = resolve(process.cwd(), config.projectName);
     // Check if directory already exists
@@ -198,9 +135,49 @@ export async function run() {
     // Generate project
     console.log('');
     await generateProject(config, outputDir);
+    // Write config file for downstream commands
+    writeConfigFile(outputDir, config);
     // Success message and next steps
     console.log('');
     console.log(pc.green('✔') + ` Created ${pc.bold(config.projectName)} successfully!`);
     printNextSteps(config.projectName, config.platforms);
     process.exit(0);
 }
+/**
+ * Parse command line arguments and run the CLI
+ */
+export async function run() {
+    const args = process.argv.slice(2);
+    // Check for --help or -h
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp();
+        process.exit(0);
+    }
+    // Check for --version or -v
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(getVersion());
+        process.exit(0);
+    }
+    // Find the command (first non-flag argument)
+    const commandIndex = args.findIndex((arg) => !arg.startsWith('-'));
+    const command = commandIndex !== -1 ? args[commandIndex] : undefined;
+    const commandArgs = commandIndex !== -1 ? args.slice(commandIndex + 1) : [];
+    // Route to appropriate command handler
+    switch (command) {
+        case 'setup-aws-envs':
+            await runSetupAwsEnvs(commandArgs);
+            break;
+        case 'initialize-github':
+            await runInitializeGitHub(commandArgs);
+            break;
+        case 'setup-github':
+            // Deprecated command - show notice and exit
+            showDeprecationNotice();
+            break;
+        default:
+            // Default: run interactive create wizard
+            // This handles both no command and unknown commands
+            await runCreate(args);
+            break;
+    }
+}

package/dist/commands/initialize-github.d.ts

@@ -0,0 +1,13 @@
+/**
+ * initialize-github command
+ *
+ * Configures GitHub Environment with AWS credentials for a single environment
+ * Must be run from inside a project directory
+ * Requires environment name as argument (dev, stage, prod)
+ */
+/**
+ * Runs the initialize-github command
+ *
+ * @param args Command arguments - expects environment name as first arg (optional)
+ */
+export declare function runInitializeGitHub(args: string[]): Promise<void>;