gitxplain 0.1.8 → 0.2.0

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "gitxplain",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "AI-powered Git commit explainer CLI",
   "type": "module",
   "bin": {
-    "gitxplain": "./cli/index.js",
-    "gitxplore": "./cli/index.js"
+    "gitxplain": "cli/index.js",
+    "gitxplore": "cli/index.js"
   },
   "scripts": {
     "start": "node ./cli/index.js",
-    "lint": "node --check ./cli/index.js && node --check ./cli/services/chatService.js && node --check ./cli/services/gitConnectionService.js && node --check ./cli/services/envLoader.js && node --check ./cli/services/pipelineService.js",
+    "lint": "node --check ./cli/index.js && node --check ./cli/services/envLoader.js && node --check ./cli/services/pipelineService.js",
     "test": "node --test"
   },
   "keywords": [

package/packaging/README.md

@@ -0,0 +1,60 @@
+# Packaging
+
+This directory contains packaging assets for Homebrew, AUR, and Debian releases.
+
+## Homebrew tap
+
+Template formula: `packaging/homebrew-tap/Formula/gitxplain.rb`
+
+Create and publish the tap repository:
+
+```bash
+gh repo create guruswarupa/homebrew-tap --public --clone
+cd homebrew-tap
+mkdir -p Formula
+cp /path/to/gitxplain/packaging/homebrew-tap/Formula/gitxplain.rb Formula/gitxplain.rb
+git add Formula/gitxplain.rb
+git commit -m "Add gitxplain formula"
+git push -u origin main
+```
+
+After each new npm publish, update the formula `url` and replace `"<SHA256_PLACEHOLDER>"` with the tarball SHA-256, then push the change.
+
+## AUR
+
+Template files:
+
+- `packaging/aur/PKGBUILD`
+- `packaging/aur/.SRCINFO`
+
+Generate `.SRCINFO` after updating `PKGBUILD`:
+
+```bash
+cd /path/to/gitxplain/packaging/aur
+makepkg --printsrcinfo > .SRCINFO
+```
+
+Create and publish the AUR package:
+
+```bash
+git clone ssh://aur@aur.archlinux.org/gitxplain.git aur-gitxplain
+cd aur-gitxplain
+cp /path/to/gitxplain/packaging/aur/PKGBUILD .
+cp /path/to/gitxplain/packaging/aur/.SRCINFO .
+makepkg --printsrcinfo > .SRCINFO
+git add PKGBUILD .SRCINFO
+git commit -m "Initial gitxplain release"
+git push
+```
+
+Replace `"<SHA256_PLACEHOLDER>"` with the npm tarball SHA-256 before publishing.
+
+## Debian
+
+Build the Debian package from this repository:
+
+```bash
+./scripts/build-deb.sh
+```
+
+The package is written to `dist/gitxplain_<version>_all.deb`.

package/packaging/aur/.SRCINFO

@@ -0,0 +1,12 @@
+pkgbase = gitxplain
+	pkgdesc = AI-powered Git commit explainer CLI
+	pkgver = 0.1.9
+	pkgrel = 1
+	url = https://github.com/guruswarupa/gitxplain
+	arch = any
+	license = MIT
+	depends = nodejs
+	source = https://registry.npmjs.org/gitxplain/-/gitxplain-0.1.9.tgz
+	sha256sums = <SHA256_PLACEHOLDER>
+
+pkgname = gitxplain

package/packaging/aur/PKGBUILD

@@ -0,0 +1,22 @@
+pkgname=gitxplain
+pkgver=0.1.9
+pkgrel=1
+pkgdesc="AI-powered Git commit explainer CLI"
+arch=('any')
+url="https://github.com/guruswarupa/gitxplain"
+license=('MIT')
+depends=('nodejs')
+source=("https://registry.npmjs.org/${pkgname}/-/${pkgname}-${pkgver}.tgz")
+sha256sums=('<SHA256_PLACEHOLDER>')
+
+package() {
+  install -d "${pkgdir}/usr/lib/${pkgname}"
+  tar -xzf "${srcdir}/${pkgname}-${pkgver}.tgz" -C "${srcdir}"
+  cp -a "${srcdir}/package/." "${pkgdir}/usr/lib/${pkgname}/"
+
+  chmod 755 "${pkgdir}/usr/lib/${pkgname}/cli/index.js"
+
+  install -d "${pkgdir}/usr/bin"
+  ln -sf "/usr/lib/${pkgname}/cli/index.js" "${pkgdir}/usr/bin/gitxplain"
+  ln -sf "/usr/lib/${pkgname}/cli/index.js" "${pkgdir}/usr/bin/gitxplore"
+}

package/packaging/homebrew-tap/Formula/gitxplain.rb

@@ -0,0 +1,19 @@
+class Gitxplain < Formula
+  desc "AI-powered Git commit explainer CLI"
+  homepage "https://github.com/guruswarupa/gitxplain"
+  url "https://registry.npmjs.org/gitxplain/-/gitxplain-0.1.9.tgz"
+  sha256 "<SHA256_PLACEHOLDER>"
+  license "MIT"
+
+  depends_on "node"
+
+  def install
+    libexec.install Dir["package/*"]
+    bin.install_symlink libexec/"cli/index.js" => "gitxplain"
+    bin.install_symlink libexec/"cli/index.js" => "gitxplore"
+  end
+
+  test do
+    assert_match "gitxplain", shell_output("#{bin}/gitxplain --help")
+  end
+end

package/prompts/blame.txt

@@ -0,0 +1,29 @@
+Analyze this git blame report for a file and explain ownership patterns.
+
+Context:
+- The input below is not a diff. It is a compact blame summary built from `git blame --line-porcelain`.
+- Focus on who changed which parts of the file, when the major edits happened, and what kinds of changes appear to have shaped the file.
+- Call out concentrated ownership, legacy areas, and spots that may need extra care during onboarding or refactoring.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Blame Report:
+{{diff}}
+
+Return:
+
+1. Ownership Summary:
+- Summarize the main authors or time periods that shaped the file
+
+2. Likely Change Themes:
+- Explain what kinds of changes the major contributors appear to have made
+
+3. Onboarding Notes:
+- Suggest where a new maintainer should read carefully, who to ask first, or what parts look risky or stable

package/prompts/changelog.txt

@@ -0,0 +1,36 @@
+Generate release notes in a conventional-changelog style.
+
+Context:
+- This may represent a single commit or a range of commits.
+- Prefer grouping entries under headings like Features, Fixes, Refactors, Docs, Tests, Chores, and Breaking Changes when supported by the evidence.
+- Use commit messages first, then use the diff to sharpen unclear items.
+- Be conservative and do not invent user-facing changes that are not visible in the Git data.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Change Hints:
+{{change_hints}}
+
+Diff:
+{{diff}}
+
+Return:
+
+1. Release Summary:
+- One short paragraph describing the overall release/change set
+
+2. Changelog:
+- Group entries under relevant categories
+- Keep bullets concise and user-facing
+- If there are no clear entries for a category, omit it
+
+3. Upgrade Notes:
+- Mention any migration steps, rollout cautions, or compatibility risks
+- If none are apparent, say so clearly

package/prompts/conflict.txt

@@ -0,0 +1,33 @@
+You are helping resolve unresolved Git merge conflicts.
+
+Context:
+- The input below is a structured report extracted from conflict markers in the working tree.
+- Explain what each side appears to be doing, suggest the most likely safe resolution, and call out any ambiguity that requires human review.
+- Be conservative. Do not pretend a single resolution is certain when the intent is unclear.
+
+Conflict Summary:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Conflict Report:
+{{diff}}
+
+Return:
+
+1. Conflict Summary:
+- Explain the overall source of the conflict
+
+2. Suggested Resolution:
+- For each file or conflict block, describe the most likely resolution
+- Be explicit about which lines to keep, merge, or rewrite
+
+3. Why:
+- Explain why the suggested resolution is the safest or most consistent
+
+4. Follow-Up Checks:
+- Suggest tests, manual verification steps, or edge cases to validate after resolving the conflict

package/prompts/pr-description.txt

@@ -0,0 +1,40 @@
+Write a pull request description for this change set.
+
+Context:
+- This may be a single commit, a commit range, or a branch comparison.
+- The result should be ready to paste into GitHub or GitLab.
+- Be accurate and concise. Do not invent testing or screenshots that are not evidenced by the diff.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Change Hints:
+{{change_hints}}
+
+Diff:
+{{diff}}
+
+Return:
+
+## Summary
+- Short bullets describing the main changes
+
+## Why
+- Why this PR exists
+
+## Testing
+- Mention visible testing evidence from the diff if any
+- If no testing evidence is visible, say "Not specified in diff"
+
+## Risks
+- Briefly describe rollout, compatibility, or review risks
+
+## Screenshots
+- If the diff suggests UI work, include "Screenshots: Needed"
+- Otherwise include "Screenshots: Not needed"

package/prompts/refactor.txt

@@ -0,0 +1,29 @@
+Review this change for refactoring opportunities.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Change Hints:
+{{change_hints}}
+
+Diff:
+{{diff}}
+
+Return:
+
+1. Refactor Opportunities:
+- List concrete refactors suggested by the code shown
+- Focus on duplication, naming, cohesion, dead code, control flow, error handling, and API clarity
+- If there are no worthwhile refactors, say so explicitly
+
+2. Why These Matter:
+- Explain the maintenance or correctness benefits of the top opportunities
+
+3. Safe Next Steps:
+- Suggest a small, practical follow-up plan that avoids mixing refactors with risky behavior changes

package/prompts/stash.txt

@@ -0,0 +1,34 @@
+Explain the contents of this Git stash entry.
+
+Context:
+- This stash may include staged work, unstaged work, or both.
+- Focus on what work is preserved here, why it may have been stashed, and what to watch for before applying it.
+
+Stash Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Change Hints:
+{{change_hints}}
+
+Diff:
+{{diff}}
+
+Return:
+
+1. Summary:
+- Explain what work is stored in the stash
+
+2. Likely Intent:
+- Explain why a developer might have stashed these changes
+
+3. Key Changes:
+- Summarize the important code or file-level changes
+
+4. Reapply Notes:
+- Mention any cautions, missing context, or likely conflicts to watch for when applying the stash

package/prompts/test-suggest.txt

@@ -0,0 +1,29 @@
+Suggest what tests should be added or updated for this change.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Change Hints:
+{{change_hints}}
+
+Diff:
+{{diff}}
+
+Return:
+
+1. Test Coverage Suggestions:
+- List the highest-value tests to add or update
+- Be specific about scenarios, assertions, and edge cases
+- If existing coverage already looks sufficient, say so clearly
+
+2. Risk Gaps:
+- Call out the most important behaviors that could regress without tests
+
+3. Suggested Test Plan:
+- Organize the recommended tests by unit, integration, or end-to-end when appropriate

package/scripts/build-deb.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PACKAGE_JSON="${ROOT_DIR}/package.json"
+VERSION="$(node -p "JSON.parse(require('node:fs').readFileSync(process.argv[1], 'utf8')).version" "${PACKAGE_JSON}")"
+DESCRIPTION="$(node -p "JSON.parse(require('node:fs').readFileSync(process.argv[1], 'utf8')).description" "${PACKAGE_JSON}")"
+PACKAGE_NAME="gitxplain"
+ARCHITECTURE="${DEB_ARCHITECTURE:-all}"
+MAINTAINER="${DEB_MAINTAINER:-Guruswarupa <opensource@local.invalid>}"
+OUTPUT_DIR="${ROOT_DIR}/dist"
+BUILD_ROOT="$(mktemp -d)"
+PACKAGE_ROOT="${BUILD_ROOT}/${PACKAGE_NAME}_${VERSION}"
+INSTALL_ROOT="${PACKAGE_ROOT}/usr/lib/${PACKAGE_NAME}"
+CONTROL_DIR="${PACKAGE_ROOT}/DEBIAN"
+DOC_DIR="${PACKAGE_ROOT}/usr/share/doc/${PACKAGE_NAME}"
+DEB_FILE="${OUTPUT_DIR}/${PACKAGE_NAME}_${VERSION}_${ARCHITECTURE}.deb"
+
+cleanup() {
+  rm -rf "${BUILD_ROOT}"
+}
+
+trap cleanup EXIT
+
+mkdir -p "${OUTPUT_DIR}" "${INSTALL_ROOT}" "${CONTROL_DIR}" "${DOC_DIR}" "${PACKAGE_ROOT}/usr/bin"
+
+cp -a \
+  "${ROOT_DIR}/cli" \
+  "${ROOT_DIR}/prompts" \
+  "${ROOT_DIR}/package.json" \
+  "${ROOT_DIR}/README.md" \
+  "${INSTALL_ROOT}/"
+
+find "${PACKAGE_ROOT}" -type d -exec chmod 755 {} +
+find "${PACKAGE_ROOT}" -type f -exec chmod 644 {} +
+chmod 755 "${INSTALL_ROOT}/cli/index.js"
+ln -s "../lib/${PACKAGE_NAME}/cli/index.js" "${PACKAGE_ROOT}/usr/bin/gitxplain"
+ln -s "../lib/${PACKAGE_NAME}/cli/index.js" "${PACKAGE_ROOT}/usr/bin/gitxplore"
+
+cat > "${CONTROL_DIR}/control" <<EOF
+Package: ${PACKAGE_NAME}
+Version: ${VERSION}
+Section: utils
+Priority: optional
+Architecture: ${ARCHITECTURE}
+Maintainer: ${MAINTAINER}
+Depends: nodejs (>= 18)
+Homepage: https://github.com/guruswarupa/gitxplain
+Description: ${DESCRIPTION}
+ AI-powered Git commit explainer CLI distributed as a Debian package.
+EOF
+
+cat > "${DOC_DIR}/copyright" <<EOF
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: gitxplain
+Source: https://github.com/guruswarupa/gitxplain
+
+Files: *
+License: MIT
+EOF
+
+dpkg-deb --root-owner-group --build "${PACKAGE_ROOT}" "${DEB_FILE}" >/dev/null
+echo "${DEB_FILE}"

package/IMPLEMENTATION.md

@@ -1,225 +0,0 @@
-# GitXplain Enhancement - Implementation Summary
-
-## Overview
-Successfully implemented two major new features for gitxplain:
-1. **GitHub Connection** (`--connect-github`) - Connect GitHub account with Personal Access Token
-2. **Interactive Chat Interface** (`--boot`) - Start a chat session with repository context
-
-## New Features
-
-### 1. GitHub Connection Feature (`--connect-github`)
-
-**Command:**
-```bash
-gitxplain --connect-github
-```
-
-**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-github`)
-- 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-github` - Initialize GitHub connection
-- `--boot` - Start interactive chat session
-
-**Updated Features:**
-- `parseArgs()` - Now detects `connectGitHub` 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-github` 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-github` 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-github
-# 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-github, --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