xoegit 1.0.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 ilham alfath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# xoegit
+
+![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)
+![Gemini](https://img.shields.io/badge/Gemini-AI-8E75B2?logo=google&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+**xoegit** is an AI-powered CLI tool that generates concise, semantic, and atomic git commit messages and PR descriptions. It analyzes your `git diff`, `git status`, and `git log` to provide context-aware suggestions powered by Google's Gemini models.
+
+> **Philosophy:** "Craft, Don't Code" — `xoegit` suggests commands; YOU execute them. You stay in control.
+
+## Features
+
+- **Atomic Commits** — Automatically suggests splitting large changes into multiple logical commits
+- **Context Aware** — Provide context with `--context` for more accurate commit messages
+- **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
+
+## Installation
+
+### Prerequisites
+
+- **Node.js**: Version 18 or higher
+- **Git**: Must be installed and available in your PATH
+- **API Key**: A Google Gemini API key ([get one here](https://aistudio.google.com/))
+
+### Quick Install
+
+```bash
+git clone git@github.com:ujangdoubleday/xoegit.git
+cd xoegit
+make
+```
+
+> **Note:** If you encounter permission errors, run `sudo make global`
+
+## Configuration
+
+### First Run
+
+Simply run `xoegit` for the first time. It will prompt you for your API Key securely and save it.
+
+### Manual Configuration
+
+**Option 1: Environment Variable**
+
+```bash
+export XOEGIT_GEMINI_API_KEY="your-key-here"
+```
+
+**Option 2: Config File**
+
+- Linux: `~/.config/xoegit/config.json`
+- macOS: `~/Library/Application Support/xoegit/config.json`
+- Windows: `%APPDATA%\xoegit\config.json`
+
+```json
+{
+  "XOEGIT_GEMINI_API_KEY": "your-key-here"
+}
+```
+
+## Usage
+
+```bash
+xoegit
+```
+
+### Options
+
+| Option                 | Description                                   |
+| ---------------------- | --------------------------------------------- |
+| `-k, --api-key <key>`  | Use specific API key for this session         |
+| `-c, --context <text>` | Provide context for more accurate suggestions |
+| `-V, --version`        | Show version                                  |
+| `-h, --help`           | Show help                                     |
+
+### Examples
+
+```bash
+# Basic usage
+xoegit
+
+# With context for better commit type detection
+xoegit --context "refactoring folder structure"
+xoegit -c "fixing authentication bug"
+xoegit -c "adding new payment feature"
+```
+
+### Sample Output
+
+```
+xoegit — AI-powered commit generator
+
+Suggestion generated!
+
+commit 1
+git add src/auth/login.ts
+git commit -m "feat(auth): add login validation"
+
+commit 2
+git add src/utils/logger.ts
+git commit -m "refactor(utils): improve error logging"
+
+pr title: feat(auth): implement secure login
+pr description: feat(auth): implement secure login
+- feat(auth): add login validation
+- refactor(utils): improve error logging
+```
+
+## Smart Model Fallback
+
+xoegit uses multiple Gemini models with automatic fallback:
+
+| Model                   | Priority      |
+| ----------------------- | ------------- |
+| `gemini-2.5-flash-lite` | 1st (default) |
+| `gemini-2.5-flash`      | 2nd           |
+| `gemini-3-flash`        | 3rd           |
+
+When one model hits its rate limit, xoegit automatically tries the next one.
+
+## Troubleshooting
+
+### "Current directory is not a git repository"
+
+- Ensure you're inside a valid git repo (`git init`)
+
+### "No changes detected"
+
+- Make sure you have modified, staged, or untracked files
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode for tests
+npm run test:watch
+```
+
+## Project Structure
+
+```
+src/
+├── cli/           # CLI program and actions
+├── config/        # Configuration management
+├── git/           # Git operations
+├── prompts/       # AI prompt templates
+├── providers/     # Gemini AI integration
+├── types/         # TypeScript types
+└── utils/         # Utilities (input, UI)
+```
+
+## License
+
+[MIT](LICENSE.md)

package/dist/cli/analyze.js

@@ -0,0 +1,97 @@
+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 { generateSystemPrompt } from '../prompts/index.js';
+import { generateCommitSuggestion } from '../providers/index.js';
+/**
+ * Main analyze action - orchestrates the commit suggestion flow
+ */
+export async function analyzeAction() {
+    // Show beautiful banner
+    showBanner();
+    try {
+        // 0. Check API Key Config
+        const options = program.opts();
+        let apiKey = options.apiKey;
+        const configService = new ConfigService();
+        if (!apiKey) {
+            apiKey = await configService.getApiKey();
+        }
+        if (!apiKey) {
+            showWarning('Gemini API Key not found.');
+            showInfo('Get one at https://aistudio.google.com/');
+            try {
+                apiKey = await promptApiKey();
+            }
+            catch (err) {
+                showError('Input Error', 'Failed to read input.');
+                process.exit(1);
+            }
+            if (!apiKey || !isValidApiKey(apiKey)) {
+                showError('Configuration Error', 'API Key is required to use xoegit.');
+                process.exit(1);
+            }
+            await configService.saveApiKey(apiKey);
+            showSuccess('API Key saved successfully!');
+        }
+        // 1. Check if git repo
+        const isRepo = await isGitRepository();
+        if (!isRepo) {
+            showError('Git Error', 'Current directory is not a git repository.');
+            process.exit(1);
+        }
+        // 2. Fetch Git Info
+        const spinner = ora({
+            text: spinnerText.analyzing,
+            spinner: 'dots12'
+        }).start();
+        const [diff, status, log] = await Promise.all([
+            getGitDiff(),
+            getGitStatus(),
+            getGitLog()
+        ]);
+        // Check if there are any changes
+        const hasDiff = diff && diff.trim() !== 'Unstaged Changes:\n\n\nStaged Changes:';
+        let hasUntracked = false;
+        try {
+            const statusObj = JSON.parse(status);
+            hasUntracked = statusObj.not_added && statusObj.not_added.length > 0;
+        }
+        catch (e) {
+            // failed to parse
+        }
+        if (!hasDiff && !hasUntracked) {
+            spinner.stop();
+            showWarning('No changes detected (staged, unstaged, or untracked).');
+            return;
+        }
+        // 3. Generate Prompt
+        const systemPrompt = await generateSystemPrompt();
+        // Get user context if provided
+        const userContext = options.context || '';
+        if (userContext) {
+            spinner.text = spinnerText.generatingWithContext(userContext);
+        }
+        else {
+            spinner.text = spinnerText.generating;
+        }
+        // 4. Call AI (automatic model fallback on rate limit)
+        try {
+            const suggestion = await generateCommitSuggestion(apiKey, systemPrompt, diff, status, log, userContext);
+            spinner.stop();
+            showSuccess('Suggestion generated!');
+            showSuggestion(suggestion);
+            showTip('Copy and execute the commands above. xoegit never runs commands automatically.');
+        }
+        catch (error) {
+            spinner.stop();
+            showError('Generation Failed', error.message);
+        }
+    }
+    catch (error) {
+        showError('Unexpected Error', error.message);
+        process.exit(1);
+    }
+}

package/dist/cli/index.js

@@ -0,0 +1,2 @@
+export { program } from './program.js';
+export { analyzeAction } from './analyze.js';

package/dist/cli/program.js

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+export const program = new Command();
+program
+    .name('xoegit')
+    .description('AI-powered git commit generator')
+    .version('0.1.0')
+    .option('-k, --api-key <key>', 'Gemini API Key')
+    .option('-c, --context <context>', 'Context for the changes (e.g., "refactoring folder structure")');

package/dist/config/constants.js

@@ -0,0 +1,16 @@
+import path from 'path';
+import os from 'os';
+/**
+ * Gets the platform-specific config file path
+ */
+export function getConfigPath() {
+    const homeDir = os.homedir();
+    switch (process.platform) {
+        case 'win32':
+            return path.join(process.env.APPDATA || path.join(homeDir, 'AppData', 'Roaming'), 'xoegit', 'config.json');
+        case 'darwin':
+            return path.join(homeDir, 'Library', 'Application Support', 'xoegit', 'config.json');
+        default: // Linux and others
+            return path.join(homeDir, '.config', 'xoegit', 'config.json');
+    }
+}

package/dist/config/index.js

@@ -0,0 +1,2 @@
+export { ConfigService } from './service.js';
+export { getConfigPath } from './constants.js';

package/dist/config/service.js

@@ -0,0 +1,47 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getConfigPath } from './constants.js';
+import { isValidApiKey } from '../utils/index.js';
+export class ConfigService {
+    configPath;
+    constructor() {
+        this.configPath = getConfigPath();
+    }
+    async getApiKey() {
+        // 1. Check environment variable
+        if (process.env.XOEGIT_GEMINI_API_KEY) {
+            return process.env.XOEGIT_GEMINI_API_KEY;
+        }
+        // 2. Check config file
+        try {
+            const configStr = await fs.readFile(this.configPath, 'utf-8');
+            const config = JSON.parse(configStr);
+            if (config.XOEGIT_GEMINI_API_KEY && isValidApiKey(config.XOEGIT_GEMINI_API_KEY)) {
+                return config.XOEGIT_GEMINI_API_KEY;
+            }
+        }
+        catch (error) {
+            // Config file doesn't exist or is invalid, ignore
+        }
+        return undefined;
+    }
+    async saveApiKey(apiKey) {
+        try {
+            const dir = path.dirname(this.configPath);
+            await fs.mkdir(dir, { recursive: true });
+            let config = {};
+            try {
+                const existing = await fs.readFile(this.configPath, 'utf-8');
+                config = JSON.parse(existing);
+            }
+            catch (e) {
+                // ignore
+            }
+            config.XOEGIT_GEMINI_API_KEY = apiKey;
+            await fs.writeFile(this.configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+        }
+        catch (error) {
+            throw new Error(`Failed to save configuration: ${error.message}`);
+        }
+    }
+}

package/dist/git/index.js

@@ -0,0 +1 @@
+export * from './service.js';

package/dist/git/service.js

@@ -0,0 +1,40 @@
+import { simpleGit } from 'simple-git';
+const git = simpleGit();
+/**
+ * Checks if the current directory is a git repository
+ */
+export async function isGitRepository() {
+    try {
+        return await git.checkIsRepo();
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Gets the current git status
+ */
+export async function getGitStatus() {
+    const status = await git.status();
+    return JSON.stringify(status, null, 2);
+}
+/**
+ * Gets the diff of staged and unstaged changes
+ */
+export async function getGitDiff() {
+    const diff = await git.diff();
+    const diffCached = await git.diff(['--cached']);
+    return `Unstaged Changes:\n${diff}\n\nStaged Changes:\n${diffCached}`;
+}
+/**
+ * Gets the git log (recent commits)
+ */
+export async function getGitLog(maxCount = 5) {
+    try {
+        const log = await git.log({ maxCount });
+        return JSON.stringify(log.all, null, 2);
+    }
+    catch (error) {
+        return "No commits yet.";
+    }
+}

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { program, analyzeAction } from './cli/index.js';
+program.action(analyzeAction);
+program.parse(process.argv);

package/dist/prompts/index.js

@@ -0,0 +1 @@
+export * from './service.js';

package/dist/prompts/service.js

@@ -0,0 +1,38 @@
+import fs from 'fs/promises';
+import path from 'path';
+import url from 'url';
+/**
+ * Generates the system prompt for the AI
+ */
+export async function generateSystemPrompt() {
+    let rulesContent = '';
+    try {
+        const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+        const rulesPath = path.resolve(__dirname, './templates/RULES.md');
+        rulesContent = await fs.readFile(rulesPath, 'utf-8');
+    }
+    catch (error) {
+        console.warn('Could not read RULES.md, using default rules.');
+        rulesContent = 'Follow conventional commits.';
+    }
+    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.
+
+1.  Analyze the provided "Git Diff", "Git Status", and "Git Log".
+2.  Generate a valid 'git add' command.
+3.  Generate a valid 'git commit' command following Conventional Commits.
+4.  Strictly follow the rules defined below.
+
+---
+RULES FROM USER:
+${rulesContent}
+---
+
+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.
+- If the changes are huge, suggest splitting them if instructed by the Rules, or just one big commit if not specified.
+- The user is using a CLI. Return the response in a way that is easy to read.
+`;
+}

package/dist/prompts/templates/RULES.md

@@ -0,0 +1,126 @@
+# Git Workflow Agent
+
+An agent that helps generate git commit messages, PR titles, and squash messages following team conventions. You execute all commands manually.
+
+## 1. Agent Purpose
+
+The agent will **only suggest/generate**:
+
+- Atomic commits (splitting changes into logical units)
+- PR title in proper format
+- Squash message for PR merge
+
+**Agent will NOT**:
+
+- Suggest single large commits for unrelated changes
+- Auto-commit your changes
+
+## 2. REQUIRED Output Format
+
+You must ALWAYS output in this exact format. Do not use markdown code blocks for the commands themselves, but separate commits clearly.
+
+**CRITICAL:** Split the changes into **AS MANY ATOMIC COMMITS AS NEEDED**. Do not limit yourself to 1 or 2 commits if the changes cover multiple distinct scopes or purposes.
+
+```text
+commit 1
+git add <files for commit 1>
+git commit -m "<type>(<scope>): <subject>"
+
+commit 2
+git add <files for commit 2>
+git commit -m "<type>(<scope>): <subject>"
+
+... (add more commits as needed) ...
+
+commit N
+git add <files for commit N>
+git commit -m "<type>(<scope>): <subject>"
+
+pr title: <type>(<scope>): <summary>
+pr description: <type>(<scope>): <summary>
+- <commit 1 message>
+- <commit 2 message>
+- ... (list all commits)
+```
+
+**Example Output (showing 3 commits, but could be more):**
+
+```text
+commit 1
+git add src/auth/login.ts
+git commit -m "feat(auth): add login validation"
+
+commit 2
+git add src/utils/logger.ts
+git commit -m "refactor(utils): improve error logging"
+
+commit 3
+git add package.json
+git commit -m "chore: update dependencies"
+
+pr title: feat(auth): implement secure login and maintenance
+pr description: feat(auth): implement secure login and maintenance
+- feat(auth): add login validation
+- refactor(utils): improve error logging
+- chore: update dependencies
+```
+
+## 3. How to Use the Agent
+
+### Step 1: Analyze Your Changes
+
+Run these commands to see your changes:
+
+```bash
+git status
+git diff
+```
+
+### Step 2: Agent Response
+
+Agent will analyze the diff and `git status` and automatically split changes into atomic commits.
+
+## 4. Commit Message Convention
+
+### Prefix Types
+
+- **feat:** new feature
+- **fix:** bug fix
+- **chore:** maintenance (dependencies, configs)
+- **refactor:** code restructuring
+- **docs:** documentation only
+- **style:** formatting, whitespace
+- **perf:** performance improvement
+- **test:** add or update tests
+- **build:** build system changes
+- **ci:** CI/CD changes
+- **revert:** revert previous commit
+
+### Format
+
+```
+<type>(<scope>): <description>
+```
+
+### Rules
+
+- All lowercase
+- Description under 72 characters
+- Use imperative mood ("add" not "added")
+- No period at the end
+
+## 5. PR Title & PR Description Convention
+
+- **PR Title**: summaries the entire set of changes.
+- **PR Description**: matches the PR title and includes a detailed list of changes.
+
+## 6. Logic for Splitting Commits
+
+- Group changes by **scope** (e.g., auth, ui, api).
+- separating **refactors** from **features**.
+- separating **tests** from **implementation** (unless TDD implies otherwise, but often usually better to keep atomic).
+- separating **config/chore** changes (package.json, .gitignore) from **code** changes.
+
+## 7. User Instructions
+
+If the user provides specific instructions like "split into 3 commits", follow them. Otherwise, determine the best split logically.

package/dist/providers/gemini.js

@@ -0,0 +1,87 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { getModelList } from './models.js';
+/**
+ * Check if error is a rate limit error (429)
+ */
+function isRateLimitError(error) {
+    const message = error?.message || '';
+    return message.includes('429') || message.includes('Too Many Requests') || message.includes('quota');
+}
+/**
+ * Generate content with a specific model
+ */
+async function tryGenerateWithModel(genAI, modelName, systemPrompt, userMessage) {
+    const model = genAI.getGenerativeModel({ model: modelName });
+    const result = await model.generateContent([
+        { text: systemPrompt },
+        { text: userMessage }
+    ]);
+    const response = await result.response;
+    return response.text();
+}
+/**
+ * Generates a commit suggestion using the Google Generative AI SDK (Gemini)
+ * Automatically falls back to other models when rate limit is hit
+ */
+export async function generateCommitSuggestion(apiKey, systemPrompt, diff, status, log, context = '') {
+    const genAI = new GoogleGenerativeAI(apiKey);
+    // Parse status to find untracked files
+    let untrackedMsg = '';
+    try {
+        const statusObj = JSON.parse(status);
+        if (statusObj.not_added && statusObj.not_added.length > 0) {
+            untrackedMsg = `
+Untracked Files (New Files):
+${statusObj.not_added.join('\n')}
+
+IMPORTANT: The above files are NEW and untracked. You MUST suggest 'git add' for them and include them in commits based on their names/purpose.
+`;
+        }
+    }
+    catch (e) {
+        // metadata parsing failed, just ignore
+    }
+    // Build context section if provided
+    const contextSection = context ? `
+USER CONTEXT (IMPORTANT - This describes the overall purpose of these changes):
+"${context}"
+
+Use this context to determine the appropriate commit type (feat, fix, refactor, chore, etc.) and to write more accurate commit messages.
+` : '';
+    const userMessage = `
+${contextSection}
+Git Status:
+${status}
+
+${untrackedMsg}
+
+Git Log (Last 5 commits):
+${log}
+
+Git Diff:
+${diff}
+
+Please suggest the git add command and the git commit message.
+`;
+    // Get ordered list of models to try
+    const modelsToTry = getModelList();
+    const errors = [];
+    // Try each model in order, fallback on rate limit
+    for (const modelName of modelsToTry) {
+        try {
+            const result = await tryGenerateWithModel(genAI, modelName, systemPrompt, userMessage);
+            return result;
+        }
+        catch (error) {
+            if (isRateLimitError(error)) {
+                errors.push(`${modelName}: rate limited`);
+                // Continue to next model
+                continue;
+            }
+            // Non-rate-limit error, throw immediately
+            throw new Error(`Gemini Provider Error: ${error.message}`);
+        }
+    }
+    // All models exhausted
+    throw new Error(`All models rate limited. Tried: ${errors.join(', ')}. Please try again later.`);
+}

package/dist/providers/index.js

@@ -0,0 +1,2 @@
+export * from './gemini.js';
+export * from './models.js';

package/dist/providers/models.js

@@ -0,0 +1,39 @@
+/**
+ * Available Gemini models for free tier
+ */
+export const GEMINI_MODELS = {
+    'flash-lite': 'gemini-2.5-flash-lite',
+    'flash': 'gemini-2.5-flash',
+    'flash-3': 'gemini-3-flash',
+};
+/**
+ * Default model to use
+ */
+export const DEFAULT_MODEL = 'flash-lite';
+/**
+ * Get model name from key, returns default if invalid
+ */
+export function getModelName(key) {
+    if (key && key in GEMINI_MODELS) {
+        return GEMINI_MODELS[key];
+    }
+    return GEMINI_MODELS[DEFAULT_MODEL];
+}
+/**
+ * Get list of available model keys for CLI help
+ */
+export function getAvailableModels() {
+    return Object.keys(GEMINI_MODELS);
+}
+/**
+ * Get ordered list of model names for fallback (default first)
+ */
+export function getModelList() {
+    const defaultModelName = GEMINI_MODELS[DEFAULT_MODEL];
+    const allModels = Object.values(GEMINI_MODELS);
+    // Put default model first, then the rest
+    return [
+        defaultModelName,
+        ...allModels.filter(m => m !== defaultModelName)
+    ];
+}

package/dist/services/config.service.js

@@ -0,0 +1,124 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import readline from 'readline';
+export class ConfigService {
+    configPath;
+    constructor() {
+        this.configPath = this.getConfigPath();
+    }
+    getConfigPath() {
+        const homeDir = os.homedir();
+        switch (process.platform) {
+            case 'win32':
+                return path.join(process.env.APPDATA || path.join(homeDir, 'AppData', 'Roaming'), 'xoegit', 'config.json');
+            case 'darwin':
+                return path.join(homeDir, 'Library', 'Application Support', 'xoegit', 'config.json');
+            default: // Linux and others
+                return path.join(homeDir, '.config', 'xoegit', 'config.json');
+        }
+    }
+    async getApiKey() {
+        // 1. Check environment variable
+        if (process.env.XOEGIT_GEMINI_API_KEY) {
+            return process.env.XOEGIT_GEMINI_API_KEY;
+        }
+        // 2. Check config file
+        try {
+            const configStr = await fs.readFile(this.configPath, 'utf-8');
+            const config = JSON.parse(configStr);
+            if (config.XOEGIT_GEMINI_API_KEY && this.isValidApiKey(config.XOEGIT_GEMINI_API_KEY)) {
+                return config.XOEGIT_GEMINI_API_KEY;
+            }
+        }
+        catch (error) {
+            // Config file doesn't exist or is invalid, ignore
+        }
+        return undefined;
+    }
+    isValidApiKey(key) {
+        // Basic validation: length > 10, no spaces, allowed chars
+        // Gemini keys are typically AIza... (39 chars)
+        // We allow A-Z, a-z, 0-9, -, _
+        if (!key || key.length < 10)
+            return false;
+        // Check for non-ASCII characters which cause the ByteString error in headers
+        // 9881 is '⚙', checking for ASCII range 33-126
+        const asciiRegex = /^[\x21-\x7E]+$/;
+        return asciiRegex.test(key);
+    }
+    async saveApiKey(apiKey) {
+        try {
+            const dir = path.dirname(this.configPath);
+            await fs.mkdir(dir, { recursive: true });
+            let config = {};
+            try {
+                const existing = await fs.readFile(this.configPath, 'utf-8');
+                config = JSON.parse(existing);
+            }
+            catch (e) {
+                // ignore
+            }
+            config.XOEGIT_GEMINI_API_KEY = apiKey;
+            await fs.writeFile(this.configPath, JSON.stringify(config, null, 2), { mode: 0o600 }); // Secure permissions
+        }
+        catch (error) {
+            throw new Error(`Failed to save configuration: ${error.message}`);
+        }
+    }
+    async promptApiKey() {
+        return new Promise((resolve) => {
+            process.stdout.write('Please enter your Google Gemini API Key: ');
+            // Use raw mode for hidden input if available
+            if (process.stdin.setRawMode && process.stdout.isTTY) {
+                process.stdin.setRawMode(true);
+                process.stdin.resume();
+                let input = '';
+                const onData = (char) => {
+                    const charStr = char.toString('utf-8');
+                    // Enter key
+                    if (charStr === '\r' || charStr === '\n' || charStr === '\r\n') {
+                        process.stdin.setRawMode(false);
+                        process.stdin.removeListener('data', onData);
+                        process.stdin.pause(); // Pause stdin to allow program to exit naturally if needed
+                        process.stdout.write('\n');
+                        const trimmedInput = input.trim();
+                        if (this.isValidApiKey(trimmedInput)) {
+                            resolve(trimmedInput);
+                        }
+                        else {
+                            console.error('Invalid API Key format. Please try again.');
+                            process.exit(1);
+                        }
+                        return;
+                    }
+                    // Ctrl+C
+                    if (charStr === '\u0003') {
+                        process.exit(1);
+                    }
+                    // Backspace
+                    if (charStr === '\u007f' || charStr === '\b') {
+                        if (input.length > 0) {
+                            input = input.slice(0, -1);
+                        }
+                        return;
+                    }
+                    input += charStr;
+                };
+                process.stdin.on('data', onData);
+            }
+            else {
+                // Fallback for non-TTY environments (or if hidden input not supported)
+                const rl = readline.createInterface({
+                    input: process.stdin,
+                    output: process.stdout,
+                    terminal: false // Treat as non-terminal to avoid echoing if possible, though rl.question usually echoes. 
+                });
+                rl.question('', (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                });
+            }
+        });
+    }
+}

package/dist/services/gemini.service.js

@@ -0,0 +1,50 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+/**
+ * generates a commit suggestion using the Google Generative AI SDK (Gemini)
+ */
+export async function generateCommitSuggestion(apiKey, systemPrompt, diff, status, log) {
+    const genAI = new GoogleGenerativeAI(apiKey);
+    // use the user-requested model.
+    const model = genAI.getGenerativeModel({ model: 'gemini-2.5-flash-lite' });
+    // parse status to find untracked files and make them explicit to the AI
+    let untrackedMsg = '';
+    try {
+        const statusObj = JSON.parse(status);
+        if (statusObj.not_added && statusObj.not_added.length > 0) {
+            untrackedMsg = `
+Untracked Files (New Files):
+${statusObj.not_added.join('\n')}
+
+IMPORTANT: The above files are NEW and untracked. You MUST suggest 'git add' for them and include them in commits based on their names/purpose.
+`;
+        }
+    }
+    catch (e) {
+        // metadata parsing failed, just ignore
+    }
+    const userMessage = `
+Git Status:
+${status}
+
+${untrackedMsg}
+
+Git Log (Last 5 commits):
+${log}
+
+Git Diff:
+${diff}
+
+Please suggest the git add command and the git commit message.
+`;
+    try {
+        const result = await model.generateContent([
+            { text: systemPrompt },
+            { text: userMessage }
+        ]);
+        const response = await result.response;
+        return response.text();
+    }
+    catch (error) {
+        throw new Error(`Gemini Provider Error: ${error.message}`);
+    }
+}

package/dist/services/git.service.js

@@ -0,0 +1,45 @@
+import { simpleGit } from 'simple-git';
+const git = simpleGit();
+/**
+ * Checks if the current directory is a git repository
+ */
+export async function isGitRepository() {
+    try {
+        return await git.checkIsRepo();
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Gets the current git status
+ */
+export async function getGitStatus() {
+    const status = await git.status();
+    return JSON.stringify(status, null, 2);
+}
+/**
+ * Gets the diff of staged and unstaged changes
+ */
+export async function getGitDiff() {
+    // Get diff of everything (staged and unstaged)
+    const diff = await git.diff();
+    // Also get staged diff to be thorough, if needed, but 'git diff' usually shows unstaged.
+    // 'git diff --cached' shows staged.
+    // For the AI to know full context, sending both might be useful, or a combined view.
+    // Let's allow the caller to decide or just fetch both.
+    const diffCached = await git.diff(['--cached']);
+    return `Unstaged Changes:\n${diff}\n\nStaged Changes:\n${diffCached}`;
+}
+/**
+ * Gets the git log (recent commits)
+ */
+export async function getGitLog(maxCount = 5) {
+    try {
+        const log = await git.log({ maxCount });
+        return JSON.stringify(log.all, null, 2);
+    }
+    catch (error) {
+        return "No commits yet.";
+    }
+}

package/dist/services/prompt.service.js

@@ -0,0 +1,39 @@
+import fs from 'fs/promises';
+import path from 'path';
+import url from 'url';
+/**
+ * Generates the system prompt for the AI
+ */
+export async function generateSystemPrompt() {
+    let rulesContent = '';
+    try {
+        // Find rules relative to this file (dist/services/prompt.service.js -> dist/rules/RULES.md)
+        const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+        const rulesPath = path.resolve(__dirname, '../rules/RULES.md');
+        rulesContent = await fs.readFile(rulesPath, 'utf-8');
+    }
+    catch (error) {
+        console.warn('Could not read RULES/RULES.md, using default rules.');
+        rulesContent = 'Follow conventional commits.';
+    }
+    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.
+
+1.  Analyze the provided "Git Diff", "Git Status", and "Git Log".
+2.  Generate a valid 'git add' command.
+3.  Generate a valid 'git commit' command following Conventional Commits.
+4.  Strictly follow the rules defined below.
+
+---
+RULES FROM USER:
+${rulesContent}
+---
+
+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.
+- If the changes are huge, suggest splitting them if instructed by the Rules, or just one big commit if not specified.
+- The user is using a CLI. Return the response in a way that is easy to read.
+`;
+}

package/dist/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.js

@@ -0,0 +1 @@
+export * from './config.js';

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from './input.js';
+export * from './ui.js';

package/dist/utils/input.js

@@ -0,0 +1,67 @@
+import readline from 'readline';
+/**
+ * Validates if a string is a valid API key format
+ */
+export function isValidApiKey(key) {
+    if (!key || key.length < 10)
+        return false;
+    const asciiRegex = /^[\x21-\x7E]+$/;
+    return asciiRegex.test(key);
+}
+/**
+ * Prompts user for API key input via stdin with hidden input
+ */
+export async function promptApiKey() {
+    return new Promise((resolve) => {
+        process.stdout.write('Please enter your Google Gemini API Key: ');
+        if (process.stdin.setRawMode && process.stdout.isTTY) {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            let input = '';
+            const onData = (char) => {
+                const charStr = char.toString('utf-8');
+                // Enter key
+                if (charStr === '\r' || charStr === '\n' || charStr === '\r\n') {
+                    process.stdin.setRawMode(false);
+                    process.stdin.removeListener('data', onData);
+                    process.stdin.pause();
+                    process.stdout.write('\n');
+                    const trimmedInput = input.trim();
+                    if (isValidApiKey(trimmedInput)) {
+                        resolve(trimmedInput);
+                    }
+                    else {
+                        console.error('Invalid API Key format. Please try again.');
+                        process.exit(1);
+                    }
+                    return;
+                }
+                // Ctrl+C
+                if (charStr === '\u0003') {
+                    process.exit(1);
+                }
+                // Backspace
+                if (charStr === '\u007f' || charStr === '\b') {
+                    if (input.length > 0) {
+                        input = input.slice(0, -1);
+                    }
+                    return;
+                }
+                input += charStr;
+            };
+            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();
+                resolve(answer.trim());
+            });
+        }
+    });
+}

package/dist/utils/ui.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+/**
+ * CLI UI Components
+ */
+// Brand colors
+const brand = {
+    primary: chalk.hex('#6366F1'), // Indigo
+    secondary: chalk.hex('#8B5CF6'), // Violet
+    accent: chalk.hex('#06B6D4'), // Cyan
+    success: chalk.hex('#10B981'), // Emerald
+    warning: chalk.hex('#F59E0B'), // Amber
+    error: chalk.hex('#EF4444'), // Red
+    muted: chalk.hex('#6B7280'), // Gray
+};
+/**
+ * App banner
+ */
+export function showBanner() {
+    console.log(`\n${brand.primary('⚡')} ${brand.secondary.bold('xoegit')} ${brand.muted('— AI-powered commit generator')}\n`);
+}
+/**
+ * Display the AI suggestion
+ */
+export function showSuggestion(suggestion) {
+    const lines = suggestion.split('\n');
+    console.log(brand.accent.bold('\n📝 Suggestion\n'));
+    for (const line of lines) {
+        console.log(formatSuggestionLine(line));
+    }
+}
+/**
+ * Format individual suggestion lines with subtle highlighting
+ */
+function formatSuggestionLine(line) {
+    if (line.startsWith('git add')) {
+        return chalk.cyan(line);
+    }
+    if (line.startsWith('git commit')) {
+        return chalk.green(line);
+    }
+    if (line.match(/^commit \d+$/i)) {
+        return brand.secondary.bold(line);
+    }
+    if (line.startsWith('pr title:') || line.startsWith('pr description:')) {
+        return chalk.yellow(line);
+    }
+    return line;
+}
+/**
+ * Show success message
+ */
+export function showSuccess(message) {
+    console.log(`${brand.success('✓')} ${message}`);
+}
+/**
+ * Show error message
+ */
+export function showError(title, message) {
+    console.log(`${brand.error('✗')} ${brand.error.bold(title)}: ${message}`);
+}
+/**
+ * Show warning message
+ */
+export function showWarning(message) {
+    console.log(`${brand.warning('⚠')} ${message}`);
+}
+/**
+ * Show info message
+ */
+export function showInfo(message) {
+    console.log(`${brand.accent('ℹ')} ${brand.muted(message)}`);
+}
+/**
+ * Show tip/reminder
+ */
+export function showTip(message) {
+    console.log(`\n${brand.muted('💡 ' + message)}`);
+}
+/**
+ * Spinner text for different stages
+ */
+export const spinnerText = {
+    analyzing: brand.muted('Analyzing repository...'),
+    generating: brand.muted('Generating suggestion...'),
+    generatingWithContext: (ctx) => brand.muted(`Generating with context: "${ctx}"...`),
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "xoegit",
+  "version": "1.0.0",
+  "description": "AI-powered CLI tool for generating semantic git commit messages and PR descriptions",
+  "license": "MIT",
+  "author": "ujangdoubleday",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ujangdoubleday/xoegit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ujangdoubleday/xoegit/issues"
+  },
+  "homepage": "https://github.com/ujangdoubleday/xoegit#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "xoegit": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "git",
+    "commit",
+    "ai",
+    "gemini",
+    "cli",
+    "conventional-commits",
+    "commit-message",
+    "automation",
+    "productivity"
+  ],
+  "scripts": {
+    "build": "tsc && mkdir -p dist/prompts/templates && cp src/prompts/templates/RULES.md dist/prompts/templates/RULES.md",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "ora": "^8.1.0",
+    "simple-git": "^3.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.16"
+  }
+}