@logickernel/agileflow 0.16.1 → 0.17.1

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.16.1",
+  "version": "0.17.1",
   "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

@@ -15,11 +15,10 @@ Commands:
   push [remote]  Push a semantic version tag to the remote repository (default: origin)
   gitlab   Create a semantic version tag via GitLab API (for GitLab CI)
   github   Create a semantic version tag via GitHub API (for GitHub Actions)
+  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
 `);
@@ -28,21 +27,19 @@ 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.
  */
-const VALID_COMMANDS = ['push', 'gitlab', 'github'];
+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}`);
@@ -51,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) {
@@ -91,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':
@@ -117,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();
@@ -149,7 +126,7 @@ async function main() {
   }
 
   // Handle version
-  if (cmd === '-v' || cmd === '--version' || cmd === 'version') {
+  if (cmd === 'version') {
     console.log(version);
     process.exit(0);
   }
@@ -157,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;
   }
 
@@ -180,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

@@ -108,11 +108,10 @@ function fetchTags() {
 }
 
 /**
- * Builds a map of commit SHA → tag names for all tags in the repository.
- * Uses a single git call instead of one per commit.
+ * Builds a tag map from locally stored tags.
  * @returns {Map<string, string[]>}
  */
-function buildTagMap() {
+function buildTagMapFromLocal() {
   try {
     // %(objecttype) distinguishes lightweight (commit) from annotated (tag) refs.
     // %(*objectname) is the peeled commit SHA for annotated tags, but may be empty
@@ -152,6 +151,60 @@ function buildTagMap() {
   }
 }
 
+/**
+ * Builds a tag map by reading tags directly from the remote via ls-remote.
+ * Used as a fallback when git fetch --tags fails (e.g. in shallow CI clones).
+ * Does not store anything locally.
+ * @returns {Map<string, string[]>}
+ */
+function buildTagMapFromRemote() {
+  try {
+    const remotes = runWithOutput('git remote').trim();
+    if (!remotes) return new Map();
+    const remote = remotes.split('\n')[0].trim();
+    const output = runWithOutput(`git ls-remote --tags ${remote}`).trim();
+    if (!output) return new Map();
+
+    const map = new Map();
+    const direct = new Map(); // tagName -> SHA (tag obj or commit)
+    const peeled = new Map(); // tagName -> commit SHA (from ^{} entries)
+
+    for (const line of output.split('\n')) {
+      const tabIdx = line.indexOf('\t');
+      if (tabIdx === -1) continue;
+      const sha = line.slice(0, tabIdx).trim();
+      const ref = line.slice(tabIdx + 1).trim();
+      if (ref.endsWith('^{}')) {
+        // Annotated tag: peeled entry gives the commit SHA
+        peeled.set(ref.slice('refs/tags/'.length, -3), sha);
+      } else if (ref.startsWith('refs/tags/')) {
+        direct.set(ref.slice('refs/tags/'.length), sha);
+      }
+    }
+
+    for (const [name, sha] of direct) {
+      const commitSha = peeled.get(name) || sha;
+      if (!map.has(commitSha)) map.set(commitSha, []);
+      map.get(commitSha).push(name);
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Builds a map of commit SHA → tag names for all tags in the repository.
+ * Tries local tags first; falls back to reading from the remote when local
+ * tags are absent (common in shallow CI clones where git fetch --tags fails).
+ * @returns {Map<string, string[]>}
+ */
+function buildTagMap() {
+  const local = buildTagMapFromLocal();
+  if (local.size > 0) return local;
+  return buildTagMapFromRemote();
+}
+
 /**
  * Parses a conventional commit message.
  * @param {string} message - The commit message to parse

package/docs/README.md

@@ -1,60 +0,0 @@
-# AgileFlow Documentation
-
-Welcome to the AgileFlow documentation! AgileFlow is a lightweight, platform-agnostic tool for automatic semantic versioning and changelog generation.
-
-```bash
-npx @logickernel/agileflow
-```
-
-## Quick Navigation
-
-| I want to... | Read this |
-|--------------|-----------|
-| Get started quickly | [Getting Started](./getting-started.md) |
-| Set up CI/CD integration | [Installation Guide](./installation.md) |
-| Understand the CLI | [CLI Reference](./cli-reference.md) |
-| Learn the methodology | [Version-Centric CI/CD](./version-centric-cicd.md) |
-| Fix an issue | [Troubleshooting](./troubleshooting.md) |
-
-## Documentation Index
-
-### Getting Started
-- **[Getting Started](./getting-started.md)** — Quick start guide for new users
-- **[Installation Guide](./installation.md)** — Setup for GitHub Actions and GitLab CI
-- **[CLI Reference](./cli-reference.md)** — Commands, options, and examples
-
-### Core Concepts
-- **[Version-Centric CI/CD](./version-centric-cicd.md)** — The methodology behind AgileFlow
-- **[Branching Strategy](./branching-strategy.md)** — How to structure your Git workflow
-- **[Conventional Commits](./conventional-commits.md)** — Commit message format and version impact
-- **[Release Management](./release-management.md)** — Managing releases and versions
-
-### Reference
-- **[Configuration](./configuration.md)** — Environment variables and options
-- **[Best Practices](./best-practices.md)** — Recommended patterns and tips
-- **[Migration Guide](./migration-guide.md)** — Transitioning from other CI/CD approaches
-- **[Troubleshooting](./troubleshooting.md)** — Common issues and solutions
-
-## Platform Support
-
-AgileFlow works with any Git repository and provides native integrations for:
-
-- **GitHub Actions** — Uses GitHub API for tag creation
-- **GitLab CI** — Uses GitLab API for tag creation
-- **Any CI/CD** — Native git push for other platforms
-
-## Contributing to Documentation
-
-We welcome improvements to our documentation! Please:
-
-1. Follow the existing style and tone
-2. Use clear, concise language
-3. Include practical examples
-4. Test any code examples or commands
-5. Submit changes via pull/merge requests
-
-## External Resources
-
-- [Main README](../README.md) — Project overview and quick start
-- [Conventional Commits Specification](https://www.conventionalcommits.org/)
-- [Semantic Versioning Specification](https://semver.org/)