@akash-chowdhury-24/deployhub 1.0.6 → 1.0.8

package/README.md

@@ -109,6 +109,558 @@ deployhub build
 
 Or push to `main` — GitHub Actions runs `deployhub build` automatically.
 
+For a full walkthrough by project type, language, and deployment mode, see [Complete Tutorial](#complete-tutorial) below.
+
+## Complete Tutorial
+
+This section walks through every supported setup: **frontend only**, **backend only**, **full stack**, **storage only** (build + upload artifacts, no deploy), and **storage + deployment** (build, upload, then deploy). Use it as a checklist from zero to a working pipeline.
+
+### What DeployHub does on every run
+
+When you run `deployhub build` (locally or in GitHub Actions), DeployHub runs these stages in order:
+
+| Stage | What happens |
+|-------|----------------|
+| **detect** | Auto-detect framework, language, build output |
+| **install** | Install dependencies (`npm ci`, `pip install`, `mvn`, etc.) |
+| **test** | Run tests (skippable via config) |
+| **build** | Run your build command(s) |
+| **docker** | Build Docker image if `Dockerfile` exists and enabled |
+| **artifact** | Create versioned `artifact.zip` + metadata locally |
+| **storage** | Upload artifact to all selected providers (parallel) |
+| **deploy** | Deploy to targets — **only if you configured deployment during `init`** |
+| **verify** | Hit your health-check URL — **only if configured** |
+| **notify** | Slack / email / webhook — **only if enabled** |
+
+**Storage only** means you answer **No** to *Configure deployment?* during `init`. You still get builds and cloud backups; nothing is pushed to a server or platform.
+
+**Storage + deployment** means you answer **Yes**, pick targets, and add the matching secrets. Deploy always runs **after** storage upload succeeds.
+
+---
+
+### Prerequisites (all projects)
+
+1. **Git repository** with a remote (GitHub recommended for CI).
+2. **DeployHub installed** — see [Installation](#installation) above.
+3. **Run from your project root** (where `package.json`, `go.mod`, `pom.xml`, etc. lives).
+
+| Language / stack | You need on the machine / in CI |
+|------------------|----------------------------------|
+| Node.js (React, Vue, Express, NestJS, …) | Node.js 18+, npm |
+| Python (FastAPI, Django, Flask) | Python 3.11+, `requirements.txt` or `pyproject.toml` |
+| PHP (Laravel, Symfony) | PHP, Composer, `composer.json` |
+| Java (Spring Boot) | JDK 17+, Maven, `pom.xml` |
+| Go | Go 1.22+, `go.mod` |
+| .NET | .NET 8 SDK, `.csproj` |
+| Ruby on Rails | Ruby 3.2+, Bundler, `Gemfile` |
+
+---
+
+### Step 1 — Initialize (every workflow)
+
+```bash
+cd your-project
+deployhub init
+```
+
+The wizard asks the same core questions for every setup:
+
+| Prompt | What to choose |
+|--------|----------------|
+| **Project name** | Defaults to folder name; used in artifact paths and deploy paths |
+| **What are you deploying?** | `Frontend only` · `Backend only` · `Both (monorepo / fullstack)` |
+| **Framework** | Auto-detected when possible; confirm or change |
+| **Build command / output** | Pre-filled per framework (see [Framework defaults](#framework-defaults-by-language) below) |
+| **Storage providers** | Pick one or more: Local, AWS S3, Google Drive, Azure, GCP, Dropbox |
+| **Configure deployment?** | **No** = storage only · **Yes** = storage + deploy |
+| **CLI source for GitHub Actions** | Default `npm:@akash-chowdhury-24/deployhub` is fine for most users |
+
+**Generated files:**
+
+- `deployhub.config.json` — project settings (no secrets)
+- `.github/workflows/deployhub.yml` — CI pipeline
+- `.env.example` — list of env vars you may need
+- `nginx.conf` — auto-generated if frontend deploys to SSH
+- `firebase.json` — auto-generated if you pick Firebase Hosting
+
+---
+
+### Step 2 — Credentials
+
+```bash
+cp .env.example .env
+# Edit .env locally
+
+deployhub storage add aws      # repeat per provider
+deployhub storage add gdrive
+```
+
+For **GitHub Actions**, add the same values as repository secrets (Settings → Secrets and variables → Actions). See [GitHub Secrets](#github-secrets).
+
+---
+
+### Step 3 — Verify
+
+```bash
+deployhub doctor
+```
+
+Fix any ✗ items before your first build.
+
+---
+
+### Step 4 — Build (and deploy if configured)
+
+```bash
+deployhub build
+```
+
+Or push to `main` / `master` — the generated workflow runs the same command.
+
+**Useful follow-up commands:**
+
+```bash
+deployhub artifact list              # see uploaded versions
+deployhub artifact restore v1.2.3    # download a past build
+deployhub deploy                     # deploy latest artifact without rebuilding
+deployhub rollback v1.2.2            # roll back on server
+deployhub logs                       # last deployment logs
+```
+
+---
+
+## Walkthrough: Storage only
+
+Use this when you want **versioned build artifacts in the cloud** but deploy manually (or add deployment later).
+
+### During `deployhub init`
+
+1. Choose project type (frontend / backend / both).
+2. Select framework and confirm build settings.
+3. Check at least one **storage** provider (Local is checked by default).
+4. Answer **Configure deployment?** → **No**.
+
+### Resulting config
+
+`deployhub.config.json` will have `"deploy": []` and `"pipeline": { "deploy": false }`. Every `deployhub build` still runs detect → install → test → build → artifact → **storage**.
+
+### Example: React app → AWS S3 only
+
+```bash
+deployhub init
+# What are you deploying?     → Frontend only
+# Framework                   → React
+# Build command               → npm run build
+# Build output                → dist
+# Storage                     → ✓ AWS S3
+# Configure deployment?       → No
+```
+
+```bash
+cp .env.example .env
+# Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET, AWS_REGION
+
+deployhub doctor
+deployhub build
+```
+
+Artifacts appear under `artifact/{projectName}/{date}/v{version}/` locally **and** in your S3 bucket.
+
+### Same steps for other languages
+
+Storage-only init is **identical** for every language — only the framework/build prompts change. See [Framework defaults](#framework-defaults-by-language).
+
+---
+
+## Walkthrough: Storage + deployment
+
+Use this when you want **build → upload artifact → deploy** in one command.
+
+### During `deployhub init`
+
+1. Complete project type + framework setup.
+2. Select storage provider(s).
+3. Answer **Configure deployment?** → **Yes**.
+4. Follow the deployment prompts (differs by project type — below).
+
+Deployment **requires** at least one storage provider. DeployHub restores from the uploaded artifact on the target.
+
+---
+
+## Walkthrough: Frontend only
+
+### Init choices
+
+| Prompt | Options |
+|--------|---------|
+| What are you deploying? | **Frontend only** |
+| Framework | React, Vue, Angular, Next.js, Svelte, Astro, Vanilla JS, Other |
+| Configure deployment? | No (storage only) or Yes |
+
+If **Yes** to deployment:
+
+| Prompt | Options |
+|--------|---------|
+| How do you want to deploy? | **Managed platform** or **Self-hosted server** |
+
+#### Option A — Managed platform (Vercel, Netlify, …)
+
+Best for static sites and Jamstack frontends. DeployHub builds locally/CI, uploads the artifact, then invokes the platform CLI.
+
+| Platform | Best for | Secrets to add |
+|----------|----------|----------------|
+| Vercel | Next.js, React | `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` |
+| Netlify | React, Vue, Svelte | `NETLIFY_AUTH_TOKEN`, `NETLIFY_SITE_ID` |
+| Cloudflare Pages | Astro, static React | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CF_PROJECT_NAME` |
+| AWS Amplify | React, Next.js on AWS | `AWS_*`, `AMPLIFY_APP_ID` |
+| Azure Static Web Apps | React, Angular | `AZURE_STATIC_WEB_APPS_TOKEN` |
+| Firebase Hosting | SPAs | `FIREBASE_TOKEN`, `FIREBASE_PROJECT_ID` |
+| Firebase App Hosting | Next.js / Angular SSR | `FIREBASE_TOKEN`, `FIREBASE_PROJECT_ID`, `FIREBASE_APP_HOSTING_BACKEND` |
+
+**Example: Vue → Google Drive + Netlify**
+
+```bash
+deployhub init
+# Frontend only → Vue
+# Storage: Local + Google Drive
+# Configure deployment? Yes
+# Managed platform → Netlify
+# Site ID: (from Netlify dashboard)
+```
+
+```bash
+cp .env.example .env
+# GDRIVE_* and NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID
+
+deployhub doctor
+git push origin main
+```
+
+#### Option B — Self-hosted server (SSH, Docker, EC2, …)
+
+Best when you serve static files from your own VPS. DeployHub uploads the built `dist/` (or your output dir) over SSH and can generate `nginx.conf`.
+
+| Deploy type | You provide |
+|-------------|-------------|
+| **ssh** | `SSH_HOST`, `SSH_USER`, `SSH_KEY`, deploy path |
+| **docker** | Docker host access / image registry per your setup |
+| **ec2** | SSH credentials to EC2 instance |
+| **azure-vm** / **gcp-vm** | SSH to VM |
+| **kubernetes** | Cluster credentials (via env / kubeconfig) |
+
+**Example: Angular → Azure Blob + SSH**
+
+```bash
+deployhub init
+# Frontend only → Angular
+# Build: ng build, output dist
+# Storage: Azure Blob
+# Configure deployment? Yes → Self-hosted → ssh
+# Host, user, deploy path: /var/www/my-app
+```
+
+Add `AZURE_*`, `SSH_HOST`, `SSH_USER`, `SSH_KEY` to `.env` and GitHub Secrets. Review the generated `nginx.conf` and install it on the server.
+
+#### Frontend framework defaults
+
+| Framework | Build command | Output dir | Notes |
+|-----------|---------------|------------|-------|
+| React | `npm run build` | `dist` or `build` | Create React App uses `build` |
+| Vue | `npm run build` | `dist` | Vite default |
+| Angular | `ng build` | `dist` | |
+| Next.js | `npm run build` | `.next` | Platform deploy recommended |
+| Svelte | `npm run build` | `public` | |
+| Astro | `astro build` | `dist` | |
+| Vanilla JS | *(none)* | `.` | Copies static files as-is |
+
+---
+
+## Walkthrough: Backend only
+
+Backends always deploy to a **self-hosted target** (SSH, Docker, EC2, Azure VM, GCP VM, or Kubernetes). There is no “managed platform” path for backend-only projects.
+
+### Init choices
+
+| Prompt | Typical value |
+|--------|----------------|
+| What are you deploying? | **Backend only** |
+| Language / framework | See table below |
+| Start command | e.g. `npm start`, `uvicorn main:app …` |
+| Port | e.g. 3000, 8000, 8080 |
+| Storage | At least one provider |
+| Configure deployment? | Yes for storage + deploy |
+| Deployment type | ssh (most common), docker, ec2, kubernetes, … |
+| App name | PM2 process name on server |
+| Health check URL | e.g. `https://api.example.com/health` |
+
+### Example: Express API → S3 + SSH
+
+```bash
+deployhub init
+# Backend only → Node.js Express
+# Start: npm start, port 3000
+# Storage: AWS S3
+# Configure deployment? Yes → ssh
+# Host: 203.0.113.10, user: deploy, path: /var/www/my-api
+# App name: my-api
+# Health URL: https://api.example.com/health
+```
+
+On the server, ensure **Node.js**, **PM2**, and your app dependencies are available. DeployHub SSHs in, extracts the artifact, runs install if needed, and restarts PM2.
+
+### Example: FastAPI → Dropbox + SSH
+
+```bash
+deployhub init
+# Backend only → Python FastAPI
+# Start: uvicorn main:app --host 0.0.0.0 --port 8000
+# Storage: Dropbox
+# Deploy: ssh
+```
+
+Server needs **Python 3.11+**, `pip`, and ideally **gunicorn/uvicorn** for production.
+
+### Backend framework defaults
+
+| Framework | Language | Build | Start | Port | Test |
+|-----------|----------|-------|-------|------|------|
+| Express | Node | — | `npm start` | 3000 | `npm test` |
+| NestJS | Node | `nest build` | `node dist/main` | 3000 | `npm test` |
+| Fastify / Koa | Node | — | `npm start` | 3000 | `npm test` |
+| FastAPI | Python | — | `uvicorn main:app --host 0.0.0.0 --port 8000` | 8000 | `pytest` |
+| Django | Python | — | `gunicorn config.wsgi:application --bind 0.0.0.0:8000` | 8000 | `python manage.py test` |
+| Flask | Python | — | `gunicorn app:app --bind 0.0.0.0:5000` | 5000 | `pytest` |
+| Laravel | PHP | — | `php artisan serve` | 80 | `php artisan test` |
+| Symfony | PHP | — | `php-fpm` | 80 | `php bin/phpunit` |
+| Spring Boot | Java | `mvn package` | `java -jar target/*.jar` | 8080 | `mvn test` |
+| Go | Go | `go build -o bin/app .` | `./bin/app` | 8080 | `go test ./...` |
+| .NET | C# | `dotnet publish -c Release -o publish` | `dotnet App.dll` | 5000 | `dotnet test` |
+| Rails | Ruby | `bundle exec rake assets:precompile` | `bundle exec puma` | 3000 | `bundle exec rspec` |
+
+**Node.js backends** without a build step still get packaged; set `buildCommand` to empty in config if you truly have no compile step.
+
+**Java / Go / .NET** always run a compile step before artifact creation.
+
+---
+
+## Walkthrough: Full stack (frontend + backend)
+
+Choose **Both (monorepo / fullstack)** when frontend and backend live in the **same repository root** (typical monorepo layout).
+
+### Init flow
+
+1. **Frontend** — framework, build command, output directory.
+2. **Backend** — framework, start command, port.
+3. **Storage** — one or more providers.
+4. **Configure deployment?** → Yes.
+5. **Frontend deploy method** — Managed platform **or** self-hosted SSH.
+6. **Backend deploy** — always self-hosted (SSH, Docker, EC2, …).
+
+DeployHub runs **both** builds, packs them into one artifact, uploads once, then deploys frontend and backend to their respective targets.
+
+### Example: React + Express monorepo
+
+```bash
+deployhub init
+# Both (monorepo / fullstack)
+# Frontend: React, npm run build, dist
+# Backend: Express, npm start, port 3000
+# Storage: AWS S3 + Local
+# Configure deployment? Yes
+# Frontend: Managed platform → Vercel
+# Backend: ssh → api.example.com, path /var/www/my-app/api, PM2 name my-app-api
+```
+
+**Secrets:** AWS + `VERCEL_*` + `SSH_*`
+
+**Layout tip:** Keep `package.json` scripts for both apps at the repo root, or ensure build commands point to the correct paths (edit `deployhub.config.json` after init if your monorepo uses subfolders).
+
+### Example: React + Express, both on one VPS
+
+```bash
+deployhub init
+# Both → React + Express
+# Frontend deploy: Self-hosted server
+# Frontend path: /var/www/my-app/public
+# Backend: ssh, path /var/www/my-app/api
+```
+
+DeployHub generates `nginx.conf` to serve static files and proxy API requests.
+
+### Example: Next.js API routes only
+
+Use **Frontend only** with **Next.js** and deploy to **Vercel** or **Firebase App Hosting** — no separate backend entry needed.
+
+---
+
+## Framework defaults by language
+
+### JavaScript / TypeScript (Node)
+
+All JS frontends share the same install/build flow: `npm ci` → `npm run build` → artifact from output directory.
+
+| Role | Frameworks |
+|------|------------|
+| Frontend | React, Vue, Angular, Next.js, Svelte, Astro, Vanilla |
+| Backend | Express, NestJS, Fastify, Koa |
+
+**Init is the same** for each; only default build/output/start commands differ (tables above).
+
+### Python
+
+- **Detect:** `requirements.txt` containing `fastapi`, `django`, or `flask`.
+- **Install:** `pip install -r requirements.txt`
+- **Test:** `pytest` (if `pytest.ini` exists) or Django test runner.
+- **Build:** Usually skipped (`buildCommand: null`); artifact includes source + dependencies list.
+- **Deploy (SSH):** Server must have Python + pip; start command runs uvicorn/gunicorn.
+
+### PHP
+
+- **Detect:** `composer.json` with `laravel/framework` or `symfony/framework-bundle`.
+- **Install:** Composer (on CI and server).
+- **Deploy:** SSH with PHP-FPM or `php artisan` for Laravel.
+
+### Java
+
+- **Detect:** `pom.xml` with Spring Boot.
+- **Install/Build:** `mvn package` produces JAR in `target/`.
+- **Deploy:** SSH runs `java -jar target/*.jar` (or your custom start command).
+
+### Go
+
+- **Detect:** `go.mod` present.
+- **Build:** `go build -o bin/app .`
+- **Artifact:** `bin/` binary + any config files.
+- **Deploy:** SSH copies binary and restarts process.
+
+### .NET
+
+- **Detect:** `.csproj` in project root.
+- **Build:** `dotnet publish -c Release -o publish`
+- **Deploy:** SSH runs `dotnet YourApp.dll` from publish folder.
+
+### Ruby
+
+- **Detect:** `Gemfile` with `rails`.
+- **Build:** `bundle exec rake assets:precompile` (for production assets).
+- **Deploy:** SSH with `bundle exec puma` or your configured start command.
+
+---
+
+## GitHub Actions setup
+
+After `init`, commit these files:
+
+```bash
+git add deployhub.config.json .github/workflows/deployhub.yml .env.example
+git commit -m "Add DeployHub CI"
+```
+
+1. Open **Settings → Secrets and variables → Actions** in your GitHub repo.
+2. Add every secret listed at the end of `deployhub init` (storage + deployment).
+3. Push to `main` or `master` — the workflow triggers on push.
+
+The workflow installs the correct language runtime (Node, Python, Java, Go, .NET, Ruby) based on your `deployhub.config.json`, installs DeployHub, runs `deployhub build`, and uses your secrets.
+
+To run manually: **Actions → DeployHub → Run workflow**.
+
+---
+
+## Choosing storage providers
+
+| Provider | Good for | Setup command |
+|----------|----------|---------------|
+| **Local** | Dev/testing, no cloud account | No credentials |
+| **AWS S3** | Production, CI-friendly | `deployhub storage add aws` |
+| **Google Drive** | Small teams, manual downloads | `deployhub storage add gdrive` |
+| **Azure Blob** | Azure ecosystem | `deployhub storage add azure` |
+| **GCP Storage** | GCP ecosystem | `deployhub storage add gcp` |
+| **Dropbox** | Simple off-site backup | `deployhub storage add dropbox` |
+
+You can enable **multiple providers** — DeployHub uploads to all of them in parallel on every build.
+
+---
+
+## Deployment target cheat sheet
+
+| Project type | Frontend deploy options | Backend deploy options |
+|--------------|-------------------------|------------------------|
+| Frontend only | Platform **or** SSH/Docker/EC2/K8s | — |
+| Backend only | — | SSH/Docker/EC2/Azure VM/GCP VM/K8s |
+| Full stack | Platform **or** SSH (static + nginx) | SSH/Docker/EC2/K8s (always) |
+
+| Mode | Storage | Deploy | When to use |
+|------|---------|--------|-------------|
+| **Storage only** | ✓ | ✗ | Backups, audit trail, manual releases |
+| **Storage + deploy** | ✓ | ✓ | Full CI/CD |
+
+---
+
+## Minimal `deployhub.config.json` examples
+
+### Storage only — React
+
+```json
+{
+  "project": "my-react-app",
+  "projectType": "frontend",
+  "framework": "react",
+  "buildCommand": "npm run build",
+  "buildOutput": "dist",
+  "storage": ["local", "aws"],
+  "deploy": [],
+  "pipeline": { "test": true, "deploy": false, "verify": false }
+}
+```
+
+### Storage + deploy — FastAPI on SSH
+
+```json
+{
+  "project": "my-api",
+  "projectType": "backend",
+  "framework": "fastapi",
+  "language": "python",
+  "startCommand": "uvicorn main:app --host 0.0.0.0 --port 8000",
+  "port": 8000,
+  "storage": ["aws"],
+  "deploy": ["production"],
+  "environments": {
+    "production": {
+      "deploymentType": "server",
+      "type": "ssh",
+      "host": "203.0.113.10",
+      "user": "deploy",
+      "deployPath": "/var/www/my-api",
+      "appName": "my-api",
+      "framework": "fastapi"
+    }
+  },
+  "pipeline": { "deploy": true, "verify": true },
+  "healthCheck": { "url": "https://api.example.com/health", "timeout": 30 }
+}
+```
+
+Prefer `deployhub init` over hand-writing config — it sets adapters, workflow, and secrets list correctly.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `Deploy requires storage upload` | Add at least one storage provider in config |
+| AWS / GDrive check fails in `doctor` | Run `deployhub storage add <provider>` and match GitHub Secrets |
+| SSH deploy fails | Verify `SSH_KEY` is the **private** key; user can write to deploy path |
+| Wrong output uploaded | Fix `buildOutput` in config (`dist` vs `build` vs `.next`) |
+| Tests fail in CI | Set `"pipeline": { "test": false }` temporarily, or fix tests |
+| Platform deploy missing CLI | Install platform CLI in CI (workflow does this for Vercel, Netlify, etc.) |
+| Monorepo subfolders | Edit `buildCommand` paths in `deployhub.config.json` after init |
+
+Run `deployhub doctor` after any config change.
+
+---
+
 ## Commands
 
 | Command | Description |
@@ -130,7 +682,9 @@ Or push to `main` — GitHub Actions runs `deployhub build` automatically.
 
 ## GitHub Secrets
 
-Add these secrets in your repository (Settings → Secrets and variables → Actions). Only add secrets for providers you selected during `init`:
+Add these secrets in your repository (Settings → Secrets and variables → Actions). Only add secrets for providers you selected during `init`. At the end of `deployhub init`, DeployHub prints the exact list for your project.
+
+### Storage
 
 | Secret | Provider |
 |--------|----------|
@@ -148,9 +702,30 @@ Add these secrets in your repository (Settings → Secrets and variables → Act
 | `GCP_KEY_FILE` | GCP Storage |
 | `GCP_BUCKET` | GCP Storage |
 | `DROPBOX_ACCESS_TOKEN` | Dropbox |
-| `SSH_HOST` | SSH deployment |
-| `SSH_USER` | SSH deployment |
-| `SSH_KEY` | SSH deployment |
+| `FTP_HOST`, `FTP_USER`, `FTP_PASSWORD` | FTP storage |
+
+### Server deployment (SSH, EC2, VMs)
+
+| Secret | Used for |
+|--------|----------|
+| `SSH_HOST` | Target server hostname |
+| `SSH_USER` | SSH username |
+| `SSH_KEY` | Private SSH key (PEM) |
+| `SSH_DEPLOY_PATH` | Remote directory (optional if set in config) |
+| `SSH_APP_NAME` | PM2 process name for backends |
+| `SSH_PORT` | App port on server (optional) |
+
+### Managed platforms (frontend)
+
+| Secret | Platform |
+|--------|----------|
+| `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` | Vercel |
+| `NETLIFY_AUTH_TOKEN`, `NETLIFY_SITE_ID` | Netlify |
+| `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CF_PROJECT_NAME` | Cloudflare Pages |
+| `AMPLIFY_APP_ID` (+ `AWS_*` if not already set) | AWS Amplify |
+| `AZURE_STATIC_WEB_APPS_TOKEN` | Azure Static Web Apps |
+| `FIREBASE_TOKEN`, `FIREBASE_PROJECT_ID` | Firebase Hosting |
+| `FIREBASE_APP_HOSTING_BACKEND` | Firebase App Hosting |
 
 ## `deployhub doctor` Output
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akash-chowdhury-24/deployhub",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

package/src/commands/init.js

@@ -14,6 +14,7 @@ import { getProjectVersion } from '../utils/version.js';
 import {
   writeWorkflowFile,
   getRequiredSecrets,
+  generateEnvExampleContent,
   guessCliGithubRepo,
   addDeployhubToPackageJson,
 } from '../utils/github-actions.js';
@@ -288,25 +289,6 @@ function buildServerEnvEntry(
   return envEntry;
 }
 
-/**
- * @returns {Promise<string>}
- */
-async function getEnvExampleContent() {
-  const possiblePaths = [
-    path.join(path.dirname(process.execPath), '.env.example'),
-    path.join(process.cwd(), '.env.example'),
-    new URL('../../.env.example', import.meta.url).pathname,
-  ];
-  for (const p of possiblePaths) {
-    try {
-      return await fs.readFile(p, 'utf-8');
-    } catch {
-      // try next path
-    }
-  }
-  return '# Add your environment variables here\n';
-}
-
 /**
  * @param {Record<string, unknown>} config
  * @param {Record<string, Record<string, unknown>>} environments
@@ -780,7 +762,12 @@ export function registerInitCommand(program) {
       await generateProjectScaffold(config, environments, cwd);
 
       const envExampleDest = path.join(cwd, '.env.example');
-      const envExampleContent = await getEnvExampleContent();
+      const envExampleContent = generateEnvExampleContent(
+        config.storage,
+        deploy,
+        environments,
+        config
+      );
       await fs.writeFile(envExampleDest, envExampleContent);
 
       const secrets = getRequiredSecrets(config.storage, deploy, environments, config);

package/src/utils/github-actions.js

@@ -1,6 +1,11 @@
 import fs from 'fs-extra';
 import path from 'path';
-import { PLATFORM_ENV_MAP, PLATFORM_CLI_MAP } from './platform-env.js';
+import {
+  PLATFORM_ENV_MAP,
+  PLATFORM_CLI_MAP,
+  PLATFORM_CHOICES,
+  getPlatformEnvExample,
+} from './platform-env.js';
 import { getWorkflowHeaderComment } from './author.js';
 
 /** @typedef {'aws'|'azure'|'gcp'|'gdrive'|'dropbox'|'local'|'ftp'|'ssh'} ProviderEnvKey */
@@ -32,6 +37,28 @@ const BACKEND_SSH_ENV_VARS = [
   'SSH_PORT',
 ];
 
+const PROVIDER_LABELS = {
+  aws: 'AWS S3',
+  azure: 'Azure Blob',
+  gcp: 'GCP',
+  gdrive: 'Google Drive',
+  dropbox: 'Dropbox',
+  ftp: 'FTP',
+  ssh: 'SSH Deployment',
+};
+
+const PLATFORM_LABELS = Object.fromEntries(
+  PLATFORM_CHOICES.map(({ name, value }) => [value, name])
+);
+
+const ENV_VAR_DEFAULTS = {
+  AWS_REGION: 'us-east-1',
+  FTP_PORT: '21',
+  FTP_PATH: '/uploads',
+  SSH_DEPLOY_PATH: '/var/www/app',
+  SMTP_PORT: '587',
+};
+
 const NPM_PACKAGE = '@akash-chowdhury-24/deployhub';
 const DEFAULT_NPM_CLI_SOURCE = `npm:${NPM_PACKAGE}`;
 
@@ -400,4 +427,113 @@ export function getRequiredSecrets(
   return Array.from(secrets);
 }
 
+/**
+ * @param {string} title
+ * @param {string[]} keys
+ * @param {Record<string, string>} [defaults]
+ * @param {Set<string>} seenKeys
+ * @returns {string}
+ */
+function formatEnvSection(title, keys, defaults, seenKeys) {
+  const newKeys = keys.filter((key) => !seenKeys.has(key));
+  if (newKeys.length === 0) return '';
+
+  for (const key of newKeys) {
+    seenKeys.add(key);
+  }
+
+  const lines = newKeys.map((key) => {
+    const value = defaults?.[key] ?? ENV_VAR_DEFAULTS[key] ?? '';
+    return value ? `${key}=${value}` : `${key}=`;
+  });
+
+  return `# ${title}\n${lines.join('\n')}\n`;
+}
+
+/**
+ * @param {string[]} storageProviders
+ * @param {string[]} deployEnvironments
+ * @param {Record<string, Record<string, unknown>>} environments
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @returns {string}
+ */
+export function generateEnvExampleContent(
+  storageProviders,
+  deployEnvironments,
+  environments,
+  config = null
+) {
+  /** @type {Set<string>} */
+  const seenKeys = new Set();
+  /** @type {string[]} */
+  const sections = [];
+
+  const addSection = (title, keys, defaults = {}) => {
+    const section = formatEnvSection(title, keys, defaults, seenKeys);
+    if (section) sections.push(section);
+  };
+
+  for (const provider of storageProviders) {
+    const keys = PROVIDER_ENV_MAP[provider] || [];
+    if (keys.length > 0) {
+      addSection(PROVIDER_LABELS[provider] || provider, keys);
+    }
+  }
+
+  for (const envName of deployEnvironments) {
+    const env = environments[envName];
+    if (!env) continue;
+
+    if (env.deploymentType === 'platform' || env.frontendDeploymentType === 'platform') {
+      const platform = env.platform;
+      if (platform) {
+        const examples = getPlatformEnvExample(platform);
+        addSection(
+          PLATFORM_LABELS[platform] || platform,
+          Object.keys(examples),
+          examples
+        );
+      }
+      continue;
+    }
+
+    const keys = PROVIDER_ENV_MAP[env.type] || [];
+    if (keys.length > 0) {
+      addSection(PROVIDER_LABELS[env.type] || env.type, keys);
+    }
+
+    if (env.type === 'ssh' && config) {
+      const projectType = config.projectType || 'frontend';
+      if (projectType === 'backend' || projectType === 'both') {
+        addSection('SSH Deployment (backend)', BACKEND_SSH_ENV_VARS);
+      }
+    }
+  }
+
+  if (config?.notifications) {
+    if (config.notifications.slack) {
+      addSection('Notifications', ['SLACK_WEBHOOK_URL']);
+    }
+    if (config.notifications.webhook) {
+      addSection('Notifications', ['WEBHOOK_URL']);
+    }
+    if (config.notifications.email) {
+      addSection('Email (SMTP)', [
+        'SMTP_HOST',
+        'SMTP_PORT',
+        'SMTP_USER',
+        'SMTP_PASS',
+        'NOTIFICATION_EMAIL',
+        'NOTIFY_EMAIL_TO',
+      ]);
+    }
+  }
+
+  if (sections.length === 0) {
+    return '# Add your environment variables here\n';
+  }
+
+  return `${sections.join('\n')}\n`;
+}
+
 export { PROVIDER_ENV_MAP };