gitpal-cli 1.0.3 → 1.0.5

package/README.md

@@ -1,11 +1,11 @@
 # 🤖 GitPal — AI-Powered Git Assistant CLI
-<!-- 
+
 > Stop writing commit messages manually. Let AI do it in 3 seconds.
 
 [![npm version](https://img.shields.io/npm/v/gitpal-cli.svg?style=flat-square)](https://www.npmjs.com/package/gitpal-cli)
 [![npm downloads](https://img.shields.io/npm/dm/gitpal-cli.svg?style=flat-square)](https://www.npmjs.com/package/gitpal-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?style=flat-square)](https://nodejs.org) -->
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?style=flat-square)](https://nodejs.org)
 
 ---
 
@@ -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
@@ -193,6 +193,91 @@ gitpal config
 
 ---
 
+### `gitpal review` — AI Code Reviewer
+Reviews your staged code for bugs, security issues and bad practices before you commit — like having a senior developer on your team 24/7.
+
+```bash
+git add .
+gitpal review
+
+# 🐛 Bugs Found:
+# - No error handling on login failure
+#
+# 🔒 Security Issues:
+# - Password stored as plain text, use bcrypt
+#
+# 💡 Improvements:
+# - Add input validation for username and password
+#
+# ❌ Verdict: Do not commit
+
+# ? What would you like to do?
+# ✅ Looks good — generate commit message and commit
+# ❌ I will fix the issues first
+```
+
+**Options:**
+```bash
+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
 
 ```
@@ -201,6 +286,8 @@ Morning — open your project
 Write some code (auth feature)
          ↓
 git add .
+gitpal review  →  AI checks for bugs and security issues
+         ↓
 gitpal commit  →  "feat(auth): add Google OAuth login"
          ↓
 Write more code (fix a bug)
@@ -216,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
 ```
 
 ---
@@ -228,6 +318,8 @@ gitpal changelog --ver 2.0.0  →  Full changelog ready
 | Spend 15 mins on PR description | Generated in 3 seconds |
 | 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 |
 
 ---
@@ -247,7 +339,9 @@ gitpal/
 │       ├── summary.js     ← gitpal summary
 │       ├── pr.js          ← gitpal pr
 │       ├── changelog.js   ← gitpal changelog
-│       └── config.js      ← gitpal config
+│       ├── config.js      ← gitpal config
+│       ├── review.js      ← gitpal review
+│       └── explain.js     ← gitpal explain
 └── tests/
     └── ai.test.js
 ```
@@ -258,7 +352,7 @@ gitpal/
 
 ```bash
 # Clone the repo
-git clone https://github.com/harshit_gangwar16/gitpal
+git clone https://github.com/h1a2r3s4h/gitpal
 cd gitpal
 
 # Install dependencies
@@ -292,7 +386,7 @@ Contributions are welcome! To add a new AI provider:
 
 Built by **Harshit Gangwar**
 
-- GitHub: [@harshit_gangwar16](https://github.com/harshit_gangwar16)
+- GitHub: [@h1a2r3s4h](https://github.com/h1a2r3s4h)
 - npm: [gitpal-cli](https://www.npmjs.com/package/gitpal-cli)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitpal-cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "AI-powered Git assistant CLI",
   "main": "src/index.js",
   "bin": {
@@ -26,5 +26,8 @@
     "ora": "^7.0.1",
     "simple-git": "^3.21.0"
   },
-  "type": "module"
+  "type": "module",
+  "devDependencies": {
+    "jest": "^30.3.0"
+  }
 }

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/explain.js

@@ -0,0 +1,181 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs';
+import path from 'path';
+import { isGitRepo } from '../git.js';
+import { askAI } from '../ai.js';
+import simpleGit from 'simple-git';
+
+const git = simpleGit();
+
+export async function explainCommand(target, options) {
+  // 1. Guard: must be inside a git repo
+  if (!(await isGitRepo())) {
+    console.log(chalk.red('❌ Not a git repository.'));
+    process.exit(1);
+  }
+
+  // 2. Decide what to explain
+  if (!target) {
+    console.log(chalk.red('❌ Please provide something to explain.'));
+    console.log(chalk.dim('\nExamples:'));
+    console.log(chalk.cyan('  gitpal explain a3f2c1              ') + chalk.dim('← explain a commit'));
+    console.log(chalk.cyan('  gitpal explain src/auth.js         ') + chalk.dim('← explain a file'));
+    console.log(chalk.cyan('  gitpal explain src/auth.js --function login') + chalk.dim('← explain a function'));
+    process.exit(1);
+  }
+
+  // 3. Check if target is a file or a commit hash
+  const isFile = fs.existsSync(target);
+  const isCommitHash = /^[0-9a-f]{6,40}$/i.test(target);
+
+  if (isFile) {
+    await explainFile(target, options);
+  } else if (isCommitHash) {
+    await explainCommit(target);
+  } else {
+    console.log(chalk.red(`❌ "${target}" is not a valid file or commit hash.`));
+    process.exit(1);
+  }
+}
+
+// ─── EXPLAIN FILE ─────────────────────────────────────────────────────────────
+
+async function explainFile(filePath, options) {
+  const spinner = ora(`Reading ${filePath}...`).start();
+
+  let code;
+  try {
+    code = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    spinner.fail(chalk.red(`Cannot read file: ${filePath}`));
+    process.exit(1);
+  }
+
+  if (!code.trim()) {
+    spinner.fail(chalk.yellow('File is empty.'));
+    process.exit(1);
+  }
+
+  spinner.succeed(`Read ${path.basename(filePath)} successfully.`);
+
+  const aiSpinner = ora('AI is analyzing the code...').start();
+
+  let prompt;
+
+  if (options.function) {
+    // Explain a specific function
+    prompt = `You are a senior developer explaining code to a junior developer.
+
+Analyze this code and explain ONLY the function named "${options.function}".
+
+Explain:
+1. What this function does in simple words
+2. What inputs it takes
+3. What it returns
+4. Step by step what happens inside it
+5. Any important things to know
+
+Use simple language. No jargon. Maximum 10 lines.
+End with: "Depends on: X, Y, Z" (list any libraries or functions it uses)
+
+File: ${filePath}
+Code:
+${code.slice(0, 4000)}`;
+  } else {
+    // Explain the entire file
+    prompt = `You are a senior developer explaining code to a junior developer.
+
+Analyze this entire file and explain it clearly.
+
+Tell me:
+1. What is the PURPOSE of this file in one sentence
+2. What are the MAIN functions/classes (list each with one line description)
+3. How does it FIT into a typical project
+4. Any IMPORTANT patterns or techniques used
+
+Use simple language. Be concise. Maximum 15 lines.
+End with: "Depends on: X, Y, Z" (list key imports/dependencies)
+
+File: ${filePath}
+Code:
+${code.slice(0, 4000)}`;
+  }
+
+  try {
+    const explanation = await askAI(prompt);
+    aiSpinner.succeed('Explanation ready!\n');
+
+    const title = options.function
+      ? `📖 Explaining function: ${chalk.cyan(options.function)}() in ${chalk.dim(filePath)}`
+      : `📖 Explaining file: ${chalk.cyan(path.basename(filePath))}`;
+
+    console.log(chalk.bold(title));
+    console.log(chalk.dim('─'.repeat(50)));
+    console.log(chalk.white(explanation));
+    console.log('');
+
+  } catch (err) {
+    aiSpinner.fail(chalk.red(`AI Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// ─── EXPLAIN COMMIT ───────────────────────────────────────────────────────────
+
+async function explainCommit(hash) {
+  const spinner = ora(`Fetching commit ${hash}...`).start();
+
+  let diff, log;
+  try {
+    diff = await git.show([hash, '--stat', '--patch']);
+    log = await git.log({ from: `${hash}^`, to: hash, maxCount: 1 });
+  } catch {
+    spinner.fail(chalk.red(`Commit "${hash}" not found.`));
+    process.exit(1);
+  }
+
+  spinner.succeed('Commit found.');
+
+  const aiSpinner = ora('AI is analyzing the commit...').start();
+
+  const commitMessage = log.all[0]?.message || 'No message';
+  const commitDate = log.all[0]?.date || '';
+  const commitAuthor = log.all[0]?.author_name || '';
+
+  const prompt = `You are a senior developer explaining a git commit to a junior developer.
+
+Explain this commit in plain English.
+
+Tell me:
+1. WHAT changed — what was added, removed or modified
+2. WHY it was likely changed — what problem it solves
+3. FILES affected — list each file and what changed in it
+4. IMPACT — how does this affect the overall project
+
+Use simple language. Be specific. Maximum 15 lines.
+
+Commit: ${hash}
+Message: ${commitMessage}
+Author: ${commitAuthor}
+Date: ${commitDate}
+
+Diff:
+${diff.slice(0, 4000)}`;
+
+  try {
+    const explanation = await askAI(prompt);
+    aiSpinner.succeed('Explanation ready!\n');
+
+    console.log(chalk.bold(`📖 Explaining commit: ${chalk.cyan(hash)}`));
+    console.log(chalk.dim(`Message: ${commitMessage}`));
+    console.log(chalk.dim(`Author: ${commitAuthor}  |  Date: ${commitDate}`));
+    console.log(chalk.dim('─'.repeat(50)));
+    console.log(chalk.white(explanation));
+    console.log('');
+
+  } catch (err) {
+    aiSpinner.fail(chalk.red(`AI Error: ${err.message}`));
+    process.exit(1);
+  }
+}

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

@@ -6,7 +6,8 @@ import { prCommand } from './commands/pr.js';
 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'));
@@ -53,7 +54,18 @@ program
   .option('-r, --review-only', 'Only review, do not commit')
   .action(reviewCommand);
   
+program
+  .command('explain <target>')
+  .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

package/tests/ai.test.js

@@ -0,0 +1,207 @@
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const CONFIG_PATH = path.join(os.homedir(), '.gitpal.json');
+
+function cleanConfig() {
+  if (fs.existsSync(CONFIG_PATH)) {
+    fs.unlinkSync(CONFIG_PATH);
+  }
+}
+
+// ─── CONFIG TESTS ─────────────────────────────────────────────────────────────
+
+describe('Config Management', () => {
+
+  beforeEach(() => cleanConfig());
+  afterEach(() => cleanConfig());
+
+  test('loadConfig returns empty object when no config exists', async () => {
+    const { loadConfig } = await import('../src/ai.js');
+    const config = loadConfig();
+    expect(config).toEqual({});
+  });
+
+  test('saveConfig saves provider and apiKey correctly', async () => {
+    const { saveConfig, loadConfig } = await import('../src/ai.js');
+    saveConfig({ provider: 'groq', apiKey: 'test-key-123' });
+    const config = loadConfig();
+    expect(config.provider).toBe('groq');
+    expect(config.apiKey).toBe('test-key-123');
+  });
+
+  test('saveConfig overwrites existing config', async () => {
+    const { saveConfig, loadConfig } = await import('../src/ai.js');
+    saveConfig({ provider: 'openai', apiKey: 'old-key' });
+    saveConfig({ provider: 'anthropic', apiKey: 'new-key' });
+    const config = loadConfig();
+    expect(config.provider).toBe('anthropic');
+    expect(config.apiKey).toBe('new-key');
+  });
+
+  test('saveConfig supports all 4 providers', async () => {
+    const { saveConfig, loadConfig } = await import('../src/ai.js');
+    const providers = ['groq', 'openai', 'gemini', 'anthropic'];
+    for (const provider of providers) {
+      saveConfig({ provider, apiKey: `key-for-${provider}` });
+      const config = loadConfig();
+      expect(config.provider).toBe(provider);
+    }
+  });
+
+  test('config file is created at correct path', async () => {
+    const { saveConfig } = await import('../src/ai.js');
+    saveConfig({ provider: 'groq', apiKey: 'test-key' });
+    expect(fs.existsSync(CONFIG_PATH)).toBe(true);
+  });
+
+  test('config file contains valid JSON', async () => {
+    const { saveConfig } = await import('../src/ai.js');
+    saveConfig({ provider: 'groq', apiKey: 'test-key' });
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf-8');
+    expect(() => JSON.parse(raw)).not.toThrow();
+  });
+
+});
+
+// ─── AI PROVIDER TESTS ────────────────────────────────────────────────────────
+
+describe('AI Provider Validation', () => {
+
+  beforeEach(() => cleanConfig());
+  afterEach(() => cleanConfig());
+
+  test('askAI throws error when no config exists', async () => {
+    const { askAI } = await import('../src/ai.js');
+    await expect(askAI('test prompt')).rejects.toThrow('No AI provider configured');
+  });
+
+  test('askAI throws error for unknown provider', async () => {
+    const { saveConfig, askAI } = await import('../src/ai.js');
+    saveConfig({ provider: 'unknownprovider', apiKey: 'test-key' });
+    await expect(askAI('test prompt')).rejects.toThrow();
+  });
+
+  test('askAI throws error when apiKey is missing', async () => {
+    const { saveConfig, askAI } = await import('../src/ai.js');
+    saveConfig({ provider: 'groq', apiKey: '' });
+    await expect(askAI('test prompt')).rejects.toThrow();
+  });
+
+});
+
+// ─── GIT UTILITY TESTS ────────────────────────────────────────────────────────
+
+describe('Git Utilities', () => {
+
+test('isGitRepo returns a boolean', async () => {
+  const { isGitRepo } = await import('../src/git.js');
+  const result = await isGitRepo();
+  expect(typeof result).toBe('boolean');
+});
+
+  test('isGitRepo returns true inside a git repo', async () => {
+    const { isGitRepo } = await import('../src/git.js');
+    const result = await isGitRepo();
+    expect(result).toBe(true);
+  });
+
+  test('getRecentCommits returns an array', async () => {
+    const { getRecentCommits } = await import('../src/git.js');
+    const commits = await getRecentCommits(3);
+    expect(Array.isArray(commits)).toBe(true);
+  });
+
+  test('getRecentCommits respects the limit', async () => {
+    const { getRecentCommits } = await import('../src/git.js');
+    const commits = await getRecentCommits(2);
+    expect(commits.length).toBeLessThanOrEqual(2);
+  });
+
+  test('getCurrentBranch returns a string', async () => {
+    const { getCurrentBranch } = await import('../src/git.js');
+    const branch = await getCurrentBranch();
+    expect(typeof branch).toBe('string');
+    expect(branch.length).toBeGreaterThan(0);
+  });
+
+  test('getStagedDiff returns a string', async () => {
+    const { getStagedDiff } = await import('../src/git.js');
+    const diff = await getStagedDiff();
+    expect(typeof diff).toBe('string');
+  });
+
+});
+
+// ─── PACKAGE.JSON VALIDATION ──────────────────────────────────────────────────
+
+describe('Package Configuration', () => {
+
+  test('package.json has correct name', () => {
+    const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf-8'));
+    expect(pkg.name).toBe('gitpal-cli');
+  });
+
+  test('package.json has bin field', () => {
+    const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf-8'));
+    expect(pkg.bin).toBeDefined();
+  });
+
+  test('package.json has version', () => {
+    const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf-8'));
+    expect(pkg.version).toBeDefined();
+    expect(pkg.version).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  test('package.json has required dependencies', () => {
+    const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf-8'));
+    const required = ['commander', 'simple-git', 'chalk', 'ora', 'inquirer'];
+    required.forEach(dep => {
+      expect(pkg.dependencies).toHaveProperty(dep);
+    });
+  });
+
+  test('bin/gitpal.js file exists and is not empty', () => {
+    const binPath = './bin/gitpal.js';
+    expect(fs.existsSync(binPath)).toBe(true);
+    const content = fs.readFileSync(binPath, 'utf-8');
+    expect(content.trim().length).toBeGreaterThan(0);
+  });
+
+});
+
+// ─── COMMAND FILES EXIST ──────────────────────────────────────────────────────
+
+describe('Command Files', () => {
+
+  const commands = ['commit', 'summary', 'pr', 'changelog', 'config', 'review'];
+
+  commands.forEach(cmd => {
+    test(`src/commands/${cmd}.js exists`, () => {
+      expect(fs.existsSync(`./src/commands/${cmd}.js`)).toBe(true);
+    });
+
+    test(`src/commands/${cmd}.js is not empty`, () => {
+      const content = fs.readFileSync(`./src/commands/${cmd}.js`, 'utf-8');
+      expect(content.trim().length).toBeGreaterThan(0);
+    });
+  });
+
+  test('src/ai.js exists and is not empty', () => {
+    const content = fs.readFileSync('./src/ai.js', 'utf-8');
+    expect(content.trim().length).toBeGreaterThan(0);
+  });
+
+  test('src/git.js exists and is not empty', () => {
+    const content = fs.readFileSync('./src/git.js', 'utf-8');
+    expect(content.trim().length).toBeGreaterThan(0);
+  });
+
+  test('src/index.js exists and is not empty', () => {
+    const content = fs.readFileSync('./src/index.js', 'utf-8');
+    expect(content.trim().length).toBeGreaterThan(0);
+  });
+
+});