deploy-stack 0.16.0 → 0.17.0

package/README.md

@@ -49,6 +49,7 @@ You retain complete ownership of your infrastructure code without relying on bla
 * **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.
 * **Ephemeral PR Previews (Opt-In):** Automatically spins up completely isolated AWS Fargate environments for every Pull Request and posts the live preview URL to GitHub, accelerating team code reviews.
+* **🤖 IDE AI Integration:** Automatically generates contextual rules for Cursor, Windsurf, Copilot, and Claude to prevent Terraform hallucinations.
 
 ---
 
@@ -97,6 +98,9 @@ The interactive wizard will analyze your codebase, detect your framework, estima
 * **`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-2`, and `--size=micro`.
 
+* **`npx deploy-stack sync-ai`**
+  Selectively generates architecture rules for AI coding assistants (Cursor, Copilot, Windsurf, Claude). Automatically extracts your AWS Region and Container Port to prevent Terraform hallucinations.
+
 ---
 
 ## 📁 Generated File Structure
@@ -133,14 +137,16 @@ your-project/
 
 ---
 
-## 🤖 AI Agent Integration
+## 🤖 AI Context Management (Cursor, Copilot, Windsurf, Claude)
+
+AI coding assistants are incredible, but they often hallucinate custom Terraform or raw AWS CLI commands that can break your infrastructure state. `deploy-stack` natively intercepts and guides AI agents directly in your IDE by providing strict deployment rules and project-specific context (like your exact AWS Region and Container Port).
 
-Are you using Cursor, Windsurf, or GitHub Copilot? AI coding assistants often hallucinate complex, broken infrastructure code when asked to "deploy to AWS." 
+**How it works:**
+* **Quickstart Flow:** The CLI silently auto-detects if you are using AI tools in your repository and safely injects context.
+* **Advanced Flow:** You are explicitly prompted to choose which AI assistants your team uses.
+* **Standalone Command:** You can run `npx deploy-stack sync-ai` at any time to selectively generate these rules later.
 
-To teach your AI to natively use this CLI instead, copy our [Agent Ruleset](./agent-rules.md) into your repository's specific instruction file:
-* **Cursor:** Save as `.cursorrules` in your project root.
-* **Windsurf:** Save as `.windsurfrules` in your project root.
-* **GitHub Copilot:** Save as `.github/copilot-instructions.md`.
+**Safe & Non-Destructive:** We use isolated rule files (like `.cursor/rules/deploy-stack.mdc`) or strictly delimited blocks (``) to ensure your team's existing agent instructions, coding standards, and project prompts are **never overwritten**.
 
 ---
 
@@ -158,7 +164,7 @@ npx deploy-stack --no-telemetry
 
 ### Current Focus (Phase 7: Team Workflows & Ecosystem Integrations)
 - [x] **Ephemeral PR Previews:** Generate GitHub Actions workflows that spin up temporary ECS Fargate tasks and post live preview URLs directly in pull request comments to streamline team code reviews.
-- [ ] **AI Context Synchronization:** Implement `deploy-stack sync-ai` to automatically generate `.cursorrules` and AI context files, ensuring coding assistants generate accurate deployment commands tailored to the project.
+- [x] **AI Context Synchronization:** Implement `deploy-stack sync-ai` to automatically generate `.cursorrules` and AI context files, ensuring coding assistants generate accurate deployment commands tailored to the project.
 - [ ] **Native Ecosystem Integrations:** Publish seamless, push-button plugins across major frameworks. Targets include a `svelte-adapter-deploy-stack`, an official `create-next-app` AWS template, a `vite-plugin-deploy-stack`, a NestJS schematic, and a Django Cookiecutter template.
 - [ ] **Automated Troubleshooting:** Build `deploy-stack diagnose` (alias: `wtf`) to automatically analyze and troubleshoot common day-2 AWS operational issues (e.g., Fargate OOM kills, ALB 502s) directly from the terminal.
 

package/bin/cli.js

@@ -6,6 +6,7 @@ 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';
+import { syncAi } from '../src/commands/sync-ai.js';
 
 // 1. Extract the telemetry flag and set the environment variable
 const rawArgs = process.argv.slice(2);
@@ -40,15 +41,17 @@ const headlessOptions = isHeadless ? {
 if (args[0] === 'secrets' && args[1] === 'push') {
     const envFile = args[2] || '.env';
     const projectName = path.basename(process.cwd());
-    pushSecrets(envFile, projectName).catch(console.error);
+    pushSecrets(envFile, projectName).catch(e => { console.error(e); process.exit(1); });
 } else if (args[0] === 'apply') {
-    applyStack({ isDryRun }).catch(console.error);
+    applyStack({ isDryRun }).catch(e => { console.error(e); process.exit(1); });
 } else if (args[0] === 'doctor') {
-    runDoctor().catch(console.error);
+    runDoctor().catch(e => { console.error(e); process.exit(1); });
 } else if (args[0] === 'destroy') {
-    destroyStack().catch(console.error);
+    destroyStack().catch(e => { console.error(e); process.exit(1); });
 } else if (args[0] === 'eject') {
-    ejectStack().catch(console.error);
+    ejectStack().catch(e => { console.error(e); process.exit(1); });
+} else if (args[0] === 'sync-ai') {
+    syncAi().catch(e => { console.error(e); process.exit(1); });
 } else {
     mainStack({ isHeadless, headlessOptions }).catch(e => { console.error(e); process.exit(1); });
 }

package/docs/ROADMAP.md

@@ -25,6 +25,6 @@
 ### Phase 7: Team Workflows & Ecosystem Integrations (Current)
 *Focus: Enhance collaborative development and expand native support across major framework ecosystems.*
 - [x] **Ephemeral PR Previews:** Generate GitHub Actions workflows that spin up temporary ECS Fargate tasks and post live URLs directly in PR comments to streamline team code reviews.
-- [ ] **AI Context Synchronization:** Implement `deploy-stack sync-ai` to automatically generate `.cursorrules` and AI context files, ensuring IDE assistants understand the infrastructure.
+- [x] **AI Context Synchronization:** Implement `deploy-stack sync-ai` to automatically generate `.cursorrules` and AI context files, ensuring IDE assistants understand the infrastructure.
 - [ ] **Native Ecosystem Integrations:** Publish push-button plugins across major frameworks (e.g., `svelte-adapter-deploy-stack`, `create-next-app` AWS template, `vite-plugin-deploy-stack`, NestJS deployment schematic, Django Cookiecutter).
 - [ ] **Automated Troubleshooting:** Build `deploy-stack diagnose` to auto-diagnose common day-2 AWS failures (e.g., Fargate OOM kills, ALB 502s) to establish immediate technical credibility and simplify maintenance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deploy-stack",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"

package/src/commands/init.js

@@ -20,7 +20,8 @@ import { handleExistingFiles } from '../utils/backup.js';
 import { estimateMonthlyCost } from '../utils/visualizer.js';
 import { getTargetDirectory, getProjectConfig } from '../utils/prompts.js';
 import { resolveDjangoWsgi, handleRailsCI } from '../utils/frameworks.js';
-import { hasDockerCompose, parseDockerCompose } from '../utils/dockerCompose.js';
+import { parseDockerCompose } from '../utils/dockerCompose.js';
+import { getBaseRules, getCursorRules, injectManagedBlock } from '../utils/ai-rules.js';
 
 const pkg = JSON.parse(fsSync.readFileSync(new URL('../../package.json', import.meta.url)));
 const CLI_VERSION = pkg.version;
@@ -171,10 +172,53 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
         is_vercel_migration: !!vercelRules,
         is_docker_compose: !!dockerCompose,
         has_pr_previews: config.enablePrPreviews,
+        ai_assistants_configured: config.aiAssistants || [],
     });
 
     s.stop('Infrastructure provisioned successfully!');
 
+    // 8.5 Configure AI Context
+    s.start('Configuring AI workspace rules...');
+    const aiContext = { region: config.region, port: config.port };
+
+    if (config.setupType === 'advanced') {
+        // --- ADVANCED MODE: Explicitly respect user choices ---
+        if (config.aiAssistants.includes('cursor')) {
+            const cursorDir = path.join(dirConfig.targetDir, '.cursor', 'rules');
+            if (!fsSync.existsSync(cursorDir)) fsSync.mkdirSync(cursorDir, { recursive: true });
+            fsSync.writeFileSync(path.join(cursorDir, 'deploy-stack.mdc'), getCursorRules(aiContext));
+        }
+        if (config.aiAssistants.includes('windsurf')) {
+            injectManagedBlock(path.join(dirConfig.targetDir, '.windsurfrules'), getBaseRules(aiContext), false);
+        }
+        if (config.aiAssistants.includes('claude')) {
+            injectManagedBlock(path.join(dirConfig.targetDir, 'CLAUDE.md'), getBaseRules(aiContext), true);
+        }
+        if (config.aiAssistants.includes('copilot')) {
+            const copilotPath = path.join(dirConfig.targetDir, '.github', 'copilot-instructions.md');
+            if (!fsSync.existsSync(path.dirname(copilotPath))) fsSync.mkdirSync(path.dirname(copilotPath), { recursive: true });
+            injectManagedBlock(copilotPath, getBaseRules(aiContext), true);
+        }
+    } else {
+        // --- QUICKSTART MODE: Silent Auto-Detection ---
+        if (fsSync.existsSync(path.join(dirConfig.targetDir, '.cursor'))) {
+            const cursorDir = path.join(dirConfig.targetDir, '.cursor', 'rules');
+            if (!fsSync.existsSync(cursorDir)) fsSync.mkdirSync(cursorDir, { recursive: true });
+            fsSync.writeFileSync(path.join(cursorDir, 'deploy-stack.mdc'), getCursorRules(aiContext));
+        }
+        if (fsSync.existsSync(path.join(dirConfig.targetDir, '.windsurf')) || fsSync.existsSync(path.join(dirConfig.targetDir, '.windsurfrules'))) {
+            injectManagedBlock(path.join(dirConfig.targetDir, '.windsurfrules'), getBaseRules(aiContext), false);
+        }
+        if (fsSync.existsSync(path.join(dirConfig.targetDir, 'CLAUDE.md'))) {
+            injectManagedBlock(path.join(dirConfig.targetDir, 'CLAUDE.md'), getBaseRules(aiContext), true);
+        }
+        const copilotPath = path.join(dirConfig.targetDir, '.github', 'copilot-instructions.md');
+        if (fsSync.existsSync(copilotPath)) {
+            injectManagedBlock(copilotPath, getBaseRules(aiContext), true);
+        }
+    }
+    s.stop('AI rules configured successfully!');
+
     // 9. Output
     let frameworkWarnings = '';
     if (!(config.framework === 'static' && detectedFramework?.buildDir)) {

package/src/commands/sync-ai.js

@@ -0,0 +1,83 @@
+import fsSync from 'fs';
+import path from 'path';
+import { intro, outro, spinner, log } from '@clack/prompts';
+import color from 'picocolors';
+import { getAiAssistants } from '../utils/prompts.js';
+import { getBaseRules, getCursorRules, injectManagedBlock } from '../utils/ai-rules.js';
+import { trackEvent, flushTelemetry } from '../core/telemetry.js';
+
+function getProjectContext(cwd) {
+    const context = { region: '', port: '' };
+    const mainTfPath = path.join(cwd, 'terraform', 'main.tf');
+
+    if (fsSync.existsSync(mainTfPath)) {
+        const tfContent = fsSync.readFileSync(mainTfPath, 'utf8');
+
+        // Extract Region
+        const regionMatch = tfContent.match(/region\s*=\s*"([^"]+)"/);
+        if (regionMatch) context.region = regionMatch[1];
+
+        // Extract Port
+        const portMatch = tfContent.match(/containerPort\s*=\s*(\d+)/);
+        if (portMatch) context.port = portMatch[1];
+    }
+
+    return context;
+}
+
+export async function syncAi() {
+    intro(color.bgCyan(color.black(' deploy-stack sync-ai 🤖 ')));
+
+    const assistants = await getAiAssistants();
+
+    if (!assistants || assistants.length === 0) {
+        log.warn('No AI assistants selected. Skipping synchronization.');
+        process.exit(0);
+    }
+
+    const s = spinner();
+    s.start('Writing AI context rules...');
+    const cwd = process.cwd();
+
+    const context = getProjectContext(cwd);
+
+    try {
+        if (assistants.includes('cursor')) {
+            const cursorDir = path.join(cwd, '.cursor', 'rules');
+            if (!fsSync.existsSync(cursorDir)) fsSync.mkdirSync(cursorDir, { recursive: true });
+            fsSync.writeFileSync(path.join(cursorDir, 'deploy-stack.mdc'), getCursorRules(context));
+        }
+
+        if (assistants.includes('copilot')) {
+            const githubDir = path.join(cwd, '.github');
+            if (!fsSync.existsSync(githubDir)) fsSync.mkdirSync(githubDir, { recursive: true });
+            injectManagedBlock(path.join(githubDir, 'copilot-instructions.md'), getBaseRules(context), true);
+        }
+
+        if (assistants.includes('windsurf')) {
+            injectManagedBlock(path.join(cwd, '.windsurfrules'), getBaseRules(context), false);
+        }
+
+        if (assistants.includes('claude')) {
+            injectManagedBlock(path.join(cwd, 'CLAUDE.md'), getBaseRules(context), true);
+        }
+
+        trackEvent('sync_ai_executed', {
+            assistants_selected: assistants,
+            has_cursor: assistants.includes('cursor'),
+            has_copilot: assistants.includes('copilot'),
+            has_windsurf: assistants.includes('windsurf'),
+            has_claude: assistants.includes('claude')
+        });
+        await flushTelemetry();
+
+        s.stop('AI context synchronized successfully!');
+
+        outro(`${color.green('✅ AI Assistant Rules generated!')} 
+Your AI tools now know exactly how to deploy your app without hallucinating Terraform.`);
+    } catch (error) {
+        s.stop('❌ Failed to write AI context files.');
+        console.error(color.red(error.message));
+        process.exit(1);
+    }
+}

package/src/utils/ai-rules.js

@@ -0,0 +1,54 @@
+import fsSync from 'fs';
+
+export const getBaseRules = (context = {}) => `
+# deploy-stack Infrastructure Context
+
+This project's AWS infrastructure is managed strictly by the \`deploy-stack\` CLI. 
+**DO NOT** generate custom Terraform, AWS CloudFormation, or raw AWS CLI commands to deploy this application or modify the architecture.
+
+### Standard Operating Procedures
+
+1. **Applying Changes:** If the user asks to deploy, provision, or update the infrastructure, instruct them to run:
+   \`npx deploy-stack apply\`
+
+2. **Environment Variables:** If the user adds a new environment variable and needs it available in production, instruct them to run:
+   \`npx deploy-stack secrets push <path-to-env-file>\`
+
+3. **Teardown:** If the user wants to destroy the AWS environment, instruct them to run:
+   \`npx deploy-stack destroy\`
+
+4. **Architecture Details:** 
+   - **AWS Region:** \`${context.region || 'Unknown (Check terraform/main.tf)'}\`
+   - **Container Port:** \`${context.port || 'Unknown'}\`
+   - The infrastructure is an AWS ECS Fargate cluster.
+   - It uses an Application Load Balancer (ALB).
+   - CI/CD is handled securely via GitHub Actions OIDC (no long-lived IAM keys).
+   - Preview environments (Ephemeral PRs) are managed via Terraform Workspaces.
+`;
+
+export const getCursorRules = (context = {}) => `---
+description: "Rules for deploying the application and managing AWS infrastructure"
+globs: ["terraform/*.tf", ".github/workflows/*.yml", "Dockerfile"]
+---${getBaseRules(context)}`;
+
+export function injectManagedBlock(filePath, content, isMarkdown = true) {
+    const beginMarker = isMarkdown ? '<!-- BEGIN DEPLOY-STACK CONTEXT -->' : '# BEGIN DEPLOY-STACK CONTEXT';
+    const endMarker = isMarkdown ? '<!-- END DEPLOY-STACK CONTEXT -->' : '# END DEPLOY-STACK CONTEXT';
+    const block = `\n${beginMarker}\n${content.trim()}\n${endMarker}\n`;
+
+    if (fsSync.existsSync(filePath)) {
+        let fileContent = fsSync.readFileSync(filePath, 'utf8');
+        // Look for the existing block to replace it
+        const regex = new RegExp(`\\n?${beginMarker}[\\s\\S]*?${endMarker}\\n?`);
+
+        if (regex.test(fileContent)) {
+            fileContent = fileContent.replace(regex, block); // Replace our old rules
+        } else {
+            fileContent = fileContent.trim() + '\n' + block; // Append to bottom
+        }
+        fsSync.writeFileSync(filePath, fileContent);
+    } else {
+        // File doesn't exist, create it cleanly
+        fsSync.writeFileSync(filePath, block.trim() + '\n');
+    }
+}

package/src/utils/dockerCompose.js

@@ -2,13 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { load } from 'js-yaml';
 
-// 1. Check if a Docker Compose file exists in the target directory.
-export function hasDockerCompose(targetDir) {
-    return fs.existsSync(path.join(targetDir, 'docker-compose.yml')) ||
-        fs.existsSync(path.join(targetDir, 'docker-compose.yaml'));
-}
-
-// 2. Parse docker-compose.yml and normalize it into an array of services.
+// Parse docker-compose.yml and normalize it into an array of services.
 export function parseDockerCompose(targetDir) {
     let composePath = path.join(targetDir, 'docker-compose.yml');
     if (!fs.existsSync(composePath)) {

package/src/utils/generator.js

@@ -14,6 +14,8 @@ export async function generateTemplates(targetDir, config) {
 
     // 2. Define paths
     const templatesDir = path.join(__dirname, '../../templates');
+    const readmeExists = fsSync.existsSync(path.join(targetDir, 'README.md'));
+    const readmeDest = readmeExists ? 'DEPLOYMENT.md' : 'README.md';
     const filesToProcess = [
         { src: 'terraform/main.tf', dest: 'terraform/main.tf' },
         { src: 'terraform/network.tf', dest: 'terraform/network.tf' },
@@ -23,9 +25,15 @@ export async function generateTemplates(targetDir, config) {
         { 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' }
+        { src: 'README.md', dest: readmeDest }
     ];
 
+    // 2.1 Check if README.md exists (append DEPLOYMENT.md note if yes, generate new if no)
+    if (readmeExists) {
+        const readmeNotice = `\n## 🚀 Deployment\nAWS Fargate infrastructure is managed via [deploy-stack](./DEPLOYMENT.md).\n`;
+        fsSync.appendFileSync(path.join(targetDir, 'README.md'), readmeNotice);
+    }
+
     // 2.1 Add Ephemeral PR workflows only if opted in
     if (config.ENABLE_PR_PREVIEWS) {
         filesToProcess.push({ src: 'github/preview.yml', dest: '.github/workflows/preview.yml' });

package/src/utils/prompts.js

@@ -1,5 +1,5 @@
 import path from 'path';
-import { text, select, confirm, group, cancel, log } from '@clack/prompts';
+import { text, select, multiselect, confirm, group, cancel } from '@clack/prompts';
 import color from 'picocolors';
 import { execSync } from 'child_process';
 
@@ -101,6 +101,7 @@ export async function getProjectConfig(isHeadless, headlessOptions, targetDir, d
     }
 
     let enablePrPreviews = false;
+    let aiAssistants = [];
     if (setupType === 'advanced') {
         const prChoice = await confirm({
             message: `Enable Ephemeral PR Previews? (Spins up isolated, temporary AWS environments for PRs)\n  ${color.gray('📖 Learn more: https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/guides/ephemeral-pr-previews.md')}`,
@@ -108,6 +109,8 @@ export async function getProjectConfig(isHeadless, headlessOptions, targetDir, d
         });
         if (typeof prChoice === 'symbol') process.exit(0);
         enablePrPreviews = prChoice;
+
+        aiAssistants = await getAiAssistants();
     }
 
     const project = await group({
@@ -163,6 +166,27 @@ export async function getProjectConfig(isHeadless, headlessOptions, targetDir, d
         branch: project.branch || currentGitBranch,
         needsDatabase,
         enablePrPreviews,
+        aiAssistants,
         setupType
     };
+}
+
+export async function getAiAssistants() {
+    const selected = await multiselect({
+        message: 'Which AI coding assistants does your team use?',
+        options: [
+            { value: 'cursor', label: 'Cursor', hint: 'Generates .cursor/rules/deploy-stack.mdc' },
+            { value: 'copilot', label: 'GitHub Copilot', hint: 'Generates .github/copilot-instructions.md' },
+            { value: 'windsurf', label: 'Windsurf', hint: 'Generates .windsurfrules' },
+            { value: 'claude', label: 'Claude Code / CLI Agents', hint: 'Generates CLAUDE.md' }
+        ],
+        required: false,
+    });
+
+    if (typeof selected === 'symbol') {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+
+    return selected;
 }