@logickernel/agileflow 0.17.0 → 0.20.0

package/docs/reference/cli.md

@@ -0,0 +1,124 @@
+# CLI Reference
+
+## Installation
+
+Run without installing:
+```bash
+npx @logickernel/agileflow
+```
+
+Or install globally:
+```bash
+npm install -g @logickernel/agileflow
+```
+
+---
+
+## Commands
+
+### `agileflow` (no command)
+
+Analyzes the repository and prints the current version, next version, commits, and changelog. Does not create or modify anything.
+
+```bash
+agileflow
+```
+
+```
+Commits since current version (3):
+  a1b2c3d feat: add dark mode
+  d4e5f6a fix: resolve login timeout
+  7g8h9i0 docs: update README
+
+Current version: v1.4.2
+New version:     v1.5.0
+
+Changelog:
+
+### Features
+- add dark mode
+
+### Bug fixes
+- resolve login timeout
+```
+
+If no bump is needed, `New version` shows `no bump needed` and no changelog is printed.
+
+---
+
+### `agileflow push [remote]`
+
+Creates an annotated git tag and pushes it to the specified remote. Uses standard git commands — requires git credentials to be configured.
+
+```bash
+agileflow push           # pushes to origin
+agileflow push upstream  # pushes to a different remote
+```
+
+If no bump is needed, exits without creating a tag.
+
+---
+
+### `agileflow 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 and `Maintainer` role
+
+**Provided automatically by GitLab CI:**
+- `CI_SERVER_HOST` — GitLab server hostname
+- `CI_PROJECT_PATH` — Project path (e.g., `group/project`)
+- `CI_COMMIT_SHA` — Commit to tag
+
+---
+
+### `agileflow 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: Read and write` permission
+
+**Provided automatically by GitHub Actions:**
+- `GITHUB_REPOSITORY` — Repository (e.g., `owner/repo`)
+- `GITHUB_SHA` — Commit to tag
+
+---
+
+### `agileflow version`
+
+Prints the AgileFlow tool version.
+
+```bash
+agileflow version
+# 0.17.0
+```
+
+---
+
+### `agileflow --help`
+
+Prints usage information.
+
+```bash
+agileflow --help
+agileflow -h
+```
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success (including "no bump needed") |
+| `1` | Error (authentication failure, git error, API error, unknown command) |

package/docs/reference/conventional-commits.md

@@ -0,0 +1,133 @@
+# Conventional Commits
+
+AgileFlow uses [Conventional Commits](https://www.conventionalcommits.org/) to determine the next semantic version and generate changelogs.
+
+## Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Examples:
+```
+feat: add user authentication
+fix(api): handle timeout errors
+feat!: remove deprecated endpoints
+docs: update README
+```
+
+---
+
+## Version impact
+
+| Commit | Example | Before v1.0.0 | v1.0.0 and after |
+|--------|---------|---------------|------------------|
+| Breaking change | `feat!: redesign API` | minor bump | major bump |
+| `feat` | `feat: add login` | minor bump | minor bump |
+| `fix` | `fix: resolve crash` | patch bump | patch bump |
+| Everything else | `docs: update README` | no bump | no bump |
+
+When multiple commits exist since the last tag, the highest-priority bump wins.
+
+### Marking breaking changes
+
+```bash
+# Using ! after the type
+feat!: remove deprecated API endpoints
+
+# Using a BREAKING CHANGE footer
+feat: change response format
+
+BREAKING CHANGE: Response now uses camelCase instead of snake_case
+```
+
+---
+
+## Commit types
+
+| Type | Use for | Changelog |
+|------|---------|-----------|
+| `feat` | New functionality | Yes — Features |
+| `fix` | Bug fixes | Yes — Bug fixes |
+| `perf` | Performance improvements | Yes — Performance improvements |
+| `refactor` | Code restructuring (no behavior change) | Yes — Other changes |
+| `docs` | Documentation only | Yes — Documentation |
+| `ci` | CI/CD configuration | Yes — Other changes |
+| `test` | Tests only | No |
+| `style` | Formatting, whitespace | No |
+| `chore` | Maintenance tasks, work in progress | No |
+| `build` | Build system changes | No |
+| `revert` | Revert a previous commit | No |
+
+Types not in this table appear under "Other changes" in the changelog.
+
+---
+
+## Choosing the right type
+
+1. **Adds new functionality users can use?** → `feat`
+2. **Fixes broken functionality?** → `fix`
+3. **Work in progress or maintenance with no user impact?** → `chore` (excluded from changelog)
+4. **Performance improvement?** → `perf`
+5. **Refactoring internal code?** → `refactor`
+6. **Breaking any existing behavior?** → add `!` after the type (e.g., `feat!:`, `fix!:`)
+
+---
+
+## Best practices
+
+Use present tense: `feat: add login` not `feat: added login`
+
+Be specific: `fix: prevent timeout on uploads larger than 100MB` not `fix: fix timeout`
+
+Use `chore:` for work in progress so it doesn't add noise to the changelog:
+```bash
+# ✅ Won't appear in changelog
+chore: scaffold form validation module
+
+# ❌ Will appear as "Other changes" — misleading
+refactor: scaffold form validation module
+```
+
+Use scopes to clarify context when helpful:
+```bash
+feat(auth): add OAuth2 support
+fix(api): handle empty response body
+```
+
+---
+
+## Changelog format
+
+AgileFlow groups commits by type:
+
+```
+v1.5.0
+
+### Features
+- add dark mode
+- add keyboard shortcuts
+
+### Bug fixes
+- resolve login timeout
+- fix pagination on mobile
+
+### Performance improvements
+- optimize image loading
+```
+
+Breaking changes are highlighted:
+
+```
+v2.0.0
+
+### Features
+- BREAKING: remove deprecated v1 API endpoints
+- add new v2 API
+```
+
+Non-conventional commits (no `type:` prefix) appear under "Other changes" and trigger no version bump.

package/docs/start-here/getting-started.md

@@ -0,0 +1,83 @@
+# Getting Started
+
+## Run it now
+
+No installation needed. Run AgileFlow in any git repository:
+
+```bash
+npx @logickernel/agileflow
+```
+
+This is a read-only preview — it never creates tags or modifies anything.
+
+### Understanding the output
+
+```
+Commits since current version (3):
+  a1b2c3d feat: add dark mode
+  d4e5f6a fix: resolve login timeout
+  7g8h9i0 docs: update README
+
+Current version: v1.4.2
+New version:     v1.5.0
+
+Changelog:
+
+### Features
+- add dark mode
+
+### Bug fixes
+- resolve login timeout
+```
+
+- **Current version** — the highest semver tag found in the commit history
+- **New version** — calculated from the commit types since that tag
+- **Changelog** — grouped by commit type; `docs`, `chore`, and `style` commits are omitted from the changelog but still analyzed for versioning
+
+If all commits since the last tag are `docs`, `chore`, `style`, or other non-bumping types, AgileFlow prints `no bump needed` and skips tag creation.
+
+### Starting from scratch
+
+No version tags yet? AgileFlow starts from `v0.0.0`:
+
+```bash
+git commit -m "feat: initial project setup"
+npx @logickernel/agileflow
+# New version: v0.1.0
+```
+
+### Creating v1.0.0
+
+`v1.0.0` signals your first stable release. Create it manually when you're ready:
+
+```bash
+git tag -a v1.0.0 -m "First stable release"
+git push origin v1.0.0
+```
+
+After `v1.0.0`, breaking changes bump the major version (e.g., `v2.0.0`). Before it, they bump minor (e.g., `v0.2.0`).
+
+---
+
+## Set up CI/CD
+
+Pick your platform:
+
+- [GitHub Actions](../guides/github-actions.md)
+- [GitLab CI](../guides/gitlab-ci.md)
+- [Other CI/CD](../guides/other-ci.md)
+
+---
+
+## How version bumps are calculated
+
+AgileFlow picks the highest-priority bump across all commits since the last tag:
+
+| Commit | Example | Before v1.0.0 | v1.0.0 and after |
+|--------|---------|---------------|------------------|
+| Breaking change | `feat!: redesign API` | minor bump | major bump |
+| New feature | `feat: add login` | minor bump | minor bump |
+| Bug fix | `fix: resolve crash` | patch bump | patch bump |
+| Everything else | `docs: update README` | no bump | no bump |
+
+See [Conventional Commits](../reference/conventional-commits.md) for the full format reference.

package/package.json

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

package/src/git-push.js

@@ -14,7 +14,7 @@ const os = require('os');
  * @param {boolean} quiet - If true, suppress success message
  * @returns {Promise<void>}
  */
-async function pushTag(tagName, message, quiet = false, remote = 'origin') {
+async function pushTag(tagName, message, remote = 'origin') {
   const safeTag = String(tagName).replace(/"/g, '\\"');
   const safeRemote = String(remote).replace(/"/g, '\\"');
   
@@ -29,9 +29,7 @@ async function pushTag(tagName, message, quiet = false, remote = 'origin') {
     // Push to remote
     execSync(`git push "${safeRemote}" "${safeTag}"`, { stdio: 'pipe' });
     
-    if (!quiet) {
-      console.log(`Tag ${tagName} created and pushed successfully.`);
-    }
+    console.log(`Tag ${tagName} created and pushed successfully.`);
   } finally {
     // Clean up temp file
     try {

package/src/github-push.js

@@ -130,7 +130,7 @@ function makeRequest({ method, path, accessToken, body }) {
  * @param {boolean} quiet - If true, suppress success message
  * @returns {Promise<void>}
  */
-async function pushTag(tagName, message, quiet = false, remote = 'origin') {
+async function pushTag(tagName, message, remote = 'origin') {
   const accessToken = process.env.AGILEFLOW_TOKEN;
   const repository = process.env.GITHUB_REPOSITORY;
   const commitSha = process.env.GITHUB_SHA;
@@ -155,9 +155,7 @@ async function pushTag(tagName, message, quiet = false, remote = 'origin') {
   
   await createTagViaAPI(tagName, message || tagName, repository, accessToken, commitSha);
   
-  if (!quiet) {
-    console.log(`Tag ${tagName} created and pushed successfully.`);
-  }
+  console.log(`Tag ${tagName} created and pushed successfully.`);
 }
 
 module.exports = {

package/src/gitlab-push.js

@@ -96,7 +96,7 @@ function createTagViaAPI(tagName, message, projectPath, serverHost, accessToken,
  * @param {string} message - The tag message
  * @returns {Promise<void>}
  */
-async function pushTag(tagName, message, quiet = false, remote = 'origin') {
+async function pushTag(tagName, message, remote = 'origin') {
   const accessToken = process.env.AGILEFLOW_TOKEN;
   const serverHost = process.env.CI_SERVER_HOST;
   const projectPath = process.env.CI_PROJECT_PATH;
@@ -134,10 +134,8 @@ async function pushTag(tagName, message, quiet = false, remote = 'origin') {
   
   await createTagViaAPI(tagName, message || tagName, projectPath, serverHost, accessToken, commitSha);
 
-  if (!quiet) {
-    const commitUrl = `https://${process.env.CI_SERVER_HOST}/${process.env.CI_PROJECT_PATH}/-/commit/${process.env.CI_COMMIT_SHA}/pipelines`;
-    console.log(`Tag ${tagName} created and pushed successfully.\nView the build pipelines at: ${commitUrl}`);
-  }
+  const commitUrl = `https://${process.env.CI_SERVER_HOST}/${process.env.CI_PROJECT_PATH}/-/commit/${process.env.CI_COMMIT_SHA}/pipelines`;
+  console.log(`Tag ${tagName} created and pushed successfully.\nView the build pipelines at: ${commitUrl}`);
 }
 
 module.exports = {

package/src/index.js

@@ -18,9 +18,7 @@ Commands:
   version  Print the agileflow tool version
 
 Options:
-  --quiet        Only output the next version (or empty if no bump)
   -h, --help     Show this help message
-  -v, --version  Show version number
 
 For more information, visit: https://code.logickernel.com/tools/agileflow
 `);
@@ -29,7 +27,7 @@ For more information, visit: https://code.logickernel.com/tools/agileflow
 /**
  * Valid options that can be passed to commands.
  */
-const VALID_OPTIONS = ['--quiet', '--help', '-h', '--version', '-v'];
+const VALID_OPTIONS = ['--help', '-h'];
 
 /**
  * Valid commands.
@@ -39,11 +37,9 @@ const VALID_COMMANDS = ['push', 'gitlab', 'github', 'version'];
 /**
  * Parses command line arguments and validates them.
  * @param {Array<string>} args - Command line arguments
- * @returns {{quiet: boolean}}
  * @throws {Error} If invalid options are found
  */
 function parseArgs(args) {
-  // Check for invalid options
   for (const arg of args) {
     if (arg.startsWith('--') && !VALID_OPTIONS.includes(arg)) {
       throw new Error(`Unknown option: ${arg}`);
@@ -52,28 +48,15 @@ function parseArgs(args) {
       throw new Error(`Unknown option: ${arg}`);
     }
   }
-  
-  return {
-    quiet: args.includes('--quiet'),
-  };
 }
 
 /**
  * Displays version info to the console.
  * @param {{currentVersion: string|null, newVersion: string|null, commits: Array, changelog: string}} info
- * @param {boolean} quiet - Only output the new version
  */
-function displayVersionInfo(info, quiet) {
+function displayVersionInfo(info) {
   const { currentVersion, newVersion, commits, changelog } = info;
-  
-  if (quiet) {
-    if (newVersion) {
-      console.log(newVersion);
-    }
-    return;
-  }
-  
-  
+
   // List commits
   console.log(`Commits since current version (${commits.length}):`);
   for (const commit of commits) {
@@ -92,20 +75,17 @@ function displayVersionInfo(info, quiet) {
 /**
  * Handles a push command.
  * @param {string} pushType - 'push', 'gitlab', or 'github'
- * @param {{quiet: boolean}} options
+ * @param {string} remote
  */
-async function handlePushCommand(pushType, options, remote = 'origin') {
+async function handlePushCommand(pushType, remote = 'origin') {
   const info = await processVersionInfo();
-  
-  // Display version info
-  displayVersionInfo(info, options.quiet);
-  
-  // Skip push if no version bump needed
+
+  displayVersionInfo(info);
+
   if (!info.newVersion) {
     return;
   }
-  
-  // Get the appropriate push module
+
   let pushModule;
   switch (pushType) {
     case 'push':
@@ -118,23 +98,19 @@ async function handlePushCommand(pushType, options, remote = 'origin') {
       pushModule = require('./github-push');
       break;
   }
-  
-  // Create tag message from changelog
+
   const tagMessage = info.changelog || info.newVersion;
-  
-  if (!options.quiet) {
-    console.log(`\nCreating tag ${info.newVersion}...`);
-  }
-  
-  await pushModule.pushTag(info.newVersion, tagMessage, options.quiet, remote);
+
+  console.log(`\nCreating tag ${info.newVersion}...`);
+
+  await pushModule.pushTag(info.newVersion, tagMessage, remote);
 }
 
 async function main() {
   const [, , cmd, ...rest] = process.argv;
   
-  let options;
   try {
-    options = parseArgs(cmd ? [cmd, ...rest] : rest);
+    parseArgs(cmd ? [cmd, ...rest] : rest);
   } catch (err) {
     console.error(`Error: ${err.message}`);
     console.error();
@@ -150,7 +126,7 @@ async function main() {
   }
 
   // Handle version
-  if (cmd === '-v' || cmd === '--version' || cmd === 'version') {
+  if (cmd === 'version') {
     console.log(version);
     process.exit(0);
   }
@@ -158,7 +134,7 @@ async function main() {
   // Handle push commands
   if (cmd === 'push' || cmd === 'gitlab' || cmd === 'github') {
     const remote = rest.find(arg => !arg.startsWith('-')) || 'origin';
-    await handlePushCommand(cmd, options, remote);
+    await handlePushCommand(cmd, remote);
     return;
   }
 
@@ -181,7 +157,7 @@ async function main() {
 
   // Default: show version info
   const info = await processVersionInfo();
-  displayVersionInfo(info, options.quiet);
+  displayVersionInfo(info);
 }
 
 process.on('unhandledRejection', (err) => {

package/src/utils.js

@@ -224,9 +224,57 @@ function parseConventionalCommit(message) {
 }
 
 /**
- * Expands commit information by finding the latest version and filtering commits.
- * @param {Array} commits - Array of commit objects (newest to oldest)
- * @returns {{latestVersion: string|null, commits: Array}} Filtered commits since last version
+ * Finds the highest semver version tag in a list of commits.
+ * @param {Array} commits - The commits to scan
+ * @returns {{latestVersion: string|null, taggedCommitHash: string|null}}
+ */
+function findLatestVersionTag(commits) {
+  if (!commits?.length) {
+    return { latestVersion: null, taggedCommitHash: null };
+  }
+
+  let bestHash = null;
+  let bestVersion = null;
+
+  for (let i = 0; i < commits.length; i++) {
+    const semverTags = commits[i].tags?.filter(tag => SEMVER_PATTERN.test(tag));
+    if (!semverTags?.length) continue;
+
+    const highest = semverTags.sort((a, b) => {
+      const pa = parseVersion(a);
+      const pb = parseVersion(b);
+      if (pb.major !== pa.major) return pb.major - pa.major;
+      if (pb.minor !== pa.minor) return pb.minor - pa.minor;
+      return pb.patch - pa.patch;
+    })[0];
+
+    if (!bestVersion) {
+      bestVersion = highest;
+      bestHash = commits[i].hash;
+    } else {
+      const pBest = parseVersion(bestVersion);
+      const pCand = parseVersion(highest);
+      const isHigher =
+        pCand.major > pBest.major ||
+        (pCand.major === pBest.major && pCand.minor > pBest.minor) ||
+        (pCand.major === pBest.major && pCand.minor === pBest.minor && pCand.patch > pBest.patch);
+      if (isHigher) {
+        bestVersion = highest;
+        bestHash = commits[i].hash;
+      }
+    }
+  }
+
+  return { latestVersion: bestVersion, taggedCommitHash: bestHash };
+}
+
+/**
+ * Expands commit info by finding the latest version tag and returning
+ * only commits since that tag. Uses positional slicing from a date-sorted
+ * commit list — for accurate results with merge commits, prefer using
+ * findLatestVersionTag + getCommitsSinceTag (as processVersionInfo does).
+ * @param {Array} commits - All commits (date-sorted, newest first)
+ * @returns {{latestVersion: string|null, commits: Array}}
  */
 function expandCommitInfo(commits) {
   if (!commits?.length) {
@@ -548,6 +596,45 @@ function getAllBranchCommits(branch) {
   }
 }
 
+/**
+ * Retrieves commits reachable from the branch but not from the given tag,
+ * using git's native range selection so that date ordering cannot cause
+ * commits from merged branches to be missed.
+ * @param {string} tagHash - The commit hash of the version tag
+ * @param {string} branchSha - The resolved SHA of the branch tip
+ * @returns {Array<{hash: string, datetime: string, author: string, message: string, tags: Array<string>}>}
+ */
+function getCommitsSinceTag(tagHash, branchSha) {
+  const tagMap = buildTagMap();
+  const RS = '\x1E';
+  const COMMIT_SEP = `${RS}${RS}`;
+
+  try {
+    const logCmd = `git log --format=%H${RS}%ai${RS}%an${RS}%B${COMMIT_SEP} ${tagHash}..${branchSha}`;
+    const output = runWithOutput(logCmd).trim();
+    if (!output) return [];
+
+    return output
+      .split(COMMIT_SEP)
+      .filter(block => block.trim())
+      .map(block => {
+        const parts = block.split(RS);
+        if (parts.length < 4) return null;
+        const hash = parts[0].trim();
+        return {
+          hash,
+          datetime: parts[1].trim(),
+          author: parts[2].trim(),
+          message: parts.slice(3).join(RS).trim(),
+          tags: tagMap.get(hash) || [],
+        };
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Processes version information for the current branch.
  * @returns {Promise<{currentVersion: string|null, newVersion: string|null, commits: Array, changelog: string}>}
@@ -556,12 +643,25 @@ async function processVersionInfo() {
   ensureGitRepo();
   const branch = getCurrentBranch();
   fetchTags();
-  
+
   const allCommits = getAllBranchCommits(branch);
-  const expandedInfo = expandCommitInfo(allCommits);
-  const { latestVersion, commits } = expandedInfo;
+  const { latestVersion, taggedCommitHash } = findLatestVersionTag(allCommits);
+
+  let commits;
+  if (taggedCommitHash) {
+    // Use git's range selection (tag..HEAD) to correctly identify all commits
+    // since the tag, regardless of commit date ordering. This fixes an issue
+    // where commits from merged feature branches could be missed because their
+    // dates are older than the tagged commit.
+    const branchSha = allCommits[0]?.hash;
+    commits = branchSha ? getCommitsSinceTag(taggedCommitHash, branchSha) : [];
+  } else {
+    commits = allCommits;
+  }
+
+  const expandedInfo = { latestVersion, commits };
   const { newVersion, changelog } = calculateNextVersionAndChangelog(expandedInfo);
-  
+
   return {
     currentVersion: latestVersion,
     newVersion,
@@ -577,6 +677,8 @@ module.exports = {
   getCurrentBranch,
   fetchTags,
   getAllBranchCommits,
+  findLatestVersionTag,
+  getCommitsSinceTag,
   expandCommitInfo,
   calculateNextVersionAndChangelog,
   processVersionInfo,