create-aws-project 1.2.1 → 1.4.3

package/README.md

@@ -2,12 +2,12 @@
 
 Create a new AWS project from scratch including CloudFront, API Gateway, Lambdas, Cognito or Auth0, DynamoDB. GitHub pipeline for testing and deploying.
 
-[![npm version](https://img.shields.io/npm/v/create-aws-starter-kit.svg)](https://www.npmjs.com/package/create-aws-starter-kit)
+[![npm version](https://img.shields.io/npm/v/create-aws-project.svg)](https://www.npmjs.com/package/create-aws-project)
 
 ## 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-project [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 --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
+  npx create-aws-project my-app
+  npx create-aws-project setup-aws-envs
+  npx create-aws-project initialize-github dev
+  npx create-aws-project --help
 ```
 
-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
@@ -89,9 +74,148 @@ The interactive wizard will ask you about:
   - Note: Node 25+ has Jest compatibility issues - use 22.x or 24.x
 - **npm** - Included with Node.js
 
-## After Generation
+## 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: connect to your .git project
+
+* Initialize the repository
+```
+git init
+```
+
+* Add the remote repository using the git remote add <name> <url> command. A common practice is to name it origin.
+```bash
+git remote add origin <REMOTE_URL>
+```
+
+* Verify the connection by listing your remotes. The -v flag shows the URLs.
+```bash
+git remote -v
+```
+
+* Push your local commits to the remote repository for the first time.
+```bash
+git push -u origin main
+```
+
+### Step 2: 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 3: 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
+
+## After Setup
 
-Once your project is created:
+Once your project is set up:
 
 ```bash
 cd my-project

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__/harness/fixtures/config-factories.d.ts

@@ -0,0 +1,15 @@
+import type { ProjectConfig } from '../../../types.js';
+export declare const createWebCognitoConfig: () => ProjectConfig;
+export declare const createWebAuth0Config: () => ProjectConfig;
+export declare const createMobileCognitoConfig: () => ProjectConfig;
+export declare const createMobileAuth0Config: () => ProjectConfig;
+export declare const createApiCognitoConfig: () => ProjectConfig;
+export declare const createApiAuth0Config: () => ProjectConfig;
+export declare const createWebMobileCognitoConfig: () => ProjectConfig;
+export declare const createWebMobileAuth0Config: () => ProjectConfig;
+export declare const createWebApiCognitoConfig: () => ProjectConfig;
+export declare const createWebApiAuth0Config: () => ProjectConfig;
+export declare const createMobileApiCognitoConfig: () => ProjectConfig;
+export declare const createMobileApiAuth0Config: () => ProjectConfig;
+export declare const createFullStackCognitoConfig: () => ProjectConfig;
+export declare const createFullStackAuth0Config: () => ProjectConfig;

package/dist/__tests__/harness/fixtures/config-factories.js

@@ -0,0 +1,71 @@
+/**
+ * Create a base configuration with sensible defaults.
+ * All factories should call this to ensure consistent structure.
+ */
+function createBaseConfig(overrides = {}) {
+    const authProvider = overrides.authProvider ?? 'cognito';
+    return {
+        projectName: overrides.projectName ?? 'test-project',
+        platforms: overrides.platforms ?? ['web', 'api'],
+        awsRegion: overrides.awsRegion ?? 'us-east-1',
+        features: overrides.features ?? [],
+        brandColor: overrides.brandColor ?? 'blue',
+        auth: {
+            provider: authProvider,
+            features: authProvider === 'none' ? [] : (overrides.authFeatures ?? []),
+        },
+    };
+}
+// Single platform factories
+export const createWebCognitoConfig = () => createBaseConfig({ projectName: 'test-web-cognito', platforms: ['web'], authProvider: 'cognito' });
+export const createWebAuth0Config = () => createBaseConfig({ projectName: 'test-web-auth0', platforms: ['web'], authProvider: 'auth0' });
+export const createMobileCognitoConfig = () => createBaseConfig({
+    projectName: 'test-mobile-cognito',
+    platforms: ['mobile'],
+    authProvider: 'cognito',
+});
+export const createMobileAuth0Config = () => createBaseConfig({ projectName: 'test-mobile-auth0', platforms: ['mobile'], authProvider: 'auth0' });
+export const createApiCognitoConfig = () => createBaseConfig({ projectName: 'test-api-cognito', platforms: ['api'], authProvider: 'cognito' });
+export const createApiAuth0Config = () => createBaseConfig({ projectName: 'test-api-auth0', platforms: ['api'], authProvider: 'auth0' });
+// Double platform factories
+export const createWebMobileCognitoConfig = () => createBaseConfig({
+    projectName: 'test-web-mobile-cognito',
+    platforms: ['web', 'mobile'],
+    authProvider: 'cognito',
+});
+export const createWebMobileAuth0Config = () => createBaseConfig({
+    projectName: 'test-web-mobile-auth0',
+    platforms: ['web', 'mobile'],
+    authProvider: 'auth0',
+});
+export const createWebApiCognitoConfig = () => createBaseConfig({
+    projectName: 'test-web-api-cognito',
+    platforms: ['web', 'api'],
+    authProvider: 'cognito',
+});
+export const createWebApiAuth0Config = () => createBaseConfig({
+    projectName: 'test-web-api-auth0',
+    platforms: ['web', 'api'],
+    authProvider: 'auth0',
+});
+export const createMobileApiCognitoConfig = () => createBaseConfig({
+    projectName: 'test-mobile-api-cognito',
+    platforms: ['mobile', 'api'],
+    authProvider: 'cognito',
+});
+export const createMobileApiAuth0Config = () => createBaseConfig({
+    projectName: 'test-mobile-api-auth0',
+    platforms: ['mobile', 'api'],
+    authProvider: 'auth0',
+});
+// Triple platform factories
+export const createFullStackCognitoConfig = () => createBaseConfig({
+    projectName: 'test-full-cognito',
+    platforms: ['web', 'mobile', 'api'],
+    authProvider: 'cognito',
+});
+export const createFullStackAuth0Config = () => createBaseConfig({
+    projectName: 'test-full-auth0',
+    platforms: ['web', 'mobile', 'api'],
+    authProvider: 'auth0',
+});

package/dist/__tests__/harness/fixtures/fixtures.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/harness/fixtures/fixtures.spec.js

@@ -0,0 +1,89 @@
+import { describe, it, expect } from '@jest/globals';
+import { TEST_MATRIX, getConfigsByTier, getConfigByName } from './matrix.js';
+describe('Test Fixtures', () => {
+    describe('TEST_MATRIX', () => {
+        it('should define exactly 14 configurations', () => {
+            expect(TEST_MATRIX).toHaveLength(14);
+        });
+        it('should have unique names for all configurations', () => {
+            const names = TEST_MATRIX.map(c => c.name);
+            const uniqueNames = new Set(names);
+            expect(uniqueNames.size).toBe(names.length);
+        });
+        it('should have unique project names for all configurations', () => {
+            const projectNames = TEST_MATRIX.map(c => c.config.projectName);
+            const uniqueNames = new Set(projectNames);
+            expect(uniqueNames.size).toBe(projectNames.length);
+        });
+        it('should cover all 7 platform combinations', () => {
+            const platformSets = TEST_MATRIX.map(c => [...c.config.platforms].sort().join('+'));
+            const uniquePlatforms = new Set(platformSets);
+            expect(uniquePlatforms.size).toBe(7);
+        });
+        it('should cover both auth providers (cognito, auth0)', () => {
+            const authProviders = TEST_MATRIX.map(c => c.config.auth.provider);
+            const uniqueProviders = new Set(authProviders);
+            expect(uniqueProviders).toContain('cognito');
+            expect(uniqueProviders).toContain('auth0');
+        });
+        it('should not include auth provider none', () => {
+            const authProviders = TEST_MATRIX.map(c => c.config.auth.provider);
+            const uniqueProviders = new Set(authProviders);
+            expect(uniqueProviders).not.toContain('none');
+        });
+    });
+    describe('getConfigsByTier', () => {
+        it('should return 1 config for smoke tier', () => {
+            const configs = getConfigsByTier('smoke');
+            expect(configs).toHaveLength(1);
+        });
+        it('should return 5 configs for core tier (smoke + core)', () => {
+            const configs = getConfigsByTier('core');
+            expect(configs).toHaveLength(5);
+        });
+        it('should return all 14 configs for full tier', () => {
+            const configs = getConfigsByTier('full');
+            expect(configs).toHaveLength(14);
+        });
+        it('core tier should include at least one config per platform', () => {
+            const configs = getConfigsByTier('core');
+            const platforms = new Set();
+            for (const config of configs) {
+                for (const platform of config.config.platforms) {
+                    platforms.add(platform);
+                }
+            }
+            expect(platforms).toContain('web');
+            expect(platforms).toContain('mobile');
+            expect(platforms).toContain('api');
+        });
+        it('core tier should include at least one config per auth provider', () => {
+            const configs = getConfigsByTier('core');
+            const providers = new Set(configs.map(c => c.config.auth.provider));
+            expect(providers).toContain('cognito');
+            expect(providers).toContain('auth0');
+        });
+    });
+    describe('getConfigByName', () => {
+        it('should return config when name exists', () => {
+            const config = getConfigByName('web-api-cognito');
+            expect(config.name).toBe('web-api-cognito');
+        });
+        it('should throw when name does not exist', () => {
+            expect(() => getConfigByName('nonexistent')).toThrow('Configuration "nonexistent" not found in TEST_MATRIX');
+        });
+    });
+    describe('Config validity', () => {
+        it.each(TEST_MATRIX)('$name should have valid ProjectConfig structure', ({ config }) => {
+            // Required fields
+            expect(config.projectName).toBeDefined();
+            expect(config.platforms.length).toBeGreaterThan(0);
+            expect(config.awsRegion).toBeDefined();
+            expect(config.brandColor).toBeDefined();
+            expect(config.auth.provider).toBeDefined();
+            // Valid values
+            expect(['web', 'mobile', 'api']).toEqual(expect.arrayContaining(config.platforms));
+            expect(['cognito', 'auth0', 'none']).toContain(config.auth.provider);
+        });
+    });
+});

package/dist/__tests__/harness/fixtures/index.d.ts

@@ -0,0 +1,2 @@
+export { createWebCognitoConfig, createWebAuth0Config, createMobileCognitoConfig, createMobileAuth0Config, createApiCognitoConfig, createApiAuth0Config, createWebMobileCognitoConfig, createWebMobileAuth0Config, createWebApiCognitoConfig, createWebApiAuth0Config, createMobileApiCognitoConfig, createMobileApiAuth0Config, createFullStackCognitoConfig, createFullStackAuth0Config, } from './config-factories.js';
+export { TEST_MATRIX, getConfigsByTier, getConfigByName, type TestTier, type TestConfiguration, } from './matrix.js';

package/dist/__tests__/harness/fixtures/index.js

@@ -0,0 +1,2 @@
+export { createWebCognitoConfig, createWebAuth0Config, createMobileCognitoConfig, createMobileAuth0Config, createApiCognitoConfig, createApiAuth0Config, createWebMobileCognitoConfig, createWebMobileAuth0Config, createWebApiCognitoConfig, createWebApiAuth0Config, createMobileApiCognitoConfig, createMobileApiAuth0Config, createFullStackCognitoConfig, createFullStackAuth0Config, } from './config-factories.js';
+export { TEST_MATRIX, getConfigsByTier, getConfigByName, } from './matrix.js';

package/dist/__tests__/harness/fixtures/matrix.d.ts

@@ -0,0 +1,28 @@
+import type { ProjectConfig } from '../../../types.js';
+export type TestTier = 'smoke' | 'core' | 'full';
+export interface TestConfiguration {
+    name: string;
+    config: ProjectConfig;
+    tier: TestTier;
+}
+/**
+ * Complete test matrix: 14 configurations (7 platforms x 2 auth providers)
+ *
+ * Tier assignments:
+ * - smoke: 1 config (quick sanity check)
+ * - core: 4 configs (PR validation - covers all platforms and auth providers)
+ * - full: 9 configs (release validation - remaining combinations)
+ */
+export declare const TEST_MATRIX: TestConfiguration[];
+/**
+ * Get configurations by tier (cumulative)
+ * - 'smoke' returns smoke configs only (1)
+ * - 'core' returns smoke + core configs (5)
+ * - 'full' returns all configs (14)
+ */
+export declare function getConfigsByTier(tier: TestTier): TestConfiguration[];
+/**
+ * Get a single configuration by name.
+ * Throws if not found (fail-fast for typos).
+ */
+export declare function getConfigByName(name: string): TestConfiguration;

package/dist/__tests__/harness/fixtures/matrix.js

@@ -0,0 +1,58 @@
+import * as factories from './config-factories.js';
+/**
+ * Complete test matrix: 14 configurations (7 platforms x 2 auth providers)
+ *
+ * Tier assignments:
+ * - smoke: 1 config (quick sanity check)
+ * - core: 4 configs (PR validation - covers all platforms and auth providers)
+ * - full: 9 configs (release validation - remaining combinations)
+ */
+export const TEST_MATRIX = [
+    // === SMOKE TIER (1 config) ===
+    // Most common configuration - web+api with cognito
+    { name: 'web-api-cognito', tier: 'smoke', config: factories.createWebApiCognitoConfig() },
+    // === CORE TIER (4 configs) ===
+    // Ensures every platform and every auth provider is tested on PRs
+    { name: 'web-cognito', tier: 'core', config: factories.createWebCognitoConfig() },
+    { name: 'mobile-auth0', tier: 'core', config: factories.createMobileAuth0Config() },
+    { name: 'api-cognito', tier: 'core', config: factories.createApiCognitoConfig() },
+    { name: 'full-auth0', tier: 'core', config: factories.createFullStackAuth0Config() },
+    // === FULL TIER (9 remaining configs) ===
+    // All other combinations for release validation
+    { name: 'web-auth0', tier: 'full', config: factories.createWebAuth0Config() },
+    { name: 'mobile-cognito', tier: 'full', config: factories.createMobileCognitoConfig() },
+    { name: 'api-auth0', tier: 'full', config: factories.createApiAuth0Config() },
+    { name: 'web-mobile-cognito', tier: 'full', config: factories.createWebMobileCognitoConfig() },
+    { name: 'web-mobile-auth0', tier: 'full', config: factories.createWebMobileAuth0Config() },
+    { name: 'web-api-auth0', tier: 'full', config: factories.createWebApiAuth0Config() },
+    { name: 'mobile-api-cognito', tier: 'full', config: factories.createMobileApiCognitoConfig() },
+    { name: 'mobile-api-auth0', tier: 'full', config: factories.createMobileApiAuth0Config() },
+    { name: 'full-cognito', tier: 'full', config: factories.createFullStackCognitoConfig() },
+];
+/**
+ * Get configurations by tier (cumulative)
+ * - 'smoke' returns smoke configs only (1)
+ * - 'core' returns smoke + core configs (5)
+ * - 'full' returns all configs (14)
+ */
+export function getConfigsByTier(tier) {
+    switch (tier) {
+        case 'smoke':
+            return TEST_MATRIX.filter(c => c.tier === 'smoke');
+        case 'core':
+            return TEST_MATRIX.filter(c => c.tier === 'smoke' || c.tier === 'core');
+        case 'full':
+            return TEST_MATRIX;
+    }
+}
+/**
+ * Get a single configuration by name.
+ * Throws if not found (fail-fast for typos).
+ */
+export function getConfigByName(name) {
+    const config = TEST_MATRIX.find(c => c.name === name);
+    if (!config) {
+        throw new Error(`Configuration "${name}" not found in TEST_MATRIX`);
+    }
+    return config;
+}

package/dist/__tests__/harness/local-runner.d.ts

@@ -0,0 +1,2 @@
+import { type TestTier } from './fixtures/index.js';
+export declare function runValidationSuite(tier?: TestTier): Promise<void>;