deploy-stack 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish CLI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+          
+      - name: Inject Telemetry Key
+        # This securely swaps the placeholder for the real key right before publishing
+        run: sed -i "s/___POSTHOG_INGESTION_KEY___/${{ secrets.POSTHOG_KEY }}/g" src/core/telemetry.js
+        
+      - run: npm install
+      
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,132 @@
+# deploy-stack ☁️🚀
+
+> The zero-lock-in cloud generator. Eject your containerized web app from expensive PaaS platforms to production-ready, highly available AWS infrastructure in 60 seconds.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## The Problem
+
+Managed platforms like Vercel, Heroku, or Render offer rapid initial deployments, but costs escalate quickly with seat pricing, compute caps, and bandwidth markups.
+
+Migrating directly to AWS provides greater cost efficiency and infrastructure control. However, architecting raw Terraform for ECS clusters, Application Load Balancers, CloudFront distributions, and keyless CI/CD pipelines typically requires writing hundreds of lines of complex boilerplate infrastructure code.
+
+## The Solution
+
+**`deploy-stack`** is an interactive CLI that streamlines the process. It analyzes your project requirements and generates **clean, readable, and completely ejectable Terraform and GitHub Actions workflows** directly inside your repository.
+
+You retain complete ownership of your infrastructure code without relying on black-box platforms.
+
+---
+
+## ✨ Features
+
+* **Zero Vendor Lock-In:** Generates standard, clean `.tf` files. Modify, expand, or decouple them at any time.
+* **Framework Agnostic:** Tailored container presets for Next.js (standalone), Express.js, FastAPI, and custom Docker setups.
+* **Production-Grade Defaults:** Automatically provisions an Amazon ECS Fargate cluster fronted by an Application Load Balancer across multiple availability zones.
+* **Global Edge Acceleration:** Includes an integrated AWS CloudFront CDN distribution with SSL termination and optimized caching.
+* **Keyless, Zero-Secret CI/CD:** Uses AWS IAM OpenID Connect (OIDC) for automated GitHub Actions deployments—no long-lived AWS keys stored in GitHub Secrets.
+* **Remote State with Native S3 Locking:** Automatically creates an encrypted S3 state bucket utilizing modern native S3 concurrency locking.
+* **Built-in Secrets Sync:** Provides a dedicated CLI workflow to securely push local `.env` variables into AWS Secrets Manager and map them directly into containers at runtime.
+* **Non-Destructive:** Safely analyzes existing directories and prompts for confirmation before updating any files.
+
+---
+
+## 🚀 Quick Start
+
+Run the CLI directly in your project root:
+
+```bash
+npx deploy-stack
+```
+
+The interactive CLI will guide you through the setup:
+1. **Target Directory / Name:** (Type `.` to bootstrap your current directory)
+2. **Setup Mode:** (Choose **Quickstart** for sensible defaults, or **Advanced** to customize health checks, scaling, and branch names)
+3. **AWS Region:** (e.g., `us-east-2`)
+4. **Compute Tier:** (Choose from Micro, Small, Medium, or Large with live monthly cost estimates)
+5. **Target Port & Framework:** (Generates an optimized multi-stage `Dockerfile`)
+
+---
+
+## 🔑 Securely Managing Secrets
+
+Avoid committing sensitive environment files to version control. Push local variables directly to AWS:
+
+```bash
+npx deploy-stack secrets push .env.production
+```
+*This command encrypts your values in AWS Secrets Manager and updates `terraform/secret_keys.json` to expose those variables inside your ECS tasks at boot.*
+
+---
+
+## 🛠️ Next Steps After Generation
+
+1. **Provision Infrastructure:**
+   ```bash
+   cd terraform
+   terraform init
+   terraform apply
+   ```
+2. **Push to GitHub:**
+   ```bash
+   git add .
+   git commit -m "feat: infrastructure and deployment pipeline"
+   git push origin main
+   ```
+3. **Automated Deployment:** GitHub Actions securely authenticates via OIDC, builds your container, pushes to Amazon ECR, and executes a zero-downtime rolling deployment to ECS.
+
+---
+
+## 📁 Generated File Structure
+
+Running the CLI generates a modular architecture tailored to your service:
+
+```text
+your-project/
+├── Dockerfile                  # Multi-stage container preset
+├── .github/
+│   └── workflows/
+│       └── deploy.yml          # Keyless OIDC CI/CD deployment pipeline
+└── terraform/
+    ├── main.tf                 # ECR repository, ECS Cluster, and Fargate Task
+    ├── network.tf              # VPC, Public Subnets, ALB, and Security Groups
+    ├── cloudfront.tf           # CloudFront CDN edge distribution
+    ├── oidc.tf                 # GitHub Actions keyless IAM OIDC Provider & Roles
+    ├── secrets.tf              # AWS Secrets Manager integration
+    ├── backend.tf              # S3 Remote State backend with native locking
+    └── secret_keys.json        # Dynamic key map for injected environment variables
+```
+
+---
+
+## 📦 Reference Implementations
+
+* **[Next.js Fullstack Reference App](https://github.com/anton-codes-iac/deploy-stack-nextjs-example):** A complete Next.js deployment showcasing the generated Terraform, CloudFront setup, and automated OIDC workflow.
+
+---
+
+### 🛡️ Telemetry & Privacy
+By default, `deploy-stack` collects anonymous, hashed usage data to help improve the CLI (e.g., framework presets used, deployment success rates). **No codebase files, AWS credentials, or personal data are ever collected.**
+
+To opt out, simply append the flag:
+\`\`\`bash
+npx deploy-stack --no-telemetry
+\`\`\`
+
+---
+
+## 🗺️ Roadmap
+
+- [x] **POC:** Interactive CLI, ECS Fargate + ALB Terraform generation, GitHub Actions CI/CD, and Secrets sync.
+- [x] **MVP:** CloudFront distribution, Remote S3 State locking, OIDC security, and CLI configuration flows.
+- [ ] **v0.9:** Zero-config framework detection (auto-discovering Next.js, Express, and FastAPI via `package.json` / `requirements.txt`).
+- [ ] **v1.0 (Pro):** Automated RDS PostgreSQL provisioning, custom domain Route 53 / ACM SSL configuration, and environment workspaces (`staging` vs `prod`).
+- [ ] **v2.0 (Enterprise):** Private VPC subnets with NAT gateways, AWS WAF integration, and automated compliance scanning.
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for more information.

package/bin/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import path from 'path';
+import { runDoctor } from '../src/commands/doctor.js';
+import { pushSecrets } from '../src/commands/secrets.js';
+import { mainStack } from '../src/commands/init.js';
+
+// 1. Extract the telemetry flag and set the environment variable
+const rawArgs = process.argv.slice(2);
+const hasNoTelemetry = rawArgs.includes('--no-telemetry');
+
+if (hasNoTelemetry) {
+    process.env.DO_NOT_TRACK = '1';
+}
+
+// 2. Filter out the telemetry flag from the args so the subcommands don't see it
+const args = rawArgs.filter((arg) => arg !== '--no-telemetry');
+
+// 3. Handle commands
+if (args[0] === 'secrets' && args[1] === 'push') {
+    const envFile = args[2] || '.env';
+    const projectName = path.basename(process.cwd());
+    pushSecrets(envFile, projectName).catch(console.error);
+} else if (args[0] === 'doctor') {
+    runDoctor().catch(console.error);
+} else {
+    mainStack().catch(console.error);
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "deploy-stack",
+  "version": "0.1.0",
+  "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
+  "type": "module",
+  "bin": {
+    "deploy-stack": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "anton-codes-iac",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anton-codes-iac/deploy-stack.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1115.0",
+    "@aws-sdk/client-secrets-manager": "3.1112.0",
+    "@aws-sdk/client-sts": "3.1115.0",
+    "@clack/prompts": "1.7.0",
+    "dotenv": "17.4.2",
+    "picocolors": "1.1.1"
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,39 @@
+import { intro, outro, spinner } from '@clack/prompts';
+import color from 'picocolors';
+import { checkDependency } from '../utils/system.js';
+
+export async function runDoctor() {
+    intro(color.bgCyan(color.black(' deploy-stack ☁️  ')));
+
+    const s = spinner();
+    s.start('Running pre-flight checks...');
+
+    const [hasTerraform, hasAws, hasDocker, hasGit] = await Promise.all([
+        checkDependency('terraform'),
+        checkDependency('aws'),
+        checkDependency('docker'),
+        checkDependency('git')
+    ]);
+
+    s.stop('Pre-flight checks complete.\n');
+
+    const printStatus = (ok, label, fix) => {
+        const icon = ok ? color.green('✅') : color.red('❌');
+        const message = ok ? `${label} (✓)` : `${label} (✗)`;
+        console.log(`   ${icon} ${message}`);
+        if (!ok) {
+            console.log(`      ┌─ Try: ${color.dim(fix)}`);
+        }
+    };
+
+    printStatus(hasTerraform, 'Terraform', 'Install via Homebrew: brew install terraform');
+    printStatus(hasAws, 'AWS CLI', 'Install via Homebrew: brew install awscli');
+    printStatus(hasDocker, 'Docker', 'Install via Homebrew: brew install docker');
+    printStatus(hasGit, 'Git', 'Install via Homebrew: brew install git');
+
+    if (hasTerraform && hasAws && hasDocker && hasGit) {
+        outro(color.green('Your system is 100% ready to provision and deploy! 🚀'));
+    } else {
+        outro(color.yellow('Please install the missing dependencies before running the provisioning tool.'));
+    }
+}

package/src/commands/init.js

@@ -0,0 +1,331 @@
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import { S3Client, CreateBucketCommand, PutBucketVersioningCommand } from '@aws-sdk/client-s3';
+import fsSync from 'fs';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { intro, outro, group, text, select, spinner, cancel, confirm } from '@clack/prompts';
+import color from 'picocolors';
+
+import { checkDependency } from '../utils/system.js';
+import { trackEvent } from '../core/telemetry.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export async function mainStack() {
+    const startTime = Date.now();
+
+    // 0. Silent Pre-flight check
+    const hasTerraform = await checkDependency('terraform');
+    if (!hasTerraform) {
+        console.error(color.red('✖ Terraform is not installed.'));
+        console.log(color.yellow('Please run "npx deploy-stack doctor" to check your environment.'));
+        process.exit(1);
+    }
+
+    // 1. Start the CLI
+    intro(color.bgCyan(color.black(' deploy-stack ☁️  ')));
+
+    // 2. Ask the user for project configuration
+    const setupType = await select({
+        message: 'Choose your setup mode:',
+        options: [
+            { value: 'quick', label: '⚡ Quickstart (Recommended)', hint: 'Production defaults, minimal prompts' },
+            { value: 'advanced', label: '🛠️  Advanced Configuration', hint: 'Customize health checks, task count, branch, etc.' },
+        ],
+    });
+
+    if (typeof setupType === 'symbol') {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+
+    // 3. Prompt Configuration Group
+    const project = await group(
+        {
+            name: () =>
+                text({
+                    message: 'What is the name of your project? (Type "." to use current directory)',
+                    placeholder: 'my-web-app',
+                    validate: (value) => {
+                        if (!value) return 'Please enter a name.';
+                        if (value !== '.' && value.includes(' ')) return 'Name cannot contain spaces.';
+                    },
+                }),
+            region: () =>
+                select({
+                    message: 'Which AWS region do you want to deploy to?',
+                    options: [
+                        { value: 'us-east-1', label: 'us-east-1 (N. Virginia)' },
+                        { value: 'us-east-2', label: 'us-east-2 (Ohio)' },
+                        { value: 'eu-west-1', label: 'eu-west-1 (Ireland)' },
+                        { value: 'eu-central-1', label: 'EU (Frankfurt)' },
+                        { value: 'ap-southeast-2', label: 'Asia Pacific (Sydney)' },
+                    ],
+                }),
+            port: () =>
+                text({
+                    message: 'What port does your container expose?',
+                    placeholder: '3000',
+                    defaultValue: '3000',
+                }),
+            framework: () =>
+                select({
+                    message: 'Which framework preset should we configure?',
+                    options: [
+                        { value: 'node', label: 'Node.js / Express' },
+                        { value: 'nextjs', label: 'Next.js (Standalone)' },
+                        { value: 'python', label: 'Python FastAPI' },
+                        { value: 'static', label: 'Static Site (Gatsby, React, plain HTML via Nginx)' },
+                    ],
+                }),
+            size: () =>
+                select({
+                    message: 'Select your Fargate compute size:',
+                    options: [
+                        { value: 'micro', label: 'Micro (0.25 vCPU, 512MB RAM) - Best for POCs' },
+                        { value: 'small', label: 'Small (0.5 vCPU, 1GB RAM) - Best for small Projects' },
+                    ],
+                }),
+            // --- Advanced-Only Prompts (Skipped if setupType === 'quick') ---
+            healthCheckPath: () => {
+                if (setupType === 'quick') return undefined;
+                return text({
+                    message: 'ALB Health Check Path:',
+                    placeholder: '/',
+                    defaultValue: '/',
+                });
+            },
+            desiredCount: () => {
+                if (setupType === 'quick') return undefined;
+                return select({
+                    message: 'How many container replicas (tasks) should run?',
+                    options: [
+                        { value: '1', label: '1 Task (Single instance - lowest cost)' },
+                        { value: '2', label: '2 Tasks (High Availability across AZs)' },
+                    ],
+                    defaultValue: '1',
+                });
+            },
+            branch: () => {
+                if (setupType === 'quick') return undefined;
+                return text({
+                    message: 'Primary Git deployment branch for CI/CD:',
+                    placeholder: 'main',
+                    defaultValue: 'main',
+                });
+            },
+        },
+        {
+            onCancel: () => {
+                cancel('Provisioning cancelled.');
+                process.exit(0);
+            },
+        }
+    );
+
+    // 4. Map the user's choices and update the variables
+    const actualProjectName = project.name === '.' ? path.basename(process.cwd()) : project.name;
+    const targetDir = project.name === '.' ? process.cwd() : path.join(process.cwd(), project.name);
+
+    const cpu = project.size === 'small' ? '512' : '256';
+    const memory = project.size === 'small' ? '1024' : '512';
+
+    const computeTier = project.size === 'small' ? 'Small (0.5 vCPU, 1GB RAM)' : 'Micro (0.25 vCPU, 512MB RAM)';
+    const estimatedCost = project.size === 'small' ? '~$35.00 / month' : '~$25.00 / month';
+
+    const healthCheckPath = project.healthCheckPath || '/';
+    const desiredCount = project.desiredCount || '1';
+    const deployBranch = project.branch || 'main';
+
+    // 5. Check for existing files that might be overwritten
+    const dockerfilePath = path.join(targetDir, 'Dockerfile');
+    const tfDirPath = path.join(targetDir, 'terraform');
+
+    if (fsSync.existsSync(dockerfilePath) || fsSync.existsSync(tfDirPath)) {
+        const overwrite = await confirm({
+            message: color.yellow('⚠️  A Dockerfile or terraform/ folder already exists here. Overwrite them?'),
+            initialValue: false,
+        });
+
+        if (!overwrite) {
+            cancel('Provisioning cancelled to protect existing files.');
+            process.exit(0);
+        }
+    }
+
+    const s = spinner();
+    s.start('Provisioning infrastructure...');
+
+    // 6. Provision S3 bucket for Terraform state & enable versioning
+    const stsClient = new STSClient({ region: project.region });
+    let awsAccountId;
+    try {
+        const { Account } = await stsClient.send(new GetCallerIdentityCommand({}));
+        awsAccountId = Account;
+    } catch (error) {
+        s.stop('❌ Failed to authenticate with AWS.');
+        console.error(color.red(`AWS Error: Ensure your credentials are valid. (${error.name})`));
+
+        trackEvent('cli-error', { step: 'aws_sts_auth', error_code: error.name });
+        process.exit(1);
+    }
+
+    let stateBucketName = `${actualProjectName}-tfstate-${awsAccountId}`.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    if (stateBucketName.length > 63) {
+        stateBucketName = stateBucketName.substring(0, 63).replace(/-$/, '');
+    }
+
+    const s3Client = new S3Client({ region: project.region });
+    try {
+        await s3Client.send(new CreateBucketCommand({
+            Bucket: stateBucketName,
+            CreateBucketConfiguration: project.region === 'us-east-1' ? undefined : { LocationConstraint: project.region }
+        }));
+
+        await s3Client.send(new PutBucketVersioningCommand({
+            Bucket: stateBucketName,
+            VersioningConfiguration: { Status: 'Enabled' }
+        }));
+    } catch (error) {
+        if (error.name !== 'BucketAlreadyOwnedByYou') {
+            s.stop('❌ Failed to provision remote state.');
+            console.error(color.red(`AWS S3 Error: ${error.message}`));
+
+            trackEvent('cli-error', { step: 's3_bucket_creation', error_code: error.name });
+            process.exit(1);
+        }
+    }
+
+    s.message('Synthesizing Terraform templates...');
+
+    // 7. Create project directories
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.mkdir(path.join(targetDir, 'terraform'), { recursive: true });
+    await fs.mkdir(path.join(targetDir, '.github', 'workflows'), { recursive: true });
+
+    // 8. Read the template files
+    const tfMainPath = path.join(__dirname, '../../templates', 'terraform', 'main.tf');
+    const tfNetworkPath = path.join(__dirname, '../../templates', 'terraform', 'network.tf');
+    const tfSecretsPath = path.join(__dirname, '../../templates', 'terraform', 'secrets.tf');
+    const tfOidcPath = path.join(__dirname, '../../templates', 'terraform', 'oidc.tf');
+    const tfBackendPath = path.join(__dirname, '../../templates', 'terraform', 'backend.tf');
+    const tfCloudfrontPath = path.join(__dirname, '../../templates', 'terraform', 'cloudfront.tf');
+    const dockerTemplatePath = path.join(__dirname, '../../templates', 'docker', `${project.framework}.Dockerfile`);
+    const githubActionPath = path.join(__dirname, '../../templates', 'github', 'deploy.yml');
+    const readmePath = path.join(__dirname, '../../templates', 'README.md');
+    const gitignorePath = path.join(__dirname, '../../templates', '_gitignore');
+
+    let tfMain = await fs.readFile(tfMainPath, 'utf-8');
+    let tfNetwork = await fs.readFile(tfNetworkPath, 'utf-8');
+    let tfSecrets = await fs.readFile(tfSecretsPath, 'utf-8');
+    let tfOidc = await fs.readFile(tfOidcPath, 'utf-8');
+    let tfBackend = await fs.readFile(tfBackendPath, 'utf-8');
+    let tfCloudfront = await fs.readFile(tfCloudfrontPath, 'utf-8');
+    let dockerContent = await fs.readFile(dockerTemplatePath, 'utf-8');
+    let githubAction = await fs.readFile(githubActionPath, 'utf-8');
+    let readmeContent = await fs.readFile(readmePath, 'utf-8');
+    let gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
+
+    // 9. Update the variables
+    const injectVariables = (content) => {
+        return content
+            .replace(/{{PROJECT_NAME}}/g, actualProjectName)
+            .replace(/{{REGION}}/g, project.region)
+            .replace(/{{PORT}}/g, project.port)
+            .replace(/{{CPU}}/g, cpu)
+            .replace(/{{MEMORY}}/g, memory)
+            .replace(/{{COMPUTE_TIER}}/g, computeTier)
+            .replace(/{{ESTIMATED_COST}}/g, estimatedCost)
+            .replace(/{{STATE_BUCKET}}/g, stateBucketName)
+            .replace(/{{AWS_ACCOUNT_ID}}/g, awsAccountId)
+            .replace(/{{HEALTH_CHECK_PATH}}/g, healthCheckPath)
+            .replace(/{{DESIRED_COUNT}}/g, desiredCount)
+            .replace(/{{DEPLOY_BRANCH}}/g, deployBranch);
+    };
+
+    tfMain = injectVariables(tfMain);
+    tfNetwork = injectVariables(tfNetwork);
+    tfSecrets = injectVariables(tfSecrets);
+    tfOidc = injectVariables(tfOidc);
+    tfBackend = injectVariables(tfBackend);
+    tfCloudfront = injectVariables(tfCloudfront);
+    dockerContent = injectVariables(dockerContent);
+    githubAction = injectVariables(githubAction);
+    readmeContent = injectVariables(readmeContent);
+
+    // 10. Write the finalized files
+    await fs.writeFile(path.join(targetDir, 'terraform', 'main.tf'), tfMain);
+    await fs.writeFile(path.join(targetDir, 'terraform', 'network.tf'), tfNetwork);
+    await fs.writeFile(path.join(targetDir, 'terraform', 'secrets.tf'), tfSecrets);
+    await fs.writeFile(path.join(targetDir, 'terraform', 'oidc.tf'), tfOidc);
+    await fs.writeFile(path.join(targetDir, 'terraform', 'backend.tf'), tfBackend);
+    await fs.writeFile(path.join(targetDir, 'terraform', 'cloudfront.tf'), tfCloudfront);
+    await fs.writeFile(path.join(targetDir, 'Dockerfile'), dockerContent);
+    await fs.writeFile(path.join(targetDir, '.github', 'workflows', 'deploy.yml'), githubAction);
+    await fs.writeFile(path.join(targetDir, 'README.md'), readmeContent);
+    await fs.writeFile(path.join(targetDir, 'terraform', 'secret_keys.json'), "[]");
+
+    // 10.5. Ensure .gitignore exists and contains necessary Terraform ignores
+    const targetGitignore = path.join(targetDir, '.gitignore');
+    if (!fsSync.existsSync(targetGitignore)) {
+        // No gitignore exists? Give them the full template (Terraform + Node + Python)
+        await fs.writeFile(targetGitignore, gitignoreContent);
+    } else {
+        // File exists? Only inject the Terraform rules to prevent duplicates
+        const existingGitignore = await fs.readFile(targetGitignore, 'utf-8');
+
+        if (!existingGitignore.includes('terraform/.terraform/')) {
+            const terraformIgnores = `
+            # Added by deploy-stack (Terraform)
+            terraform/.terraform/
+            terraform/*.tfstate
+            terraform/*.tfstate.backup
+            terraform/.terraform.lock.hcl
+            terraform/secret_keys.json
+            terraform/.terraform.*
+            `;
+            await fs.appendFile(targetGitignore, '\n' + terraformIgnores);
+        }
+    }
+
+    // 11. Track the event in telemetry
+    trackEvent('project_provisioned', {
+        projectName: actualProjectName,
+        framework: project.framework,
+        region: project.region,
+        size: project.size,
+        setup_mode: setupType,
+        desiredCount: desiredCount,
+        duration_ms: Date.now() - startTime
+    });
+
+    s.stop('Infrastructure provisioned successfully!');
+
+    // 12. Provide the Outro, Framework Warnings and Next Steps
+    let frameworkWarnings = '';
+
+    if (project.framework === 'nextjs') {
+        frameworkWarnings =
+            color.bgYellow(color.black(' ⚠️  IMPORTANT: NEXT.JS SETUP REQUIRED ')) +
+            color.yellow('\n    You must modify your next.config file and create a health check route before deploying.') +
+            color.yellow('\n    See the "Critical Application Prerequisites" section in your README.md for copy-paste code.\n\n');
+    }
+
+    outro(`
+    ${color.green('✅ Project provisioned successfully!')}
+    
+        Next steps:
+        1. cd ${project.name}
+        2. Deploy infrastructure:
+           cd terraform && terraform init && terraform apply
+        3. Push to GitHub:
+           git init && git add . && git commit -m "Initial commit"
+
+        ${color.cyan('Once deployed, Terraform will output your new https://*.cloudfront.net URL.')}
+
+    ${color.magenta('🚀 Infrastructure ready! Need help or have feedback? Grab 15 mins with Anton:')}
+    ${color.underline('https://calendly.com/anton-codes-iac/15min')}
+    `);
+}

package/src/commands/secrets.js

@@ -0,0 +1,48 @@
+import { SecretsManagerClient, UpdateSecretCommand } from "@aws-sdk/client-secrets-manager";
+import dotenv from "dotenv";
+import fs from 'fs/promises';
+import { spinner } from '@clack/prompts';
+import color from 'picocolors';
+import path from 'path';
+
+export async function pushSecrets(envFilePath, projectName) {
+    const s = spinner();
+    s.start(`Reading ${envFilePath} and pushing to AWS Secrets Manager...`);
+
+    try {
+        // 1. Read and parse the local .env file
+        const envPath = path.resolve(process.cwd(), envFilePath);
+        const envContent = await fs.readFile(envPath, 'utf-8');
+        const parsedSecrets = dotenv.parse(envContent);
+
+        if (Object.keys(parsedSecrets).length === 0) {
+            s.stop('No secrets found in file.');
+            return;
+        }
+
+        // 2. Initialize the AWS Client
+        // It automatically uses the AWS credentials the user set in their terminal
+        const client = new SecretsManagerClient({});
+
+        // 3. Update the secret string in AWS
+        // The SecretId matches the name we generated in secrets.tf
+        const command = new UpdateSecretCommand({
+            SecretId: `${projectName}-secrets`,
+            SecretString: JSON.stringify(parsedSecrets),
+        });
+
+        await client.send(command);
+
+        const keys = Object.keys(parsedSecrets);
+        const keysFilePath = path.join(process.cwd(), 'terraform', 'secret_keys.json');
+
+        await fs.writeFile(keysFilePath, JSON.stringify(keys, null, 2));
+
+        s.stop(`✅ Successfully pushed ${Object.keys(parsedSecrets).length} secrets to AWS!`);
+        console.log(color.cyan(`\nUpdated ${keysFilePath}`));
+        console.log(color.green('Commit this file and push to GitHub to trigger a deployment with your new variables.'));
+
+    } catch (error) {
+        s.stop(`❌ Failed to push secrets: ${error.message}`);
+    }
+}

package/src/core/telemetry.js

@@ -0,0 +1,39 @@
+import crypto from 'crypto';
+
+const TELEMETRY_ENDPOINT = 'https://app.posthog.com/capture';
+
+const POSTHOG_API_KEY = '___POSTHOG_INGESTION_KEY___';
+
+export function trackEvent(eventName, properties) {
+    // 1. Respect privacy standards
+    if (process.env.DO_NOT_TRACK === '1' || process.env.DO_NOT_TRACK === 'true') {
+        return;
+    }
+
+    // 2. Hash the project name so it is completely anonymous
+    const rawProjectName = properties.projectName || 'unknown';
+    const anonymousProjectId = crypto.createHash('sha256').update(rawProjectName).digest('hex').substring(0, 16);
+
+    // 3. Strip the raw name out of the payload
+    delete properties.projectName;
+
+    const payload = {
+        api_key: POSTHOG_API_KEY,
+        event: eventName,
+        properties: {
+            distinct_id: anonymousProjectId, // Used to count unique projects, not identify them
+            os: process.platform,
+            node_version: process.version,
+            ...properties
+        }
+    };
+
+    // 4. Fire and forget (No 'await' so we don't block the user's terminal)
+    fetch(TELEMETRY_ENDPOINT, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    }).catch(() => {
+        // Silently swallow network errors (e.g., user is offline)
+    });
+}