cistack 3.1.0 → 4.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - 18.x
+          - 20.x
+          - 22.x
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run package smoke test
+        run: npm test
+
+      - name: Verify audit command
+        run: node bin/ciflow.js audit --path .
+
+      - name: Verify upgrade command
+        run: node bin/ciflow.js upgrade --path . --dry-run
+
+      - name: Smoke test init command in temp workspace
+        shell: bash
+        run: |
+          set -euo pipefail
+          tmp_dir="$(mktemp -d)"
+          node bin/ciflow.js init --path "$tmp_dir"
+          test -f "$tmp_dir/cistack.config.js"
+
+      - name: Smoke test generate command in temp workspace
+        shell: bash
+        run: |
+          set -euo pipefail
+          tmp_dir="$(mktemp -d)"
+          cat > "$tmp_dir/package.json" <<'JSON'
+          {
+            "name": "fixture-app",
+            "version": "1.0.0",
+            "scripts": {
+              "test": "echo ok"
+            }
+          }
+          JSON
+          node bin/ciflow.js generate --path "$tmp_dir" --dry-run --no-prompt

package/README.md

@@ -1,186 +1,258 @@
 # cistack
 
-> Automatically generate GitHub Actions CI/CD pipelines by analysing your codebase
+> Generate GitHub Actions CI/CD pipelines by analyzing the codebase you already have.
 
-`cistack` scans your project directory and produces production-grade GitHub Actions workflow YAML files. It detects your language, framework, testing tools, and hosting platform — then writes the best pipeline for your stack.
+`cistack` scans your project, detects the stack, and writes production-ready GitHub Actions workflows for CI, deployment, Docker, security, and releases. It is designed for real repos, not toy demos: it reads lock files, framework signals, release config, monorepo workspaces, hosting config, and Git branch metadata before generating YAML.
 
----
+## Why cistack
 
-## Features
-
-- 🔍 **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
-- 🛡️ **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 (supports per-package workflows)
-- ✅ **Interactive mode** — confirms detected settings before writing files
-- 🎯 **Zero config** — works out of the box with `cistack.config.js` for overrides
-
----
+- Detects languages, frameworks, testing tools, hosting providers, and release tooling automatically
+- Uses your repository's default Git branch when available instead of assuming `main`
+- Supports monorepos, per-package workflows, and package-manager-aware commands
+- Generates ecosystem-aware Dependabot config, including Bun when `bun.lock` is present
+- Smart-merges generated workflows with existing files instead of blindly overwriting them
+- Generates deploy pipelines for Vercel, Netlify, Firebase, GitHub Pages, AWS, Azure, Heroku, Render, and Railway
+- Ships with built-in workflow audit and upgrade commands
+- Includes typed `cistack.config.js` support through `index.d.ts`
+- Backed by an automated regression suite covering branch handling, release detection, smart merge behavior, monorepo package scripts, and CLI smoke tests
 
 ## Installation
 
 ```bash
-# Run without installing (recommended for one-off use)
+# One-off usage
 npx cistack
 
-# Install globally
+# Global install
 npm install -g cistack
 ```
 
----
+`cistack` supports Node.js 16+, and the project itself is continuously verified on Node.js 18, 20, and 22 in GitHub Actions.
 
-## Usage
+## CLI Usage
 
-### Generate Pipelines
-Analyze your stack and generate best-practice workflows.
-```bash
-# In your project directory
-npx cistack
+### Generate workflows
 
-# Show reasoning for detected stack
-npx cistack --explain
+`generate` is the default command, so both of these work:
 
-# Specify a project path
-npx cistack --path /path/to/project
+```bash
+npx cistack
+npx cistack generate
+```
 
-# Custom output directory
-npx cistack --output .github/workflows
+Common options:
 
-# Dry run (print YAML without writing files)
-npx cistack --dry-run
+```bash
+npx cistack generate --path /path/to/project
+npx cistack generate --dry-run
+npx cistack generate --explain
+npx cistack generate --output .github/workflows
+npx cistack generate --no-prompt
 ```
 
-### Audit Existing Workflows
-Analyze your current `.github/workflows` folder for outdated actions or missing features.
+### Audit existing workflows
+
 ```bash
 npx cistack audit
 ```
 
-### Automatic Upgrade
-Automatically bump all action versions (e.g., `actions/checkout@v3` → `@v4`) across all your workflow files to the latest stable releases.
+This checks `.github/workflows` for issues like missing concurrency blocks, outdated actions, old Node versions, and missing dependency caching.
+
+### Upgrade workflow actions
+
 ```bash
 npx cistack upgrade
+npx cistack upgrade --dry-run
 ```
 
-### Initialization
-Create a `cistack.config.js` to override auto-detected settings.
+This updates known GitHub Actions to their latest supported stable versions.
+
+### Create a starter config
+
 ```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
+This writes `cistack.config.js` with the supported override keys.
 
-| Platform | Detection Signal |
-|---|---|
-| **Firebase** | `firebase.json`, `.firebaserc`, `firebase-tools` dep |
-| **Vercel** | `vercel.json`, `.vercel` dir, `vercel` dep |
-| **Netlify** | `netlify.toml`, `_redirects`, `netlify-cli` dep |
-| **GitHub Pages** | `gh-pages` dep, `github.io` homepage in `package.json` |
-| **AWS** | `serverless.yml`, `appspec.yml`, `cdk.json`, `aws-sdk` dep |
-| **GCP App Engine** | `app.yaml` |
-| **Azure** | `azure/pipelines.yml`, `@azure/*` deps |
-| **Heroku** | `Procfile`, `heroku.yml` |
-| **Render** | `render.yaml` |
-| **Railway** | `railway.json`, `railway.toml` |
-| **Docker** | `Dockerfile`, `docker-compose.yml` |
+## What gets generated
 
----
+### `ci.yml`
 
-## Detected Frameworks
+Continuous integration for linting, tests, builds, coverage upload, and optional E2E jobs.
 
-Next.js, Nuxt, SvelteKit, Remix, Astro, Vite, React, Vue, Angular, Svelte, Gatsby,
-Express, Fastify, NestJS, Hono, Koa, tRPC,
-Django, Flask, FastAPI,
-Ruby on Rails,
-Spring Boot,
-Laravel,
-Go (gin), Rust (Cargo)
-
----
-
-## Detected Testing Tools
-
-| Tool | Type |
-|---|---|
-| Jest, Vitest, Mocha | Unit |
-| Cypress, Playwright | E2E |
-| Pytest | Python unit |
-| RSpec | Ruby unit |
-| Go Test | Go unit |
-| Cargo Test | Rust unit |
-| PHPUnit | PHP unit |
-| JUnit/Maven | JVM unit |
-| Storybook | Visual |
-
----
+- Runs on pushes and pull requests
+- Uses the detected default branch or your configured `branches`
+- Uses runtime matrices where appropriate
+- Uses package-manager-aware install and script commands
+
+### `deploy.yml`
+
+Continuous deployment for the primary hosting provider.
+
+- Runs on production pushes plus manual dispatch
+- Uses preview deployments on pull requests for providers that support them cleanly
+- Documents the required secrets in the file header
+- Avoids empty push branch lists when a repo is `develop`-only
+
+### `docker.yml`
+
+Builds and optionally pushes Docker images to GHCR.
+
+- Runs on configured branches, pull requests, and semantic version tags
+- Uses Buildx and GitHub Actions cache
+
+### `security.yml`
+
+Dependency audit plus CodeQL analysis.
+
+- Runs on push, pull request, and a weekly schedule
+- Uses the detected default branch or configured branch overrides
+
+### `release.yml`
+
+Generated when `semantic-release`, `changesets`, `release-it`, `standard-version`, or a custom release command is detected or configured.
+
+- Uses the detected package manager for release commands
+- Respects configured branches and detected default branch
+- Documents additional required secrets such as `NPM_TOKEN`
+
+## Supported detection
+
+### Hosting
+
+- Firebase
+- Vercel
+- Netlify
+- GitHub Pages
+- AWS
+- GCP App Engine
+- Azure
+- Heroku
+- Render
+- Railway
+- Docker
+
+### Frameworks
+
+- Next.js
+- Nuxt
+- SvelteKit
+- Remix
+- Astro
+- Vite
+- React
+- Vue
+- Angular
+- Svelte
+- Gatsby
+- Express
+- Fastify
+- NestJS
+- Hono
+- Koa
+- Django
+- Flask
+- FastAPI
+- Rails
+- Spring Boot
+- Laravel
+- Go
+- Rust
+
+### Testing tools
+
+- Jest
+- Vitest
+- Mocha
+- Cypress
+- Playwright
+- Pytest
+- RSpec
+- Go test
+- Cargo test
+- PHPUnit
+- Maven / JUnit
+- Storybook
+
+## Configuration
+
+Create `cistack.config.js` when you want to override detection:
+
+```js
+/** @type {import('cistack').Config} */
+module.exports = {
+  nodeVersion: '20',
+  packageManager: 'pnpm',
+  branches: ['main', 'staging'],
+  hosting: ['Vercel'],
+  outputDir: '.github/workflows',
+
+  cache: {
+    npm: true,
+    cargo: true,
+    pip: true,
+  },
+
+  monorepo: {
+    perPackage: true,
+  },
+
+  release: {
+    tool: 'semantic-release',
+  },
+};
+```
 
-## Generated Workflows
+Supported top-level config keys:
 
-### `ci.yml` — Continuous Integration
-Runs on every push and pull request:
-1. **Lint** — ESLint, TypeScript type-check, formatter check
-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
+- `nodeVersion`
+- `packageManager`
+- `hosting`
+- `frameworks`
+- `testing`
+- `branches`
+- `cache`
+- `monorepo`
+- `release`
+- `secrets`
+- `outputDir`
 
-### `deploy.yml` — Continuous Deployment
-Triggers on push to `main`/`master` + manual dispatch:
-- 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
+Branch behavior:
 
-### `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 (GHA)
+- If `branches` is set in config, `cistack` uses it exactly
+- Otherwise it reads the repository's default branch from Git metadata when available
+- If Git metadata is unavailable, it falls back to safe defaults like `main`, `master`, and `develop` depending on the workflow type
 
-### `security.yml` — Security Audit
-Runs on push, PRs, and weekly schedule:
-- Dependency vulnerability audit (npm audit / safety / cargo audit)
-- GitHub CodeQL analysis for the detected language
+## Secrets
 
----
+Generated deploy and release workflows document the secrets they need at the top of each file. Add them in:
 
-## Required Secrets
+`GitHub -> Settings -> Secrets and variables -> Actions`
 
-After generating, add the required secrets to your repository at:
-`Settings → Secrets and variables → Actions`
+## Development and Quality
 
-Each generated `deploy.yml` has a comment at the top listing the exact secrets needed.
+The project now includes a regression suite for the areas that were historically the easiest to break:
 
----
+- config override handling
+- default branch detection
+- deploy branch selection
+- Netlify production branch handling
+- smart merge behavior
+- monorepo per-package build script lookup
+- release config detection
+- release workflow generation
+- CLI dry-run smoke testing
 
-## Examples
+Run the checks locally:
 
-**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
+npm test
+npm run test:smoke
+node bin/ciflow.js audit --path .
+node bin/ciflow.js upgrade --path . --dry-run
 ```
 
----
+If you are using the published package, the executable is `cistack`. In this repository, the local entrypoint is `bin/ciflow.js`.
 
 ## License
 

package/bin/ciflow.js

@@ -87,7 +87,7 @@ 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)
+  // branches: ['main', 'staging'], // CI branches (default: detected git default branch, then main/master/develop)
   // outputDir: '.github/workflows', // Where to write workflow files
 
   // cache: {

package/index.d.ts

@@ -0,0 +1,90 @@
+export type PackageManager =
+  | 'npm'
+  | 'yarn'
+  | 'pnpm'
+  | 'bun'
+  | 'pip'
+  | 'poetry'
+  | 'pipenv'
+  | 'bundler'
+  | 'go mod'
+  | 'cargo'
+  | 'maven'
+  | 'gradle'
+  | 'composer';
+
+export type HostingName =
+  | 'Firebase'
+  | 'Vercel'
+  | 'Netlify'
+  | 'AWS'
+  | 'GCP App Engine'
+  | 'Azure'
+  | 'Heroku'
+  | 'Render'
+  | 'Railway'
+  | 'GitHub Pages'
+  | 'Docker';
+
+export type ReleaseTool =
+  | 'semantic-release'
+  | 'changesets'
+  | 'release-it'
+  | 'standard-version'
+  | 'custom';
+
+export interface CacheConfig {
+  npm?: boolean;
+  pip?: boolean;
+  cargo?: boolean;
+  maven?: boolean;
+  gradle?: boolean;
+  go?: boolean;
+  composer?: boolean;
+  bundler?: boolean;
+}
+
+export interface MonorepoConfig {
+  perPackage?: boolean;
+}
+
+export interface ReleaseConfig {
+  tool: ReleaseTool;
+  command?: string;
+  publishToNpm?: boolean;
+  requiresNpmToken?: boolean;
+  branches?: string[];
+}
+
+export interface Config {
+  nodeVersion?: string | number;
+  packageManager?: PackageManager;
+  hosting?: HostingName | HostingName[];
+  frameworks?: string | string[];
+  testing?: string | string[];
+  branches?: string[];
+  cache?: CacheConfig;
+  monorepo?: MonorepoConfig;
+  release?: ReleaseTool | ReleaseConfig;
+  secrets?: string[];
+  outputDir?: string;
+}
+
+export interface CIFlowOptions {
+  projectPath: string;
+  outputDir?: string;
+  dryRun?: boolean;
+  force?: boolean;
+  prompt?: boolean;
+  verbose?: boolean;
+  explain?: boolean;
+}
+
+declare class CIFlow {
+  constructor(options: CIFlowOptions);
+  run(): Promise<void>;
+  audit(): Promise<void>;
+  upgrade(): Promise<void>;
+}
+
+export default CIFlow;

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "cistack",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "Automatically generate GitHub Actions CI/CD pipelines by analysing your codebase",
   "main": "src/index.js",
+  "types": "index.d.ts",
   "bin": {
     "cistack": "./bin/ciflow.js"
   },
   "scripts": {
     "start": "node bin/ciflow.js",
-    "test": "node bin/ciflow.js --dry-run --no-prompt"
+    "test": "node tests/run.js",
+    "test:smoke": "node bin/ciflow.js generate --path . --dry-run --no-prompt"
   },
   "keywords": [
     "github-actions",

package/src/analyzers/codebase.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 const { globSync } = require('glob');
 
 /**
@@ -25,9 +26,11 @@ class CodebaseAnalyzer {
       srcStructure: {},
       hasMonorepo: false,
       workspaces: [],
+      defaultBranch: null,
+      currentBranch: null,
     };
 
-    // ── gather all file paths (ignore node_modules, .git, dist, build) ────
+    // ── gather notable file paths (avoid giant deep scans) ──────────────
     const allFiles = globSync('**/*', {
       cwd: this.root,
       ignore: [
@@ -38,11 +41,16 @@ class CodebaseAnalyzer {
         '.next/**',
         '.nuxt/**',
         'coverage/**',
+        'public/**',
+        'assets/**',
+        'static/**',
+        'vendor/**',
         '*.min.js',
         '*.min.css',
       ],
-      nodir: true,
+      nodir: false,
       dot: true,
+      maxDepth: 5, // Avoid extreme depth for general discovery
     });
 
     info.files = allFiles;
@@ -60,6 +68,7 @@ class CodebaseAnalyzer {
       'package-lock.json',
       'yarn.lock',
       'pnpm-lock.yaml',
+      'bun.lock',
       'bun.lockb',
       'Pipfile.lock',
       'poetry.lock',
@@ -149,7 +158,7 @@ class CodebaseAnalyzer {
       'biome.json',
       // CI already present
       '.travis.yml',
-      'circle.ci/config.yml',
+      '.circleci/config.yml',
       'Jenkinsfile',
     ];
 
@@ -188,9 +197,7 @@ class CodebaseAnalyzer {
       fs.existsSync(path.join(this.root, 'turbo.json')) ||
       fs.existsSync(path.join(this.root, 'nx.json')) ||
       fs.existsSync(path.join(this.root, 'lerna.json')) ||
-      (info.packageJson &&
-        (info.packageJson.workspaces ||
-          info.packageJson.private === true));
+      (info.packageJson && info.packageJson.workspaces);
 
     info.hasMonorepo = !!hasMonorepoMarker;
     if (info.packageJson && info.packageJson.workspaces) {
@@ -198,8 +205,38 @@ class CodebaseAnalyzer {
       info.workspaces = Array.isArray(ws) ? ws : ws.packages || [];
     }
 
+    // ── git branch hints ───────────────────────────────────────────────────
+    const gitInfo = this._detectGitBranches();
+    info.defaultBranch = gitInfo.defaultBranch;
+    info.currentBranch = gitInfo.currentBranch;
+
     return info;
   }
+
+  _detectGitBranches() {
+    const readGit = (args) => {
+      try {
+        return execFileSync('git', args, {
+          cwd: this.root,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+      } catch (_) {
+        return '';
+      }
+    };
+
+    const remoteHead = readGit(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
+    const currentBranch = readGit(['symbolic-ref', '--quiet', '--short', 'HEAD']) || null;
+    const defaultBranch = remoteHead
+      ? remoteHead.replace(/^origin\//, '')
+      : currentBranch;
+
+    return {
+      defaultBranch: defaultBranch || null,
+      currentBranch,
+    };
+  }
 }
 
 module.exports = CodebaseAnalyzer;