cistack 1.0.0 → 3.0.0

package/src/config/loader.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Loads cistack.config.js (or .cjs / .mjs) from the project root.
+ * Returns an empty object if no config file is found.
+ *
+ * Supported keys:
+ *   nodeVersion      – override detected Node version e.g. '18'
+ *   packageManager   – override detected PM: 'npm'|'yarn'|'pnpm'|'bun'
+ *   hosting          – array of hosting names to force e.g. ['Firebase']
+ *   branches         – branches to run CI on e.g. ['main', 'staging']
+ *   cache            – { npm: bool, cargo: bool, pip: bool, ... } enable/disable caches
+ *   monorepo         – { perPackage: bool } generate one file per workspace
+ *   release          – { tool: 'semantic-release'|'changesets'|'standard-version'|'release-it' }
+ *   secrets          – extra secret names to document in workflow comments
+ *   outputDir        – override default '.github/workflows'
+ */
+class ConfigLoader {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+  }
+
+  load() {
+    const candidates = [
+      'cistack.config.js',
+      'cistack.config.cjs',
+      'cistack.config.mjs',
+    ];
+
+    for (const candidate of candidates) {
+      const fullPath = path.join(this.projectPath, candidate);
+      if (fs.existsSync(fullPath)) {
+        try {
+          // 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) {
+          // 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.`));
+          }
+        }
+      }
+    }
+
+    return {};
+  }
+
+  /**
+   * Deep-merge config file settings into detected settings.
+   * Config file always wins on scalar values; arrays overwrite entirely.
+   */
+  static merge(detected, override) {
+    if (!override || typeof override !== 'object') return detected;
+
+    const result = { ...detected };
+
+    for (const [key, val] of Object.entries(override)) {
+      if (val === null || val === undefined) continue;
+
+      if (Array.isArray(val)) {
+        result[key] = val; // arrays overwrite
+      } else if (typeof val === 'object' && !Array.isArray(detected[key])) {
+        result[key] = { ...(detected[key] || {}), ...val };
+      } else {
+        result[key] = val;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Apply config file overrides onto the full detected stack.
+   *
+   * @param {object} cfg          - raw cistack.config.js export
+   * @param {object} detected     - { hosting, frameworks, languages, testing, ... }
+   * @returns {object}            - merged config ready for the generator
+   */
+  static applyToStack(cfg, detected) {
+    if (!cfg || Object.keys(cfg).length === 0) return detected;
+
+    const result = { ...detected };
+
+    // 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), 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, manual: true } : l
+      );
+    }
+
+    // 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,
+        secrets: [],
+        notes: ['set via cistack.config.js'],
+      }));
+    }
+
+    // 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 = { ...(result._config || {}), ...cfg };
+
+    return result;
+  }
+}
+
+module.exports = ConfigLoader;

package/src/detectors/env.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Detects environment variables documented in .env.example or .env.sample.
+ *
+ * Returns:
+ *   {
+ *     secrets: string[],   – keys that look like secrets (TOKEN, KEY, SECRET, PASSWORD, PASS)
+ *     public:  string[],   – other public env vars
+ *     all:     string[],   – full list in file order
+ *     sourceFile: string,  – which file was read
+ *   }
+ */
+class EnvDetector {
+  constructor(projectPath, codebaseInfo) {
+    this.root = projectPath;
+    this.info = codebaseInfo;
+  }
+
+  async detect() {
+    const candidates = ['.env.example', '.env.sample', '.env.template', '.env.defaults'];
+
+    for (const candidate of candidates) {
+      const fullPath = path.join(this.root, candidate);
+      if (fs.existsSync(fullPath)) {
+        const content = fs.readFileSync(fullPath, 'utf8');
+        return this._parse(content, candidate);
+      }
+    }
+
+    return { secrets: [], public: [], all: [], sourceFile: null };
+  }
+
+  _parse(content, sourceFile) {
+    const all = [];
+    const secrets = [];
+    const publicVars = [];
+
+    const SECRET_PATTERN = /SECRET|TOKEN|KEY|PASSWORD|PASS|PRIVATE|AUTH|CREDENTIAL|CERT|PEM/i;
+
+    for (const rawLine of content.split('\n')) {
+      const line = rawLine.trim();
+
+      // Skip comments and blank lines
+      if (!line || line.startsWith('#')) continue;
+
+      // Match KEY=value or KEY= or just KEY
+      const match = line.match(/^([A-Z_][A-Z0-9_]*)\s*(?:=.*)?$/i);
+      if (!match) continue;
+
+      const key = match[1].toUpperCase();
+      if (all.includes(key)) continue; // de-dupe
+
+      all.push(key);
+      if (SECRET_PATTERN.test(key)) {
+        secrets.push(key);
+      } else {
+        publicVars.push(key);
+      }
+    }
+
+    return { secrets, public: publicVars, all, sourceFile };
+  }
+}
+
+module.exports = EnvDetector;

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,
     };
   }