gitxplain 0.1.0 → 0.1.3

package/.env.example

@@ -1,6 +1,11 @@
 LLM_PROVIDER=openai
 LLM_MODEL=
 
+# Gemini API (Recommended)
+GEMINI_API_KEY=
+GEMINI_MODEL=gemini-2.5-flash
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
+
 OPENAI_API_KEY=
 OPENAI_MODEL=gpt-4.1-mini
 OPENAI_BASE_URL=https://api.openai.com/v1
@@ -9,16 +14,6 @@ GROQ_API_KEY=
 GROQ_MODEL=llama-3.3-70b-versatile
 GROQ_BASE_URL=https://api.groq.com/openai/v1
 
-OPENROUTER_API_KEY=
-OPENROUTER_MODEL=openai/gpt-4.1-mini
-OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
-OPENROUTER_SITE_URL=https://github.com
-OPENROUTER_APP_NAME=gitxplain
-
-GEMINI_API_KEY=
-GEMINI_MODEL=gemini-2.5-flash
-GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
-
 OLLAMA_API_KEY=ollama
 OLLAMA_MODEL=llama3.2
 OLLAMA_BASE_URL=http://127.0.0.1:11434/v1

package/IMPLEMENTATION.md

@@ -0,0 +1,225 @@
+# GitXplain Enhancement - Implementation Summary
+
+## Overview
+Successfully implemented two major new features for gitxplain:
+1. **Git Connection** (`--connect-git`) - Connect GitHub account with Personal Access Token
+2. **Interactive Chat Interface** (`--boot`) - Start a chat session with repository context
+
+## New Features
+
+### 1. Git Connection Feature (`--connect-git`)
+
+**Command:**
+```bash
+gitxplain --connect-git
+```
+
+**Functionality:**
+- Prompts user for GitHub Personal Access Token (PAT)
+- Saves connection securely to `~/.gitxplain/git-connection.json`
+- Displays user's git configuration (name and email)
+- Shows success message upon completion
+- Required before using `--boot` feature
+
+**Files Created:**
+- `cli/services/gitConnectionService.js` - Handles connection storage and retrieval
+
+**Key Functions:**
+- `saveGitConnection(token, provider)` - Saves PAT locally
+- `loadGitConnection()` - Retrieves saved connection
+- `isGitConnected()` - Checks if connection exists
+- `getGitUserInfo()` - Gets git user name/email
+
+### 2. Interactive Chat Interface (`--boot`)
+
+**Command:**
+```bash
+gitxplain --boot
+gitxplain --boot --provider groq --model llama-3.3-70b-versatile
+```
+
+**Functionality:**
+- Requires prior git connection (`gitxplain --connect-git`)
+- Initializes repository context (commits, branches, status)
+- Launches interactive readline interface
+- Maintains conversation history with LLM
+- Supports all LLM providers (OpenAI, Groq, OpenRouter, Gemini, Ollama, Chutes)
+
+**Files Created:**
+- `cli/services/chatService.js` - Chat interface implementation
+
+**Key Features:**
+- Repository Context Awareness
+  - Last 20 commits with abbreviated hash and message
+  - All git branches (local and remote)
+  - Current working directory status
+  
+- Chat Commands:
+  - Type normally to ask questions about the code/commits
+  - `clear` - Reset conversation history
+  - `exit` - Close chat session
+
+- Multi-Provider Support:
+  - OpenAI Compatible providers: OpenAI, Groq, OpenRouter, Chutes
+  - Specialized providers: Gemini (with custom formatting)
+  - Local providers: Ollama
+
+**Key Classes:**
+- `ChatService` - Main chat interface class
+  - `constructor(cwd, providerOverride, modelOverride)` - Initialize service
+  - `initializeRepoContext()` - Load repository information
+  - `buildSystemPrompt()` - Create context-aware system prompt
+  - `sendMessage(userMessage)` - Handle user input
+  - `startInteractiveChat()` - Main interactive loop
+
+### 3. Updated CLI (`cli/index.js`)
+
+**New Flags:**
+- `--connect-git` - Initialize GitHub connection
+- `--boot` - Start interactive chat session
+
+**Updated Features:**
+- `parseArgs()` - Now detects `connectGit` and `boot` flags
+- `handleConnectGit()` - Manages connection workflow
+- `handleBoot()` - Manages chat initialization
+- `printHelp()` - Updated documentation
+
+**Error Handling:**
+- Checks for git repository existence
+- Validates connection before allowing `--boot`
+- Graceful error messages for missing PAT or connection
+
+## Updated Files
+
+### `cli/services/aiService.js`
+- Exported `getProviderConfig()` function (moved from private)
+- Exported `validateProviderConfig()` function (moved from private)
+- These are now used by `chatService.js`
+
+### `package.json`
+- Updated lint script to include new service files
+  - `gitConnectionService.js`
+  - `chatService.js`
+
+### `README.md`
+- Added new features documentation
+- Added usage examples for `--connect-git` and `--boot`
+- Added section explaining chat commands
+
+## Connection Storage
+
+**Location:** `~/.gitxplain/git-connection.json`
+
+**Format:**
+```json
+{
+  "token": "github_pat_xxx",
+  "provider": "github",
+  "connectedAt": "2026-04-08T09:45:18.238Z"
+}
+```
+
+**Security Notes:**
+- Token stored locally in user's home directory
+- Not included in version control (added to `.gitignore`)
+- Can be manually deleted to disconnect
+
+## Testing
+
+✅ All features tested and working:
+1. `--connect-git` successfully saves PAT
+2. Connection file created at correct location
+3. `--boot` checks for existing connection
+4. Help text updated with new commands
+5. Syntax validation passes for all files
+
+## Usage Examples
+
+### Connect to GitHub
+```bash
+gitxplain --connect-git
+# Enter your PAT when prompted
+# Output: Git Connected Successfully
+```
+
+### Start Interactive Chat with Default Provider
+```bash
+gitxplain --boot
+# Opens chat interface with repository context
+```
+
+### Start Chat with Specific Provider
+```bash
+gitxplain --boot --provider groq --model llama-3.3-70b-versatile
+```
+
+### Chat Commands
+```
+You: What commits were made recently?
+[Assistant responds about recent commits]
+
+You: Explain the last change
+[Assistant explains based on repo context]
+
+You: clear
+[Conversation history cleared]
+
+You: exit
+[Chat session ends]
+```
+
+## Architecture
+
+```
+CLI (index.js)
+├── parseArgs() → detects --connect-git, --boot
+├── handleConnectGit()
+│   └── gitConnectionService.js
+│       ├── saveGitConnection()
+│       └── getGitUserInfo()
+└── handleBoot()
+    └── chatService.js
+        ├── ChatService class
+        ├── initializeRepoContext()
+        ├── sendMessage()
+        └── startInteractiveChat()
+            └── aiService.js
+                ├── getProviderConfig()
+                └── validateProviderConfig()
+```
+
+## Backward Compatibility
+
+✅ All existing features remain fully functional:
+- Commit analysis (`gitxplain <commit-id>`)
+- All analysis modes (--summary, --issues, --fix, --impact, --full)
+- Provider override (--provider, --model)
+- Output formatting (--json)
+- Help command
+
+## Next Steps (Optional Enhancements)
+
+1. Add token validation against GitHub API
+2. Add token expiration checking
+3. Add support for other git platforms (GitLab, Bitbucket)
+4. Add option to save chat history
+5. Add syntax highlighting in chat output
+6. Add keyboard shortcuts for chat commands
+
+## Files Modified/Created
+
+### Created:
+- `cli/services/gitConnectionService.js` (134 lines)
+- `cli/services/chatService.js` (216 lines)
+
+### Modified:
+- `cli/index.js` - Added new features, updated help, added handlers
+- `cli/services/aiService.js` - Exported previously private functions
+- `package.json` - Updated lint script
+- `README.md` - Updated documentation
+
+### Unchanged but Supporting:
+- `cli/services/gitService.js` - Git integration
+- `cli/services/outputFormatter.js` - Output formatting
+- `cli/services/promptService.js` - Prompt templates
+- Prompts directory - All prompt templates

package/README.md

@@ -15,6 +15,11 @@ Supported providers:
 
 - Explains what a commit does, why it exists, and how the fix works
 - Supports focused output modes like summary, issue, fix, impact, review, security, and line-by-line walkthroughs
+- Supports AI-assisted commit splitting plans, with optional execution for the latest commit
+- Supports release-branch merge previews driven by detected version bumps in diffs
+- Supports automatic release tagging driven by the same version-bump detection used for release merges
+- Supports AI-assisted commit planning for uncommitted working tree changes
+- Supports quick repository log output for full history inspection
 - Supports single commits, commit ranges, and branch-vs-base comparisons
 - Truncates oversized diffs before sending them to the model and reports that truncation
 - Streams output for supported providers
@@ -60,6 +65,24 @@ cp .env.example .env
 
 ```bash
 gitxplain help
+gitxplain commit
+gitxplain --commit
+gitxplain merge
+gitxplain --merge
+gitxplain tag
+gitxplain --tag
+gitxplore tag
+gitxplore --tag
+gitxplain log --log
+gitxplain status
+gitxplain --status
+gitxplain add README.md
+gitxplain remove README.md
+gitxplain del scratch.txt
+gitxplain pop
+gitxplain pop 2
+gitxplain push
+gitxplain push origin main
 gitxplain <commit-id>
 gitxplain <commit-id> --summary
 gitxplain <commit-id> --issues
@@ -69,6 +92,12 @@ gitxplain <commit-id> --full
 gitxplain <commit-id> --lines
 gitxplain <commit-id> --review
 gitxplain <commit-id> --security
+gitxplain <commit-id> --split
+gitxplain --commit --execute
+gitxplain merge
+gitxplain --merge --execute
+gitxplain tag
+gitxplain --tag --execute
 gitxplain <commit-id> --json
 gitxplain <commit-id> --markdown
 gitxplain <commit-id> --html
@@ -76,18 +105,24 @@ gitxplain <commit-id> --stream
 gitxplain <commit-id> --clipboard
 gitxplain <commit-id> --verbose
 gitxplain <commit-id> --quiet
+gitxplain log --log
 gitxplain <start>..<end> --markdown
 gitxplain --branch main --review
 gitxplain --pr origin/main --security
 gitxplain install-hook
 gitxplain <commit-id> --provider openrouter --model anthropic/claude-3.7-sonnet
 gitxplain <commit-id> --provider chutes --model deepseek-ai/DeepSeek-V3-0324
+gitxplain <commit-id> --split --execute
 ```
 
 Examples:
 
 ```bash
 npm start -- HEAD~1 --summary
+npm start -- commit
+npm start -- merge
+npm start -- tag
+npm start -- log --log
 npm start -- a1b2c3d --full
 npm start -- HEAD~1 --lines
 npm start -- HEAD~5..HEAD --markdown
@@ -95,6 +130,7 @@ npm start -- --branch main --review
 npm start -- HEAD~1 --provider groq --model llama-3.3-70b-versatile
 npm start -- HEAD~1 --provider gemini --model gemini-2.5-flash
 npm start -- HEAD~1 --provider chutes --model deepseek-ai/DeepSeek-V3-0324
+npm start -- HEAD --split --execute
 ```
 
 ## Running The CLI
@@ -142,12 +178,46 @@ node /home/guru/Dev/gitxplain/cli/index.js HEAD~1 --full
 - `--lines`: file-by-file, line-by-line walkthrough of the changed code
 - `--review`: code review findings with actionable suggestions
 - `--security`: security-focused analysis of the change
+- `--split`: propose how to split a commit into multiple atomic commits
+- `--merge`: preview or execute a merge into the `release` branch based on detected version bumps
+- `--tag`: preview or create release tags from the same detected version windows
+- `--commit`: propose commits for current uncommitted changes
+- `--log`: print Git log entries for the current repository
+- `--status`: print Git working tree status for the current repository
+- `--execute`: apply a proposed split by rewriting history
+- `--dry-run`: preview the split or commit plan without applying it
 - `--json`: return structured JSON instead of formatted text
 - `--markdown`: return Markdown output
 - `--html`: return HTML output
 
 If no analysis flag is supplied, the CLI asks what kind of explanation you want.
 
+## Repository Log
+
+Print recent log entries from the current repository:
+
+```bash
+gitxplain log
+gitxplain --log
+```
+
+Both forms print the repository history in a compact one-line format using the current repository, without calling the LLM.
+
+## Quick Actions
+
+Run a few common Git actions directly through `gitxplain`:
+
+```bash
+gitxplain status
+gitxplain add README.md
+gitxplain remove README.md
+gitxplain del scratch.txt
+gitxplain pop
+gitxplain pop 2
+gitxplain push
+gitxplain push origin main
+```
+
 ## Comparison Modes
 
 Single commit:
@@ -171,6 +241,90 @@ gitxplain --pr origin/main --security
 
 `--branch` and `--pr` compare the current branch to a base ref using the merge base with `HEAD`.
 
+## Commit Splitting
+
+Preview how a commit could be split:
+
+```bash
+gitxplain HEAD~1 --split
+```
+
+Actually split the current `HEAD` commit into smaller commits:
+
+```bash
+gitxplain HEAD --split --execute
+```
+
+Use a specific provider for the analysis:
+
+```bash
+gitxplain HEAD --split --provider gemini
+```
+
+`--split` asks the model for a plan first. By default this is a dry run and only prints the proposed commit breakdown. Adding `--execute` rewrites Git history by undoing the current `HEAD` commit and recreating it as multiple commits in the suggested order.
+
+Warning: `--split --execute` rewrites history. If the commit was already pushed, you may need to force-push after reviewing the new commit stack. For safety, execution only supports splitting the current `HEAD` commit and requires a clean working tree.
+
+## Release Merge
+
+Preview the release merge plan for the current branch:
+
+```bash
+gitxplain merge
+gitxplain --merge
+```
+
+Actually merge the current branch into the `release` branch:
+
+```bash
+gitxplain --merge --execute
+```
+
+This command scans commits on your current branch after the branch split point and uses version-file diffs as release checkpoints. Each time a commit changes the version, that closes a release window. On the `release` branch, the command creates commits named `release <version>`. If no release versions have been promoted yet, it creates release commits for all detected versions in order. If some release versions already exist on `release`, it skips those and creates only the latest unreleased `release <version>` commit.
+
+## Release Tagging
+
+Preview the release tags for the current branch:
+
+```bash
+gitxplain tag
+gitxplain --tag
+gitxplore tag
+gitxplore --tag
+```
+
+Actually create the tags:
+
+```bash
+gitxplain --tag --execute
+gitxplore --tag --execute
+```
+
+This command uses the same release-window detection as `merge`. It scans commits on your current branch after the branch split point, detects version bumps from version-file diffs, and maps each unreleased version to the last commit in that release window. By default it creates annotated tags named exactly after the detected version, such as `1.2.3`.
+
+## Commit Working Tree
+
+Preview how the current uncommitted changes should be committed:
+
+```bash
+gitxplain commit
+gitxplain --commit
+```
+
+Actually create the suggested commits:
+
+```bash
+gitxplain --commit --execute
+```
+
+Use a specific provider for the analysis:
+
+```bash
+gitxplain --commit --provider gemini
+```
+
+This mode analyzes the current working tree, proposes one or more logical commits with conventional commit messages, and can then create those commits automatically. By default it only previews the plan.
+
 ## Config File
 
 Example `.gitxplainrc`: