@logickernel/agileflow 0.17.0 → 0.20.0

package/docs/release-management.md

@@ -1,309 +0,0 @@
-# Release Management
-
-AgileFlow automates version generation with a decoupled architecture that creates version tags, which then trigger your release pipelines.
-
-## Architecture
-
-```
-Merge to main ──▶ AgileFlow ──▶ Tag v1.2.3 ──▶ Your build/deploy
-```
-
-1. **AgileFlow creates the version tag** — Triggered on merge to main
-2. **Your pipelines handle the release** — Triggered by tag creation
-
-This separation keeps versioning independent from build and deployment.
-
----
-
-## How Version Generation Works
-
-### Semantic Versioning
-
-AgileFlow follows [Semantic Versioning](https://semver.org/):
-
-```
-MAJOR.MINOR.PATCH
-  │     │     └── Bug fixes, refactors
-  │     └──────── New features
-  └────────────── Breaking changes
-```
-
-### Automatic Version Calculation
-
-| Commit Type | Example | 0.x.x | 1.0.0+ |
-|-------------|---------|-------|--------|
-| Breaking change | `feat!: redesign API` | **Minor** (0.1.0 → 0.2.0) | **Major** (1.0.0 → 2.0.0) |
-| Feature | `feat: add login` | **Minor** | **Minor** |
-| Fix | `fix: resolve crash` | **Patch** | **Patch** |
-| Everything else | `docs: update README` | No bump | No bump |
-
----
-
-## Release Process
-
-### 1. Development
-
-Work on feature branches:
-
-```bash
-git checkout -b feat/user-auth
-git commit -m "feat: implement login flow"
-git push origin feat/user-auth
-```
-
-### 2. Merge
-
-Create and merge a pull/merge request to main.
-
-### 3. Version Creation (Automatic)
-
-AgileFlow runs and creates a tag:
-- Analyzes commits since last version
-- Calculates next version
-- Creates annotated tag with release notes
-
-### 4. Release (Your Pipelines)
-
-Tag creation triggers your release workflow:
-- Build artifacts tagged with version
-- Deploy to environments
-- Run tests
-
----
-
-## Release Workflows
-
-### GitHub Actions
-
-**Release workflow** (`.github/workflows/release.yml`):
-```yaml
-name: Release
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Get version
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
-
-      - name: Build
-        run: docker build -t myapp:$VERSION .
-
-  deploy-staging:
-    needs: build
-    runs-on: ubuntu-latest
-    environment: staging
-    steps:
-      - run: kubectl set image deployment/myapp myapp=myapp:$VERSION
-
-  deploy-production:
-    needs: build
-    runs-on: ubuntu-latest
-    environment: production
-    steps:
-      - run: kubectl set image deployment/myapp myapp=myapp:$VERSION
-```
-
-### GitLab CI
-
-```yaml
-build:
-  stage: build
-  script:
-    - docker build -t myapp:$CI_COMMIT_TAG .
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-
-deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
-  environment: staging
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-
-deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
-  environment: production
-  when: manual
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-```
-
----
-
-## Release Notes
-
-AgileFlow generates structured release notes from conventional commits:
-
-```
-v1.2.4
-
-### Features
-- auth: add OAuth2 login flow
-
-### Bug fixes
-- api: handle null user ID
-
-### Performance
-- cache: implement Redis pooling
-```
-
-### View Release Notes
-
-```bash
-git tag -l -n99 v1.2.4
-```
-
----
-
-## Initial Development (0.x.x)
-
-New projects start at v0.0.0:
-
-- Features → Minor bump (0.0.0 → 0.1.0)
-- Fixes → Patch bump (0.0.0 → 0.0.1)
-- Breaking changes → Minor bump (0.0.0 → 0.1.0)
-
----
-
-## First Stable Release
-
-Version 1.0.0 represents first stable release. Create manually:
-
-```bash
-git tag -a v1.0.0 -m "First stable release"
-git push origin v1.0.0
-```
-
-This will trigger your release workflow.
-
----
-
-## Viewing Releases
-
-```bash
-# List versions
-git tag --sort=-version:refname
-
-# View specific version
-git show v1.2.3
-
-# Compare versions
-git log v1.2.2..v1.2.3 --oneline
-```
-
----
-
-## Rollbacks
-
-### Simple Rollback
-
-Redeploy a previous version:
-
-```bash
-kubectl set image deployment/myapp myapp=myapp:v1.2.2
-```
-
-### Automated Rollback Job
-
-**GitHub Actions:**
-```yaml
-rollback:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    - run: |
-        PREVIOUS=$(git describe --tags --abbrev=0 HEAD^)
-        kubectl set image deployment/myapp myapp=myapp:$PREVIOUS
-```
-
-**GitLab CI:**
-```yaml
-rollback:
-  script:
-    - PREVIOUS=$(git describe --tags --abbrev=0 HEAD^)
-    - kubectl set image deployment/myapp myapp=myapp:$PREVIOUS
-  when: manual
-```
-
----
-
-## Release Strategies
-
-### Continuous Delivery
-
-Auto-deploy to staging, manual to production:
-
-```yaml
-deploy-staging:
-  # Runs automatically on tag
-
-deploy-production:
-  when: manual
-```
-
-### Version-Based Gates
-
-Only deploy certain version types:
-
-```yaml
-deploy-production:
-  rules:
-    # Only minor/major versions
-    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.0$/'
-```
-
----
-
-## Release Communication
-
-### Notifications
-
-```yaml
-notify:
-  script:
-    - |
-      curl -X POST "$SLACK_WEBHOOK" \
-        -d "{\"text\": \"Released $CI_COMMIT_TAG\"}"
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-```
-
-### GitHub Releases
-
-```yaml
-- uses: softprops/action-gh-release@v1
-  with:
-    tag_name: ${{ github.ref_name }}
-    generate_release_notes: true
-```
-
----
-
-## Best Practices
-
-1. **Use conventional commits** — For accurate versioning
-2. **Keep releases small** — Easier to debug and rollback
-3. **Test in staging first** — Before production
-4. **Document breaking changes** — Clear for users
-5. **Plan rollbacks** — Have procedures ready
-
----
-
-## Related Documentation
-
-- [Getting Started](./getting-started.md) — Quick start
-- [Conventional Commits](./conventional-commits.md) — Commit format
-- [Version-Centric CI/CD](./version-centric-cicd.md) — Methodology
-- [Best Practices](./best-practices.md) — Recommendations

package/docs/troubleshooting.md

@@ -1,367 +0,0 @@
-# Troubleshooting Guide
-
-This guide helps you resolve common issues when using AgileFlow.
-
-## Quick Diagnosis
-
-### Check Your Setup
-
-```bash
-# Verify git repository
-git status
-
-# Check existing version tags
-git tag --sort=-version:refname | head -5
-
-# Preview next version
-npx @logickernel/agileflow
-```
-
-### Common Symptoms
-
-| Symptom | Likely Cause | Section |
-|---------|--------------|---------|
-| No tag created | Token permissions | [Authentication](#authentication-errors) |
-| Wrong version | Commit format | [Version Generation](#version-generation-issues) |
-| Tag created but no build | Release workflow config | [Release Workflow](#release-workflow-issues) |
-
----
-
-## Authentication Errors
-
-### GitHub: "Resource not accessible by integration"
-
-**Cause:** Token lacks required permissions.
-
-**Solution:**
-1. Create a Fine-grained Personal Access Token
-2. Grant `Contents: Read and write` permission
-3. Ensure repository is in token scope
-4. Update `AGILEFLOW_TOKEN` secret
-
-### GitHub: "Bad credentials"
-
-**Cause:** Token invalid or expired.
-
-**Solution:**
-1. Check token hasn't expired
-2. Regenerate token
-3. Update secret
-
-### GitLab: "403 Forbidden"
-
-**Cause:** Token lacks permissions.
-
-**Solution:**
-1. Verify `api` scope
-2. Ensure `Maintainer` role
-3. Check token not expired
-4. For protected branches, ensure variable is protected
-
-### GitLab: "401 Unauthorized"
-
-**Cause:** Invalid or missing token.
-
-**Solution:**
-1. Verify `AGILEFLOW_TOKEN` variable exists
-2. Check variable protection settings
-3. Regenerate if needed
-
----
-
-## Version Generation Issues
-
-### No Tag Created
-
-**Possible causes:**
-
-1. **No conventional commits**
-   ```bash
-   # Check recent commits
-   git log --oneline -10
-   
-   # Should see: feat:, fix:, perf:, etc.
-   ```
-
-2. **All commits are docs/chore/style**
-   ```bash
-   # These don't trigger bumps:
-   docs: update README
-   chore: update deps
-   style: format code
-   ```
-
-3. **Not on main branch**
-   ```bash
-   git branch --show-current
-   ```
-
-**Solution:** Include bump-triggering commits (`feat`, `fix`, `perf`, etc.).
-
-### Wrong Version Calculated
-
-**Possible causes:**
-
-1. **Breaking change not marked**
-   ```bash
-   # Wrong
-   feat: remove old API
-   
-   # Correct
-   feat!: remove old API
-   ```
-
-2. **Wrong commit type**
-   ```bash
-   # Wrong
-   fix: add new login feature
-   
-   # Correct
-   feat: add new login feature
-   ```
-
-### Commits Not Recognized
-
-**Common mistakes:**
-
-```bash
-# Wrong — missing colon
-feat add new feature
-
-# Wrong — wrong separator
-feat - add new feature
-
-# Wrong — capitalized
-Feat: add new feature
-
-# Correct
-feat: add new feature
-```
-
----
-
-## Release Workflow Issues
-
-### Tag Created but Build Didn't Run
-
-**Cause:** Release workflow not triggered by tags.
-
-**GitHub Actions — Check workflow trigger:**
-```yaml
-# ✅ Correct
-on:
-  push:
-    tags:
-      - 'v*'
-
-# ❌ Wrong — only triggers on branch push
-on:
-  push:
-    branches: [main]
-```
-
-**GitLab CI — Check rules:**
-```yaml
-# ✅ Correct
-build:
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-
-# ❌ Wrong — only runs on main branch
-build:
-  rules:
-    - if: '$CI_COMMIT_BRANCH == "main"'
-```
-
-### Version Not Available in Release Workflow
-
-**GitHub Actions:**
-```yaml
-# Extract version from tag
-- name: Get version
-  run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
-
-- name: Use version
-  run: docker build -t myapp:$VERSION .
-```
-
-**GitLab CI:**
-```yaml
-# Use CI_COMMIT_TAG directly
-build:
-  script:
-    - docker build -t myapp:$CI_COMMIT_TAG .
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-```
-
----
-
-## Git Repository Errors
-
-### "Not a git repository"
-
-**Cause:** Running outside git repository.
-
-**Solution:**
-```bash
-ls -la .git  # Verify .git exists
-```
-
-### "Detached HEAD state"
-
-**GitHub Actions:**
-```yaml
-- uses: actions/checkout@v4
-  with:
-    fetch-depth: 0
-    ref: main  # Checkout branch
-```
-
-**GitLab CI:**
-```yaml
-agileflow:
-  script:
-    - git checkout $CI_COMMIT_REF_NAME
-    - npx @logickernel/agileflow gitlab
-```
-
-### Shallow Clone Issues
-
-**Cause:** Commit history not available.
-
-**GitHub Actions:**
-```yaml
-- uses: actions/checkout@v4
-  with:
-    fetch-depth: 0  # Fetch all history
-```
-
-**GitLab CI:**
-```yaml
-variables:
-  GIT_DEPTH: 0
-```
-
----
-
-## Pipeline Issues
-
-### Versioning Job Fails
-
-**Debug steps:**
-
-1. **Check logs** for error messages
-2. **Verify token** is set:
-   ```yaml
-   - run: echo "Token set: ${{ secrets.AGILEFLOW_TOKEN != '' }}"
-   ```
-3. **Check git state**:
-   ```yaml
-   - run: |
-       git log --oneline -5
-       git tag --sort=-version:refname | head -3
-   ```
-
-### Both Workflows Running on Same Push
-
-**Cause:** Main push triggers versioning, tag push triggers release — correct behavior!
-
-This is expected:
-1. Push to main → Versioning workflow → Creates tag
-2. Tag push → Release workflow → Builds
-
----
-
-## Debug Commands
-
-### Verify AgileFlow
-
-```bash
-# Check version
-npx @logickernel/agileflow --version
-
-# Preview (no tag creation)
-npx @logickernel/agileflow
-
-# Quiet mode
-npx @logickernel/agileflow --quiet
-```
-
-### Check Git State
-
-```bash
-# Recent tags
-git tag --sort=-version:refname | head -5
-
-# Recent commits
-git log --oneline -10
-
-# Current branch
-git branch --show-current
-```
-
-### Test Tokens
-
-**GitLab:**
-```bash
-curl --header "PRIVATE-TOKEN: $AGILEFLOW_TOKEN" \
-  "https://gitlab.com/api/v4/projects"
-```
-
-**GitHub:**
-```bash
-curl -H "Authorization: token $AGILEFLOW_TOKEN" \
-  "https://api.github.com/user"
-```
-
----
-
-## Common Patterns
-
-### Complete Debug Workflow
-
-**GitHub Actions:**
-```yaml
-- name: Debug
-  run: |
-    echo "Node: $(node --version)"
-    echo "Git: $(git --version)"
-    echo "Branch: $(git branch --show-current)"
-    echo "Tags: $(git tag --sort=-version:refname | head -3)"
-    echo "Commits:"
-    git log --oneline -5
-    npx @logickernel/agileflow || echo "Exit: $?"
-```
-
-**GitLab CI:**
-```yaml
-debug:
-  script:
-    - node --version
-    - git --version
-    - git branch --show-current
-    - git tag --sort=-version:refname | head -3
-    - git log --oneline -5
-    - npx @logickernel/agileflow || echo "Exit: $?"
-```
-
----
-
-## Getting Help
-
-If still stuck:
-
-1. **Check error messages** — Usually descriptive
-2. **Verify configuration** — Tokens, workflow triggers
-3. **Test locally** — `npx @logickernel/agileflow`
-4. **Open an issue** — Include logs and config
-
----
-
-## Related Documentation
-
-- [Installation Guide](./installation.md) — Setup
-- [Configuration](./configuration.md) — Variables
-- [CLI Reference](./cli-reference.md) — Commands
-- [Conventional Commits](./conventional-commits.md) — Commit format