@logickernel/agileflow 0.13.0 → 0.14.0

package/README.md

@@ -14,10 +14,16 @@ AgileFlow works with your CI/CD engine to **automatically create a new version t
 
 ## Quick Start
 
+Install the tool
+
+```bash
+npm install -g @logickernel/agileflow
+```
+
 ### Preview Your Next Version
 
 ```bash
-npx @logickernel/agileflow
+agileflow
 ```
 
 ### Create a Version Tag
@@ -25,19 +31,19 @@ npx @logickernel/agileflow
 
 **Push to Remote Git Repository:**
 ```bash
-npx @logickernel/agileflow push
+agileflow push
 ```
 
 #### CD/CI
 
 **GitHub Actions:**
 ```bash
-npx @logickernel/agileflow github
+agileflow github
 ```
 
 **GitLab CI:**
 ```bash
-npx @logickernel/agileflow gitlab
+agileflow gitlab
 ```
 
 **Learn More**: [Getting Started Guide](./docs/getting-started.md) • [CLI Reference](./docs/cli-reference.md)
@@ -78,12 +84,22 @@ jobs:
 ```
 
 **GitLab CI** (`.gitlab-ci.yml`):
+
+For a job tagged with `agileflow` for a GitLab Runner:
+
+```yaml
+include:
+  - remote: https://code.logickernel.com/tools/agileflow/-/raw/main/.gitlab-ci.yml
+```
+
+Or manually:
+
 ```yaml
 agileflow:
   image: node:20
   script:
     - npm install -g @logickernel/agileflow
-    - npx @logickernel/agileflow gitlab
+    - agileflow gitlab
   rules:
     - if: '$CI_COMMIT_BRANCH == "main"'
 ```
@@ -111,11 +127,6 @@ AgileFlow uses [Conventional Commits](https://www.conventionalcommits.org/) to a
 
 ```text
 type(scope): description
-
-feat(auth): add OAuth2 login flow
-fix(api): correct null handling in user lookup
-perf(cache)!: switch to Redis cluster
-docs: update README with usage examples
 ```
 
 The commit type (`feat`, `fix`, `perf`, etc.) indicates what kind of change was made, while the optional scope identifies the area affected. Breaking changes are marked with `!` or a `BREAKING CHANGE:` footer.
@@ -132,8 +143,7 @@ Each merge to main triggers automatic version generation based on commit types.
 
 New projects start at **v0.0.0** and automatically increment based on commits. AgileFlow will keep automatically generating versions as you develop (0.0.1, 0.0.2, 0.1.0, etc.). When your product has reached maturity and you have a stable API ready for production, create version 1.0.0 manually.
 
-<details>
-<summary><strong>Version 1.0.0 — First Stable Release</strong></summary>
+### Version 1.0.0 — First Stable Release
 
 Version 1.0.0 represents your first stable API and marks the transition from initial development to a stable, production-ready release. This version **must be created manually** when your team decides the API is stable and ready for production use.
 
@@ -146,7 +156,6 @@ git push origin v1.0.0
 
 After 1.0.0, AgileFlow continues automatic versioning with standard semantic versioning rules: features bump minor, fixes bump patch, and breaking changes bump major.
 
-</details>
 
 **Learn More**: [Release Management Guide](./docs/release-management.md)
 

package/docs/conventional-commits.md

@@ -2,142 +2,129 @@
 
 AgileFlow uses [Conventional Commits](https://www.conventionalcommits.org/) to automatically determine version bumps and generate release notes.
 
-## Commit Format
+## What are Conventional Commits?
+
+The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](https://semver.org/), by describing the features, fixes, and breaking changes made in commit messages.
+
+The commit message should be structured as follows:
 
 ```
-type(scope): description
+<type>[optional scope]: <description>
 
 [optional body]
 
-[optional footer]
+[optional footer(s)]
 ```
 
-### Components
+The commit contains the following structural elements, to communicate intent to the consumers of your library:
 
-| Part | Required | Description |
-|------|----------|-------------|
-| `type` | Yes | Type of change (feat, fix, etc.) |
-| `scope` | No | Area affected (auth, api, ui) |
-| `!` | No | Breaking change indicator |
-| `description` | Yes | Short summary |
-| `body` | No | Detailed explanation |
-| `footer` | No | Breaking changes, issue refs |
+- **`fix:`** — A commit of the type `fix` patches a bug in your codebase (this correlates with **PATCH** in Semantic Versioning).
+- **`feat:`** — A commit of the type `feat` introduces a new feature to the codebase (this correlates with **MINOR** in Semantic Versioning).
+- **`BREAKING CHANGE:`** — A commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with **MAJOR** in Semantic Versioning). A `BREAKING CHANGE` can be part of commits of any type.
+- **Other types** — Types other than `fix:` and `feat:` are allowed (e.g., `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others). These have no implicit effect in Semantic Versioning (unless they include a `BREAKING CHANGE`).
+- **Scope** — A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.
+- **Footers** — Footers other than `BREAKING CHANGE: <description>` may be provided and follow a convention similar to git trailer format.
 
 ---
 
-## Commit Types and Version Impact
+## How to Choose a Commit Type
 
-| Type | Description | 1.0.0+ | 0.x.x |
-|------|-------------|--------|-------|
-| `feat` | New features | Minor | Minor |
-| `fix` | Bug fixes | Patch | Patch |
-| `perf` | Performance improvements | None | None |
-| `refactor` | Code refactoring | None | None |
-| `build` | Build system changes | None | None |
-| `ci` | CI/CD changes | None | None |
-| `test` | Test changes | None | None |
-| `revert` | Revert commits | None | None |
-| `docs` | Documentation | None | None |
-| `style` | Code style | None | None |
-| `chore` | Maintenance | None | None |
+Use this decision flow to choose the right commit type:
 
-### Breaking Changes
+```mermaid
+flowchart TD
+  Start([Start]) --> A{Does it add functionality?}
 
-Breaking changes trigger a major version bump (or minor for 0.x.x):
+  A -- "yes" --> F[feat:]
+  A -- "no" --> B{Does it fix functionality?}
 
-```bash
-# Using ! suffix
-feat!: remove deprecated API
+  B -- "yes" --> X[fix:]
+  B -- "no" --> C{Is it work in progress?}
 
-# Using footer
-feat: change response format
+  C -- "yes" --> W[wip:]
+  C -- "no" --> D[Choose best: docs, ci, style, chore, etc.]
 
-BREAKING CHANGE: Response now uses camelCase
+  W --> E{Is it a breaking change?}
+  F --> E
+  X --> E
+  D --> E
+
+  E -- "no" --> Z([Commit])
+  E -- "yes" --> G[Add ! to type/scope or BREAKING CHANGE: in body]
+  G --> Z
 ```
 
----
+### Quick Decision Guide
 
-## Examples
+1. **Adds new functionality?** → `feat:`
+2. **Fixes broken functionality?** → `fix:`
+3. **Work in progress?** → `wip:` (not included in releases)
+4. **Otherwise?** → Choose the most appropriate:
+   - `docs:` — Documentation changes
+   - `ci:` — CI/CD changes
+   - `style:` — Code style (formatting, whitespace)
+   - `chore:` — Maintenance tasks
+   - `test:` — Test changes
+   - `refactor:` — Code refactoring
+   - `perf:` — Performance improvements
+   - `build:` — Build system changes
+   - `revert:` — Revert previous commits
+5. **Breaking change?** → Add `!` after type/scope or include `BREAKING CHANGE:` in body
 
-### Features
+### Examples
 
 ```bash
+# Adds functionality
 feat: add user authentication
-feat(auth): implement OAuth2 login
-feat(api): add rate limiting endpoint
-```
-
-### Fixes
+feat(auth): add OAuth2 support
 
-```bash
-fix: resolve null pointer exception
-fix(auth): handle expired tokens correctly
-fix(ui): correct button alignment on mobile
-```
+# Fixes functionality
+fix: resolve login validation error
+fix(api): handle timeout errors
 
-### Performance
+# Work in progress
+wip: implement user authentication
 
-```bash
-perf: optimize database queries
-perf(cache): implement Redis connection pooling
-```
+# Other types
+docs: update API reference
+ci: update GitHub Actions workflow
+style: format code with prettier
+chore: update dependencies
 
-### Refactoring
+# Breaking changes
+feat!: remove deprecated API endpoints
+feat: change response format
 
-```bash
-refactor: simplify authentication logic
-refactor(api): extract validation middleware
+BREAKING CHANGE: Response now uses camelCase
 ```
 
-### Breaking Changes
-
-```bash
-feat!: remove v1 API endpoints
-feat(auth)!: change token format to JWT
+---
 
-fix: update database schema
+## Commit Types and Version Impact
 
-BREAKING CHANGE: User table now requires email field
-```
+| Type | Description | 0.x.x | 1.0.0+ |
+|------|-------------|--------|-------|
+| BREAKING CHANGE | Changes that break backward compatibility <br> (e.g., removed APIs, changed function signatures, modified response formats) | Minor | Major |
+| `feat` | New features | Minor | Minor |
+| `fix` | Bug fixes | Patch | Patch |
+|  | Any other type of commit | None | None |
 
-### Documentation
+When multiple commits exist, the highest priority wins.
 
-```bash
-docs: update installation guide
-docs(api): add authentication examples
-docs(readme): improve getting started section
-```
+### Breaking Changes
 
-### No Version Bump
+Breaking changes trigger a major version bump (or minor for 0.x.x):
 
 ```bash
-docs: update README
-style: format code with prettier
-chore: update development dependencies
-```
-
----
-
-## Version Bump Priority
-
-When multiple commits exist, the highest priority wins:
-
-1. **Breaking changes** → Major (or Minor for 0.x.x)
-2. **Features** → Minor
-3. **Fixes** → Patch
-4. **Everything else** → No bump
+# Using ! suffix
+feat!: remove deprecated API
 
-### Example
+# Using footer
+feat: change response format
 
-If commits since last version include:
-```
-feat: add new dashboard
-fix: resolve login bug
-docs: update README
+BREAKING CHANGE: Response now uses camelCase
 ```
 
-Result: **Minor bump** (feat has highest priority)
-
 ---
 
 ## Release Notes Generation
@@ -162,6 +149,8 @@ v1.2.4
 - update API reference
 ```
 
+Chore commits are omitted from release notes unless they include a breaking change.
+
 ### Breaking Changes in Notes
 
 Breaking changes are highlighted:
@@ -174,16 +163,6 @@ v2.0.0
 - BREAKING: change authentication flow
 ```
 
----
-
-## Skip Release
-
-Use `[skip release]` to prevent version bump:
-
-```bash
-chore(deps): bump jest to 29.0.0 [skip release]
-docs: internal notes [skip release]
-```
 
 ---
 
@@ -192,13 +171,12 @@ docs: internal notes [skip release]
 Commits not following the format:
 - Trigger **no bump** by default
 - Appear under "Other changes" in release notes
-- Use `[skip release]` to prevent bump
 
 ---
 
 ## Best Practices
 
-### 1. Use Clear Types
+1. Use Clear Types
 
 ```bash
 # ✅ Correct type
@@ -210,31 +188,20 @@ fix: add login feature  # Should be feat
 feat: fix crash         # Should be fix
 ```
 
-### 2. Add Meaningful Scopes
-
-```bash
-# ✅ Helpful scope
-feat(auth): add OAuth2 support
-fix(api): handle timeout errors
-
-# ✅ Also fine without scope
-feat: add OAuth2 support
-fix: handle timeout errors
-```
 
-### 3. Write Clear Descriptions
+2. Write Clear Descriptions
 
 ```bash
 # ✅ Clear and specific
-feat(auth): add two-factor authentication via SMS
-fix(api): prevent timeout on uploads larger than 100MB
+feat: add two-factor authentication via SMS
+fix: prevent timeout on uploads larger than 100MB
 
 # ❌ Vague
 feat: add 2fa
 fix: fix timeout
 ```
 
-### 4. Mark Breaking Changes
+3. Mark Breaking Changes
 
 ```bash
 # ✅ Properly marked
@@ -244,7 +211,7 @@ feat!: remove deprecated endpoints
 feat: remove deprecated endpoints
 ```
 
-### 5. Use Present Tense
+4. Use Present Tense
 
 ```bash
 # ✅ Present tense
@@ -254,23 +221,17 @@ feat: add user authentication
 feat: added user authentication
 ```
 
----
+5. Add Meaningful Scopes when applicable
+
+```bash
+# ✅ Helpful scope
+feat(auth): add OAuth2 support
+fix(api): handle timeout errors
 
-## Commit Type Details
-
-For detailed guidance on each type, see:
-
-- [feat](./conventional-commits/type-feat.md) — Features
-- [fix](./conventional-commits/type-fix.md) — Bug fixes
-- [perf](./conventional-commits/type-perf.md) — Performance
-- [refactor](./conventional-commits/type-refactor.md) — Refactoring
-- [build](./conventional-commits/type-build.md) — Build system
-- [ci](./conventional-commits/type-ci.md) — CI/CD
-- [test](./conventional-commits/type-test.md) — Tests
-- [docs](./conventional-commits/type-docs.md) — Documentation
-- [style](./conventional-commits/type-style.md) — Code style
-- [chore](./conventional-commits/type-chore.md) — Maintenance
-- [revert](./conventional-commits/type-revert.md) — Reverts
+# ✅ Also fine without scope
+feat: add OAuth2 support
+fix: handle timeout errors
+```
 
 ---
 

package/package.json

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

package/src/utils.js

@@ -72,7 +72,7 @@ function getCurrentBranch() {
 }
 
 // Conventional commit type configuration
-const TYPE_ORDER = ['feat', 'fix', 'perf', 'refactor', 'style', 'test', 'build', 'ci', 'docs', 'chore', 'revert'];
+const TYPE_ORDER = ['feat', 'fix', 'perf', 'refactor', 'style', 'test', 'build', 'ci', 'docs', 'revert'];
 const SEMVER_PATTERN = /^v(\d+)\.(\d+)\.(\d+)(-[a-zA-Z0-9.-]+)?$/;
 
 // Friendly header names for changelog
@@ -86,7 +86,6 @@ const TYPE_HEADERS = {
   docs: 'Documentation:',
   build: 'Build:',
   ci: 'CI:',
-  chore: 'Chores:',
   revert: 'Reverts:',
 };
 

package/docs/conventional-commits/type-build.md

@@ -1,23 +0,0 @@
-# Build System (`build`)
-
-Changes that affect the build tooling or dependencies.
-
-**Use for**:
-- Dependency updates
-- Lockfile changes
-- Dockerfile modifications
-- Build script updates
-- Compiler configurations
-- Bundler settings
-
-**Avoid for**:
-- Runtime code changes
-- CI-only configuration
-
-**Examples**:
-```text
-build(deps): update React to version 18
-build(docker): optimize Docker image layers
-build(webpack): configure code splitting
-build(npm): update package-lock.json
-```

package/docs/conventional-commits/type-chore.md

@@ -1,24 +0,0 @@
-# Chores (`chore`)
-
-Routine tasks that do not affect source behavior or tests.
-
-**Use for**:
-- Repository housekeeping
-- License file updates
-- Issue template changes
-- File renames without behavior change
-- Git configuration
-- Development environment setup
-
-**Avoid for**:
-- Dependency changes
-- Build system modifications
-- Code formatting
-
-**Examples**:
-```text
-chore: update .gitignore patterns
-chore: add issue templates
-chore: reorganize project structure
-chore: update development setup instructions
-```

package/docs/conventional-commits/type-ci.md

@@ -1,23 +0,0 @@
-# CI/CD (`ci`)
-
-Changes to continuous integration configuration and automation. They usually do not affect source behavior, if they do, they must be marked as ! or add a BREAKING FIX footer.
-
-**Use for**:
-- Pipeline definitions
-- Job configurations
-- Cache settings
-- CI scripts
-- Deployment automation
-- Test configurations
-
-**Avoid for**:
-- Build tooling that affects local builds
-- Application code changes
-
-**Examples**:
-```text
-ci(gitlab): add deployment job for staging
-ci(docker): configure multi-stage builds
-ci(tests): add integration test suite
-ci(deploy): automate production deployments
-```

package/docs/conventional-commits/type-docs.md

@@ -1,23 +0,0 @@
-# Documentation (`docs`)
-
-Documentation-only changes.
-
-**Use for**:
-- README updates
-- API documentation
-- Code examples
-- Architecture decision records (ADRs)
-- Inline code comments
-- User guides
-
-**Avoid for**:
-- Code changes that affect behavior
-- Configuration changes
-
-**Examples**:
-```text
-docs: update installation instructions
-docs(api): add endpoint documentation
-docs: add troubleshooting guide
-docs: update contributing guidelines
-```

package/docs/conventional-commits/type-feat.md

@@ -1,28 +0,0 @@
-# Features (`feat`)
-
-Introduces new user- or API-facing capabilities without removing existing behavior.
-
-## Examples
-
-```text
-feat(api) add user authentication endpoint
-feat(cli): implement --dry-run flag for deployments
-feat(ui): add dark mode toggle
-feat(auth): support OAuth2 login flow
-```
-
-## Use for
-
-- New endpoints or API methods
-- CLI commands and options
-- Configuration options
-- UI components and features
-- Additive database migrations
-- New functionality
-
-## Avoid for
-
-- Internal-only refactors
-- Performance tweaks that don't add capability
-- Bug fixes
-

package/docs/conventional-commits/type-fix.md

@@ -1,27 +0,0 @@
-# Bug Fixes (`fix`)
-
-Corrects faulty behavior, regressions, crashes, data corruption, or incorrect outputs.
-
-## Examples
-
-```text
-fix(auth): handle empty refresh token gracefully
-fix(api): correct null pointer exception in user lookup
-fix(ui): resolve button click event not firing
-fix(db): fix transaction rollback on connection failure
-```
-
-## Use for
-
-- Logic errors and bugs
-- Off-by-one fixes
-- Null handling improvements
-- Race condition fixes
-- Flaky behavior resolution
-- Data validation fixes
-
-## Avoid for
-
-- Refactors that don't change behavior
-- Performance improvements
-- New features

package/docs/conventional-commits/type-perf.md

@@ -1,24 +0,0 @@
-# Performance (`perf`)
-
-Makes the system faster or leaner without changing public behavior or semantics.
-
-**Use for**:
-- Algorithmic improvements
-- Caching implementations
-- Reduced memory allocations
-- Optimized database queries
-- I/O batching
-- Performance optimizations
-
-**Avoid for**:
-- Feature additions
-- Bug fixes
-- Refactoring
-
-**Examples**:
-```text
-perf(cache): implement Redis caching for user sessions
-perf(db): optimize user query with proper indexing
-perf(api): batch database writes to reduce latency
-perf(ui): lazy load images for better page performance
-```

package/docs/conventional-commits/type-refactor.md

@@ -1,24 +0,0 @@
-# Refactors (`refactor`)
-
-Internal code changes that do not alter external behavior; improves structure, readability, or maintainability.
-
-**Use for**:
-- Code reorganization
-- Function extraction
-- Module restructuring
-- Technical debt reduction
-- Code cleanup
-- Renaming variables/functions
-
-**Avoid for**:
-- Behavior changes
-- New features
-- Bug fixes
-
-**Examples**:
-```text
-refactor(auth): extract authentication logic into service
-refactor(api): split monolithic controller into modules
-refactor(ui): reorganize component hierarchy
-refactor(db): normalize database schema
-```

package/docs/conventional-commits/type-revert.md

@@ -1,16 +0,0 @@
-# Reverts (`revert`)
-
-Reverts a previous commit.
-
-## Examples
-
-```text
-revert: feat(api): add user authentication endpoint
-revert: fix(auth): handle empty refresh token gracefully
-```
-
-## Use for
-
-- Explicit rollbacks
-- Undoing problematic changes
-- Reverting breaking changes

package/docs/conventional-commits/type-style.md

@@ -1,24 +0,0 @@
-# Code Style (`style`)
-
-Non-functional changes that do not affect the meaning of code.
-
-**Use for**:
-- Code formatting
-- Whitespace changes
-- Linter fixes
-- Import reordering
-- Code style compliance
-- Prettier/ESLint fixes
-
-**Avoid for**:
-- Refactoring
-- Behavior changes
-- Bug fixes
-
-**Examples**:
-```text
-style: apply Prettier formatting
-style: fix ESLint warnings
-style: reorder imports alphabetically
-style: fix trailing whitespace
-```

package/docs/conventional-commits/type-test.md

@@ -1,24 +0,0 @@
-# Tests (`test`)
-
-Adds or updates tests without changing runtime behavior.
-
-**Use for**:
-- New unit tests
-- Integration test additions
-- Test fixture updates
-- Test refactoring
-- Test coverage improvements
-- End-to-end test additions
-
-**Avoid for**:
-- Bug fixes
-- Feature additions
-- Behavior changes
-
-**Examples**:
-```text
-test(api): add unit tests for user service
-test(ui): add integration tests for login flow
-test(db): add database migration tests
-test(auth): add OAuth2 flow tests
-```