cistack 1.0.0 → 3.0.0

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

@@ -9,7 +9,7 @@ const CIFlow = require('../src/index');
 program
   .name('cistack')
   .description('Generate GitHub Actions CI/CD pipelines by analysing your codebase')
-  .version('1.0.0');
+  .version('2.0.0');
 
 program
   .command('generate', { isDefault: true })
@@ -17,19 +17,103 @@ program
   .option('-p, --path <dir>', 'Path to the project root', process.cwd())
   .option('-o, --output <dir>', 'Output directory for workflow files', '.github/workflows')
   .option('--dry-run', 'Print the generated YAML without writing files')
-  .option('--force', 'Overwrite existing workflow files without prompting')
+  .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),
-      outputDir: options.output,
-      dryRun: options.dryRun,
-      force: options.force,
-      prompt: options.prompt,
-      verbose: options.verbose,
+      outputDir:   options.output,
+      dryRun:      options.dryRun,
+      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) => {
+    const fs = require('fs');
+    const resolvedPath = path.resolve(options.path);
+    const configPath = path.join(resolvedPath, 'cistack.config.js');
+
+    // Ensure the target directory exists
+    if (!fs.existsSync(resolvedPath)) {
+      fs.mkdirSync(resolvedPath, { recursive: true });
+    }
+
+    if (fs.existsSync(configPath)) {
+      console.error('cistack.config.js already exists. Delete it first or edit it manually.');
+      process.exit(1);
+    }
+
+    const template = `// cistack.config.js
+// Override auto-detected settings for this project.
+// All fields are optional — omit what you don't need.
+
+/** @type {import('cistack').Config} */
+module.exports = {
+  // nodeVersion: '20',          // Override detected Node.js version
+  // packageManager: 'pnpm',    // 'npm' | 'yarn' | 'pnpm' | 'bun'
+  // hosting: ['Firebase'],      // Force a specific hosting provider
+  // branches: ['main', 'staging'], // CI branches (default: main, master, develop)
+  // outputDir: '.github/workflows', // Where to write workflow files
+
+  // cache: {
+  //   npm: true,     // enabled by default
+  //   pip: true,
+  //   cargo: true,
+  //   maven: true,
+  //   gradle: true,
+  //   go: true,
+  //   composer: true,
+  // },
+
+  // monorepo: {
+  //   perPackage: true, // Generate one ci-<name>.yml per workspace
+  // },
+
+  // release: {
+  //   tool: 'semantic-release', // override release tool detection
+  // },
+
+  // secrets: ['MY_EXTRA_SECRET'], // Document additional secrets in workflow comments
+};
+`;
+
+    fs.writeFileSync(configPath, template, 'utf8');
+    const chalk = require('chalk');
+    console.log(chalk.green(`✔ Created cistack.config.js at ${configPath}`));
+    console.log(chalk.dim('  Edit the file to override detected settings.'));
+  });
+
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cistack",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "Automatically generate GitHub Actions CI/CD pipelines by analysing your codebase",
   "main": "src/index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/ciflow.js",
-    "test": "node bin/ciflow.js --dry-run"
+    "test": "node bin/ciflow.js --dry-run --no-prompt"
   },
   "keywords": [
     "github-actions",
@@ -18,7 +18,14 @@
     "devops",
     "firebase",
     "vercel",
-    "netlify"
+    "netlify",
+    "monorepo",
+    "dependabot",
+    "semantic-release",
+    "changesets",
+    "caching",
+    "turborepo",
+    "nx"
   ],
   "author": "",
   "license": "MIT",

package/src/analyzers/monorepo.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { globSync } = require('glob');
+
+/**
+ * Resolves workspace packages from monorepo config files.
+ *
+ * Supported:
+ *   - package.json#workspaces (npm/yarn workspaces array or { packages: [] })
+ *   - pnpm-workspace.yaml
+ *   - turbo.json  (uses package.json workspaces in conjunction)
+ *   - nx.json     (discovers apps/* and libs/*)
+ *   - lerna.json  (uses lerna packages array)
+ *
+ * Returns: Array<{ name: string, relativePath: string, absolutePath: string, packageJson: object|null }>
+ */
+class MonorepoAnalyzer {
+  constructor(projectPath, codebaseInfo) {
+    this.root = projectPath;
+    this.info = codebaseInfo;
+    this.pkg = codebaseInfo.packageJson || {};
+  }
+
+  async analyze() {
+    if (!this.info.hasMonorepo) return [];
+
+    const workspaceGlobs = this._collectWorkspaceGlobs();
+    if (workspaceGlobs.length === 0) return [];
+
+    const packages = [];
+    const seen = new Set();
+
+    for (const pattern of workspaceGlobs) {
+      // Each glob glob like 'packages/*' → expand to actual dirs
+      const matches = globSync(pattern, {
+        cwd: this.root,
+        onlyDirectories: true,
+        absolute: false,
+        ignore: ['node_modules/**', '**/node_modules/**'],
+      });
+
+      for (const relDir of matches) {
+        if (seen.has(relDir)) continue;
+        seen.add(relDir);
+
+        const absPath = path.join(this.root, relDir);
+        const pkgJsonPath = path.join(absPath, 'package.json');
+        let pkgJson = null;
+
+        if (fs.existsSync(pkgJsonPath)) {
+          try {
+            pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+          } catch (_) {}
+        }
+
+        const name = (pkgJson && pkgJson.name) || path.basename(relDir);
+
+        packages.push({
+          name,
+          relativePath: relDir,
+          absolutePath: absPath,
+          packageJson: pkgJson,
+        });
+      }
+    }
+
+    return packages;
+  }
+
+  _collectWorkspaceGlobs() {
+    const globs = [];
+
+    // 1. package.json workspaces
+    if (this.pkg.workspaces) {
+      const ws = this.pkg.workspaces;
+      if (Array.isArray(ws)) {
+        globs.push(...ws);
+      } else if (ws.packages) {
+        globs.push(...ws.packages);
+      }
+    }
+
+    // 2. pnpm-workspace.yaml
+    const pnpmWsPath = path.join(this.root, 'pnpm-workspace.yaml');
+    if (fs.existsSync(pnpmWsPath)) {
+      try {
+        const yaml = require('js-yaml');
+        const parsed = yaml.load(fs.readFileSync(pnpmWsPath, 'utf8'));
+        if (parsed && parsed.packages) {
+          globs.push(...parsed.packages);
+        }
+      } catch (_) {}
+    }
+
+    // 3. lerna.json
+    const lernaPath = path.join(this.root, 'lerna.json');
+    if (fs.existsSync(lernaPath)) {
+      try {
+        const lerna = JSON.parse(fs.readFileSync(lernaPath, 'utf8'));
+        if (lerna.packages) globs.push(...lerna.packages);
+      } catch (_) {}
+    }
+
+    // 4. nx.json — default convention: apps/* + libs/*
+    const nxPath = path.join(this.root, 'nx.json');
+    if (fs.existsSync(nxPath) && globs.length === 0) {
+      globs.push('apps/*', 'libs/*', 'packages/*');
+    }
+
+    // 5. turbo.json — uses root package.json workspaces (already handled above)
+    // If none found yet, use convention
+    const turboPath = path.join(this.root, 'turbo.json');
+    if (fs.existsSync(turboPath) && globs.length === 0) {
+      globs.push('apps/*', 'packages/*');
+    }
+
+    // Deduplicate
+    return [...new Set(globs)];
+  }
+}
+
+module.exports = MonorepoAnalyzer;

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;