gitpal-cli 1.0.4 → 1.0.5

package/README.md

@@ -157,7 +157,7 @@ gitpal changelog --ver 2.0.0
 
 # 📄 CHANGELOG v2.0.0:
 #
-# ## [2.0.0] - 2026-03-21
+# ## [2.0.0] - 2026-03-22
 #
 # ### Features
 # - Payment gateway integration
@@ -223,6 +223,61 @@ gitpal review --review-only    # Only review, skip commit step
 
 ---
 
+### `gitpal explain` — Explain Any Code
+Explains any file, function or commit in plain English — perfect for understanding old code or teammate's changes.
+
+```bash
+# Explain an entire file
+gitpal explain src/auth.js
+
+# 📖 Explaining file: auth.js
+# ──────────────────────────────────────────────────
+# This file handles all authentication logic.
+# It has 4 main functions:
+# - login() — verifies user credentials
+# - register() — creates new user account
+# - verifyToken() — checks if JWT is valid
+# - logout() — clears user session
+#
+# Depends on: bcrypt, jsonwebtoken, User model
+```
+
+```bash
+# Explain a specific function
+gitpal explain src/payment.js --function processPayment
+
+# 📖 Explaining function: processPayment()
+# ──────────────────────────────────────────────────
+# This function handles Razorpay payment processing.
+# Step 1 — Creates payment order with amount
+# Step 2 — Sends to Razorpay API
+# Step 3 — Waits for webhook confirmation
+# Step 4 — Updates database on success
+#
+# Depends on: razorpay, axios, Order model
+```
+
+```bash
+# Explain any commit
+gitpal explain a3f2c1
+
+# 📖 Explaining commit: a3f2c1
+# ──────────────────────────────────────────────────
+# This commit added JWT authentication.
+# - Created login function with bcrypt password check
+# - Added JWT token generation on success
+# - Protected private routes with middleware
+```
+
+**Options:**
+```bash
+gitpal explain src/auth.js                        # Explain full file
+gitpal explain src/auth.js --function login       # Explain one function
+gitpal explain a3f2c1                             # Explain a commit
+```
+
+---
+
 ## 🔄 Full Daily Workflow
 
 ```
@@ -248,6 +303,9 @@ gitpal pr  →  Full PR description, copy to GitHub
          ↓
 Releasing v2.0?
 gitpal changelog --ver 2.0.0  →  Full changelog ready
+         ↓
+Understanding old code?
+gitpal explain src/auth.js  →  Plain English explanation
 ```
 
 ---
@@ -261,6 +319,7 @@ gitpal changelog --ver 2.0.0  →  Full changelog ready
 | Forget what you built last week | Plain English summary instantly |
 | Write changelog manually | Auto-generated from commits |
 | No code review before commit | AI catches bugs before they reach GitHub |
+| Confused by old code | Explained in plain English instantly |
 | Works with one AI only | Works with 4 AI providers |
 
 ---
@@ -281,7 +340,8 @@ gitpal/
 │       ├── pr.js          ← gitpal pr
 │       ├── changelog.js   ← gitpal changelog
 │       ├── config.js      ← gitpal config
-│       └── review.js      ← gitpal review
+│       ├── review.js      ← gitpal review
+│       └── explain.js     ← gitpal explain
 └── tests/
     └── ai.test.js
 ```
@@ -339,4 +399,4 @@ MIT — free to use, modify and distribute.
 
 <p align="center">
   <strong>If GitPal saves you time, give it a ⭐ on GitHub!</strong>
-</p>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitpal-cli",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "AI-powered Git assistant CLI",
   "main": "src/index.js",
   "bin": {

package/src/ai.js

@@ -2,7 +2,6 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 
-// Config file stored in user's home directory
 const CONFIG_PATH = path.join(os.homedir(), '.gitpal.json');
 
 export function loadConfig() {
@@ -14,23 +13,11 @@ export function saveConfig(config) {
   fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
 }
 
-// ─── AI PROVIDER ROUTER ───────────────────────────────────────────────────────
-// All providers receive the same prompt and return a plain string response.
-// Adding a new provider = add one function + one case below.
-
 async function callAnthropic(prompt, apiKey) {
   const res = await fetch('https://api.anthropic.com/v1/messages', {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'x-api-key': apiKey,
-      'anthropic-version': '2023-06-01',
-    },
-    body: JSON.stringify({
-      model: 'claude-3-haiku-20240307',
-      max_tokens: 500,
-      messages: [{ role: 'user', content: prompt }],
-    }),
+    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
+    body: JSON.stringify({ model: 'claude-3-haiku-20240307', max_tokens: 500, messages: [{ role: 'user', content: prompt }] }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error?.message || 'Anthropic API error');
@@ -40,15 +27,8 @@ async function callAnthropic(prompt, apiKey) {
 async function callOpenAI(prompt, apiKey) {
   const res = await fetch('https://api.openai.com/v1/chat/completions', {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
-      model: 'gpt-3.5-turbo',
-      max_tokens: 500,
-      messages: [{ role: 'user', content: prompt }],
-    }),
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({ model: 'gpt-3.5-turbo', max_tokens: 500, messages: [{ role: 'user', content: prompt }] }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error?.message || 'OpenAI API error');
@@ -60,9 +40,7 @@ async function callGemini(prompt, apiKey) {
   const res = await fetch(url, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      contents: [{ parts: [{ text: prompt }] }],
-    }),
+    body: JSON.stringify({ contents: [{ parts: [{ text: prompt }] }] }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error?.message || 'Gemini API error');
@@ -72,39 +50,38 @@ async function callGemini(prompt, apiKey) {
 async function callGroq(prompt, apiKey) {
   const res = await fetch('https://api.groq.com/openai/v1/chat/completions', {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
-      model: 'llama-3.3-70b-versatile',
-      max_tokens: 500,
-      messages: [{ role: 'user', content: prompt }],
-    }),
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({ model: 'llama-3.3-70b-versatile', max_tokens: 500, messages: [{ role: 'user', content: prompt }] }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error?.message || 'Groq API error');
   return data.choices[0].message.content.trim();
 }
 
-// ─── MAIN EXPORT ─────────────────────────────────────────────────────────────
+async function callOpenRouter(prompt, apiKey, model) {
+  const selectedModel = model || 'google/gemini-2.0-flash-exp:free';
+  const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}`, 'HTTP-Referer': 'https://github.com/h1a2r3s4h/gitpal', 'X-Title': 'GitPal CLI' },
+    body: JSON.stringify({ model: selectedModel, max_tokens: 500, messages: [{ role: 'user', content: prompt }] }),
+  });
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error?.message || 'OpenRouter API error');
+  return data.choices[0].message.content.trim();
+}
 
 export async function askAI(prompt) {
   const config = loadConfig();
-
   const provider = config.provider;
   const apiKey = config.apiKey;
-
-  if (!provider || !apiKey) {
-    throw new Error('No AI provider configured. Run: gitpal config');
-  }
-
+  const model = config.model;
+  if (!provider || !apiKey) throw new Error('No AI provider configured. Run: gitpal config');
   switch (provider) {
-    case 'anthropic': return callAnthropic(prompt, apiKey);
-    case 'openai':    return callOpenAI(prompt, apiKey);
-    case 'gemini':    return callGemini(prompt, apiKey);
-    case 'groq':      return callGroq(prompt, apiKey);
-    default:
-      throw new Error(`Unknown provider "${provider}". Run: gitpal config`);
+    case 'anthropic':  return callAnthropic(prompt, apiKey);
+    case 'openai':     return callOpenAI(prompt, apiKey);
+    case 'gemini':     return callGemini(prompt, apiKey);
+    case 'groq':       return callGroq(prompt, apiKey);
+    case 'openrouter': return callOpenRouter(prompt, apiKey, model);
+    default: throw new Error(`Unknown provider "${provider}". Run: gitpal config`);
   }
 }

package/src/commands/config.js

@@ -19,6 +19,7 @@ const PROVIDERS = {
     label: "Groq — llama3-8b (Free & Ultra Fast)",
     keyHint: "Get free API key at console.groq.com",
   },
+  
 };
 
 export async function configCommand() {

package/src/commands/issue.js

@@ -0,0 +1,291 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import fs from 'fs';
+import path from 'path';
+import simpleGit from 'simple-git';
+import { isGitRepo, getCurrentBranch } from '../git.js';
+import { askAI, loadConfig, saveConfig } from '../ai.js';
+
+const git = simpleGit();
+
+// ─── GITHUB API ───────────────────────────────────────────────────────────────
+
+async function fetchIssue(repo, issueNumber, token) {
+  const url = `https://api.github.com/repos/${repo}/issues/${issueNumber}`;
+  const headers = {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'gitpal-cli',
+  };
+  if (token) headers['Authorization'] = `token ${token}`;
+
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    if (res.status === 404) throw new Error(`Issue #${issueNumber} not found in ${repo}`);
+    if (res.status === 401) throw new Error('Invalid GitHub token. Run: gitpal config --github-token YOUR_TOKEN');
+    throw new Error(`GitHub API error: ${res.status}`);
+  }
+  return res.json();
+}
+
+async function fetchRepoFiles(repo, token) {
+  const url = `https://api.github.com/repos/${repo}/git/trees/HEAD?recursive=1`;
+  const headers = {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'gitpal-cli',
+  };
+  if (token) headers['Authorization'] = `token ${token}`;
+
+  const res = await fetch(url, { headers });
+  if (!res.ok) return [];
+  const data = await res.json();
+  return data.tree?.filter(f => f.type === 'blob').map(f => f.path) || [];
+}
+
+// ─── READ LOCAL FILES ─────────────────────────────────────────────────────────
+
+function readLocalFiles(maxFiles = 10) {
+  const extensions = ['.js', '.ts', '.jsx', '.tsx', '.py', '.java', '.go'];
+  const ignore = ['node_modules', '.git', 'dist', 'build', 'coverage'];
+
+  const files = [];
+
+  function walk(dir) {
+    if (files.length >= maxFiles) return;
+    try {
+      const entries = fs.readdirSync(dir);
+      for (const entry of entries) {
+        if (ignore.includes(entry)) continue;
+        const fullPath = path.join(dir, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+          walk(fullPath);
+        } else if (extensions.includes(path.extname(entry))) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            files.push({ path: fullPath, content: content.slice(0, 1000) });
+            if (files.length >= maxFiles) return;
+          } catch {}
+        }
+      }
+    } catch {}
+  }
+
+  walk(process.cwd());
+  return files;
+}
+
+// ─── MAIN COMMAND ─────────────────────────────────────────────────────────────
+
+export async function issueCommand(issueNumber, options) {
+  if (!(await isGitRepo())) {
+    console.log(chalk.red('❌ Not a git repository. Clone the repo first.'));
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+
+  // Get GitHub token
+  let token = options.githubToken || config.githubToken;
+  if (!token) {
+    console.log(chalk.yellow('⚠️  No GitHub token found. Using public API (rate limited).'));
+    console.log(chalk.dim('Add token: gitpal config --github-token YOUR_TOKEN\n'));
+  }
+
+  // Get repo
+  let repo = options.repo;
+  if (!repo) {
+    try {
+      const remotes = await git.getRemotes(true);
+      const origin = remotes.find(r => r.name === 'origin');
+      if (origin) {
+        const match = origin.refs.fetch.match(/github\.com[:/](.+?)(?:\.git)?$/);
+        if (match) repo = match[1];
+      }
+    } catch {}
+  }
+
+  if (!repo) {
+    console.log(chalk.red('❌ Could not detect repo. Use: gitpal issue 234 --repo owner/repo'));
+    process.exit(1);
+  }
+
+  console.log(chalk.dim(`\nRepo: ${repo} | Issue: #${issueNumber}\n`));
+
+  // ── Step 1: Fetch Issue ──────────────────────────────────────────────────
+
+  const issueSpinner = ora(`Fetching issue #${issueNumber} from GitHub...`).start();
+  let issue;
+  try {
+    issue = await fetchIssue(repo, issueNumber, token);
+    issueSpinner.succeed(`Issue found: "${issue.title}"`);
+  } catch (err) {
+    issueSpinner.fail(chalk.red(`Failed: ${err.message}`));
+    process.exit(1);
+  }
+
+  // ── Step 2: Read local codebase ──────────────────────────────────────────
+
+  const codeSpinner = ora('Reading your local codebase...').start();
+  const localFiles = readLocalFiles(10);
+  codeSpinner.succeed(`Read ${localFiles.length} files from codebase.`);
+
+  // ── Step 3: AI Analysis ──────────────────────────────────────────────────
+
+  const aiSpinner = ora('AI is analyzing the issue and your codebase...').start();
+
+  const codeContext = localFiles
+    .map(f => `File: ${f.path}\n${f.content}`)
+    .join('\n\n---\n\n');
+
+  const prompt = `You are a senior developer helping a junior developer fix a GitHub issue.
+
+GITHUB ISSUE:
+Title: ${issue.title}
+Description: ${issue.body || 'No description'}
+Labels: ${issue.labels?.map(l => l.name).join(', ') || 'None'}
+
+LOCAL CODEBASE (first 10 files):
+${codeContext.slice(0, 5000)}
+
+Based on the issue and codebase, provide:
+
+1. UNDERSTANDING (2-3 lines explaining the bug simply)
+
+2. FILES TO CHANGE (list exact file paths that need changes)
+
+3. HOW TO FIX (step by step, simple language, include code snippets)
+
+4. DIFFICULTY: Easy / Medium / Hard
+
+5. ESTIMATED TIME: X minutes/hours
+
+6. COMMIT MESSAGE (conventional commit format)
+
+7. PR TITLE (clear and professional)
+
+8. PR DESCRIPTION (What changed, Why, How to test)
+
+Be specific and practical. Junior developers should understand this.`;
+
+  let analysis;
+  try {
+    analysis = await askAI(prompt);
+    aiSpinner.succeed('Analysis complete!\n');
+  } catch (err) {
+    aiSpinner.fail(chalk.red(`AI Error: ${err.message}`));
+    process.exit(1);
+  }
+
+  // ── Step 4: Display Analysis ─────────────────────────────────────────────
+
+  console.log(chalk.bold.cyan(`\n🔍 Issue #${issueNumber}: ${issue.title}\n`));
+  console.log(chalk.dim('─'.repeat(60)));
+  console.log(chalk.white(analysis));
+  console.log(chalk.dim('─'.repeat(60)));
+
+  // ── Step 5: Ask what to do ───────────────────────────────────────────────
+
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: '\nWhat would you like to do?',
+    choices: [
+      { name: '🌿 Create a new branch for this fix', value: 'branch' },
+      { name: '📋 Generate full PR description', value: 'pr' },
+      { name: '👀 I will fix it manually', value: 'manual' },
+      { name: '❌ Exit', value: 'exit' },
+    ],
+  }]);
+
+  if (action === 'exit' || action === 'manual') {
+    console.log(chalk.yellow('\nGood luck with the fix! Run gitpal commit when done.'));
+    return;
+  }
+
+  // ── Step 6: Create Branch ────────────────────────────────────────────────
+
+  if (action === 'branch' || action === 'pr') {
+    const branchName = `fix/issue-${issueNumber}-${issue.title
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, '')
+      .replace(/\s+/g, '-')
+      .slice(0, 30)}`;
+
+    const { confirmBranch } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirmBranch',
+      message: `Create branch: ${chalk.cyan(branchName)}?`,
+      default: true,
+    }]);
+
+    if (confirmBranch) {
+      const branchSpinner = ora('Creating branch...').start();
+      try {
+        await git.checkoutLocalBranch(branchName);
+        branchSpinner.succeed(chalk.green(`Branch created: ${branchName}`));
+      } catch (err) {
+        branchSpinner.fail(chalk.red(`Branch error: ${err.message}`));
+      }
+    }
+  }
+
+  // ── Step 7: Generate PR Description ─────────────────────────────────────
+
+  if (action === 'pr') {
+    const prSpinner = ora('Generating PR description...').start();
+
+    const prPrompt = `Write a professional GitHub Pull Request description for fixing issue #${issueNumber}.
+
+Issue Title: ${issue.title}
+Issue Description: ${issue.body?.slice(0, 500) || 'No description'}
+
+Format exactly like this:
+## Fixes
+Closes #${issueNumber}
+
+## What changed
+(bullet points)
+
+## Why
+(brief reason)
+
+## How to test
+(testing steps)
+
+## Type of change
+(Bug fix / Feature / etc)`;
+
+    try {
+      const prDesc = await askAI(prPrompt);
+      prSpinner.succeed('PR description ready!\n');
+      console.log(chalk.bold('\n📝 Pull Request Description:\n'));
+      console.log(chalk.dim('─'.repeat(60)));
+      console.log(chalk.white(prDesc));
+      console.log(chalk.dim('─'.repeat(60)));
+      console.log(chalk.dim('\n💡 Copy the above and paste into your GitHub PR.\n'));
+    } catch (err) {
+      prSpinner.fail(chalk.red(`Error: ${err.message}`));
+    }
+  }
+
+  // ── Step 8: Final instructions ───────────────────────────────────────────
+
+  console.log(chalk.bold.green('\n✅ You are ready to contribute!\n'));
+  console.log(chalk.white('Next steps:'));
+  console.log(chalk.cyan('  1.') + chalk.white(' Fix the issue in your editor'));
+  console.log(chalk.cyan('  2.') + chalk.white(' git add .'));
+  console.log(chalk.cyan('  3.') + chalk.white(' gitpal commit'));
+  console.log(chalk.cyan('  4.') + chalk.white(` git push origin fix/issue-${issueNumber}`));
+  console.log(chalk.cyan('  5.') + chalk.white(' Open PR on GitHub\n'));
+}
+
+// ─── CONFIG GITHUB TOKEN ──────────────────────────────────────────────────────
+
+export function saveGithubToken(token) {
+  const config = loadConfig();
+  config.githubToken = token;
+  saveConfig(config);
+  console.log(chalk.green('\n✅ GitHub token saved!'));
+  console.log(chalk.dim('You can now use: gitpal issue 234 --repo owner/repo\n'));
+}

package/src/index.js

@@ -7,6 +7,7 @@ import { changelogCommand } from './commands/changelog.js';
 import { configCommand } from './commands/config.js';
 import { reviewCommand } from './commands/review.js';
 import { explainCommand } from './commands/explain.js';
+import { issueCommand, saveGithubToken } from './commands/issue.js';
 const program = new Command();
 
 console.log(chalk.cyan.bold('\n🤖 GitPal — Your AI Git Assistant\n'));
@@ -58,6 +59,13 @@ program
   .description('Explain any file or commit in plain English')
   .option('-f, --function <name>', 'Explain a specific function')
   .action(explainCommand);
+
+program
+  .command('issue <number>')
+  .description('Fetch and fix any GitHub issue with AI guidance')
+  .option('-r, --repo <repo>', 'GitHub repo (owner/repo)')
+  .option('-t, --github-token <token>', 'GitHub personal access token')
+  .action(issueCommand);
 program.parse(process.argv);
 
 // Show help if no command given