deploy-stack 0.17.5 → 0.17.7

package/README.md

@@ -132,6 +132,7 @@ your-project/
 * **[Next.js Fullstack App](https://github.com/anton-codes-iac/deploy-stack-nextjs-example):** A complete Next.js deployment showcasing the generated Terraform, CloudFront setup, and automated OIDC workflow.
 * **[Docker Compose to AWS Migration](https://github.com/anton-codes-iac/deploy-stack-docker-compose-example):** Demonstrates automatic translation of local `docker-compose.yml` sidecars (like Redis) into a multi-container AWS ECS Task Definition communicating over `localhost`.
 * **[Heroku to AWS Migration (Django)](https://github.com/anton-codes-iac/deploy-stack-heroku-django-example):** A classic Heroku-style monolith migrated via the Procfile Importer.
+* **[Zero-Secret AWS Secrets Manager Injection](https://github.com/anton-codes-iac/deploy-stack-secrets-example):** A production-grade Node.js architecture demonstrating zero-plaintext secret injection. Encrypts local `.env` variables directly into AWS and maps them into ECS memory at container boot, verified against GitHub's API.
 
 👉 **[View all 14+ reference implementations in our Examples Gallery](./docs/examples.md)**
 
@@ -165,7 +166,13 @@ 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.
 - [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.
+- [ ] **Native Ecosystem Integrations & Scaffolding:** Publish seamless, push-button plugins and templates across major framework package registries:
+  - [x] `vite-plugin-deploy-stack` (Vite / React / Vue SPA ecosystem)
+  - [x] `svelte-adapter-deploy-stack` (SvelteKit adapter integration)
+  - [x] `cookiecutter-django-deploy-stack` (Listed on Django Packages)
+  - [ ] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
+  - [ ] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
+  - [ ] `rails-template-deploy-stack` (Zero-click Ruby on Rails application 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.
 
 👉 **[See the full project history and future plans in ROADMAP.md](./ROADMAP.md)**

package/bin/cli.js

@@ -10,20 +10,29 @@ import { syncAi } from '../src/commands/sync-ai.js';
 
 // 1. Extract the telemetry flag and set the environment variable
 const rawArgs = process.argv.slice(2);
-const hasNoTelemetry = rawArgs.includes('--no-telemetry');
+const hasNoTelemetry = rawArgs.some(arg => arg === '--no-telemetry' || arg.startsWith('--no-telemetry='));
 
 if (hasNoTelemetry) {
     process.env.DO_NOT_TRACK = '1';
 }
 
 // 2. Filter out the telemetry flag from the args so the subcommands don't see it
-const args = rawArgs.filter((arg) => arg !== '--no-telemetry');
+const args = rawArgs.filter((arg) => arg !== '--no-telemetry' && !arg.startsWith('--no-telemetry='));
 
-// 3. Parse headless flags
+// 3. Isolate positional commands from flags
+// This ensures flags (e.g., --dry-run) don't accidentally become file paths
+const positionalArgs = args.filter(arg => !arg.startsWith('--'));
+
+// Safely capture the base command for telemetry (ignoring file paths)
+const baseCommand = positionalArgs.length > 0 ? positionalArgs.slice(0, 2).join(' ') : 'init';
+process.env.CLI_COMMAND = baseCommand;
+
+// 4. Parse headless flags
 const isHeadless = args.includes('--headless');
 const isDryRun = args.includes('--dry-run');
 const getFlag = (flagName) => {
-    const match = args.find(a => a.startsWith(`--${flagName}=`));
+    const match = args.find(a => a === `--${flagName}` || a.startsWith(`--${flagName}=`));
+    if (match === `--${flagName}`) return true;
     return match ? match.split('=')[1] : undefined;
 };
 const headlessOptions = isHeadless ? {
@@ -34,10 +43,12 @@ const headlessOptions = isHeadless ? {
     size: getFlag('size'),
     healthCheckPath: getFlag('healthCheckPath'),
     desiredCount: getFlag('desiredCount'),
-    branch: getFlag('branch')
+    branch: getFlag('branch'),
+    needsDatabase: getFlag('needsDatabase'),
+    enablePrPreviews: getFlag('enablePrPreviews')
 } : {};
 
-// 4. Handle commands
+// 5. Handle commands
 if (args[0] === 'secrets' && args[1] === 'push') {
     const envFile = args[2] || '.env';
     const projectName = path.basename(process.cwd());

package/docs/ROADMAP.md

@@ -24,7 +24,13 @@
 
 ### 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.
-- [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.
+- [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.
+- [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.
+  - [x] `vite-plugin-deploy-stack` (Live on NPM)
+  - [x] `svelte-adapter-deploy-stack` (SvelteKit adapter integration)
+  - [x] `cookiecutter-django-deploy-stack` (Listed on Django Packages)
+  - [ ] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
+  - [ ] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
+  - [ ] `rails-template-deploy-stack` (Zero-click Ruby on Rails application 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/docs/examples.md

@@ -7,6 +7,9 @@ These repositories demonstrate how `deploy-stack` handles various frameworks and
 * **[Vercel to AWS Migration (Next.js)](https://github.com/anton-codes-iac/deploy-stack-vercel-nextjs-example):** Demonstrates automatic translation of Vercel edge routing (`vercel.json`) to native AWS Application Load Balancer rules.
 * **[Docker Compose to AWS Migration](https://github.com/anton-codes-iac/deploy-stack-docker-compose-example):** Demonstrates automatic translation of local `docker-compose.yml` sidecars (like Redis) into a multi-container AWS ECS Task Definition communicating over `localhost`.
 
+### DevSecOps & Security Architectures
+* **[Zero-Secret AWS Secrets Manager Injection](https://github.com/anton-codes-iac/deploy-stack-secrets-example):** A production-grade Node.js architecture demonstrating zero-plaintext secret injection. It pushes local `.env` variables directly to AWS and maps them into ECS memory at runtime, exposing a live endpoint querying GitHub's API.
+
 ### Frontend & Fullstack Frameworks
 * **[Next.js Fullstack App](https://github.com/anton-codes-iac/deploy-stack-nextjs-example):** A complete Next.js deployment showcasing the generated Terraform, CloudFront setup, and automated OIDC workflow.
 * **[Vite / React SPA](https://github.com/anton-codes-iac/deploy-stack-vite-example):** Demonstrates SPA routing and `dist/` auto-detection.
@@ -20,4 +23,16 @@ These repositories demonstrate how `deploy-stack` handles various frameworks and
 * **[Python FastAPI](https://github.com/anton-codes-iac/deploy-stack-fastapi-example):** A Python API demonstrating unprivileged port mapping.
 * **[Ruby on Rails](https://github.com/anton-codes-iac/deploy-stack-rails-example):** A production Rails 7+ setup featuring an auto-provisioned PostgreSQL database and secure `.auto.tfvars` Master Key injection.
 * **[Django / Python](https://github.com/anton-codes-iac/deploy-stack-django-example):** A secure Gunicorn/WSGI implementation with PostgreSQL and unprivileged container adapters.
-* **[Go / Fiber](https://github.com/anton-codes-iac/deploy-stack-go-example):** A distroless, compiled Go binary deployment demonstrating ultra-low memory footprints and instant boot times.
+* **[Go / Fiber](https://github.com/anton-codes-iac/deploy-stack-go-example):** A distroless, compiled Go binary deployment demonstrating ultra-low memory footprints and instant boot times.
+
+---
+
+## 🧩 Ecosystem Plugins & Starters
+
+In addition to standalone reference repositories, `deploy-stack` provides native integrations that hook directly into framework build pipelines and community template engines:
+
+* **[astro-deploy-stack](https://www.npmjs.com/package/astro-deploy-stack):** Push-button deployment plugin for Astro sites.
+* **[nuxt-deploy-stack](https://www.npmjs.com/package/nuxt-deploy-stack):** Nitro-optimized deployment integration for Nuxt 3 applications.
+* **[vite-plugin-deploy-stack](https://www.npmjs.com/package/vite-plugin-deploy-stack):** Zero-config Vite build plugin for single-page applications.
+* **[svelte-adapter-deploy-stack](https://www.npmjs.com/package/svelte-adapter-deploy-stack):** Native SvelteKit adapter producing optimized Fargate container builds.
+* **[cookiecutter-django-deploy-stack](https://github.com/anton-codes-iac/cookiecutter-django-deploy-stack):** Community Django starter listed on [Django Packages](https://djangopackages.org/packages/p/cookiecutter-django-deploy-stack/) with built-in Fargate and managed RDS scaffolding.

package/docs/guides/headless.md

@@ -1,6 +1,6 @@
 # Headless Mode & Automation Guide
 
-The `deploy-stack` CLI is designed to be fully automatable for CI/CD pipelines, custom scripts, and framework plugins (like `vite-plugin-deploy-stack`). 
+The `deploy-stack` CLI is designed to be fully automatable for CI/CD pipelines, custom scripts, Cookiecutters, and framework plugins (like `vite-plugin-deploy-stack`). 
 
 By passing the `--headless` flag, you bypass all interactive terminal prompts.
 
@@ -24,10 +24,13 @@ You can append any of these flags to customize the generated architecture. These
 | `--desiredCount=<number>` | Number of container replicas to run (`1` or `2`). | `1` |
 | `--branch=<name>` | The primary Git deployment branch for CI/CD. | `main` |
 | `--dir=<path>` | The directory to generate files into (use `.` for current).| `.` |
+| `--needsDatabase` | Provisions a managed AWS RDS PostgreSQL database alongside Fargate. | `false` |
 | `--enablePrPreviews` | Generates workflows for Ephemeral PR Previews. | `false` |
 | `--yes` | Automatically bypasses confirmation prompts during apply/destroy. | `false` |
 | `--no-telemetry` | Disables anonymous usage analytics. | `false` |
 
+*(Note: Boolean flags like `--needsDatabase` and `--enablePrPreviews` can be passed alone or as `--flag=true`).*
+
 ## Example Usage
 
 **Standard Static Site Automation (e.g., Vite/React):**
@@ -40,7 +43,7 @@ npx deploy-stack --headless --framework=static --region=eu-west-1 --size=micro
 npx deploy-stack --headless --framework=nextjs --size=small --desiredCount=2 --yes
 ```
 
-**Node.js Backend with PR Previews:**
+**Django Setup with Managed RDS Database:**
 ```bash
-npx deploy-stack --headless --framework=node --port=4000 --enablePrPreviews
+npx deploy-stack --headless --framework=django --needsDatabase
 ```

package/docs/guides/secrets-management.md

@@ -2,23 +2,49 @@
 
 Managing `.env` files across a team and syncing them to the cloud is a notorious pain point. `deploy-stack` solves this by natively integrating with **AWS Secrets Manager**, ensuring zero plaintext secrets ever touch your GitHub repository or CI/CD pipelines.
 
-## Pushing Secrets to AWS
+## The Secrets Lifecycle
 
-Instead of manually clicking through the AWS Console, use the built-in secrets command:
+To maintain zero-secret Git repositories and safe infrastructure provisioning, secrets follow a strict 4-step lifecycle:
+
+```text
+1. Scaffold        ───▶  2. Provision Vault   ───▶  3. Push Secrets     ───▶  4. Deploy to App
+(deploy-stack)           (deploy-stack apply)       (secrets push .env)       (git push)
+Generates Terraform       Creates empty vault        Uploads encrypted keys    ECS container boots
+& secret_keys.json        in AWS Secrets Mgr         & updates secret_keys     with injected env
+```
+
+---
+
+### Step 1: Provision the Vault (Day 1)
+Your Secrets Manager vault is declared in `terraform/secrets.tf`. Provision the base infrastructure first:
+
+```bash
+npx deploy-stack apply
+```
+*This creates an empty, secure secret vault named `<project-name>-secrets` in your AWS account.*
+
+### Step 2: Push Secrets to AWS
+Once the vault exists, push your local `.env` values directly to AWS:
 
 ```bash
-npx deploy-stack secrets push .env.production
+npx deploy-stack secrets push .env
 ```
 
-### What happens under the hood?
-1. The CLI reads your local `.env.production` file.
+**What happens under the hood?**
+1. The CLI reads your local `.env` file.
 2. It encrypts the key-value pairs and pushes them securely into AWS Secrets Manager under your project's namespace (e.g., `my-project-secrets`).
 3. It generates a local `terraform/secret_keys.json` file containing *only the names* of your keys (e.g., `["API_KEY", "STRIPE_SECRET"]`), **not the values**.
 
-## How Secrets Reach Your App
+> 💡 **Tip:** The `secrets push` command takes the file path as the first argument. If you need to use other flags, ensure they are appended at the end of the command:
+> `npx deploy-stack secrets push .env --any-other-flags`
 
-When you commit `terraform/secret_keys.json` and push to GitHub, your CI/CD pipeline runs Terraform. 
+### Step 3: Map Secrets into the Container
+Commit the updated `terraform/secret_keys.json` and push to GitHub:
 
-Terraform reads the JSON array of key names and dynamically maps them to your ECS Task Definition. When your AWS Fargate container boots up, it automatically injects those secrets directly into your application's environment as standard environment variables (e.g., `process.env.STRIPE_SECRET` or `os.getenv("API_KEY")`).
+```bash
+git add terraform/secret_keys.json
+git commit -m "chore: map new secrets to ECS"
+git push origin main
+```
 
-*Note: Because Terraform maps the secrets at runtime, updating a secret value in AWS and running an empty GitHub deployment will instantly cycle your containers with the new keys!*
+Terraform reads `secret_keys.json` during the GitHub Actions deployment and maps each key directly into your ECS Task Definition. When your Fargate container boots up, AWS injects the secret values into `process.env` (Node) or `os.environ` (Python) in memory.

package/package.json

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

package/src/commands/init.js

@@ -117,7 +117,7 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
     } catch (error) {
         s.stop('❌ Failed to provision remote state or authenticate with AWS.');
         console.error(color.red(`AWS Error: ${error.message}`));
-        trackEvent('cli-error', { step: 'aws_provisioning', error_code: error.name || 'UNKNOWN' });
+        trackEvent('cli-error', { step: 'aws_provisioning', error_code: error.name || 'UNKNOWN', error_message: error.message });
         await flushTelemetry();
         process.exit(1);
     }

package/src/commands/secrets.js

@@ -13,7 +13,16 @@ export async function pushSecrets(envFilePath, projectName) {
     try {
         // 1. Read and parse the local .env file
         const envPath = path.resolve(process.cwd(), envFilePath);
-        const envContent = await fs.readFile(envPath, 'utf-8');
+        let envContent;
+        try {
+            envContent = await fs.readFile(envPath, 'utf-8');
+        } catch (fsError) {
+            if (fsError.code === 'ENOENT') {
+                throw new Error(`File not found: ${envFilePath}. Please ensure the file exists before pushing.`);
+            }
+            throw fsError; // Re-throw if it's a permissions issue
+        }
+
         const parsedSecrets = dotenv.parse(envContent);
 
         if (Object.keys(parsedSecrets).length === 0) {
@@ -21,12 +30,23 @@ export async function pushSecrets(envFilePath, projectName) {
             return;
         }
 
-        // 2. Initialize the AWS Client
-        // It automatically uses the AWS credentials the user set in their terminal
-        const client = new SecretsManagerClient({});
+        // 2. Dynamically resolve the exact region from Terraform
+        let targetRegion = process.env.AWS_REGION;
+        try {
+            const mainTfPath = path.join(process.cwd(), 'terraform', 'main.tf');
+            const mainTfContent = await fs.readFile(mainTfPath, 'utf-8');
+            const regionMatch = mainTfContent.match(/region\s*=\s*"([^"]+)"/);
+            if (regionMatch) {
+                targetRegion = regionMatch[1];
+            }
+        } catch (e) {
+            // Silently fallback to AWS profile defaults if file read fails
+        }
 
-        // 3. Update the secret string in AWS
-        // The SecretId matches the name we generated in secrets.tf
+        // 3. Initialize the AWS Client locked to the correct region
+        const client = new SecretsManagerClient(targetRegion ? { region: targetRegion } : {});
+
+        // 4. Update the secret string in AWS
         const command = new UpdateSecretCommand({
             SecretId: `${projectName}-secrets`,
             SecretString: JSON.stringify(parsedSecrets),
@@ -39,7 +59,7 @@ export async function pushSecrets(envFilePath, projectName) {
 
         await fs.writeFile(keysFilePath, JSON.stringify(keys, null, 2));
 
-        s.stop(`✅ Successfully pushed ${Object.keys(parsedSecrets).length} secrets to AWS!`);
+        s.stop(`✅ Successfully pushed ${Object.keys(parsedSecrets).length} secrets to AWS (${targetRegion || 'default region'})!`);
         console.log(color.cyan(`\nUpdated ${keysFilePath}`));
         console.log(color.green('Commit this file and push to GitHub to trigger a deployment with your new variables.'));
         console.log(color.blue(`\n📘 Learn how secrets reach your app: ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/guides/secrets-management.md')}`));
@@ -52,13 +72,22 @@ export async function pushSecrets(envFilePath, projectName) {
         await flushTelemetry();
 
     } catch (error) {
-        s.stop(`❌ Failed to push secrets: ${error.message}`);
+        if (error.name === 'ResourceNotFoundException') {
+            s.stop(color.red(`❌ Secrets Vault "${projectName}-secrets" does not exist in AWS yet.`));
+            console.log(color.yellow('\n💡 Next Step:'));
+            console.log(`Run ${color.cyan('npx --yes deploy-stack apply')} first to provision the infrastructure and Secrets Manager vault.`);
+            console.log(`Once applied, run ${color.cyan(`npx deploy-stack secrets push ${envFilePath}`)} to upload your environment variables.\n`);
+        } else {
+            s.stop(`❌ Failed to push secrets: ${error.message}`);
+        }
 
         trackEvent('secrets_pushed', {
             projectName,
             success: false,
-            error_code: error.name || 'UNKNOWN'
+            error_code: error.name || 'UNKNOWN',
+            error_message: error.message
         });
         await flushTelemetry();
+        process.exit(1);
     }
 }

package/src/core/telemetry.js

@@ -1,9 +1,7 @@
 import crypto from 'crypto';
 
 const TELEMETRY_ENDPOINT = 'https://eu.i.posthog.com/capture/';
-
 const POSTHOG_API_KEY = 'phc_o2wgA3jVT9rVDiGSDzFAR42zZeiVGhhCY53HXVHUcYGT';
-
 const pendingRequests = [];
 
 export function trackEvent(eventName, properties) {
@@ -27,6 +25,7 @@ export function trackEvent(eventName, properties) {
             os: process.platform,
             node_version: process.version,
             is_ci: Boolean(process.env.CI || process.env.CONTINUOUS_INTEGRATION),
+            cli_command: process.env.CLI_COMMAND || 'unknown',
             ...properties
         }
     };

package/src/utils/prompts.js

@@ -46,7 +46,7 @@ export async function getProjectConfig(isHeadless, headlessOptions, targetDir, d
             desiredCount: headlessOptions.desiredCount || '1',
             branch: headlessOptions.branch || 'main',
             needsDatabase: headlessOptions.needsDatabase === 'true' || headlessOptions.needsDatabase === true,
-            enablePrPreviews: headlessOptions.enablePrPreviews || false,
+            enablePrPreviews: headlessOptions.enablePrPreviews === 'true' || headlessOptions.enablePrPreviews === true,
             setupType: 'headless'
         };
     }