gitxplain 0.1.6 → 0.1.9

package/cli/services/usageService.js

@@ -0,0 +1,158 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function getUsageLogPath() {
+  return path.join(os.homedir(), ".gitxplain", "usage.jsonl");
+}
+
+export function getUsageLogFile() {
+  return getUsageLogPath();
+}
+
+function readRecords() {
+  const filePath = getUsageLogPath();
+  if (!existsSync(filePath)) {
+    return [];
+  }
+
+  return readFileSync(filePath, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function parseNumeric(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+export function normalizeUsageMetrics(usage) {
+  if (!usage || typeof usage !== "object") {
+    return {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0
+    };
+  }
+
+  const inputTokens =
+    parseNumeric(usage.prompt_tokens) ||
+    parseNumeric(usage.input_tokens) ||
+    parseNumeric(usage.promptTokenCount);
+  const outputTokens =
+    parseNumeric(usage.completion_tokens) ||
+    parseNumeric(usage.output_tokens) ||
+    parseNumeric(usage.candidatesTokenCount);
+  const totalTokens =
+    parseNumeric(usage.total_tokens) ||
+    parseNumeric(usage.totalTokenCount) ||
+    inputTokens + outputTokens;
+
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens
+  };
+}
+
+function parseEnvPrice(envKey) {
+  const raw = process.env[envKey];
+  if (raw == null || raw === "") {
+    return null;
+  }
+
+  const parsed = Number.parseFloat(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+export function resolvePricing(config) {
+  const providerKey = config.provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+  const modelKey = String(config.model ?? "default").toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+
+  const inputPerMillion =
+    parseEnvPrice(`${providerKey}_${modelKey}_INPUT_COST_PER_MTOK`) ??
+    parseEnvPrice(`${providerKey}_INPUT_COST_PER_MTOK`) ??
+    parseEnvPrice("LLM_INPUT_COST_PER_MTOK");
+  const outputPerMillion =
+    parseEnvPrice(`${providerKey}_${modelKey}_OUTPUT_COST_PER_MTOK`) ??
+    parseEnvPrice(`${providerKey}_OUTPUT_COST_PER_MTOK`) ??
+    parseEnvPrice("LLM_OUTPUT_COST_PER_MTOK");
+
+  if (inputPerMillion == null || outputPerMillion == null) {
+    return null;
+  }
+
+  return {
+    inputPerMillion,
+    outputPerMillion
+  };
+}
+
+export function estimateCostUsd(usage, pricing) {
+  if (!pricing) {
+    return null;
+  }
+
+  const metrics = normalizeUsageMetrics(usage);
+  const costUsd =
+    (metrics.inputTokens / 1_000_000) * pricing.inputPerMillion +
+    (metrics.outputTokens / 1_000_000) * pricing.outputPerMillion;
+
+  return Number.isFinite(costUsd) ? costUsd : null;
+}
+
+export function appendUsageRecord({ provider, model, usage, latencyMs, estimatedCostUsd }) {
+  const metrics = normalizeUsageMetrics(usage);
+  if (metrics.totalTokens === 0 && estimatedCostUsd == null) {
+    return;
+  }
+
+  const filePath = getUsageLogPath();
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  appendFileSync(
+    filePath,
+    `${JSON.stringify({
+      timestamp: new Date().toISOString(),
+      provider,
+      model,
+      usage: metrics,
+      latencyMs: latencyMs ?? null,
+      estimatedCostUsd
+    })}\n`,
+    "utf8"
+  );
+}
+
+export function getUsageStats() {
+  const records = readRecords();
+
+  return records.reduce(
+    (summary, record) => {
+      summary.requestCount += 1;
+      summary.inputTokens += parseNumeric(record.usage?.inputTokens);
+      summary.outputTokens += parseNumeric(record.usage?.outputTokens);
+      summary.totalTokens += parseNumeric(record.usage?.totalTokens);
+      summary.estimatedCostUsd += parseNumeric(record.estimatedCostUsd);
+      return summary;
+    },
+    {
+      requestCount: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0,
+      estimatedCostUsd: 0
+    }
+  );
+}
+
+export function clearUsageLog() {
+  const filePath = getUsageLogPath();
+  const count = readRecords().length;
+
+  if (existsSync(filePath)) {
+    rmSync(filePath, { force: true });
+  }
+
+  return count;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitxplain",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "AI-powered Git commit explainer CLI",
   "type": "module",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "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/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/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