@logickernel/agileflow 0.2.2 → 0.4.1

package/docs/version-centric-cicd.md

@@ -1,166 +1,289 @@
-# Version-Centric CI/CD Approach
+# Version-Centric CI/CD
 
-AgileFlow introduces a revolutionary approach to CI/CD that prioritizes **version management over environment-based deployments**. This paradigm shift eliminates the complexity of managing multiple deployment branches and environments, replacing them with a streamlined, version-focused workflow.
+AgileFlow enables a **version-centric approach** to CI/CD where versioning is decoupled from build and deployment. This architecture simplifies pipelines and provides flexibility.
 
-## Traditional Git-Based Flows vs. AgileFlow
+## The Decoupled Architecture
 
-### Traditional Approach (Branch-Based Environments)
-Traditional CI/CD pipelines often rely on branch-based environment management:
+```
+┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
+│  Merge to main  │         │  Tag: v1.2.3    │         │  Build/Deploy   │
+│                 │ ──────▶ │                 │ ──────▶ │                 │
+│  AgileFlow      │         │  (event)        │         │  Your pipelines │
+│  creates tag    │         │                 │         │                 │
+└─────────────────┘         └─────────────────┘         └─────────────────┘
+```
+
+### How It Works
+
+1. **On merge to main**: AgileFlow analyzes commits and creates a version tag
+2. **Tag creation event**: Triggers your build and deploy pipelines
+3. **Build/Deploy**: Uses the tag as the version identifier
+
+### Benefits
+
+- **Separation of concerns** — Versioning is independent from build/deploy
+- **Flexibility** — Any process can hook into tag creation
+- **Simplicity** — Each pipeline has one responsibility
+- **Reusability** — Same build pipeline for all versions
+- **Auditability** — Clear version trail for every deployment
+
+---
+
+## Traditional vs. Version-Centric
+
+### Traditional (Coupled)
 
-```mermaid
-graph LR
-    A[main branch] --> B[staging branch]
-    B --> C[production branch]
-    D[feature branch] --> A
-    E[hotfix branch] --> A
+```yaml
+# Everything in one pipeline
+on: push to main
+  → calculate version
+  → build
+  → deploy staging
+  → deploy production
 ```
 
-**Problems with Traditional Approach:**
-- **Environment Drift**: Different branches can diverge, leading to "works in staging, breaks in production"
-- **Complex Branch Management**: Multiple long-lived branches require constant synchronization
-- **Deployment Uncertainty**: Hard to know exactly what version is running in each environment
-- **Rollback Complexity**: Rolling back requires managing multiple branch states
-- **Version Inconsistency**: Different environments may run different versions
-
-### AgileFlow Approach (Version-Centric)
-AgileFlow simplifies this by making **every deployment, test, and operation version-centric**:
-
-```mermaid
-graph LR
-    A[main branch] --> B[Version v1.2.3]
-    B --> C[Deploy to Staging]
-    B --> D[Deploy to Production]
-    B --> E[Run Integration Tests]
-    B --> F[Performance Testing]
+**Problems:**
+- Complex, monolithic pipelines
+- Version logic mixed with build logic
+- Hard to rerun individual steps
+
+### Version-Centric (Decoupled)
+
+```yaml
+# Pipeline 1: Versioning
+on: push to main
+  → AgileFlow creates tag
+
+# Pipeline 2: Release
+on: tag created
+  → build with tag version
+  → deploy staging
+  → deploy production
 ```
 
-**Benefits of Version-Centric Approach:**
-- **Single Source of Truth**: All environments run the exact same version
-- **Predictable Deployments**: Every deployment uses a well-identified, immutable version
-- **Simplified Rollbacks**: Rollback to any previous version with confidence
-- **Consistent Testing**: All tests run against the same version that will be deployed
-- **Clear Audit Trail**: Every deployment is tied to a specific, documented version
+**Benefits:**
+- Simple, focused pipelines
+- Versioning completely separate
+- Easy to rerun builds for any version
 
-## Simplified Pipeline Stages
+---
 
-AgileFlow's CI/CD pipeline consists of just 6 focused stages:
+## Implementation
 
-### 1. **Version** Stage
-- **Purpose**: Generate semantic version and comprehensive release notes
-- **Output**: `VERSION` variable available to all subsequent stages
-- **Automation**: Uses AgileFlow tool to analyze commit history and determine next version
-- **Artifacts**: Version tag pushed to repository, release notes generated
+### GitHub Actions
 
-### 2. **Test** Stage
-- **Purpose**: Run tests against the source code before building
-- **Input**: Uses the source code and `VERSION` variable from the version stage
-- **Output**: Test results and validation that the code is ready for building
-- **Benefits**: Catch issues early before building artifacts
+**Versioning workflow** (`.github/workflows/version.yml`):
+```yaml
+name: Version
+on:
+  push:
+    branches: [main]
 
-### 3. **Build** Stage
-- **Purpose**: Create application artifacts and Docker images
-- **Input**: Uses the `VERSION` variable from the version stage
-- **Output**: Versioned artifacts (e.g., `app:v1.2.3`, `frontend:v1.2.3`)
-- **Consistency**: All builds use the same version identifier
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-### 4. **Deploy** Stage
-- **Purpose**: Deploy the versioned artifacts to various environments
-- **Approach**: Deploy the same version to staging, production, etc.
-- **Benefits**: Identical behavior across all environments
-- **Rollback**: Simple version-based rollback (e.g., "rollback to v1.2.2")
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
 
-### 5. **E2E** Stage
-- **Purpose**: Run end-to-end tests against the deployed version
-- **Scope**: Integration tests, end-to-end tests, performance tests
-- **Target**: Tests run against the actual deployed version
-- **Confidence**: Tests validate exactly what will run in production
+      - name: Create version tag
+        env:
+          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
+        run: npx @logickernel/agileflow github
+```
 
-### 6. **Clean** Stage
-- **Purpose**: Cleanup temporary resources and artifacts
-- **Maintenance**: Remove old Docker images, temporary files, etc.
-- **Optimization**: Keep only necessary version artifacts
+**Release workflow** (`.github/workflows/release.yml`):
+```yaml
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
 
-## Real-World Example
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
-Here's how the version-centric approach works in practice:
+      - name: Get version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+
+      - name: Build
+        run: docker build -t myapp:$VERSION .
+
+  deploy-staging:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - run: kubectl set image deployment/myapp myapp=myapp:$VERSION
+
+  deploy-production:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - run: kubectl set image deployment/myapp myapp=myapp:$VERSION
+```
+
+### GitLab CI
 
 ```yaml
-# .gitlab-ci.yml
-include:
-  - local: templates/AgileFlow.gitlab-ci.yml
+stages:
+  - version
+  - build
+  - deploy
 
-# Test stage runs tests against source code
-test:
-  stage: test
+# Versioning - runs on merge to main
+agileflow:
+  stage: version
+  image: node:20-alpine
   script:
-    - npm test
-    - npm run lint
+    - npx @logickernel/agileflow gitlab
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
 
-# Build stage uses VERSION from agileflow job
+# Build - runs on tag creation
 build:
   stage: build
   script:
-    - docker build -t myapp:${VERSION} .
-    - docker push myapp:${VERSION}
-  needs:
-    - test
-
-# Deploy stage deploys the same version everywhere
-deploy-testing:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: testing
-  needs:
-    - build
+    - docker build -t myapp:$CI_COMMIT_TAG .
+    - docker push myapp:$CI_COMMIT_TAG
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
 
+# Deploy - runs on tag creation
 deploy-staging:
   stage: deploy
   script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
   environment:
     name: staging
-  when: manual
-  needs:
-    - build
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
 
 deploy-production:
   stage: deploy
   script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
   environment:
     name: production
   when: manual
-  needs:
-    - build
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
+```
+
+---
 
-# E2E stage validates the deployed version
-integration-tests:
-  stage: e2e
+## Version-Centric Deployments
+
+### All Environments Use the Same Version
+
+```
+Tag v1.2.3
+    │
+    ├──▶ Build: myapp:v1.2.3
+    │
+    ├──▶ Staging: myapp:v1.2.3
+    │
+    └──▶ Production: myapp:v1.2.3
+```
+
+No environment drift — every environment runs identical code.
+
+### Simple Rollbacks
+
+```bash
+# Rollback = deploy previous tag
+kubectl set image deployment/myapp myapp=myapp:v1.2.2
+```
+
+### Clear Audit Trail
+
+```bash
+# What version is running?
+kubectl get deployment myapp -o jsonpath='{.spec.template.spec.containers[0].image}'
+# myapp:v1.2.3
+
+# What's in that version?
+git show v1.2.3
+```
+
+---
+
+## Advanced Patterns
+
+### Conditional Deployments
+
+Deploy only specific version types:
+
+```yaml
+# Only deploy minor/major versions to production
+deploy-production:
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.0$/'
+```
+
+### Multiple Services
+
+Same version for all services in a monorepo:
+
+```yaml
+build-backend:
+  script:
+    - docker build -t backend:$CI_COMMIT_TAG ./backend
+
+build-frontend:
+  script:
+    - docker build -t frontend:$CI_COMMIT_TAG ./frontend
+```
+
+### Notifications
+
+Announce new versions:
+
+```yaml
+notify:
   script:
-    - ./run-tests.sh --version ${VERSION}
-  needs:
-    - deploy-testing
+    - |
+      curl -X POST "$SLACK_WEBHOOK" \
+        -d "{\"text\": \"Released $CI_COMMIT_TAG\"}"
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
 ```
 
+---
+
 ## Key Advantages
 
-1. **Eliminates Environment Drift**: Staging and production always run identical versions
-2. **Simplifies Operations**: DevOps teams work with versions, not branch states
-3. **Improves Reliability**: Every deployment is predictable and auditable
-4. **Reduces Complexity**: No need to manage multiple deployment branches
-5. **Enhances Security**: Version-based deployments provide clear audit trails
-6. **Facilitates Compliance**: Easy to demonstrate what version is running where
+1. **Eliminates environment drift** — All environments run identical versions
+2. **Simplifies operations** — Work with versions, not branch states
+3. **Enables easy rollbacks** — Just redeploy a previous tag
+4. **Provides clear audit trail** — Every deployment tied to a version
+5. **Decouples concerns** — Versioning separate from build/deploy
+
+---
 
 ## Migration Path
 
-If you're currently using a traditional branch-based approach:
+If using a traditional coupled approach:
+
+1. **Add AgileFlow** — Create versioning workflow
+2. **Add tag-triggered workflow** — For build/deploy
+3. **Test both workflows** — Verify tags trigger releases
+4. **Remove old logic** — Clean up version calculation from build pipeline
+
+---
 
-1. **Start with AgileFlow**: Include the template and let it generate versions
-2. **Gradually Simplify**: Remove environment-specific branches over time
-3. **Update Deployments**: Modify deployment scripts to use `${VERSION}` variable
-4. **Standardize Testing**: Run all tests against the versioned artifacts
-5. **Document Changes**: Update runbooks to reference versions instead of branches
+## Related Documentation
 
-This approach transforms your CI/CD from a complex, branch-managed system into a simple, version-driven pipeline where every deployment is predictable, auditable, and reliable.
+- [Getting Started](./getting-started.md) — Quick start
+- [Installation Guide](./installation.md) — Setup instructions
+- [Branching Strategy](./branching-strategy.md) — Git workflow
+- [Best Practices](./best-practices.md) — Recommended patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logickernel/agileflow",
-  "version": "0.2.2",
+  "version": "0.4.1",
   "description": "Automatic semantic versioning and changelog generation based on conventional commits",
   "main": "src/index.js",
   "bin": {
@@ -14,7 +14,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepack": "chmod +x bin/agileflow"
   },
   "keywords": [
     "semantic-versioning",

package/src/index.js

@@ -12,9 +12,9 @@ Usage:
 
 Commands:
   <none>   Prints the current version, next version, commits, and changelog
-  push     Push a semantic version tag to the remote repository (native git)
-  gitlab   Push a semantic version tag via GitLab API (for GitLab CI)
-  github   Push a semantic version tag via GitHub API (for GitHub Actions)
+  push     Push a semantic version tag to the remote repository
+  gitlab   Create a semantic version tag via GitLab API (for GitLab CI)
+  github   Create a semantic version tag via GitHub API (for GitHub Actions)
 
 Options:
   --quiet        Only output the next version (or empty if no bump)
@@ -26,11 +26,32 @@ For more information, visit: https://code.logickernel.com/tools/agileflow
 }
 
 /**
- * Parses command line arguments.
+ * Valid options that can be passed to commands.
+ */
+const VALID_OPTIONS = ['--quiet', '--help', '-h', '--version', '-v'];
+
+/**
+ * Valid commands.
+ */
+const VALID_COMMANDS = ['push', 'gitlab', 'github'];
+
+/**
+ * Parses command line arguments and validates them.
  * @param {Array<string>} args - Command line arguments
  * @returns {{quiet: boolean}}
+ * @throws {Error} If invalid options are found
  */
 function parseArgs(args) {
+  // Check for invalid options
+  for (const arg of args) {
+    if (arg.startsWith('--') && !VALID_OPTIONS.includes(arg)) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (arg.startsWith('-') && !arg.startsWith('--') && !VALID_OPTIONS.includes(arg)) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  
   return {
     quiet: args.includes('--quiet'),
   };
@@ -61,7 +82,7 @@ function displayVersionInfo(info, quiet) {
   }
   
   console.log(`\nCurrent version: ${currentVersion || 'none'}`);
-  console.log(`New version: ${newVersion || 'no bump needed'}`);
+  console.log(`New version:     ${newVersion || 'no bump needed'}`);
   if (changelog) {
     console.log(`\nChangelog:\n\n${changelog}`);
   }
@@ -113,7 +134,17 @@ async function handlePushCommand(pushType, options) {
 
 async function main() {
   const [, , cmd, ...rest] = process.argv;
-  const options = parseArgs(cmd ? [cmd, ...rest] : rest);
+  
+  let options;
+  try {
+    options = parseArgs(cmd ? [cmd, ...rest] : rest);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    console.error();
+    printHelp();
+    process.exit(1);
+    return;
+  }
 
   // Handle help
   if (cmd === '-h' || cmd === '--help' || cmd === 'help') {
@@ -134,13 +165,22 @@ async function main() {
   }
 
   // Unknown command (not an option)
-  if (cmd && !cmd.startsWith('--')) {
+  if (cmd && !cmd.startsWith('--') && !cmd.startsWith('-')) {
     console.error(`Error: Unknown command "${cmd}"`);
     console.error();
     printHelp();
     process.exit(1);
   }
 
+  // Invalid option (starts with -- but not valid)
+  if (cmd && cmd.startsWith('--') && !VALID_OPTIONS.includes(cmd)) {
+    console.error(`Error: Unknown option "${cmd}"`);
+    console.error();
+    printHelp();
+    process.exit(1);
+    return;
+  }
+
   // Default: show version info
   const info = await processVersionInfo();
   displayVersionInfo(info, options.quiet);

package/src/utils.js

@@ -170,13 +170,16 @@ function extractIssueReference(message) {
  * @param {string} subject - First line of commit message
  * @param {Object} parsed - Parsed conventional commit info
  * @param {string} fullMessage - Full commit message
+ * @param {boolean} isBreakingSection - Whether this is for the breaking changes section
  * @returns {string} Formatted description
  */
-function formatChangelogDescription(subject, parsed, fullMessage) {
+function formatChangelogDescription(subject, parsed, fullMessage, isBreakingSection = false) {
   if (!parsed) return subject;
   let description = parsed.description;
   const isBreaking = parsed.breaking || /BREAKING CHANGE:/i.test(fullMessage);
-  if (isBreaking) {
+  
+  // Only add BREAKING prefix if not in breaking changes section
+  if (isBreaking && !isBreakingSection) {
     description = `BREAKING: ${description}`;
   }
   return description;
@@ -229,13 +232,25 @@ function applyVersionBump(current, bump) {
   }
 }
 
+/**
+ * Checks if a commit is a breaking change.
+ * @param {Object} commit - Commit object
+ * @param {Object} parsed - Parsed conventional commit info
+ * @returns {boolean}
+ */
+function isBreakingChange(commit, parsed) {
+  if (!parsed) return false;
+  return parsed.breaking || /BREAKING CHANGE:/i.test(commit.message);
+}
+
 /**
  * Analyzes commits to determine version bump requirements.
  * @param {Array} commits - Array of commit objects
- * @returns {{hasBreaking: boolean, hasFeat: boolean, hasPatchTypes: boolean, commitsByType: Object}}
+ * @returns {{hasBreaking: boolean, hasFeat: boolean, hasPatchTypes: boolean, commitsByType: Object, breakingCommits: Array}}
  */
 function analyzeCommitsForVersioning(commits) {
   const commitsByType = Object.fromEntries(TYPE_ORDER.map(t => [t, []]));
+  const breakingCommits = [];
   let hasBreaking = false, hasFeat = false, hasPatchTypes = false;
   
   for (const commit of commits) {
@@ -243,18 +258,23 @@ function analyzeCommitsForVersioning(commits) {
     if (!parsed) continue;
     
     const { type, breaking } = parsed;
-    const isBreaking = breaking || /BREAKING CHANGE:/i.test(commit.message);
+    const isBreaking = isBreakingChange(commit, parsed);
     
-    if (isBreaking) hasBreaking = true;
-    if (type === 'feat') hasFeat = true;
-    else if (PATCH_TYPES.includes(type)) hasPatchTypes = true;
-    
-    if (commitsByType[type]) {
-      commitsByType[type].push(commit);
+    if (isBreaking) {
+      hasBreaking = true;
+      breakingCommits.push(commit);
+    } else {
+      // Only add to type sections if not breaking
+      if (type === 'feat') hasFeat = true;
+      else if (PATCH_TYPES.includes(type)) hasPatchTypes = true;
+      
+      if (commitsByType[type]) {
+        commitsByType[type].push(commit);
+      }
     }
   }
   
-  return { hasBreaking, hasFeat, hasPatchTypes, commitsByType };
+  return { hasBreaking, hasFeat, hasPatchTypes, commitsByType, breakingCommits };
 }
 
 /**
@@ -270,9 +290,10 @@ function capitalize(str) {
 /**
  * Generates changelog entries for a commit type section.
  * @param {Array} commits - Commits of this type
+ * @param {boolean} isBreakingSection - Whether this is for the breaking changes section
  * @returns {Array<string>} Changelog lines
  */
-function generateTypeChangelog(commits) {
+function generateTypeChangelog(commits, isBreakingSection = false) {
   const byScope = {};
   const noScope = [];
   
@@ -283,7 +304,7 @@ function generateTypeChangelog(commits) {
     const subject = commit.message.split('\n')[0].trim();
     const entry = {
       scope: parsed.scope,
-      description: formatChangelogDescription(subject, parsed, commit.message),
+      description: formatChangelogDescription(subject, parsed, commit.message, isBreakingSection),
       issueRef: extractIssueReference(commit.message) || '',
     };
     
@@ -323,6 +344,15 @@ function calculateNextVersionAndChangelog(expandedInfo) {
   
   // Generate changelog
   const changelogLines = [];
+  
+  // Add breaking changes section first if any
+  if (analysis.breakingCommits.length > 0) {
+    changelogLines.push('BREAKING CHANGES:');
+    changelogLines.push(...generateTypeChangelog(analysis.breakingCommits, true));
+    changelogLines.push('');
+  }
+  
+  // Add regular type sections
   for (const type of TYPE_ORDER) {
     const typeCommits = analysis.commitsByType[type];
     if (!typeCommits?.length) continue;