cistack 2.0.0 → 3.0.1

package/README.md

@@ -10,12 +10,15 @@
 
 - 🔍 **Deep codebase analysis** — reads `package.json`, lock files, config files, and directory structure
 - 🧠 **Smart detection** — identifies 30+ frameworks, 12 languages, 12+ testing tools, and 10+ hosting platforms
+- ⚡ **Native Cache support** — speeds up pipelines by 2–4min using native caching for npm, pip, go, cargo, maven, gradle, and bundler
+- ✨ **PR Preview Deploys** — automatic preview environments for Vercel and Netlify on every pull request
 - 🚀 **Hosting auto-detect** — Firebase, Vercel, Netlify, AWS, GCP, Azure, Heroku, Render, Railway, GitHub Pages, Docker
-- 🏗️ **Multi-workflow output** — generates separate `ci.yml`, `deploy.yml`, `docker.yml`, and `security.yml` as appropriate
+- 🛡️ **Workflow Audit & Upgrade** — analyse existing `.github/workflows` for outdated actions and missing best practices
+- 🏗️ **Multi-workflow output** — generates separate `ci.yml`, `deploy.yml`, `docker.yml`, and `security.yml`
 - 🔒 **Security built-in** — CodeQL analysis + dependency auditing on every pipeline
-- 📦 **Monorepo aware** — detects Turborepo, Nx, Lerna, pnpm workspaces
+- 📦 **Monorepo aware** — detects Turborepo, Nx, Lerna, pnpm workspaces (supports per-package workflows)
 - ✅ **Interactive mode** — confirms detected settings before writing files
-- 🎯 **Zero config** — works out of the box with no configuration needed
+- 🎯 **Zero config** — works out of the box with `cistack.config.js` for overrides
 
 ---
 
@@ -33,10 +36,15 @@ npm install -g cistack
 
 ## Usage
 
+### Generate Pipelines
+Analyze your stack and generate best-practice workflows.
 ```bash
 # In your project directory
 npx cistack
 
+# Show reasoning for detected stack
+npx cistack --explain
+
 # Specify a project path
 npx cistack --path /path/to/project
 
@@ -45,19 +53,40 @@ npx cistack --output .github/workflows
 
 # Dry run (print YAML without writing files)
 npx cistack --dry-run
+```
 
-# Skip interactive prompts
-npx cistack --no-prompt
+### Audit Existing Workflows
+Analyze your current `.github/workflows` folder for outdated actions or missing features.
+```bash
+npx cistack audit
+```
 
-# Verbose output
-npx cistack --verbose
+### Automatic Upgrade
+Automatically bump all action versions (e.g., `actions/checkout@v3` → `@v4`) across all your workflow files to the latest stable releases.
+```bash
+npx cistack upgrade
+```
 
-# Force overwrite existing files
-npx cistack --force
+### Initialization
+Create a `cistack.config.js` to override auto-detected settings.
+```bash
+npx cistack init
 ```
 
 ---
 
+## Flags
+
+- `--explain` — Show detailed reasoning for every detection (build trust)
+- `--dry-run` — Print YAML to terminal without writing to disk
+- `--force` — Overwrite existing files instead of smart-merging
+- `--no-prompt` — Skip interactive confirmation
+- `--verbose` — Show raw analysis data
+- `--path <dir>` — Project root directory
+- `--output <dir>` — Workflow output directory (default: `.github/workflows`)
+
+---
+
 ## Detected Hosting Platforms
 
 | Platform | Detection Signal |
@@ -112,21 +141,23 @@ Runs on every push and pull request:
 2. **Test** — unit tests with coverage upload (matrix across Node versions)
 3. **Build** — production build, artifact upload
 4. **E2E** — Cypress / Playwright (if detected)
+5. **Caching** — Full dependency caching for faster runs
 
 ### `deploy.yml` — Continuous Deployment
 Triggers on push to `main`/`master` + manual dispatch:
-- Platform-specific deploy using the best available GitHub Action
+- Platform-specific deploy using official GitHub Actions
+- **PR Preview Deploys** — automatic previews for Vercel and Netlify pull requests
 - Proper secret references documented in the file header
 
 ### `docker.yml` — Docker Build & Push
 Triggers on push to `main` and version tags:
 - Multi-platform build via Docker Buildx
 - Pushes to GitHub Container Registry (GHCR)
-- Build cache via GitHub Actions cache
+- Build cache via GitHub Actions cache (GHA)
 
 ### `security.yml` — Security Audit
 Runs on push, PRs, and weekly schedule:
-- Dependency vulnerability audit (npm audit / safety / etc.)
+- Dependency vulnerability audit (npm audit / safety / cargo audit)
 - GitHub CodeQL analysis for the detected language
 
 ---
@@ -142,28 +173,11 @@ Each generated `deploy.yml` has a comment at the top listing the exact secrets n
 
 ## Examples
 
-**Next.js + Vercel project:**
-```
-npx cistack
-# → .github/workflows/ci.yml     (lint, test, build)
-# → .github/workflows/deploy.yml (vercel deploy)
-# → .github/workflows/security.yml
-```
-
-**Firebase + React project:**
-```
-npx cistack
-# → .github/workflows/ci.yml
-# → .github/workflows/deploy.yml (firebase deploy --only hosting)
-# → .github/workflows/security.yml
-```
-
-**Node.js API + Docker:**
-```
-npx cistack
-# → .github/workflows/ci.yml
-# → .github/workflows/docker.yml (GHCR push)
-# → .github/workflows/security.yml
+**Next.js + Vercel project with Audit:**
+```bash
+npx cistack audit       # Check existing workflows
+npx cistack upgrade     # Update versions to v4
+npx cistack generate    # Refresh with latest caching & previews
 ```
 
 ---

package/bin/ciflow.js

@@ -6,10 +6,12 @@ const { program } = require('commander');
 const path = require('path');
 const CIFlow = require('../src/index');
 
+const { version } = require('../package.json');
+
 program
   .name('cistack')
   .description('Generate GitHub Actions CI/CD pipelines by analysing your codebase')
-  .version('2.0.0');
+  .version(version);
 
 program
   .command('generate', { isDefault: true })
@@ -20,6 +22,7 @@ program
   .option('--force', 'Overwrite existing workflow files without smart-merge')
   .option('--no-prompt', 'Skip interactive prompts and use detected settings')
   .option('--verbose', 'Show detailed analysis output')
+  .option('--explain', 'Show reasoning for detected stack')
   .action(async (options) => {
     const ciflow = new CIFlow({
       projectPath: path.resolve(options.path),
@@ -28,12 +31,36 @@ program
       force:       options.force,
       prompt:      options.prompt,
       verbose:     options.verbose,
+      explain:     options.explain,
     });
     await ciflow.run();
   });
 
+program
+  .command('audit')
+  .description("Analyse existing .github/workflows/ folder and suggest fixes")
+  .option('-p, --path <dir>', 'Path to the project root', process.cwd())
+  .action(async (options) => {
+    const ciflow = new CIFlow({ projectPath: path.resolve(options.path) });
+    await ciflow.audit();
+  });
+
+program
+  .command('upgrade')
+  .description("Automatically bump action versions across all workflow files")
+  .option('-p, --path <dir>', 'Path to the project root', process.cwd())
+  .option('--dry-run', 'Show what would be upgraded without modifying files')
+  .action(async (options) => {
+    const ciflow = new CIFlow({ 
+      projectPath: path.resolve(options.path),
+      dryRun: options.dryRun
+    });
+    await ciflow.upgrade();
+  });
+
 program
   .command('init')
+  // ... rest of init
   .description('Create a starter cistack.config.js in the current directory')
   .option('-p, --path <dir>', 'Path to the project root', process.cwd())
   .action(async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cistack",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "Automatically generate GitHub Actions CI/CD pipelines by analysing your codebase",
   "main": "src/index.js",
   "bin": {

package/src/analyzers/workflow.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+
+class WorkflowAnalyzer {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.workflowsDir = path.join(projectPath, '.github/workflows');
+    
+    // Latest stable versions for common actions
+    this.latestVersions = {
+      'actions/checkout': 'v4',
+      'actions/setup-node': 'v4',
+      'actions/setup-python': 'v5',
+      'actions/setup-java': 'v4',
+      'actions/setup-go': 'v5',
+      'actions/upload-artifact': 'v4',
+      'actions/download-artifact': 'v4',
+      'actions/cache': 'v4',
+      'docker/setup-buildx-action': 'v3',
+      'docker/login-action': 'v3',
+      'docker/build-push-action': 'v5',
+      'docker/metadata-action': 'v5',
+      'pnpm/action-setup': 'v3',
+      'codecov/codecov-action': 'v4',
+      'github/codeql-action/init': 'v3',
+      'github/codeql-action/analyze': 'v3',
+      'github/codeql-action/autobuild': 'v3',
+    };
+  }
+
+  async audit() {
+    const results = {
+      files: [],
+      totalIssues: 0,
+      suggestions: [],
+    };
+
+    if (!fs.existsSync(this.workflowsDir)) {
+      return results;
+    }
+
+    const files = fs.readdirSync(this.workflowsDir).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'));
+
+    for (const filename of files) {
+      const filePath = path.join(this.workflowsDir, filename);
+      const content = fs.readFileSync(filePath, 'utf8');
+      
+      try {
+        const parsed = yaml.load(content);
+        const fileIssues = this._auditFile(filename, parsed, content);
+        results.files.push({
+          filename,
+          issues: fileIssues,
+        });
+        results.totalIssues += fileIssues.length;
+      } catch (err) {
+        results.files.push({
+          filename,
+          error: `Failed to parse YAML: ${err.message}`,
+        });
+      }
+    }
+
+    return results;
+  }
+
+  _auditFile(filename, parsed, rawContent) {
+    const issues = [];
+
+    // 1. Check for concurrency
+    if (!parsed.concurrency) {
+      issues.push({
+        type: 'missing_concurrency',
+        severity: 'medium',
+        message: 'Missing concurrency group (highly recommended to prevent redundant runs)',
+        fix: 'Add concurrency block with cancel-in-progress: true',
+      });
+    }
+
+    // 2. Check for outdated actions
+    const actionRegex = /uses:\s*([\w\-\/]+)@([\w\.]+)/g;
+    let match;
+    while ((match = actionRegex.exec(rawContent)) !== null) {
+      const fullAction = match[0];
+      const actionName = match[1];
+      const currentVersion = match[2];
+
+      const latest = this.latestVersions[actionName];
+      if (latest && this._isOutdated(currentVersion, latest)) {
+        issues.push({
+          type: 'outdated_action',
+          severity: 'low',
+          message: `Outdated action: ${actionName}@${currentVersion} (latest is ${latest})`,
+          action: actionName,
+          current: currentVersion,
+          latest: latest,
+          fix: `Update to @${latest}`,
+        });
+      }
+    }
+
+    // 3. Check for node-version (hardcoded vs matrix)
+    const rawLines = rawContent.split('\n');
+    for (let i = 0; i < rawLines.length; i++) {
+      if (rawLines[i].includes('node-version:')) {
+        const versionMatch = rawLines[i].match(/node-version:\s*['"]?(\d+)['"]?/);
+        if (versionMatch && parseInt(versionMatch[1]) < 18) {
+          issues.push({
+            type: 'old_node_version',
+            severity: 'medium',
+            message: `Using end-of-life Node.js version: ${versionMatch[1]}`,
+            line: i + 1,
+            fix: 'Upgrade to Node.js 18 or 20',
+          });
+        }
+      }
+    }
+
+    // 4. Check for caching
+    if (rawContent.includes('actions/setup-node') && !rawContent.includes('cache:')) {
+      issues.push({
+        type: 'missing_cache',
+        severity: 'high',
+        message: 'Dependency caching is not enabled in setup-node',
+        fix: 'Add cache: "npm" (or yarn/pnpm) to actions/setup-node',
+      });
+    }
+
+    return issues;
+  }
+
+  async upgrade(dryRun = false) {
+    const results = {
+      upgradedFiles: [],
+      changes: 0,
+    };
+
+    if (!fs.existsSync(this.workflowsDir)) {
+      return results;
+    }
+
+    const files = fs.readdirSync(this.workflowsDir).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'));
+
+    for (const filename of files) {
+      const filePath = path.join(this.workflowsDir, filename);
+      let content = fs.readFileSync(filePath, 'utf8');
+      let originalContent = content;
+      let fileChanges = 0;
+
+      for (const [action, latest] of Object.entries(this.latestVersions)) {
+        const regex = new RegExp(`uses:\\s*${action}@([\\w\\.]+)`, 'g');
+        content = content.replace(regex, (match, version) => {
+          if (this._isOutdated(version, latest)) {
+            fileChanges++;
+            return `uses: ${action}@${latest}`;
+          }
+          return match;
+        });
+      }
+
+      if (fileChanges > 0) {
+        if (!dryRun) {
+          fs.writeFileSync(filePath, content, 'utf8');
+        }
+        results.upgradedFiles.push({
+          filename,
+          changes: fileChanges,
+        });
+        results.changes += fileChanges;
+      }
+    }
+
+    return results;
+  }
+
+  _isOutdated(current, latest) {
+    // Simple version comparison for vX formats
+    if (current === latest) return false;
+    
+    const currNum = parseInt(current.replace('v', ''));
+    const lateNum = parseInt(latest.replace('v', ''));
+    
+    if (!isNaN(currNum) && !isNaN(lateNum)) {
+      return currNum < lateNum;
+    }
+    
+    return current !== latest; // Fallback for complex tags
+  }
+}
+
+module.exports = WorkflowAnalyzer;

package/src/config/loader.js

@@ -34,16 +34,33 @@ class ConfigLoader {
       const fullPath = path.join(this.projectPath, candidate);
       if (fs.existsSync(fullPath)) {
         try {
-          // Clear require cache so hot-reloads work in watch mode
-          delete require.cache[require.resolve(fullPath)];
-          const cfg = require(fullPath);
+          // For .js and .cjs, we can use require (with cache clearing)
+          // For .mjs, we might need a different approach, but sticking to sync require for now where possible
+          // In a real CLI, we might use dynamic import() but that's async.
+          // Since this is a CLI, we can afford a bit of hackiness or just support CommonJS primarily.
+          
+          let cfg;
+          if (candidate.endsWith('.mjs')) {
+            // Very basic support for .mjs if the environment supports it, but require usually fails.
+            // We'll try to use the fact that many environments now support require('.mjs') or just warn.
+            cfg = require(fullPath);
+          } else {
+            delete require.cache[require.resolve(fullPath)];
+            cfg = require(fullPath);
+          }
+
           // Handle both `module.exports = {}` and `export default {}`
           const resolved = cfg && cfg.__esModule ? cfg.default : cfg;
           if (resolved && typeof resolved === 'object') {
             return resolved;
           }
         } catch (err) {
-          console.warn(`[cistack] Warning: could not load ${candidate}: ${err.message}`);
+          // If it fails, it might be because it's ESM. 
+          // We don't want to crash, but we should inform the user if they have a config but it's broken.
+          console.warn(chalk.yellow(`[cistack] Warning: could not load ${candidate}: ${err.message}`));
+          if (err.message.includes('ERR_REQUIRE_ESM')) {
+            console.warn(chalk.dim(`  Tip: Try renaming ${candidate} to ${candidate.replace('.js', '.cjs')} or use CommonJS syntax.`));
+          }
         }
       }
     }
@@ -79,7 +96,7 @@ class ConfigLoader {
    * Apply config file overrides onto the full detected stack.
    *
    * @param {object} cfg          - raw cistack.config.js export
-   * @param {object} detected     - { hosting, frameworks, languages, testing }
+   * @param {object} detected     - { hosting, frameworks, languages, testing, ... }
    * @returns {object}            - merged config ready for the generator
    */
   static applyToStack(cfg, detected) {
@@ -87,24 +104,25 @@ class ConfigLoader {
 
     const result = { ...detected };
 
-    // Override primary language settings
+    // 1. Language overrides (Node version, package manager)
     if (cfg.nodeVersion && result.languages && result.languages.length > 0) {
       result.languages = result.languages.map((l, i) =>
         i === 0 && (l.name === 'JavaScript' || l.name === 'TypeScript')
-          ? { ...l, nodeVersion: String(cfg.nodeVersion) }
+          ? { ...l, nodeVersion: String(cfg.nodeVersion), manual: true }
           : l
       );
     }
 
     if (cfg.packageManager && result.languages && result.languages.length > 0) {
       result.languages = result.languages.map((l, i) =>
-        i === 0 ? { ...l, packageManager: cfg.packageManager } : l
+        i === 0 ? { ...l, packageManager: cfg.packageManager, manual: true } : l
       );
     }
 
-    // Override hosting
-    if (cfg.hosting && Array.isArray(cfg.hosting)) {
-      result.hosting = cfg.hosting.map((name) => ({
+    // 2. Hosting overrides
+    if (cfg.hosting) {
+      const hostingNames = Array.isArray(cfg.hosting) ? cfg.hosting : [cfg.hosting];
+      result.hosting = hostingNames.map((name) => ({
         name,
         confidence: 1.0,
         manual: true,
@@ -113,8 +131,30 @@ class ConfigLoader {
       }));
     }
 
+    // 3. Framework overrides
+    if (cfg.frameworks) {
+      const frameworkNames = Array.isArray(cfg.frameworks) ? cfg.frameworks : [cfg.frameworks];
+      result.frameworks = frameworkNames.map(name => ({
+        name,
+        confidence: 1.0,
+        manual: true
+      }));
+    }
+
+    // 4. Testing overrides
+    if (cfg.testing) {
+      const testNames = Array.isArray(cfg.testing) ? cfg.testing : [cfg.testing];
+      result.testing = testNames.map(name => ({
+        name,
+        confidence: 1.0,
+        manual: true,
+        type: 'unit', // default
+        command: `npm run test` // fallback
+      }));
+    }
+
     // Pass through raw extras for generators to consume
-    result._config = cfg;
+    result._config = { ...(result._config || {}), ...cfg };
 
     return result;
   }

package/src/detectors/framework.js

@@ -64,29 +64,46 @@ class FrameworkDetector {
   // ── generic JS/TS checker ─────────────────────────────────────────────────
   _check(name, depKeys, configFiles, meta = {}) {
     let confidence = 0;
+    const reasons = [];
 
     for (const dep of depKeys) {
-      if (this.deps[dep]) { confidence += 0.5; break; }
+      if (this.deps[dep]) { 
+        confidence += 0.5; 
+        reasons.push(`dependency: ${dep}`);
+        break; 
+      }
     }
     for (const cfg of configFiles) {
-      if (this.configs.has(cfg) || this.files.has(cfg)) { confidence += 0.4; break; }
+      if (this.configs.has(cfg) || this.files.has(cfg)) { 
+        confidence += 0.4; 
+        reasons.push(`config file: ${cfg}`);
+        break; 
+      }
     }
 
-    return { name, confidence: Math.min(confidence, 1), ...meta };
+    return { name, confidence: Math.min(confidence, 1), reasons, ...meta };
   }
 
   _checkPython(name, pkg, markerFile) {
     let confidence = 0;
+    const reasons = [];
     const reqFiles = ['requirements.txt', 'Pipfile', 'pyproject.toml'];
     for (const rf of reqFiles) {
       const fullPath = path.join(this.root, rf);
       if (fs.existsSync(fullPath)) {
         const content = fs.readFileSync(fullPath, 'utf8').toLowerCase();
-        if (content.includes(pkg.toLowerCase())) { confidence += 0.7; break; }
+        if (content.includes(pkg.toLowerCase())) { 
+          confidence += 0.7; 
+          reasons.push(`found ${pkg} in ${rf}`);
+          break; 
+        }
       }
     }
-    if (markerFile && this.files.has(markerFile)) confidence += 0.2;
-    return confidence > 0 ? { name, confidence: Math.min(confidence, 1), isServer: true, isPython: true } : null;
+    if (markerFile && this.files.has(markerFile)) {
+      confidence += 0.2;
+      reasons.push(`found marker file ${markerFile}`);
+    }
+    return confidence > 0 ? { name, confidence: Math.min(confidence, 1), isServer: true, isPython: true, reasons } : null;
   }
 
   _checkRuby(name, gem) {
@@ -94,20 +111,27 @@ class FrameworkDetector {
     if (!fs.existsSync(gemfilePath)) return null;
     const content = fs.readFileSync(gemfilePath, 'utf8').toLowerCase();
     const confidence = content.includes(gem.toLowerCase()) ? 0.9 : 0;
-    return confidence > 0 ? { name, confidence, isServer: true, isRuby: true } : null;
+    const reasons = confidence > 0 ? [`found ${gem} in Gemfile`] : [];
+    return confidence > 0 ? { name, confidence, isServer: true, isRuby: true, reasons } : null;
   }
 
   _checkJVM(name, keyword) {
     const gradlePath = path.join(this.root, 'build.gradle');
     const pomPath = path.join(this.root, 'pom.xml');
     let confidence = 0;
+    let foundIn = '';
     for (const p of [gradlePath, pomPath]) {
       if (fs.existsSync(p)) {
         const content = fs.readFileSync(p, 'utf8').toLowerCase();
-        if (content.includes(keyword.toLowerCase())) { confidence = 0.9; break; }
+        if (content.includes(keyword.toLowerCase())) { 
+          confidence = 0.9; 
+          foundIn = path.basename(p);
+          break; 
+        }
       }
     }
-    return confidence > 0 ? { name, confidence, isServer: true, isJVM: true } : null;
+    const reasons = confidence > 0 ? [`found ${keyword} in ${foundIn}`] : [];
+    return confidence > 0 ? { name, confidence, isServer: true, isJVM: true, reasons } : null;
   }
 
   _checkComposer(name, pkg) {
@@ -117,20 +141,21 @@ class FrameworkDetector {
       const composer = JSON.parse(fs.readFileSync(composerPath, 'utf8'));
       const allDeps = { ...(composer.require || {}), ...(composer['require-dev'] || {}) };
       const confidence = allDeps[pkg] ? 0.9 : 0;
-      return confidence > 0 ? { name, confidence, isServer: true, isPHP: true } : null;
+      const reasons = confidence > 0 ? [`found ${pkg} in composer.json`] : [];
+      return confidence > 0 ? { name, confidence, isServer: true, isPHP: true, reasons } : null;
     } catch (_) { return null; }
   }
 
   _checkGo(name) {
     const goMod = path.join(this.root, 'go.mod');
     if (!fs.existsSync(goMod)) return null;
-    return { name, confidence: 0.9, isServer: true, isGo: true };
+    return { name, confidence: 0.9, isServer: true, isGo: true, reasons: ['go.mod found'] };
   }
 
   _checkRust(name) {
     const cargoToml = path.join(this.root, 'Cargo.toml');
     if (!fs.existsSync(cargoToml)) return null;
-    return { name, confidence: 0.9, isServer: true, isRust: true };
+    return { name, confidence: 0.9, isServer: true, isRust: true, reasons: ['Cargo.toml found'] };
   }
 }
 

package/src/detectors/hosting.js

@@ -60,13 +60,13 @@ class HostingDetector {
 
   _checkFirebase() {
     let confidence = 0;
-    const notes = [];
+    const reasons = [];
 
-    if (this.configs.has('firebase.json')) { confidence += 0.6; notes.push('firebase.json found'); }
-    if (this.configs.has('.firebaserc')) { confidence += 0.3; notes.push('.firebaserc found'); }
-    if (this.deps['firebase-tools'] || this.deps['firebase']) { confidence += 0.2; notes.push('firebase dep'); }
-    if (Object.values(this.scripts).some((s) => s.includes('firebase deploy'))) { confidence += 0.3; notes.push('deploy script'); }
-    if (this.info.srcStructure.hasFunctions) { confidence += 0.1; }
+    if (this.configs.has('firebase.json')) { confidence += 0.6; reasons.push('firebase.json found'); }
+    if (this.configs.has('.firebaserc')) { confidence += 0.3; reasons.push('.firebaserc found'); }
+    if (this.deps['firebase-tools'] || this.deps['firebase']) { confidence += 0.2; reasons.push('firebase dependency found'); }
+    if (Object.values(this.scripts).some((s) => s.includes('firebase deploy'))) { confidence += 0.3; reasons.push('firebase deploy script found'); }
+    if (this.info.srcStructure.hasFunctions) { confidence += 0.1; reasons.push('functions directory found'); }
 
     // Detect what Firebase services are used
     let deployTarget = 'hosting';
@@ -85,38 +85,38 @@ class HostingDetector {
       confidence: Math.min(confidence, 1),
       deployCommand: `firebase deploy --only ${deployTarget}`,
       secrets: ['FIREBASE_TOKEN'],
-      notes,
+      reasons,
       buildStep: this._detectBuildScript(),
     };
   }
 
   _checkVercel() {
     let confidence = 0;
-    const notes = [];
+    const reasons = [];
 
-    if (this.configs.has('vercel.json')) { confidence += 0.7; notes.push('vercel.json found'); }
-    if (this.configs.has('.vercel')) { confidence += 0.4; notes.push('.vercel dir found'); }
-    if (this.deps['vercel']) { confidence += 0.3; notes.push('vercel dep'); }
-    if (Object.values(this.scripts).some((s) => s.includes('vercel'))) { confidence += 0.3; notes.push('vercel script'); }
+    if (this.configs.has('vercel.json')) { confidence += 0.7; reasons.push('vercel.json found'); }
+    if (this.configs.has('.vercel')) { confidence += 0.4; reasons.push('.vercel directory found'); }
+    if (this.deps['vercel']) { confidence += 0.3; reasons.push('vercel dependency found'); }
+    if (Object.values(this.scripts).some((s) => s.includes('vercel'))) { confidence += 0.3; reasons.push('vercel script found'); }
 
     return {
       name: 'Vercel',
       confidence: Math.min(confidence, 1),
       deployCommand: 'vercel --prod --token $VERCEL_TOKEN',
       secrets: ['VERCEL_TOKEN', 'VERCEL_ORG_ID', 'VERCEL_PROJECT_ID'],
-      notes,
+      reasons,
       buildStep: this._detectBuildScript(),
     };
   }
 
   _checkNetlify() {
     let confidence = 0;
-    const notes = [];
+    const reasons = [];
 
-    if (this.configs.has('netlify.toml')) { confidence += 0.7; notes.push('netlify.toml found'); }
-    if (this.configs.has('_redirects')) { confidence += 0.2; notes.push('_redirects found'); }
-    if (this.deps['netlify-cli'] || this.deps['netlify']) { confidence += 0.3; notes.push('netlify dep'); }
-    if (Object.values(this.scripts).some((s) => s.includes('netlify'))) { confidence += 0.3; notes.push('netlify script'); }
+    if (this.configs.has('netlify.toml')) { confidence += 0.7; reasons.push('netlify.toml found'); }
+    if (this.configs.has('_redirects')) { confidence += 0.2; reasons.push('_redirects file found'); }
+    if (this.deps['netlify-cli'] || this.deps['netlify']) { confidence += 0.3; reasons.push('netlify dependency found'); }
+    if (Object.values(this.scripts).some((s) => s.includes('netlify'))) { confidence += 0.3; reasons.push('netlify script found'); }
 
     let publishDir = 'dist';
     try {
@@ -130,7 +130,7 @@ class HostingDetector {
       confidence: Math.min(confidence, 1),
       deployCommand: `netlify deploy --prod --dir=${publishDir}`,
       secrets: ['NETLIFY_AUTH_TOKEN', 'NETLIFY_SITE_ID'],
-      notes,
+      reasons,
       publishDir,
       buildStep: this._detectBuildScript(),
     };
@@ -138,110 +138,118 @@ class HostingDetector {
 
   _checkRender() {
     let confidence = 0;
-    if (this.configs.has('render.yaml')) { confidence += 0.8; }
+    const reasons = [];
+    if (this.configs.has('render.yaml')) { confidence += 0.8; reasons.push('render.yaml detected'); }
     return {
       name: 'Render',
       confidence,
       deployCommand: 'curl -X POST $RENDER_DEPLOY_HOOK_URL',
       secrets: ['RENDER_DEPLOY_HOOK_URL'],
-      notes: ['render.yaml detected'],
+      reasons,
     };
   }
 
   _checkRailway() {
     let confidence = 0;
-    if (this.configs.has('railway.json') || this.configs.has('railway.toml')) confidence += 0.8;
-    if (this.deps['@railway/cli']) confidence += 0.2;
+    const reasons = [];
+    if (this.configs.has('railway.json') || this.configs.has('railway.toml')) { confidence += 0.8; reasons.push('railway config found'); }
+    if (this.deps['@railway/cli']) { confidence += 0.2; reasons.push('railway cli dependency found'); }
     return {
       name: 'Railway',
       confidence,
       deployCommand: 'railway up',
       secrets: ['RAILWAY_TOKEN'],
-      notes: [],
+      reasons,
     };
   }
 
   _checkHeroku() {
     let confidence = 0;
-    if (this.configs.has('Procfile')) { confidence += 0.5; }
-    if (this.configs.has('heroku.yml')) { confidence += 0.5; }
-    if (this.deps['heroku']) { confidence += 0.2; }
+    const reasons = [];
+    if (this.configs.has('Procfile')) { confidence += 0.5; reasons.push('Procfile found'); }
+    if (this.configs.has('heroku.yml')) { confidence += 0.5; reasons.push('heroku.yml found'); }
+    if (this.deps['heroku']) { confidence += 0.2; reasons.push('heroku dependency found'); }
     return {
       name: 'Heroku',
       confidence,
       deployCommand: 'git push heroku main',
       secrets: ['HEROKU_API_KEY', 'HEROKU_APP_NAME'],
-      notes: [],
+      reasons,
     };
   }
 
   _checkGCPAppEngine() {
     let confidence = 0;
-    if (this.configs.has('app.yaml')) { confidence += 0.7; }
-    if (this.deps['@google-cloud/functions-framework']) confidence += 0.2;
+    const reasons = [];
+    if (this.configs.has('app.yaml')) { confidence += 0.7; reasons.push('app.yaml detected'); }
+    if (this.deps['@google-cloud/functions-framework']) { confidence += 0.2; reasons.push('gcp functions framework found'); }
     return {
       name: 'GCP App Engine',
       confidence,
       deployCommand: 'gcloud app deploy',
       secrets: ['GCP_PROJECT_ID', 'GCP_SA_KEY'],
-      notes: [],
+      reasons,
     };
   }
 
   _checkAWS() {
     let confidence = 0;
-    if (this.configs.has('appspec.yml')) confidence += 0.5;
-    if (this.configs.has('serverless.yml') || this.configs.has('serverless.yaml')) confidence += 0.6;
-    if (this.configs.has('cdk.json')) confidence += 0.4;
-    if (this.deps['aws-sdk'] || this.deps['@aws-sdk/client-s3']) confidence += 0.15;
+    const reasons = [];
+    if (this.configs.has('appspec.yml')) { confidence += 0.5; reasons.push('appspec.yml found'); }
+    if (this.configs.has('serverless.yml') || this.configs.has('serverless.yaml')) { confidence += 0.6; reasons.push('serverless.yml found'); }
+    if (this.configs.has('cdk.json')) { confidence += 0.4; reasons.push('cdk.json found'); }
+    if (this.deps['aws-sdk'] || this.deps['@aws-sdk/client-s3']) { confidence += 0.15; reasons.push('aws-sdk found'); }
     return {
       name: 'AWS',
       confidence: Math.min(confidence, 1),
       deployCommand: 'aws s3 sync ./dist s3://$AWS_S3_BUCKET --delete',
       secrets: ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION'],
-      notes: [],
+      reasons,
     };
   }
 
   _checkAzure() {
     let confidence = 0;
-    if (this.files.has('.azure/pipelines.yml')) confidence += 0.5;
-    if (this.deps['@azure/core-http']) confidence += 0.2;
+    const reasons = [];
+    if (this.files.has('.azure/pipelines.yml')) { confidence += 0.5; reasons.push('.azure/pipelines.yml found'); }
+    if (this.deps['@azure/core-http']) { confidence += 0.2; reasons.push('azure core-http found'); }
     return {
       name: 'Azure',
       confidence,
       deployCommand: 'az webapp up',
       secrets: ['AZURE_CREDENTIALS'],
-      notes: [],
+      reasons,
     };
   }
 
   _checkGitHubPages() {
     let confidence = 0;
+    const reasons = [];
     const pkgHomepage = this.pkg.homepage || '';
-    if (pkgHomepage.includes('github.io')) { confidence += 0.6; }
-    if (this.deps['gh-pages']) { confidence += 0.4; }
-    if (Object.values(this.scripts).some((s) => s.includes('gh-pages'))) confidence += 0.3;
+    if (pkgHomepage.includes('github.io')) { confidence += 0.6; reasons.push('homepage contains github.io'); }
+    if (this.deps['gh-pages']) { confidence += 0.4; reasons.push('gh-pages dependency found'); }
+    if (Object.values(this.scripts).some((s) => s.includes('gh-pages'))) { confidence += 0.3; reasons.push('gh-pages script found'); }
     return {
       name: 'GitHub Pages',
       confidence: Math.min(confidence, 1),
       deployCommand: null, // handled by actions/deploy-pages
       secrets: [],
-      notes: [],
+      reasons,
       buildStep: this._detectBuildScript(),
     };
   }
 
   _checkDocker() {
     let confidence = 0;
-    if (this.configs.has('Dockerfile')) confidence += 0.5;
-    if (this.configs.has('docker-compose.yml') || this.configs.has('docker-compose.yaml')) confidence += 0.3;
+    const reasons = [];
+    if (this.configs.has('Dockerfile')) { confidence += 0.5; reasons.push('Dockerfile found'); }
+    if (this.configs.has('docker-compose.yml') || this.configs.has('docker-compose.yaml')) { confidence += 0.3; reasons.push('docker-compose.yml found'); }
     return {
       name: 'Docker',
       confidence,
       deployCommand: 'docker push $DOCKER_IMAGE',
       secrets: ['DOCKER_USERNAME', 'DOCKER_PASSWORD'],
-      notes: [],
+      reasons,
     };
   }
 

package/src/generators/workflow.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const yaml = require('js-yaml');
+const { version } = require('../../package.json');
+
 
 /**
  * Takes all detected signals and produces one or more complete GitHub Actions workflow YAML files.
@@ -190,7 +192,7 @@ class WorkflowGenerator {
 
     const envComment = this._envComment();
     const header =
-      `# Generated by cistack v2.0.0 — https://github.com/cistack\n` +
+      `# Generated by cistack v${version} — https://github.com/cistack\n` +
       `# CI Pipeline: lint → test → build${this.e2eTests.length > 0 ? ' → e2e' : ''}\n` +
       envComment +
       `\n`;
@@ -266,7 +268,7 @@ class WorkflowGenerator {
 
     return this._toYaml(
       workflow,
-      '# Generated by cistack v2.0.0 — https://github.com/cistack\n# Monorepo CI — matrix over all workspaces\n\n'
+      `# Generated by cistack v${version} — https://github.com/cistack\n# Monorepo CI — matrix over all workspaces\n\n`
     );
   }
 
@@ -277,7 +279,6 @@ class WorkflowGenerator {
   _buildDeployWorkflow() {
     const h = this.primaryHosting;
     const lang = this.primaryLang;
-
     const branches = this.extraConfig.branches || ['main', 'master'];
 
     const preDeploySteps = [
@@ -286,17 +287,30 @@ class WorkflowGenerator {
       this._stepInstallDeps(lang),
     ].filter(Boolean);
 
-    const deploySteps = this._hostingDeploySteps(h, lang);
+    const deploySteps = this._hostingDeploySteps(h, lang, false); // production
+    const previewSteps = this._hostingDeploySteps(h, lang, true);  // preview
 
     const jobs = {
       deploy: {
-        name: `🚀 Deploy → ${h.name}`,
+        name: `🚀 Deploy → ${h.name} (Production)`,
+        if: "github.event_name == 'push' || github.event_name == 'workflow_dispatch'",
         'runs-on': 'ubuntu-latest',
         environment: 'production',
         steps: [...preDeploySteps, ...deploySteps].filter(Boolean),
       },
     };
 
+    // Add preview job if supported
+    if (previewSteps.length > 0) {
+      jobs.preview = {
+        name: `✨ Deploy → ${h.name} (Preview)`,
+        if: "github.event_name == 'pull_request'",
+        'runs-on': 'ubuntu-latest',
+        environment: 'preview',
+        steps: [...preDeploySteps, ...previewSteps].filter(Boolean),
+      };
+    }
+
     const allSecrets = [
       ...(h.secrets || []),
       ...this.envVars.secrets,
@@ -313,6 +327,7 @@ class WorkflowGenerator {
       name: `Deploy to ${h.name}`,
       on: {
         push: { branches: branches.filter((b) => b !== 'develop') },
+        pull_request: { branches },
         workflow_dispatch: {},
       },
       jobs,
@@ -320,7 +335,7 @@ class WorkflowGenerator {
 
     return this._toYaml(
       workflow,
-      `# Generated by cistack v2.0.0\n# Deploy Pipeline → ${h.name}\n${secretsDoc}${envComment}\n`
+      `# Generated by cistack v${version}\n# Deploy Pipeline → ${h.name}\n${secretsDoc}${envComment}\n`
     );
   }
 
@@ -398,7 +413,7 @@ class WorkflowGenerator {
       },
     };
 
-    return this._toYaml(workflow, '# Generated by cistack v2.0.0\n# Docker image build and push to GHCR\n\n');
+    return this._toYaml(workflow, `# Generated by cistack v${version}\n# Docker image build and push to GHCR\n\n`);
   }
 
   // ══════════════════════════════════════════════════════════════════════════
@@ -470,7 +485,7 @@ class WorkflowGenerator {
       },
     };
 
-    return this._toYaml(workflow, '# Generated by cistack v2.0.0\n# Security: dependency audit + CodeQL analysis (runs weekly)\n\n');
+    return this._toYaml(workflow, `# Generated by cistack v${version}\n# Security: dependency audit + CodeQL analysis (runs weekly)\n\n`);
   }
 
   // ══════════════════════════════════════════════════════════════════════════
@@ -499,8 +514,8 @@ class WorkflowGenerator {
         uses: 'actions/setup-node@v4',
         with: {
           'node-version': lang.nodeVersion || '20',
-          // setup-node handles npm/yarn/pnpm caching natively
-          cache: lang.packageManager === 'yarn' ? 'yarn' : lang.packageManager === 'pnpm' ? 'pnpm' : 'npm',
+          // Use native caching in setup-node
+          cache: cacheOverride.npm !== false ? (lang.packageManager === 'yarn' ? 'yarn' : lang.packageManager === 'pnpm' ? 'pnpm' : 'npm') : undefined,
         },
       });
     }
@@ -510,35 +525,12 @@ class WorkflowGenerator {
       steps.push({
         name: 'Set up Python',
         uses: 'actions/setup-python@v5',
-        with: { 'python-version': '3.x' },
+        with: { 
+          'python-version': '3.x',
+          // Native caching for pip/poetry
+          cache: cacheOverride.pip !== false ? (lang.packageManager === 'poetry' ? 'poetry' : 'pip') : undefined
+        },
       });
-
-      if (cacheOverride.pip !== false) {
-        if (lang.packageManager === 'poetry') {
-          steps.push({
-            name: 'Cache Poetry virtualenv',
-            uses: 'actions/cache@v4',
-            with: {
-              path: [
-                '~/.cache/pypoetry',
-                '~/.local/share/pypoetry',
-              ].join('\n'),
-              key: "${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}",
-              'restore-keys': '${{ runner.os }}-poetry-',
-            },
-          });
-        } else {
-          steps.push({
-            name: 'Cache pip',
-            uses: 'actions/cache@v4',
-            with: {
-              path: '~/.cache/pip',
-              key: "${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}",
-              'restore-keys': '${{ runner.os }}-pip-',
-            },
-          });
-        }
-      }
     }
 
     // ── Go ───────────────────────────────────────────────────────────────
@@ -546,20 +538,11 @@ class WorkflowGenerator {
       steps.push({
         name: 'Set up Go',
         uses: 'actions/setup-go@v5',
-        with: { 'go-version': 'stable', cache: true },
+        with: { 
+          'go-version': 'stable', 
+          cache: cacheOverride.go !== false 
+        },
       });
-      // setup-go has built-in module cache; add explicit one for Go pkg mod
-      if (cacheOverride.go !== false) {
-        steps.push({
-          name: 'Cache Go modules',
-          uses: 'actions/cache@v4',
-          with: {
-            path: '~/go/pkg/mod',
-            key: "${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}",
-            'restore-keys': '${{ runner.os }}-go-',
-          },
-        });
-      }
     }
 
     // ── Java / Kotlin ─────────────────────────────────────────────────────
@@ -567,35 +550,13 @@ class WorkflowGenerator {
       steps.push({
         name: 'Set up JDK',
         uses: 'actions/setup-java@v4',
-        with: { 'java-version': '21', distribution: 'temurin' },
+        with: { 
+          'java-version': '21', 
+          distribution: 'temurin',
+          // Native caching for maven/gradle
+          cache: cacheOverride.maven !== false ? (lang.packageManager === 'gradle' ? 'gradle' : 'maven') : undefined
+        },
       });
-
-      if (lang.packageManager === 'maven' && cacheOverride.maven !== false) {
-        steps.push({
-          name: 'Cache Maven repository',
-          uses: 'actions/cache@v4',
-          with: {
-            path: '~/.m2',
-            key: "${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}",
-            'restore-keys': '${{ runner.os }}-m2-',
-          },
-        });
-      }
-
-      if (lang.packageManager === 'gradle' && cacheOverride.gradle !== false) {
-        steps.push({
-          name: 'Cache Gradle packages',
-          uses: 'actions/cache@v4',
-          with: {
-            path: [
-              '~/.gradle/caches',
-              '~/.gradle/wrapper',
-            ].join('\n'),
-            key: "${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}",
-            'restore-keys': '${{ runner.os }}-gradle-',
-          },
-        });
-      }
     }
 
     // ── Ruby ─────────────────────────────────────────────────────────────
@@ -603,9 +564,8 @@ class WorkflowGenerator {
       steps.push({
         name: 'Set up Ruby',
         uses: 'ruby/setup-ruby@v1',
-        with: { 'bundler-cache': true },
+        with: { 'bundler-cache': cacheOverride.bundler !== false },
       });
-      // setup-ruby already handles bundler cache via bundler-cache: true
     }
 
     // ── Rust ─────────────────────────────────────────────────────────────
@@ -754,7 +714,7 @@ class WorkflowGenerator {
   // Hosting-specific deploy steps
   // ══════════════════════════════════════════════════════════════════════════
 
-  _hostingDeploySteps(h, lang) {
+  _hostingDeploySteps(h, lang, isPreview = false) {
     const steps = [];
     const buildScript = this._findScript(['build', 'build:prod']);
     const pm = lang.packageManager || 'npm';
@@ -766,23 +726,24 @@ class WorkflowGenerator {
           steps.push({ name: 'Build', run: runCmd(buildScript), env: { NODE_ENV: 'production' } });
         }
         steps.push({
-          name: 'Deploy to Firebase',
+          name: isPreview ? 'Deploy Preview' : 'Deploy to Firebase',
           uses: 'FirebaseExtended/action-hosting-deploy@v0',
           with: {
             repoToken: '${{ secrets.GITHUB_TOKEN }}',
             firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}',
-            channelId: 'live',
+            channelId: isPreview ? 'preview-${{ github.event.number }}' : 'live',
           },
         });
         break;
       }
 
       case 'Vercel': {
+        const prodFlag = isPreview ? '' : '--prod';
         steps.push(
           { name: 'Install Vercel CLI', run: 'npm install -g vercel' },
-          { name: 'Pull Vercel environment', run: 'vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}' },
-          { name: 'Build project', run: 'vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}' },
-          { name: 'Deploy to Vercel', run: 'vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}' },
+          { name: 'Pull Vercel environment', run: `vercel pull --yes --environment=${isPreview ? 'preview' : 'production'} --token=\${{ secrets.VERCEL_TOKEN }}` },
+          { name: 'Build project', run: `vercel build ${prodFlag} --token=\${{ secrets.VERCEL_TOKEN }}` },
+          { name: 'Deploy to Vercel', run: `vercel deploy --prebuilt ${prodFlag} --token=\${{ secrets.VERCEL_TOKEN }}` },
         );
         break;
       }
@@ -792,15 +753,17 @@ class WorkflowGenerator {
           steps.push({ name: 'Build', run: runCmd(buildScript), env: { NODE_ENV: 'production' } });
         }
         steps.push({
-          name: 'Deploy to Netlify',
+          name: isPreview ? 'Deploy Preview' : 'Deploy to Netlify',
           uses: 'nwtgck/actions-netlify@v3.0',
           with: {
             'publish-dir': h.publishDir || 'dist',
             'production-branch': 'main',
             'github-token': '${{ secrets.GITHUB_TOKEN }}',
-            'deploy-message': 'Deploy from GitHub Actions – ${{ github.sha }}',
+            'deploy-message': isPreview ? 'Preview Deploy – ${{ github.event.number }}' : 'Production Deploy – ${{ github.sha }}',
             'enable-pull-request-comment': true,
             'enable-commit-comment': true,
+            'production-deploy': !isPreview,
+            alias: isPreview ? 'preview-${{ github.event.number }}' : undefined,
           },
           env: {
             NETLIFY_AUTH_TOKEN: '${{ secrets.NETLIFY_AUTH_TOKEN }}',

package/src/index.js

@@ -20,6 +20,8 @@ const ReleaseGenerator  = require('./generators/release');
 const ConfigLoader      = require('./config/loader');
 const { ensureDir, writeFile, banner, smartMergeWorkflow } = require('./utils/helpers');
 
+const WorkflowAnalyzer = require('./analyzers/workflow');
+
 class CIFlow {
   constructor(options) {
     this.options = options;
@@ -29,6 +31,7 @@ class CIFlow {
     this.force     = options.force   || false;
     this.prompt    = options.prompt  !== false;
     this.verbose   = options.verbose || false;
+    this.explain   = options.explain || false;
   }
 
   async run() {
@@ -129,19 +132,100 @@ class CIFlow {
     }
   }
 
+  async audit() {
+    banner();
+    const spinner = ora({ text: 'Auditing existing workflows...', color: 'cyan' }).start();
+    
+    try {
+      const analyzer = new WorkflowAnalyzer(this.projectPath);
+      const results = await analyzer.audit();
+      spinner.succeed(chalk.green('Audit complete'));
+
+      if (results.files.length === 0) {
+        console.log(chalk.yellow('\nNo workflow files found to audit.'));
+        return;
+      }
+
+      console.log('\n' + chalk.bold('🔍 Workflow Audit Results'));
+      console.log(chalk.dim('─'.repeat(48)));
+
+      for (const file of results.files) {
+        if (file.error) {
+          console.log(`\n📄 ${chalk.red(file.filename)} – ${chalk.red(file.error)}`);
+          continue;
+        }
+
+        console.log(`\n📄 ${chalk.cyan(file.filename)} – ${file.issues.length > 0 ? chalk.yellow(file.issues.length + ' issues found') : chalk.green('Excellent')}`);
+        
+        for (const issue of file.issues) {
+          const color = issue.severity === 'high' ? chalk.red : issue.severity === 'medium' ? chalk.yellow : chalk.dim;
+          console.log(`  ${color('•')} ${issue.message}`);
+          console.log(`    ${chalk.dim('Fix:')} ${chalk.italic(issue.fix)}`);
+        }
+      }
+
+      if (results.totalIssues > 0) {
+        console.log('\n' + chalk.yellow(`💡 Run ${chalk.bold('cistack upgrade')} to automatically fix outdated actions.`));
+      } else {
+        console.log('\n' + chalk.green('✅  Your workflows are up to date and follow best practices.'));
+      }
+      console.log('');
+    } catch (err) {
+      spinner.fail(chalk.red('Audit failed: ' + err.message));
+      process.exit(1);
+    }
+  }
+
+  async upgrade() {
+    banner();
+    const spinner = ora({ text: 'Upgrading actions...', color: 'cyan' }).start();
+    
+    try {
+      const analyzer = new WorkflowAnalyzer(this.projectPath);
+      const results = await analyzer.upgrade(this.dryRun);
+      
+      if (results.changes === 0) {
+        spinner.succeed(chalk.green('All actions are already up to date.'));
+        return;
+      }
+
+      spinner.succeed(chalk.green(`Upgraded ${results.changes} action(s) across ${results.upgradedFiles.length} file(s)`));
+      
+      if (this.dryRun) {
+        console.log(chalk.yellow('\n── DRY RUN – files not modified ──'));
+      }
+
+      for (const file of results.upgradedFiles) {
+        console.log(`  ${chalk.green('✔')} ${file.filename} (${file.changes} changes)`);
+      }
+      console.log('');
+    } catch (err) {
+      spinner.fail(chalk.red('Upgrade failed: ' + err.message));
+      process.exit(1);
+    }
+  }
+
   // ── helpers ──────────────────────────────────────────────────────────────
 
-  _printSummary({ hosting, frameworks, languages, testing }, releaseInfo, envVars, monorepoPackages) {
-    const line = (label, value) =>
+  _printSummary(config, releaseInfo, envVars, monorepoPackages) {
+    const { hosting, frameworks, languages, testing } = config;
+    const line = (label, value, reasons = []) => {
       console.log(`  ${chalk.dim(label.padEnd(20))} ${chalk.cyan(value || chalk.italic('none detected'))}`);
+      if (this.explain && reasons && reasons.length > 0) {
+        for (const reason of reasons) {
+          console.log(`    ${chalk.dim('↳')} ${chalk.italic.gray(reason)}`);
+        }
+      }
+    };
 
     console.log('\n' + chalk.bold('  📊 Detected Stack'));
     console.log(chalk.dim('  ' + '─'.repeat(48)));
-    line('Languages:',   languages.map((l) => l.name).join(', '));
-    line('Frameworks:',  frameworks.map((f) => f.name).join(', '));
-    line('Hosting:',     hosting.map((h) => h.name).join(', ') || 'none');
-    line('Testing:',     testing.map((t) => t.name).join(', ')  || 'none');
-    line('Release tool:', releaseInfo ? releaseInfo.tool : 'none');
+    
+    line('Languages:',   languages.map((l) => l.name).join(', '), languages[0] && languages[0].reasons);
+    line('Frameworks:',  frameworks.map((f) => f.name).join(', '), frameworks[0] && frameworks[0].reasons);
+    line('Hosting:',     hosting.map((h) => h.name).join(', ') || 'none', hosting[0] && hosting[0].reasons);
+    line('Testing:',     testing.map((t) => t.name).join(', ')  || 'none', testing[0] && testing[0].reasons);
+    line('Release tool:', releaseInfo ? releaseInfo.tool : 'none', releaseInfo && releaseInfo.reasons);
 
     if (monorepoPackages.length > 0) {
       line('Monorepo pkgs:', monorepoPackages.map((p) => p.name).join(', '));

package/src/utils/helpers.js

@@ -5,6 +5,8 @@ const path = require('path');
 const chalk = require('chalk');
 const yaml = require('js-yaml');
 
+const { version } = require('../../package.json');
+
 function ensureDir(dirPath) {
   if (!fs.existsSync(dirPath)) {
     fs.mkdirSync(dirPath, { recursive: true });
@@ -17,16 +19,8 @@ function writeFile(filePath, content) {
 }
 
 function banner() {
-  console.log('\n' + chalk.bold.cyan('  ██████╗██╗███████╗████████╗ █████╗  ██████╗██╗  ██╗'));
-  console.log(chalk.bold.cyan('  ██╔════╝██║██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝'));
-  console.log(chalk.bold.cyan('  ██║     ██║███████╗   ██║   ███████║██║     █████╔╝ '));
-  console.log(chalk.bold.cyan('  ██║     ██║╚════██║   ██║   ██╔══██║██║     ██╔═██╗ '));
-  console.log(chalk.bold.cyan('  ╚██████╗██║███████║   ██║   ██║  ██║╚██████╗██║  ██╗'));
-  console.log(chalk.bold.cyan('   ╚═════╝╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝'));
-  console.log('');
-  console.log('  ' + chalk.dim('GitHub Actions pipeline generator  ') + chalk.bold.cyan('v2.0.0'));
-  console.log('  ' + chalk.dim('─'.repeat(52)));
-  console.log('');
+  console.log('\n' + chalk.bold.cyan('  cistack ') + chalk.dim('v' + version));
+  console.log(chalk.dim('  ' + '─'.repeat(24)) + '\n');
 }
 
 /**