deploy-stack 0.9.15 → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anton-codes-iac (https://github.com/anton-codes-iac)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,8 +2,10 @@
 
 > 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.
 
+[![NPM Version](https://img.shields.io/npm/v/deploy-stack.svg?color=blue&logo=npm)](https://www.npmjs.com/package/deploy-stack)
+[![Node.js Support](https://img.shields.io/node/v/deploy-stack.svg?color=brightgreen)](https://www.npmjs.com/package/deploy-stack)
+[![Security: Trivy](https://img.shields.io/badge/Security-Trivy_Scanned-blue.svg?logo=docker)](https://trivy.dev/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Security: Trivy](https://img.shields.io/badge/Security-Trivy_Scanned-blue.svg)](https://trivy.dev/)
 
 <!-- ![deploy-stack CLI demonstration](./docs/demo.gif) -->
 
@@ -25,22 +27,26 @@ You retain complete ownership of your infrastructure code without relying on bla
 
 ## ✨ Features
 
-* **Zero Vendor Lock-In:** Generates standard, clean `.tf` files. Modify, expand, or decouple them at any time.
-* **Automated DevSecOps:** Integrated Trivy vulnerability scanning for your infrastructure (IaC) and Docker containers on every GitHub Actions run.
-* **Hardened, Unprivileged Containers:** Built-in Dockerfile generators explicitly drop root privileges and utilize `nginx-unprivileged` for maximum Fargate security compliance.
-* **Cost & Observability Baselines:** Prevents runaway AWS bills with explicit 14-day CloudWatch log retention policies and auto-generates 5XX error alerting.
-* **Safe Overwrite Flow:** Idempotent CLI safely backs up existing configurations to timestamped `.bak` files and updates `.gitignore` to guarantee zero data loss during rapid iteration.
-* **Framework Agnostic:** Tailored container presets for Next.js, Express.js, FastAPI, Go, Django, Ruby on Rails, Nuxt 3, and **Zero-Config Static Sites** (React, Vue, SvelteKit, Astro, Vite).
-* **Smart Git Integration:** Automatically detects your working branch (`main`, `master`, `develop`) and binds it directly to the generated GitHub Actions pipeline.
-* **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 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 Terraform (1.7+) 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.
-* **Ecosystem Ready:** Integrated directly with the [deploy-stack GitHub Action](https://github.com/marketplace/actions/deploy-stack-aws-fargate-terraform-deploy) for a secure, boilerplate-free continuous deployment pipeline.
+**🚀 Zero-Config Deployments**
+* **Framework Agnostic:** Tailored container presets for Next.js, Express.js, FastAPI, Go, Django, Rails, Nuxt 3, and Static Sites (React, Vue, SvelteKit, Astro).
+* **Smart Discovery:** Automatically detects build output directories and generates highly optimized, multi-stage Dockerfiles.
 * **Database Scaffolding:** Automatically provisions fully isolated, zero-trust AWS RDS PostgreSQL databases for backend monoliths.
-* **Smart Boilerplate Resolution:** Intelligently detects and optionally safely disables default framework CI pipelines (e.g., Rails `ci.yml`) that crash in isolated environments, guaranteeing a green pipeline on the first run.
-* **Safe Teardown:** Completely remove all generated AWS resources and empty S3 state buckets with a single `destroy` command.
+
+**🛡️ DevSecOps & Security**
+* **Automated Trivy Scanning:** Integrated IaC and container vulnerability scanning on every GitHub Actions run.
+* **Hardened Containers:** Explicitly drops root privileges using `nginx-unprivileged` and distroless bases for strict Fargate security compliance.
+* **Zero-Secret CI/CD:** Utilizes AWS IAM OpenID Connect (OIDC) for automated deployments—no long-lived AWS keys in GitHub.
+* **Built-in Secrets Manager:** Push local `.env` variables directly into encrypted AWS Secrets Manager vaults with a single CLI command.
+
+**☁️ AWS Native Architecture**
+* **Production Defaults:** Provisions an Amazon ECS Fargate cluster fronted by an Application Load Balancer across multiple availability zones.
+* **Global Edge Acceleration:** Integrated AWS CloudFront CDN distribution with SSL termination and edge caching.
+* **Cost & Observability:** Prevents runaway AWS bills with explicit 14-day CloudWatch log retention and auto-generates 5XX error alerting.
+
+**🛠️ Developer Experience**
+* **Zero Vendor Lock-In:** Generates standard, readable Terraform (`.tf`) files. You own the infrastructure.
+* **Native S3 State Locking:** Automatically creates an encrypted S3 state bucket utilizing modern Terraform concurrency locking.
+* **Safe Iteration:** Idempotent CLI safely backs up existing configurations to `.bak` files to guarantee zero data loss.
 
 ---
 
@@ -52,58 +58,43 @@ Run the CLI directly in your project root:
 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** for custom scaling and branch names)
-3. **Zero-Config Detection:** The CLI automatically scans your project to detect your framework. For static sites, it intelligently discovers your build output directory (`dist`, `build`, `.output`, etc.) and dynamically configures the hardened Nginx container.
-4. **AWS Region & Compute Tier:** (Select your target region and Fargate size with live cost estimates)
+The interactive wizard will analyze your codebase, detect your framework, estimate your AWS costs, and generate your Terraform and GitHub Actions configurations.
 
 ---
 
-## 🔑 Securely Managing Secrets
+## 🧰 CLI Command Reference
 
-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.*
+`deploy-stack` manages the entire lifecycle of your infrastructure.
 
-*Note: For frameworks like Ruby on Rails, `deploy-stack` automatically detects your local `config/master.key` and securely injects it into AWS Secrets Manager via git-ignored `.auto.tfvars` files—ensuring zero hardcoded secrets.*
+* **`npx deploy-stack apply`**
+  Wraps Terraform execution in a beautiful, terminal-friendly UI. Automatically provisions your AWS infrastructure and outputs your live CDN and Load Balancer URLs.
+  
+* **`npx deploy-stack secrets push <file>`**
+  Securely encrypts your local environment variables (e.g., `.env.production`) into AWS Secrets Manager and maps them to your ECS container at runtime.
 
----
+* **`npx deploy-stack doctor`**
+  Scans your local environment and generated files to ensure all required dependencies (Docker, Terraform, AWS CLI) are installed and configured correctly.
 
-## 🛠️ 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.
+* **`npx deploy-stack destroy`**
+  Safely tears down your ECS cluster, Load Balancers, and networking resources to stop AWS billing. Includes an interactive prompt to optionally retain or delete your S3 remote state bucket.
 
----
+* **`npx deploy-stack eject`**
+  Strips all `deploy-stack` metadata and management tags from your project, leaving behind pure, standard Terraform and GitHub Actions files. You retain 100% ownership.
 
-## 🗑️ Infrastructure Teardown
-To safely completely remove your ECS cluster, load balancers, and empty the remote S3 state bucket, run:
-`npx deploy-stack destroy`
+* **`npx deploy-stack --headless`**
+  Bypasses the interactive wizard for fully programmatic execution. Perfect for CI/CD pipelines, custom scripts, or AI agent integration. Accepts flags like `--framework=static`, `--region=us-east-1`, and `--size=micro`.
 
 ---
 
 ## 📁 Generated File Structure
 
-Running the CLI generates a modular architecture tailored to your service:
+Running the CLI seamlessly integrates a modular, DevSecOps-hardened architecture into your repository:
 
 ```text
 your-project/
 ├── Dockerfile                  # Multi-stage container preset
+├── .dockerignore               # Prevents secret leaks into container builds
+├── .gitignore                  # Automatically updated to ignore tfstate and .bak files
 ├── .github/
 │   └── workflows/
 │       └── deploy.yml          # Keyless OIDC CI/CD deployment pipeline
@@ -138,16 +129,14 @@ your-project/
 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
+```bash
 npx deploy-stack --no-telemetry
-\`\`\`
+```
 
 ---
 
 ## 🗺️ Roadmap
 
-## 🗺️ Roadmap
-
 ### Phase 1–3: The Core Engine (Completed)
 - [x] **Core MVP:** Interactive CLI, ECS Fargate + ALB generation, CI/CD, and Secrets sync.
 - [x] **Production Readiness:** CloudFront CDN edge distribution, native S3 state locking, and secure OIDC integration.
@@ -160,15 +149,15 @@ npx deploy-stack --no-telemetry
 - [x] **Zero Vendor Lock-In:** Explicit `npx deploy-stack eject` command to safely strip `ManagedBy` tags and CLI metadata, leaving behind pure IaC.
 - [x] **Heavy Backend Monoliths:** Hardened, unprivileged container adapters for Go, Nuxt.js, Django, and Rails, complete with automated zero-trust RDS PostgreSQL provisioning.
 
-### Phase 5: The Activation Engine (Pre-1.0 Growth Loops)
+### Phase 5: The Activation Engine (v0.10.0 - Current)
+- [x] **Local Execution Wrapper:** Native `deploy-stack apply` command with terminal-optimized streaming to eliminate Terraform context switching.
+- [x] **Ecosystem Integrations:** Publishing official plugins to the Astro Integrations directory and backend framework ecosystems.
 - [ ] **Ephemeral PR Previews:** Generating live preview URLs on every GitHub Pull Request, turning single-user tests into team-wide advertisements.
-- [ ] **Next.js Image Optimization Handler:** A drop-in AWS Serverless handler (Lambda + CloudFront) to process images affordably, removing a massive Vercel lock-in hurdle.
 - [ ] **GitHub Deployments UI Sync:** Wiring up the native GitHub "Environments" tab for instant visual validation that the CLI succeeded in the background.
 
 ### Phase 6: Workflow Interception (IDE, AI, & Local Bridges)
 - [ ] **AI Agent Rulesets:** Publishing `.cursorrules` and Copilot instructions that teach AI assistants exactly how to utilize the CLI on the user's behalf.
 - [ ] **Docker Compose to ECS Translator:** Automatically converting a familiar local `docker-compose.yml` into production ECS task definitions.
-- [ ] **Framework Registries:** Submitting official plugins to the Astro Integrations directory and Nuxt Modules to secure passive, sustained discovery.
 - [ ] **Dry-Run Visualization:** Generating a local `docker-compose.yml` mirror and a visual architecture map for local infrastructure validation.
 
 ---

package/bin/cli.js

@@ -5,6 +5,7 @@ import { destroyStack } from '../src/commands/destroy.js';
 import { runDoctor } from '../src/commands/doctor.js';
 import { pushSecrets } from '../src/commands/secrets.js';
 import { ejectStack } from '../src/commands/eject.js';
+import { applyStack } from '../src/commands/apply.js';
 
 // 1. Extract the telemetry flag and set the environment variable
 const rawArgs = process.argv.slice(2);
@@ -17,11 +18,30 @@ if (hasNoTelemetry) {
 // 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
+// 3. Parse headless flags
+const isHeadless = args.includes('--headless');
+const getFlag = (flagName) => {
+    const match = args.find(a => a.startsWith(`--${flagName}=`));
+    return match ? match.split('=')[1] : undefined;
+};
+const headlessOptions = isHeadless ? {
+    dir: getFlag('dir'),
+    framework: getFlag('framework'),
+    region: getFlag('region'),
+    port: getFlag('port'),
+    size: getFlag('size'),
+    healthCheckPath: getFlag('healthCheckPath'),
+    desiredCount: getFlag('desiredCount'),
+    branch: getFlag('branch')
+} : {};
+
+// 4. 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] === 'apply') {
+    applyStack().catch(console.error);
 } else if (args[0] === 'doctor') {
     runDoctor().catch(console.error);
 } else if (args[0] === 'destroy') {
@@ -29,5 +49,5 @@ if (args[0] === 'secrets' && args[1] === 'push') {
 } else if (args[0] === 'eject') {
     ejectStack().catch(console.error);
 } else {
-    mainStack().catch(console.error);
+    mainStack({ isHeadless, headlessOptions }).catch(console.error);
 }

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "deploy-stack",
-  "version": "0.9.15",
+  "version": "0.11.0",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "type": "module",
   "bin": {
     "deploy-stack": "bin/cli.js"

package/src/commands/apply.js

@@ -0,0 +1,133 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { intro, outro, spinner, log, cancel } from '@clack/prompts';
+import color from 'picocolors';
+
+// Helper to run a command while piping the latest stdout line into a @clack spinner
+function runTerraformCommand(args, cwd, spin, loadingPrefix) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('terraform', args, { cwd });
+        let errorOutput = '';
+        let isDone = false;
+
+        child.stdout.on('data', (data) => {
+            if (isDone) return;
+            const lines = data.toString().split('\n').filter(line => line.trim() !== '');
+            if (lines.length > 0) {
+                const latestLine = lines[lines.length - 1].trim();
+                const display = latestLine.length > 120 ? latestLine.substring(0, 117) + '...' : latestLine;
+                spin.message(`${loadingPrefix} - ${color.dim(display)}`);
+            }
+        });
+
+        child.stderr.on('data', (data) => {
+            errorOutput += data.toString();
+        });
+
+        child.on('close', (code) => {
+            isDone = true;
+            if (code === 0) {
+                resolve();
+            } else {
+                reject(new Error(errorOutput || `Terraform exited with code ${code}`));
+            }
+        });
+
+        child.on('error', (err) => {
+            isDone = true;
+            reject(err);
+        });
+    });
+}
+
+// Helper to pull JSON outputs from Terraform
+function getTerraformOutputs(cwd) {
+    return new Promise((resolve) => {
+        const child = spawn('terraform', ['output', '-json'], { cwd });
+        let outputData = '';
+
+        child.stdout.on('data', (data) => {
+            outputData += data.toString();
+        });
+
+        child.on('close', (code) => {
+            if (code === 0) {
+                try {
+                    resolve(JSON.parse(outputData));
+                } catch {
+                    resolve({});
+                }
+            } else {
+                resolve({});
+            }
+        });
+
+        child.on('error', () => {
+            resolve({});
+        });
+    });
+}
+
+export async function applyStack() {
+    intro(color.bgCyan(color.black(' deploy-stack apply ☁️  ')));
+
+    const targetDir = process.cwd();
+    const tfDir = path.join(targetDir, 'terraform');
+
+    // 1. Verify that the user is inside a project generated by deploy-stack
+    if (!fs.existsSync(tfDir) || !fs.existsSync(path.join(tfDir, 'main.tf'))) {
+        log.error(color.red('✖ No terraform directory found in current path.'));
+        log.message('Please run "npx deploy-stack" first to generate your infrastructure templates.');
+        process.exit(1);
+    }
+
+    const s = spinner();
+
+    try {
+        // 2. Run terraform init
+        s.start('Initializing Terraform plugins...');
+        await runTerraformCommand(['init', '-upgrade'], tfDir, s, 'Initializing');
+        log.success('Terraform initialized.');
+
+        // 3. Run terraform apply
+        s.start('Provisioning AWS infrastructure (this may take 3–5 minutes)...');
+        await runTerraformCommand(['apply', '-auto-approve'], tfDir, s, 'Provisioning');
+        s.stop('AWS infrastructure provisioned successfully!');
+
+        // 4. Extract and print the outputs
+        const outputs = await getTerraformOutputs(tfDir);
+
+        const cfUrl = outputs.cloudfront_url?.value;
+        const albUrl = outputs.alb_direct_url?.value;
+
+        let finalMessage = color.green('✅ Infrastructure is live!');
+        if (cfUrl) finalMessage += `\n  🌍 CDN: ${color.cyan(cfUrl)}`;
+        if (albUrl) finalMessage += `\n  🚦 ALB: ${color.gray(albUrl)}`;
+
+        outro(`${finalMessage}\n\n  ${color.yellow('Push code to deploy your app and clear the 503 error:')}\n  ${color.cyan('git add . && git commit -m "ci: infra" && git push origin main')}`);
+
+        process.exit(0);
+
+    } catch (error) {
+        s.stop(color.red('❌ Terraform apply failed.'));
+
+        const errString = error.message || "";
+
+        if (errString.includes('EntityAlreadyExists') && errString.includes('token.actions.githubusercontent.com')) {
+            log.error(color.red('GitHub OIDC Provider Conflict Detected'));
+            log.message('AWS only allows one GitHub Actions provider per account, and you already have one configured.');
+            log.message('');
+            log.message(`${color.bold('How to fix this:')}`);
+            log.message(`1. Open ${color.cyan('terraform/oidc.tf')}`);
+            log.message(`2. Change ${color.green('create_oidc_provider = true')} to ${color.green('create_oidc_provider = false')}`);
+            log.message(`3. Run ${color.cyan('npx deploy-stack apply')} again.`);
+        } else {
+            // Generic fallback for unknown errors
+            log.error(color.red(errString));
+            log.message(`${color.bold('To debug manually, navigate to your terraform folder:')}`);
+            log.message(color.cyan('cd terraform && terraform apply'));
+        }
+        process.exit(1);
+    }
+}

package/src/commands/destroy.js

@@ -2,11 +2,45 @@ import fsSync from 'fs';
 import path from 'path';
 import { intro, outro, confirm, spinner, cancel } from '@clack/prompts';
 import color from 'picocolors';
-import { execSync } from 'child_process';
+import { execSync, spawn } from 'child_process';
 import { teardownStateBucket } from '../utils/aws.js';
 import { checkDependency } from '../utils/system.js';
 import { trackEvent, flushTelemetry } from '../core/telemetry.js';
 
+// Helper to run a command while piping the latest stdout line into a @clack spinner
+function runTerraformCommand(args, cwd, spin, loadingPrefix) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('terraform', args, { cwd });
+        let errorOutput = '';
+        let isDone = false;
+
+        child.stdout.on('data', (data) => {
+            if (isDone) return;
+            const lines = data.toString().split('\n').filter(line => line.trim() !== '');
+            if (lines.length > 0) {
+                const latestLine = lines[lines.length - 1].trim();
+                const display = latestLine.length > 120 ? latestLine.substring(0, 117) + '...' : latestLine;
+                spin.message(`${loadingPrefix} - ${color.dim(display)}`);
+            }
+        });
+
+        child.stderr.on('data', (data) => {
+            errorOutput += data.toString();
+        });
+
+        child.on('close', (code) => {
+            isDone = true;
+            if (code === 0) resolve();
+            else reject(new Error(errorOutput || `Terraform exited with code ${code}`));
+        });
+
+        child.on('error', (err) => {
+            isDone = true;
+            reject(err);
+        });
+    });
+}
+
 export async function destroyStack() {
     intro(color.bgRed(color.white(' deploy-stack destroy 🗑️  ')));
 
@@ -46,23 +80,34 @@ export async function destroyStack() {
     const region = regionMatch ? regionMatch[1] : 'us-east-1';
 
     // 2. Execute Terraform Destroy
-    console.log(color.cyan('\nInitiating Terraform destroy (this may take a few minutes)...\n'));
+    s.start('Destroying AWS compute resources (this takes a few minutes)...');
     try {
-        execSync('terraform destroy -auto-approve', { cwd: tfDirPath, stdio: 'inherit' });
+        await runTerraformCommand(['destroy', '-auto-approve'], tfDirPath, s, 'Destroying');
+        s.stop('AWS compute resources destroyed.');
     } catch (error) {
-        console.error(color.red('\n✖ Terraform destroy failed. Please check the output above.'));
+        s.stop(color.red('❌ Terraform destroy failed.'));
+        console.error(color.red(error.message));
         process.exit(1);
     }
 
     // 3. Clean up the S3 State Bucket
     if (bucketName) {
-        s.start(`Emptying and deleting S3 state bucket: ${bucketName}...`);
-        try {
-            await teardownStateBucket(region, bucketName);
-            s.stop(`S3 bucket ${bucketName} successfully deleted.`);
-        } catch (error) {
-            s.stop(`❌ Failed to delete S3 bucket. You may need to delete it manually in the AWS Console.`);
-            console.error(color.red(`AWS Error: ${error.message}`));
+        const deleteS3Bucket = await confirm({
+            message: color.yellow(`AWS compute resources destroyed. Do you also want to permanently delete the S3 state bucket?\n  (Select 'No' if you plan to run 'deploy-stack apply' later to spin this back up.)`),
+            initialValue: false,
+        });
+
+        if (deleteS3Bucket && typeof deleteS3Bucket !== 'symbol') {
+            s.start(`Emptying and deleting S3 state bucket: ${bucketName}...`);
+            try {
+                await teardownStateBucket(region, bucketName);
+                s.stop(`S3 bucket ${bucketName} successfully deleted.`);
+            } catch (error) {
+                s.stop(`❌ Failed to delete S3 bucket. You may need to delete it manually in the AWS Console.`);
+                console.error(color.red(`AWS Error: ${error.message}`));
+            }
+        } else {
+            console.log(color.cyan(`\n  S3 bucket retained. You can run 'npx deploy-stack apply' anytime to restore your infrastructure.`));
         }
     }
 

package/src/commands/init.js

@@ -13,7 +13,7 @@ import { provisionStateBucket } from '../utils/aws.js';
 import { generateTemplates } from '../utils/generator.js';
 import { handleExistingFiles } from '../utils/backup.js';
 
-export async function mainStack() {
+export async function mainStack({ isHeadless = false, headlessOptions = {} } = {}) {
     const startTime = Date.now();
 
     // 0. Silent Pre-flight check
@@ -24,179 +24,212 @@ export async function mainStack() {
         process.exit(1);
     }
 
-    // 1. Start the CLI
-    intro(color.bgCyan(color.black(' deploy-stack ☁️  ')));
-
-    // 2. Ask for the target directory FIRST
-    const projectName = await text({
-        message: 'Where should we generate the infrastructure? (Type "." for current directory)',
-        placeholder: '.',
-        initialValue: '.',
-        validate: (value) => {
-            if (!value) return 'Please enter a name or directory.';
-            if (value !== '.' && value.includes(' ')) return 'Name cannot contain spaces.';
-        },
-    });
+    const getFlag = (key, defaultValue) => headlessOptions[key] !== undefined ? headlessOptions[key] : defaultValue;
 
-    if (typeof projectName === 'symbol') {
-        cancel('Operation cancelled.');
-        process.exit(0);
-    }
+    let projectName, actualProjectName, targetDir;
+    let finalFramework, detectedFramework;
+    let djangoWsgi = 'core.wsgi';
+    let setupType = 'quick';
+    let needsDatabase = false;
+    let disableDefaultCI = false;
+    let project = {};
+    let currentGitBranch = 'main';
 
-    const actualProjectName = projectName === '.' ? path.basename(process.cwd()) : projectName;
-    const targetDir = projectName === '.' ? process.cwd() : path.join(process.cwd(), projectName);
+    if (isHeadless) {
+        // --- HEADLESS MODE ---
+        projectName = getFlag('dir', '.');
+        actualProjectName = projectName === '.' ? path.basename(process.cwd()) : projectName;
+        targetDir = projectName === '.' ? process.cwd() : path.join(process.cwd(), projectName);
+
+        detectedFramework = detectFramework(targetDir);
+        finalFramework = getFlag('framework', detectedFramework ? detectedFramework.id : 'static');
+
+        project = {
+            region: getFlag('region', 'us-east-1'),
+            port: getFlag('port', finalFramework === 'static' ? '8080' : '3000'),
+            size: getFlag('size', 'micro'),
+            healthCheckPath: getFlag('healthCheckPath', '/'),
+            desiredCount: getFlag('desiredCount', '1'),
+            branch: getFlag('branch', 'main')
+        };
+
+        console.log(color.cyan(`🤖 Running deploy-stack in headless mode [${finalFramework} -> ${project.region}]`));
+    } else {
+        // --- INTERACTIVE MODE ---
+        // 1. Start the CLI
+        intro(color.bgCyan(color.black(' deploy-stack ☁️  ')));
+
+        // 2. Ask for the target directory FIRST
+        const projectName = await text({
+            message: 'Where should we generate the infrastructure? (Type "." for current directory)',
+            placeholder: '.',
+            initialValue: '.',
+            validate: (value) => {
+                if (!value) return 'Please enter a name or directory.';
+                if (value !== '.' && value.includes(' ')) return 'Name cannot contain spaces.';
+            },
+        });
 
-    // 2.5 Run the scanner
-    const detectedFramework = detectFramework(targetDir);
-    if (detectedFramework) {
-        log.success(`Auto-detected framework: ${detectedFramework.name}`);
-    }
+        if (typeof projectName === 'symbol') {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+
+        const actualProjectName = projectName === '.' ? path.basename(process.cwd()) : projectName;
+        const targetDir = projectName === '.' ? process.cwd() : path.join(process.cwd(), projectName);
 
-    // 2.6 Resolve the framework
-    let finalFramework = detectedFramework ? detectedFramework.id : null;
+        // 2.5 Run the scanner
+        const detectedFramework = detectFramework(targetDir);
+        if (detectedFramework) {
+            log.success(`Auto-detected framework: ${detectedFramework.name}`);
+        }
+
+        // 2.6 Resolve the framework
+        let finalFramework = detectedFramework ? detectedFramework.id : null;
+
+        if (!finalFramework) {
+            finalFramework = await select({
+                message: 'Which framework preset should we configure?',
+                options: [
+                    { value: 'node', label: 'Node.js / Express' },
+                    { value: 'nextjs', label: 'Next.js (Standalone)' },
+                    { value: 'nuxt', label: 'Nuxt 3 (SSR)' },
+                    { value: 'python', label: 'Python FastAPI' },
+                    { value: 'django', label: 'Django (Python)' },
+                    { value: 'rails', label: 'Ruby on Rails' },
+                    { value: 'go', label: 'Go (Golang)' },
+                    { value: 'static', label: 'Static Site (Gatsby, React, plain HTML via Nginx)' },
+                ],
+            });
 
-    if (!finalFramework) {
-        finalFramework = await select({
-            message: 'Which framework preset should we configure?',
+            if (typeof finalFramework === 'symbol') {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+        }
+
+        // --- DJANGO SPECIFIC PROMPT ---
+        let djangoWsgi = 'core.wsgi';
+        if (finalFramework === 'django') {
+            djangoWsgi = await text({
+                message: 'What is the Python module path to your Django wsgi.py?',
+                placeholder: 'core.wsgi',
+                initialValue: 'core.wsgi',
+            });
+            if (typeof djangoWsgi === 'symbol') process.exit(0);
+        }
+
+        // 3. Prompt for Setup Mode
+        const setupType = await select({
+            message: 'Choose your setup mode:',
             options: [
-                { value: 'node', label: 'Node.js / Express' },
-                { value: 'nextjs', label: 'Next.js (Standalone)' },
-                { value: 'nuxt', label: 'Nuxt 3 (SSR)' },
-                { value: 'python', label: 'Python FastAPI' },
-                { value: 'django', label: 'Django (Python)' },
-                { value: 'rails', label: 'Ruby on Rails' },
-                { value: 'go', label: 'Go (Golang)' },
-                { value: 'static', label: 'Static Site (Gatsby, React, plain HTML via Nginx)' },
+                { 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 finalFramework === 'symbol') {
+        if (typeof setupType === 'symbol') {
             cancel('Operation cancelled.');
             process.exit(0);
         }
-    }
-
-    // --- DJANGO SPECIFIC PROMPT ---
-    let djangoWsgi = 'core.wsgi';
-    if (finalFramework === 'django') {
-        djangoWsgi = await text({
-            message: 'What is the Python module path to your Django wsgi.py?',
-            placeholder: 'core.wsgi',
-            initialValue: 'core.wsgi',
-        });
-        if (typeof djangoWsgi === 'symbol') process.exit(0);
-    }
-
-    // 3. Prompt for Setup Mode
-    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);
-    }
 
-    // 4. Set intelligent defaults & check current Git branch
-    let defaultPort = '3000';
+        // 4. Set intelligent defaults & check current Git branch
+        let defaultPort = '3000';
 
-    if (finalFramework === 'static') defaultPort = '8080';
-    if (finalFramework === 'python' || finalFramework === 'django') defaultPort = '8000';
-    if (finalFramework === 'rails') defaultPort = '3000';
-    if (finalFramework === 'go') defaultPort = '8080';
+        if (finalFramework === 'static') defaultPort = '8080';
+        if (finalFramework === 'python' || finalFramework === 'django') defaultPort = '8000';
+        if (finalFramework === 'rails') defaultPort = '3000';
+        if (finalFramework === 'go') defaultPort = '8080';
 
-    let currentGitBranch = 'main';
-    try {
-        currentGitBranch = execSync('git symbolic-ref --short HEAD', { cwd: targetDir, stdio: 'pipe' }).toString().trim();
-    } catch (e) {
-        // Not a git repo yet, fallback to 'main'
-    }
+        let currentGitBranch = 'main';
+        try {
+            currentGitBranch = execSync('git symbolic-ref --short HEAD', { cwd: targetDir, stdio: 'pipe' }).toString().trim();
+        } catch (e) {
+            // Not a git repo yet, fallback to 'main'
+        }
 
-    // 5. Ask for Managed Database (Only for Backend/Fullstack Frameworks)
-    let needsDatabase = false;
-    const isBackendFramework = ['node', 'nextjs', 'nuxt', 'python', 'django', 'rails', 'go'].includes(finalFramework);
+        // 5. Ask for Managed Database (Only for Backend/Fullstack Frameworks)
+        let needsDatabase = false;
+        const isBackendFramework = ['node', 'nextjs', 'nuxt', 'python', 'django', 'rails', 'go'].includes(finalFramework);
 
-    if (isBackendFramework) {
-        const dbChoice = await confirm({
-            message: 'Do you need a managed AWS RDS PostgreSQL database? (Adds ~$14/month or uses AWS Free Tier)',
-            initialValue: false,
-        });
+        if (isBackendFramework) {
+            const dbChoice = await confirm({
+                message: 'Do you need a managed AWS RDS PostgreSQL database? (Adds ~$14/month or uses AWS Free Tier)',
+                initialValue: false,
+            });
 
-        if (typeof dbChoice === 'symbol') {
-            cancel('Provisioning cancelled.')
-            process.exit(0);
+            if (typeof dbChoice === 'symbol') {
+                cancel('Provisioning cancelled.')
+                process.exit(0);
+            }
+            needsDatabase = dbChoice;
         }
-        needsDatabase = dbChoice;
-    }
 
-    // 6. Prompt Configuration Group
-    const project = await group(
-        {
-            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: defaultPort,
-                    defaultValue: defaultPort,
-                }),
-            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: currentGitBranch,
-                    defaultValue: currentGitBranch,
-                });
-            },
-        },
-        {
-            onCancel: () => {
-                cancel('Provisioning cancelled.');
-                process.exit(0);
+        // 6. Prompt Configuration Group
+        const project = await group(
+            {
+                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: defaultPort,
+                        defaultValue: defaultPort,
+                    }),
+                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: currentGitBranch,
+                        defaultValue: currentGitBranch,
+                    });
+                },
             },
-        }
-    );
+            {
+                onCancel: () => {
+                    cancel('Provisioning cancelled.');
+                    process.exit(0);
+                },
+            }
+        );
+    }
 
     // 7. Map the user's choices and update the variables
     const cpu = project.size === 'small' ? '512' : '256';
@@ -215,40 +248,45 @@ export async function mainStack() {
     const buildDir = detectedFramework?.buildDir || 'dist';
 
     // 7.4 Check for conflicting CI boilerplate (Rails)
-    let disableDefaultCI = false;
     if (finalFramework === 'rails') {
         const ciPath = path.join(targetDir, '.github', 'workflows', 'ci.yml');
         const dependabotPath = path.join(targetDir, '.github', 'dependabot.yml');
 
         if (fsSync.existsSync(ciPath) || fsSync.existsSync(dependabotPath)) {
-            console.log('');
-            const ciContent = await confirm({
-                message: color.yellow('We detected default Rails GitHub Actions (ci.yml, dependabot.yml) that usually crash in isolated CI environments without a database. Would you like deploy-stack to safely disable them by renaming them to .bak?'),
-                initialValue: true,
-            });
-            if (typeof ciContent === 'symbol') {
-                cancel('Provisioning cancelled.');
-                process.exit(0);
+            if (!isHeadless) {
+                console.log('');
+                const ciContent = await confirm({
+                    message: color.yellow('We detected default Rails GitHub Actions (ci.yml, dependabot.yml) that usually crash in isolated CI environments without a database. Would you like deploy-stack to safely disable them by renaming them to .bak?'),
+                    initialValue: true,
+                });
+                if (typeof ciContent === 'symbol') {
+                    cancel('Provisioning cancelled.');
+                    process.exit(0);
+                }
+                disableDefaultCI = ciContent;
+            } else {
+                // Headless: automatically disable conflicting CI
+                disableDefaultCI = true;
             }
-            disableDefaultCI = ciContent;
         }
     }
 
     // 7.5. The Pre-Flight Cost Estimator
     // We explicitly ask for financial consent to eliminate AWS billing anxiety.
-    console.log(''); // Add a blank line for visual pacing
-    const costConsent = await confirm({
-        message: color.yellow(`⚠️  Pre-Flight Check: This AWS architecture will cost ${estimatedCost}. Proceed with provisioning?`),
-        initialValue: true,
-    });
-
-    if (!costConsent || typeof costConsent === 'symbol') {
-        cancel('Deployment cancelled. No AWS resources were provisioned.');
-        process.exit(0);
+    if (!isHeadless) {
+        console.log(''); // Add a blank line for visual pacing
+        const costConsent = await confirm({
+            message: color.yellow(`⚠️  Pre-Flight Check: This AWS architecture will cost ${estimatedCost}. Proceed with provisioning?`),
+            initialValue: true,
+        });
+        if (!costConsent || typeof costConsent === 'symbol') {
+            cancel('Deployment cancelled. No AWS resources were provisioned.');
+            process.exit(0);
+        }
     }
 
     // 8. Safely handle existing files (Backup and auto-prune)
-    await handleExistingFiles(targetDir);
+    await handleExistingFiles(targetDir, isHeadless);
 
     const s = spinner();
     s.start('Provisioning infrastructure...');
@@ -313,36 +351,20 @@ export async function mainStack() {
     const isGitInitialized = fsSync.existsSync(path.join(targetDir, '.git'));
 
     const cdStep = projectName === '.' ? '' : `1. cd ${projectName}\n        `;
-    const deployStepNum = projectName === '.' ? '1' : '2';
-    const gitStepNum = projectName === '.' ? '2' : '3';
+    const applyStep = `${cdStep}npx deploy-stack apply`;
 
     const gitInstructions = isGitInitialized
-        ? `git add .\n       git commit -m "chore: add AWS infrastructure and CI/CD"\n       git push`
-        : `git init\n       git add .\n       git commit -m "chore: add AWS infrastructure and CI/CD"\n       git branch -M ${deployBranch}\n       git remote add origin https://github.com/your-username/your-repo.git\n       git push -u origin ${deployBranch}`;
-
-    outro(`
-    ${color.green('✅ Project provisioned successfully!')}
-
-    ${color.blue('🛡️ DevSecOps Enabled:')}
-       Automated Trivy vulnerability scanning for your Docker container 
-       and Terraform has been added to your CI/CD pipeline. 
-       Check the 'Summary' page of your GitHub Actions runs for reports.
-
-    ${frameworkWarnings}
-    
-    Next steps:
-    ${cdStep}${deployStepNum}. Deploy infrastructure:
-       cd terraform && terraform init && terraform apply
-
-    ${gitStepNum}. Push to GitHub to trigger CI/CD:
-       cd ..
-       ${gitInstructions}
+        ? `git add . && git commit -m "chore: add AWS infrastructure and CI/CD" && git push`
+        : `git init && git add . && git commit -m "chore: add AWS infrastructure and CI/CD" && git branch -M ${deployBranch} && git remote add origin https://github.com/your-username/your-repo.git && git push -u origin ${deployBranch}`;
 
-    ${color.cyan('Once deployed, Terraform will output your new https://*.cloudfront.net URL.')}
+    const outroMessage = `${color.green('✅ Templates generated!')} ${color.blue('🛡️ DevSecOps scanning enabled.')}
+    ${frameworkWarnings ? `\n  ${frameworkWarnings}` : ''}
+    ${color.yellow('Next steps:')}
+    1. ${color.cyan(applyStep)}
+    2. ${color.cyan(gitInstructions)}
+    ${color.magenta('🚀 Need help?')} ${color.underline('https://calendly.com/anton-codes-iac/15min')}`;
 
-    ${color.magenta('🚀 Infrastructure ready! Need help or have feedback? Grab 15 mins with Anton:')}
-    ${color.underline('https://calendly.com/anton-codes-iac/15min')}
-    `);
+    outro(outroMessage);
 
     // 13.Ensure all analytics are sent before the CLI terminates
     await flushTelemetry();

package/src/utils/backup.js

@@ -3,7 +3,7 @@ import path from 'path';
 import { select, isCancel, cancel } from '@clack/prompts';
 import color from 'picocolors';
 
-export async function handleExistingFiles(targetDir) {
+export async function handleExistingFiles(targetDir, isHeadless = false) {
     const tfPath = path.join(targetDir, 'terraform');
     const dockerfilePath = path.join(targetDir, 'Dockerfile');
     const wfDir = path.join(targetDir, '.github', 'workflows');
@@ -22,17 +22,21 @@ export async function handleExistingFiles(targetDir) {
     if (dockerfileExists) foundFiles.push('Dockerfile');
     if (wfExists) foundFiles.push('.github/workflows/deploy.yml');
 
-    const overwriteDecision = await select({
-        message: color.yellow(`⚠️  Conflicting files found (${foundFiles.join(', ')}). To guarantee a secure, 0-CVE deployment, we must use our optimized configurations.`),
-        options: [
-            { value: 'backup', label: 'Backup & Regenerate', hint: 'Move old configs to .bak and generate secure templates' },
-            { value: 'cancel', label: 'Cancel', hint: 'Exit without making changes' }
-        ]
-    });
+    let overwriteDecision = 'backup';
 
-    if (isCancel(overwriteDecision) || overwriteDecision === 'cancel') {
-        cancel('Operation cancelled to protect existing files.');
-        process.exit(0);
+    if (!isHeadless) {
+        overwriteDecision = await select({
+            message: color.yellow(`⚠️  Conflicting files found (${foundFiles.join(', ')}). To guarantee a secure, 0-CVE deployment, we must use our optimized configurations.`),
+            options: [
+                { value: 'backup', label: 'Backup & Regenerate', hint: 'Move old configs to .bak and generate secure templates' },
+                { value: 'cancel', label: 'Cancel', hint: 'Exit without making changes' }
+            ]
+        });
+
+        if (isCancel(overwriteDecision) || overwriteDecision === 'cancel') {
+            cancel('Operation cancelled to protect existing files.');
+            process.exit(0);
+        }
     }
 
     // Execute the safe backup

package/src/utils/generator.js

@@ -152,13 +152,17 @@ Thumbs.db
         const railsCiPath = path.join(targetDir, '.github', 'workflows', 'ci.yml');
         const dependabotPath = path.join(targetDir, '.github', 'dependabot.yml');
 
-        if (fsSync.existsSync(railsCiPath)) {
-            fsSync.renameSync(railsCiPath, `${railsCiPath}.bak`);
-            console.log('  ⚠️  Disabled default Rails ci.yml (renamed to .bak) to prevent database connection crashes in CI.');
-        }
-        if (fsSync.existsSync(dependabotPath)) {
-            fsSync.renameSync(dependabotPath, `${dependabotPath}.bak`);
-            console.log('  ⚠️  Disabled default dependabot.yml (renamed to .bak) to prevent automated PRs from triggering the broken CI suite.');
+        if (config.DISABLE_DEFAULT_CI) {
+            if (fsSync.existsSync(railsCiPath)) {
+                fsSync.renameSync(railsCiPath, `${railsCiPath}.bak`);
+                console.log('  ✅  Safely disabled default Rails ci.yml (renamed to .bak).');
+            }
+            if (fsSync.existsSync(dependabotPath)) {
+                fsSync.renameSync(dependabotPath, `${dependabotPath}.bak`);
+                console.log('  ✅  Safely disabled default dependabot.yml (renamed to .bak).');
+            }
+        } else if (fsSync.existsSync(railsCiPath) || fsSync.existsSync(dependabotPath)) {
+            console.log('  ⚠️  You chose to keep your existing GitHub Actions. Please note that default tests may fail until you configure a database service in your CI runner.');
         }
     }
 }