deploy-stack 0.10.0 → 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

@@ -54,9 +54,9 @@ You retain complete ownership of your infrastructure code without relying on bla
 
 Run the CLI directly in your project root:
 
-\`\`\`bash
+```bash
 npx deploy-stack
-\`\`\`
+```
 
 The interactive wizard will analyze your codebase, detect your framework, estimate your AWS costs, and generate your Terraform and GitHub Actions configurations.
 
@@ -81,13 +81,16 @@ The interactive wizard will analyze your codebase, detect your framework, estima
 * **`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.
 
+* **`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 seamlessly integrates a modular, DevSecOps-hardened architecture into your repository:
 
-\`\`\`text
+```text
 your-project/
 ├── Dockerfile                  # Multi-stage container preset
 ├── .dockerignore               # Prevents secret leaks into container builds
@@ -103,7 +106,7 @@ your-project/
     ├── 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
-\`\`\`
+```
 
 ---
 
@@ -126,9 +129,9 @@ 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
-\`\`\`
+```
 
 ---
 
@@ -148,14 +151,13 @@ npx deploy-stack --no-telemetry
 
 ### 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.
-- [ ] **Ecosystem Integrations:** Publishing official plugins to the Astro Integrations directory and backend framework ecosystems.
+- [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.
 - [ ] **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

@@ -18,7 +18,24 @@ 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());
@@ -32,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.10.0",
+  "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/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';
+
+    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.';
+            },
+        });
+
+        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);
+        const actualProjectName = projectName === '.' ? path.basename(process.cwd()) : projectName;
+        const targetDir = projectName === '.' ? process.cwd() : path.join(process.cwd(), projectName);
 
-    // 2.5 Run the scanner
-    const detectedFramework = detectFramework(targetDir);
-    if (detectedFramework) {
-        log.success(`Auto-detected framework: ${detectedFramework.name}`);
-    }
+        // 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;
+        // 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',
-                });
+        // 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,
+                    });
+                },
             },
-            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);
-            },
-        }
-    );
+            {
+                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...');

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