xoegit 1.1.3 → 1.1.5

package/README.md

@@ -15,14 +15,18 @@
 ## Features
 
 - **Atomic Commits** — Automatically suggests splitting large changes into multiple logical commits
+- **Execute Mode** — Optionally execute commits with confirmation using `--execute`
 - **Context Aware** — Provide context with `--context` for more accurate commit messages
+- **Explain Mode** — Learn commit crafting with `--explain` to see reasoning behind each grouping
 - **Smart Fallback** — Automatically switches between Gemini models when rate limits are hit
 - **Semantic Commits** — Strictly follows [Conventional Commits](https://www.conventionalcommits.org/)
 - **PR Ready** — Generates ready-to-use PR title and description
 
 ## How It Works
 
-> **Important:** `xoegit` **never** stages your files, commits your changes, or modifies your repository in any way. It only analyzes your changes and provides recommendations that you can review and execute yourself.
+> **Important:** By default, `xoegit` **never** stages your files, commits your changes, or modifies your repository in any way. It only analyzes your changes and provides recommendations that you can review and execute yourself.
+>
+> With the `--execute` flag, you can optionally let `xoegit` execute the suggested commits after your explicit confirmation.
 
 You remain in full control of your git workflow.
 
@@ -34,13 +38,19 @@ You remain in full control of your git workflow.
 - **Git**: Must be installed and available in your PATH
 - **API Key**: A Google Gemini API key ([get one here](https://aistudio.google.com/))
 
-### Install
+### Quick Start
+
+```bash
+npx xoegit
+```
+
+### Global Installation (Optional)
 
 ```bash
 npm install -g xoegit
 ```
 
-**or** install from source:
+### Install from Source 
 
 ```bash
 git clone git@github.com:ujangdoubleday/xoegit.git
@@ -56,7 +66,13 @@ Simply run `xoegit` for the first time. It will prompt you for your API Key secu
 
 ## Usage
 
-Then, from whatever project you're working on, just run:
+From any git repository, just run:
+
+```bash
+npx xoegit
+```
+
+**or** if installed globally:
 
 ```bash
 xoegit
@@ -66,42 +82,57 @@ xoegit
 
 ### Options
 
-| Option                 | Description                                   |
-| ---------------------- | --------------------------------------------- |
-| `-k, --api-key <key>`  | Use specific API key for this session         |
-| `-c, --context <text>` | Provide context for more accurate suggestions |
-| `-s, --set-key <key>`  | Save API key to config
-| `-d, --delete-key`     | Delete saved API key from config              |
-| `-V, --version`        | Show version                                  |
-| `-h, --help`           | Show help                                     |
+| Option                 | Description                                         |
+| ---------------------- | --------------------------------------------------- |
+| `-k, --api-key <key>`  | Use specific API key for this session               |
+| `-c, --context <text>` | Provide context for more accurate suggestions       |
+| `-e, --execute`        | Execute commits after confirmation prompt           |
+| `--explain`            | Show reasoning behind each commit grouping          |
+| `-s, --set-key <key>`  | Save API key to config                              |
+| `-d, --delete-key`     | Delete saved API key from config                    |
+| `-V, --version`        | Show version                                        |
+| `-h, --help`           | Show help                                           |
 
 ### Examples
 
 **Basic usage:**
 
 ```bash
-xoegit
+npx xoegit
 ```
 
 **With context for better commit type detection:**
 
 ```bash
-xoegit --context "refactoring folder structure"
-xoegit -c "fixing authentication bug"
-xoegit -c "adding new payment feature"
+npx xoegit --context "refactoring folder structure"
+npx xoegit -c "fixing authentication bug"
+npx xoegit -c "adding new payment feature"
 ```
 
-**Use API key for this session only (not saved):**
-
 ```bash
-xoegit --api-key "YOUR_GEMINI_API_KEY"
+npx xoegit --api-key "YOUR_GEMINI_API_KEY"
 ```
 
 **Manage API key:**
 
 ```bash
-xoegit --set-key "YOUR_GEMINI_API_KEY"
-xoegit --delete-key
+npx xoegit --set-key "YOUR_GEMINI_API_KEY"
+npx xoegit --delete-key
+```
+
+**Execute mode (auto-commit with confirmation):**
+
+```bash
+npx xoegit --execute
+npx xoegit -e
+npx xoegit -e -c "fixing critical bug"
+```
+
+**Explain mode (verbose reasoning):**
+
+```bash
+npx xoegit --explain
+npx xoegit --explain -c "refactoring auth module"
 ```
 
 ### Sample Output
@@ -125,6 +156,37 @@ pr description: feat(auth): implement secure login
 - refactor(utils): improve error logging
 ```
 
+### Explain Mode Output
+
+```
+commit 1
+git add src/auth/login.ts src/auth/validator.ts
+git commit -m "feat(auth): add login validation"
+why: I grouped these files because they both handle authentication logic and the validator is directly used by login.ts.
+
+commit 2
+git add package.json package-lock.json
+git commit -m "chore: update dependencies"
+why: I separated dependency updates from code changes to keep the commit atomic and make it easy to revert if needed.
+```
+
+### Execute Mode Output
+
+```
+ℹ Execute mode enabled. 2 commit(s) will be created.
+Do you want to execute these commands? (y/n): y
+✔ [1/2] a1b2c3d feat(auth): add login validation
+└─ src/
+   └─ auth/
+      └─ login.ts
+✔ [2/2] e4f5g6h refactor(utils): improve error logging
+└─ src/
+   └─ utils/
+      └─ logger.ts
+
+✓ All 2 commit(s) executed successfully!
+```
+
 ## Troubleshooting
 
 ### "Current directory is not a git repository"

package/dist/cli/analyze.js

@@ -1,8 +1,8 @@
 import ora from 'ora';
 import { program } from './program.js';
 import { ConfigService } from '../config/index.js';
-import { isValidApiKey, promptApiKey, showBanner, showSuggestion, showSuccess, showError, showWarning, showInfo, showTip, spinnerText, } from '../utils/index.js';
-import { getGitDiff, getGitLog, getGitStatus, isGitRepository } from '../git/index.js';
+import { isValidApiKey, promptApiKey, promptConfirm, showBanner, showSuggestion, showSuccess, showError, showWarning, showInfo, showTip, spinnerText, } from '../utils/index.js';
+import { getGitDiff, getGitLog, getGitStatus, isGitRepository, executeGitAdd, executeGitCommit, } from '../git/index.js';
 import { generateSystemPrompt } from '../prompts/index.js';
 import { generateCommitSuggestion } from '../providers/index.js';
 /**
@@ -80,7 +80,7 @@ export async function analyzeAction() {
             return;
         }
         // 3. Generate Prompt
-        const systemPrompt = await generateSystemPrompt();
+        const systemPrompt = await generateSystemPrompt({ explain: options.explain });
         // Get user context if provided
         const userContext = options.context || '';
         if (userContext) {
@@ -95,7 +95,13 @@ export async function analyzeAction() {
             spinner.stop();
             showSuccess('Suggestion generated!');
             showSuggestion(suggestion);
-            showTip('Copy and execute the commands above. xoegit never runs commands automatically.');
+            // Handle -e (execute) flag
+            if (options.execute) {
+                await handleExecuteMode(suggestion);
+            }
+            else {
+                showTip('Copy and execute the commands above. xoegit never runs commands automatically.');
+            }
         }
         catch (error) {
             spinner.stop();
@@ -107,3 +113,135 @@ export async function analyzeAction() {
         process.exit(1);
     }
 }
+/**
+ * Parse all commit operations from suggestion
+ * Each "commit N" section contains git add and git commit commands
+ */
+function parseCommitOperations(suggestion) {
+    const operations = [];
+    const lines = suggestion.split('\n');
+    let currentFiles = [];
+    let currentMessage = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Check for commit section header (e.g., "commit 1", "commit 2")
+        if (trimmed.match(/^commit\s+\d+$/i)) {
+            // Save previous operation if complete
+            if (currentFiles.length > 0 && currentMessage) {
+                operations.push({ files: [...currentFiles], message: currentMessage });
+            }
+            // Reset for new commit
+            currentFiles = [];
+            currentMessage = null;
+            continue;
+        }
+        // Parse git add command
+        if (trimmed.startsWith('git add ')) {
+            const filesStr = trimmed.slice(8).trim();
+            const matches = filesStr.match(/(?:[^\s"]+|"[^"]*")+/g);
+            if (matches) {
+                currentFiles.push(...matches.map((f) => f.replace(/^"|"$/g, '')));
+            }
+            continue;
+        }
+        // Parse git commit command
+        if (trimmed.startsWith('git commit -m ')) {
+            const match = trimmed.match(/git commit -m ["'](.+)["']/);
+            if (match) {
+                currentMessage = match[1];
+            }
+            continue;
+        }
+    }
+    // Don't forget the last operation
+    if (currentFiles.length > 0 && currentMessage) {
+        operations.push({ files: [...currentFiles], message: currentMessage });
+    }
+    return operations;
+}
+/**
+ * Handle execute mode - prompt user and execute git commands for all commits
+ */
+async function handleExecuteMode(suggestion) {
+    const operations = parseCommitOperations(suggestion);
+    if (operations.length === 0) {
+        showWarning('Could not parse git commands from suggestion.');
+        showTip('Copy and execute the commands manually.');
+        return;
+    }
+    console.log('');
+    showInfo(`Execute mode enabled. ${operations.length} commit(s) will be created.`);
+    const confirmed = await promptConfirm('Do you want to execute these commands?');
+    if (!confirmed) {
+        showInfo('Execution cancelled.');
+        return;
+    }
+    try {
+        for (let i = 0; i < operations.length; i++) {
+            const op = operations[i];
+            const commitNum = i + 1;
+            // Add files silently
+            await executeGitAdd(op.files);
+            // Create commit with spinner
+            const commitSpinner = ora({
+                text: `[${commitNum}/${operations.length}] Creating commit...`,
+                spinner: 'dots12',
+            }).start();
+            const commitHash = await executeGitCommit(op.message);
+            const shortHash = commitHash.slice(0, 7);
+            commitSpinner.succeed(`[${commitNum}/${operations.length}] ${shortHash} ${op.message}`);
+            // Display file tree
+            printFileTree(op.files);
+        }
+        console.log('');
+        showSuccess(`All ${operations.length} commit(s) executed successfully!`);
+    }
+    catch (error) {
+        showError('Execution Failed', error.message);
+    }
+}
+/**
+ * Print files in a tree format similar to husky
+ */
+function printFileTree(files) {
+    // Sort files for consistent display
+    const sortedFiles = [...files].sort();
+    // Build tree structure
+    const tree = {};
+    for (const file of sortedFiles) {
+        const parts = file.split('/');
+        let current = tree;
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            const isLast = i === parts.length - 1;
+            if (isLast) {
+                current[part] = null; // File (leaf node)
+            }
+            else {
+                if (!current[part]) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+    }
+    // Print tree
+    const lines = [];
+    printTreeNode(tree, '', lines);
+    for (const line of lines) {
+        console.log(line);
+    }
+}
+function printTreeNode(node, prefix, lines) {
+    const entries = Object.entries(node);
+    entries.forEach(([name, children], index) => {
+        const isLast = index === entries.length - 1;
+        const connector = isLast ? '└─' : '├─';
+        const isDir = children !== null;
+        lines.push(`${prefix}${connector} ${name}${isDir ? '/' : ''}`);
+        if (isDir) {
+            const newPrefix = prefix + (isLast ? '   ' : '│  ');
+            printTreeNode(children, newPrefix, lines);
+        }
+    });
+}

package/dist/cli/program.js

@@ -8,4 +8,6 @@ program
     .option('-k, --api-key <key>', 'Gemini API Key')
     .option('-c, --context <context>', 'Context for the changes (e.g., "refactoring folder structure")')
     .option('-s, --set-key <key>', 'Save Gemini API Key to config (overwrites existing)')
-    .option('-d, --delete-key', 'Delete saved API Key from config');
+    .option('-d, --delete-key', 'Delete saved API Key from config')
+    .option('-e, --execute', 'Execute commit after confirmation prompt')
+    .option('--explain', 'Show explanation for each commit grouping (verbose mode)');

package/dist/git/service.js

@@ -38,3 +38,16 @@ export async function getGitLog(maxCount = 5) {
         return 'No commits yet.';
     }
 }
+/**
+ * Execute git add with specified files
+ */
+export async function executeGitAdd(files) {
+    await git.add(files);
+}
+/**
+ * Execute git commit with specified message
+ */
+export async function executeGitCommit(message) {
+    const result = await git.commit(message);
+    return result.commit;
+}

package/dist/prompts/service.js

@@ -4,7 +4,7 @@ import url from 'url';
 /**
  * Generates the system prompt for the AI
  */
-export async function generateSystemPrompt() {
+export async function generateSystemPrompt(options = {}) {
     let rulesContent = '';
     try {
         const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
@@ -15,6 +15,33 @@ export async function generateSystemPrompt() {
         console.warn('Could not read RULES.md, using default rules.');
         rulesContent = 'Follow conventional commits.';
     }
+    // Build explain mode instructions
+    const explainInstructions = options.explain
+        ? `
+EXPLAIN MODE ENABLED:
+For each commit, you MUST add a "why:" line directly after the git commit command (no blank line in between).
+This line should explain the logical reasoning behind grouping these specific files together.
+
+Format:
+commit N
+git add <files>
+git commit -m "<message>"
+why: <one sentence explaining why these files are grouped together>
+
+Example:
+commit 1
+git add src/auth/login.ts src/auth/utils.ts
+git commit -m "feat(auth): add login validation"
+why: I grouped these files because they both handle authentication logic and the validation directly depends on the auth utilities.
+
+commit 2
+git add package.json package-lock.json
+git commit -m "chore: update dependencies"
+why: I separated dependency updates from code changes to keep the commit atomic and make it easy to revert if needed.
+
+The explanation should help developers understand your commit crafting logic for educational purposes.
+`
+        : '';
     return `
 You are a Git Commit Assistant for the 'xoegit' CLI.
 Your goal is to suggest git commands and commit messages based on the provided changes.
@@ -28,7 +55,7 @@ Your goal is to suggest git commands and commit messages based on the provided c
 RULES FROM USER:
 ${rulesContent}
 ---
-
+${explainInstructions}
 IMPORTANT:
 - You definitely MUST NOT execute commands. You only suggest them.
 - Output MUST be strictly valid shell commands or clear instructions as per the examples in RULES.md.

package/dist/utils/input.js

@@ -65,3 +65,49 @@ export async function promptApiKey() {
         }
     });
 }
+/**
+ * Prompts user for yes/no confirmation
+ */
+export async function promptConfirm(message) {
+    return new Promise((resolve) => {
+        process.stdout.write(`${message} (y/n): `);
+        if (process.stdin.setRawMode && process.stdout.isTTY) {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            const onData = (char) => {
+                const charStr = char.toString('utf-8').toLowerCase();
+                // Ctrl+C
+                if (charStr === '\u0003') {
+                    process.stdout.write('\n');
+                    process.stdin.setRawMode(false);
+                    process.stdin.removeListener('data', onData);
+                    process.stdin.pause();
+                    resolve(false);
+                    return;
+                }
+                if (charStr === 'y' || charStr === 'n') {
+                    process.stdout.write(charStr + '\n');
+                    process.stdin.setRawMode(false);
+                    process.stdin.removeListener('data', onData);
+                    process.stdin.pause();
+                    resolve(charStr === 'y');
+                    return;
+                }
+            };
+            process.stdin.on('data', onData);
+        }
+        else {
+            // Fallback for non-TTY environments
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+                terminal: false,
+            });
+            rl.question('', (answer) => {
+                rl.close();
+                const normalized = answer.trim().toLowerCase();
+                resolve(normalized === 'y' || normalized === 'yes');
+            });
+        }
+    });
+}

package/dist/utils/ui.js

@@ -53,6 +53,10 @@ function formatSuggestionLine(line) {
     if (line.startsWith('pr title:') || line.startsWith('pr description:')) {
         return chalk.yellow(line);
     }
+    // Format explanation lines from --explain mode
+    if (line.startsWith('why:')) {
+        return brand.muted('   ') + chalk.italic.hex('#A78BFA')(line);
+    }
     return line;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xoegit",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "AI-powered CLI tool for generating semantic git commit messages and PR descriptions",
   "license": "MIT",
   "author": "ujangdoubleday",