@logickernel/agileflow 0.16.1 → 0.17.1

package/docs/cli-reference.md

@@ -1,301 +0,0 @@
-# CLI Reference
-
-AgileFlow provides a simple command-line interface for automatic semantic versioning and changelog generation.
-
-## Installation
-
-Run directly with npx (no installation required):
-
-```bash
-npx @logickernel/agileflow
-```
-
-Or install globally:
-
-```bash
-npm install -g @logickernel/agileflow
-agileflow
-```
-
----
-
-## Commands
-
-### Default (no command)
-
-Analyzes the repository and displays version information without creating tags.
-
-```bash
-agileflow
-```
-
-**Output:**
-```
-Current version: v1.2.3
-Next version: v1.2.4
-Commits since current version: 3
-
-Changelog:
-### fix
-- resolve authentication issue
-
-### feat
-- add new login flow
-```
-
-### push
-
-Creates an annotated git tag and pushes it to the origin remote.
-
-```bash
-agileflow push
-```
-
-**Requirements:**
-- Git credentials configured for push access
-
-**Behavior:**
-- Calculates the next version
-- Creates an annotated tag with the changelog as the message
-- Pushes the tag to origin
-- Skips if no version bump is needed
-
-### gitlab
-
-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
-
-**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
-
-**Example:**
-```yaml
-agileflow:
-  stage: version
-  image: node:20-alpine
-  script:
-    - npx @logickernel/agileflow gitlab
-  only:
-    - main
-```
-
-### github
-
-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
-
-**Auto-provided by GitHub Actions:**
-- `GITHUB_REPOSITORY` — Repository name (e.g., `owner/repo`)
-- `GITHUB_SHA` — Current commit SHA
-
-**Example:**
-```yaml
-- name: Create version tag
-  env:
-    AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
-  run: npx @logickernel/agileflow github
-```
-
----
-
-## Options
-
-### --quiet
-
-Output only the next version string. Useful for capturing in scripts.
-
-```bash
-agileflow --quiet
-# Output: v1.2.4
-```
-
-If no version bump is needed, outputs nothing.
-
-```bash
-VERSION=$(npx @logickernel/agileflow --quiet)
-if [ -n "$VERSION" ]; then
-  echo "New version: $VERSION"
-else
-  echo "No version bump needed"
-fi
-```
-
-### --help, -h
-
-Display help information.
-
-```bash
-agileflow --help
-```
-
-### --version, -v
-
-Display the AgileFlow CLI version.
-
-```bash
-agileflow --version
-```
-
----
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Error (missing token, git error, API error, etc.) |
-
----
-
-## Error Messages
-
-### Authentication Errors
-
-**GitLab:**
-```
-AGILEFLOW_TOKEN environment variable is required but not set.
-
-To fix this:
-1. Create a project access token with 'api' scope and 'Maintainer' role
-2. Add it as a CI/CD variable named AGILEFLOW_TOKEN
-```
-
-**GitHub:**
-```
-AGILEFLOW_TOKEN environment variable is required but not set.
-
-To fix this:
-1. Create a Personal Access Token with 'contents: write' permission
-2. Add it as a repository secret named AGILEFLOW_TOKEN
-3. Pass it via env: AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
-```
-
-### Git Repository Errors
-
-```
-Current directory is not a git repository (missing .git directory).
-```
-
-### Detached HEAD State
-
-```
-Repository is in a detached HEAD state. Please check out a branch and try again.
-```
-
----
-
-## Examples
-
-### Preview Version Locally
-
-```bash
-cd my-project
-npx @logickernel/agileflow
-```
-
-### 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
-stages:
-  - version
-  - build
-  - deploy
-
-agileflow:
-  stage: version
-  image: node:20-alpine
-  script:
-    - VERSION=$(npx @logickernel/agileflow gitlab --quiet)
-    - echo "VERSION=$VERSION" >> version.env
-  artifacts:
-    reports:
-      dotenv: version.env
-  only:
-    - main
-
-build:
-  stage: build
-  script:
-    - docker build -t myapp:$VERSION .
-  needs:
-    - agileflow
-
-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
-- [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,217 +0,0 @@
-# Configuration Guide
-
-AgileFlow uses environment variables for configuration. Most variables are automatically provided by your CI/CD platform.
-
-## Environment Variables
-
-### Required for CI/CD
-
-#### AGILEFLOW_TOKEN
-
-The access token used to create version tags via the platform API.
-
-| Platform | Token Type | Required Permissions |
-|----------|------------|---------------------|
-| GitHub | Personal Access Token | `contents: write` |
-| GitLab | Project or Personal Access Token | `api` scope, `Maintainer` role |
-
-**GitHub Actions:**
-```yaml
-env:
-  AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
-```
-
-**GitLab CI:**
-```yaml
-# Set via Settings → CI/CD → Variables
-# Key: AGILEFLOW_TOKEN
-# Flags: Protected, Masked
-```
-
-### Auto-Provided Variables
-
-These are automatically set by your CI/CD platform:
-
-#### GitHub Actions
-
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `GITHUB_REPOSITORY` | Repository name | `owner/repo` |
-| `GITHUB_SHA` | Current commit SHA | `abc123...` |
-
-#### GitLab CI
-
-| 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...` |
-
----
-
-## Platform Configuration
-
-### GitHub Actions
-
-```yaml
-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: agileflow github
-```
-
-### GitLab CI
-
-```yaml
-agileflow:
-  image: node:20
-  script:
-    - npm install -g @logickernel/agileflow
-    - agileflow gitlab
-  rules:
-    - if: '$CI_COMMIT_BRANCH == "main"'
-  tags:
-    - agileflow
-```
-
----
-
-## Setting Up Tokens
-
-### GitHub Personal Access Token
-
-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
-
-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
-
-### GitLab Project Access Token
-
-1. Go to project **Settings → Access tokens**
-2. Create new token:
-   - **Name**: `AgileFlow`
-   - **Role**: `Maintainer`
-   - **Scopes**: `api`
-3. Copy the token
-
-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
-
----
-
-## Security Best Practices
-
-### Token Security
-
-- **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 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
-
-### Token Permission Errors
-
-**GitHub:**
-```
-Error: Resource not accessible by integration
-```
-- Ensure token has `contents: write` permission
-- Check repository access is granted
-
-**GitLab:**
-```
-Error: 403 Forbidden
-```
-- Ensure token has `api` scope
-- Verify `Maintainer` role or higher
-- Check token hasn't expired
-
-### Missing Environment Variables
-
-```
-Error: AGILEFLOW_TOKEN environment variable is required but not set.
-```
-- Verify the variable is configured in your CI/CD settings
-- Check variable protection settings match your branch
-
-### Debug 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:
-  script:
-    - echo "Server: $CI_SERVER_HOST"
-    - echo "Project: $CI_PROJECT_PATH"
-    - echo "Token set: ${AGILEFLOW_TOKEN:+yes}"
-```
-
----
-
-## Related Documentation
-
-- [Installation Guide](./installation.md) — Complete setup instructions
-- [CLI Reference](./cli-reference.md) — Command-line options
-- [Troubleshooting](./troubleshooting.md) — Common issues and solutions