@logickernel/agileflow 0.1.0 → 0.2.1

package/src/gitlab-push.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const https = require('https');
+
+/**
+ * Creates a tag via the GitLab API.
+ * @param {string} tagName - The tag name
+ * @param {string} message - The tag message
+ * @param {string} projectPath - GitLab project path (e.g., "group/project")
+ * @param {string} serverHost - GitLab server hostname
+ * @param {string} accessToken - GitLab access token
+ * @param {string} ref - Git ref to tag (branch name or commit SHA)
+ * @returns {Promise<Object>} API response
+ */
+function createTagViaAPI(tagName, message, projectPath, serverHost, accessToken, ref) {
+  return new Promise((resolve, reject) => {
+    const projectId = encodeURIComponent(projectPath);
+    
+    const postData = JSON.stringify({
+      tag_name: tagName,
+      ref: ref,
+      message: message,
+    });
+    
+    const options = {
+      hostname: serverHost,
+      port: 443,
+      path: `/api/v4/projects/${projectId}/repository/tags`,
+      method: 'POST',
+      headers: {
+        'PRIVATE-TOKEN': accessToken,
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+      },
+    };
+    
+    const req = https.request(options, (res) => {
+      let data = '';
+      
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(JSON.parse(data));
+        } else {
+          let errorMessage = `GitLab API request failed with status ${res.statusCode}`;
+          try {
+            const errorData = JSON.parse(data);
+            if (errorData.message) {
+              errorMessage += `: ${JSON.stringify(errorData.message)}`;
+            }
+            if (res.statusCode === 401) {
+              errorMessage += '\n\nAuthentication failed. The AGILEFLOW_TOKEN is invalid or expired.';
+              errorMessage += '\nTo fix this:';
+              errorMessage += '\n1. Go to your project Settings > Access Tokens';
+              errorMessage += '\n2. Check the expiration date of your AgileFlow Bot token';
+              errorMessage += '\n3. If expired, create a new token or extend the existing one';
+            } else if (res.statusCode === 403) {
+              errorMessage += '\n\nPermission denied. The AGILEFLOW_TOKEN needs "api" scope and maintainer role.';
+              errorMessage += '\nTo fix this:';
+              errorMessage += '\n1. Go to your project Settings > Access Tokens';
+              errorMessage += '\n2. Ensure your AgileFlow Bot token has "api" scope and maintainer role';
+              errorMessage += '\n3. If permissions are insufficient, create a new token with proper permissions';
+            }
+          } catch {
+            if (data) {
+              errorMessage += `\nResponse: ${data}`;
+            }
+          }
+          reject(new Error(errorMessage));
+        }
+      });
+    });
+    
+    req.on('error', (error) => {
+      reject(new Error(`Network error: ${error.message}`));
+    });
+    
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Pushes a tag to GitLab via the API.
+ * Requires AGILEFLOW_TOKEN environment variable.
+ * Uses CI_SERVER_HOST and CI_PROJECT_PATH from GitLab CI environment.
+ * @param {string} tagName - The tag name
+ * @param {string} message - The tag message
+ * @returns {Promise<void>}
+ */
+async function pushTag(tagName, message) {
+  const accessToken = process.env.AGILEFLOW_TOKEN;
+  const serverHost = process.env.CI_SERVER_HOST;
+  const projectPath = process.env.CI_PROJECT_PATH;
+  const commitSha = process.env.CI_COMMIT_SHA;
+  
+  if (!accessToken) {
+    const projectUrl = serverHost && projectPath ? `https://${serverHost}/${projectPath}` : 'your-project';
+    const projectTokenUrl = `${projectUrl}/-/settings/access_tokens`;
+    const cicdUrl = `${projectUrl}/-/settings/ci_cd#js-cicd-variables-settings`;
+    
+    throw new Error(
+      `AGILEFLOW_TOKEN environment variable is required but not set.\n\n` +
+      `To fix this:\n` +
+      `1. Create a project access token: ${projectTokenUrl}\n` +
+      `   - Name: AgileFlow Bot\n` +
+      `   - Role: maintainer\n` +
+      `   - Scopes: api\n` +
+      `2. Add it as a CI/CD variable: ${cicdUrl}\n` +
+      `   - Variable key: AGILEFLOW_TOKEN\n` +
+      `   - Protect variable: Yes (recommended)`
+    );
+  }
+  
+  if (!serverHost) {
+    throw new Error('CI_SERVER_HOST environment variable is not set. Are you running inside GitLab CI?');
+  }
+  
+  if (!projectPath) {
+    throw new Error('CI_PROJECT_PATH environment variable is not set. Are you running inside GitLab CI?');
+  }
+  
+  if (!commitSha) {
+    throw new Error('CI_COMMIT_SHA environment variable is not set. Are you running inside GitLab CI?');
+  }
+  
+  await createTagViaAPI(tagName, message || tagName, projectPath, serverHost, accessToken, commitSha);
+}
+
+module.exports = {
+  pushTag,
+};
+

package/src/index.js

@@ -1,50 +1,114 @@
 'use strict';
 
 const { version } = require('../package.json');
+const { processVersionInfo } = require('./utils');
 
 function printHelp() {
-  console.log(`agileflow - Automatic semantic versioning and changelog generation
+  console.log(`agileflow - Automatic semantic versioning and changelog generation tool.
 
 Usage:
   agileflow [options]
   agileflow <command>
 
 Commands:
-  gitlab-ci       Configure git, compute semver tag, and push to GitLab (CI mode)
+  <none>   Prints the current version, next version, commits, and changelog
+  push     Push a semantic version tag to the remote repository (native git)
+  gitlab   Push a semantic version tag via GitLab API (for GitLab CI)
+  github   Push a semantic version tag via GitHub API (for GitHub Actions)
 
 Options:
-  --branch <name>  Allow running on specified branch (default: main)
-  -h, --help       Show this help message
-  -v, --version    Show version number
+  --quiet        Only output the next version (or empty if no bump)
+  -h, --help     Show this help message
+  -v, --version  Show version number
 
-Examples:
-  agileflow                   # Run on main branch
-  agileflow --branch develop  # Run on develop branch
-  agileflow gitlab-ci
-
-For more information, visit: https://code.logickernel.com/kernel/agileflow
+For more information, visit: https://code.logickernel.com/tools/agileflow
 `);
 }
 
+/**
+ * Parses command line arguments.
+ * @param {Array<string>} args - Command line arguments
+ * @returns {{quiet: boolean}}
+ */
 function parseArgs(args) {
-  const parsed = { branch: 'main' };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--branch' && i + 1 < args.length) {
-      parsed.branch = args[i + 1];
-      i++;
+  return {
+    quiet: args.includes('--quiet'),
+  };
+}
+
+/**
+ * Displays version info to the console.
+ * @param {{currentVersion: string|null, nextVersion: string|null, commits: Array, changelog: string}} info
+ * @param {boolean} quiet - Only output the next version
+ */
+function displayVersionInfo(info, quiet) {
+  const { currentVersion, nextVersion, commits, changelog } = info;
+  
+  if (quiet) {
+    if (nextVersion) {
+      console.log(nextVersion);
     }
+    return;
+  }
+  
+  console.log(`Current version: ${currentVersion || 'none'}`);
+  console.log(`Next version: ${nextVersion || 'no bump needed'}`);
+  console.log(`Commits since current version: ${commits.length}`);
+  if (changelog) {
+    console.log(`\nChangelog:\n${changelog}`);
   }
-  return parsed;
 }
 
-async function runLocal(args) {
-  const { branch } = parseArgs(args);
-  const localMain = require('./local.js');
-  await localMain(branch);
+/**
+ * Handles a push command.
+ * @param {string} pushType - 'push', 'gitlab', or 'github'
+ * @param {{quiet: boolean}} options
+ */
+async function handlePushCommand(pushType, options) {
+  const info = await processVersionInfo();
+  
+  // Display version info
+  displayVersionInfo(info, options.quiet);
+  
+  // Skip push if no version bump needed
+  if (!info.nextVersion) {
+    if (!options.quiet) {
+      console.log('\nNo version bump needed. Skipping tag creation.');
+    }
+    return;
+  }
+  
+  // Get the appropriate push module
+  let pushModule;
+  switch (pushType) {
+    case 'push':
+      pushModule = require('./git-push');
+      break;
+    case 'gitlab':
+      pushModule = require('./gitlab-push');
+      break;
+    case 'github':
+      pushModule = require('./github-push');
+      break;
+  }
+  
+  // Create tag message from changelog
+  const tagMessage = info.changelog || info.nextVersion;
+  
+  if (!options.quiet) {
+    console.log(`\nCreating tag ${info.nextVersion}...`);
+  }
+  
+  await pushModule.pushTag(info.nextVersion, tagMessage);
+  
+  if (!options.quiet) {
+    console.log(`Tag ${info.nextVersion} created and pushed successfully.`);
+  }
 }
 
 async function main() {
   const [, , cmd, ...rest] = process.argv;
+  const options = parseArgs(cmd ? [cmd, ...rest] : rest);
 
   // Handle help
   if (cmd === '-h' || cmd === '--help' || cmd === 'help') {
@@ -58,14 +122,13 @@ async function main() {
     process.exit(0);
   }
 
-  // Handle gitlab-ci command
-  if (cmd === 'gitlab-ci') {
-    console.error('Error: gitlab-ci command is not yet implemented');
-    console.error('This feature will be available in a future release.');
-    process.exit(1);
+  // Handle push commands
+  if (cmd === 'push' || cmd === 'gitlab' || cmd === 'github') {
+    await handlePushCommand(cmd, options);
+    return;
   }
 
-  // Unknown command
+  // Unknown command (not an option)
   if (cmd && !cmd.startsWith('--')) {
     console.error(`Error: Unknown command "${cmd}"`);
     console.error();
@@ -73,8 +136,9 @@ async function main() {
     process.exit(1);
   }
 
-  // Default: run version calculation
-  await runLocal(cmd ? [cmd, ...rest] : rest);
+  // Default: show version info
+  const info = await processVersionInfo();
+  displayVersionInfo(info, options.quiet);
 }
 
 process.on('unhandledRejection', (err) => {

package/src/utils.js

@@ -1,6 +1,66 @@
 'use strict';
 
-const { runWithOutput, ensureGitRepo } = require('./git-utils');
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+/**
+ * Executes a shell command and returns the output.
+ * @param {string} command - The command to execute
+ * @param {Object} options - Execution options
+ * @returns {string} Command output
+ * @throws {Error} If command fails
+ */
+function runWithOutput(command, options = {}) {
+  try {
+    return execSync(command, { stdio: 'pipe', encoding: 'utf8', ...options });
+  } catch (error) {
+    const captured = {
+      stdout: error?.stdout ? String(error.stdout) : '',
+      stderr: error?.stderr ? String(error.stderr) : '',
+      message: error?.message || 'Command failed',
+      status: typeof error?.status === 'number' ? error.status : 1,
+    };
+    try {
+      Object.defineProperty(error, '_captured', { value: captured });
+    } catch {
+      error._captured = captured;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Executes a shell command without returning output.
+ * @param {string} command - The command to execute
+ * @param {Object} options - Execution options
+ * @throws {Error} If command fails
+ */
+function run(command, options = {}) {
+  execSync(command, { stdio: 'pipe', ...options });
+}
+
+/**
+ * Ensures the current directory is a git repository.
+ * @throws {Error} If the current directory is not a git repository
+ */
+function ensureGitRepo() {
+  if (!fs.existsSync('.git')) {
+    throw new Error('Current directory is not a git repository (missing .git directory).');
+  }
+}
+
+/**
+ * Gets the current branch name.
+ * @returns {string} Current branch name
+ * @throws {Error} If in detached HEAD state
+ */
+function getCurrentBranch() {
+  const branch = runWithOutput('git branch --show-current').trim();
+  if (!branch) {
+    throw new Error('Repository is in a detached HEAD state. Please check out a branch and try again.');
+  }
+  return branch;
+}
 
 // Conventional commit type configuration
 const TYPE_ORDER = ['feat', 'fix', 'perf', 'refactor', 'style', 'test', 'docs', 'build', 'ci', 'chore', 'revert'];
@@ -9,15 +69,12 @@ const SEMVER_PATTERN = /^v(\d+)\.(\d+)\.(\d+)(-[a-zA-Z0-9.-]+)?$/;
 
 /**
  * Fetches tags from remote (non-destructive) if a remote is configured.
- * This is a safe operation that doesn't modify the working directory.
  * @returns {boolean} True if tags were fetched, false if using local tags only
  */
-function fetchTagsLocally() {
+function fetchTags() {
   try {
     const remotes = runWithOutput('git remote').trim();
-    if (!remotes) {
-      return false;
-    }
+    if (!remotes) return false;
     runWithOutput('git fetch --tags --prune --prune-tags');
     return true;
   } catch {
@@ -25,21 +82,6 @@ function fetchTagsLocally() {
   }
 }
 
-/**
- * Validates that the current branch is the expected name.
- * @param {string} expectedName - The expected name of the branch
- * @throws {Error} If the current branch is not the expected name or in detached HEAD state
- */
-function validateBranchName(expectedName) {
-  const branch = runWithOutput('git branch --show-current').trim();
-  if (!branch) {
-    throw new Error('Repository is in a detached HEAD state. Please check out a branch and try again.');
-  }
-  if (branch !== expectedName) {
-    throw new Error(`Current branch is "${branch}", not "${expectedName}". Switch to ${expectedName} or use --branch ${branch}.`);
-  }
-}
-
 /**
  * Gets all tags pointing to a specific commit.
  * @param {string} commitSha - The commit SHA to check for tags
@@ -57,18 +99,13 @@ function getTagsForCommit(commitSha) {
 /**
  * Parses a conventional commit message.
  * @param {string} message - The commit message to parse
- * @returns {{type: string, breaking: boolean, scope: string, description: string}|null} Parsed commit or null if not conventional
+ * @returns {{type: string, breaking: boolean, scope: string, description: string}|null}
  */
 function parseConventionalCommit(message) {
   if (!message) return null;
-  
-  // Get the first line (subject) of the commit message
   const subject = message.split('\n')[0].trim();
-  
-  // Conventional commit pattern: type[!]?(scope)?: description
   const match = subject.match(/^(\w+)(!)?(?:\(([^)]+)\))?:\s+(.+)$/);
   if (!match) return null;
-  
   return {
     type: match[1].toLowerCase(),
     breaking: Boolean(match[2]),
@@ -79,17 +116,14 @@ function parseConventionalCommit(message) {
 
 /**
  * Expands commit information by finding the latest version and filtering commits.
- * Filters out commits that are older than the latest commit with a semver tag.
- * Commits are expected to be ordered from newest to oldest.
- * @param {Array<{hash: string, datetime: string, author: string, message: string, tags: Array<string>}>} commits - Array of commit objects
- * @returns {{latestVersion: string|null, commits: Array}} Object with latestVersion and filtered commits array
+ * @param {Array} commits - Array of commit objects (newest to oldest)
+ * @returns {{latestVersion: string|null, commits: Array}} Filtered commits since last version
  */
 function expandCommitInfo(commits) {
   if (!commits?.length) {
     return { latestVersion: null, commits: [] };
   }
   
-  // Find the first commit (newest) that has a semver tag
   const taggedIndex = commits.findIndex(commit => 
     commit.tags?.some(tag => SEMVER_PATTERN.test(tag))
   );
@@ -99,16 +133,17 @@ function expandCommitInfo(commits) {
   }
   
   const latestVersion = commits[taggedIndex].tags.find(tag => SEMVER_PATTERN.test(tag));
+  // Exclude the tagged commit itself - only return commits since the tag
   return {
     latestVersion,
-    commits: commits.slice(0, taggedIndex + 1),
+    commits: commits.slice(0, taggedIndex),
   };
 }
 
 /**
- * Extracts issue reference from commit message (e.g., #123 or (#123)).
+ * Extracts issue reference from commit message.
  * @param {string} message - The commit message
- * @returns {string|null} Issue reference like "(#123)" or null if not found
+ * @returns {string|null} Issue reference like "(#123)" or null
  */
 function extractIssueReference(message) {
   const match = message?.match(/\(?#(\d+)\)?/);
@@ -116,33 +151,26 @@ function extractIssueReference(message) {
 }
 
 /**
- * Formats the first line of commit message for changelog, removing the type prefix.
- * @param {string} subject - The first line of the commit message
+ * Formats commit description for changelog.
+ * @param {string} subject - First line of commit message
  * @param {Object} parsed - Parsed conventional commit info
- * @param {string} fullMessage - Full commit message to check for BREAKING CHANGE:
+ * @param {string} fullMessage - Full commit message
  * @returns {string} Formatted description
  */
 function formatChangelogDescription(subject, parsed, fullMessage) {
-  if (!parsed) {
-    // Not a conventional commit, use subject as-is
-    return subject;
-  }
-  
+  if (!parsed) return subject;
   let description = parsed.description;
-  
-  // Add BREAKING prefix if it's a breaking change (check both ! and BREAKING CHANGE:)
   const isBreaking = parsed.breaking || /BREAKING CHANGE:/i.test(fullMessage);
   if (isBreaking) {
     description = `BREAKING: ${description}`;
   }
-  
   return description;
 }
 
 /**
- * Parses a semver version string into its components.
- * @param {string|null} version - Version string like "v1.2.3" or "v1.2.3-beta"
- * @returns {{major: number, minor: number, patch: number}} Parsed version or {0,0,0} if invalid
+ * Parses a semver version string into components.
+ * @param {string|null} version - Version string like "v1.2.3"
+ * @returns {{major: number, minor: number, patch: number}}
  */
 function parseVersion(version) {
   if (!version) return { major: 0, minor: 0, patch: 0 };
@@ -152,14 +180,13 @@ function parseVersion(version) {
 }
 
 /**
- * Determines the version bump type based on commit analysis.
- * @param {{hasBreaking: boolean, hasFeat: boolean, hasPatchTypes: boolean}} analysis - Commit analysis
+ * Determines version bump type based on commit analysis.
+ * @param {{hasBreaking: boolean, hasFeat: boolean, hasPatchTypes: boolean}} analysis
  * @param {boolean} isPreOneZero - Whether current version is 0.x.x
- * @returns {'major'|'minor'|'patch'|'none'} The version bump type
+ * @returns {'major'|'minor'|'patch'|'none'}
  */
 function determineVersionBumpType(analysis, isPreOneZero) {
   const { hasBreaking, hasFeat, hasPatchTypes } = analysis;
-  
   if (isPreOneZero) {
     if (hasBreaking || hasFeat) return 'minor';
     if (hasPatchTypes) return 'patch';
@@ -173,17 +200,17 @@ function determineVersionBumpType(analysis, isPreOneZero) {
 
 /**
  * Applies a version bump to the current version.
- * @param {{major: number, minor: number, patch: number}} current - Current version
- * @param {'major'|'minor'|'patch'|'none'} bump - Bump type
- * @returns {string} Next version string like "v1.2.3"
+ * @param {{major: number, minor: number, patch: number}} current
+ * @param {'major'|'minor'|'patch'|'none'} bump
+ * @returns {string|null} Next version string or null if no bump
  */
 function applyVersionBump(current, bump) {
-  let { major, minor, patch } = current;
+  const { major, minor, patch } = current;
   switch (bump) {
     case 'major': return `v${major + 1}.0.0`;
     case 'minor': return `v${major}.${minor + 1}.0`;
     case 'patch': return `v${major}.${minor}.${patch + 1}`;
-    default: return `v${major}.${minor}.${patch}`;
+    default: return null;
   }
 }
 
@@ -244,20 +271,22 @@ function generateTypeChangelog(commits) {
   
   const lines = [];
   for (const entry of noScope) {
-    lines.push(`- ${entry.description}${entry.issueRef}`);
+    const ref = entry.issueRef ? ` ${entry.issueRef}` : '';
+    lines.push(`- ${entry.description}${ref}`);
   }
   for (const scope of Object.keys(byScope).sort()) {
     for (const entry of byScope[scope]) {
-      lines.push(`- **${scope}**: ${entry.description}${entry.issueRef}`);
+      const ref = entry.issueRef ? ` ${entry.issueRef}` : '';
+      lines.push(`- **${scope}**: ${entry.description}${ref}`);
     }
   }
   return lines;
 }
 
 /**
- * Calculates the next version and generates a changelog from expanded commit info.
- * @param {{latestVersion: string|null, commits: Array}} expandedInfo - Output from expandCommitInfo
- * @returns {{nextVersion: string, changelog: string}} Object with nextVersion and changelog
+ * Calculates the next version and generates a changelog.
+ * @param {{latestVersion: string|null, commits: Array}} expandedInfo
+ * @returns {{nextVersion: string|null, changelog: string}}
  */
 function calculateNextVersionAndChangelog(expandedInfo) {
   const { latestVersion, commits } = expandedInfo;
@@ -278,7 +307,6 @@ function calculateNextVersionAndChangelog(expandedInfo) {
     changelogLines.push('');
   }
   
-  // Remove trailing empty line
   if (changelogLines.at(-1) === '') {
     changelogLines.pop();
   }
@@ -287,54 +315,18 @@ function calculateNextVersionAndChangelog(expandedInfo) {
 }
 
 /**
- * Processes version information for a branch, returning version details and changelog.
- * @param {string} branch - The branch to process
- * @returns {Promise<{previousVersion: string|null, nextVersion: string, commits: Array, conventionalCommits: Object, changelog: string}>} Promise resolving to version info
- */
-async function processVersionInfo(branch) {
-  ensureGitRepo();
-  validateBranchName(branch);
-  fetchTagsLocally();
-  
-  const allCommits = getAllBranchCommits(branch);
-  const expandedInfo = expandCommitInfo(allCommits);
-  const { latestVersion, commits } = expandedInfo;
-  
-  // Group commits by conventional type
-  const conventionalCommits = Object.fromEntries(TYPE_ORDER.map(t => [t, []]));
-  for (const commit of commits) {
-    const parsed = parseConventionalCommit(commit.message);
-    if (parsed && conventionalCommits[parsed.type]) {
-      conventionalCommits[parsed.type].push({ ...commit, conventional: parsed });
-    }
-  }
-  
-  const { nextVersion, changelog } = calculateNextVersionAndChangelog(expandedInfo);
-  
-  return {
-    previousVersion: latestVersion,
-    nextVersion,
-    commits,
-    conventionalCommits,
-    changelog,
-  };
-}
-
-/**
- * Retrieves all commits in the history of the specified branch, including merged commits.
- * Returns a simplified array with commit hash, datetime, author, commit message, and tags.
+ * Retrieves all commits in the history of the specified branch.
  * @param {string} branch - The branch to get commits from
- * @returns {Array<{hash: string, datetime: string, author: string, message: string, tags: Array<string>}>} Array of commit objects
+ * @returns {Array<{hash: string, datetime: string, author: string, message: string, tags: Array<string>}>}
  */
 function getAllBranchCommits(branch) {
   try {
-    // Verify the branch exists
     runWithOutput(`git rev-parse --verify ${branch}`);
   } catch {
     return [];
   }
   
-  const RS = '\x1E'; // Record Separator
+  const RS = '\x1E';
   const COMMIT_SEP = `${RS}${RS}`;
   
   try {
@@ -363,14 +355,37 @@ function getAllBranchCommits(branch) {
   }
 }
 
+/**
+ * Processes version information for the current branch.
+ * @returns {Promise<{currentVersion: string|null, nextVersion: string|null, commits: Array, changelog: string}>}
+ */
+async function processVersionInfo() {
+  ensureGitRepo();
+  const branch = getCurrentBranch();
+  fetchTags();
+  
+  const allCommits = getAllBranchCommits(branch);
+  const expandedInfo = expandCommitInfo(allCommits);
+  const { latestVersion, commits } = expandedInfo;
+  const { nextVersion, changelog } = calculateNextVersionAndChangelog(expandedInfo);
+  
+  return {
+    currentVersion: latestVersion,
+    nextVersion,
+    commits,
+    changelog,
+  };
+}
+
 module.exports = {
+  run,
+  runWithOutput,
   ensureGitRepo,
-  fetchTagsLocally,
-  validateBranchName,
+  getCurrentBranch,
+  fetchTags,
   getAllBranchCommits,
   expandCommitInfo,
   calculateNextVersionAndChangelog,
   processVersionInfo,
   parseConventionalCommit,
 };
-