@logickernel/agileflow 0.2.2 → 0.4.1

package/docs/cli-reference.md

@@ -4,7 +4,7 @@ AgileFlow provides a simple command-line interface for automatic semantic versio
 
 ## Installation
 
-AgileFlow can be run directly with npx (no installation required):
+Run directly with npx (no installation required):
 
 ```bash
 npx @logickernel/agileflow
@@ -17,18 +17,13 @@ npm install -g @logickernel/agileflow
 agileflow
 ```
 
-## Usage
-
-```bash
-agileflow [options]
-agileflow <command>
-```
+---
 
 ## Commands
 
 ### Default (no command)
 
-Analyzes the current branch and displays version information without creating any tags.
+Analyzes the repository and displays version information without creating tags.
 
 ```bash
 agileflow
@@ -50,7 +45,7 @@ Changelog:
 
 ### push
 
-Creates an annotated git tag and pushes it to the origin remote using native git commands.
+Creates an annotated git tag and pushes it to the origin remote.
 
 ```bash
 agileflow push
@@ -58,31 +53,30 @@ agileflow push
 
 **Requirements:**
 - Git credentials configured for push access
-- No additional environment variables needed
 
 **Behavior:**
 - Calculates the next version
 - Creates an annotated tag with the changelog as the message
 - Pushes the tag to origin
-- If no version bump is needed, skips tag creation
+- Skips if no version bump is needed
 
 ### gitlab
 
-Creates a version tag via the GitLab API. Designed for use in GitLab CI pipelines.
+Creates a version tag via the GitLab API. Designed for GitLab CI pipelines.
 
 ```bash
 agileflow gitlab
 ```
 
 **Required Environment Variable:**
-- `AGILEFLOW_TOKEN` - GitLab access token with `api` scope
+- `AGILEFLOW_TOKEN` — GitLab access token with `api` scope
 
 **Auto-provided by GitLab CI:**
-- `CI_SERVER_HOST` - GitLab server hostname
-- `CI_PROJECT_PATH` - Project path (e.g., "group/project")
-- `CI_COMMIT_SHA` - Current commit SHA
+- `CI_SERVER_HOST` — GitLab server hostname
+- `CI_PROJECT_PATH` — Project path (e.g., `group/project`)
+- `CI_COMMIT_SHA` — Current commit SHA
 
-**Example GitLab CI job:**
+**Example:**
 ```yaml
 agileflow:
   stage: version
@@ -95,20 +89,20 @@ agileflow:
 
 ### github
 
-Creates a version tag via the GitHub API. Designed for use in GitHub Actions workflows.
+Creates a version tag via the GitHub API. Designed for GitHub Actions workflows.
 
 ```bash
 agileflow github
 ```
 
 **Required Environment Variable:**
-- `AGILEFLOW_TOKEN` - GitHub Personal Access Token with `contents: write` permission
+- `AGILEFLOW_TOKEN` — GitHub Personal Access Token with `contents: write` permission
 
 **Auto-provided by GitHub Actions:**
-- `GITHUB_REPOSITORY` - Repository name (e.g., "owner/repo")
-- `GITHUB_SHA` - Current commit SHA
+- `GITHUB_REPOSITORY` — Repository name (e.g., `owner/repo`)
+- `GITHUB_SHA` — Current commit SHA
 
-**Example GitHub Actions step:**
+**Example:**
 ```yaml
 - name: Create version tag
   env:
@@ -116,11 +110,13 @@ agileflow github
   run: npx @logickernel/agileflow github
 ```
 
+---
+
 ## Options
 
 ### --quiet
 
-Only output the next version string. Useful for capturing the version in scripts.
+Output only the next version string. Useful for capturing in scripts.
 
 ```bash
 agileflow --quiet
@@ -154,6 +150,8 @@ Display the AgileFlow CLI version.
 agileflow --version
 ```
 
+---
+
 ## Exit Codes
 
 | Code | Meaning |
@@ -161,9 +159,9 @@ agileflow --version
 | 0 | Success |
 | 1 | Error (missing token, git error, API error, etc.) |
 
-## Error Handling
+---
 
-AgileFlow provides detailed error messages for common issues:
+## Error Messages
 
 ### Authentication Errors
 
@@ -172,13 +170,8 @@ AgileFlow provides detailed error messages for common issues:
 AGILEFLOW_TOKEN environment variable is required but not set.
 
 To fix this:
-1. Create a project access token: https://gitlab.com/your/project/-/settings/access_tokens
-   - Name: AgileFlow Bot
-   - Role: maintainer
-   - Scopes: api
-2. Add it as a CI/CD variable: https://gitlab.com/your/project/-/settings/ci_cd
-   - Variable key: AGILEFLOW_TOKEN
-   - Protect variable: Yes (recommended)
+1. Create a project access token with 'api' scope and 'Maintainer' role
+2. Add it as a CI/CD variable named AGILEFLOW_TOKEN
 ```
 
 **GitHub:**
@@ -186,9 +179,9 @@ To fix this:
 AGILEFLOW_TOKEN environment variable is required but not set.
 
 To fix this:
-1. Create a Personal Access Token with "contents: write" permission
+1. Create a Personal Access Token with 'contents: write' permission
 2. Add it as a repository secret named AGILEFLOW_TOKEN
-3. In your workflow, add: env: AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
+3. Pass it via env: AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
 ```
 
 ### Git Repository Errors
@@ -203,6 +196,8 @@ Current directory is not a git repository (missing .git directory).
 Repository is in a detached HEAD state. Please check out a branch and try again.
 ```
 
+---
+
 ## Examples
 
 ### Preview Version Locally
@@ -212,13 +207,52 @@ cd my-project
 npx @logickernel/agileflow
 ```
 
-### Get Version for Use in Scripts
+### Get Version for Scripts
 
 ```bash
 VERSION=$(npx @logickernel/agileflow --quiet)
 docker build -t myapp:$VERSION .
 ```
 
+### GitHub Actions Workflow
+
+```yaml
+name: Release
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Create version tag
+        id: version
+        env:
+          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
+        run: |
+          VERSION=$(npx @logickernel/agileflow github --quiet)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+  build:
+    needs: release
+    if: needs.release.outputs.version != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t myapp:${{ needs.release.outputs.version }} .
+```
+
 ### GitLab CI Pipeline
 
 ```yaml
@@ -245,37 +279,23 @@ build:
     - docker build -t myapp:$VERSION .
   needs:
     - agileflow
-```
-
-### GitHub Actions Workflow
 
-```yaml
-name: Release
-on:
-  push:
-    branches: [main]
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      
-      - name: Create version tag
-        env:
-          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
-        run: npx @logickernel/agileflow github
+deploy:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:$VERSION
+  environment:
+    name: production
+  when: manual
+  needs:
+    - build
 ```
 
+---
+
 ## Related Documentation
 
-- [Getting Started](./getting-started.md) - Quick start guide
-- [Conventional Commits](./conventional-commits.md) - Commit message format
-- [Version-Centric CI/CD](./version-centric-cicd.md) - Methodology overview
-- [Troubleshooting](./troubleshooting.md) - Common issues and solutions
+- [Getting Started](./getting-started.md) — Quick start guide
+- [Installation Guide](./installation.md) — Setup instructions
+- [Conventional Commits](./conventional-commits.md) — Commit message format
+- [Troubleshooting](./troubleshooting.md) — Common issues and solutions

package/docs/configuration.md

@@ -1,232 +1,219 @@
 # Configuration Guide
 
-AgileFlow uses environment variables for configuration, making it easy to customize behavior across different environments and deployment scenarios.
+AgileFlow uses environment variables for configuration. Most variables are automatically provided by your CI/CD platform.
 
 ## Environment Variables
 
-### Required Variables
+### Required for CI/CD
 
-These environment variables must be set for AgileFlow to function properly:
+#### AGILEFLOW_TOKEN
 
-#### GitLab CI/CD Variables
+The access token used to create version tags via the platform API.
 
-- **`GITLAB_USER_NAME`** - Username for git commits and tag creation
-  - **Example**: `AgileFlow Bot`
-  - **Purpose**: Sets the author name for version tags and commits
-  - **Required**: Yes
+| Platform | Token Type | Required Permissions |
+|----------|------------|---------------------|
+| GitHub | Personal Access Token | `contents: write` |
+| GitLab | Project or Personal Access Token | `api` scope, `Maintainer` role |
 
-- **`GITLAB_USER_EMAIL`** - Email address for git commits and tag creation
-  - **Example**: `agileflow@example.com`
-  - **Purpose**: Sets the author email for version tags and commits
-  - **Required**: Yes
-
-- **`CI_SERVER_HOST`** - GitLab server hostname
-  - **Example**: `gitlab.example.com`
-  - **Purpose**: Used for generating commit pipeline URLs and API calls
-  - **Required**: Yes
-
-- **`CI_PROJECT_PATH`** - GitLab project path (group/project)
-  - **Example**: `mygroup/myproject`
-  - **Purpose**: Used for API calls and URL generation
-  - **Required**: Yes
-
-- **`AGILEFLOW_TOKEN`** - GitLab access token with API permissions
-  - **Example**: `glpat-xxxxxxxxxxxxxxxxxxxx`
-  - **Purpose**: Authenticates API calls for tag creation and repository access
-  - **Required**: Yes
-  - **Scopes**: `api` access required
-  - **Role**: `maintainer` or higher recommended
+**GitHub Actions:**
+```yaml
+env:
+  AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
+```
 
-### Optional Variables
+**GitLab CI:**
+```yaml
+# Set via Settings → CI/CD → Variables
+# Key: AGILEFLOW_TOKEN
+# Flags: Protected, Masked
+```
 
-These variables can be set to customize AgileFlow behavior:
+### Auto-Provided Variables
 
-#### Version Generation
+These are automatically set by your CI/CD platform:
 
-- **`AGILEFLOW_MAX_COMMIT_LINES`** - Maximum number of commit lines in release notes
-  - **Default**: `50`
-  - **Example**: `100`
-  - **Purpose**: Controls the length of generated release notes
+#### GitHub Actions
 
-- **`AGILEFLOW_INCLUDE_MERGE_COMMITS`** - Whether to include merge commits in release notes
-  - **Default**: `false`
-  - **Example**: `true`
-  - **Purpose**: Controls whether merge commits appear in release notes
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GITHUB_REPOSITORY` | Repository name | `owner/repo` |
+| `GITHUB_SHA` | Current commit SHA | `abc123...` |
 
-#### Git Configuration
+#### GitLab CI
 
-- **`GIT_COMMITTER_NAME`** - Override committer name (if different from author)
-  - **Default**: Uses `GITLAB_USER_NAME`
-  - **Example**: `CI Bot`
-  - **Purpose**: Sets the committer name for git operations
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `CI_SERVER_HOST` | GitLab server hostname | `gitlab.com` |
+| `CI_PROJECT_PATH` | Project path | `group/project` |
+| `CI_COMMIT_SHA` | Current commit SHA | `abc123...` |
 
-- **`GIT_COMMITTER_EMAIL`** - Override committer email (if different from author)
-  - **Default**: Uses `GITLAB_USER_EMAIL`
-  - **Example**: `ci@example.com`
-  - **Purpose**: Sets the committer email for git operations
+---
 
-## Configuration Examples
+## Platform Configuration
 
-### Basic GitLab CI Configuration
+### GitHub Actions
 
 ```yaml
-# .gitlab-ci.yml
-variables:
-  GITLAB_USER_NAME: "AgileFlow Bot"
-  GITLAB_USER_EMAIL: "agileflow@example.com"
-  CI_SERVER_HOST: "gitlab.example.com"
-  CI_PROJECT_PATH: "mygroup/myproject"
-
-include:
-  - local: templates/AgileFlow.gitlab-ci.yml
-
-build:
-  stage: build
-  script:
-    - echo "Building version ${VERSION}"
-  needs:
-    - agileflow
+name: Release
+on:
+  push:
+    branches: [main]
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for full commit 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
 ```
 
-### Advanced Configuration with Custom Options
+### GitLab CI
 
 ```yaml
-# .gitlab-ci.yml
-variables:
-  GITLAB_USER_NAME: "AgileFlow Bot"
-  GITLAB_USER_EMAIL: "agileflow@example.com"
-  CI_SERVER_HOST: "gitlab.example.com"
-  CI_PROJECT_PATH: "mygroup/myproject"
-  AGILEFLOW_MAX_COMMIT_LINES: "100"
-  AGILEFLOW_INCLUDE_MERGE_COMMITS: "false"
-
-include:
-  - local: templates/AgileFlow.gitlab-ci.yml
-
-build:
-  stage: build
+agileflow:
+  stage: version
+  image: node:20-alpine
   script:
-    - echo "Building version ${VERSION}"
-  needs:
-    - agileflow
+    - VERSION=$(npx @logickernel/agileflow gitlab --quiet)
+    - echo "VERSION=$VERSION" >> version.env
+  artifacts:
+    reports:
+      dotenv: version.env
+  only:
+    - main
 ```
 
-### Environment-Specific Configuration
-
-```yaml
-# .gitlab-ci.yml
-include:
-  - local: templates/AgileFlow.gitlab-ci.yml
-
-# Development environment
-build-dev:
-  stage: build
-  variables:
-    AGILEFLOW_MAX_COMMIT_LINES: "25"
-  script:
-    - echo "Building dev version ${VERSION}"
-  needs:
-    - agileflow
-
-# Production environment
-build-prod:
-  stage: build
-  variables:
-    AGILEFLOW_MAX_COMMIT_LINES: "100"
-  script:
-    - echo "Building production version ${VERSION}"
-  needs:
-    - agileflow
-```
+---
 
-## Setting Variables in GitLab
+## Setting Up Tokens
 
-### Project-Level Variables
+### GitHub Personal Access Token
 
-1. Go to your GitLab project
-2. Navigate to **Settings > CI/CD**
-3. Expand **Variables**
-4. Add each required variable:
-   - **Key**: `GITLAB_USER_NAME`
-   - **Value**: `AgileFlow Bot`
-   - **Type**: Variable
-   - **Environment scope**: All (default)
-   - **Protect variable**: Yes (recommended)
-   - **Mask variable**: No
+1. Go to **Settings → Developer settings → Personal access tokens → Fine-grained tokens**
+2. Click **Generate new token**
+3. Configure:
+   - **Name**: `AgileFlow`
+   - **Repository access**: Select your repositories
+   - **Permissions**: `Contents: Read and write`
+4. Copy the token
 
-### Group-Level Variables
+Add as a repository secret:
+1. Go to repository **Settings → Secrets and variables → Actions**
+2. Click **New repository secret**
+3. Name: `AGILEFLOW_TOKEN`, Value: your token
 
-For organization-wide consistency:
+### GitLab Project Access Token
 
-1. Go to your GitLab group
-2. Navigate to **Settings > CI/CD**
-3. Expand **Variables**
-4. Add common variables like `GITLAB_USER_NAME` and `GITLAB_USER_EMAIL`
+1. Go to project **Settings → Access tokens**
+2. Create new token:
+   - **Name**: `AgileFlow`
+   - **Role**: `Maintainer`
+   - **Scopes**: `api`
+3. Copy the token
 
-### Instance-Level Variables
+Add as a CI/CD variable:
+1. Go to project **Settings → CI/CD → Variables**
+2. Add variable:
+   - **Key**: `AGILEFLOW_TOKEN`
+   - **Value**: your token
+   - **Flags**: Protected, Masked
 
-For self-managed GitLab instances:
+---
 
-1. Go to **Admin Area > Settings > CI/CD**
-2. Expand **Variables**
-3. Add instance-wide defaults
-
-## Security Considerations
+## Security Best Practices
 
 ### Token Security
 
-- **Protect variables**: Enable protection for sensitive variables like `AGILEFLOW_TOKEN`
-- **Mask variables**: Don't mask variables that need to be visible in logs
-- **Scope variables**: Limit variable scope to specific environments when possible
-- **Rotate tokens**: Regularly rotate access tokens
+- **Use project tokens** over personal tokens when possible
+- **Enable protection** for sensitive variables
+- **Limit scope** to only required permissions
+- **Rotate tokens** regularly
+- **Use masked variables** to hide values in logs
 
 ### Access Control
 
-- **Minimal permissions**: Use tokens with minimal required permissions
-- **Role-based access**: Ensure tokens have appropriate role assignments
-- **Audit access**: Regularly review token access and usage
+- **Minimal permissions** — Use tokens with only required access
+- **Protected branches** — Limit who can push to main
+- **Audit access** — Regularly review token usage
+
+### Example: Protected Variable
+
+**GitHub:**
+- Repository secrets are automatically protected
+- Only workflows triggered from the default branch can access them
+
+**GitLab:**
+```yaml
+# Variable settings:
+# - Protected: Yes (only available on protected branches)
+# - Masked: Yes (hidden in job logs)
+```
+
+---
 
 ## Troubleshooting Configuration
 
-### Common Configuration Issues
+### Token Permission Errors
 
-**Missing Required Variables**
+**GitHub:**
 ```
-Error: Missing required environment variable: GITLAB_USER_NAME
+Error: Resource not accessible by integration
 ```
-**Solution**: Add the missing variable to your GitLab CI/CD variables.
+- Ensure token has `contents: write` permission
+- Check repository access is granted
 
-**Invalid Token Permissions**
+**GitLab:**
 ```
-Error: Permission denied. The AGILEFLOW_TOKEN needs "api" scope and maintainer role.
+Error: 403 Forbidden
 ```
-**Solution**: Update the token to have proper permissions and role.
+- Ensure token has `api` scope
+- Verify `Maintainer` role or higher
+- Check token hasn't expired
+
+### Missing Environment Variables
 
-**Invalid Project Path**
 ```
-Error: Invalid project path format
+Error: AGILEFLOW_TOKEN environment variable is required but not set.
 ```
-**Solution**: Ensure `CI_PROJECT_PATH` follows the format `group/project`.
+- Verify the variable is configured in your CI/CD settings
+- Check variable protection settings match your branch
 
 ### Debug Configuration
 
-Add a debug job to verify configuration:
+Add a debug step to verify configuration:
+
+**GitHub Actions:**
+```yaml
+- name: Debug
+  run: |
+    echo "Repository: $GITHUB_REPOSITORY"
+    echo "SHA: $GITHUB_SHA"
+    echo "Token set: ${{ secrets.AGILEFLOW_TOKEN != '' }}"
+```
 
+**GitLab CI:**
 ```yaml
-debug-config:
-  stage: build
+debug:
   script:
-    - echo "GITLAB_USER_NAME: ${GITLAB_USER_NAME}"
-    - echo "CI_SERVER_HOST: ${CI_SERVER_HOST}"
-    - echo "CI_PROJECT_PATH: ${CI_PROJECT_PATH}"
-    - echo "AGILEFLOW_TOKEN: ${AGILEFLOW_TOKEN:0:10}..."
-  needs:
-    - agileflow
+    - echo "Server: $CI_SERVER_HOST"
+    - echo "Project: $CI_PROJECT_PATH"
+    - echo "Token set: ${AGILEFLOW_TOKEN:+yes}"
 ```
 
+---
+
 ## Related Documentation
 
-- [Installation Guide](./installation.md) - Setup and configuration
-- [GitLab CI Template](./gitlab-ci-template.md) - Template configuration
-- [Troubleshooting](./troubleshooting.md) - Common issues and solutions
-- [CLI Reference](./cli-reference.md) - Command-line configuration
+- [Installation Guide](./installation.md) — Complete setup instructions
+- [CLI Reference](./cli-reference.md) — Command-line options
+- [Troubleshooting](./troubleshooting.md) — Common issues and solutions