@logickernel/agileflow 0.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,341 @@
+# Troubleshooting Guide
+
+This guide helps you resolve common issues when using AgileFlow. If you encounter a problem not covered here, check the community discussions or open an issue in the project repository.
+
+## Quick Diagnosis
+
+### Check Pipeline Status
+
+First, verify your pipeline status:
+
+```bash
+# Check if AgileFlow job completed successfully
+gitlab-ci status
+
+# View pipeline logs
+gitlab-ci logs agileflow
+
+# Check if VERSION variable is available
+echo $VERSION
+```
+
+### Common Symptoms
+
+- **Pipeline fails on version stage**
+- **VERSION variable not available**
+- **Build jobs fail with version errors**
+- **Deployment inconsistencies**
+- **Release notes not generated**
+
+## Installation Issues
+
+### Job Token Permissions Not Available
+
+**Problem**: You don't see the "Allow Git push requests to the repository" option in GitLab CI/CD settings.
+
+**Solution**:
+1. Check if you're using a self-managed GitLab instance
+2. Enable the feature flag `allow_push_repository_for_job_token`
+3. Ensure you have admin access to the GitLab instance
+
+```bash
+# For self-managed GitLab, enable the feature flag
+sudo gitlab-rake gitlab:features:enable allow_push_repository_for_job_token
+```
+
+**Alternative**: Use a personal access token with write permissions to the repository.
+
+### Template Include Fails
+
+**Problem**: The AgileFlow template include statement fails with a network error.
+
+**Solutions**:
+1. **Check network connectivity** to `code.logickernel.com`
+2. **Use local template** if remote access is restricted:
+
+```yaml
+# .gitlab-ci.yml
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+```
+
+3. **Copy template locally** and include from your repository:
+
+```bash
+# Download template to your repository
+curl -o templates/AgileFlow.gitlab-ci.yml \
+  https://code.logickernel.com/kernel/agileflow/-/raw/main/templates/AgileFlow.gitlab-ci.yml
+```
+
+### Docker Image Pull Fails
+
+**Problem**: Cannot pull the AgileFlow Docker image.
+
+**Solutions**:
+1. **Check Docker daemon** is running
+2. **Verify image name** and tag
+3. **Check registry access** and authentication
+4. **Use alternative image** if available
+
+```bash
+# Test Docker connectivity
+docker pull hello-world
+
+# Check AgileFlow image availability
+docker pull registry.logickernel.com/kernel/agileflow:latest
+```
+
+## Version Generation Issues
+
+### VERSION Variable Not Available
+
+**Problem**: The `${VERSION}` variable is not available in subsequent pipeline stages.
+
+**Causes and Solutions**:
+
+1. **AgileFlow job failed**
+   ```bash
+   # Check agileflow job status
+   gitlab-ci logs agileflow
+   
+   # Ensure job completed successfully
+   gitlab-ci status agileflow
+   ```
+
+2. **Missing job dependency**
+   ```yaml
+   # ✅ Good - Proper dependency
+   build:
+     stage: build
+     needs:
+       - agileflow
+   
+   # ❌ Bad - No dependency specified
+   build:
+     stage: build
+   ```
+
+### Version Not Generated
+
+**Problem**: AgileFlow doesn't create a new version tag.
+
+**Causes and Solutions**:
+
+1. **No conventional commits detected**
+   ```bash
+   # Check commit messages
+   git log --oneline -10
+   
+   # Use conventional commit format
+   git commit -m "feat: add new feature"
+   git commit -m "fix: resolve bug"
+   ```
+
+2. **No merge to main branch**
+   ```bash
+   # Verify you're on main branch
+   git branch
+   
+   # Check if changes were merged
+   git log --oneline --graph
+   ```
+
+### Incorrect Version Bumping
+
+**Problem**: AgileFlow generates the wrong version number.
+
+**Causes and Solutions**:
+
+1. **Commit type not recognized**
+   ```bash
+   # Use recognized commit types
+   feat: new feature          # Minor version bump
+   fix: bug fix              # Patch version bump
+   perf: performance improvement # Patch version bump
+refactor: code refactoring    # Patch version bump
+build: build system change    # Patch version bump
+ci: CI/CD change             # Patch version bump
+test: test additions/changes  # Patch version bump
+revert: revert commit         # Patch version bump
+   feat!: breaking change    # Major version bump
+   ```
+
+2. **Breaking change not properly marked**
+   ```bash
+   # Use exclamation mark or footer
+   feat!: remove deprecated API
+   
+   # Or use footer
+   feat: change API format
+   
+   BREAKING CHANGE: API format changed from v1 to v2
+   ```
+
+3. **Version calculation logic issues**
+   ```bash
+   # Check commit history
+   git log --oneline --since="1 week ago"
+   
+   # Verify conventional commit format
+   git log --grep="^feat\|^fix\|^perf\|^refactor"
+   ```
+
+## Pipeline Issues
+
+### Build Stage Failures
+
+**Problem**: Build jobs fail with version-related errors.
+
+**Solutions**:
+
+1. **Check VERSION variable usage**
+   ```yaml
+   # ✅ Good - Proper variable usage
+   build:
+     script:
+       - docker build -t myapp:${VERSION} .
+   
+   # ❌ Bad - Hardcoded or incorrect variable
+   build:
+     script:
+       - docker build -t myapp:latest .
+       - docker build -t myapp:$VERSION .
+   ```
+
+2. **Verify job dependencies**
+   ```yaml
+   # Ensure build depends on agileflow
+   build:
+     stage: build
+     needs:
+       - agileflow
+     script:
+       - echo "Building version ${VERSION}"
+   ```
+
+3. **Check variable expansion**
+   ```yaml
+   # Test variable availability
+   build:
+     script:
+       - echo "VERSION: ${VERSION}"
+       - echo "CI_COMMIT_REF_NAME: ${CI_COMMIT_REF_NAME}"
+       - docker build -t myapp:${VERSION} .
+   ```
+
+## Release Notes Issues
+
+### Empty Release Notes
+
+**Problem**: Release notes are not generated or are empty.
+
+**Solutions**:
+
+1. **Check commit message format**
+   ```bash
+   # View recent commits
+   git log --oneline -10
+   
+   # Ensure conventional commit format
+   git log --grep="^feat\|^fix\|^perf\|^refactor\|^docs\|^test\|^build\|^ci\|^chore\|^style"
+   ```
+
+2. **Verify AgileFlow configuration**
+   ```javascript
+   // agileflow.config.js
+   module.exports = {
+     releaseNotes: {
+       enabled: true,
+       format: 'conventional',
+       includeBody: true,
+       groupByType: true
+     }
+   };
+   ```
+
+3. **Check tag creation**
+   ```bash
+   # List all tags
+   git tag --sort=-version:refname
+   
+   # View tag message
+   git tag -l -n99 v1.2.3
+   ```
+
+### Malformed Release Notes
+
+**Problem**: Release notes are generated but poorly formatted.
+
+**Solutions**:
+
+1. **Improve commit message quality**
+   ```bash
+   # ✅ Good commit messages
+   feat(auth): add OAuth2 login support
+   fix(api): handle null user ID gracefully
+   docs: update installation guide
+   
+   # ❌ Poor commit messages
+   add oauth
+   fix bug
+   update docs
+   ```
+
+2. **Use consistent scopes**
+   ```bash
+   # Consistent scope usage
+   feat(auth): add OAuth2 login
+   feat(auth): implement JWT refresh
+   fix(auth): handle expired tokens
+   ```
+
+3. **Include meaningful descriptions**
+   ```bash
+   # Descriptive commit messages
+   feat(auth): add OAuth2 login support with Google and GitHub providers
+   
+   Implements OAuth2 authentication flow supporting multiple
+   identity providers. Includes proper error handling and
+   user session management.
+   ```
+
+## Debugging Techniques
+
+### Enable Debug Logging
+
+```yaml
+agileflow:
+  variables:
+    AGILEFLOW_DEBUG: "true"
+    AGILEFLOW_LOG_LEVEL: "debug"
+  script:
+    - agileflow gitlab-ci --verbose
+```
+
+### Check Environment Variables
+
+```yaml
+debug-env:
+  stage: build
+  script:
+    - echo "VERSION: ${VERSION}"
+    - echo "CI_COMMIT_REF_NAME: ${CI_COMMIT_REF_NAME}"
+    - echo "CI_COMMIT_SHA: ${CI_COMMIT_SHA}"
+    - env | grep -E "(VERSION|CI_|AGILEFLOW_)"
+  needs:
+    - agileflow
+```
+
+### Verify Git State
+
+```yaml
+verify-git:
+  stage: build
+  script:
+    - git status
+    - git log --oneline -5
+    - git tag --sort=-version:refname | head -5
+    - git remote -v
+  needs:
+    - agileflow
+```

package/docs/version-centric-cicd.md

@@ -0,0 +1,166 @@
+# Version-Centric CI/CD Approach
+
+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.
+
+## Traditional Git-Based Flows vs. AgileFlow
+
+### Traditional Approach (Branch-Based Environments)
+Traditional CI/CD pipelines often rely on branch-based environment management:
+
+```mermaid
+graph LR
+    A[main branch] --> B[staging branch]
+    B --> C[production branch]
+    D[feature branch] --> A
+    E[hotfix branch] --> A
+```
+
+**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]
+```
+
+**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
+
+## Simplified Pipeline Stages
+
+AgileFlow's CI/CD pipeline consists of just 6 focused stages:
+
+### 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
+
+### 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
+
+### 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
+
+### 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")
+
+### 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
+
+### 6. **Clean** Stage
+- **Purpose**: Cleanup temporary resources and artifacts
+- **Maintenance**: Remove old Docker images, temporary files, etc.
+- **Optimization**: Keep only necessary version artifacts
+
+## Real-World Example
+
+Here's how the version-centric approach works in practice:
+
+```yaml
+# .gitlab-ci.yml
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+
+# Test stage runs tests against source code
+test:
+  stage: test
+  script:
+    - npm test
+    - npm run lint
+
+# Build stage uses VERSION from agileflow job
+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
+
+deploy-staging:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+  environment:
+    name: staging
+  when: manual
+  needs:
+    - build
+
+deploy-production:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+  environment:
+    name: production
+  when: manual
+  needs:
+    - build
+
+# E2E stage validates the deployed version
+integration-tests:
+  stage: e2e
+  script:
+    - ./run-tests.sh --version ${VERSION}
+  needs:
+    - deploy-testing
+```
+
+## 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
+
+## Migration Path
+
+If you're currently using a traditional branch-based approach:
+
+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
+
+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.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@logickernel/agileflow",
+  "version": "0.1.0",
+  "description": "Automatic semantic versioning and changelog generation based on conventional commits",
+  "main": "src/index.js",
+  "bin": {
+    "agileflow": "bin/agileflow"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "semantic-versioning",
+    "conventional-commits",
+    "changelog",
+    "versioning",
+    "git",
+    "ci-cd",
+    "gitlab",
+    "automation",
+    "release-management"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@code.logickernel.com:kernel/agileflow.git"
+  },
+  "author": "",
+  "license": "ISC"
+}

package/src/git-utils.js

@@ -0,0 +1,57 @@
+'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/index.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const { version } = require('../package.json');
+
+function printHelp() {
+  console.log(`agileflow - Automatic semantic versioning and changelog generation
+
+Usage:
+  agileflow [options]
+  agileflow <command>
+
+Commands:
+  gitlab-ci       Configure git, compute semver tag, and push to GitLab (CI mode)
+
+Options:
+  --branch <name>  Allow running on specified branch (default: main)
+  -h, --help       Show this help message
+  -v, --version    Show version number
+
+Examples:
+  agileflow                   # Run on main branch
+  agileflow --branch develop  # Run on develop branch
+  agileflow gitlab-ci
+
+For more information, visit: https://code.logickernel.com/kernel/agileflow
+`);
+}
+
+function parseArgs(args) {
+  const parsed = { branch: 'main' };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--branch' && i + 1 < args.length) {
+      parsed.branch = args[i + 1];
+      i++;
+    }
+  }
+  return parsed;
+}
+
+async function runLocal(args) {
+  const { branch } = parseArgs(args);
+  const localMain = require('./local.js');
+  await localMain(branch);
+}
+
+async function main() {
+  const [, , cmd, ...rest] = process.argv;
+
+  // Handle help
+  if (cmd === '-h' || cmd === '--help' || cmd === 'help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Handle version
+  if (cmd === '-v' || cmd === '--version' || cmd === 'version') {
+    console.log(version);
+    process.exit(0);
+  }
+
+  // Handle gitlab-ci command
+  if (cmd === 'gitlab-ci') {
+    console.error('Error: gitlab-ci command is not yet implemented');
+    console.error('This feature will be available in a future release.');
+    process.exit(1);
+  }
+
+  // Unknown command
+  if (cmd && !cmd.startsWith('--')) {
+    console.error(`Error: Unknown command "${cmd}"`);
+    console.error();
+    printHelp();
+    process.exit(1);
+  }
+
+  // Default: run version calculation
+  await runLocal(cmd ? [cmd, ...rest] : rest);
+}
+
+process.on('unhandledRejection', (err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(err.status || 1);
+});

package/src/local.js

@@ -0,0 +1,17 @@
+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;