deploy-stack 0.2.1 → 0.2.3

package/README.md

@@ -4,6 +4,8 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+![deploy-stack CLI demonstration](./docs/demo.gif)
+
 ---
 
 ## The Problem
@@ -118,11 +120,12 @@ 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.
+- [x] **Core MVP:** Interactive CLI, ECS Fargate + ALB Terraform generation, CI/CD, and Secrets sync.
+- [x] **Production Readiness:** CloudFront distribution, S3 State locking, and OIDC security.
+- [x] **Smart Experience:** Zero-config framework auto-discovery for Next.js, Express, and FastAPI.
+- [ ] **State & Storage:** Automated RDS PostgreSQL provisioning and persistent volumes.
+- [ ] **Advanced Networking:** Custom domains (Route 53), ACM SSL configuration, and environment workspaces (staging/prod).
+- [ ] **Security Hardening:** Private VPC subnets with NAT gateways, and AWS WAF integration.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deploy-stack",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "type": "module",
   "bin": {
@@ -14,6 +14,27 @@
     "type": "git",
     "url": "git+https://github.com/anton-codes-iac/deploy-stack.git"
   },
+  "homepage": "https://github.com/anton-codes-iac/deploy-stack#readme",
+  "bugs": {
+    "url": "https://github.com/anton-codes-iac/deploy-stack/issues"
+  },
+  "keywords": [
+    "aws",
+    "terraform",
+    "github-actions",
+    "ci-cd",
+    "ecs",
+    "fargate",
+    "nextjs-deployment",
+    "infrastructure-as-code",
+    "oidc",
+    "deploy-stack",
+    "expressjs",
+    "fastapi",
+    "nextjs",
+    "static-site",
+    "nginx"
+  ],
   "license": "MIT",
   "dependencies": {
     "@aws-sdk/client-s3": "3.1115.0",

package/src/commands/init.js

@@ -1,15 +1,15 @@
-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, log } from '@clack/prompts';
 import color from 'picocolors';
 
 import { checkDependency } from '../utils/system.js';
 import { detectFramework } from '../utils/detector.js';
 import { trackEvent } from '../core/telemetry.js';
+import { getFrameworkWarning } from '../utils/warnings.js';
+import { provisionStateBucket } from '../utils/aws.js';
+import { generateTemplates } from '../utils/generator.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -111,19 +111,6 @@ export async function mainStack() {
                     placeholder: defaultPort,
                     defaultValue: defaultPort,
                 }),
-            framework: () => {
-                if (detectedFramework) return undefined;
-
-                return 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:',
@@ -200,138 +187,38 @@ export async function mainStack() {
     s.start('Provisioning infrastructure...');
 
     // 6. Provision S3 bucket for Terraform state & enable versioning
-    const stsClient = new STSClient({ region: project.region });
-    let awsAccountId;
+    let awsAccountId, stateBucketName;
     try {
-        const { Account } = await stsClient.send(new GetCallerIdentityCommand({}));
-        awsAccountId = Account;
+        const bucketData = await provisionStateBucket(project.region, actualProjectName);
+        awsAccountId = bucketData.awsAccountId;
+        stateBucketName = bucketData.stateBucketName;
     } 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 });
+        s.stop('❌ Failed to provision remote state or authenticate with AWS.');
+        console.error(color.red(`AWS Error: ${error.message}`));
+        trackEvent('cli-error', { step: 'aws_provisioning', error_code: error.name || 'UNKNOWN' });
         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', `${finalFramework}.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);
-        }
-    }
+    // 7. Generate all templates and directories
+    await generateTemplates(targetDir, {
+        PROJECT_NAME: actualProjectName,
+        REGION: project.region,
+        PORT: project.port,
+        CPU: cpu,
+        MEMORY: memory,
+        COMPUTE_TIER: computeTier,
+        ESTIMATED_COST: estimatedCost,
+        STATE_BUCKET: stateBucketName,
+        AWS_ACCOUNT_ID: awsAccountId,
+        HEALTH_CHECK_PATH: healthCheckPath,
+        DESIRED_COUNT: desiredCount,
+        DEPLOY_BRANCH: deployBranch,
+        finalFramework: finalFramework
+    });
 
-    // 11. Track the event in telemetry
+    // 8. Track the event in telemetry
     trackEvent('project_provisioned', {
         projectName: actualProjectName,
         framework: finalFramework,
@@ -344,27 +231,25 @@ export async function mainStack() {
 
     s.stop('Infrastructure provisioned successfully!');
 
-    // 12. Provide the Outro, Framework Warnings and Next Steps
-    let frameworkWarnings = '';
+    // 9. Provide the Outro, Framework Warnings and Next Steps
+    const frameworkWarnings = getFrameworkWarning(finalFramework);
 
-    if (finalFramework === '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');
-    }
+    const cdStep = projectName === '.' ? '' : `1. cd ${projectName}\n        `;
+    const deployStepNum = projectName === '.' ? '1' : '2';
+    const gitStepNum = projectName === '.' ? '2' : '3';
 
     outro(`
     ${color.green('✅ Project provisioned successfully!')}
+
+    ${frameworkWarnings}
     
-        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.')}
+    Next steps:
+    ${cdStep}${deployStepNum}. Deploy infrastructure:
+       cd terraform && terraform init && terraform apply
+    ${gitStepNum}. 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/utils/aws.js

@@ -0,0 +1,38 @@
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import { S3Client, CreateBucketCommand, PutBucketVersioningCommand } from '@aws-sdk/client-s3';
+
+export async function provisionStateBucket(region, projectName) {
+    const stsClient = new STSClient({ region });
+    let awsAccountId;
+
+    // 1. Get AWS Account ID
+    const { Account } = await stsClient.send(new GetCallerIdentityCommand({}));
+    awsAccountId = Account;
+
+    // 2. Format Bucket Name
+    let stateBucketName = `${projectName}-tfstate-${awsAccountId}`.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    if (stateBucketName.length > 63) {
+        stateBucketName = stateBucketName.substring(0, 63).replace(/-$/, '');
+    }
+
+    // 3. Create S3 Bucket & Enable Versioning
+    const s3Client = new S3Client({ region });
+    try {
+        await s3Client.send(new CreateBucketCommand({
+            Bucket: stateBucketName,
+            CreateBucketConfiguration: region === 'us-east-1' ? undefined : { LocationConstraint: region }
+        }));
+
+        await s3Client.send(new PutBucketVersioningCommand({
+            Bucket: stateBucketName,
+            VersioningConfiguration: { Status: 'Enabled' }
+        }));
+    } catch (error) {
+        // Ignore if the bucket already exists and is owned by the user
+        if (error.name !== 'BucketAlreadyOwnedByYou') {
+            throw error;
+        }
+    }
+
+    return { awsAccountId, stateBucketName };
+}

package/src/utils/generator.js

@@ -0,0 +1,56 @@
+import fsSync from 'fs';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export async function generateTemplates(targetDir, config) {
+    // 1. Create 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 });
+
+    // 2. Define paths
+    const templatesDir = path.join(__dirname, '../../templates');
+    const filesToProcess = [
+        { src: 'terraform/main.tf', dest: 'terraform/main.tf' },
+        { src: 'terraform/network.tf', dest: 'terraform/network.tf' },
+        { src: 'terraform/secrets.tf', dest: 'terraform/secrets.tf' },
+        { src: 'terraform/oidc.tf', dest: 'terraform/oidc.tf' },
+        { src: 'terraform/backend.tf', dest: 'terraform/backend.tf' },
+        { src: 'terraform/cloudfront.tf', dest: 'terraform/cloudfront.tf' },
+        { src: `docker/${config.finalFramework}.Dockerfile`, dest: 'Dockerfile' },
+        { src: 'github/deploy.yml', dest: '.github/workflows/deploy.yml' },
+        { src: 'README.md', dest: 'README.md' }
+    ];
+
+    // 3. Process standard files
+    for (const file of filesToProcess) {
+        let content = await fs.readFile(path.join(templatesDir, file.src), 'utf-8');
+
+        // Inject variables
+        for (const [key, value] of Object.entries(config)) {
+            content = content.replace(new RegExp(`{{${key}}}`, 'g'), value);
+        }
+
+        await fs.writeFile(path.join(targetDir, file.dest), content);
+    }
+
+    // 4. Create empty secrets file
+    await fs.writeFile(path.join(targetDir, 'terraform', 'secret_keys.json'), "[]");
+
+    // 5. Handle .gitignore appending cleanly
+    const targetGitignore = path.join(targetDir, '.gitignore');
+    const gitignoreContent = await fs.readFile(path.join(templatesDir, '_gitignore'), 'utf-8');
+
+    if (!fsSync.existsSync(targetGitignore)) {
+        await fs.writeFile(targetGitignore, gitignoreContent);
+    } else {
+        const existingGitignore = await fs.readFile(targetGitignore, 'utf-8');
+        if (!existingGitignore.includes('terraform/.terraform/')) {
+            await fs.appendFile(targetGitignore, '\n# Added by deploy-stack (Terraform)\nterraform/.terraform/\nterraform/*.tfstate\nterraform/*.tfstate.backup\nterraform/.terraform.lock.hcl\nterraform/secret_keys.json\nterraform/.terraform.*\n');
+        }
+    }
+}

package/src/utils/warnings.js

@@ -0,0 +1,21 @@
+import color from 'picocolors';
+
+export function getFrameworkWarning(frameworkId) {
+    switch (frameworkId) {
+        case 'nextjs':
+            return (
+                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')
+            );
+        case 'node':
+            return (
+                color.bgYellow(color.black(' ⚠️  IMPORTANT: NODE.JS SETUP REQUIRED ')) +
+                color.yellow('\n    1. Ensure your package.json has a "start" script (e.g., "start": "node index.js").') +
+                color.yellow('\n    2. Your app must listen on 0.0.0.0 (not localhost) to receive traffic in Docker.\n\n')
+            );
+        // Python / FastAPI warnings can be added here easily!
+        default:
+            return '';
+    }
+}

package/templates/README.md

@@ -82,4 +82,12 @@ const nextConfig: NextConfig = {
 };
 
 export default nextConfig;
-```
+```
+
+### 3. Container Network Binding (Node & Python)
+
+When running inside a Docker container, your server must bind to all network interfaces (`0.0.0.0`), not just `localhost` or `127.0.0.1`. If you bind to localhost, the AWS Load Balancer will not be able to route traffic to your application.
+
+Make sure your app is configured correctly:
+* **Express.js:** `app.listen(port, '0.0.0.0', () => ...)`
+* **FastAPI:** `uvicorn.run(app, host="0.0.0.0", port=8000)`

package/templates/docker/node.Dockerfile

@@ -1,7 +1,22 @@
-FROM node:18-alpine
+FROM node:20-alpine
+
+# 1. Set production environment (optimizes Node and prevents dev dependencies)
+ENV NODE_ENV=production
+
 WORKDIR /app
+
+# 2. Copy only dependency files first to cache the npm install layer
 COPY package*.json ./
-RUN npm install
+
+# 3. Use npm ci for strict, deterministic, and faster CI/CD installs
+RUN npm ci
+
+# 4. Copy the rest of the application source code
 COPY . .
+
+# 5. DevSecOps best practice: do not run the container as root
+USER node
+
 EXPOSE {{PORT}}
+
 CMD ["npm", "start"]