@logickernel/agileflow 0.1.0 → 0.2.0

package/docs/getting-started.md

@@ -5,205 +5,189 @@ Welcome to AgileFlow! This guide will help you get up and running with AgileFlow
 ## What You'll Learn
 
 By the end of this guide, you'll have:
-- ✅ AgileFlow installed in your GitLab project
-- ✅ A working CI/CD pipeline that automatically generates versions
-- ✅ Understanding of how the version-centric approach works
-- ✅ Confidence to customize the pipeline for your needs
+- AgileFlow running in your project
+- Automatic semantic versioning based on conventional commits
+- Understanding of how the version-centric approach works
 
 ## Prerequisites
 
 Before you begin, ensure you have:
-- A GitLab project with CI/CD enabled
-- Access to modify `.gitlab-ci.yml` files and CI/CD variables
-- Basic understanding of Git and CI/CD concepts
+- Node.js 14+ installed (for local usage)
+- A Git repository with commit history
+- Basic understanding of Git and conventional commits
 
-## Quick Start (5 minutes)
+## Quick Start
 
-### Step 1: Include the AgileFlow Template
+### Local Usage
 
-Add this line to the top of your `.gitlab-ci.yml` file:
+Run AgileFlow directly with npx to see your current and next version:
 
-```yaml
-include:
-  - remote: https://code.logickernel.com/kernel/agileflow/-/raw/main/templates/AgileFlow.gitlab-ci.yml
+```bash
+npx @logickernel/agileflow
 ```
 
-### Step 2: Configure the AGILEFLOW_TOKEN
-
-AgileFlow needs a GitLab access token to create version tags via the API. Set this in your GitLab project:
-
-1. Go to **Settings > CI/CD > Variables**
-2. Add the `AGILEFLOW_TOKEN` variable:
-
-| Variable | Value | Type | Protect | Mask |
-|----------|-------|------|---------|------|
-| `AGILEFLOW_TOKEN` | Your GitLab API token | Variable | Yes | No |
-
-**Creating the AGILEFLOW_TOKEN:**
-- **Project Access Token (Recommended)**: Go to **Settings > Access Tokens** in your project
-- **Personal Access Token**: Go to your user **Settings > Access Tokens**
-- Set **Name**: `AgileFlow Bot`, **Scopes**: `api`, **Role**: `maintainer` or higher
-
-### Step 3: Add Your First Job
-
-Below the include statement, add a simple build job:
-
-```yaml
-build:
-  stage: build
-  script:
-    - echo "Building version ${VERSION}"
-    - docker build -t myapp:${VERSION} .
-    - docker push myapp:${VERSION}
-  needs:
-    - agileflow
+Example output:
 ```
+Current version: v1.2.3
+Next version: v1.2.4
+Commits since current version: 3
 
-### Step 4: Commit and Push
+Changelog:
+### fix
+- resolve authentication issue
+- correct null handling in user lookup
 
-```bash
-git add .gitlab-ci.yml
-git commit -m "feat: add AgileFlow CI/CD pipeline"
-git push
+### docs
+- update README with usage examples
 ```
 
-That's it! 🎉 Your first AgileFlow pipeline is now running.
+### Quiet Mode
 
-## What Happens Next
+Use `--quiet` to only output the next version (useful for scripts):
 
-1. **Pipeline Starts**: GitLab CI automatically detects your changes
-2. **Version Generation**: AgileFlow analyzes your commit history and generates the next semantic version
-3. **Build Process**: Your build job runs with the generated version
-4. **Version Tag**: A new version tag is created via GitLab API (not git push)
-
-## Understanding the Pipeline
+```bash
+VERSION=$(npx @logickernel/agileflow --quiet)
+echo "Next version will be: $VERSION"
+```
 
-Your pipeline now has 6 stages:
+## CI/CD Integration
+
+### GitLab CI
+
+1. **Configure the AGILEFLOW_TOKEN**
+
+   Go to **Settings > CI/CD > Variables** and add:
+
+   | Variable | Value | Protect | Mask |
+   |----------|-------|---------|------|
+   | `AGILEFLOW_TOKEN` | Your GitLab API token | Yes | Yes |
+
+   Create the token at **Settings > Access Tokens** with:
+   - **Name**: AgileFlow Bot
+   - **Role**: Maintainer
+   - **Scopes**: api
+
+2. **Add AgileFlow to your pipeline**
+
+   ```yaml
+   stages:
+     - version
+     - build
+
+   agileflow:
+     stage: version
+     image: node:20-alpine
+     script:
+       - npx @logickernel/agileflow gitlab
+     only:
+       - main
+   
+   build:
+     stage: build
+     script:
+       - echo "Building..."
+     needs:
+       - agileflow
+   ```
+
+### GitHub Actions
+
+1. **Configure the AGILEFLOW_TOKEN**
+
+   Go to **Settings > Secrets and variables > Actions** and add a secret:
+   - **Name**: `AGILEFLOW_TOKEN`
+   - **Value**: A Personal Access Token with `contents: write` permission
+
+2. **Add AgileFlow to your workflow**
+
+   ```yaml
+   name: Release
+   on:
+     push:
+       branches: [main]
+
+   jobs:
+     version:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+           with:
+             fetch-depth: 0  # Required for version history
+         
+         - uses: actions/setup-node@v4
+           with:
+             node-version: '20'
+         
+         - name: Create version tag
+           env:
+             AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
+           run: npx @logickernel/agileflow github
+   ```
+
+### Native Git Push
+
+If you prefer using native git commands (requires git credentials):
 
-```
-version → test → build → deploy → e2e → clean
+```bash
+npx @logickernel/agileflow push
 ```
 
-- **version**: AgileFlow generates semantic versions automatically using GitLab API
-- **test**: Run tests against source code before building (add your test jobs here)
-- **build**: Your application builds with the generated version
-- **deploy**: Deploy the versioned artifacts (add your deployment jobs here)
-- **e2e**: Run end-to-end tests against deployed versions (add your e2e test jobs here)
-- **clean**: Cleanup temporary resources (optional)
+This creates an annotated tag and pushes it to the origin remote.
 
 ## How AgileFlow Works
 
-### No Git Push Required
-- **AgileFlow uses GitLab API** to create version tags
-- **No repository write permissions** needed for CI/CD jobs
-- **More secure** than traditional git push approaches
-- **Works with protected branches** without special permissions
-
-### Version Generation
-- **Analyzes commit messages** since the last version
-- **Uses conventional commits** to determine version bump type
-- **Creates semantic versions** automatically (v1.0.0, v1.0.1, etc.)
-- **Generates release notes** from commit history
+### Version Calculation
+- Analyzes commit messages since the last version tag
+- Uses conventional commits to determine version bump type
+- Generates semantic versions automatically (v1.0.0, v1.0.1, etc.)
 
-## Next Steps
+### Version Bump Rules
 
-Now that you have the basics working, explore these areas:
-
-### 1. Add Deployment Jobs
-```yaml
-deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: staging
-  needs:
-    - build
-```
+| Commit Type | Example | Version Bump |
+|-------------|---------|--------------|
+| Breaking change | `feat!: redesign API` | Major (1.0.0 → 2.0.0) |
+| Feature | `feat: add login` | Minor (1.0.0 → 1.1.0) |
+| Fix | `fix: resolve crash` | Patch (1.0.0 → 1.0.1) |
+| Performance | `perf: optimize query` | Patch |
+| Refactor | `refactor: simplify logic` | Patch |
+| Docs only | `docs: update README` | No bump |
+| Chore | `chore: update deps` | No bump |
 
-### 2. Add Testing
-```yaml
-# Unit tests run before building
-unit-tests:
-  stage: test
-  script:
-    - npm test
-    - npm run lint
-  needs:
-    - agileflow
-
-# Integration tests run after deployment
-integration-tests:
-  stage: e2e
-  script:
-    - ./run-tests.sh --version ${VERSION}
-  needs:
-    - deploy-staging
-```
+### No Bump Needed
 
-### 3. Customize for Multiple Services
-```yaml
-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
-```
+If all commits since the last version are docs/chore/style types, AgileFlow will report "no bump needed" and skip tag creation in push commands.
 
 ## Common Questions
 
 ### Q: How does AgileFlow determine the next version?
-A: AgileFlow analyzes your commit messages using conventional commits. Each merge to main increments the patch version (v1.0.0 → v1.0.1). Use `feat:` for minor versions and `feat!:` for major versions.
-
-### Q: Can I use this with existing CI/CD pipelines?
-A: Yes! AgileFlow is designed to work alongside existing pipelines. Just include the template and gradually migrate your jobs to use the `${VERSION}` variable.
+A: AgileFlow analyzes your commit messages using conventional commits. Features bump the minor version, fixes bump the patch version, and breaking changes bump the major version.
 
-### Q: What if I need different versions for different environments?
-A: AgileFlow generates one version per pipeline run. Deploy the same version everywhere to eliminate environment drift. Use environment-specific configuration instead of different versions.
+### Q: What if there's no version tag yet?
+A: AgileFlow starts from v0.0.0 and calculates the first version based on your commits.
 
-### Q: How do I rollback to a previous version?
-A: Simply redeploy the previous version tag. Since all environments use the same version, rollbacks are consistent and predictable.
+### Q: Can I use this locally before pushing?
+A: Yes! Run `npx @logickernel/agileflow` to preview the next version without creating any tags.
 
-### Q: Why doesn't AgileFlow need git push permissions?
-A: AgileFlow uses the GitLab API to create tags remotely instead of pushing them with git commands. This is more secure and doesn't require repository write access.
+### Q: What happens if no version bump is needed?
+A: The push commands (`push`, `gitlab`, `github`) will skip tag creation and exit successfully.
 
 ## Troubleshooting
 
-### Pipeline Fails on Version Stage
-- Check that the `AGILEFLOW_TOKEN` is set correctly
-- Ensure the token has `api` scope and `maintainer` role
-- Verify your GitLab CI/CD settings
-- Check the `agileflow` job logs for specific errors
-
-### VERSION Variable Not Available
-- Ensure the `agileflow` job completed successfully
-- Check that your jobs have `needs: - agileflow` dependency
-- Verify the dotenv artifact is properly configured
+### "Not a git repository" Error
+- Ensure you're running AgileFlow from within a git repository
+- Check that the `.git` directory exists
 
-### Build Jobs Fail
-- Check that you're using `${VERSION}` correctly
-- Ensure proper job dependencies with `needs:`
-- Verify your build scripts work with the version variable
+### "AGILEFLOW_TOKEN not set" Error
+- Ensure the environment variable is configured in your CI/CD settings
+- Verify the token has the required permissions
 
-## Getting Help
+### No Version Bump Detected
+- Ensure you're using conventional commit format
+- Check that there are commits since the last version tag
+- Verify commits include bump-triggering types (feat, fix, perf, etc.)
 
-- 📚 [Complete Documentation](./README.md) - Browse all available guides
-- 🔧 [GitLab CI Template Reference](./gitlab-ci-template.md) - Detailed template documentation
-- 💡 [Version-Centric CI/CD Approach](./version-centric-cicd.md) - Deep dive into the methodology
-- 🐛 [Troubleshooting](./troubleshooting.md) - Common issues and solutions
-
-## Congratulations! 🎉
-
-You've successfully set up AgileFlow and are now using a modern, version-centric CI/CD approach. Your deployments will be more predictable, your rollbacks will be simpler, and your team will have better visibility into what's running where.
+## Next Steps
 
-Ready to dive deeper? Explore the [advanced topics](./README.md#advanced-topics) or customize your pipeline further!
+- Read the [CLI Reference](./cli-reference.md) for all available commands
+- Learn about [Conventional Commits](./conventional-commits.md)
+- Explore [Version-Centric CI/CD](./version-centric-cicd.md) methodology

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logickernel/agileflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Automatic semantic versioning and changelog generation based on conventional commits",
   "main": "src/index.js",
   "bin": {

package/src/git-push.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { run } = require('./utils');
+
+/**
+ * Creates an annotated tag and pushes it to the remote repository.
+ * Uses native git commands - requires git credentials to be configured.
+ * @param {string} tagName - The tag name (e.g., "v1.2.3")
+ * @param {string} message - The tag message (changelog)
+ * @returns {Promise<void>}
+ */
+async function pushTag(tagName, message) {
+  const safeTag = String(tagName).replace(/"/g, '\\"');
+  const safeMsg = String(message).replace(/"/g, '\\"');
+  
+  // Create annotated tag
+  run(`git tag -a "${safeTag}" -m "${safeMsg}"`);
+  
+  // Push to origin
+  run(`git push origin "${safeTag}"`);
+}
+
+module.exports = {
+  pushTag,
+};
+

package/src/github-push.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const https = require('https');
+
+/**
+ * Creates a tag via the GitHub API.
+ * GitHub requires creating a tag object first, then a reference.
+ * @param {string} tagName - The tag name
+ * @param {string} message - The tag message
+ * @param {string} repository - GitHub repository (e.g., "owner/repo")
+ * @param {string} accessToken - GitHub access token
+ * @param {string} commitSha - The commit SHA to tag
+ * @returns {Promise<Object>} API response
+ */
+async function createTagViaAPI(tagName, message, repository, accessToken, commitSha) {
+  // Step 1: Create an annotated tag object
+  const tagObject = await makeRequest({
+    method: 'POST',
+    path: `/repos/${repository}/git/tags`,
+    accessToken,
+    body: {
+      tag: tagName,
+      message: message,
+      object: commitSha,
+      type: 'commit',
+    },
+  });
+  
+  // Step 2: Create a reference pointing to the tag object
+  await makeRequest({
+    method: 'POST',
+    path: `/repos/${repository}/git/refs`,
+    accessToken,
+    body: {
+      ref: `refs/tags/${tagName}`,
+      sha: tagObject.sha,
+    },
+  });
+  
+  return tagObject;
+}
+
+/**
+ * Makes an HTTPS request to the GitHub API.
+ * @param {{method: string, path: string, accessToken: string, body?: Object}} options
+ * @returns {Promise<Object>}
+ */
+function makeRequest({ method, path, accessToken, body }) {
+  return new Promise((resolve, reject) => {
+    const postData = body ? JSON.stringify(body) : '';
+    
+    const options = {
+      hostname: 'api.github.com',
+      port: 443,
+      path: path,
+      method: method,
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Accept': 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'User-Agent': 'AgileFlow',
+        'Content-Type': 'application/json',
+        ...(body && { 'Content-Length': Buffer.byteLength(postData) }),
+      },
+    };
+    
+    const req = https.request(options, (res) => {
+      let data = '';
+      
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(data ? JSON.parse(data) : {});
+        } else {
+          let errorMessage = `GitHub API request failed with status ${res.statusCode}`;
+          try {
+            const errorData = JSON.parse(data);
+            if (errorData.message) {
+              errorMessage += `: ${errorData.message}`;
+            }
+            if (res.statusCode === 401) {
+              errorMessage += '\n\nAuthentication failed. The AGILEFLOW_TOKEN is invalid or expired.';
+              errorMessage += '\nTo fix this:';
+              errorMessage += '\n1. Go to your repository Settings > Secrets and variables > Actions';
+              errorMessage += '\n2. Create a secret named AGILEFLOW_TOKEN with a Personal Access Token';
+              errorMessage += '\n3. The token needs "contents: write" permission';
+            } else if (res.statusCode === 403) {
+              errorMessage += '\n\nPermission denied. The AGILEFLOW_TOKEN needs "contents: write" permission.';
+              errorMessage += '\nTo fix this:';
+              errorMessage += '\n1. Ensure your token has "contents: write" scope';
+              errorMessage += '\n2. If using GITHUB_TOKEN, add permissions to your workflow';
+            } else if (res.statusCode === 422) {
+              errorMessage += '\n\nThe tag may already exist or the reference is invalid.';
+            }
+          } catch {
+            if (data) {
+              errorMessage += `\nResponse: ${data}`;
+            }
+          }
+          reject(new Error(errorMessage));
+        }
+      });
+    });
+    
+    req.on('error', (error) => {
+      reject(new Error(`Network error: ${error.message}`));
+    });
+    
+    if (postData) {
+      req.write(postData);
+    }
+    req.end();
+  });
+}
+
+/**
+ * Pushes a tag to GitHub via the API.
+ * Requires AGILEFLOW_TOKEN environment variable.
+ * Uses GITHUB_REPOSITORY and GITHUB_SHA from GitHub Actions environment.
+ * @param {string} tagName - The tag name
+ * @param {string} message - The tag message
+ * @returns {Promise<void>}
+ */
+async function pushTag(tagName, message) {
+  const accessToken = process.env.AGILEFLOW_TOKEN;
+  const repository = process.env.GITHUB_REPOSITORY;
+  const commitSha = process.env.GITHUB_SHA;
+  
+  if (!accessToken) {
+    throw new Error(
+      `AGILEFLOW_TOKEN environment variable is required but not set.\n\n` +
+      `To fix this:\n` +
+      `1. Create a Personal Access Token with "contents: write" permission\n` +
+      `2. Add it as a repository secret named AGILEFLOW_TOKEN\n` +
+      `3. In your workflow, add: env: AGILEFLOW_TOKEN: \${{ secrets.AGILEFLOW_TOKEN }}`
+    );
+  }
+  
+  if (!repository) {
+    throw new Error('GITHUB_REPOSITORY environment variable is not set. Are you running inside GitHub Actions?');
+  }
+  
+  if (!commitSha) {
+    throw new Error('GITHUB_SHA environment variable is not set. Are you running inside GitHub Actions?');
+  }
+  
+  await createTagViaAPI(tagName, message || tagName, repository, accessToken, commitSha);
+}
+
+module.exports = {
+  pushTag,
+};
+

package/src/gitlab-push.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const https = require('https');
+
+/**
+ * Creates a tag via the GitLab API.
+ * @param {string} tagName - The tag name
+ * @param {string} message - The tag message
+ * @param {string} projectPath - GitLab project path (e.g., "group/project")
+ * @param {string} serverHost - GitLab server hostname
+ * @param {string} accessToken - GitLab access token
+ * @param {string} ref - Git ref to tag (branch name or commit SHA)
+ * @returns {Promise<Object>} API response
+ */
+function createTagViaAPI(tagName, message, projectPath, serverHost, accessToken, ref) {
+  return new Promise((resolve, reject) => {
+    const projectId = encodeURIComponent(projectPath);
+    
+    const postData = JSON.stringify({
+      tag_name: tagName,
+      ref: ref,
+      message: message,
+    });
+    
+    const options = {
+      hostname: serverHost,
+      port: 443,
+      path: `/api/v4/projects/${projectId}/repository/tags`,
+      method: 'POST',
+      headers: {
+        'PRIVATE-TOKEN': accessToken,
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+      },
+    };
+    
+    const req = https.request(options, (res) => {
+      let data = '';
+      
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(JSON.parse(data));
+        } else {
+          let errorMessage = `GitLab API request failed with status ${res.statusCode}`;
+          try {
+            const errorData = JSON.parse(data);
+            if (errorData.message) {
+              errorMessage += `: ${JSON.stringify(errorData.message)}`;
+            }
+            if (res.statusCode === 401) {
+              errorMessage += '\n\nAuthentication failed. The AGILEFLOW_TOKEN is invalid or expired.';
+              errorMessage += '\nTo fix this:';
+              errorMessage += '\n1. Go to your project Settings > Access Tokens';
+              errorMessage += '\n2. Check the expiration date of your AgileFlow Bot token';
+              errorMessage += '\n3. If expired, create a new token or extend the existing one';
+            } else if (res.statusCode === 403) {
+              errorMessage += '\n\nPermission denied. The AGILEFLOW_TOKEN needs "api" scope and maintainer role.';
+              errorMessage += '\nTo fix this:';
+              errorMessage += '\n1. Go to your project Settings > Access Tokens';
+              errorMessage += '\n2. Ensure your AgileFlow Bot token has "api" scope and maintainer role';
+              errorMessage += '\n3. If permissions are insufficient, create a new token with proper permissions';
+            }
+          } catch {
+            if (data) {
+              errorMessage += `\nResponse: ${data}`;
+            }
+          }
+          reject(new Error(errorMessage));
+        }
+      });
+    });
+    
+    req.on('error', (error) => {
+      reject(new Error(`Network error: ${error.message}`));
+    });
+    
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Pushes a tag to GitLab via the API.
+ * Requires AGILEFLOW_TOKEN environment variable.
+ * Uses CI_SERVER_HOST and CI_PROJECT_PATH from GitLab CI environment.
+ * @param {string} tagName - The tag name
+ * @param {string} message - The tag message
+ * @returns {Promise<void>}
+ */
+async function pushTag(tagName, message) {
+  const accessToken = process.env.AGILEFLOW_TOKEN;
+  const serverHost = process.env.CI_SERVER_HOST;
+  const projectPath = process.env.CI_PROJECT_PATH;
+  const commitSha = process.env.CI_COMMIT_SHA;
+  
+  if (!accessToken) {
+    const projectUrl = serverHost && projectPath ? `https://${serverHost}/${projectPath}` : 'your-project';
+    const projectTokenUrl = `${projectUrl}/-/settings/access_tokens`;
+    const cicdUrl = `${projectUrl}/-/settings/ci_cd#js-cicd-variables-settings`;
+    
+    throw new Error(
+      `AGILEFLOW_TOKEN environment variable is required but not set.\n\n` +
+      `To fix this:\n` +
+      `1. Create a project access token: ${projectTokenUrl}\n` +
+      `   - Name: AgileFlow Bot\n` +
+      `   - Role: maintainer\n` +
+      `   - Scopes: api\n` +
+      `2. Add it as a CI/CD variable: ${cicdUrl}\n` +
+      `   - Variable key: AGILEFLOW_TOKEN\n` +
+      `   - Protect variable: Yes (recommended)`
+    );
+  }
+  
+  if (!serverHost) {
+    throw new Error('CI_SERVER_HOST environment variable is not set. Are you running inside GitLab CI?');
+  }
+  
+  if (!projectPath) {
+    throw new Error('CI_PROJECT_PATH environment variable is not set. Are you running inside GitLab CI?');
+  }
+  
+  if (!commitSha) {
+    throw new Error('CI_COMMIT_SHA environment variable is not set. Are you running inside GitLab CI?');
+  }
+  
+  await createTagViaAPI(tagName, message || tagName, projectPath, serverHost, accessToken, commitSha);
+}
+
+module.exports = {
+  pushTag,
+};
+