@logickernel/agileflow 0.1.0 → 0.2.0

package/docs/gitlab-ci-template.md

@@ -1,324 +0,0 @@
-# GitLab CI Template Reference
-
-The AgileFlow GitLab CI template provides a streamlined, version-centric CI/CD pipeline that eliminates the complexity of traditional environment-based deployments.
-
-## Overview
-
-This template implements a 6-stage pipeline that focuses on version management rather than branch-based environment management. Every deployment, test, and operation is performed on well-identified versions, ensuring consistency and reliability across all environments.
-
-## Template Structure
-
-```yaml
-include:
-  - local: templates/AgileFlow.gitlab-ci.yml
-```
-
-## Pipeline Stages
-
-### 1. Version Stage
-The foundation of the AgileFlow approach. This stage automatically generates semantic versions and comprehensive release notes.
-
-**Job**: `agileflow`
-- **Image**: `registry.logickernel.com/kernel/agileflow:0.8.0`
-- **Script**: `agileflow gitlab-ci`
-- **Artifacts**: `VERSION` variable (dotenv report)
-
-**What it does**:
-- Analyzes commit history on the main branch
-- Calculates the next semantic version based on conventional commits
-- Generates comprehensive release notes
-- Creates and pushes version tags to the repository
-- Makes the `VERSION` variable available to all subsequent stages
-
-**Output**: The `VERSION` variable contains the generated semantic version (e.g., `v1.2.3`)
-
-### 2. Test Stage
-Runs tests against the source code before building artifacts.
-
-**Purpose**: Validate that the source code is ready for building and deployment
-**Input**: Source code and `VERSION` variable from the version stage
-**Output**: Test results and validation that the code meets quality standards
-
-**Example implementation**:
-```yaml
-test:
-  stage: test
-  script:
-    - npm test
-    - npm run lint
-  needs:
-    - agileflow
-```
-
-### 3. Build Stage
-Creates application artifacts and Docker images using the version from the version stage.
-
-**Purpose**: Build versioned artifacts that will be deployed across all environments
-**Input**: `VERSION` variable from the version stage
-**Output**: Versioned artifacts (e.g., `app:v1.2.3`, `frontend:v1.2.3`)
-
-**Example implementation**:
-```yaml
-build:
-  stage: build
-  script:
-    - docker build -t myapp:${VERSION} .
-    - docker push myapp:${VERSION}
-  needs:
-    - test
-```
-
-### 4. Deploy Stage
-Deploys the versioned artifacts to various environments.
-
-**Purpose**: Deploy the same version to staging, production, and other environments
-**Approach**: All environments receive identical versions, eliminating environment drift
-**Benefits**: Predictable deployments, simplified rollbacks, consistent behavior
-
-**Example implementation**:
-```yaml
-deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: staging
-  needs:
-    - build
-
-deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: production
-  when: manual
-  needs:
-    - build
-```
-
-### 5. E2E Stage
-Validates the deployed version across all environments.
-
-**Purpose**: Run tests against the actual deployed version
-**Scope**: Integration tests, end-to-end tests, performance tests
-**Target**: Tests validate exactly what will run in production
-
-**Example implementation**:
-```yaml
-integration-tests:
-  stage: e2e
-  script:
-    - ./run-tests.sh --version ${VERSION}
-  needs:
-    - deploy-staging
-
-performance-tests:
-  stage: e2e
-  script:
-    - ./run-performance-tests.sh --version ${VERSION}
-  needs:
-    - deploy-staging
-```
-
-### 6. Clean Stage
-Cleanup temporary resources and artifacts.
-
-**Purpose**: Remove old Docker images, temporary files, and unnecessary artifacts
-**Maintenance**: Keep only necessary version artifacts
-**Optimization**: Reduce storage costs and improve pipeline performance
-
-**Example implementation**:
-```yaml
-cleanup:
-  stage: clean
-  script:
-    - docker image prune -f
-    - rm -rf /tmp/build-artifacts
-  when: always
-```
-
-## Key Benefits
-
-### Version Consistency
-- **Single Source of Truth**: All environments run identical versions
-- **No Environment Drift**: Staging and production are always in sync
-- **Predictable Deployments**: Every deployment uses a well-identified version
-
-### Simplified Operations
-- **Clear Version Tracking**: Easy to identify what's running where
-- **Simple Rollbacks**: Rollback to any previous version with confidence
-- **Reduced Complexity**: No need to manage multiple deployment branches
-
-### Enhanced Reliability
-- **Auditable Deployments**: Every deployment is tied to a specific version
-- **Consistent Testing**: Tests validate the exact version that will be deployed
-- **Improved Security**: Version-based deployments provide clear audit trails
-
-## Implementation Examples
-
-### Basic Implementation
-```yaml
-include:
-  - local: templates/AgileFlow.gitlab-ci.yml
-
-build:
-  stage: build
-  script:
-    - docker build -t myapp:${VERSION} .
-    - docker push myapp:${VERSION}
-  needs:
-    - agileflow
-
-deploy:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  needs:
-    - build
-```
-
-### Advanced Implementation with Multiple Services
-```yaml
-include:
-  - local: templates/AgileFlow.gitlab-ci.yml
-
-build-backend:
-  stage: build
-  script:
-    - docker build -t backend:${VERSION} ./backend
-    - docker push backend:${VERSION}
-  needs:
-    - agileflow
-
-build-frontend:
-  stage: build
-  script:
-    - docker build -t frontend:${VERSION} ./frontend
-    - docker push frontend:${VERSION}
-  needs:
-    - agileflow
-
-deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/backend backend=backend:${VERSION}
-    - kubectl set image deployment/frontend frontend=frontend:${VERSION}
-  environment:
-    name: staging
-  needs:
-    - build-backend
-    - build-frontend
-
-deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/backend backend=backend:${VERSION}
-    - kubectl set image deployment/frontend frontend=frontend:${VERSION}
-  environment:
-    name: production
-  when: manual
-  needs:
-    - build-backend
-    - build-frontend
-```
-
-## Best Practices
-
-### 1. Always Use the VERSION Variable
-```yaml
-# ✅ Good - Uses VERSION from AgileFlow
-- docker build -t myapp:${VERSION} .
-
-# ❌ Bad - Hardcoded or branch-based tagging
-- docker build -t myapp:latest .
-- docker build -t myapp:${CI_COMMIT_REF_SLUG} .
-```
-
-### 2. Proper Stage Dependencies
-```yaml
-# ✅ Good - Clear dependency chain
-deploy:
-  stage: deploy
-  needs:
-    - build
-
-# ❌ Bad - No dependencies specified
-deploy:
-  stage: deploy
-```
-
-### 3. Environment-Specific Deployments
-```yaml
-# ✅ Good - Same version, different environments
-deploy-staging:
-  environment:
-    name: staging
-
-deploy-production:
-  environment:
-    name: production
-  when: manual
-```
-
-### 4. Consistent Testing
-```yaml
-# ✅ Good - Test against deployed version
-test:
-  stage: test
-  script:
-    - ./run-tests.sh --version ${VERSION}
-  needs:
-    - deploy-staging
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**VERSION variable not available**
-- Ensure the `agileflow` job completed successfully
-- Check that the dotenv artifact is properly configured
-- Verify the job dependencies are set correctly
-
-**Build failures in later stages**
-- Check that the `VERSION` variable is being used correctly
-- Ensure all jobs have proper `needs` dependencies
-- Verify the artifact paths and variable names
-
-**Deployment inconsistencies**
-- Confirm that all deploy jobs use the same `${VERSION}` variable
-- Check that the same image tags are used across environments
-- Verify that the deployment scripts are identical
-
-### Debug Commands
-
-```yaml
-debug-version:
-  stage: build
-  script:
-    - echo "VERSION: ${VERSION}"
-    - echo "CI_COMMIT_REF_NAME: ${CI_COMMIT_REF_NAME}"
-    - echo "CI_COMMIT_SHA: ${CI_COMMIT_SHA}"
-  needs:
-    - agileflow
-```
-
-## Migration from Traditional CI/CD
-
-If you're currently using a traditional branch-based approach:
-
-1. **Include the template**: Add the include statement to your `.gitlab-ci.yml`
-2. **Update build jobs**: Modify build scripts to use `${VERSION}` instead of branch names
-3. **Consolidate deployments**: Deploy the same version to all environments
-4. **Update testing**: Ensure tests run against the deployed version
-5. **Remove branch logic**: Eliminate environment-specific branch handling
-
-## Support
-
-For issues or questions about the GitLab CI template:
-
-- Check the [main documentation](../README.md)
-- Review the [version-centric CI/CD approach](./version-centric-cicd.md)
-- Open an issue in the project repository
-- Join community discussions

package/src/git-utils.js

@@ -1,57 +0,0 @@
-'use strict';
-
-const { execSync } = require('child_process');
-const fs = require('fs');
-
-/**
- * Executes a shell command and returns the output.
- * @param {string} command - The command to execute
- * @param {Object} options - Execution options
- * @returns {string} Command output
- * @throws {Error} If command fails
- */
-function runWithOutput(command, options = {}) {
-  try {
-    return execSync(command, { stdio: 'pipe', encoding: 'utf8', ...options });
-  } catch (error) {
-    const captured = {
-      stdout: error?.stdout ? String(error.stdout) : '',
-      stderr: error?.stderr ? String(error.stderr) : '',
-      message: error?.message || 'Command failed',
-      status: typeof error?.status === 'number' ? error.status : 1,
-    };
-    try {
-      Object.defineProperty(error, '_captured', { value: captured });
-    } catch {
-      error._captured = captured;
-    }
-    throw error;
-  }
-}
-
-/**
- * Executes a shell command without returning output.
- * @param {string} command - The command to execute
- * @param {Object} options - Execution options
- * @throws {Error} If command fails
- */
-function run(command, options = {}) {
-  execSync(command, { stdio: 'pipe', ...options });
-}
-
-/**
- * Ensures the current directory is a git repository.
- * @throws {Error} If the current directory is not a git repository
- */
-function ensureGitRepo() {
-  if (!fs.existsSync('.git')) {
-    throw new Error('Current directory is not a git repository (missing .git directory).');
-  }
-}
-
-module.exports = {
-  run,
-  runWithOutput,
-  ensureGitRepo,
-};
-

package/src/local.js

@@ -1,17 +0,0 @@
-const { processVersionInfo } = require('./utils');
-
-async function main(branch = 'main') {
-  try {
-    const { previousVersion, nextVersion, commits, changelog } = await processVersionInfo(branch);
-    
-    console.log(`Previous version: ${previousVersion || 'none'}`);
-    console.log(`Next version: ${nextVersion}`);
-    console.log(`Commits since latest version: ${commits.length}`);
-    console.log(`\nChangelog:\n${changelog}`);
-  } catch (err) {
-    console.error('Error:', err.message);
-    process.exit(err.status || 1);
-  }
-}
-
-module.exports = main;

package/templates/agileflow-tagged.gitlab-ci.yml

@@ -1,66 +0,0 @@
-# AgileFlow GitLab CI Template
-#
-# This template provides a simplified, version-centric CI/CD pipeline that focuses on
-# version management rather than environment-based deployments. The pipeline consists
-# of 6 stages that work together to create a streamlined release process.
-#
-# Key Benefits:
-# - Version-centric approach: All deployments, tests, and operations are performed
-#   on well-identified versions rather than branch-based environments
-# - Simplified stages: Clear separation of concerns with minimal complexity
-# - Automated versioning: Integrates with AgileFlow to automatically generate
-#   semantic versions based on commit history
-# - Consistent deployments: All environments use the same version artifacts
-#
-# Stages Overview:
-# 1. version    - Generate semantic version and release notes
-# 2. test       - Run tests against source code before building
-# 3. build      - Build application artifacts and Docker images
-# 4. deploy     - Deploy to various environments using the generated version
-# 5. e2e        - Run end-to-end tests against deployed versions
-# 6. clean      - Cleanup temporary resources and artifacts
-#
-# Usage:
-# Include this template in your .gitlab-ci.yml:
-# include:
-#   - local: templates/AgileFlow.gitlab-ci.yml
-#
-# The agileflow job will automatically:
-# - Calculate the next semantic version based on commit history
-# - Generate comprehensive release notes from conventional commits
-# - Create and push version tags to the repository
-# - Make the VERSION variable available to subsequent stages
-
-stages:
-  - version   # Calculate the next semantic version based on commit history, 
-              # if there's a tag, it will use that as the version.
-
-              # Although the version is available in the $VERSION variable in all scenarios,
-              # the rest of the stages are recommended to run when there's a version tag pushed.
-              # This way the deployment process is version-centric.
-  - test      # Run tests against source code before building.
-  - build     # Build the image, and push to the registry.
-  - deploy    # Automatically deploy to DEV, manual deploy to STG and to PROD.
-  - e2e       # Run end-to-end tests against the deployed version.
-  - clean     # Cleanup temporary resources and artifacts.
-
-# Example: 
-# Run the job only when there's a version tag pushed. The version tags starts with v and semver.
-#
-# stage: build
-# rules:
-#   - if: $CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/
-
-# Version Generation Stage
-# This stage uses the AgileFlow tool to automatically generate semantic versions
-# and release notes based on the main branch's commit history. The VERSION
-# variable is made available as an artifact for use in subsequent stages.
-agileflow:
-  stage: version
-  image: registry.logickernel.com/kernel/agileflow:0.9.0
-  only:
-    - main
-  script:
-    - agileflow gitlab-ci
-  tags:
-    - agileflow

package/templates/agileflow.gitlab-ci.yml

@@ -1,64 +0,0 @@
-# AgileFlow GitLab CI Template
-#
-# This template provides a simplified, version-centric CI/CD pipeline that focuses on
-# version management rather than environment-based deployments. The pipeline consists
-# of 6 stages that work together to create a streamlined release process.
-#
-# Key Benefits:
-# - Version-centric approach: All deployments, tests, and operations are performed
-#   on well-identified versions rather than branch-based environments
-# - Simplified stages: Clear separation of concerns with minimal complexity
-# - Automated versioning: Integrates with AgileFlow to automatically generate
-#   semantic versions based on commit history
-# - Consistent deployments: All environments use the same version artifacts
-#
-# Stages Overview:
-# 1. version    - Generate semantic version and release notes
-# 2. test       - Run tests against source code before building
-# 3. build      - Build application artifacts and Docker images
-# 4. deploy     - Deploy to various environments using the generated version
-# 5. e2e        - Run end-to-end tests against deployed versions
-# 6. clean      - Cleanup temporary resources and artifacts
-#
-# Usage:
-# Include this template in your .gitlab-ci.yml:
-# include:
-#   - local: templates/AgileFlow.gitlab-ci.yml
-#
-# The agileflow job will automatically:
-# - Calculate the next semantic version based on commit history
-# - Generate comprehensive release notes from conventional commits
-# - Create and push version tags to the repository
-# - Make the VERSION variable available to subsequent stages
-
-stages:
-  - version   # Calculate the next semantic version based on commit history, 
-              # if there's a tag, it will use that as the version.
-
-              # Although the version is available in the $VERSION variable in all scenarios,
-              # the rest of the stages are recommended to run when there's a version tag pushed.
-              # This way the deployment process is version-centric.
-  - test      # Run tests against source code before building.
-  - build     # Build the image, and push to the registry.
-  - deploy    # Automatically deploy to DEV, manual deploy to STG and to PROD.
-  - e2e       # Run end-to-end tests against the deployed version.
-  - clean     # Cleanup temporary resources and artifacts.
-
-# Example: 
-# Run the job only when there's a version tag pushed. The version tags starts with v and semver.
-#
-# stage: build
-# rules:
-#   - if: $CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/
-
-# Version Generation Stage
-# This stage uses the AgileFlow tool to automatically generate semantic versions
-# and release notes based on the main branch's commit history. The VERSION
-# variable is made available as an artifact for use in subsequent stages.
-agileflow:
-  stage: version
-  image: registry.logickernel.com/kernel/agileflow:0.9.0
-  only:
-    - main
-  script:
-    - agileflow gitlab-ci